Loriot LoRa


Cumulocity IoT can interface with LORIOT Network Server through the Loriot agent microservice. You can:

The Loriot agent automatically creates a LoRa device in the Cumulocity IoT platform if it does not exist so explicit registration is not required.

The following illustration gives an overview of the Cumulocity IoT Loriot LoRa integration.

Cumulocity IoT Loriot LoRa integration

The following sections describe how to:

Moreover, check out

Note that your subscription needs to include this feature to be able to use it. If you do not see the functionality described in this document, please contact product support.

Configuring the Loriot agent endpoint credentials

Before using LoRa devices with Cumulocity IoT, you must configure the Cumulocity IoT Loriot agent endpoint details in LORIOT Network Server.

Configuring the Loriot endpoint using Basic authentication

In LORIOT Network Server you can create multiple applications. Each application allows you to configure LoRa devices.

To specify the Loriot agent endpoint with user credentials, navigate to one of the applications in your LORIOT Network Server account and select Output in the Application menu in the navigator.

LORIOT Network Server forwards the LoRa device messages to the external applications using different connectors which are available in the Output section.

Output page with https forwarder

Use Cumulocity IoT data forwarder for configuring the Loriot endpoint using Basic authentication.

Setting endpoint credentials

Always keep the Gateway Information option enabled because the Loriot agent only processes “gw” (gateway information) messages.

Enable gateway information option

Assigning the Loriot admin role permission

In the Cumulocity IoT platform, assign the Loriot admin role permission to the user configured in LORIOT Network Server.

In the Administration application, click Roles in the navigator and select the ADMIN checkbox for “Loriot”.

Set loriot admin role

Registering Loriot LoRa devices

While processing the Loriot LoRa device request, the Loriot agent automatically creates the device in the Cumulocity IoT platform, if it does not yet exist. This means that the user does not need to register the Loriot LoRa device explicitly.

LORIOT Network Server forwards two types of messages to the Loriot agent: “rx” (uplink message) and “gw” (gateway information).

The Loriot LoRa agent only processes “gw” messages to avoid duplicate measurements or events in Cumulocity IoT, because most of the information matches with “gw” message whereas “gw” message also carries all gateway information.

You must enable the “gw” message option on LORIOT Network Server while connecting to the Loriot LoRa agent, see Configuring the Loriot agent endpoint credentials.

