...

Payload formats

The Modbus Bridge sends two different kinds of messages over three different LoRaWAN ports:

Uplink Messages

Status message (Port 1)

The Modbus Bridge sends a status messages report on the health of the device itself. This messages are sent along when the device is sending data packages with a maximum of one status message per day.

Status messages are transmitted on port 1 and have a fixed length of 16 bytes.

^‡ Since version 1.3.0.

Data messages - verbose format (Port 3, PlFmt=1)

Data messages contain responses to Modbus Commands received by the Bridge. The Bridge supports multiple Payload formats for different use cases. The format is selected by the configuration parameter PlFmt:

• 1: Verbose payload format (port 3)

The verbose payload format (PlFmt=1) is the standard setting of the Bridge. It is designed to be very versatile (it uploads the complete Response sent by the Slave Devices, so reading registers as well as writing registers are both supported). It contains all information you need to know the register and the slave device your data is coming from. You do not need to know the exact configuration of your devices in your backend to be able to parse the data. This is convenient when you have man Modbus Bridges with different configuration in the field. This payload format is also good in communicating error conditions in case the executed Modbus Commands fail. The trade off is overhead in the transmission. If you need to get a lot of data uploaded often, this could be a problem for you with the limited LoRaWAN bandwidth. If this is a problem for your use case, you should take a look at the compact data formats.

Data messages using the verbose payload format are uploaded on port 3. Every message starts with a 5 byte timestamp (UNIX timestamp as big endian int40, see timestamps in our LoRaWAN devices) for more information). The timestamp is followed by one or more responses of varying length.

Each of the responses starts with a single byte (uint8) indicating the length of its payload (len) followed by that many bytes of payload. The payload consists of the raw Modbus response as sent by the Slave Device followed by 3 additional bytes: the first register/coil as uint16 (big endian) and the number of registers/coils as uint8 taken from the executed command. The following tables visualise the message structure. See the Examples Section for some sample data messages explained down to the individual bytes. We also provide a Reference Decoder in JavaScript that can read the format.

The timestamp in the message is the wakeup time when the device was activated by the cron expression in MbCron (using the devices internal clock), so all Uplinks from a single activation will have the same Timestamp. The Modbus Response in the message in addition with the start register/coil and the register/coil count makes it possible to know which registers/coils where exactly read/written, what kind they were, and the address of the device. For Modbus Commands that do not have a register/coil count (like function 5, forcing a single coil), or for those that do not contain a start register/coil (e.g. funtion 7, reading exception status), the contents of the additional fields start register and/or count are undefined. The payload format used only a single byte for the count value, so if you are reading/writing more than 255 coils, the higher byte will be cut off.

The Bridge puts as many responses as in one message as possible (without changing the order of responses and respecting the maximal message size of the current Spreading Factor). If the responses do not fit into a single message it will upload as many messages as needed. When a single response is too long to fit in a message, the response will be split up over multiple messages and will need to be reassembled in the backend. See Split Messages for instructions on how to do that and how to prevent splitting.

Structure of a message on port 3:

Bytes  | 0 . 1 . 2 . 3 . 4 | 5 ...      | ...        | ... | ...        |
       +-------------------+------------+------------+-----+------------+
Part   | timestamp         | response 1 | response 2 | ... | response n |

Structure of a response part on port 3:

Bytes  | 0   | 1 .. len-3      | len-2 . len-1  | len   |
       +-----+-----------------+----------------+-------+
Field  | len | Modbus response | start register | count |

Response to Downlink (Port 4)

A Downlink Modbus Command can be executed on Downlink Port 4. The answer has the verbose payload format like described above on port 3.

The Timestamp in Port 4 Uplinks is the time when the Downlink containing the Command was received (according to the devices internal clock).

For details about the downlink see below.

Split messages (Port 5)

If a single Modbus Response does not fit into a LoRaWAN uplink, due to the length restriction for the current Spreading Factor, the message is split up into multiple Uplinks. The first part will be sent on Port 3 (for cron triggered reads) or on Port 4 (for reads triggered by downlink). The remaining Bytes will be sent in the following uplinks on Port 5 in as many Uplinks as needed. You can know that an Uplink is split, when the length information (Byte 0 in the response part) is longer than the data following it. The payload from Port 5 must be appended to the last uplink received on either Port 3 or 4 in your application server, before you can parse the message. Check the frame counter to make sure you receive all parts. For very long responses and high Spreading Factors, splits over up to 6 messages are possible.

Split messages will only ever contain a single Modbus Response. If multiple Responses are transmitted, they will be put in separat Port 3 or Port 4 Uplinks.

You can prevent splitting of messages completly, if you make sure your Responses will never be longer than 42 Bytes (or longer if you reduce the Spreading Factor). You can also change to using the Compact Payload Format to avoid Splitting.

The Examples section contains an illustration of a split up Response.

Compact Payload Format (Port 20-59, PlFmt=4&5)

The Modbus Bridge provides an alternative Payload Format for uplinks that uses the limited bandwidth more efficiently by only sending data. This requires a dedicated parser on the network server of application server that has knowledge of the device's configuration. The configuration can be requested from devices in the field with our Remote Configuration. Be aware that Error Conditions cannot be communicated as well in this format.

If you have problems writing a dedicated parser, please contact Lobaro, we can provide you with an offer for writing it for you.

When using the compact format, all Modbus Command from MbCmd is executed in order. Only the payload is taken from the responses, as it is sent by the Modbus Slaves. As many responses as fit in a single upload are connectated and send on Port 20. The next responses connectated are send on Port 21 and so forth, up to port 59 (so there can be up to 40 different uplinks). The Uplinks are prefixed with a short Message Header. When a Modbus Command fails to execute, an Error Indicator is set and the Bytes for that command are set to 0xff.

On booting, the device prints the complete Payload Format in the Log, so it is relatively easy to write a parser with that information (only for Payload Formats 4 and 5).

There are 4 ConfigParameters that influence the format: PlFmt, PlMax, PlId, and of course MbCmd.

PlFmt=5 sends a Message Header of 1 byte, containing an error indicator (highest bit) and the value given in PlId (lowest 7 bits).
PlFmt=4 sends a Message Header of 6 byte, consiting of the same byte as in PlFmt=5 followed by a 5 Byte timestamp (int40 BE Unix Timestamp).

PlId is a numeric value 0-127 that is simply uploaded with each Uplink. This can be used for advanced setups where you have multiple different configurations for a big number of devices, so that the parser knows, what configuration to use.

PlMax limits the number of Bytes that will be used per Uplink (including the Message Header of 1 or 6 bytes). This an advanced parameter that can be used to optimise distribution of data over the Uplink messages. This value is limited by the LoRaWAN restrictions and cannot be set higher than possible for the configurated Spreading Factor (ConfigParameter SF). For the default SF of 12 it is limited to 51 Bytes. See Spreading Factor in our LoRaWAN background article for all numbers. Be aware, that selecting a lower Spreading Factor will decrease the range your device can communicate via LoRaWAN drastically. No single ModbusCommand must create a Payload that does not fit into this limit (after also including the Message Header).

The Timestamp contains the time the device wakes up by the cron (according to the internal clock). So all Uplinks from the same activation will have the same Timestamp and are easy to associate.

Remote Config (Port 128-131)

When Remote Configuration is enabled, you can send Downlinks on Port 128 to read or set Config Parameters and execute commands like Reboot. Responses to those Downlinks are set on port 128 (or 129-131 if they are too long for a single Uplink).

CE Declaration of Conformity

...