Skip to content

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.

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.

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

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

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

  1. Shut down the gateway.
  2. Insert microSD card into the reader connected to your computer.
  3. Go to rootfs/etc/wpa_supplicant folder on the card.
  4. Make a backup of wpa_supplicant.conf on your computer.
  5. 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: mqtt.dev     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
## -- 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

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

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:

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

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.

  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.

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

Pomoc

Still unable to configure your gateway?

Check our FAQ


Last update: 2021-09-01