Usage¶

After you finish the Installation, the Gateway is active and forwards recent data from OneMeter devices in the neighborhood which are in Advertising mode to cloud. Frequent interaction with the Gateway is not required.

gw-product-2

Recommendations:

Place the gateway as close as possible to OneMeter devices and with good Wi-Fi coverage.
Make sure data is forwarded to cloud once per 2 weeks.
Move the gateway to a place where the data can be sent to the server in case of prolonged lack of internet connection.

LED status¶


	Off	The application is turned off.
	Blinks slowly	① Connecting to cloud.
	On	② Connected to cloud.
	Blinks unsteadily	③ Forwarding data.

Green LED (LED_ACT to be precise) is used by the application. How to find it? It is located on bottom right and bottom left on the below pictures of Raspberry Pi Zero W (the left one) and 3B/4B (the right one) respectively.

pi-zero-w-clip pi-4b-clip

Operation¶

Connecting to cloud¶

You have to provide the internet connection during launching the gateway in order to connect to the cloud and start transferring data. If the gateway loses connection later (during its operation), it automatically retries to renew the connection after several seconds.

No internet during launch

If the gateway fails to connect to the cloud for 5 minutes after the startup, it will end up signalizing an error. Then it will be restarted after several seconds.

Connected to cloud¶

You need to provide a stable internet connection in order to forward recent data to the cloud. If established, the application forwards data advertised by OneMeter devices in the neighborhood to the cloud just instantly (up to a few seconds since reception).

In case of internet connection is lost

The Gateway is designed to work even if there is no internet connection for days. The Data backup is preserved in memory and resent to server after the connection is back.

Data forwarding¶

The application is receiving data from OneMeter devices in the neighborhood constantly and forwards it to the cloud. If the internet connection is established, data instantly reaches the server. The transferred data includes OBIS codes from last reading (read: Advertising mode) and metadata including name and ID of the Gateway, signal strength and status of OneMeter devices.

Flow control since v2.2

The gateway can control the outgoing packets to the cloud. Check configuration options.

In order to monitor the gateway operation, go to device view on the cloud and check its state on the list of gateways. Its state may refresh after several seconds. The last data packet received does not concern the mentioned metadata packets.

gw-cloud-rssi

I don't see my gateway on the list

Wait a minute. Refresh the page and wait another minute. Check LED status if you still don't see the gateway on the list. If it is fine, make sure the OneMeter device is active (e.g. try to connect to it and synchronize with mobile app). If you cannot connect to the device, replace the battery. In you still encountered problems, contact us.

Data backup¶

The application preserves the data packets locally (retained) in case the internet connection is lost and forwards to the cloud after the connection is successfully re-established. Theoretically, the gateway can store up to 50 days of data from one device (the number of days is decreasing with the number of OneMeter devices in the neighborhood).

No internet for too much time

If the number of stored packets exceeds the maximum, the application will end up signalizing an error. Then it will be restarted after several seconds. After the restart, 50% of oldest packets will be vanished.

Provide a relatively stable internet connection or reconfigure the gateway in order not to lose packets advertised by OneMeter devices.

Automatic synchronization¶

This option is exclusive for OneMeter Enterprise.

The gateway has the ability to automatically synchronize the time of OneMeter devices in the vicinity. If synchronization is required (e.g. after battery replacement or periodically), the gateway will connect to the device and update its time, which will bring the device back into operation and you will not necessarily need to synchronize the device manually using the mobile application.

The automatic synchronization is disabled by default. Check configuration options.

In order to synchronize readouts stored in memory, you should still use the mobile application.

Software update¶

If you don't feel comfortable with a terminal, download System image and install it anew. After reinstallation, the gateway will obtain a new ID (you will see a new gateway on gateways list) and local data backup will be cleared.

In order to update the software (preserving gateway ID and local data backup), do the followings. For system image (or if you already updated the gateway in the past), you can omit the first step.

Add a package registry to the list of known apt sources in /etc/apt/sources.list.
```
deb [trusted=yes] https://packages.onemeter.com/apt/ /
```
Run the command.

sudo apt-get update && sudo apt-get install onemeter-gateway

Select the right configuration

In case you face a prompt related to configuration files, for servers file always select package maintainer's version whereas for uuid always select currently-installed version. For other files, you have full discretion.

