STG Series WMBus (Wireless MBus) – Modbus TCP/RTU Gateway with 2 x 10/100Base-T(x) Ports, 1 x RS232 and 1 x RS485 Serial Ports and/or BPL (Broadband Power Line Link) User Manual

STG Series WMBus Gateways receive Wireless M-Bus (WMBus) telegrams of meters over the air, decrypt and parse them, and make the meter values available as Modbus registers and as MQTT messages. This manual describes the Gen3 devices (firmware v3.00.00 and later): the STG154 and STG254 (standard models), the STG154 Lite and the STG655 (model with Broadband Power Line link).

One device has six functions. The function is chosen on the Operating Mode page with Device Function:

• WMBus - TCP/IP Transparent Gateway - received telegrams are passed to TCP/IP clients; clients can send telegrams to the air. This is the factory setting.
• WMBus - Modbus TCP Gateway (and MQTT Publisher) - meter values are read as Modbus TCP registers.
• WMBus Decoder/Parser and MQTT Publisher - meter values are published to an MQTT broker.
• WMBus - Serial Transparent Gateway - as the first function, over the serial port.
• WMBus - Modbus RTU Gateway (and MQTT Publisher) - meter values are read as Modbus RTU registers.
• WMBus Repeater - received telegrams are sent to the air again.

The standard models and the STG655 hold 128 meters: 128 Modbus rows and 128 AES keys. The STG154 Lite holds 20 meters.

1.1 What is new in firmware 3.00.00

NOTE:

Upgrading a device from firmware 2.x resets its settings to the factory values. Read chapter 15 "Firmware Update and Upgrading from 2.x" before you upgrade.

STG Series WMBus Gateways are made with and without a Broadband Power Line (BPL) link.

2.1 Features

• 2 x 10/100Base-T(X) Ethernet ports
• 1 x RS232 and 1 x RS485 serial connection, up to 460800 baud
• Embedded web interface
• 868 MHz Wireless M-Bus (WMBus) radio
• Supported CI values (radio module): 53h, 5Bh, 60h, 6Ch, 6Dh, 6Eh, 6Fh, 72h, 74h, 75h, 78h, 7Ah, 7Ch, 7Dh, 80h, 8Ah, 8Bh, 8Ch, 8Dh, 8Eh, 8Fh, C3h, C4h, C5h
• One device with six functions: WMBus to Modbus TCP or Modbus RTU gateway with MQTT publisher, WMBus to TCP/IP or serial transparent gateway, WMBus decoder with MQTT publisher, WMBus repeater
• Up to 10 TCP clients at the same time, for example several Modbus TCP masters
• MQTT publisher with three data formats: raw decrypted telegram, parsed data as objects, parsed data as Modbus frame
• Configurable WMBus reception mode: S mode, T mode, or C and T mode together
• AES-128 decryption and Modbus mapping for up to 128 meters (20 on the STG154 Lite)
• Auto configuration from the telegrams heard on the air
• Configurable radio output power, -1 dBm to 13 dBm, used when the gateway sends telegrams (transparent gateway and repeater functions)
• Received telegrams, parsed meter data and the device status are shown on the web interface
• DHCP server
• White list and black list filters for WMBus telegrams
• Firmware update from the web interface; two firmware images are stored in the device, one of them active
• DC or AC power input depending on the model
• Operating temperature: -25 to 70 C for the AC powered versions, -40 to 85 C for the DC powered versions
• Metal IP 40 housing, DIN rail mounting
• No battery for the clock: after a power cut set the time again, from an NTP server or with Set Device Time

2.2 Extra features of the model with BPL (STG655)

• 2 x 10/100Base-T(X) Ethernet ports and 1 x BPL link
• Three-phase AC input (110 - 240 V, 50 - 60 Hz) or 9 - 36 V DC input, depending on the version
• Up to 30 Mbps PHY rate on the BPL link, up to 10 hops and 1000 nodes
• Up to 432 sub-carriers from 2 to 28 MHz analog bandwidth, LDPC-C FEC with 128-bit AES
• BPL role (master or node) is selected on the web interface

2.3 STG154 Lite differences

• 1 x 10/100 Ethernet port
• 1 x RS485 port, no RS232
• 9 - 36 V DC power input (40 V maximum)
• No console port; the log is available over UDP
• AES-128 decryption and Modbus mapping for up to 20 meters

Each device has a DIN rail kit on its rear panel. Tilt the device, hook the metal spring onto the DIN rail and push the device towards the rail until it clicks into place.

4.1 STG154 and STG254

