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.
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.
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.
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.
shell 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.
In order to use other/selected version, open its details in Release notes.
Reset Wi-Fi¶
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_supplicantfolder on the card. - Make a backup of
wpa_supplicant.confon your computer. -
Replace the content of
wpa_supplicant.confwith the following one. ReplaceNETWORK_SSIDandPASSWORDwith 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.
shell $ systemctl status onemeter-gateway 🟢 onemeter-gateway.service - OneMeter Gateway Loaded: loaded (/etc/systemd/system/onemeter-gateway.service
Commands¶
```shell 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.
shell 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
```shell
-- 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 ```
```shell
-- 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 | Bluetooth 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
WatchdogSecvalue in/etc/systemd/system/onemeter-gateway.service. - Run the following commands.
shell 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=online in/boot/config.txtfile. - Restart the system. After that the watchdog should be visible in the system (check
dmesg | grep -i watchdog). -
Install watchdog service.
shell sudo apt-get install watchdog -
Configure the watchdog in
/etc/watchdog.conffile. The proposed values below.shell max-load-1 = 50 # maximal CPU load avg./min max-load-5 = 35 max-load-15 = 25 watchdog-timeout = 15 -
Run the watchdog.
shell 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
shell 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
- Bluetooth is enabled