¶ Introduction
This application note describes the use of this LUA script which sets a protocol to communicate with the Acrios N-W-D converter and the server configured for this purpose.
¶ Payload
In this case, there are two different kinds of payload messages, one that is sent from the converter to the server with the requested information = uplink, and one that is sent from the server to the converter with specific commands = downlink. First, you can find a description of Command bytes, which are sent by the converter to the server, and secondly, the commands are given by the server.
¶ Command bytes
| Converter command bytes = Uplink | Server command bytes = Downlink | ||||
| Command byte | Description | Command byte | Description | ||
| 0xFF | Gather report | 0x01 | Send IDs | ||
| 0xFE | Configuration acknowledge | 0x02 | Send config | ||
| 0xFD | W M-Bus IDs acknowledge | 0x03 | Request config | ||
| 0xFC | Scanned unit report | 0x04 | Request scan | ||
| 0xFB | Scanning done | 0x05 | Request IDs | ||
| 0xFA | Status report | 0x06 | Request status | ||
| 0xF9 | Bootloader request | 0x07 | Request reset | ||
| 0xF8 | Scanned unit with mode report | 0x08 | Downlink send ack | ||
| 0xF7 | Bootloader answer | 0x09 | Downlink error report readout | serial log + error | |
| 0xF6 | W M-Bus IDs checksum | 0x0A | error | ||
| 0xF5 | MBus scan done | ||||
| 0xF4 | Gather report acked | ||||
| 0xF3 | Scanned unit with mode report acked | ||||
| 0xF2 | Status report extended | ||||
| 0xF1 | Error report | ||||
| 0xF0 0xFF | Beacon report | ||||
| 0xF0 0xFE | Send once data | ||||
| 0xF0 0x00 | ACRCOM | ||||
| 0xF0 0xFD | Send once end of gathering | ||||
¶ Payloads sent by the converter = UPLINK
¶
Gather report
Gather report for N devices. The report is sent after every scanning cycle and includes the information about which ID was found and which was not found.
| Description | Command byte | Gather report | ||
| Bytes | 1B | N x 1B | ||
| Example | 0xFF | 0x01 | 0x01 | 0x01 |
0x01 = IDs received
0x00 = IDs not found
0xFF 01 00 01 = ID1 was found, ID2 was not found, ID3 was found
¶
Configuration acknowledgment
| Description | Command byte | Time per entry [s] |
Gather time S mode [s] |
Gather time T/C mode [s] |
Wake up period [Days] |
Wake up period [Hours] |
Wake up period [minutes] |
Filter length | Config version | Gather time M mode [s] |
| Bytes | 1B | 1B | 1B | 1B | 1B | 1B | 1B | 1B | 1B | 1B |
| Example | 0xFE | 0x78 | 0x00 | 0x00 | 0x00 | 0x00 | 0x0F | 0x06 | 0x0E | 0x1E |
Time per entry - the time in seconds for how long we scan for 1 ID. The total scan time is being calculated as N*Time per entry, where “N” is the number of IDs in the filter. If we have 15 IDs, the total scan time will be calculated as the 15*Time per entry.
Gather time S, T, and M mode - time in seconds defining for how long the device receives the data in S, T, or M mode (timeout)
Filter length - total number of device IDs stored in memory
Config version - number that increments with the new configuration (0 to 255)
¶ W M-Bus IDs acknowledgment
| Description | Command byte | Filter length [= N] | Filter IDs | |||||||||||
| Bytes | 1B | 1B | N x 4B | |||||||||||
| Example | 0xFD | 0x03 | 0x90 | 0x82 | 0xCB | 0x01 | 0x74 | 0x82 | 0xCB | 0x01 | 0x75 | 0x82 | 0xCB | 0x01 |
The byte order of filter IDs (mentioned in the example above) starts with LSB and ends with MSB (little endian), therefore IDs look like this:
ID1 = 01 CB 82 90
ID2 = 01 CB 82 74
ID3 = 01 CB 82 75
¶ Status report
| Description | Command byte | Status report | Script version | ||||
| Bytes | 1B | 3B | 3B | ||||
| Example | 0xFA | 0x0F | 0x0B | 0x0E | 0x33 | 0x2E | 0x30 |
The status report contains 3 bytes. where:
- 1st byte (0x0F) is a signal
- 2nd byte (0x0B) is the LSB of battery voltage
- 3rd byte (0x0E) is the MSB of battery voltage
¶ Scanned unit with mode report
| Description | Command byte | N x Device type | N x Device ID | N x Manufacturer ID | N x RSSI | N x Mode | |||||
| Bytes | 1B | N x 1B | N x 4B | N x 2B | N x 1B | N x 1B | |||||
| Example | 0xF8 | 0x80 | 0x06 | 0x32 | 0x67 | 0x01 | 0x68 | 0x50 | 0x0A | 0xFF | 0x01 |
N = number of devices
This is an answer to a scan request given by the server.
Device type - is given by a WMBUS device manufacturer and can tell you whether it is hot or cold water, ITN, or other device types. For the description please check the OMS Metering protocol.
Manufacturer ID - is given by a WMBUS device manufacturer.
RSSI - Received Signal Strength Indication. A higher number is better.
Mode:
- - 0x00 = S Mode
- - 0x01 = T/C Mode
- - 0x02 = M Mode - proprietary protocol. Reach out to us for the specification and closer information.
¶ Data report
| Description | Local W M-Bus ID | Raw device data | |||||
| Bytes | 1B | xB | |||||
| Example | 0x01 | 0xXX | |||||
On each device can be set only 240 local W M-Bus IDs in range from 0 (0x00) to 127 (0xF0)
This is a periodic report sent by the converter, where the first byte defines the local W M-Bus ID followed by raw data from the W M-Bus device.
¶ W M-Bus IDs checksum
| Description | Command byte | Filter length [= N] | Checksum | |||
| Bytes | 1B | 1B | 4B | |||
| Example | 0xF6 | 0x03 | 0x91 | 0x82 | 0xCB | 0x01 |
The checksum is calculated with bitwise XOR:
RES1 = 0 ⊕ (ID1) => 0 ⊕ 0x01CB8290 = 0x01CB8290
RES2 = (RES1) ⊕ (ID2) => 0x01CB8290 ⊕ 0x01CB8274 = 0xE4
RES3 = (RES2) ⊕ (ID3) => 0xE4 ⊕ 0x01CB8275 = 0x01CB8291
…
RESN = (RESN-1) ⊕ (IDN)
The last calculated value is the checksum.
¶ Bootloader request
The example bellow is split here only for better understanding, otherwise it's sent only as one frame.
Bellow is first part of the frame, it contains bootloader specific command byte, bootloader version and bootloader request type.
There are three different bootloader request types:
- BL_REQ_ALL - contains whole frame, including NB-IoT, Chip IDs and CRC section (example bellow)
- BL_REQ_NBIOT_IDS - contains only NB-IoT related part (IMEI, IMSI, ICCID separated with 0x00 as in the example)
- BL_REQ_CHIP_IDS - contains only chip information
- BL_REQ_SECTIONS_CRC - contains only CRC part of the frame
¶
|
Description |
Command byte |
Version |
BL request type |
||||
| Bytes | 1B | 2B | 1B | ||||
| Example | 0xF9 | 0x06 | 0x06 | 0x00 | |||
NB-IoT IDs section (BL_REQ_NBIOT_IDS)
|
Description |
IMEI (868333035037122) |
Split by zero |
|||||||||||||||||||
| Bytes | xB (ASCII) | 1B | |||||||||||||||||||
| Example | 0x38 | 0x36 | 0x38 | 0x33 | 0x33 | 0x33 | 0x30 | 0x33 | 0x35 | 0x30 | 0x33 | 0x37 | 0x31 | 0x32 | 0x32 | 0x00 | |||||
|
Description |
IMSI (901405710058915) |
Split by zero |
|||||||||||||||||||
| Bytes | xB (ASCII) | 1B | |||||||||||||||||||
| Example | 0x39 | 0x30 | 0x 31 | 0x34 | 0x30 | 0x35 | 0x37 | 0x31 | 0x30 | 0x30 | 0x35 | 0x38 | 0x39 | 0x31 | 0x35 | 0x00 | |||||
| Description | ICCID (89882280000010095459) | Split by zero | |||||||||||||||||||
| Bytes | xB (ASCII) | 1B | |||||||||||||||||||
| Example | 0x38 | 0x39 | 0x38 | 0x38 | 0x32 | 0x32 | 0x38 | 0x30 | 0x30 | 0x30 | 0x30 | 0x30 | 0x31 | 0x30 | 0x30 | 0x39 | 0x35 | 0x34 | 0x35 | 0x39 | 0x00 |
Chip IDs section (BL_REQ_CHIP_IDS)
|
Description |
Chip EUI (0x203839375942500D0031005D) |
|||||||||||||||
| Bytes | 12B (little endian) | |||||||||||||||
| Example | 0x5D | 0x00 | 0x31 | 0x00 | 0x0d | 0x50 | 0x42 | 0x59 | 0x37 | 0x39 | 0x38 | 0x20 | ||||
| Description | Flash size in kB (100 kB) | Chip package (10) | Chip ID & Rev (REV Z, id 435) | |||||||||
| Bytes | 4B (little endian) | 4B (little endian) | 4B (little endian) | |||||||||
| Example | 0x00 | 0x01 | 0x00 | 0x00 | 0x0B | 0x00 | 0x00 | 0x00 | 0x35 | 0x64 | 0x01 | 0x10 |
Chip package types:
- 0 - LQFP64
- 10 - UFQFPN48
- 11 - LQFP48
Revision:
0x10016435 → 0x1001
((0x10016435 & 0xFFFF0000) >> 16)
- 0x1000 - REV A
- 0x1001 - REV Z
- 0x2001 - REV Y
Chip ID:
0x10016435 → 0x435
0x10016435 & 0xFFF)
- 0x435 = STM32L43xxx/STM32L44xxx
- 0x462 = STM32L45xxx/STM32L46xxx
- 0x464 = STM32L41xxx/STM32L42xxx
CRC section (BL_REQ_SECTIONS_CRC)
| Description | CRC16 BL | CRC16 Config | CRC16 App | CRC16 Lua | CRC16 Fragment | |||||||
| Bytes | 2B (little endian) | 2B (little endian) | 2B (little endian) | 2B (little endian) | 2B (little endian) | |||||||
| Example | 0xF5 | 0x09 | 0x5B | 0x1B | 0x56 | 0x38 | 0x94 | 0x56 | 0x80 | 0x9E | ||
¶ Beacon report
| Description | Command byte | Relative counter | Reason | Uptime in [sec] | Since last TAU [sec] | Last gathering timestamp [sec] | This beacon timestamp [sec] | |||||||||||||||||||
| Bytes | 2B | 1B | 1B | 4B (little endian) | 4B (little endian) | 4B (little endian) | 4B (little endian) | |||||||||||||||||||
| Example | 0xF0 | 0xFF | 0x0D | 0x01 | 0x04 | 0xa9 | 0x00 | 0x00 | 0x04 | 0xa9 | 0x00 | 0x00 | 0xa7 | 0x19 | 0x86 | 0x0d | 0xa3 | 0x27 | 0x86 | 0x0d | ||||||
Uptime → 0x04A90000 → 43268 s
Since last TAU → 0x04A90000 → 43268 s
Last gathering timestamp → 0xA719860D => 226892199 + epochBase = 1678491399 => To UTC => 10/03/2023
This beacon timestamp → 0xA327860D => 226895779 + epochBase = 1678494979 => To UTC => 11/03/2023
epochBase = 1451602800-3600
The rest is data
| Description | Script version (1.1) | NB report next | Signal (26) | Battery voltage [mV] (3561 = 3.5V) | |||||
| Bytes | 3B (ASCII) | 1B | 1B | 2B (little endian) | |||||
| Example | 0x31 | 0x2E | 0x31 | 0x00 | 0x56 | 0xE9 | 0x0D | ||
|
Description |
IMEI (868333035037122) |
||||||||||||||||||||
| Bytes | 16B (ASCII) | ||||||||||||||||||||
| Example | 0x38 | 0x36 | 0x38 | 0x33 | 0x33 | 0x33 | 0x30 | 0x33 | 0x35 | 0x30 | 0x33 | 0x37 | 0x31 | 0x32 | 0x32 | 0x00 | |||||
¶ Send once end of gathering
| Description | Command byte | # of meters found (1) | Relative counter (10) | ||||
| Bytes | 2B (ASCII) | 1B | 1B | ||||
| Example | 0xF0 | 0xF9 | 0x01 | 0x00 | 0x0B | ||
¶ Payloads sent by the server = DOWNLINK
The server side is used for the remote configuration of the converters within installations. By using the server-side for configuration over NB-IoT you can deploy out-of-the-box converters and configure them one by one after the deployment. If needed, please reach out to us for the option of using our server-side API tool.
¶ New filter configuration
| Description | Command byte | Filter IDs | |||||||||||
| Bytes | 1B | N x 4B | |||||||||||
| Example | 0x01 | 0x90 | 0x82 | 0xCB | 0x01 | 0x74 | 0x82 | 0xCB | 0x01 | 0x75 | 0x82 | 0xCB | 0x01 |
The byte order of filter IDs (mentioned in the example above) starts with LSB and ends with MSB (little endian), therefore IDs look like this:
ID1 = 01 CB 82 90
ID2 = 01 CB 82 74
ID3 = 01 CB 82 75
¶ Send configuration
| Description | Command byte | Time per entry [s] |
Gather time S mode [s] |
Gather time T/C mode [s] |
Wake up period [Days] |
Wake up period [Hours] |
Wake up period [minutes] |
Gather time M mode [s] |
| Bytes | 1B | 1B | 1B | 1B | 1B | 1B | 1B | 1B |
| Example | 0x02 | 0x78 | 0x00 | 0x00 | 0x00 | 0x00 | 0x0F | 0x1E |
Time per entry - the time in seconds for how long we scan for 1 ID. The total scan time is being calculated as N*Time per entry, where “N” is the number of IDs in the filter. If we have 15 IDs, the total scan time will be calculated as the 15*Time per entry.
Gather time S, T, and M mode - time in seconds defining for how long the device receives the data in S, T, or M mode (timeout)
¶ Request configuration
| Description | Command byte | ||||
| Bytes | 1B | ||||
| Example | 0x03 | ||||
Similar payload is to request IDs, status and reset
Request configuration - converter answers with 0xFE frame (Configuration acknowledgment)
Request IDs - converter answers with 0xFD frame (W M-Bus IDs acknowledgment)
Request status - converter answers with 0xFA frame (Status report)
Request reset - converter performs reset (used for example to perform remote FW update)
¶ Request scan
| Description | Command byte | Scan minutes | Mode | ||||||||
| Bytes | 1B | 1B | 1B | ||||||||
| Example | 0x04 | 0x02 | 0xXX | ||||||||
Modes:
0x00 = S Mode
0x01 = T/C Mode
0x02 = M Mode - proprietary protocol. Reach out to us for the specification and closer information.
In case of using more than one mode, send the frame as follows:
| Description | Command byte | Scan minutes S mode |
S Mode | Scan minutes T/C mode |
T/C Mode | Scan minutes M mode |
M Mode | |||||||||||||||||||
| Example | 0x04 | 0x05 | 0x00 | 0x05 | 0x01 | 0x05 | 0x02 | |||||||||||||||||||
If you don't need any of the modes mentioned in the table above, for example, T mode, remove its corresponding bytes[scan minutes (0x05) and T mode (0x01)].
Device response is with frame 0xF8 (Scanned unit with mode report).
¶ Configuration
The scheme below represents not only the initial configuration procedure but configuration in general where there is no, or old configuration within the converter. If the converter has no filter of IDs set it will automatically send an uplink every 1 hour (0xFF) in order to open a receive window for possible downlink.
¶ Scan (receive command and scan)
The unit does scan for surrounding WMBUS IDs and sends its device ID, RSSI, and manufacturer ID to the server/backend. This feature is being used in situations where you want to do an automatic allocation based on the RSSI or if you want to sniff for surrounding WMBUS IDs in general.
¶ Example of the possible resulting JSON representation
Scanned unit with mode report
{
"unit": "unit",
"wmbusId": "01673206",
"deviceType": 128,
"manufacturerId": "0x5068",
"mode": "T/C",
"owner": "owner",
"rssi": -96,
"timestamp": "timestamp"
},