Loriot LoRa

Overview

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

• Configure the Loriot agent endpoint in LORIOT Network Server using Cumulocity IoT data forwarder.
• Assign a device protocol for the LoRa device for payload processing.
• Decode upstream payload packets using a web-based user interface.
• Post-process raw device data through Cumulocity IoT events.
• Make use of existing Cumulocity IoT features with LoRa devices, for example: connectivity monitoring, device management, data visualization with dashboards, real-time analytics and more.

Info: 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.

The following sections describe how to:

• Configure Loriot agent endpoint credentials in LORIOT Network Server.
• Assign the Loriot admin role to the user in Cumulocity IoT.
• Register devices and visualize Loriot payload using Cumulocity IoT.
• Create device protocols for all devices.
• Set device protocol for processing the Loriot LoRa device payload for creating measurements or events in Cumulocity IoT.
• Troubleshoot for warning messages.

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 need to 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.

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

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

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”.

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.

If a device protocol has been changed after being associated to a device, the reflection of the change can take up to 10 minutes because of the refresh mechanism of the Loriot server-side agent.

Info: 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.

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:

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:

• FPort: if the message type can be determined by looking at the FPort parameter of a message.
• Payload: if the message type can be determined by looking at the subset of the message payload itself.

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

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”.

Click Add value to create the value configuration.

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

New value window part 1

New value window part 2

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 (i.e. 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”.

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 (i.e. start bit = “16”) and is 1 byte long (i.e. number of bits = “8”).

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:

• Multiplier: This value is multiplied with the value extracted from the Value selection. It can be decimal, negative and positive. By default it is set to 1.
• Offset: This value defines the offset that is added or subtracted. It can be decimal, negative and positive. By default it is set to 0.
• Unit (optional): A unit can be defined which is saved together with the value (e.g. temperature unit “C” for degree Celsius).

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

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

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

• Signed - if the value is a signed number.
• Packed decimal - if the value is BCD encoded.

Under Functionalities, specify how this device protocol should behave:

• Send measurement: Creates a measurement with the decoded value.
• Raise alarm: Creates an alarm if the value is not equal to zero.
• Send event: Creates an event with the decoded value.
• Update managed object: Updates a fragment in a managed object with the decoded value.

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.

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

New value window part 2

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

New value window, Latitude

This will be the result:

Assign the Loriot LoRa device protocol

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

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

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.

Info: You need to 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.

Troubleshooting

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 device protocol please refer the section Set device protocol