Configuration file `/etc/onemeter-gateway/servers'
==> Modified (by you or by a script) since installation.
==> Package distributor has shipped an updated version.
What would you like to do about it ?  Your options are:
    Y or I  : install the package maintainer's version
    N or O  : keep your currently-installed version
    D     : show the differences between the versions
    Z     : start a shell to examine the situation
The default action is to keep your current version.

If you don't want to add a package registry, update the software by Installation package instruction.

Package manager should be able to upgrade the version to the one you downloaded.

armhf · amd64

In order to use other/selected version, open its details in Release notes.

Reset Wi-Fi¶

Change Wi-Fi passwordReset to configuration mode

If you look for a headless Wi-Fi password change:

Shut down the gateway.
Insert microSD card into the reader connected to your computer.
Go to rootfs/etc/wpa_supplicant folder on the card.
Make a backup of wpa_supplicant.conf on your computer.
Replace the content of wpa_supplicant.conf with the following one. Replace NETWORK_SSID and PASSWORD with your Wi-Fi settings.
```
country=pl
update_config=1
ctrl_interface=/var/run/wpa_supplicant
network={
    scan_ssid=1
    ssid="NETWORK_SSID"
    psk="PASSWORD"
}
```
Unable to overwrite file

In case of problems to save a modified file you have to retry as administrator because the file is write-protected by default.

In the end, eject the microSD card, insert it to the device and run the gateway.

If you want to restore the configured device Wi-Fi configuration state and you have keyboard and monitor, connect them to your device. Then login to the console with the login and password and run the following commands.

sudo python3 /usr/lib/raspiwifi/reset_device/manual_reset.py
sudo reboot

The Gateway will be rebooted in Wi-Fi configuration mode.

Administration¶

The installed application works as a system service named onemeter-gateway.

$ systemctl status onemeter-gateway
🟢 onemeter-gateway.service - OneMeter Gateway
     Loaded: loaded (/etc/systemd/system/onemeter-gateway.service

Commands¶

sudo service onemeter-gateway restart  # restart the service
sudo service onemeter-gateway stop     # disable the service (until system restart)
sudo service onemeter-gateway disable  # disable autostart of the service
sudo service onemeter-gateway enable   # enable autostart of the service
sudo service onemeter-gateway start    # enable the service (now)
sudo dpkg --remove onemeter-gateway    # remove the application
# sudo dpkg --purge onemeter-gateway   # remove the application and its configuration (not recommended)

Journal¶

The log journal contains the information about the device operation (connection state, statistics of packets). You can also read the app version, its configuration and errors encountered.

journalctl -u onemeter-gateway -f --since “2 hours ago”

Example

    App: ------------------------------------------------------------
    App:                     OneMeter Gateway 2.1
    App:                1ca456330e (24 May 2021) armhf
    App: ------------------------------------------------------------
    App: System: Linux onemeter-gateway 5.10.11-v7l+ armv7l GNU/Linux
    App:   Disk: 3.61 GiB of 13.92 GiB used (25.96%)
    App:    Buf: 4,0K        /var/opt/onemeter-gateway/
    App: ------------------------------------------------------------
    ...
    App: Model           : Raspberry Pi Zero W Rev 1.1
    App: ------------------------------------------------------------
    App: 11223344-5566-7788-9900-aabbccddeeff
    App: ------------------------------------------------------------
    App: CONSOLE: CLOUD:INFO PROTOCOL:INFO SCANNER:INFO STATS:INFO UI:INFO
    App: DAILY: CLOUD:OFF PROTOCOL:OFF SCANNER:OFF STATS:OFF UI:OFF
    App: PERIOD: LOG DAYS:7 STATS MINS:60
    App: PROTO: BUFFERED DUPLICATES:NO BUFFERED IN RAM:NO BUFFERED MESSAGES:50000
    App: WATCHDOG: ACKED MINS:20 FIRST CONNECTION MINS:5
    App: ------------------------------------------------------------
    App: [2] Kick systemd every 5 s
Scanner: Opened: onemeter-gateway
    ...
    Stats: [3] Log every 60 min
    Stats: server        ack    meta    conn    lost    read    info    null     dev    period
    Stats: Server       3126    9850       0       0    3126    5322    4528      22      3600
Server: Connection: lost
Server: Connection: not seen
Server: Connection: established
    Stats: server        ack    meta    conn    lost    read    info    null     dev    period
    Stats: Server       3669    9108       1       1    3669    6237    5074      22      3600

Log retention time

If /var/log is mounted in RAM (to Extend SD card lifetime), then the journal is cleared after the system restart.

Configuration¶

In order to accustom the application behavior to your needs, you need to apply changes in /etc/onemeter-gateway/settings file and restart the application. Alternatively, find this file on rootfs partition after connecting SD card to your computer. You need to have admin rights to save changes. The option not specified in config file takes the default value.

Default settings

v2.2v2.1

## -- console ------------------------------------
CONSOLE_CLOUD INFO
CONSOLE_PROTOCOL INFO
CONSOLE_SCANNER INFO
CONSOLE_STATS INFO
CONSOLE_SYNC INFO
CONSOLE_UI OFF

## -- daily --------------------------------------
DAILY_CLOUD OFF
DAILY_PROTOCOL OFF
DAILY_SCANNER OFF
DAILY_STATS OFF
DAILY_SYNC OFF
DAILY_UI OFF

## -- ble ----------------------------------------
BLE_RETRY_DELAY 1000
BLE_RETRIES 2

## -- proto --------------------------------------
# PROTO_BUFFERED_IN_RAM
PROTO_BUFFERED_MESSAGES 50000
# PROTO_BUFFERED_DUPLICATES
PROTO_FLOW_CONTROL_PERIOD_MINS 30
PROTO_FLOW_KEEPALIVE_SECONDS 30
PROTO_MAX_DEVICES 20

## -- sync ---------------------------------------
# SYNC_ENABLED
SYNC_FETCH_DIAG_INFO
# SYNC_PERIODIC_MODE
SYNC_PERIODIC_MINS 1440
SYNC_READOUT_DURATION 4
SYNC_TIME_EXPIRATION 30
SYNC_RETRY_DELAY 2000
SYNC_RETRIES 1

## -- stats --------------------------------------
STATS_PERIOD_MINS 60

## -- watchdog -----------------------------------
# WATCHDOG_ACKED_MINS 20
WATCHDOG_FIRST_CONNECTION_MINS 5

## -- console ------------------------------------
CONSOLE_CLOUD INFO
CONSOLE_PROTOCOL INFO
CONSOLE_SCANNER INFO
CONSOLE_STATS INFO
CONSOLE_UI INFO

## -- daily --------------------------------------
DAILY_CLOUD OFF
DAILY_PROTOCOL OFF
DAILY_SCANNER OFF
DAILY_STATS OFF
DAILY_UI OFF

## -- period -------------------------------------
PERIOD_LOG_DAYS 7
PERIOD_STATS_MINS 60

## -- proto --------------------------------------
#PROTO_BUFFERED_IN_RAM
PROTO_BUFFERED_MESSAGES 50000
#PROTO_BUFFERED_DUPLICATES

## -- watchdog -----------------------------------
WATCHDOG_ACKED_MINS 0
WATCHDOG_FIRST_CONNECTION_MINS 5

Synchronization mode¶

Provide SYNC_ENABLED option and restart the application. Then, the gateway will synchronize the device if you restart it or replace its battery.

Additional options below.

option	default value	details
`SYNC_FETCH_DIAG_INFO`	disabled	enable the feature
`SYNC_READOUT_DURATION`	4	guard range of readout [s]
`SYNC_TIME_EXPIRATION`	30	synchronization time validity [s]
`SYNC_RETRY_DELAY`	2000	retry delay [ms]
`SYNC_RETRIES`	1	retries

Provide SYNC_FETCH_DIAG_INFO option if you want the gateway to collect diagnostic data from the device during synchronization. Attach this information to your email to us in case of problems.

Synchronization will not take place near the readout time (within guard range). If the time is set during synchronization and the time difference comparing to a gate time exceeds the established accuracy (4 s), it is considered as failure. The device time is valid for at least the validity period of the synchronization.

Periodic synchronization

(Optionally) Provide SYNC_PERIODIC_MODE. It will run automatically with a given period. You need to wait the whole period again after you restart the application.

option	default value	details
`SYNC_PERIODIC_MODE`	disabled	enable the feature
`SYNC_PERIODIC_MINS`	1440	synchronization period [min]

Buffering¶

option	default value	details
`PROTO_BUFFERED_MESSAGES`	50000	maximal number of retained packets
`PROTO_BUFFERED_IN_RAM`	disabled	retain packets in RAM (volatile)
`PROTO_BUFFERED_DUPLICATES`	disabled	allow to retain duplicates
`PROTO_FLOW_CONTROL_PERIOD_MINS`	30	flow control period
`PROTO_FLOW_KEEPALIVE_SECONDS`	30	maximal time without passing a packet
`PROTO_MAX_DEVICES`	20	maximal number of tracked OneMeter devices

The flow control period defines the amount of time a packet can be considered served to avoid buffering and forwarding of packets that do not bring a new information. After it expires, the packet can be passed through again. It can be passed conditionally at a specified time (when maximum period without passing a packet passes) to ensure a reasonable delay of updating the state of the gateway in the cloud.

Limited deduplication capabilities

If you don't provide PROTO_BUFFERED_DUPLICATES, duplicate packets are not filtered-out immediately as you might think. They are filtered only during the application startup if the number of retained packets exceed PROTO_BUFFERED_MESSAGES. The 50% of oldest packets are vanished then.

Logs¶

The application provides two log sinks: standard output (CONSOLE_*) and daily file logging with auto-rotation (DAILY_*).

In the first case, logs are managed by log manager of the OS and are visible in journalctl. It's the simplest and default logging mechanism.

Secondly, the app can preserve logs in files in /var/log/onemeter-gateway folder. The maximal number of days can be changed with PERIOD_LOG_DAYS setting (7 by default). This mode is recommended to be used to increase the application performance, because the application threads don't need to wait for common logging resources as they operate on different files.

option	default value	details
`CONSOLE_CLOUD`/`DAILY_CLOUD`	`INFO`/`OFF`	data transmitter
`CONSOLE_PROTOCOL`/`DAILY_PROTOCOL`	`INFO`/`OFF`	packet coder
`CONSOLE_SCANNER`/`DAILY_SCANNER`	`INFO`/`OFF`	BLE scanner
`CONSOLE_STATS`/`DAILY_STATS`	`INFO`/`OFF`	statistics
`CONSOLE_UI`/`DAILY_UI`	`INFO`/`OFF`	user interface

Log levels: OFF, ERROR, WARNING, INFO, DEBUG, TRACE.

Monitoring of modules¶

The application can monitor the state of a few its modules in order to raise the error and restart itself in case of not unsatisfactory quality of operation, for example when the particular operation does not happen in the given period of time.

In order to disable monitoring of a specific module, set the relevant option to 0.

option	default value	details
`WATCHDOG_ACKED_MINS`	0	data packet acknowledgement by the server
`WATCHDOG_FIRST_CONNECTION_MINS`	5	first connection to cloud since application start

Monitoring of application¶

The application is configured so that if it freezes for a longer time than 30 s, it will be restarted. In order to modify this feature:

Set the WatchdogSec value in /etc/systemd/system/onemeter-gateway.service.
Run the following commands.

sudo systemctl daemon-reload
sudo service onemeter-gateway restart

The Hardware watchdog is the other mechanism provided to prevent application from freezing or crash. It restarts the system after the defined CPU usage is exceeded (in case device freezes).

Wi-Fi driver crash on Raspberry Pi Zero W

In some cases, the Raspberry Pi Zero W won't be restarted after its Wi-Fi driver is crashed. In order to prevent it you can add interface = wlan0 line in /etc/watchdog.conf file and restart the system. It is not recommended, because if the lack of internet does happen often, the system will keep rebooting.

Hardware watchdog¶

Skip this section if you use System image which has already set it up.

In order to configure it manually, follow these steps.

Add dtparam=watchdog=on line in /boot/config.txt file.
Restart the system. After that the watchdog should be visible in the system (check dmesg | grep -i watchdog).
Install watchdog service.
```
sudo apt-get install watchdog
```

Configure the watchdog in /etc/watchdog.conf file. The proposed values below.

max-load-1       = 50 # maximal CPU load avg./min
max-load-5       = 35
max-load-15      = 25
watchdog-timeout = 15

Run the watchdog.

sudo systemctl enable watchdog
sudo systemctl start watchdog
systemctl status watchdog

In order to test the watchdog, call the following command.

The following command will freeze your system until the next startup

sudo bash -c ':(){ :|:& };:' # !!! FORK BOMB !!!

Statistics¶

Statistics are logged with 60 min period by default. Example and legend below.

    Stats: server        ack    meta    conn    lost    read    info    null     dev    period
    Stats: Server       3126    9850       0       0    3126    5322    4528      22      3600

Legend

The below values for the given period in seconds mean the number of:

ack - data packets received and acknowledged by the server,
meta - metadata packets sent to server (without acknowledgement),
conn - successful connections to server,
lost - lost connections to server,
read - data packets received from OneMeter devices,
info - metadata packets (information) received from OneMeter devices,
null - metadata packets (keep-alive) received from OneMeter devices,
dev - scanned OneMeter devices.

In order to change the statistics period, put the following line with the expected aggregation period in /etc/onemeter-gateway/settings file. If you set 0, statistics won't be collected. Restart the service afterwards.

STATS_PERIOD_MINS 60

Extend SD card lifetime¶

Skip this section if you use System image which has already set it up.

You can mount some directories in RAM in order to extend the SD card lifetime. Add the following lines to /etc/fstab. Modify them if you need. For example, extend the /var/log and /run memory if the computer has a few GB of RAM.

Technical support¶

Most of the potential errors associated with the operation of the gateway can be resolved by restarting the system. Make sure that:

You have an active internet connection
BLE is enabled

Help¶

Still unable to configure your gateway?

Check our FAQ

Last update: 2023-09-15