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

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: mqtt.dev     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_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

Buffering¶

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: mqtt.dev     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

Pomoc¶

Still unable to configure your gateway?

Check our FAQ