Overview

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

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.

Device registration via uplink message

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

The Loriot devices can now be registered in Cumulocity IoT when uplink messages are received.

### Device creation via Loriot uplink message

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 you do 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 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 Loriot LoRa device message below, 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.

In order to be able to send downlink operations, the devices registered via uplink message must be re-registered using Cumulocity IoT (see Device registration via Cumulocity IoT), to be associated with a connection and a device type.

Device registration via Cumulocity IoT

Creation of Loriot LNS Connection in Cumulocity IoT

Before using LoRa devices with Cumulocity IoT, you must configure the Cumulocity IoT Loriot agent endpoint details in the Administration application. Click the Connectivity tab in the Settings menu to create, edit, delete or update multiple Loriot connections.

To add a new connection

When you select Connectivity for the first time, you are asked to create a connection. Click Add Connection.

Enter the following information:

Click Save. If the information you have entered is correct, the message “Connection created” appears.

To add another connection, click Add Connection and follow the steps above.

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

Enable gateway information option

To update a connection

Select the connection to be updated, make your edits, and save the connection.

If there are devices associated with the connection, an error message appears, stating “Can not update the LNS Connection with <name of LNS Connection> as it’s associated with <number of devices>. Click the link to download the file with the details of the associated devices: /service/<agent-context-path>/lns-connection/<lns-connection-name>/device”.

Update connection information

To delete a connection

Select the connection to be deleted and click Delete.

If there are devices associated with the connection, an error message appears, stating “Can not delete the LNS Connection with <name of LNS Connection> as it’s associated with <number of devices>. Click the link to download the file with the details of the associated devices: /service/<agent-context-path>/lns-connection/<lns-connection-name>/device”.

Delete connection

Loriot device registration

To register a Loriot device in Cumulocity IoT navigate to Devices > Registration in the Device management application, click Register device at the top right and select Single device registration > LORIOT LoRa from the dropdown.

Register devices

Info
If Loriot is not one of the available options, your tenant is not subscribed to the relevant applications, see information at the top.

In the next window, fill in the required information:

Register devices

Click Register to submit the device registration request and create the device.

You can verify that the device is connected by incoming events. Click on a device and open its Events tab. All events related to this device are listed.

For more information on viewing and managing your connected devices, also refer to Device management in the User guide.

In order to migrate the device from one LNS connection to another, the device must be re-registered:

  1. Navigate to the LPWAN tab of the Device.
  2. Click the Provider connection dropdown.
  3. A prompt will appear stating that in order to migrate the device from one LNS connection to another, you must re-register the device. Click the Re-Register button.
  4. You are directed to the device registration page where you can perform the re-registration following the steps above and selecting the desired LNS connection.

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

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.

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.

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.

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

Sending operations

If a Loriot device supports hexadecimal commands, you can send them using shell operations. Notice that these commands are not serial monitor commands. In order to send an operation, navigate to the device you want to send an operation to in the Device management application under All devices. Switch to the Shell tab.

In the following screenshot you can find some examples of a device protocol’s predefined commands and their format:

Predefined shell commands

Enter the shell command or view/edit the predefined command in the Command field.

If you enter the command without defining a port, it will be sent to the default target port (that is, port 1) of the device. If you enter the command and define a port (format “command:port”), it will be sent to the specified target port instead of the default port.

Port configuration

Click Execute. The operation will be sent to the device. The timing depends on Loriot platform.

The status of the operation is set to SUCCESSFUL when the operation has successfully been sent to the Loriot platform. The status of the operation is set to FAILED when a problem occurred with the validation of the command or after the operation has been sent to the Loriot platform.

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 a device protocol refer to the section Assign the Loriot LoRa device protocol.