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.

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).

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.

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.

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).

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.

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.

1. Add a package registry to the list of known apt sources in /etc/apt/sources.list.

   deb [trusted=yes] https://packages.onemeter.com/apt/ /
   

2. Run the command.

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

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.

Reset Wi-Fi¶

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

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”

    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

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.

## -- 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.

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.

Buffering¶

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.

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.

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.

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:

1. Set the WatchdogSec value in /etc/systemd/system/onemeter-gateway.service.
2. 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).

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.

1. Add dtparam=watchdog=on line in /boot/config.txt file.
2. Restart the system. After that the watchdog should be visible in the system (check dmesg | grep -i watchdog).

3. Install watchdog service.

   sudo apt-get install watchdog
   

4. 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
   

5. Run the watchdog.

   sudo systemctl enable watchdog
   sudo systemctl start watchdog
   systemctl status watchdog
   

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

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

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

Help¶

Still unable to configure your gateway?

Check our FAQ