1. SMA female antenna connector, 50 ohm
2. Console port for the log, 115200 baud - micro USB on earlier hardware, USB Type-C on current hardware. The USB serial chip is made by FTDI; the driver is on the Driver page under Support on redz-sc.com (https://redz-sc.com/en/support/driver). The Tx and Rx LEDs of the console blink during transmission
3. WMBus LEDs - ALIVE blinks during normal operation; Tx and Rx blink when telegrams are sent and received
4. Device LEDs - STATUS: in the device functions with a TCP server it blinks while no client is connected and stays on while a client is connected; in the serial device functions it stays on. Tx and Rx blink when data is sent and received. SERVER: on in the two device functions with a TCP server (WMBus - TCP/IP Transparent Gateway and WMBus - Modbus TCP Gateway (and MQTT Publisher)), off in the others
5. Ethernet activity LEDs for port 1, port 2 and the device itself
6. 5 pin terminal block - RS232: Tx, Rx and GND; RS485: A, B and GND. The serial port is selected and set on the web interface
7. 2 x 10/100Base-T(X) Ethernet ports

4.2 STG655

1. SMA female antenna connector, 50 ohm
2. Console port for the log, 115200 baud - micro USB on earlier hardware, USB Type-C on current hardware. The USB serial chip is made by FTDI; the driver is on the Driver page under Support on redz-sc.com (https://redz-sc.com/en/support/driver). The Tx and Rx LEDs of the console blink during transmission
3. WMBus LEDs - ALIVE blinks during normal operation; Tx and Rx blink when telegrams are sent and received
4. Device LEDs - STATUS: in the device functions with a TCP server it blinks while no client is connected and stays on while a client is connected; in the serial device functions it stays on. Tx and Rx blink when data is sent and received. SERVER: on in the two device functions with a TCP server (WMBus - TCP/IP Transparent Gateway and WMBus - Modbus TCP Gateway (and MQTT Publisher)), off in the others
5. Ethernet activity LEDs for port 1, port 2 and the device itself
6. 5 pin terminal block for the serial line - RS232: Tx, Rx and GND; RS485: A, B and GND
7. BPL LEDs - ACTIVITY blinks during BPL traffic; LINK is on when a BPL link is established; MASTER is on when the device is set as BPL master
8. 2 x 10/100Base-T(X) Ethernet ports

4.3 STG154 Lite

• SMA female antenna connector, 50 ohm
• WMBus LEDs - ALIVE blinks during normal operation; Tx and Rx blink when telegrams are sent and received
• Device LEDs - STATUS: in the device functions with a TCP server it blinks while no client is connected and stays on while a client is connected; in the serial device functions it stays on. Tx and Rx blink when data is sent and received. SERVER: on in the two device functions with a TCP server (WMBus - TCP/IP Transparent Gateway and WMBus - Modbus TCP Gateway (and MQTT Publisher)), off in the others
• Ethernet activity LED
• Terminal block for RS485: A and B
• 1 x 10/100Base-T(X) Ethernet port

5.1 STG154

1. DC power input, 5 - 48 V DC (60 V maximum), protected against reverse polarity
2. Power LED, on while the device is powered
3. Reset buttons, marked RESET TO SERVER and RESET TO CLIENT. With firmware 3.00.00 both do the same: held for more than 5 seconds, either one restores the factory settings and restarts the device

5.2 STG254

1. AC power input, 100 - 240 V AC, 50 Hz to 60 Hz (120 - 370 V DC)
2. Power LED, on while the device is powered
3. Reset buttons, marked RESET TO SERVER and RESET TO CLIENT. With firmware 3.00.00 both do the same: held for more than 5 seconds, either one restores the factory settings and restarts the device

5.3 STG655

1. Power and BPL terminal block
2. Power LED, on while the device is powered
3. Reset buttons, marked RESET TO SERVER and RESET TO CLIENT. With firmware 3.00.00 both do the same: held for more than 5 seconds, either one restores the factory settings and restarts the device

The STG655 is powered over terminal pins 1 and 2 only. On the AC version the terminals are marked L3, L2, L1 and N: power is connected to L1 and N (pins 1 and 2), the other two terminals (L2 and L3, pins 3 and 4) are data terminals. The STG655 is made in an AC powered version (110 - 240 V, 50 - 60 Hz) and in a DC powered version (9 - 36 V DC). The BPL data connection depends on the version:

The AC powered version is made with the PP or the PN data connection, the DC powered version with the PP data connection.

5.4 STG154 Lite

• DC power input, 9 - 36 V DC (40 V maximum), protected against reverse polarity
• Reset button, marked RESET TO SERVER: held for more than 5 seconds, it restores the factory settings and restarts the device

The Ethernet ports are standard 10/100Base-T(X) ports with RJ-45 connectors.

6.1 Cable type and specifications

6.2 Pin assignments

With a 100BASE-TX / 10BASE-T cable, pins 1 and 2 transmit data and pins 3 and 6 receive data.

The table compares a link over CAT5 cable with the BPL link of the STG655.

WARNING:

Connect an STG655 to a network over one path only: over the power line or over an Ethernet cable. If it reaches the same network over both, the network has a loop; packets are lost and firmware uploads are cut.

The standard models and the STG655 have one RS232 and one RS485 port on the terminal block; the STG154 Lite has RS485 only. The port in use, the baud rate and the line control are set on the Serial Settings page.

8.1 RS232

8.2 RS485

NOTE:

The STG154 Lite has a 2 wire RS485 connection (A and B).

9.1 Overview

The Device Function on the page Operating Mode selects one of six ways of working. The scenarios below describe the data flow of each function. Functions that read meters handle up to 128 meters (STG154 Lite: 20).

NOTE:

The serial functions and the repeater start working without an Ethernet connection. After power-up without a DHCP server these functions start up to one minute later. The functions that work over TCP or MQTT need the network and do not deliver data without it.

9.2 Scenario 1 - WMBus to Modbus TCP (and MQTT)

The gateway receives the frames of the meters listed in Device Query Settings, decrypts and decodes them and keeps the latest values of every meter as Modbus registers. It works as a Modbus TCP server: Modbus TCP clients (SCADA, PLC, data logger) connect to the Server Listening Port (factory value 502) and read a meter under the Modbus Address of its row. Up to Maximum Number of Clients clients can be connected at the same time (1 to 10, factory value 2; saving this function on the page Operating Mode raises a setting of 1 to 2).

If Enable MQTT Publisher for Parsed WMBus Packages is switched on on the page Network Settings, the same meters are published to the MQTT broker in parallel. Saving this function does not change the MQTT setting.

• Frames are not sent to the air in this function.
• A client above the configured number is refused.
• With MQTT switched off the gateway expects a Modbus TCP client: after 30 minutes without any client it reopens its listening port, after a further 30 minutes it restarts.

WARNING:

Switch MQTT on only when a broker can be reached. While MQTT is switched on and the broker cannot be reached, the gateway restarts about every 13 minutes to recover the connection; Modbus TCP connections are dropped by each restart.

9.3 Scenario 2 - WMBus to Modbus RTU (and MQTT)

The gateway receives, decrypts and decodes the frames of the listed meters as in scenario 1, but works as a Modbus RTU slave on its serial port. One Modbus RTU master is connected to the RS485 or RS232 port selected on the page Serial Settings and reads each meter under the Modbus Address of its row. Baud rate and line control of both sides must match.

MQTT publishing runs in parallel if it is switched on on the page Network Settings; this needs the Ethernet connection. Saving this function does not change the MQTT setting.

• Frames are not sent to the air in this function.
• Modbus RTU works without an Ethernet connection.

WARNING:

Switch MQTT on only when a broker can be reached. While the broker cannot be reached the gateway restarts about every 13 minutes to recover the connection.

9.4 Scenario 3 - WMBus to MQTT

The gateway receives, decrypts and decodes the frames of the listed meters and publishes them to an MQTT broker. Saving this function switches the MQTT publisher on; broker, topics, Data Format and Minimum Send Interval for a Parsed Data (in seconds) are set on the page Network Settings. The table Device Query Settings lists the meters without Modbus addresses.

• There is no Modbus access and no serial data in this function.
• Frames are not sent to the air in this function.

WARNING:

This function needs a broker that can be reached. While MQTT is switched on and the broker cannot be reached, the gateway restarts about every 13 minutes to recover the connection.

9.5 Scenario 4 - WMBus to TCP/IP, transparent

The gateway is a TCP server on the Server Listening Port (factory value 502). Up to Maximum Number of Clients clients (1 to 10, factory value 2) can be connected. Every WMBus frame that is received and passes the white list / black list is sent to all connected clients, starting with the length field of the frame. The content is not changed, with one exception: frames of meters whose AES key is entered are decrypted first (see 9.8 "Decryption in the transparent functions and in the repeater"). The number of meters is not limited; nothing is decoded and no meter list is needed.

In the other direction a client can send WMBus frames to the air. The gateway transmits them with the Tx Package Transmission Mode and Tx Power Level of the page WMBus Settings.

• A frame sent by a client must be a complete WMBus frame that starts with its length field (L); the gateway takes exactly L + 1 bytes as one frame.
• The bytes of a frame must follow each other without a pause: an incomplete frame is discarded when no further byte arrives for 1 second.
• The same frame sent again within 2 seconds is not transmitted a second time.
• The white list / black list is applied to frames from the client as well.
• A client that has not yet taken the previous frame does not get the next one.
• MQTT and Modbus are not available in this function.

WARNING:

The gateway expects a TCP client in this function. After 5 minutes without any client it reopens its listening port, after a further 5 minutes it restarts. Keep one client connected.

9.6 Scenario 5 - WMBus to serial, transparent

The same as scenario 4, with the serial port in place of the TCP connection. Every WMBus frame that is received and passes the white list / black list is written to the RS485 or RS232 port selected on the page Serial Settings, starting with the length field of the frame. A WMBus frame received on the serial port is sent to the air under the same rules as in scenario 4.

• One serial device is served. The number of meters is not limited.
• A frame that is received while the previous one is still being written to the serial port is not passed on. Choose a baud rate that is high enough for the number of frames.
• The function works without an Ethernet connection.
• MQTT and Modbus are not available in this function.

9.7 Scenario 6 - WMBus repeater

The gateway sends received WMBus frames to the air again, so that a receiver outside the range of the meters can still read them. The frames are transmitted with the Tx Package Transmission Mode and Tx Power Level of the page WMBus Settings. No meter list is needed and the number of meters is not limited; only the white list / black list decides which meters are repeated.

• The repeater works without an Ethernet connection; the network is needed for the web interface only.
• MQTT and Modbus are not available in this function.

9.8 Decryption in the transparent functions and in the repeater

The AES-128 Decryption List of the page WMBus Settings is used in every function, with or without Add to Config. A frame of a meter whose AES key is in this list (up to 128 meters, STG154 Lite 20) is decrypted before it is passed on; frames of all other meters are passed on as they were received.

The gateway is configured from its embedded web interface. The pages are described below in the order of the menu.

10.1 Connecting to the Web Interface

The gateway is configured with a web browser over its Ethernet port. Every page of the interface is protected by a user name and a password.

10.1.1 Factory network state

A factory device asks for its address by DHCP: Use Static Address for Device and DHCP Server Enabled are both off. The address fields are stored nevertheless and serve as the fall-back address:

If no DHCP server answers, the device keeps the fall-back address 192.168.1.1 / 255.255.255.0. It waits up to one minute for a DHCP answer before it starts its data services with that address.

NOTE:

A device that started with the fall-back address and receives a DHCP address later restarts once and continues with the new address.

Type the address of the device into the address line of the browser (http, port 80).

10.1.2 Find the address with the abcZ Network Tool

The abcZ Network Tool lists the REDZ devices of a network with their address, MAC address, product and firmware version, so the gateway can be found without knowing its address.

1. Connect the PC to the same network as the gateway. Start the abcZ Network Tool and open the Discovery tab.
2. Type the network in IP range, for example 192.168.0.0/24 for the addresses 192.168.0.1 to 192.168.0.254. Leave User and Password at the factory values (admin / admin) unless the password of the gateway was changed.
3. Click Scan (HTTP). Each gateway that answers appears as a row, with its address in IP and its MAC, Product and Version.
4. Find your gateway by its MAC address and double-click the row: the web interface of the gateway opens in the browser. The same MAC address is shown in the header of every page of the web interface.

A gateway with another password is listed with "auth required (password?)" - type its password and scan again. Discover (UDP) is a faster alternative inside the same subnet. The tool is described in full in chapter 16 "Software - abcZ Network Tool".

10.1.3 Login

The browser asks for a user name and a password before the first page is shown.

WARNING:

Change the password after the first login: page Management, card Change Password.

10.1.4 Page header and menu

The header of every page shows the product name, the firmware version, the build date of the firmware and the MAC address of the device.

The menu on the left has eight entries. Seven are always present; Serial Settings appears only when the selected Device Function uses the serial port.

10.1.5 Saving and the answer of the device

The Save Configuration button of a page is disabled until a value on that page has been changed. After a click a waiting window is shown while the device stores the settings, then a message window with an OK button reports the result.

WARNING:

If the reason reads "Rejected: flash verify failed - NOT saved; restart restores factory settings" or "Rejected: config flash invalid - restart the device (factory settings)", the device could not verify the stored settings. It keeps working with the running settings; after the next restart it starts with factory settings and must be configured again.

10.1.6 Reset button

Holding the reset button of the device for more than 5 seconds restores the factory settings and restarts the device. This works at any time while the device is running. After the restart the device is in the factory network state described above and the password is the factory password.

10.2 Operating Mode

The page Operating Mode names the device, selects what the gateway does with the received WMBus frames and, in the modes that read meters, lists the meters.

10.2.1 The six device functions

The data flow of each function is described in chapter 9 "Usage Scenarios and Connection Diagrams".

10.2.2 Settings that change together with the device function

Saving the page Operating Mode also sets a few settings of other pages to match the selected function. This happens with every save of this page, also when the function itself was not changed.

10.2.3 Device Query Settings

The card Device Query Settings is shown for the functions WMBus - Modbus TCP Gateway (and MQTT Publisher), WMBus Decoder/Parser and MQTT Publisher and WMBus - Modbus RTU Gateway (and MQTT Publisher). Each row assigns one meter to the gateway: only the frames of meters that have an enabled row are decoded into Modbus registers and published to MQTT. The table has 128 rows (STG154 Lite: 20 rows). The rows are shown in two columns side by side, each with its row number.

The page checks the entries before it sends them:

NOTE:

The table and the AES-128 Decryption List of the page WMBus Settings are kept in step: enabling a row here checks Add to Config of the meter with the same number there, disabling it clears the box. In the other direction, a meter that is saved with Add to Config on the page WMBus Settings gets a row in this table. Meters can therefore be taken over from the list of detected meters instead of being typed in.

10.2.4 Saving the page

1. Change the name, the function or the table. Save Configuration becomes active.
2. Click Save Configuration. The window "Saving Operating Mode..." is shown while the device stores the settings.
3. The window "Operating Mode Saved." follows, together with the note that a reboot is required. If the window reads "Operating Mode Change Failed!", nothing was stored; the reason of the device stands in brackets.
4. Check the pages Network Settings, WMBus Settings and, if shown, Serial Settings for the new function and save them where needed.
5. Restart the device: page Management, button Reboot Device. The new function, the new name and the new table are in effect after the restart.

NOTE:

Until the restart the device keeps working in the previous function, while the pages already show the saved selection.

10.3 Network Settings

The Network Settings page holds three cards: NTP Settings, MQTT Settings and Device Network Settings. One Save Configuration button at the bottom of the page saves all three cards together. The button becomes active as soon as a field differs from the stored value.

10.3.1 Saving and restart

A save on this page stores the settings but does not restart the device. The confirmation window reads "Network Settings Changed. REBOOT REQUIRED: this setting is applied only at boot - the device keeps running with the previous value until you reboot it." Restart the device with Reboot Device in the Restore / Reboot card of the Management page. The address mode, the addresses, the DHCP server, the listening port, the number of clients, the NTP server and the MQTT connection are all set up once, at start.

Four MQTT settings are used at once, without a restart: the Enable MQTT Publisher for Parsed WMBus Packages box when it is un-ticked, Publish Topic, Minimum Send Interval for a Parsed Data (in seconds) and Data Format. Restart the device after every save on this page so that all settings apply together.

NOTE:

A value the device does not accept (empty text, a number outside the range) is not stored: the field keeps its previous value. Open the page again after the restart and check the values.

WARNING:

If you change the address mode or the address, the web interface answers on the new address after the restart. Note the new address before you restart.

10.3.2 NTP Settings

How the clock is kept:

• After every start the device asks the time server. As soon as it has an answer and the device is in normal operation, the device clock is compared with the NTP time. The comparison is then repeated once an hour.
• If the device clock differs from the NTP time by 5 seconds or more, it is set to the NTP time. A smaller difference is left alone. The correction does not restart the device.
• If the time server does not answer, nothing is changed: a time that was set by hand on the Management page stays as it is.
• The device clock runs in UTC: the NTP time is UTC, and Set Device Time on the Management page also writes UTC. There is no time zone setting.

NOTE:

The time stamps in MQTT messages come directly from the NTP time. They are sent only while the device has a current time from the time server (the last answer is not older than 11 minutes); otherwise the messages are sent without time stamps - see chapter 13 "Sending WMBus Data to an MQTT Server".

10.3.3 MQTT Settings

The card is shown only when Device Function on the Operating Mode page is one of the three functions that decode meter data:

The fields below the check box are shown only while the check box is ticked (or, in the function WMBus Decoder/Parser and MQTT Publisher, always).

The use of these fields, the message layouts and the behaviour of the connection are described in chapter 13 "Sending WMBus Data to an MQTT Server".

10.3.4 Device Network Settings

Each address is entered in four boxes, each a number from 0 to 255.

10.3.5 Address modes

The two check boxes select one of three modes:

WARNING:

To run the DHCP server leave Use Static Address for Device unticked. With both boxes ticked the device works with the static address only and the DHCP server is not started.

DHCP client: until a DHCP server has answered, the device keeps the address stored in Server IP Address (192.168.1.1 from the factory). This is the address under which a new device is reached when it is connected directly to a computer. While the DHCP server does not answer, the device waits and does not restart. When it later receives an address that differs from the one it was working with, it writes the change to the log (IP changed: old -> new) and restarts once to work on the new address; TCP clients have to connect again.

NOTE:

Static address and host names: with a static address the device resolves host names (NTP server, MQTT broker) through Primary DNS Address and Secondary DNS Address. Enter the DNS server of your network there, or enter the time server and the broker as IP addresses.

10.3.6 DHCP server

With DHCP Server Enabled the device serves the network it is connected to:

• Addresses are handed out upwards from DHCP Server Range Start Address. The start address must lie in the network given by Server IP Address and Server Net Mask and must be higher than Server IP Address (for example device 192.168.1.1, start 192.168.1.100).
• Up to 15 clients are served. A lease lasts 20 minutes and is renewed by the client.
• The clients receive Server Net Mask as their mask and Server Gateway Address as their gateway. With 0.0.0.0 in this field no gateway is handed out. The device itself does not forward traffic: enter the address of a router of this network, or 0.0.0.0 for an isolated network, for example a computer connected directly to the device. From the factory the field holds 192.168.1.1, the factory address of the device.
• The clients receive Primary DNS Address as their DNS server. With 0.0.0.0 in this field no DNS server is handed out. The device does not answer DNS queries itself. Secondary DNS Address is not sent.
• From the factory Primary DNS Address holds 192.168.1.1, the factory address of the device, which does not answer DNS: enter the DNS server of your network or 0.0.0.0.

WARNING:

Run only one DHCP server on a network. Do not enable the DHCP server when the device is connected to a network that already has one, for example behind a router.

10.3.7 Server Listening Port and Maximum Number of Clients

Both fields are shown when Device Function is WMBus - TCP/IP Transparent Gateway or WMBus - Modbus TCP Gateway (and MQTT Publisher). Clients connect to the address of the device and the Server Listening Port.

Maximum Number of Clients limits how many clients are served at the same time; the highest value is 10. When every place is taken, a further client waits at most a quarter of a second: if a place becomes free in that time the client takes it, otherwise the connection is refused at once and the refusal is written to the log (the first three refusals, then every hundredth). Saving the Operating Mode page with the Modbus TCP gateway function raises a value of 1 to 2.

10.3.8 BPL Operating Mode

The field exists only on the STG655. MASTER makes the built-in power line modem the master of its power line network, NODE makes it a node of that network. The device switches the modem to the selected role at every start and checks that the modem has taken it. The Ethernet side of the device and all other settings of this page are the same in both roles.

10.4 Serial Settings

The menu entry Serial Settings opens the page Modbus Serial Settings. The entry is shown only when the Device Function is WMBus - Serial Transparent Gateway or WMBus - Modbus RTU Gateway (and MQTT Publisher); in the other functions the serial port is switched off. The same settings are used by both functions.

1. Select the port, the baud rate and the line control. They must match the device connected to the serial port.
2. Click Save Configuration. The window "Saving Serial Settings..." is followed by "Serial Settings Changed." and the note that a reboot is required. "Cannot change Serial Settings." means that nothing was stored; the reason of the device stands in brackets.
3. Restart the device: page Management, button Reboot Device.

10.5 Device Status

The Device Status page shows the health of the gateway at a glance: a summary strip, the address and the application state, the communication counters and, depending on the operating mode, the connections and the Modbus communication state of every meter. Nothing on this page changes the configuration.

10.5.1 Refreshing the page

The status data is read once when the web interface is opened, again every time the Device Status menu entry is clicked, and when Refresh Status is pressed. The page does not refresh by itself. Only the data is reloaded, not the page. The line "Last update: <time>" under the page title gives the time of the last successful read (clock of the computer).

Refresh Status is disabled while the request is running. If the gateway does not answer within 15 seconds the message "Status request timed out." is shown and the button is enabled again. "Cannot refresh the status page." means that the gateway answered with an error, and "The Device is not ready, please retry later." means that another request of the web interface is still running.

10.5.2 Summary strip

The strip at the top of the page condenses the chain radio - decryption - clients - MQTT into a few boxes. Each box has a coloured dot (green = good, amber = attention, red = problem, grey = nothing to report yet), a headline and a detail line. Under the detail line most boxes add one or two small lines that name what the box is about: which meter, which client, which broker. A small line in amber is a warning. Ages are written as "just now", "N min ago" or "N h ago".

NOTE:

The operating modes with a meter list are WMBus - Modbus TCP Gateway (and MQTT Publisher), WMBus Decoder/Parser and MQTT Publisher and WMBus - Modbus RTU Gateway (and MQTT Publisher).

10.5.3 IP Address and App Status

When one of the protections of the gateway has stopped restarting the device for a repeating cause ("parked"), a text in brackets is added after the application state. While the text is shown the gateway does not restart for this cause, so the web interface stays reachable for diagnosis. The text of the radio module and of the serial line disappears by itself when the cause is gone. A gateway parked for the network still restarts by itself when it can no longer reach its default gateway, when no client has been connected for 10 minutes (function WMBus - TCP/IP Transparent Gateway) or 60 minutes (function WMBus - Modbus TCP Gateway (and MQTT Publisher) with MQTT switched off), or when its network processing has stopped.

10.5.4 Communication Counters

All counters count from the last start of the gateway or from the last Reset Logs, whichever is later. Which counters are shown depends on the operating mode; the tables below say so for every row.

10.5.5 Connections

The Connections table is shown in the modes WMBus - TCP/IP Transparent Gateway, WMBus - Modbus TCP Gateway (and MQTT Publisher) and WMBus - Modbus RTU Gateway (and MQTT Publisher). The columns depend on the operating mode:

Last Query Time is the time of the gateway clock at the last request (Modbus RTU: at the last response sent); "-" means that no request was received yet or that the clock is not set. Last Request and Last Response show the bytes of the last Modbus request and of the response that was sent, in hexadecimal. A frame longer than 12 bytes is cut to one line; the link with the byte count ("N B - show") opens the full frame and closes it again.

10.5.6 Modbus Communication Status

Shown in the two Modbus gateway modes. The table has one line for every row of the meter list of the Operating Mode page and tells whether the host reads the meter and whether the meter delivers data.

Disabled rows are hidden until Show disabled rows is checked. The search box ("Search address, ID, meter") filters the lines by Modbus address, device ID, manufacturer or device type. The counter next to it reads, for example, "12 enabled - 10 with data, 116 disabled hidden".

10.5.7 Buttons

NOTE:

Reset Logs does not clear N. of Module Incorrect Chars Received and N. of Gateway Side Incorrect Chars Received. These two start from zero at a restart (the gateway side counter also when a park of the serial line ends). The button does not delete log lines and does not touch the tables of the page.

10.5.8 Status data for support

For a support case, open http://<address of the gateway>/assets/ajax/dev_status_json.htm in the browser; it asks for the login of the web interface. Support asks for the text that is shown.

10.6 WMBus Settings

The WMBus Settings page holds the radio settings of the gateway and the list of meters with their AES keys. It has three cards: Radio Settings, AES Decryption and AES-128 Decryption List. Changes are stored with the Save Configuration button at the bottom of the page; the button is enabled as soon as something on the page differs from the stored values.

10.6.1 Radio Settings

The three repeater fields give the repeater an address of its own. When the repeater has repeated an installation telegram of a meter (C field 46h), it sends an SND-NKE telegram 2 to 5 seconds later. That telegram carries the repeater address from these fields (device type 32h, unidirectional repeater) and the address of the meter. While manufacturer ID and device ID are both 0 no SND-NKE telegram is sent; the repeater then only repeats. If only one of the two is 0, the telegram is sent.

NOTE:

Restart the gateway after changing Radio Settings: the reception mode is loaded into the radio module when the gateway starts. The page offers the restart after the save (see 10.6.9 "Saving the WMBus settings" below).

10.6.2 Supported encryption

The gateway reads unencrypted telegrams and decrypts telegrams encrypted with AES-128 in security mode 5 (AES-128 CBC), mode 7 (AES-128 CBC with dynamic key) and mode 128 (ELL AES-128 counter mode). The WMBus Status page names the encryption mode of the last telegram. A telegram in a mode the gateway cannot decrypt is reported as Mode not supported and its data is not available.

Some meters send further, unencrypted records after the encrypted part of a mode 5 telegram. The gateway recognises such a meter by itself and delivers the complete telegram. There is no setting for this.

NOTE:

If the key of such a meter was already in the gateway before the meter was heard for the first time, its telegrams are delivered without the trailing unencrypted records until the next restart; from then on they are complete.

10.6.3 AES Decryption - the detection list

While it runs, the gateway keeps a detection list of the meters it has heard on the air. The list has room for 256 meters. It is kept in memory only and starts again at every restart with the meters that have Add to Config checked and, while the black list is active, the device IDs of the black list. Every other meter is entered the first time one of its telegrams is received. Telegrams that the white or black list drops, telegrams with device ID 0 and telegrams sent by another reader towards a meter are not entered. When all 256 places are used, new meters are no longer entered until the next restart.

When the page is opened it compares the detection list with the table and, if there are meters that are not in the table yet, shows a line next to the button, for example "3 new devices detected - press Refresh Auto Config List to add". Nothing is added by itself.

Refresh Auto Config List reads the detection list and brings it into the AES-128 Decryption List:

• A meter that is already a row of the table (same manufacturer ID, device ID, version and device type) only gets its Last RSSI refreshed.
• A meter that is not in the table is written into the first free row: its four identity fields are filled in, the key is set to all zeros, Add to Config is checked and the row is marked "Recently Detected" in the Status column.
• A line next to the button tells the result, for example "2 new devices added".
• If the table has no free row left, a pop-up says how many meters could not be listed: "... detected device(s) could not be listed: the AES-128 Decryption List has no free row. Free a row or add unwanted devices to the Black List, then press Refresh again." Those meters are offered again at the next refresh.

NOTE:

Refresh Auto Config List only fills the table on the screen. Nothing is stored in the gateway until Save Configuration is pressed.

For every row that the refresh added, decide what the meter is:

• Add to Config - the meter is to be read. With the save the gateway also enters the meter in the Device Query Settings table of the Operating Mode page and enables that row. Type the AES key of the meter if it is encrypted.
• Add to Black List - the meter is not wanted. With the save its device ID is written to the Black List Device ID Table of the Security Settings page, the black list is switched on if it was off, and the row is cleared so that it is free for another meter.

The two check boxes exclude each other: checking one unchecks the other.

10.6.4 AES-128 Decryption List

• All four identity fields are read as hex, with or without the prefix 0x. Type the values as the meter label or the WMBus Status page shows them: 12345678 and 0x12345678 both give 0x12345678 in Device ID, 2C2D and 0x2C2D both give 0x2C2D in Manufacturer ID. The page rewrites the entry with 0x and leading zeros when the field is left.
• An entry without 0x that has more digits than the field holds is refused with a pop-up and the previous value comes back: more than 8 digits in Device ID, more than 4 in Manufacturer ID, more than 2 in Version and Device Type.

Enter all four identity fields exactly as the meter sends them: manufacturer ID, device ID, version and device type. Let Refresh Auto Config List fill them whenever possible; when you type a row by hand, take the values from the WMBus Status page.

The line above the table reminds of one rule: "Add to Config adds the meter to the Modbus / MQTT query list. The AES key of a row is always used for decryption, checked or not."

10.6.5 Tools above the table

The filters only show and hide rows. The order of the rows does not change.

10.6.6 Status words

10.6.7 Key format

• A key is 16 bytes, written as 32 hex digits, for example 000102030405060708090A0B0C0D0E0F.
• The prefix 0x is optional. Dashes and colons between the digits are allowed. The page shows the key as 16 byte pairs separated by dashes.
• If fewer than 32 digits are typed, the key is filled with leading zeros to 32 digits. Type all 32 digits.
• Anything else is refused with the message "AES-128 Bit Decryption Key should be a 16 Byte value (0xAABBCCDDEEFF1122AABBCCDDEEFF1122)" and the field returns to its previous value.
• A new row starts with a key of all zeros. Leave it for meters that are not encrypted. For an encrypted meter enter the real key: with the zero key such a meter shows Key might be wrong after the restart. A meter that really uses the all-zero key is decrypted with it and is marked Default key.

10.6.8 Key tools

Below the table the page offers four tools for entering many keys. None of them sends anything to the gateway; the keys they write into the table are stored with Save Configuration, like a typed key.

10.6.9 Saving the WMBus settings

Save Configuration sends the radio settings and the changed rows of the table to the gateway ("Saving WMBus Settings..."). With the save the gateway also updates its other lists:

• For every row with Add to Config: if the meter is already a row of Device Query Settings, that row is enabled. Otherwise the meter is written into the first free row of Device Query Settings and enabled; it gets the Modbus address that this row already had. A row is not used if its Modbus address is in use by another enabled row.
• For every row with Add to Config whose device ID is in the saved black list: the ID is removed from the black list.
• For every row with Add to Black List: the device ID is added to the Black List Device ID Table, the black list is switched on if it was off, the row of the meter in Device Query Settings is cleared and the row in this table returns to its unused state.
• For every row without Add to Config: an enabled row of the same meter in Device Query Settings is disabled.

After a successful save the page asks, in a pop-up with the buttons Confirm and Cancel:

"WMBus Settings Changed. Meter rows added to the query list are active now; new AES keys are loaded into the radio module after a reboot - until then those meters may show "No key" (meters the gateway decrypts itself are read at once). Reboot the device now?"

Confirm restarts the gateway. Cancel leaves it running: meters added to the meter list are read from now on, but new or changed keys and a changed reception mode are loaded into the radio module with the next restart. Restart the gateway before you judge the result of a key entry.

More sentences can appear in the pop-up after "WMBus Settings Changed.":

• "... device(s) NOT added to the Black List: the White List is active (Security Settings)." - a meter cannot be moved to the black list while the white list is enabled.
• "... device(s) NOT added to the Black List: the Black List is full (Security Settings)." - all 64 entries of the Black List Device ID Table are in use; see 10.8.5 "Black list entries made from the WMBus Settings page" below.
• "... device(s) NOT added to the Operating Mode query list: no free row without a Modbus address conflict." - free a row in Device Query Settings or resolve the address conflict there, then save again.

Other messages of the save:

• If the white list is enabled and a row has Add to Black List checked, nothing is sent and the page says: "The White List is active: devices cannot be added to the Black List. Uncheck "Add to Black List" or disable the White List on the Security Settings page first."
• If a key rule is switched on but incomplete, nothing is sent and the page says, for rule 1: "Key rule 1: type a manufacturer (3 letters or 4 hex digits) and a key of 32 hex digits, or switch the rule off."
• If only the key rules were changed, no restart is offered: "WMBus Settings Changed. The key rules are stored in the gateway and apply to rows added from now on - no reboot needed."
• If the save fails the page says "Cannot change WMBus Settings." followed by the reason given by the gateway.

10.6.10 Repeater

When the gateway runs as WMBus Repeater and a row of the table holds a key that is not all zeros, the line above the table shows the mark Repeater mode and this warning:

WARNING:

"A meter whose AES key is in this list is repeated DECRYPTED and the receiving gateway cannot read it. Remove the meter keys on a repeater."

On a repeater keep all keys at zero. The keys belong in the gateway that reads the meters.

10.6.11 Limits

On STG154 Lite the page works with 20 rows: Add Row and Show all rows stop at row 20, and Refresh Auto Config List places new meters in rows 1 to 20 only. When these 20 rows are in use, the refresh reports the remaining meters in the pop-up described above.

10.7 WMBus Status

The WMBus Status page shows the last WMBus frame the gateway handled - radio data, link layer header, payload and decoded records - and, in the Meters card, every meter of the meter list with its signal and decryption state. It is the page to use on site to check that a meter is heard and decrypted.

The data is read when the web interface is opened, every time the WMBus Status menu entry is clicked and when Refresh WMBus Status is pressed; the Meters card is filled on a menu click or a button press. Only the data is reloaded, not the page. "Last update: <time>" under the page title gives the time of the last read. The button is disabled during the request; after 15 seconds without an answer "Status request timed out." is shown and the button is enabled again.

10.7.1 Latest Message - Module protocol fields

The three "Latest Message" cards describe one frame: the last radio frame that passed the white list / black list. A frame rejected by the address filter does not appear here. It is still listed in the Meters card; in the operating modes with a meter list it is marked Filtered there. In the transparent gateway modes the cards show the last frame the gateway transmitted for the host when that is the newest one; such a frame has no radio data: Decryption Status and Packet Info read "UNKNOWN", Encryption Mode "UNKNOWN: 99", Packet RSSI in dBm 0 and Message Date-Time 01-01-70 00:00:00. Until the first frame the fields are empty; Message Time then shows 01-01-70 00:00:00.

10.7.2 Latest Message - WMBUS Link Layer fields

NOTE:

Manufacturer ID, Device ID, Version ID and Type read "N.A." when the frame is too short to carry the link layer header.

10.7.3 Latest Message - Payload

NOTE:

The records shown here are the ones the gateway serves over Modbus and MQTT; their order and coding are described in chapter 11 "Modbus Register Map and Data Types".

10.7.4 Meters

The Meters card joins two sources: the meter list of the Operating Mode page with the last frame of every meter, and the last 16 frames the gateway keeps in memory (they are lost at a restart). These are the received radio frames and, in the two transparent gateway modes and in the repeater, also the frames the gateway sends to the air. In the operating modes with a meter list the table has one line for every enabled row of the list and one line for every other device heard in the last 16 frames; in the default order these other devices come first. In the other operating modes the table lists only the devices of the last 16 frames; frames the gateway sent are listed on a line of their own, apart from received frames of the same device ID.

A meter of the list that was not heard since the start shows "no frame yet" across the line. Lines of meters without a frame or with a stale frame are greyed; lines with a green background are meters that have a frame among the last 16.

10.7.5 Tools of the Meters table

• Click a column heading to sort by that column; a second click reverses the order.
• The search box ("Search ID, manufacturer, type") filters the lines.
• "Needs attention only" (modes with a meter list) keeps the lines with a problem: no frame yet, last frame older than 60 minutes, meter status not OK, or not decrypted.
• "Auto refresh (3 s)" reads the last 16 frames again every 3 seconds while the page is shown. Signal, decryption state and time of a line follow the newer frame; for a meter of the list Access No and Meter Status are updated by the next Refresh WMBus Status.
• The counter on the right reads, for example, "12 meters - 10 with data - 2 need attention - avg RSSI -71 dBm"; in the modes without a meter list it reads "N devices in the last 16 frames".
• Click a line to open the bytes of its newest frame among the last 16: the length in decimal and hexadecimal (for example "L 78 (0x4E)"), the C and CI fields, the frame in hexadecimal and a "Copy" button. When the gateway no longer keeps a frame of that meter the line says so. A second click closes it.

10.7.6 Installer view

In the operating modes with a meter list the button Installer view replaces the table by a short list made for a phone; Table view switches back. On a narrow screen the page starts in this view. The list contains the enabled meters of the meter list: the meters that were not heard come first, then the heard meters from the weakest signal to the strongest.

• Every entry shows the device ID and the Modbus address - for a meter that was heard also the manufacturer and the device type - and on the right the signal strength with the age of the last frame ("time unknown" for a frame received before the clock was set) or Not heard.
• No key, Mode not supported or Key might be wrong is shown next to the device ID when the meter is heard but not decrypted.
• The three buttons above the list filter it: "All (n)", "Not heard (n)" and "Weak signal (n)"; a weak signal is -85 dBm or lower.

10.7.7 Checking that a meter is heard and decrypted

1. Enter the meter in the meter list of the Operating Mode page (and its key in the AES list of the WMBus Settings page if it is encrypted) and save.
2. Open WMBus Status. On a phone the Meters card opens in the installer view; on a computer use the table.
3. Wait for the meter to transmit and press Refresh WMBus Status, or check "Auto refresh (3 s)" in the table view. A meter that was not heard shows Not heard ("no frame yet" in the table).
4. When the meter is heard, read the signal strength. -85 dBm or lower is weak (the installer view lists the meter under "Weak signal"; the bar is red below -85 dBm): improve the antenna position or the distance before leaving the site.
5. Read the decryption state. Decrypted or Not encrypted is the goal. No key - enter the key of the meter. Key might be wrong - check the key. Mode not supported - a key does not help; the encryption mode of this meter cannot be decrypted.
6. For a decrypted meter the decoded records are shown under OMS Parsing in the "Latest Message" cards while its frame is the last one received; press Refresh WMBus Status right after the meter has transmitted. Clicking the line of the meter shows the raw bytes of its frame.
7. In the operating modes with a meter list, a meter marked Not in list is heard but is not an enabled row of the meter list; a meter marked Filtered is rejected by the white list or black list of the Security Settings page.

NOTE:

The gateway keeps only the last 16 frames for the green lines and the frame bytes, and it loses them at a restart; in the transparent gateway modes and in the repeater the frames it sends take places among them. On a site with many meters a frame of one meter is pushed out quickly; the signal, decryption state and time of a meter of the meter list stay in its line all the same.

10.8 Security Settings

The Security Settings page filters the received telegrams by the address of the meter. A white list lets only the listed meters pass; a black list drops the listed meters and lets every other meter pass. Without a list every telegram is accepted.

10.8.1 Address Filtering

Only one list can be active. Checking one box unchecks the other. The tables of the list that is not active stay stored in the gateway and are shown again when that list is enabled.

10.8.2 The four tables

The table sizes are the same on all models.

• Values are hex. The page rewrites a typed value as 0x followed by 4 digits (manufacturer) or 8 digits (device ID) when the field is left.
• A value can be typed as it is printed on the meter, with or without the prefix 0x: 12345678 and 0x12345678 both give 0x12345678, 2C2D and 0x2C2D both give 0x2C2D. An entry without 0x that has more digits than the field holds (more than 8 for a device ID, more than 4 for a manufacturer ID) is refused and the previous value comes back.
• An entry of 0 is an empty entry and matches no meter. To remove an entry, set it to 0.
• In a device ID an asterisk stands for any digit. The page shows this hint above the device ID tables: "Use * for any digit: 0x2900**12 matches every device ID that differs only in the starred digits." A pattern needs exactly 8 characters (hex digits and asterisks, at least one hex digit).
• The manufacturer ID is the 2 byte hex code, not the three letters. The WMBus Status page and the AES-128 Decryption List show the hex code of every meter heard.

10.8.3 How a telegram is checked

• White list: a telegram passes if its device ID matches an entry of the White List Device ID Table or its manufacturer matches an entry of the White List Manufacturer ID Table. One of the two is enough, so a listed manufacturer lets all meters of that manufacturer pass. Every other telegram is dropped, also a telegram whose address cannot be read.
• Black list: a telegram is dropped if its device ID matches an entry of the Black List Device ID Table or its manufacturer matches an entry of the Black List Manufacturer ID Table. Every other telegram passes.

The filter works on the received telegram after decryption and before everything else. A dropped telegram is not entered in the detection list of the WMBus Settings page, is not converted to Modbus registers or MQTT messages, is not passed to the TCP/IP or serial client of the transparent functions and is not repeated by a repeater. In the transparent functions the same check is applied to the telegrams a client hands to the gateway for transmission.

A dropped telegram stays visible for diagnosis while it is among the last 16 telegrams the gateway keeps: the Meters table of the WMBus Status page marks its row Filtered.

10.8.4 Saving the security settings

Save Security Settings stores the two check boxes and the four tables ("Saving Security Settings..."). The filter works with the new lists as soon as the save is confirmed; a restart is not needed. The page confirms with:

"Security Settings Changed. The white / black lists are in effect now - no reboot needed."

If the save fails the page says "Cannot Change Security Settings." followed by the reason given by the gateway.

10.8.5 Black list entries made from the WMBus Settings page

• A row saved with Add to Black List on the WMBus Settings page puts the device ID of that meter into the first empty entry of the Black List Device ID Table and switches Black List Enabled on if it was off. Entries that were already stored in the black list tables are kept and take effect together with the new one.
• If all 64 entries of the Black List Device ID Table are in use, the meter is not black-listed. Its row stays in the table and is stored without the Add to Black List mark, and the pop-up after the save says how many meters were not added. The other rows of the save are handled as usual. Free an entry on the Security Settings page, then check the box again and save.
• This is refused while White List Enabled is checked.
• A meter on the active black list is no longer offered by Refresh Auto Config List.
• To read such a meter again, set its entry in the Black List Device ID Table to 0 and press Save Security Settings; the meter is then offered again by Refresh Auto Config List. Saving a row of that meter with Add to Config on the WMBus Settings page also removes its ID from the black list. Pattern entries are never removed this way.

10.9 Management

The Management page holds the service functions of the gateway: device clock, firmware update, configuration file, commissioning report, password, log and restart. Each function has its own card.

10.9.1 Set Device Time

The time is applied at once and the gateway does not restart. The page answers Device time has been set.

If the time cannot be set the page shows Set Device Time Failed! followed by the reason given by the gateway, for example "Rejected: reboot in progress - time NOT set" when the gateway is just closing down for a restart. The UTC date of the computer must lie in the years 2000 to 2099.

NOTE:

The gateway has no time zone setting; its clock is kept in UTC. The button takes the clock of your computer at the moment you press it and sends it as UTC, so the time zone of the computer makes no difference to the result - but the clock and the time zone of the computer must be set correctly. The value that is written is the UTC value shown in the field above the button.

Relation to NTP: while the gateway receives the time from the NTP server set in NTP Server IP or URL it compares its clock with that time once an hour and corrects the clock when it is 5 seconds or more off. The NTP time is UTC, the same time that the button writes. Without an answer from the NTP server the gateway does not touch a time that was set by hand.

The device clock is the time printed at the start of every log line and used for the time of the last frame of a meter in the commissioning report. The report and its CSV file mark these times as UTC.

10.9.2 Live Firmware Update

The gateway holds two firmware images: the one that is running and an alternative one. An upload is always written to the alternative place; the running firmware is not touched by the upload. The new firmware starts only when you switch to it with Reboot Alternative Firmware.

Use the image file that belongs to your model and do not rename it:

NOTE:

A Lite device accepts only the Lite image, and the Lite image is accepted only by a Lite device: the gateway refuses the wrong image and the running firmware stays unchanged. For the standard models and the STG655, choose the image by your model in the table above and check the file name before you upload.

NOTE:

When the gateway starts to write an uploaded file it first removes the alternative firmware that was stored before. After an upload that was cut or refused there is no firmware to switch to until a good image has been uploaded.

WARNING:

An upgrade from firmware 2.x to 3.00.00 resets ALL settings to factory values, including the network settings: the gateway then asks for its address by DHCP and no longer answers on a static address that was set before. Record every setting before the upgrade and find the gateway afterwards by its MAC address with the abcZ Network Tool.

WARNING:

A direct upgrade from firmware 1.x to 3.x is not supported. The only supported upgrade path is from firmware 2.x.

1. Record the present settings: press Download Current Configuration and keep the file.
2. Press Select Firmware File and choose the image file of your model. Its name appears in Firmware file to upload.
3. Press Upload Firmware. A window with the title Upload firmware file and the line Uploading... opens; the bar counts the sent part in percent. When the whole file has been sent the bar shows Checking... while the gateway verifies what it has written. Do not switch the gateway off and do not close the page.
4. Wait for the result "Firmware Uploaded" in the bar and press Close. Alternative Firmware Date and Alternative Firmware Version now show the uploaded firmware and Reboot Alternative Firmware is enabled.
5. Press Reboot Alternative Firmware. The page asks Reboot into the ALTERNATIVE firmware? The device will switch firmware banks. - press Confirm. The window shows Reboot Alternative Firmware Command has been sent. and Rebooting...; the page reloads by itself when the gateway answers again.
6. Check the version and the build date in the header of the page.

A complete update took 28 to 41 seconds in our measurements.

If the upload is cut (cable pulled, browser closed, power of the computer lost) the running firmware is not affected and the gateway keeps working. The alternative firmware is marked as not valid before the first byte is written and stays so after every failure, so a half-written image can never be started: Reboot Alternative Firmware stays disabled, and a switch that is requested nevertheless is refused (Alternate Firmware Boot Failed! with the reason). Simply upload the file again.

Settings after the switch: the settings are carried over to the new firmware only when both versions have the same first two numbers (for example 3.00.00 to 3.00.01). When the first or the second number differs the settings are not carried over; after an upgrade from 2.x the gateway starts with factory settings.

Going back: after the switch the previous firmware is the alternative one. As long as Alternative Firmware Version shows it and the button is enabled, Reboot Alternative Firmware starts it again. The same rule for the settings applies in this direction. A 2.x firmware does not accept a configuration file made by 3.00.00, so plan to enter the settings again when you go back to 2.x.

NOTE:

The files of the web interface carry the firmware version in their address, so the browser loads the new pages by itself after an update. Refreshing the browser cache with Ctrl+F5 is not needed.

10.9.3 Download / Upload Configuration

The file is plain JSON text. It starts with an identity header named "_meta": product name, variant (FULL for the standard models, LITE for the Lite model, FULL,UNE for the model with BPL), firmware version, build date, a check number of the settings format and device name. The settings follow in groups: password, log, device and network settings, security lists, MQTT, NTP and WMBus settings with the meter rows.

WARNING:

The file contains secrets in readable form: the password of the web interface, the MQTT user name and password and the AES keys of all meters. Store and send it like a password list.

On upload the gateway checks the header before it takes anything over:

Only a reply that starts with "Configuration Uploaded" means that the file was taken over; every other reply is shown as an error and the settings of the gateway stay as they were.

WARNING:

An accepted file replaces all settings it contains, including the network settings and the password of the web interface, and the gateway restarts at once. If the file carries another IP address the gateway answers on that address after the restart.

Files of firmware 2.x: a configuration file saved with 2.x can be loaded into 3.00.00 as a legacy file (measured with a file of 2.09.03). The meter list and the key list of the file replace the lists of the gateway: a 2.x file has 64 rows, so the rows 65 to 128 are set to their factory values. The opposite direction does not work: firmware 2.x refuses a file made by 3.00.00.

10.9.4 Commissioning Report

The Commissioning Report card collects on one page what an installer hands over to the operator or to the SCADA team: the settings of the gateway, which meter answers at which Modbus address, signal and decryption state of every meter and the Modbus registers of every meter. The report is drawn inside the card; no new window is opened. AES keys are never printed - the report only says whether a key is set.

The CSV button, the two check boxes and the meter tables exist only in the device functions that have a meter list: WMBus - Modbus TCP Gateway (and MQTT Publisher), WMBus Decoder/Parser and MQTT Publisher and WMBus - Modbus RTU Gateway (and MQTT Publisher). In the other device functions the report consists of the gateway block and the line This device function has no meter list. In WMBus Decoder/Parser and MQTT Publisher the report has the meter table but no register tables.

The report has these parts:

NOTE:

The report shows the settings that are stored in the gateway. A change that you typed into a form but did not save is not in the report. The registers of a meter are known only after the gateway has received a frame of that meter.

The CSV file is separated by semicolons and has one line per enabled meter with the columns modbus_address, device_id, manufacturer, type, aes_key, decryption, rssi_dbm, last_frame_utc, records and tail_register. It contains all enabled meters, whatever the check boxes say.

If the card shows The device did not answer - try again. the gateway was busy; press the button again.

10.9.5 Change Password

The user name of the web interface is always admin and cannot be changed; only the password can.

After a successful change the page shows Password Changed, Next time you login, please use new password. The gateway does not restart. The new password is valid at once: the browser asks for it again and the old password is no longer accepted.

If the change is refused the page shows Error! Cannot change password. with the reason: "Rejected: current password is incorrect - password NOT changed", "Rejected: new password is empty - password NOT changed" or "Rejected: new password and confirmation do not match - password NOT changed".

NOTE:

A forgotten password is set back to admin by a factory restore; without the password use the reset button of the device (hold it for more than 5 seconds), which does the same as Restore Factory Configuration. The password is also part of the configuration file: uploading a configuration file sets the password stored in that file.

10.9.6 LOG

The gateway can report what it does as text lines, either on its console port or to a UDP server on the network. Logging is switched off at the factory.

The new log settings take effect with the restart that follows the save: the page shows Change Log Level and Reboot Command has been sent. and Rebooting... and reloads by itself.

The page checks the entries: a wrong address is answered with You have entered an invalid IP address! and a wrong port with UDP Port should be a number between 1 and 65535; the field then returns to its previous value.

Console output: 115200 baud, 8 data bits, no parity, 1 stop bit. Any terminal program can show the lines.

UDP output: every log line is one UDP packet to UDP Server IP : UDP Server Port. Run a UDP listener on that computer and allow the port in its firewall. Lines are sent only while the network is up. With the address 0.0.0.0 nothing is sent.

NOTE:

The Lite model has no console port for the log. Use UDP SERVER on a Lite device.

Every line starts with the device time and the kind of the line: ERR-, INF- or DBG-. A line longer than the line buffer is cut and ends with the character ~.

WARNING:

DEBUG produces many lines. The log output delivers about 17 lines per second; when more lines are produced the surplus is dropped and the gateway reports it with the line "LOG ring overflow - line(s) dropped (oldest kept): <n>". Only log lines are lost - meter data, Modbus and MQTT are not affected. Use DEBUG for a short diagnosis only and do not conclude from a missing line that something did not happen.

10.9.7 Restore / Reboot

WARNING:

The factory restore erases ALL settings: operating mode, meter list and AES keys, Modbus rows, filter lists, MQTT, log settings, the network settings and the password (back to admin). After the restart the gateway asks for its address by DHCP; a static address that was set before is gone. Download the configuration first if you may need it again, and find the gateway afterwards by its MAC address with the abcZ Network Tool.

The factory restore does not change the firmware: the running firmware and the alternative firmware stay as they are.

If the gateway is just closing down for a restart the command is refused and the page shows "Restore to Factory Failed! (Rejected: reboot in progress - factory restore NOT applied)". Repeat it after the restart.

After a restart command the bar runs for 5 seconds. The window then shows "Device is restarting..." while the gateway still answers and "Waiting for the device to come back..." while it does not, and the page reloads by itself as soon as the gateway answers again. If the gateway does not come back within 2 minutes the page reloads anyway and the browser may show an error; reload the page by hand a little later.

NOTE:

After Restore Factory Configuration the gateway usually comes back on another address, because it asks for its address by DHCP again. The window then waits the full 2 minutes; close it and find the gateway with the abcZ Network Tool by its MAC address.

NOTE:

The gateway restarts by itself after 24 hours of operation, counted from its last start. This planned daily restart is part of the design; the log line of it, at Log Level INFO or DEBUG, is "RESTART_SYSTEM_TIMEOUT: (S)<seconds>". Connections of Modbus TCP and other TCP clients are closed by the restart and must be opened again by the client.

In the Modbus TCP and Modbus RTU functions every meter is a separate Modbus slave. The registers of a meter are read with function 03 (Read Holding Registers), starting at address 0.

11.1 Basic rules

11.2 Register map

NOTE:

Example: a meter with 4 measurements (n = 4) has 30 registers: header 0 - 5, blocks 6 - 25, tail 26 - 29. The first block is 6 - 10, the second 11 - 15, the third 16 - 20, the fourth 21 - 25.

11.3 Data types

The "Data type" register of a measurement block holds one of the codes below. The name is the one shown on the web interface and in MQTT messages.

NOTE:

FLOAT32: the gateway applies the scale of the meter, the value is in the unit named in the third column. RAW 4 bytes: the data bytes of the meter, first byte in the high byte of the first register. Codes are fixed: a new type is always added at the end of the published list.

11.4 Function field

This chapter goes through a complete commissioning: the gateway hears a meter, the meter and its key are added, the meter gets a Modbus address, and a Modbus master reads its values. The layout of the registers is described in the chapter 11 "Modbus Register Map and Data Types".

12.1 Step 1 - Choose the function

1. Open the Operating Mode page. In the card Device Functionality Settings set Device Function to WMBus - Modbus TCP Gateway (and MQTT Publisher) or to WMBus - Modbus RTU Gateway (and MQTT Publisher).
2. Press Save Configuration. The page answers "Operating Mode Saved. REBOOT REQUIRED: this setting is applied only at boot - the device keeps running with the previous value until you reboot it."
3. Open the Management page and press Reboot Device in the card Restore / Reboot; confirm the question "Reboot the device now?".
4. Modbus TCP: the master connects to the IP address of the gateway and to the port set in Server Listening Port on the Network Settings page (factory default 502).
5. Modbus RTU: set the serial port on the Serial Settings page: RS232 or RS485, Baud rate and Line Control as the master uses them.

12.2 Step 2 - Let the gateway hear the meters

1. Open the WMBus Settings page and check Rx Package Reception Mode: it must be the mode the meters transmit in (factory default T - Mode). If you change it, press Save Configuration and confirm the restart.
2. Wait until the meters have transmitted at least once. Meters transmit on their own schedule; the gateway collects every meter it hears in its detection list.
3. Open the WMBus Settings page again. If new meters were heard, a line next to Refresh Auto Config List says, for example, "1 new device detected - press Refresh Auto Config List to add".

12.3 Step 3 - Add the meter and its key

1. Press Refresh Auto Config List. Every new meter appears as a row of the AES-128 Decryption List with its Manufacturer ID, Device ID, Version, Device Type and Last RSSI, marked "Recently Detected", with Add to Config checked.
2. For a meter you want to read: type its key into AES-128 bit Decryption Key (32 hex digits). Leave the key at zeros if the meter is not encrypted.
3. For a meter you hear but do not want to read over Modbus or MQTT: clear its Add to Config. It is then not added to the query list; its key, if it has one, is still used for decryption.
4. For a meter you do not want: check Add to Black List. It will be dropped from now on and its row is freed.
5. Press Save Configuration. In the pop-up that follows press Confirm to restart the gateway; the keys become active with this restart.

12.4 Step 4 - Give the meter a Modbus address

1. Open the Operating Mode page. The card Device Query Settings now holds a row for the meter: its device ID in WMBus Device Address, Enable checked, and a Modbus Address. The save in step 3 used the first free row, so the address is the one that row had (in a factory configuration row 1 has address 1, row 2 has address 2 and so on).
2. Change Modbus Address if your plant needs another one, from 1 to 247. Every enabled row needs its own address, otherwise the page says "All Enabled Modbuss Addresses must be unique!".
3. If you changed something, press Save Configuration, then restart the gateway with Reboot Device on the Management page as in step 1.

NOTE:

Each meter is a Modbus device of its own: the Modbus address of the row is the unit ID (slave address) the master uses for that meter. The gateway itself has no Modbus address.

12.5 Step 5 - Check on the status pages

1. Open the WMBus Status page and press Refresh WMBus Status. In the Meters table the row of the meter must show, in the Decryption column, Decrypted (or Not encrypted for a meter without encryption). The last column shows the time of the telegram. If the clock of the gateway has not been set, the last column shows Time unknown instead; the data is valid all the same.
2. If the Decryption column says No key, the gateway was not restarted after the row was saved: restart it. If it says Key might be wrong, the key of the row is wrong or was left at zeros: enter the key on the WMBus Settings page, save and restart.
3. Open the Device Status page. In Modbus Communication Status the row of the meter shows its Modbus Address, its WMBus Device ID, Enabled in the column Row and, once a telegram has been received, Fresh in the column Data. No frame yet means the meter has not been heard since the restart; Stale means its last telegram is older than 60 minutes. If the clock of the gateway has not been set, the column shows Time unknown instead of Fresh or Stale; if the telegram could not be decrypted it shows the same word as the Decryption column of the Meters table.

12.6 Step 6 - Read the registers

Use any Modbus master. Read holding registers with function 03; the unit ID is the Modbus address of the meter; the map of every meter starts at register address 0.

A meter with n data records therefore fills 10 + 5 x n registers: 6 header registers, 5 registers per record and 4 registers at the end. Two ways of reading are common:

• Exact read: read 6 registers from address 0, take n from register 5, then read 10 + 5 x n registers from address 0. For a meter with 2 records this is 10 + 5 x 2 = 20 registers; its records are in registers 6 - 10 and 11 - 15, the access number is in register 16, the RSSI in 17, the meter status in 18 and the decryption status in 19.
• Fixed block: always read 80 registers from address 0. 80 is the largest map (14 records: 10 + 5 x 14). Registers behind the end of the map of the meter read 0. The four end registers still follow the last record, so their position depends on n.

Example for Modbus TCP, meter at Modbus address 5, fixed block of 80 registers. Request (hex): 00 01 00 00 00 06 05 03 00 00 00 50 - transaction 0001, protocol 0000, length 6, unit 05, function 03, start address 0000, quantity 0050. The answer has 169 bytes: 7 header bytes, the function code, the byte count A0 (160) and 80 registers of 2 bytes each. With Modbus RTU the same read is 05 03 00 00 00 50 followed by the CRC, and the answer has 165 bytes.

• Only function 03 is answered.
• A request to a unit ID that is not the Modbus address of an enabled row is not answered.
• A quantity above 126 registers (Modbus TCP) or above 127 registers (Modbus RTU) is answered with exception code 03. One meter never needs more than 80.
• Until the first telegram of a meter has been received after a restart, all registers of that meter read 0, the device ID in registers 0 - 1 included. A decryption status of 0 does not mean "not encrypted" then: treat device ID 0 as "no telegram yet".

WARNING:

Check the decryption status register before using the values. With status 2, 3 or 4 the last telegram could not be read. The number of records and the record registers then still hold the values of the last telegram that was read (no records if none was read since the restart), while access number, RSSI, meter status and decryption status belong to the telegram received last. A master that reads only the records takes old values for current ones.

NOTE:

The Connections table of the Device Status page shows the last request and the last response of each master, which helps when a master does not get the answer it expects.

The gateway can publish the data of every configured meter to an MQTT broker. A meter is published when it has an enabled row in the Device Query Settings table of the Operating Mode page and its telegram could be decrypted and decoded. Telegrams of meters that are not in the table, and telegrams that cannot be decrypted, are not published. Standard models and the STG655 publish up to 128 meters, the STG154 Lite up to 20.

Publishing runs next to the Modbus service: in the Modbus TCP and Modbus RTU gateway functions the same meter data can be read over Modbus and is sent to the broker at the same time.

13.1 Which device functions publish

The publisher is switched with Enable MQTT Publisher for Parsed WMBus Packages on the Network Settings page. In four of the six device functions a save of the Operating Mode page also sets this box:

NOTE:

MQTT runs only in the three device functions that publish. In WMBus - TCP/IP Transparent Gateway, WMBus - Serial Transparent Gateway and WMBus Repeater the gateway does not connect to a broker, even when a configuration file brings the publisher in switched on: nothing is published, the MQTT rows and the MQTT box of the Device Status page are not shown, the delivery watchdog does not run and a configuration cannot be sent over MQTT. In these functions use the web page or a configuration file upload.

13.2 Setting up the connection

1. On the broker create an account for the gateway and note its address, port, user name and password. The broker must accept an unencrypted MQTT connection with user name and password.
2. On the Operating Mode page select the Device Function, enter the meters in Device Query Settings, tick Enable for each of them and save. Enter the AES keys of encrypted meters on the WMBus settings page.
3. Open Network Settings. In the Modbus gateway functions tick Enable MQTT Publisher for Parsed WMBus Packages.
4. Enter MQTT Broker IP or URL and MQTT Broker Port.
5. Enter a Client ID that is unique on the broker, then User Name and Password.
6. Enter the Publish Topic and a Subscribe Topic that belongs to this device only.
7. Set Minimum Send Interval for a Parsed Data (in seconds) and choose the Data Format.
8. If the broker or the time server is entered by name, make sure the device has a DNS server and a gateway (see the Network Settings page description). Enter the NTP Server IP or URL if the messages should carry time stamps.
9. Click Save Configuration and restart the device with Reboot Device on the Management page.
10. Open Device Status. MQTT Status shows APP_MQTT_STATE_SUBSCRIBED when the device is connected to the broker and has subscribed (for a moment during each publish it shows APP_MQTT_STATE_PUBLISH instead; a state that stays at IDLE, NET_CONNECT or CLIENT_CONNECT means the broker is not reached or refuses the login). MQTT Sent Messages counts the published messages since the start.

NOTE:

User Name and Password are always sent and cannot be left empty. For a broker that needs no login enter any text the broker accepts.

NOTE:

MQTT Sent Messages and MQTT Status are shown on the Device Status page only while the publisher is enabled in one of the three functions that publish.

13.3 Connection properties

13.4 When a message is sent

Each decoded telegram marks its meter as waiting. The device sends one message per waiting meter, built from the latest telegram of that meter.

• Minimum Send Interval for a Parsed Data (in seconds) is the shortest time between two messages of the same meter. A meter that transmits every 15 seconds is published once a minute with the factory value of 60; a meter that transmits once an hour is published once an hour.
• If several telegrams of a meter arrive within the interval, only the latest one is published when the interval has passed. The Modbus values are not affected.
• The interval also runs from the start of the device: the first message of each meter is sent no earlier than this many seconds after a restart.
• Messages are sent only while the device is connected and subscribed. A telegram received while the broker is away stays waiting and is published after the connection is back - one message per meter, with the latest data.
• A message that was being sent when the connection broke is sent again after the reconnect.

NOTE:

Capacity: the device publishes about 3 messages per second. If telegrams arrive faster than that for a longer time, part of them does not reach MQTT (a newer telegram of the same meter replaces the waiting one). The Modbus values stay complete. Take this into account for large populations of fast-sending meters and choose the send interval accordingly.

13.5 Common part of every message

A message is one JSON object without spaces or line breaks. Every value is a JSON string (in double quotes), also the numbers. All three formats start with the same fields:

{"STGid":"<gateway id>","STGNme":"<device name>","Time":"<send time>","RxTm":"<receive time>","Data":{"DevId":"<meter id>","ManId":"<manufacturer>","Ver":"<version>","Typ":"<type>","RSSI":"<rssi>","AcNu":"<access number>", ... }}

WARNING:

The hexadecimal values are printed without leading zeros and with capital letters. A meter with the number 00144739 appears as "DevId":"144739", version 05 as "Ver":"5". Compare these values as numbers or after removing leading zeros, never as text of fixed length.

NOTE:

Time stamps need NTP. If the time server stops answering, "Time" and "RxTm" disappear from the messages about 11 minutes later and come back with the next answer; all other fields are sent as usual. The receiver must not expect the keys to be present.

13.6 Format RAW WMBUS DECRYPTED DATA

{"STGid":"<gateway id>","STGNme":"<device name>","Time":"<send time>","RxTm":"<receive time>","Data":{"DevId":"<meter id>","ManId":"<manufacturer>","Ver":"<version>","Typ":"<type>","RSSI":"<rssi>","AcNu":"<access number>","RawDt":"<telegram bytes as hex>"}}

RawDt is the telegram as text: two capital hexadecimal digits per byte, no separators. It starts with the length byte of the telegram and ends before the checksum. The receiver decodes the data records itself. Also in this format a message is sent only for a telegram the gateway could decrypt and decode.

Example, received from a gateway with firmware 3.00.00 (meter 19142190, the first byte 4E = 78 bytes follow):

{"STGid":"5A9A","STGNme":"STG_21ea_LAB","Time":"1792046738","RxTm":"1792046738","Data":{"DevId":"19142190","ManId":"9B4","Ver":"13","Typ":"7","RSSI":"-60","AcNu":"52","RawDt":"4E44B4099021141913077A341840052F2F0C1330120000046D37294F3A0F173E202723030000007B00007B00007B00007B00007B00007B00007B00007B00007B00007B00007B00007B0000002F2F2F"}}

13.7 Format PARSED DATA AS OBJECTS

{"STGid":"<gateway id>","STGNme":"<device name>","Time":"<send time>","RxTm":"<receive time>","Data":{"DevId":"<meter id>","ManId":"<manufacturer>","Ver":"<version>","Typ":"<type>","RSSI":"<rssi>","AcNu":"<access number>","DtCnt":"<count>","Trnc":"1","Blcks":[{"S":"<storage>","F":"<function>","T":"<data type>","V":"<value>"},{"S":"<storage>","F":"<function>","T":"<data type>","V":"<value>"}]}}

Records the gateway cannot express as one of its data types are left out of the array and are not counted in DtCnt.

Example, the same meter in this format (2 records: data type 3 and data type 47):

{"STGid":"5A9A","STGNme":"STG_21ea_LAB","Time":"1792047106","RxTm":"1792047106","Data":{"DevId":"19142190","ManId":"9B4","Ver":"13","Typ":"7","RSSI":"-64","AcNu":"58","DtCnt":"2","Blcks":[{"S":"0","F":"1","T":"3","V":"1230"},{"S":"0","F":"1","T":"47","V":"15-10-2026 10:01:00 DST:0"}]}}

13.8 Format PARSED DATA AS MODBUS FRAME

{"STGid":"<gateway id>","STGNme":"<device name>","Time":"<send time>","RxTm":"<receive time>","Data":{"DevId":"<meter id>","ManId":"<manufacturer>","Ver":"<version>","Typ":"<type>","RSSI":"<rssi>","AcNu":"<access number>","ModFr":"<length byte and registers as hex>"}}

ModFr is text with two capital hexadecimal digits per byte. The first byte is the number of bytes that follow. The following bytes are the Modbus registers of this meter, two bytes per register, high byte first, exactly as a Modbus master reads them from address 0:

A meter with 3 data records gives 6 + 15 + 4 = 25 registers, 50 bytes; the length byte is then 32 (hexadecimal) and ModFr is 102 characters long. The register contents are described in the Modbus chapter.

Example, the same meter in this format: 2 data records give 6 + 10 + 4 = 20 registers, 40 bytes, so ModFr starts with 28 (hexadecimal):

{"STGid":"5A9A","STGNme":"STG_21ea_LAB","Time":"1792047230","RxTm":"1792047230","Data":{"DevId":"19142190","ManId":"9B4","Ver":"13","Typ":"7","RSSI":"-56","AcNu":"60","ModFr":"281914219009B40013000700020000000100034499C00000000001002F032A4F3A003CFFC800180001"}}

13.9 Largest message

A published message is at most 1152 bytes long. The raw format and the Modbus frame format always fit, and so does the object format with ordinary numeric values. Only a meter whose 14 records carry long text values can reach the limit in the object format. The records that no longer fit are then left out: DtCnt still gives the full number of records, the array holds fewer, and the text may end with a comma before the closing bracket, which a strict JSON reader refuses. If you see this for a meter, use a short Device Name or one of the other two formats.

13.10 Keep-alive, ping and reconnect

• The keep-alive time announced to the broker is 120 seconds.
• When nothing was published for 60 seconds the device sends a PING to the broker.
• If the PING is not answered within 10 seconds the device closes the connection and connects again.
• After any loss of the connection the device tries again by itself, at most once every 5 seconds, and subscribes again after it has connected. Nothing has to be done on the device.

A broker or router that drops idle connections therefore does not cut the data silently.

13.11 Delivery watchdog

WARNING:

While the MQTT publisher is enabled and the broker cannot be reached, the device restarts itself after about 13 minutes, and once more after the same time. Every restart also drops the Modbus TCP connections. Enable MQTT only when the broker is reachable; if the broker is not ready yet, switch the publisher off.

The watchdog works as follows. Every published message and every answered PING counts as a delivery. If there was no delivery for 3 minutes although the local network is fine, the device counts once a minute and reacts in steps: at the 5th count it renews its DHCP lease, at the 8th it asks for a new lease, at the 11th it restarts. The DHCP steps apply to a device that gets its address from a DHCP server. When deliveries work again the count is cleared. A broker that is reachable but receives no meter data does not trigger the watchdog, because the PING is answered.

The watchdog works when the device has a static address or an address from a DHCP server, and only while the cable is connected and the default gateway answers. It does not run while DHCP Server Enabled is ticked, and not in the device functions without MQTT.

After two such restarts in a row the device does not restart a third time: it stays up and waits. The web interface and the TCP service stay available; restart the device from the web page (or switch the power off and on) once the cause is removed.

Log lines of the watchdog, visible when logging is enabled:

13.12 Subscribe Topic: configuration over MQTT

The device subscribes to the Subscribe Topic and accepts one kind of message on it: a configuration file, sent in parts. It is the same file that Download Current Configuration on the Management page produces and Upload Configuration File accepts. There are no other commands: a restart, a time setting or a single setting cannot be sent over MQTT. This works only while the publisher is enabled in one of the three functions that publish.

Each part is one MQTT message with this payload:

<total>, <position>, <length>"<characters of the file>"

• Send the parts in order and without gaps: the position of a part must be the position of the previous part plus its length. The part whose position plus length reaches the total ends the file.
• Keep the parts small. The device receives a message of up to 1024 bytes in one piece; a longer message is not read correctly. Parts of 800 file bytes are the size used in the tests.
• Wait for the reply to a part before you send the next one.
• If the next part does not arrive within 60 seconds the transfer is abandoned and the running settings are restored. A configuration upload from the web page also abandons an unfinished MQTT transfer.

The device answers every part with one message on the topic MQTT_STG_Conf_Ack_topic. This reply topic is fixed and cannot be changed:

{ "variable": "conf_upd_ack","value": "started","metadata": {"mqtt_topic": "MQTT_STG_Conf_Ack_topic", "result": "OK", "position": <position>, "length": <length>, "response": "<text>", "response_1": "" }}

In response and response_1 double quotes, backslashes, line ends and other non-printable characters are shown as $.

WARNING:

A configuration file received over MQTT replaces all settings of the device - operating mode, network address, meters and keys, filters, MQTT settings and the password of the web interface are all part of the file. The device does not restart by itself. Part of the new settings is used at once, the rest only after a restart; until then the device works with a mixture of old and new settings. Restart it right after the last reply, from the web page or by switching the power off and on.

WARNING:

A configuration file holds the password of the web interface, the MQTT password and the AES keys of the meters in readable form, not encrypted. Everyone who can read the Subscribe Topic on the broker can read them, so allow only authorised clients to subscribe and to publish to this topic.

WARNING:

Every device that is subscribed to the topic takes the file. Two gateways with the same Subscribe Topic on the same broker are both overwritten, including their network address. Give each gateway its own Subscribe Topic before you use this function, and protect the topic on the broker so that only authorised senders may publish to it.

NOTE:

A payload that does not start with the three numbers changes nothing. The device still answers it: the reply has position 0 and length 0 and says result OK, and its response text may be left over from an earlier transfer - do not take such a reply as a confirmation. Publish nothing but configuration parts to this topic.

NOTE:

The reply topic is the same for all gateways and the reply does not name the gateway. Send a configuration to one gateway at a time and wait for its last reply.

Recordings of the web interface of a gateway with firmware 3.00.00. The videos have no sound; each step is described in the chapter named above the video.

14.1 Firmware update

The Management page of a standard gateway: the image file is chosen, sent with Upload Firmware and checked by the gateway; afterwards the alternative firmware shows the uploaded version. The switch to the new firmware with Reboot Alternative Firmware is not part of the recording. Steps, limits and the upgrade from 2.x: 10.9.2 "Live Firmware Update" and chapter 15 "Firmware Update and Upgrading from 2.x".

14.2 WMBus to Modbus conversion

The example of chapter 12 "WMBus to Modbus Conversion Example" on a standard gateway that starts from the factory settings: the Modbus TCP function, the meters heard on the air, the key of one meter, its Modbus address and the status pages while a Modbus master reads the meter.

WARNING:

CRITICAL MIGRATION NOTE: upgrading 2.x -> 3.x RESETS all device settings to FACTORY defaults (the layout of the stored configuration changed from 64 to 128 rows). Record every setting BEFORE the upgrade and enter it again afterwards. After the upgrade the network settings are factory too: the device asks for its address by DHCP (static address off). Supported upgrade path: 2.x -> 3.x. A direct upgrade from 1.x to 3.x is not supported.

15.1 Firmware images

NOTE:

Notes: next to every image there is <image>_ICSP.hex (programmer file: bootloader + application) and the manifest RELEASE_v3.00.00.json / .md with the SHA-256 values. Do not rename the image files - the update tool reads the variant from the name. The Lite device accepts only the Lite image. There is no Lite + BPL product.

15.2 Upgrade checklist

15.3 What behaves differently from 2.x

The table lists what you notice on the web interface and in your system after the upgrade, and what to do.

The factory values did not change: device function WMBus - TCP/IP Transparent Gateway, address 192.168.1.1 / 255.255.255.0, server port 502, at most 2 clients, serial port 115200 8N1, MQTT and log off.

16.1 What the tool does

The abcZ Network Tool is our Windows program for REDZ devices on an Ethernet network. With STG gateways it finds them and shows their address, product, firmware version and MAC address, reads the identity of one gateway, gives a gateway a static address, and updates the firmware of one gateway or of many gateways at once. This chapter describes version 1.1.0 and only what you need with an STG gateway. Download the tool and its own user guide from the Support page of redz-sc.com (https://redz-sc.com/en/support).

The tool talks to the gateway the way a web browser does. Type the user name and password of the gateway's web interface in User and Password on each tab. A gateway with another password is listed with "auth required (password?)" in the Product column.

16.2 Find the gateway

Open the Discovery tab. In IP range type the addresses to search: a network such as 192.168.0.0/24, a range of the last number such as 192.168.0.1-254, a range such as 192.168.0.10-192.168.1.50, or one address. Click Scan (HTTP): the tool reads the start page of every address in the range, so it also finds gateways behind a router. Each gateway found appears as a row with IP, MAC, Series, Product, Device (the device name), Version and Build date.

Discover (UDP) is faster: it asks with a broadcast on UDP port 30303, which the gateway answers. A broadcast does not cross routers, so it finds only gateways in the same subnet as the PC. The gateways that answer are then read in the same way as with Scan.

Double-click a row to open the gateway's web interface in your browser. Series filter and Find narrow the list. Export CSV saves the selected rows (or all rows shown) as a list for Fleet Update.

A gateway that is not found may still be at its factory address 192.168.1.1 in a network without a DHCP server; see 10.1 "Connecting to the Web Interface". Assign Address at Factory IP... on the Discovery tab gives such a device a new address from a PC in another network; its steps are in the tool's own user guide.

16.3 Read the identity of one gateway

On the Single Device Update tab, type the gateway's address in Device IP and click Read Identity (safe). The panel Device identity (last read) shows the product name, firmware version, build date, MAC address and device name. Nothing is changed on the gateway. If Expected product is empty, the tool fills it with the product name it read; this name protects the firmware update (below).

16.4 Give the gateway a static address

On the Discovery tab, right-click the gateway's row and choose Set IP / Subnet / Gateway (one device).... The tool first reads the gateway's network settings; the window "Set network - <address>" then shows IP address, Subnet mask and Gateway as they are stored for the static address (Server IP Address, Server Net Mask and Server Gateway Address on the Network Settings page). A gateway that has its address from a DHCP server shows these stored values, not the address it uses now.

Type the new values, click Apply and type SET to confirm. The tool turns on Use Static Address for Device, saves the three values (the other network settings are kept), restarts the gateway and looks for it by its MAC address in the new subnet. When it finds the gateway there, the log says "now reachable at" with the new address. When it does not, the log warns that the gateway was not found by its MAC address, and the Status column shows "IP set? not found at" with the address you typed. While a scan or an update is running, the tool refuses this command; wait until the task ends.

NOTE:

If the gateway is not found after the change, check the new address with Scan (HTTP) or in your browser. A wrong subnet mask or gateway can make the gateway unreachable.

16.5 Update the firmware

On the Single Device Update tab:

1. Type the gateway's address in Device IP and click Read Identity (safe), so that Expected product holds the product name of this gateway.
2. Click Browse... and choose the firmware image (.binimg) of your model from the firmware package (see chapter 15 "Firmware Update and Upgrading from 2.x"). Keep the package's RELEASE_v3.00.00.json file next to the image: the tool then checks the image against it.
3. Click Update and confirm.

Before it writes, the tool stops when the product name read from the gateway is not the expected one (this cannot be overridden), skips a gateway that already runs the version in the file name (tick Force (flash even if version matches) to write it anyway) and asks before it writes an image for another model, for example an image with BPL for a gateway without BPL or a Lite image for a gateway that is not a Lite model: answer No in the window Image / device mismatch and the gateway is not touched. The image is written into the gateway's alternative firmware bank; the tool then sends the command to start it once, waits for the restart and compares the version and build date the gateway reports. The log ends with "RESULT:" and SUCCESS when the gateway runs the new firmware.

NOTE:

Factory reset after update deletes every setting of the gateway after the update, and its address may change. Leave it off unless you want the factory settings. When the factory reset was sent and accepted, the result line reads "SUCCESS (factory reset)". When the gateway was updated but the factory reset was refused, answered with an error or not sent, the result is UPDATED, FACTORY RESET FAILED; as the pilot of a fleet update this result stops the fleet.

16.6 Update many gateways

The Fleet Update tab updates a list of gateways from a CSV file with the columns ip, expected_product and image_path (the image path is relative to the CSV file). Export CSV on the Discovery tab writes such a list with the image column empty. Validate CSV (dry-run) checks the list without writing. With a Pilot IP (opt.) the tool updates that gateway first and leaves all the others untouched if it fails; the rest are then updated Parallelism (jobs) at a time.

The gateway writes log lines to the console port or to a UDP log server, and answers every save on the web interface with a text. The tables below list the lines and replies you are most likely to see, when they appear and what to do.

17.1 Boot (every start, at every log level)

17.2 Network watchdog

17.3 Restart gate / parking

17.4 MQTT

17.5 Web replies (text of the reply to a save or upload)

17.6 Configuration (log lines)

17.7 Firmware update

17.8 Modbus / serial

17.9 WMBus / radio module

17.10 Log channel / memory

17.11 Known behaviours and limits

The following behaviours of firmware 3.00.00 are known and intended or accepted. They are listed here so that they are not taken for a fault.

17.11.1 Factory settings after the upgrade from 2.x

• Symptom: after the upgrade from firmware 2.x the gateway has lost operating mode, meter list, AES keys, Modbus rows and network settings; it does not answer on its former static address.
• Cause: firmware 3.00.00 stores 128 meter rows instead of 64. The layout of the stored settings is different, so the settings of 2.x cannot be taken over.
• What to do: record all settings before the upgrade. After the upgrade find the gateway by its MAC address with the abcZ Network Tool (it asks for an address by DHCP) and enter the settings again, or upload the configuration file saved with 2.x and check every setting on the pages. A gateway that runs 2.x does not accept a configuration file made by 3.00.00.

17.11.2 No direct upgrade from 1.x

A direct upgrade from firmware 1.x to 3.x is not supported. The only supported upgrade path is from firmware 2.x.

17.11.3 Restarts while the MQTT broker is unreachable

• Symptom: the gateway restarts about every 13 minutes; Modbus TCP connections drop at every restart.
• Cause: MQTT is enabled in one of the three device functions that publish, but the broker cannot be reached. The gateway watches the delivery to the broker, first renews its network address and, if that does not help, restarts. After two such restarts in a row it does not restart a third time for this reason; it stays up and waits.
• What to do: make sure that the broker address, the port and the route to the broker are right, or switch MQTT off until the broker is ready. Saving the device function WMBus Decoder/Parser and MQTT Publisher switches MQTT on by itself.

17.11.4 MQTT: about 3 messages per second

• Symptom: with many meters that send often, not every telegram appears at the MQTT broker.
• Cause: the gateway publishes about 3 messages per second. Telegrams that arrive faster overwrite each other for MQTT.
• What to do: take this into account for large populations of fast-sending meters. The Modbus values stay complete - every meter row holds the values of its last telegram.

17.11.5 Planned restart every 24 hours

• Symptom: once a day the gateway restarts; TCP connections are closed.
• Cause: by design the gateway restarts after 24 hours of operation, counted from its last start. The log line, at Log Level INFO or DEBUG, is "RESTART_SYSTEM_TIMEOUT: (S)<seconds>".
• What to do: nothing. A Modbus TCP master or another TCP client must be able to connect again by itself.

17.11.6 Not every Modbus request is logged

• Symptom: the log shows only a few lines for Modbus requests although the master polls all the time.
• Cause: the request lines are written at level DEBUG only, and only for the first 3 requests and then for every 100th request.
• What to do: read the request and response counters on the status page instead of counting log lines.

17.11.7 "flash verify failed" or "config flash invalid"

• Symptom: a save or a configuration upload is answered with "Rejected: flash verify failed - NOT saved; restart restores factory settings"; every further save is answered with "Rejected: config flash invalid - restart the device (factory settings)". Reboot Alternative Firmware is refused with the same reason (Alternate Firmware Boot Failed!).
• Cause: the gateway reads back every write of its settings. This write did not verify, so the stored settings are not valid. Until the restart the gateway keeps working with the settings it had before.
• What to do: restart the gateway. It starts with factory settings (network by DHCP, password admin); upload your configuration file or enter the settings again. Switch the firmware only after this restart. Contact REDZ support if it happens again.

17.11.8 Delayed answers on packet loss

• Symptom: single Modbus TCP answers arrive 1 second late (3 seconds in a longer interruption); a web page reply can take about 1.6 seconds.
• Cause: a packet was lost on the network; the gateway repeats a lost Modbus TCP answer after 1.0 second and, if the interruption lasts longer than 1 second, again in the 3rd second.
• What to do: set the response timeout of the Modbus TCP master longer than these times. A shorter timeout closes and reopens the connection on every lost packet.

17.11.9 "LOG ring overflow" at log level DEBUG

• Symptom: at Log Level DEBUG and with much traffic the log shows "LOG ring overflow - line(s) dropped (oldest kept): <n>" and lines are missing.
• Cause: the log output delivers about 17 lines per second; lines produced faster are dropped and counted.
• What to do: nothing is wrong with the data - only log lines are lost, Modbus and MQTT are not affected. Use the counters of the status page for measurements and a lower log level for long observations.

17.11.10 A file with fewer rows replaces the meter list

• Symptom: after a configuration file of firmware 2.x (64 rows) was uploaded into a gateway that already had meters in the rows 65 to 128, those rows are empty.
• Cause: the meter list and the key list of a file replace the lists stored in the gateway. Rows that the file does not contain are set to their factory values; they do not keep their former content. This is the same for an upload on the web page and over MQTT.
• What to do: nothing if the file is the complete configuration. If the rows 65 to 128 are still needed, download the configuration of the gateway first and enter those rows again after the upload.

17.11.11 Configuration over MQTT needs a restart

• Symptom: a configuration file sent over MQTT is answered with "Configuration Uploaded - reboot required to apply", but the gateway goes on working with its former settings.
• Cause: over MQTT the file is stored but the gateway does not restart by itself; the settings take full effect only after a restart. If the transfer stops and no further part arrives for 60 seconds, the gateway gives the transfer up and returns to the settings it had before (log line "MQTT config upload abandoned - running settings restored"); the same happens when a configuration file is uploaded on the web page meanwhile.
• What to do: restart the gateway after the last part was acknowledged. Send the complete file again after an interrupted transfer. Every gateway that is subscribed to the topic takes the file - use a separate topic for each gateway.

17.11.12 BPL model: one path only

Connect an STG655 to a network either over the power line or over Ethernet, never over both at the same time: both paths together close a loop in the network, packets are lost and uploads are cut.

17.11.13 Modbus values after a telegram that cannot be read

• Symptom: a meter whose last telegram could not be decrypted still shows meter values on Modbus.
• Cause: the gateway keeps the values of the last telegram it could read. Only the decryption status register (value 2, 3 or 4) tells that the newest telegram could not be read.
• What to do: let the SCADA system read the decryption status register first and not use the values while it reads 2, 3 or 4.

17.11.14 Standard and BPL images are not told apart

A standard gateway also accepts the image of the STG655, and the reverse. Choose the image by your model and check the file name before you upload. If the wrong image was loaded, upload the right image and switch to it.