...

Table of Content

Overview

The Lobaro Hybrid Modbus Gateway is a simple to use, cost and energy efficient device that reads, caches and forwards data via Modbus from any number of Modbus enabled devices into the Internet.

...

The Modbus Gateway supports reading of all four object types that can be provided by Modbus slave devices: Coil, Discrete Input, Input Register, and Holding Register. It also supports writing values to all writable objects: Coils and Holding Registers. Multiple different slave devices on the Bus can be accessed individually by a single Gateway device, even if the slave devices have a different Modbus configuration. Reading intervals and register definitions can be configured very flexibly to suit individual requirements.

Quick start guide

For details about each Steps please refer to the related detailed sections of the Manual below.

• Make sure the SIM card is inserted correctly when using NB-IoT or LTE-CatM1.
• Connect the Modbus Gateway to your Modbus Slave Devices
  • Via RS485 connector using a twisted pair cable: A to A, B to B, and GND to GND (GND is not strictly necessary but enhances the connection. Not all slave devices supply a GND connector).
  • Via ETH connector for Modbus TCP using a RJ45 LAN cable(externally powered variants only).
• Connect the Modbus Bridge to a computer using the Lobaro Configuration Adapter and the Lobaro Maintenance Tool.
• Connect power to the device - powering with the configuration adapter does not work.
• Make sure the configuration is correct to connect to the Internet (depends on you connection method: Mobile, LoRaWAN or LAN.
• Make sure the configuration is correct to read out your desired Modbus device (e.g. ASCII/RTU, Baud, Data Length, Stop Bits, Parity and Modbus Command).
• Optionally: Switch to the Log tab of the Lobaro Tool to see if the device is connecting and working as expected.
• Go to The Lobaro Platform and log into your account.
• Go to "Devices" and select your "Hybrid Modbus Gateway".
• If you have several Gateways: the "Address" is printed on the device's case as "DevEUI".
• You should see all Uplinks the Gateway collected sent far. Next step is to configure your individual Device Type to display you slaves data or forward data to your own IT.

Supported Devices

The Lobaro Modbus Gateway works with all devices that act as a Modbus Client using RTU, ASCII (or, in a future release TCP). Some devices that have been used successfully with the Gateways are:

Modbus Introduction

For an overview about the Modbus protocol please refer to our documentation page about Modbus.

...

Setting up the device

Interfaces

Connections as on the label:

...

Power Supply

• Power supply via external mains adapter with 12 - 24 Volt DC
• Power output must be at least 2W and maximum 100W.

Radio (LoRa, FSK, NB-IoT, LTE Cat-M1)

...

Properties of compatible SMA Antennas: 

...

RESET-Button

• Press the RESET Button to restart the device
• The RESET Button can be pressed through a small hole in the cover (e.g. with a paper clip). The position is marked with a ring on the label.

Config Port

• The config port can only be reached when the cover is removed
• The configuration port is compatible with our 6-pin Lobaro USB Configuration Adapter (Article No. 8000005).
• A free to use configuration tool can be downloaded from the Lobaro website. 

LED

• Status information is visualized via the RGB LED

Mobile operator and LTE band configuration

If you are using a different mobile operator than pre-configured, you should change the mobile operator code set in the Config Parameters Operator and (LTE) Band Operator codes are 5 digit codes that indicate country and operator.

Configuration

The device is shipped with default configuration parameters. The configuration can be changed via the 6-pin config port using the Lobaro USB Configuration Adapter.

...

Networking Parameters (NB-IoT / LoRaWAN)

Name#LoRaWAN-RemoteConfiguration	Description	Default Value	Value Description & Examples
WAN	Radio technology used for connection to backend	lte	lte: use either cellular NB-IoT or LTE-M nbiot: use cellular NB-IoT ltem: use cellular LTE-M lorawan: use LoRaWAN with OTAA lorawan-abp: use LoRaWAN with ABP lan: use LAN/Ethernet (not supported, yet)
Host	Hostname / IP of the Lobaro Platform API Not used for LoRaWAN uplink	94.130.20.37	94.130.20.37 = platform.lobaro.com  DNS is not supported yet
Port	Port number of the Lobaro Platform API Not used for LoRaWAN uplink	5683

NB-IoT Parameters (WAN = "lte", "nbiot", "ltem")

The LTE functionality is enabled if the WAN parameter is set to lte, nbiot, or ltem. Using this mode requires an appropriate SIM-Card to be inserted.

LoRaWAN Parameters (WAN = "lorawan", "lorawan-abp")

...

OTAA - Over the Air Activation

The preferred method to use LoRaWAN is Over The Air Activation (OTAA). When WAN="lorawan" the device uses the values to perform an OTAA Join with the LoRaWAN Network Server. Make sure the values for DevEUI, JoinEUI, and AppKey match.

...

Each Device will be configured with a unique JoinEUI and AppKey that are generated using a cryptographic hashing algorithm. Those values will seem random and are very likely to be unique for each device. These values are known to Lobaro but will not be made public. You can change the AppKey if you prefere to have Keys that are known only to you. Be sure to use a good random source when generating keys.

ABP - Activation by personalisation

Our devices support activation by personalisation (ABP) when WAN="lorawan-abp". This mode is useful for devices that have a bad reception. You will have to synchronise session keys by hand between the device and your Network Server when using ABP.

...

The Values will be printed out in the Log after boot, so you can copy them to the configuration in your Network Server. Do change the DevAddr, alter the DevEUI value in the configuration. To create a different pair of session keys, change the value of AppKey in the configuration. Best practise is, to change it to randomly generated bytes coming from a good random source. The generated Session Keys will be deterministic for a given value of AppKey, even if used on different devices.

LAN Parameters (WAN = "lan")

Connection via LAN/Ethernet is not supported, yet.

Modbus related Parameters

...

MbCmd        = "<Entry1>;<Entry2>;...;<Entry32>"
Entry        = "<Cron>:<MbParm>:<Command1>,<Command2>,...,<CommandN>"
MbParm       = "<Protocol>,<Baud>,<SymbolCfg>"
Protocol     = "R" for Modbus RTC, "A" for Modbus ASCII
Baud         = Baud rate, any of: 2400, 4800, 9600, 19200, 38400, 57600, 115200
SymbolConfig = Token string defining Data Length, Parity, and Stop Bits. Any of: "7E1", "7E2", "8N1", "8N2"
Command      = "<bytes to be sent in hex without checksum>"

Examples

Example A:
"0 0/5 * * * *:R,9600,8N1:010300000003"
  Entry 1:
    Cron:   "0 0/5 * * * *": Execute entry every 5 minutes, on minutes 0, 5, 10, 15, ..., 55
    Config: "R,9600,8N1": Use Modbus RTU on 9600 Baud, Datalength: 8, Parity: None, 1 stop bit
    Commands:
      "010300000003": Read 3 holding registers of Slave 1, starting at register 0

Example B:
"0 * * * * *:A,9600,7E1:0e0400100004,0f400100004;0 0 * * * *:A,9600,7E1:0e0400200020"
  Entry 1:
    Cron:   "0 * * * * *": Execute entry every full minute
    Config: "A,9600,7E1": Use Modbus ASCII on 9600 Baud, Datalength:7, Parity: Even, 1 stop bit
    Commands:
      "0e0400100004": Read 4 input registers of Slave 14, starting at register 16
      "0f0400100004": Read 4 input registers of Slave 15, starting at register 16 
  Entry 2:
    Cron:   "0 0 * * * *": Execute entry every full hour
    Config: "A,9600,7E1": Use Modbus ASCII on 9600 Baud, Datalength:7, Parity: Even, 1 stop bit
      "0e040a800020": Read 32 input registers of Slave 14, starting at register 2688

Modes of operation (work cycle)

This chapter explains how the device starts and works to collect and upload data.

Startup process

The starting process of the device is linear and executed the following steps in the order given here. The startup is triggered on power on or after a reset was triggered; this can happen over the reset button, by using the Lobaro tool over the config adapter, by sending a reboot command via Downlink, of if a fatal error occurs during operation of the device.

• On power on (or after a reset), the device will start by verifying the signature of the installed firmware. It will only continue the boot process if the signature is valid.
• The device will then activate the Arm TrustZone of its central processor, to prepare an isolated environment for the actual firmware to run. This activates hardware security mechanisms that protect the device from a wide range of errors and manipulations while it is running.
• Only then, the application program is started, having restricted access to the hardware.
• The application reads and outputs the configuration parameters programmed into it and verifies the configuration does not contain any obvious errors (like invalid syntax or impossible value combinations). If any fatal errors exist, the device will output information about it in the Log and then reboot, so that you spot invalid configurations directly when you set them.
• At this point the RGB-LED starts to continuously output the state of the Modbus connection and the connection to the backend.
• The device will try and execute every Modbus command from every entry in the configuration parameter MbCmd, using the Modbus configuration of the entry (writing operations are skipped to avoid side effects). This allows you to check your Modbus configuration and the connection to the slave devices early on boot and even without a config adapter attached. The device will continue execution, even if the Modbus Commands fail, so that you can check the connection to the backend even when not connected to the Modbus slaves.
• After testing Modbus, the device will try to connect to the network for connection to the backend. The exact action will depend on your configuration:
  • For NB-IoT or LTE-M the Gateway will activate its Modem and try to attach to the mobile provider. If that succeeds, it will try to connect to the backend configured (normally an instance of the Lobaro Platform). If that succeeds, the device will upload some information about itself to the backend (including its configuration) and than synchronise its internal clock over the connection. Only if all this succeeds, the device will move on.
  • For LoRaWAN with OTAA, the device will perform an OTAA Join operation with the LoRaWAN Network Server. If that succeeds, the device will upload a Status Message that will also be used to synchronise its internal clock with the network. Only if that succeeds, the device will move on. On failure, the device will retry with increasing timeouts to perform the join operation and time sync, until it succeeds.
  • For LoRaWAN with ABP there is no explicit joining operation, as the session must already exist between Network Server and Device. It simply uploads a Status Message that will also be used to synchronise the internal clock. If the synching fails multiple times, the device will skip synchronisation and just move on to start normal operations. Be aware that this can lead to the Device operating with a clock that does not match real time. The Modbus Commands will be executed according to that clock, which will most likely not be consistent with what you expect. This exception is introduced on purpose, as ABP is meant to make the device usable in locations, where there is poor Downlink reception from the Network, where an OTAA Join cannot be performed, but Uplink messages still might be coming through to the Network. The device will continue to try and synchronise its clock every day and might succeed at some point in the future. The changing of the clock will be compensated as well as possible, but the exact times when commands are executed is most likely to change at that point.
• When the connection to the backend has been established (this is not certain to have succeeded when using LoRaWAN ABP), the device will start its internal scheduler and will from this moment on be running in normal operation mode.

Normal operation

The actions executed by the device during normal operation are controlled by a scheduler that executes a list of jobs whenever it is their time to run. Only a single job will be executed at any time, so if a job is running for some time, other jobs will be executed delayed (but the execution will not be skipped). Each entry you add to the MbCmd config parameter will have its own job in the scheduler. The Cron Expression of the entry will control, how often and when the job will be executed. In addition to that there will be a Status job which runs once every day and triggers the upload of a status message which will also perform a clock synchronisation. When your configuration has multiple entries that are scheduled for the same time, they will be executed in the order you put them in the configuration.

...

Changing configuration or performing a firmware update will result in the Gateway rebooting. We try our best to keep our devices from ever reaching a state that makes them unreachable. A new configuration set via Downlink will be temporary until a connection to the Network can be established again. If the new configuration fails to connect to the Network, the previous configuration is restored.

Mobile data consumption

Uploading one Uplink with 400 bytes including all metadata (might be less, depending on the configuration).

...

All calculations are estimations and might vary depending on the configuration

The Lobaro Platform

The easiest way to work with the Lobaro Modbus Gateway is the Lobaro Platform. You can find it under https://platform.lobaro.com – Log in with the credentials provided by Lobaro.

Your Gateways should be listed under "Devices". If you have multiple devices in your account, you can distinguish them by the field "Address". The Address is printed on the box of the Gateway (the Address is the IMEI of the modem used by the device; that is the unique hardware address used for mobile communication).

Data messages

Data messages differ between LoRaWAN and LTE/LAN upload. While LoRaWAN messages are defined by Port and Byte pattern, LTE/LAN Uplinks are encoded as structured data (CBOR).

...

LoRaWAN Payload formats

The Modbus Bridge sends two different kinds of messages over 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.

...

^‡ 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:

...

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

Reference Decoder

This is a decoder written in JavaScript that can be used to parse the device's LoRaWAN messages. It can be used as is in The Things Network.

function readVersion(bytes) {
    if (bytes.length<3) {
        return null;
    }
    return "v" + bytes[0] + "." + bytes[1] + "." + bytes[2];
}
 
function int40_BE(bytes, idx) {
    bytes = bytes.slice(idx || 0);
    return bytes[0] << 32 |
        bytes[1] << 24 | bytes[2] << 16 | bytes[3] << 8 | bytes[4] << 0;
}
 
function int16_BE(bytes, idx) {
    bytes = bytes.slice(idx || 0);
    return bytes[0] << 8 | bytes[1] << 0;
}
 
function uint16_BE(bytes, idx) {
    bytes = bytes.slice(idx || 0);
    return bytes[0] << 8 | bytes[1] << 0;
}
 
function port1(bytes) {
    return {
        "port":1,
        "version":readVersion(bytes),
        "flags":bytes[3],
        "temp": int16_BE(bytes, 4) / 10,
        "vBat": int16_BE(bytes, 6) / 1000,
        "timestamp": int40_BE(bytes, 8),
        "operationMode": bytes[13],
        "noData": !!(bytes[3] & 0x01)
    };
}
 
function port2(bytes) {
    var regs = [];
    if (bytes.length > 5) {
        // loop through data packs
        var b = bytes.slice(5);
        while (b.length>=4) {
            var r = {
                "device":b[0],
                "register":int16_BE(b, 1),
                "count":b[3] & 0x3f,
                "error":!!(b[3]>>7),
                "data":null
            };
            var dataLen = r["count"]*2;
            if (b.length >= dataLen+4) {
                r["data"] = b.slice(4, 4 + dataLen);
            }
            regs.push(r);
            b = b.slice(4+dataLen);
        }
    }
    return {
        "port":2,
        "timestamp": int40_BE(bytes, 0),
        "registers": regs
    };
}
 
function modbusErrorString(code) {
    // Modbus exception codes
    // see https://en.wikipedia.org/wiki/Modbus#Exception_responses
    switch (code) {
        case 1:
            return "Illegal Function";
        case 2:
            return "Illegal Data Address";
        case 3:
            return "Illegal Data Value";
        case 4:
            return "Slave Device Failure";
        case 5:
            return "Acknowledge";
        case 6:
            return "Slave Device Busy";
        case 7:
            return "Negative Acknowledge";
        case 8:
            return "Memory Parity Error";
        case 10:
            return "Gateway Path Unavailable";
        case 11:
            return "Gateway Target Device Failed to Respond";
        default:
            return "Unknown error code";
    }
}
 
function parseModbusPayloadRegisters(payload) {
    if (payload.length < 1) {
        return null;
    }
    var byteCnt = payload[0];
    if (payload.length !== byteCnt + 1) {
        return null;
    }
    var vals = [];
    for (var i=0; i<byteCnt; i+=2) {
        vals.push([+payload[i+1], +payload[i+2]])
    }
    return vals;
 
}
function parseModbusResponse(raw) {
    var resp = {};
    if (raw.length >= 6) {
        var fun = raw[1] & 0xf;
        var error = !!(raw[1] & 0x80);
        var rawResp = raw.slice(0, raw.length - 3);
        resp["slave"] = raw[0];
        resp["function"] = fun;
        resp["error"] = error;
        resp["start"] = uint16_BE(raw, raw.length - 3);
        resp["cnt"] = raw[raw.length - 1];
        resp["raw"] = rawResp;
        if (error) {
            resp["errorCode"] = raw[2];
            resp["errorText"] = modbusErrorString(raw[2]);
        } else {
            resp["values"] = parseModbusPayloadRegisters(rawResp.slice(2))
            // TODO: coils
        }
    }
    return resp;
}
 
function FullResponses(bytes, port) {
    var timestamp = int40_BE(bytes);
    var pos = 5;
    var resps = [];
    while (pos < bytes.length) {
        var respLen = bytes[pos++];
        if (bytes.length >= pos + respLen) {
            var rawResponse = bytes.slice(pos, pos + respLen);
            resps.push(parseModbusResponse(rawResponse));
            pos += respLen;
        } else {
            break;
        }
    }
    return {
        "port": port,
        "timestamp" : timestamp,
        "responses": resps
    };
}
 
function bin2String(array) {
    var result = "";
    for (var i = 0; i < array.length; i++) {
        result += String.fromCharCode(array[i]);
    }
    return result;
}
 
function ConfigResponse(data) {
    var t = bin2String(data);
    return {
        "response" : t,
        "error" : (t.length === 0) || (t[0] === '!')
    }
}
 
/**
 * TTN decoder function.
 */
function Decoder(bytes, port) {
    switch (port) {
        case 1:
            // Status message:
            return port1(bytes);
        case 2:
            // not legacy format:
            return port2(bytes);
        case 3:
        case 4:
            // v1.0.0 format, full modbus responses:
            return FullResponses(bytes, port);
        case 5:
            // continuation of previous response:
            return {};
        case 6:
            // dense format with prefixed timestamp:
            return {};
        case 7:
            // dense format without timestamp:
            return {};
        case 128:
            return ConfigResponse(bytes);
    }
    return {"error":"invalid port", "port":port};
}
 
/**
 * LoRaServer decoder function.
 */
function Decode(fPort, bytes) {
    // wrap TTN Decoder:
    return Decoder(bytes, fPort);
}
function Parse(input) {
    var data = bytes(atob(input.data));
    var port = input.fPort;
    var fcnt = input.fCnt;
    var vals =  Decoder(data, port);
    vals["port"] = port;
    vals["data"] = data;
    vals["fnct"] = fcnt;
    var lastFcnt = Device.getProperty("lastFcnt");
    vals["reset"] = fcnt <= lastFcnt;
    Device.setProperty("lastFcnt", fcnt);
    return vals;
}

Compact Payload Format (Port 20, (21-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.

...

Part | HD | response 1 | response 2 | ... | response n |

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.

...

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.

...

MbCmd = '010300000003'

# Example resulting Uplink after successful readout
Up, Port 3: '005d1698fd0c0103061234567890ab000003'
 '005d1698fd' -> timestamp = 1561762045 -> 2019-06-28T22:47:25 UTC
 '0c'       -> first Response is 12 bytes long
 '0103061234567890ab000003' 12 bytes modbus response:
   '01' -> slave device with address 1
   '03' -> function 3 = read Holding Register, success
   '06' -> 6 bytes of data in Response following
   '1234567890ab' -> 6 bytes of data
   '0000' -> start reading at register 0
   '03' -> read 3 consecutive registers

# Example resulting Uplink after failing readout
Up, Port 3: '005d1698fd0601830b000003'
 '005d1698fd' -> timestamp = 1561762045 -> 2019-06-28T22:47:25 UTC
 '06'       -> first Response is 6 bytes long
 '01830b000003' 3 bytes modbus response:
   '01' -> slave device with address 1
   '83' -> function 3 with error indicator 80 = read Holding Register, failed
   '0b' -> error code 11: "Gateway Target Device Failed to Respond"
   '0000' -> start reading at register 0
   '03' -> read 3 consecutive registers

...

(Port 128 (129-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).

...

NB-IoT/LTE Payload formats

The Modbus Bridge sends different kinds of messages over different Querys ("q"):

"q": "device" (in first upload frame) Device description
"q": "config" (in second upload frame) Configuration description
"q": (still) does not exist (from the third package) normal data packages

Data Uplink Messages (part):

{
    "d": {
      "mb": [
        {
          "cmd": "AQMAFgAC",
          "rsp": "AQMEAUEYeA==",
          "time": 1660050482,
          "error": 0
        },
      ]
    },
    "i": "70b3d5e050011bb4",
    "n": 19
  }

"mb" modbus
"cmd" (command) "AQMAFgAC" is equivalent in HEX "010300160002" 
SlaveID (01) Command Read (03) Register 0016 (dec 22) Quantity 0002 (2)

"rsp" (response) "AQMEAUEYeA==" is equivalent in HEX "01030401411878"
SlaveID (01) Command Read (03) Quantity Bytes (04) ValueRegister1+2 (01 41 18 78) 
Equivalent Hex 01 41 in DEC is 321 (Example: if register 00 00 is the value for temperature/100 it represents 3,21 Grad Celsius)

"time" 1660050482 (UnixTimeStamp Tue Aug 09 2022 13:08:02 GMT+0000)
"error" 0 (no error)
"i" 70b3d5e050011bb4 (DevEUI)
"n" 19 (frame counter)

CE Declaration of Conformity

CE-LOB-GW-DINRAIL-HYB_11_01_22.pdf