In the below Loriot LoRa device message gws represents a list of gateways involved in the network.

    "cmd"  : "gw",
    "EUI"  : "0102030405060708",
    "ts"   : 1470850675433,
    "ack"  : false,
    "fcnt" : 1,
    "port" : 1,
    "data" : "0102AABB",
    "freq" : 868500000,
    "dr"   : "SF12 BW125 4/5",
    "gws"  : [
            "rssi"  : -130,
            "snr"   : 1.2,
            "ts"    : 43424140,
            "gweui" : "1122334455667788.0",
            "lat"   : 47.284687,
            "lon"   :  8.565746

The Loriot Lora agent picks gw with the oldest timestamp for processing. The Loriot LoRa agent maps the rssi value to the standard Cumulocity IoT SignalStrength object and updates the device managed object with the lat and lon values.

Creating device protocols

To process data from LoRa devices, Cumulocity IoT needs to understand the payload format of the devices. Mapping payload data to Cumulocity IoT data can be done by creating a LoRa device protocol.

During the device registration, you can associate this device protocol. The received uplink message for this device with a hexadecimal payload will then be mapped to the ones you have configured in your device protocol.

Device protocol mapping only supports decoding for fixed byte positions based on the message type. The length for the device payload parts, which is set in the Number of bits field, can be maximum 32 bits (4 bytes).

In order to create a device protocol, navigate to the Device Management application and select Device protocols in the Device types menu in the navigator. You can either import an existing device protocol or create a new one.

Importing a predefined device protocol

  1. In the Device protocols page, click Import.
  2. Select the predefined device type, for example “LoRaWAN Demonstrator” or upload from a file.
  3. Click Import.

Import device protocol

Alternatively, you may also load the device protocol from a file and import it.

Creating a new device protocol

In the Device protocols page, click New device protocol in the top menu bar. The following window will open:

Create new LoRa protocol

Select LoRa as the device protocol type, provide a name for it and click Create.

Under Message types, specify the message types. LoRa devices can send messages of different types with different encodings per type.

Select the way the message type is encoded in the Source dropdown box:

In the following example payload structure, the first byte indicates the message type source (as highlighted).

Example payload: message type source

In the user interface you can enter this type of message type source information as follows: In the Start bit field, indicate where the message type information starts in the payload and in the Number of bits field, indicate how long this information is, for example start bit = “0” and number of bits = “8”.

LoRa protocol payload

Click Add value to create the value configuration.

LoRa protocol add value

In the upcoming window, configure the relevant values as shown in this example.

New value window part 1 LoRa protocol add new value

New value window part 2 LoRa protocol add new value

The value configuration maps the value in the payload of a message type to the Cumulocity IoT data.

Under Message type, configure the Message ID according to your device message specification and map it to the Cumulocity IoT data. The message ID is the numeric value identifying the message type. It will be matched with the message ID found in the source specified on the device protocol main page (that is, Payload or FPort). The message ID needs to be entered in decimal numbers (not hex).

In this example payload structure the message ID is “1”.

Example payload: message type source

LoRa bits

Under General, specify a name for the value and the category under which it will be displayed in the values list. The associated name for this value will be displayed under the Display category given.

Under Value selection, define from where the value should be extracted. In order to do so, indicate where the value information starts in the Start bit field and how long this information is in the Number of bits field. The maximum value for the number of bits is 32 bits (4 bytes).

In this example the “Channel 1 Type” information starts in byte 2 (that means, start bit = “16”) and is 1 byte long (that means, number of bits = “8”).

Example payload: value selection

LoRa bits

The hexadecimal value is converted to a decimal number and afterwards a “value normalisation” is applied.

Under Value normalisation define how the raw value should be transformed before being stored in the platform and enter the appropriate values for:

For detailed information on how to decode the payload, refer to the documentation of the device.

“Little endian” support to decode the payload has been added.

Under Options, select one of the following options, if required:

Under Functionalities, specify how this device protocol should behave:

You can also have a nested structure with several values within a measurement, event or managed object fragment. In case of a measurement all the properties of the same type will be merged to create a nested structure. In case of an event or a managed object all the properties with the same fragment are merged to create a nested structure. Also refer to the example of a nested structure for a “Position” device protocol below.

Click OK to add the values to your device protocol.

Value configurations of created device protocol

After clicking Save, your device protocol is created with the values you defined.

Example with single property

The following image shows an example for a message which sends a measurement when the battery level changes.

New value window part 1 Battery level changes example

New value window part 2

Battery level changes example

Example with nested structure

The following image shows an example of a nested structure for a device protocol reporting the current position of a GPS device. The display category is named “Position” and contains values for longitude and latitude.

The message ID should be the same for all the values. Enter the rest of the parameters according to the instructions above. Enter “c8y_Position” in the Managed object fragment field and create a new value for each: longitude and latitude.

New value window, Longitude

Value creation: Longitude-nested

New value window, Latitude

Value creation: Latitude-nested

This will be the result:

Value configuration in detail: nested structure

Using Custom decoding

The Loriot agent also supports the decoding functionality by plugging in the custom microservice. Refer to LPWAN custom codec for further details.

Assign the Loriot LoRa device protocol

Once the Loriot LoRa device is available in the Cumulocity IoT platform, you must assign a device protocol from the LPWAN tab.

Assign device protocol

Select the respective protocol from the dropdown list and click Apply. If successfully applied, the message “Device protocol set” will show up.


Device registration

No LoRa device registered in Cumulocity IoT after configuring the Loriot agent endpoint in the LORIOT Network Server account.

Check whether the user configured in LORIOT Network Server has assigned the Loriot admin role since the Loriot agent verifies if the user has appropriate permissions.

Make sure that the Gateway Information is enabled in LORIOT Network Server since the Loriot agent only processes “gw” messages.

Device type error warning

The warning message “Device type error” shows up in the log if no device protocol has been assigned to the device. To assign a device protocol refer to the section Assign the Loriot LoRa device protocol.