# LPWAN Source: https://cumulocity.com/docs/device-integration/lpwan/ Sector: Device management & connectivity Release: Latest Description: Integrate non-IP devices through the native LoRa connectors for Loriot and Actility, the Sigfox connector, and custom LPWAN protocols. ## Introduction This section details the mechanisms for integrating non-IP devices. Cumulocity provides native connectors for three major LPWAN connectivity providers including [Loriot](https://cumulocity.com/docs/device-integration/lpwan/#loriot-lora), [Actility](https://cumulocity.com/docs/device-integration/lpwan/#actility-lora), and [Sigfox](https://cumulocity.com/docs/device-integration/lpwan/#sigfox). These connectors abstract the vendor-specific APIs required for device provisioning and data retrieval. This section documents the configuration and operation of the LPWAN agent, which performs the following core functions: - **Ingestion** - Receives uplink messages from Sigfox, Loriot, or Actility (ThingPark) backends. - **Normalization** - Decouples the connectivity provider from the device logic, allowing devices to be managed using standard Cumulocity interfaces. - **Translation** - Routes binary payloads through user-defined device protocols to extract measurements, events, and alarms. - **Downlink management** - Queues and forwards commands to the Network Server APIs for transmission to the device. ## Loriot LoRa ### Introduction {#loriot-introduction} Cumulocity can interface with the Loriot Network Server through the Loriot agent microservice. You can: * Register the device in two ways: - Create a Loriot LNS connection and register the device using Cumulocity. - Configure the Loriot agent endpoint via Loriot Network Server and register the device via uplink message. In order to be able to send downlink messages, the devices created using this method must be re-registered via Cumulocity to be associated with a connection and device type. * 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 events. * Make use of existing Cumulocity features with LoRa devices, for example: connectivity monitoring, device management, data visualization with dashboards, real-time analytics and more. The following illustration gives an overview of the Cumulocity Loriot LoRa integration. ![Cumulocity Loriot LoRa integration](https://cumulocity.com/docs/images/device-protocols/lora-loriot/loriot-cumulocity-integration.png) > **Info:** > Your subscription must include this feature to be able to use it. If you do not see the functionality described in this document please contact [product support](https://cumulocity.com/docs/additional-resources/contacting-support/). ### Device registration via uplink message {#device-registration-via-uplink-message} Before using LoRa devices with Cumulocity, you must configure the Cumulocity Loriot agent endpoint details in Loriot Network Server. #### Configuring the Loriot endpoint using basic authentication {#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](https://cumulocity.com/docs/images/device-protocols/lora-loriot/loriot-output-https-page.png) Use Cumulocity data forwarder for configuring the Loriot endpoint using basic authentication. > **Info:** > In order to send an uplink request, the user configured in the Loriot Network Server must have ADMIN permission for the "Loriot" permission type in Cumulocity. > For details, see [Assigning ADMIN permission for the Loriot](https://cumulocity.com/docs/device-integration/lpwan/#assigning-the-loriot-admin-role-permission). ![Setting endpoint credentials](https://cumulocity.com/docs/images/device-protocols/lora-loriot/loriot-endpoint-assignment.png) Always keep the **Gateway Information** option enabled because the Loriot agent only processes "gw" (gateway information) messages. ![Enable gateway information option](https://cumulocity.com/docs/images/device-protocols/lora-loriot/loriot-gateway-option-enabled.png) The Loriot devices can now be registered in Cumulocity when uplink messages are received. #### Device creation via Loriot uplink message {#device-creation-via-loriot-uplink-message} While processing the Loriot LoRa device request, the Loriot agent automatically creates the device in the Cumulocity platform, if it does not yet exist. This means that you do not have to register the Loriot LoRa device explicitly. The 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, 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 the Loriot Network Server while connecting to the Loriot LoRa agent, see [Device registration via Cumulocity](https://cumulocity.com/docs/device-integration/lpwan/#device-registration-via-the-platform). 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 `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 (see [Device registration via Cumulocity](https://cumulocity.com/docs/device-integration/lpwan/#device-registration-via-the-platform)), to be associated with a connection and a device type. ### Device registration via the Cumulocity platform {#device-registration-via-the-platform} #### Creating a Loriot LNS connection in Cumulocity {#creating-a-loriot-lns-connection-in-cumulocity} Before using LoRa devices with Cumulocity, you must configure the Cumulocity 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 {#loriot-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: - **Name** - the name of the Loriot connection being created - **Base URL** - the URL associated with the Loriot provider account - **Username** - your Loriot account username - **Password** - your Loriot account password 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](https://cumulocity.com/docs/images/device-protocols/lora-loriot/loriot-gateway-option-enabled.png) ##### To update a connection {#loriot-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 `` as it's associated with ``. Click the link to download the file with the details of the associated devices: `/service//lns-connection//device`". ![Update connection information](https://cumulocity.com/docs/images/device-protocols/lora-loriot/loriot-admin-settings-update.png) ##### To delete a connection {#loriot-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 `` as it's associated with ``. Click the link to download the file with the details of the associated devices: `/service//lns-connection//device`". ![Delete connection](https://cumulocity.com/docs/images/device-protocols/lora-loriot/loriot-admin-settings-delete.png) > **Info:** > To create, update, or delete LNS connections, you must have the Loriot ADMIN permission assigned to your user. To view the LNS connections, the Loriot READ permission is sufficient. #### Loriot device registration {#loriot-device-registration} To register a Loriot device in Cumulocity 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. > **Requirements:** > To register a device, you need WRITE or ADMIN permission for the "Inventory" permission type, or ADMIN permission for the "Loriot" permission type. ![Register devices](https://cumulocity.com/docs/images/device-protocols/lora-loriot/loriot-selection.png) > **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: - **Title** - title of the device to be registered. - **Device EUI** - this is the unique identifier for the device. It is a 16 character (8 byte) long hexadecimal number. You can find it on the device itself. - **Application EUI** - this is a global application ID in the IEEE EUI64 address space that uniquely identifies the application provider of the device. It is a 16 character (8 byte) long hexadecimal number. - **Application key** - this is an AES-128 application key specific for the device that is assigned to the device by the application owner and is responsible to encrypt. The application key is a 32 character (16 byte) long hexadecimal number. - **Connection** - lists all configured Loriot connections in the tenant. The **Application name** option (see below) is populated based on the selected Loriot connection. - **Application name** - select the appropriate application name under which the device must be registered in the Loriot provider. - **Device protocol** - select the appropriate device protocol from the dropdown list. For more information on how to create a device protocol refer to [Creating device protocols](https://cumulocity.com/docs/device-integration/lpwan/#loriot-creating-device-protocols). ![Register devices](https://cumulocity.com/docs/images/device-protocols/lora-loriot/loriot-registration.png) 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 the [Device Management application](https://cumulocity.com/docs/device-management-application/). 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 ADMIN permission for Loriot {#assigning-the-loriot-admin-role-permission} In the Cumulocity platform, assign the Loriot admin role permission to the user configured in the Loriot Network Server. In the Administration application, click **Roles** in the navigator and select the **ADMIN** checkbox for "Loriot". ![Set loriot admin role](https://cumulocity.com/docs/images/device-protocols/lora-loriot/loriot-user-admin-role.png) } ### Creating device protocols {#loriot-creating-device-protocols} To process data from LoRa devices, Cumulocity needs to understand the payload format of the devices. Mapping payload data to Cumulocity data can be done by creating a LoRa device protocol. During the [device registration](https://cumulocity.com/docs/device-integration/lpwan/#loriot-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 {#loriot-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](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-protocols-import.png) Alternatively, you may also load the device protocol from a file and import it. #### Creating a new device protocol {#loriot-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](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-protocols-new.png) 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). 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](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-protocols-payload.png) Click **Add value** to create the value configuration. ![LoRa protocol add value](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-protocols-addvalue.png) In the upcoming window, configure the relevant values as shown in this example. **New value window part 1** ![LoRa protocol add new value](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-protocols-newvalue.png) **New value window part 2** ![LoRa protocol add new value](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-protocols-newvalue2.png) The value configuration maps the value in the payload of a message type to the Cumulocity data. Under **Message type**, configure the **Message ID** according to your device message specification and map it to the Cumulocity 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 must be entered in decimal numbers (not hex). In this example payload structure the message ID is "1". Example payload: message type source ![LoRa bits](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-protocols-loraid.png) 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](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-protocols-lorabits.png) 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 (for example 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](https://cumulocity.com/docs/device-integration/lpwan/#loriot-example-with-nested-structure) 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](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-protocols-loraprotocol.png) After clicking **Save**, your device protocol is created with the values you defined. ##### Example with single property {#loriot-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](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-protocols-battery.png) **New value window part 2**

![Battery level changes example](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-protocols-battery2.png) ##### Example with nested structure {#loriot-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](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-protocols-lng.png) **New value window, Latitude** ![Value creation: Latitude-nested](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-protocols-lat.png) This will be the result: ![Value configuration in detail: nested structure](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-protocols-gpsexample.png) #### Using custom decoding {#loriot-using-custom-decoding} The Loriot agent also supports the decoding functionality by plugging in the custom microservice. Refer to [LPWAN custom protocols](https://cumulocity.com/docs/device-integration/lpwan/#lpwan-custom-protocols) for further details. ### Assigning the Loriot LoRa device protocol {#assigning-the-loriot-lora-device-protocol} Once the Loriot LoRa device is available in the Cumulocity platform, you must assign a device protocol from the **LPWAN** tab. ![Assign device protocol](https://cumulocity.com/docs/images/device-protocols/lora-loriot/loriot-device-protocol-assignment.png) Select the respective protocol from the dropdown list and click **Apply**. If successfully applied, the message "Device protocol set" will show up. ### Sending operations {#loriot-sending-operations} If the device supports sending hexadecimal commands, you can send them using shell operations. Note 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** and 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](https://cumulocity.com/docs/images/device-protocols/lora-loriot/loriot-devices-predefinedshell.png) 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](https://cumulocity.com/docs/images/device-protocols/lora-loriot/loriot-devices-port.png) Click **Execute**. The operation is sent to the device. The timing depends on the 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. ### Uplink message processing {#loriot-uplink-message-processing} On receiving an uplink message, the Cumulocity platform creates the following measurements and events, and updates the corresponding device managed object. - **Unprocessed data** - An event of type c8y_LoriotUplinkRequest is created with the unprocessed data. - **Position** - The c8y_Position fragment of the device managed object is updated to capture the latitude, longitude, altitude and accuracy information of the device. Also, an event is created with the position information. - **Spreading factor** - The c8y_SpreadingFactor fragment of the device managed object is updated to capture the spreading factor of the device. - **Signal strength** - A measurement is created with RSSI and SNR values of the device signal strength. ### Troubleshooting {#loriot-troubleshooting} #### Device registration {#loriot-device-registration} **No LoRa device registered in Cumulocity after configuring the Loriot agent endpoint in the Loriot Network Server account** The Loriot agent verifies if the user has appropriate permissions. Check whether the user configured in the Loriot Network Server has assigned the Loriot admin role. Make sure that the **Gateway Information** is enabled in the 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](https://cumulocity.com/docs/device-integration/lpwan/#assigning-the-loriot-lora-device-protocol). ## Actility LoRa ### Introduction {#actility-introduction} Cumulocity can interface with LoRa devices through Actility's ThingPark Wireless, Enterprise or Community edition. You can: * Provision and deprovision LoRa devices easily using the Cumulocity Device Management application. No interaction in the ThingPark user interface is required. * Decode upstream payload packets using a web-based user interface. * Debug and postprocess raw device data through Cumulocity events. * Send downstream data to the device using Cumulocity operations. * Make use of existing Cumulocity features with LoRa devices, for example, connectivity monitoring, device management, data visualization with dashboards, real-time analytics and more. The following illustration gives an overview of the Cumulocity Actility LoRa integration. ![Cumulocity Actility LoRa integration](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-cumulocity-integration.png) > **Info:** > Your subscription must include this feature. If you do not see the functionality described in this document please contact [product support](https://cumulocity.com/docs/additional-resources/contacting-support/). ### Configuring multiple ThingPark account connections {#configuring-multiple-thingpark-account-connections} Before using LoRa devices with Cumulocity, you must configure your ThingPark account details in the Administration application. #### To add a new connection {#actility-to-add-a-new-connection} Click the **Connectivity** tab in the **Settings** menu to create, edit, delete or update multiple Actility connections. If you select **Connectivity** for the first time, you are asked to create a connection. Click **Add Connection**. Enter the following information: | Setting name | Notes | |--------------|--------| | Name | The name of the Actility connection being created. | | Description | The description of the Actility connection being created. | | Actility ThingPark URL | Base URL of the corresponding Actility DX API being used. | | Profile ID | Your ThingPark account profile identifier. | | Application server ID | Application server ID for TLS security between ThingPark platform and agent. Optional field. Leave empty to disable security. If enabled, the agent generates a token for all uplink and down-link messages. | | Application server key | Application server private key for TLS security between the ThingPark platform and agent for uplink and downlink communications. Value should be in hex and 16 bytes. Optional field. Leave empty to disable security. If enabled, the agent generates a token for all uplink and down-link messages. | | Admin API version | Version that the ThingPark admin API uses. By-default set to "latest". | | Core API version | Version that the ThingPark core API uses. By-default set to "latest". | | Username | Your ThingPark account username. | | Password | Your ThingPark account password. | | Connection type | The ThingPark account type that is being used (Enterprise or Wireless). | ##### Environment-specific information {#environment-specific-information} The following settings vary depending on your ThingPark environment: **ThingPark community:** - URL: https://community.thingpark.io/thingpark/dx/ - Profile ID: community-api - Application server ID and key: Leave empty (HTTPS used internally) - Connection type: Choose Enterprise **Other environments (Enterprise/Wireless):** - URL: Contact ThingPark support - Profile ID: Contact ThingPark support - Application server ID and key: Look up in your application server profile in ThingPark or contact ThingPark support - Connection type: Choose based on your environment (Enterprise or Wireless) > **Important:** > Do not use the same ThingPark login (username and password) for other tenants. > The profile ID, username and password are used to retrieve an access token to send further requests to the ThingPark platform. It is possible to renew the access token by replacing the account credentials for a particular connection. ![Setting provider credentials](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-admin-settings.png) Click **Save**. If you have entered the correct information, you see the message "Connection created". To add another connection, click **Add Connection** and follow the steps above. #### To update a connection {#actility-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 will appear, stating "Can not update the LNS Connection with `` as it's associated with ``. Click the link to download the file with the details of the associated devices: `/service//lns-connection//device`". ![Update connection information](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-admin-settings-update.png) #### To delete a connection {#actility-to-delete-a-connection} Select the connection to be deleted and click **Delete**. If there are devices associated with the connection, an error message will appear, stating "Can not delete the LNS Connection with `` as it's associated with ``. Click the link to download the file with the details of the associated devices: `/service//lns-connection//device`". ![Delete connection](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-admin-settings-delete.png) ### Creating device protocols {#actility-creating-device-protocols} To process data from LoRa devices, Cumulocity needs to understand the payload format of the devices. Mapping a payload data to Cumulocity data can be done by creating a LoRa device protocol. During the [device registration](https://cumulocity.com/docs/device-integration/lpwan/#registering-actility-lora-devices), you can associate this device protocol. The received uplink callbacks for this device with a hexadecimal payload will then be mapped to the ones you have configured in your device protocol. The device protocol assigned during device registration can be changed from the **LPWAN** tab in the device details page. ![Actility LPWAN Tab](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-lpwan-tab.png) > **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 or use the device protocols created by an LPWAN custom codec microservice. #### Importing a predefined device protocol {#actility-importing-a-predefined-device-protocol} In the **Device protocols** page, click **Import**. Select the predefined device type, for example "LoRaWAN Demonstrator" or upload from a file. Click **Import**. ![Import device protocol](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-protocols-import.png) Alternatively, you may also load the device protocol from a file and import it. #### Creating a new device protocol {#actility-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](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-protocols-new.png) 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). 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](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-protocols-payload.png) Click **Add value** to create the value configuration. ![LoRa protocol add value](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-protocols-addvalue.png) In the upcoming window, configure the relevant values as shown in this example. **New value window part 1** ![LoRa protocol add new value](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-protocols-newvalue.png) **New value window part 2** ![LoRa protocol add new value](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-protocols-newvalue2.png) The value configuration maps the value in the payload of a message type to the Cumulocity data. Under **Message type**, configure the **Message ID** according to your device message specification and map it to the Cumulocity 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 must be entered in decimal numbers (not hex). In this example payload structure the message ID is "1". Example payload: message type source ![LoRa bits](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-protocols-loraid.png) 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](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-protocols-lorabits.png) 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 (for example 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](https://cumulocity.com/docs/device-integration/lpwan/#loriot-example-with-nested-structure) 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](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-protocols-loraprotocol.png) After clicking **Save**, your device protocol is created with the values you defined. ##### Example with single property {#actility-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](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-protocols-battery.png) **New value window part 2**

![Battery level changes example](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-protocols-battery2.png) ##### Example with nested structure {#actility-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](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-protocols-lng.png) **New value window, Latitude** ![Value creation: Latitude-nested](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-protocols-lat.png) This will be the result: ![Value configuration in detail: nested structure](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-protocols-gpsexample.png) #### Using custom decoding/encoding {#actility-using-custom-decodingencoding} The Actility agent also supports the decoding/encoding functionality by plugging in the custom microservice. Refer to [LPWAN custom protocols](https://cumulocity.com/docs/device-integration/lpwan/#lpwan-custom-protocols) for further details. ### Registering Actility LoRa devices {#registering-actility-lora-devices} To register a LoRa device in Cumulocity navigate to **Devices** > **Registration** in the Device Management application. Click **Register device** at the top right, and select **Single device registration** > **Actility LoRa** from the dropdown. ![Register devices](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-selection.png) Cumulocity fully supports the LoRa device provisioning with Over-the-Air Activation (OTAA) which is the preferred and most secure way to connect with the LoRa network. If Activation by Personalization (ABP) is required to be used, refer to [LoRa device registration with ABP](https://cumulocity.com/docs/device-integration/lpwan/#lora-device-registration-with-activation-by-personalization-abp). In the next window fill in the required information: - **Connection**: Lists all configured Actility connections in the tenant. The following device profile and connectivity plan option is populated based on the selected Actility connection. - **Device profile**: Select the Actility Thingpark device profile from the dropdown list that matches the device that you are registering. The Actility ThingPark device profile allows to manage multi-RF profiles, ensures different LoRaWAN class compatibility (A, B or C) and allows application payload decoding for easy third-party application integration. - **Device protocol**: Select the appropriate device protocol from the dropdown list. For more information on how to create a device protocol refer to [Creating device protocols](https://cumulocity.com/docs/device-integration/lpwan/#loriot-creating-device-protocols). - **Device EUI**: This is the unique identifier for the device. It is a 16 character (8 byte) long hexadecimal number. You can find it on the device itself. - **Application EUI**: This is a global application ID in the IEEE EUI64 address space that uniquely identifies the application provider of the device. It is a 16 character (8 byte) long hexadecimal number. There can be only one application EUI for a tenant but multiple tenants can have the same application EUI. - **Application key**: This is an AES-128 application key specific for the device that is assigned to the device by the application owner and is responsible to encrypt. The application key is a 32 character (16 byte) long hexadecimal number. JOIN communication. You can find this key on the device itself. - **Connectivity plan**: Select the appropriate connectivity plan from the dropdown list. ![Register devices](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-registration.png) Click **Register** to submit the device registration request and create the device. You can verify that the device is really connected by checking that events are actually coming in. You can do so by clicking on a device and opening the **Events** tab. All events related to this device are listed here. The provision status is shown under **Device data** in the **Info** tab of the device. ![Device data](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-devices-devicedata.png) For more information on viewing and managing your connected devices, also refer to the [Device Management application](https://cumulocity.com/docs/device-management-application). 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. A prompt will appear stating that in order to migrate the device from one LNS connection to another, you must re-register the device. 3. Click **Re-Register**. You are directed to the device registration page where you can perform the re-registration by following the steps above and selecting the desired LNS connection. #### LoRa device registration process {#lora-device-registration-process} A device is created based on the above workflow. First it is checked, if the device already exists. If no device exists with the same device EUI in the ThingPark account, the device is first provisioned on the ThingPark platform and then created on the Cumulocity platform with a link to the device in the ThingPark platform. If the device exists in the ThingPark account, a validation will be applied to compare these devices based on application EUI (for OTAA activation) and device profile. If the validation is successful, the device is created only in Cumulocity with a link to the device in the ThingPark platform. If the validation fails, a failure message is shown and the device is not created in Cumulocity. #### LoRa device registration with Activation by Personalization (ABP) {#lora-device-registration-with-activation-by-personalization-abp} Activating the device by personalization is not recommended and not fully supported in Cumulocity LoRa device registration. However, if you would like to create a device with this activation type in Cumulocity and use the LoRa features - such as sending operations to a device, deprovisioning a device and setting LoRa device protocol type with custom device protocol configuration - you must first provision the device in the ThingPark platform. Moreover you must create "AS Routing Profile" for Cumulocity using the destination `http://actility-server.cumulocity.com` as a "Third Party AS (HTTP)" and assign it to your devices manually. Afterwards, you can register this device using LoRa device registration. In this case, the **Application key** field in the LoRa device registration is invalid. #### Limitations for LoRa devices created with general device registration {#limitations-for-lora-devices-created-with-general-device-registration} The general device registration for LoRa devices is no longer supported. Existing LoRa devices that have been created in Cumulocity with the general device registration process have limitations. For those devices, it is not possible to send operations to the device, deprovision the device and set the LoRa device protocol type with custom device protocol configuration. It is recommended to delete and re-register these devices using LoRa device registration to fully use the LoRa feature. ### Deprovisioning LoRa devices {#deprovisioning-lora-devices} You can deprovision a LoRa device in the ThingPark platform. This means that the device is no longer connected to the network. Its history data is still available in Cumulocity, but the device is deleted in ThingPark. To deprovision a device, navigate to the respective device in the Device Management application under **All devices**. Click **More** in the top right and select **Deprovision device**. ![Deprovision device](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-devices-deprovision.png) After confirming the deprovisioning, the device will be deprovisioned in ThingPark. To provision the device again, the device must be deleted and re-registered using LoRa device registration. ### Sending operations {#actility-sending-operations} If a LoRa device supports receiving hexadecimal commands, you can send them using shell operations. Note 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** and 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](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-devices-predefinedshell.png) 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](https://cumulocity.com/docs/images/device-protocols/lora-actility/lora-devices-port.png) Click **Execute**. The operation is sent to the device. The timing depends on Actility ThingPark. The status of the operation is set to SUCCESSFUL when the operation has successfully been sent to the ThingPark 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 Thingpark platform. ### ThingPark API availability monitoring {#thingpark-api-availability-monitoring} The ThingPark API is monitored, and if it is not reachable, an alarm is created to notify all subscribed tenants using this feature. The alarm is cleared right after the ThingPark API is reachable again. ThingPark API monitoring alarm ### Uplink message processing {#actility-uplink-message-processing} On receiving an uplink message, the Cumulocity platform creates the following measurements and events, and updates the corresponding device managed object. - **Unprocessed data** - An event of type c8y_ActilityUplinkRequest (this type is based on the `event.uplink.type` set in the configuration file) is created with the unprocessed data. - **Position** - The c8y_Position fragment of the device managed object is updated to capture the latitude, longitude, altitude and accuracy information of the device. Also, an event is created with the position information. - **Spreading factor** - The c8y_SpreadingFactor fragment of the device managed object is updated to capture the spreading factor of the device. - **Signal strength** - A measurement is created with RSSI and SNR values of the device signal strength. ### Troubleshooting {#actility-troubleshooting} #### Device registration {#actility-device-registration} **Access to device denied** This warning message shows up when there already exists a provisioned device in ThingPark with the same device EUI used for device registration and the validation comparing those devices based on application EUI (for OTAA activation) and device profile has failed. To resolve this, provide the correct application EUI from the [Connectivity](https://cumulocity.com/docs/device-integration/lpwan/#configuring-multiple-thingpark-account-connections) application and device profile and try again. **No LoRa provider settings found** This warning message shows up when there are no credentials set up for the ThingPark account. To resolve this click **Settings** to navigate to the Administration application where the connections are configured. Device registration failure without credentials
To resolve this, refer to [Configuring multiple ThingPark account connections](https://cumulocity.com/docs/device-integration/lpwan/#configuring-multiple-thingpark-account-connections). **Getting device profiles from provider failed** This warning message shows up when the tenant's access token to Thingpark becomes invalid. Invalidation of the token might happen when the same ThingPark credentials are used for another tenant. This issue can be solved by reconfiguring the Actility ThingPark credentials to renew the access token. Refer to [Configuring multiple ThingPark account connections](https://cumulocity.com/docs/device-integration/lpwan/#configuring-multiple-thingpark-account-connections) for reconfiguration of the credentials. **No device protocols configured** This warning message shows up when no LoRa device protocol exists to be used for device registration. To resolve this, click **Device protocols** to navigate to the **Device protocols** page where the protocols are configured. No device protocol given for LoRa To resolve this, configure at least one device protocol in the [Device database](https://cumulocity.com/docs/device-management-application/managing-device-types). **No connectivity plans with free slots available** This warning message shows up when the connectivity plan in Actility ThingPark has reached the limit for the device count. To resolve this, either contact ThingPark on the device quota limits for your connectivity plans or remove unused devices from ThingPark and retry registering the device in Cumulocity. #### Connectivity {#actility-connectivity} **Authorization to the LoRa platform failed** This warning message shows up if a provided profile ID, username or password is invalid. To resolve this, provide correct credentials and try again. **Authentication to the Actility platform failed. Check if the base URL is correct** To resolve this, provide a correct URL and try again. **Authentication to the Actility platform failed with status code '400'. Check if the profile ID is correct** To resolve this, provide a correct profile ID and try again. **Authentication to the Actility platform failed with status code '401'. Check if the credentials are correct** To resolve this, provide a correct username and password and try again. ## Sigfox ### Introduction {#sigfox-introduction} Cumulocity can interface with Sigfox devices through the Sigfox Cloud. You can: - Provision Sigfox devices easily using the Cumulocity Device Management application. - Decode upstream payload packets using a web-based user interface. - Debug and post-process raw device data through Cumulocity events. - Send downstream data to the device using Cumulocity operations. - Make use of existing Cumulocity features with Sigfox devices, for example: connectivity monitoring, device management, data visualization with dashboards, real-time analytics and more. The following illustration grants you a quick overview of the Cumulocity Sigfox integration: ![Cumulocity Sigfox integration](https://cumulocity.com/docs/images/device-protocols/sigfox/sigfox-cumulocity-integration.png) > **Requirements:** > To be able to use the Sigfox agent, your tenant must be subscribed to the application sigfox-agent. In case of any issues please contact [product support](https://cumulocity.com/docs/additional-resources/contacting-support/). ### Managing the connectivity settings {#managing-the-connectivity-settings} Before you register a device, you must configure the Sigfox Cloud credentials in the **Connectivity** page in the Administration application. You must set up these Sigfox Cloud credentials in Sigfox. Before you create API access to Cumulocity, you must have an "Associated user" which is added to the Cumulocity group in Sigfox Cloud and has the following profiles: - Customer [R] - Device Manager [W] > **Important:** > Without the profiles described below, the required Sigfox API access can not be set up. #### Step 1 {#step-1} If you already have an associated user make sure it has the profiles mentioned below and proceed to step 2. The group name is not constrained. "Cumulocity" is used as a sample group name throughout the remaining steps. First, enter into your Sigfox Cloud account and create a new user. Add the user to the group and select the "Customer [R]" and "Device Manager [W]" profiles. ![New user](https://cumulocity.com/docs/images/device-protocols/sigfox/sigfox-newuser.png) #### Step 2 {#step-2} After creating an "Associated user" with the proper group and profiles navigate to the **Groups** page. In the **API access** tab, create a new entry and add the following profiles: - Customer [R] - Device Manager [W] ![API access page](https://cumulocity.com/docs/images/device-protocols/sigfox/sigfox-api-access.png) #### Step 3 {#step-3} After the API access entry has been created, you can connect your Sigfox Cloud account to Cumulocity via the **Connectivity** page in the Administration application. Navigate to the **Connectivity** page and switch to the **Sigfox provider settings** tab. The **Connectivity** tab facilitates creating, updating, and deleting multiple Sigfox connections. The following information must be provided in order to create a connection: - **Name**: Name of the Sigfox connection being created. - **Description**: Description of the Sigfox connection being created. - **Login:** The login token is located in the API access entry in the Sigfox Cloud. - **Password:** The password token is located in the API access entry in the Sigfox Cloud next to **Password**. - **Parent Group ID:** This ID is written in your URL when you are logged into your Sigfox account and you have selected the "Cumulocity" group. For example, *https://backend.sigfox.com/group/**9823ruj29j9d2j9828hd8**/info*. - **Base URL:** URL that points to the Sigfox Cloud account. > **Info:** > The group name in the screenshot below is only an example. It does not necessarily have to be "Cumulocity". ![Sigfox group ID](https://cumulocity.com/docs/images/device-protocols/sigfox/sigfox-parentgroupid.png) ![Sigfox connectivity update](https://cumulocity.com/docs/images/device-protocols/sigfox/sigfox-connectivity-update.png) Click **Save**. If you have entered the correct information, the message "Credentials successfully saved" will be displayed. To add another connection, click **Add Connection** and follow the steps above. #### To update a connection {#sigfox-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 will appear, stating "Can not update the LNS Connection with `` as it's associated with ``. Click the link to download the file with the details of the associated devices: `/service//lns-connection//device`". ![Update connection information](https://cumulocity.com/docs/images/device-protocols/sigfox/sigfox-connectivity-update.png) #### To delete a connection {#sigfox-to-delete-a-connection} Select the connection to be deleted and click **Delete**. If there are devices associated with the connection, an error message will appear, stating "Can not delete the LNS Connection with `` as it's associated with ``. Click the link to download the file with the details of the associated devices: `/service//lns-connection//device`". ![Delete connection information](https://cumulocity.com/docs/images/device-protocols/sigfox/sigfox-admin-settings-delete.png) > **Info:** > To create, update, or delete LNS connections, you must have the Sigfox ADMIN permission assigned to your user. To view the LNS connections, the Sigfox READ permission is sufficient. #### Authentication to the Sigfox platform failed {#authentication-to-the-sigfox-platform-failed} Authentication to the Sigfox platform failed. Check if the Parent group ID and/or the credentials are correct. To resolve this, provide a correct baseUrl or parent group ID or username or password and try again. ### Creating device protocols {#sigfox-creating-device-protocols} To process data from Sigfox devices, Cumulocity must understand the payload format of the devices. Mapping payload data to Cumulocity data can be done by creating a Sigfox device protocol. During the [device registration](https://cumulocity.com/docs/device-integration/lpwan/#registering-sigfox-devices), you can associate this device protocol. The received uplink callbacks for this device with a hexadecimal payload will then be mapped to the ones you have configured in your device protocol. The device protocol assigned during Sigfox device registration can be changed from the **LPWAN** tab in the device details page. ![Sigfox LPWAN Tab](https://cumulocity.com/docs/images/device-protocols/sigfox/sigfox-lpwan-tab.png) > **Info:** > In order to view the relevant LNS connection in the **Current connection** field, the user must have at least Sigfox READ permission. > **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). To create device protocols, select **Device protocols** in the **Device types** menu in the navigator of the Device Management application. You can either import an existing device protocol or create a new one. #### Importing a device protocol {#importing-a-device-protocol} In the **Device protocols** page, click **Import**. Select the desired predefined device type or upload it from a file. When ready, click **Import** again. #### Creating a new device protocol {#creating-a-new-device-protocol} In the **Device protocols** page, click **New device protocol** and select **Sigfox** from the options list. ![New Sigfox protocol](https://cumulocity.com/docs/images/device-protocols/sigfox/sigfox-newprotocol.png) Provide a name for the device protocol an and optional description, and click **Create**. Under **Message types**, specify the message types. Sigfox devices can send messages of different types with different encodings per type. Depending on the device, the type can be determined by looking either at the FPort parameter of a message (Source: FPort) or at the subset of the message payload itself (Source: Payload). In the **Source** field, select the way the message type is encoded: - **Payload**: if the message type can be determined by looking at the subset of the message payload itself In the following sample 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. In the **Number of bits** field, indicate how long this information is. For example, start bit = "0" and number of bits = "8". ![Sigfox protocol](https://cumulocity.com/docs/images/device-protocols/sigfox/sigfox-bits.png) ##### Configuring values {#configuring-values} In the **Values** section, click **Add value** to create the value configuration. In the following window, configure the relevant values as shown in this example. **New value window part 1** ![Sigfox protocol add new value](https://cumulocity.com/docs/images/device-protocols/sigfox/sigfox-protocols-newvalue.png) **New value window part 2** ![Sigfox protocol add new value](https://cumulocity.com/docs/images/device-protocols/sigfox/sigfox-protocols-newvalue2.png) The value configuration maps the value in the payload of a message type to the Cumulocity data. Under **Message type**, configure the **Message ID** according to your device message specification. 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 must be entered in decimal numbers (not hex). In this sample payload structure the message ID is "1". Example payload: message type source ![Sigfox bits](https://cumulocity.com/docs/images/device-protocols/sigfox/sigfox-protocols-sigfoxid.png) Under **General**, specify a name for the value and the category under which it will be displayed in the values list. Under **Value selection**, specify from where the value should be extracted. In the **Start bit** field, indicate where the value information starts and in the **Number of bits** field, indicate the length of the information. 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 ![Sigfox bits](https://cumulocity.com/docs/images/device-protocols/sigfox/sigfox-protocols-sigfoxbits.png) The hexadecimal value is converted to a decimal number and afterwards a "value normalization" is applied. Under **Value normalization**, specify 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 or positive. By default it is set to 1. - **Offset**: This value defines the offset that is added or subtracted. It can be decimal, negative or positive. By default it is set to 0. - **Unit** (optional): A unit can be defined which is saved together with the value (for example temperature unit "C" for degree Celsius). For detailed information on how to decode the payload, refer to the documentation of the device. Under Options, select on 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](https://cumulocity.com/docs/device-integration/lpwan/#sigfox-example-with-nested-structure) 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](https://cumulocity.com/docs/images/device-protocols/sigfox/sigfox-protocol.png) Click **Save** to create the device protocol. ##### Example with single property {#sigfox-example-with-single-property} The following images show an example for a message which sends a measurement when the battery level value changes. **New value window part 1** ![Battery level changes example](https://cumulocity.com/docs/images/device-protocols/sigfox/sigfox-protocols-battery.png) **New value window part 2** ![Battery level changes example](https://cumulocity.com/docs/images/device-protocols/sigfox/sigfox-protocols-battery2.png) ##### Example with nested structure {#sigfox-example-with-nested-structure} The following images show an example of a nested structure for a device protocol, reporting the current position of a GPS device. The device protocol 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](https://cumulocity.com/docs/images/device-protocols/sigfox/sigfox-protocols-lng.png) **New value window, Latitude** ![Value creation: Latitude-nested](https://cumulocity.com/docs/images/device-protocols/sigfox/sigfox-protocols-lat.png) This will be the result: ![Value configuration in detail: nested structure](https://cumulocity.com/docs/images/device-protocols/sigfox/sigfox-protocols-gpsexample.png) #### Using custom decoding/encoding {#sigfox-using-custom-decodingencoding} The Sigfox agent also supports the decoding/encoding functionality by plugging in the custom microservice. Refer to [LPWAN custom protocols](https://cumulocity.com/docs/device-integration/lpwan/#lpwan-custom-protocols) for further details. ### Registering Sigfox devices {#registering-sigfox-devices} To register a Sigfox device in Cumulocity navigate to **Devices** > **Registration** in the Device Management application, click **Register device** at the top right and select **Single device registration** > **Sigfox** from the dropdown. ![Register devices](https://cumulocity.com/docs/images/device-protocols/sigfox/sigfox-registration.png) > **Info:** > - If Sigfox is not one of the available options, your tenant is not subscribed to the relevant application, see the requirements in the [introduction](https://cumulocity.com/docs/device-integration/lpwan/#sigfox-introduction). > - The device type created in the Sigfox Cloud platform has the following naming convention
`c8y_{tenantId}_{device-protocol-name}_{contractId}`, for example: `c8y_myTenant_mySigfoxDeviceProtocol_aabbcc5b78c901d64eecf4faaa` > - If the constructed name exceeds 100 characters it will be truncated until it is less than 100 characters. In the next window, fill in the required information: - **ID:** Unique device ID. The value must be a hexadecimal number. - **PAC:** Porting authorization code for your device. The value must be a hexadecimal number. - **Connection**: Lists all configured Sigfox connections in the tenant. The following contract option is populated based on the selected Sigfox connection. - **Contract:** Select your desired contract (all contracts are listed including active and expired). - **Device protocol:** Select your desired device protocol from the dropdown list. - **Product certificate key:** This key can be located in *https://partners.sigfox.com/*. Navigate to your device and copy the certificate key. If the checkbox is not selected and no product certificate key is specified, the device will be considered a prototype. > **Info:** > The term "Device type" is used both by Sigfox and Cumulocity, but with different meaning. In Sigfox, a device type specifies how to route data from devices. In Cumulocity, a device type describes the data that is sent by devices of a particular type. ![Register devices1](https://cumulocity.com/docs/images/device-protocols/sigfox/sigfox-registration1.png) Click **Register** to submit the device registration request and create the device. You can verify that the device is really connected by checking that events are actually coming in. You can do so by clicking on a device and opening its **Events** tab. All events related to this device are listed here. For more information on viewing and managing your connected devices, also refer to the [Device Management application](https://cumulocity.com/docs/device-management-application/). In order to migrate the device from one LNS connection to another, the device must be re-registered. Navigate to the **LPWAN** tab of the Device. Click on the **Provider connection** dropdown. 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 on the **Re-Register** button. The user is directed to the device registration page where he can perform the re-registration following the steps above and selecting the desired LNS connection. > **Info:** > For Sigfox device registration, you must have CREATE or ADMIN permission for the "Inventory" permission type. ##### Updating devices registered with the general device registration {#updating-sigfox-devices} If devices have previously been registered via the general device registration the following URLs must be manually changed in the Sigfox Cloud: - `https://sigfox-agent.cumulocity.com/sigfoxDataCallback` to `https://.cumulocity.com/service/sigfox-agent/sigfoxDataCallback`. - `https://sigfox-agent.cumulocity.com/sigfoxServiceAcknowledgeCallback` to `https://.cumulocity.com/service/sigfox-agent/sigfoxServiceAcknowledgeCallback`. - `https://sigfox-agent.cumulocity.com/sigfoxServiceStatusCallback` to `https://.cumulocity.com/service/sigfox-agent/sigfoxServiceStatusCallback`. - `https://sigfox-agent.cumulocity.com/sigfoxErrorCallback` to `https://.cumulocity.com/service/sigfox-agent/sigfoxErrorCallback`. > **Info:** > General device registration for Sigfox devices is no longer supported. ### Sending operations {#sigfox-sending-operations} If the device supports sending hexadecimal commands, you can send them using shell operations. 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** and switch to the **Shell** tab. > **Info:** > Operations do not go to a status of EXECUTING immediately. They go to EXECUTING when the device is expecting the downlink message. Afterwards, the pending operation which is created first goes to a status of EXECUTING. ### Uplink message processing {#sigfox-uplink-message-processing} On receiving an uplink message, the Cumulocity platform creates the following measurements and events, and updates the corresponding device managed object. - **Unprocessed data** - An event of type com_sigfox_UnprocessedDataEvent is created with the unprocessed data. - **Position** - The c8y_Position fragment of the device managed object is updated to capture the latitude, longitude, altitude and accuracy information of the device. - **Signal strength** - A measurement is created with RSSI and SNR values of the device signal strength. > **Important:** > Sigfox is discontinuing its Service Status callback service. This callback delivered the Sigfox out-of-band (OOB) status messages that the Sigfox agent turned into the `c8y_BatteryMeasurement` (battery voltage) and `c8y_TemperatureMeasurement` (device temperature) measurements. > > - From September 2026, the Sigfox backend no longer accepts new Service Status callbacks. The Sigfox agent still requests the callback for every new device type, but Sigfox rejects it. Devices registered with a new device type therefore do not receive these two measurements. > - From April 2027, Sigfox discontinues the service entirely. No Sigfox device receives these two measurements anymore. > > This is a change on the Sigfox side and cannot be compensated by Cumulocity, because no other Sigfox callback carries battery or temperature values. If you rely on these measurements, for example in dashboards, smart rules, or integrations, transmit battery voltage and temperature in the regular application payload of your device, as recommended by Sigfox, and map them to measurements in your [device protocol](https://cumulocity.com/docs/device-integration/lpwan/#sigfox-creating-device-protocols). Use the same fragment and series names to keep existing dashboards and rules working. ### Troubleshooting {#sigfox-troubleshooting} #### Device registration {#device-registration} **No active contracts with free slots available** Active contracts with free slots are filtered based on the activation end time and tokens in use. Contracts in which the activation end time is higher than the current time or the activation end time is unlimited, and contracts in which the max tokens are higher than the tokens in use or the max tokens are unlimited will be considered. In order to resolve this error, please contact support.sigfox.com to create a contract for your Sigfox account. **No Sigfox provider settings are found** This warning message shows up when there are no connections set up for the sigfox connectivity. To resolve this, refer to [Configure Sigfox credentials](https://cumulocity.com/docs/device-integration/lpwan/#managing-the-connectivity-settings). **No Sigfox device type configured** This warning message shows up when no Sigfox device protocol exists to be used for device registration. To resolve this, configure at least one device protocol in the [Device database](https://cumulocity.com/docs/device-management-application/managing-device-types). #### Connectivity {#connectivity} **Sigfox callbacks in backend.sigfox.com are not created correctly** Sigfox callbacks error
The information for the callback setup is retrieved by a microservice. To verify whether your setup is correct, execute the following REST API request: ```http GET {{url}}/tenant/currentTenant ``` > **Info:** > The request above is simply an example API request that could be used. For more info on REST API requests, refer to the [Tenants](https://cumulocity.com/api/core/#tag/Tenants) in the Cumulocity OpenAPI Specification. This warning message shows up when there are no connections set up for the Sigfox account. To resolve this click **Settings** to navigate to the Administration application where the connections are configured. Device registration failure without connections
**No device protocols configured** This warning message shows up when no Sigfox device protocol exists to be used for device registration. To resolve this, click **Device protocols** to navigate to the **Device protocols** page where the protocols are configured. No device protocol given for Sigfox #### Issues with alarm provisioning {#issues-with-alarm-provisioning} **Transfer operation failed** ![!Failed operation](https://cumulocity.com/docs/images/device-protocols/sigfox/sigfox-troubleshooting-failedoperation.png) If the "transfer operation failed" alarm is triggered, the device is already provisioned in the Sigfox platform and changing the device type in the Sigfox platform failed. In order to fix this issue, you must manually change the device type in the Sigfox platform to the intended one. **Provisioned status is set to false** ![!False provision](https://cumulocity.com/docs/images/device-protocols/sigfox/sigfox-troubleshooting-falseprovision.png) In case of this alarm, you can see that the **Provisioned** status is set to "false" which means that no data is coming from the Sigfox platform. In the alarm message there is more information regarding the error. In this case the PAC code given during registration was invalid. > **Info:** > If the provisioning process has been completed, but has failed, information is returned as an alarm with the reason of the failure provided. The **Provisioned** status is set to true when the device provisioning process is completed and success information is received from the Sigfox platform. Additionally, it is set to true when uplink messages are retrieved from the device. > **Info:** > The status is updated asynchronously which means that sometimes you might have to wait a bit until it is set to true. **Callback creation failed** ![Callback creation failed](https://cumulocity.com/docs/images/device-protocols/sigfox/sigfox-troubleshooting-callback.png) This alarm is created when one or more callback creation requests have failed in the Sigfox platform. You can view the alarm either in the **Alarms** page or in the **Home** page. > **Info:** > The Sigfox backend rejects the creation of Service Status callbacks (type `SERVICE_STATUS`) since September 2026, because Sigfox is discontinuing this callback service. The Sigfox agent still requests this callback during device type registration, but it does not raise this alarm when Sigfox rejects it. The rejection is only written to the microservice log. Do not create the Service Status callback manually. See [Uplink message processing](https://cumulocity.com/docs/device-integration/lpwan/#sigfox-uplink-message-processing) for the impact on battery and temperature measurements. In order to fix this issue, navigate to the Sigfox platform web interface and check the device type with the id mentioned in the alarm. ![Device Type Id in the alarm](https://cumulocity.com/docs/images/device-protocols/sigfox/sigfox-troubleshooting-callback-typeid.png) In this case navigate to the following address: *https://backend.sigfox.com/devicetype/5cd3d97ee833d9746698b27d/callbacks* If the mentioned callbacks cannot be located in the Sigfox platform, you must create them manually. All of the required information needed for the creation of the callbacks is already given in the alarm description. In the case of the above alarm, the following callback is listed first: - [[callback=[type=DATA_BIDIR, url=<>/service/sigfox-agent/sigfoxDataCallback, httpMethod=POST, bodyTemplate={"device":"{device}","time":"{time}","snr":"{snr}","station":"{station}","data":"{data}","rssi":"{rssi}","seqNumber":"{seqNumber}","ack":"{ack}"}, contentType=application/json, headers={Authorization=Basic ...}]] In order to manually create the callback, the following properties must be filled: - type - url - httpMethod - bodyTemplate - contentType - headers > **Info:** > The Authorization header displayed in the alarm does not show the user credentials. Non-mentioned properties from the alarm are: - sendSni - sendDuplicate These properties will be set to false. ## LPWAN custom protocols ### Introduction {#lpwan-custom-protocols-introduction} Cumulocity can interface with LPWAN devices through LPWAN network providers via Cumulocity LPWAN agents, such as [Actility LoRa](https://cumulocity.com/docs/device-integration/lpwan/#actility-lora). Our LoRa integration allows you to define device protocols in a self-service manner to create a binary mapping of the LoRa sensor data to the Cumulocity data model. However, this approach does not work for LoRa devices sending dynamic payloads. To integrate LoRa devices with dynamic payloads, a custom codec for payload decoding and command encoding can be created in form of a microservice. This microservice will be referred to as a custom codec microservice. A custom codec microservice is a typical Cumulocity microservice which conforms to a specific contract for decoding and encoding LoRa payloads and commands. When an LPWAN agent receives an uplink message, it forwards the device data to a REST endpoint (such as `/decode`) exposed by the custom codec microservice for decoding. Similarly, when the user executes a device command through the device shell, the LPWAN agent forwards the command text to a REST endpoint (such as `/encode`) exposed by the custom codec microservice for encoding. ### Implementing a custom codec microservice {#implementing-a-custom-codec-microservice} A custom codec microservice is a typical Cumulocity microservice, which can be implemented and enabled as follows. 1. Create a microservice which exposes the /encode and /decode REST endpoints conforming to the [OpenAPI Specification](https://cumulocity.com/docs/files/rest/lpwan-custom-codec-openapi.yaml), implementing the encoding and decoding functionality. 2. The microservice must create device protocols for each LPWAN device type it supports. If you use the lpwan-custom-codec library the device protocols will be created automatically for you. Otherwise, you must use the Inventory API to create a new managed object describing the device protocol with the following JSON structure: You must create a device protocol (with `type` and `fieldbusType` properties, and the `c8y_LpwanCodecDetails` fragment) as well as an external ID for every device manufacturer and device model combination that this codec microservice supports: * `type` is always "c8y_LpwanDeviceType". * `fieldbusType` is always "lpwan". * The `c8y_LpwanCodecDetails` fragment contains: * `codecServiceContextPath`- Custom codec microservice context path. * `supportedDevice`- Supported device information. * `deviceManufacturer`- Device manufacturer. * `deviceModel`- Device model. * `supportedDeviceCommands`- A list of commands which this device supports: * `name`- Command name, matching the name of the predefined command template you create (see below). * `category`- Command category, matching the category of the predefined command template you create (see below).
Example for the JSON structure for creating a device protocol using the Inventory API: ```json { "name": "<>", "description": "<>", "type": "c8y_LpwanDeviceType", "fieldbusType": "lpwan", "c8y_IsDeviceType": {}, "c8y_LpwanCodecDetails": { "codecServiceContextPath": "<>", "supportedDevice": { "deviceManufacturer": "<>", "deviceModel": "<>", "supportedDeviceCommands": [ { "name": "<>", "category": "<>" } ] } } } ``` Example for the JSON structure for creating an external ID for the device protocol using the Identity API: ```json { "externalIds": [ { "managedObject": "<>", "externalId": "<>", "type": "c8y_SmartRestDeviceIdentifier" } ] } ``` 3. Based on the device protocol assigned to a device, the LPWAN agent automatically routes the request to the corresponding microservice. For device downlink commands, the LPWAN agent forwards the device shell command request to the /encode endpoint only when a predefined command listed as "supportedDeviceCommands" in the `c8y_LpwanCodecDetails` fragment of the device protocol is executed. You must create a predefined command template for every supported device command (`supportedDeviceCommands`) specified in the device type. The following example shows the JSON structure for creating a predefined command template using the Inventory API: ```json { "type": "c8y_DeviceShellTemplate", "name": "<>", "deviceType": [ "<>" ], "category": "<>", "command": "<>", "deliveryTypes": [ "Default" ] } ``` ### Using the LPWAN custom codec library {#using-the-custom-codec-library} For convenience, Cumulocity provides the Java library `com.nsn.cumulocity.clients-java:lpwan-custom-codec` to develop the custom codec microservice in Java as a SpringBoot application. When subscribed, such a custom codec microservice automatically creates the required device protocols and predefined command templates as described in [Implementing a custom codec microservice](https://cumulocity.com/docs/device-integration/lpwan/#implementing-a-custom-codec-microservice). To create a custom codec microservice using this library, do the following: 1. Add the following dependency to the pom.xml file: ```xml com.nsn.cumulocity.clients-java lpwan-custom-codec ${c8y.version} ``` 2. Create a Spring Boot application and annotate its main class with: ```java @CodecMicroserviceApplication `com.cumulocity.microservice.lpwan.codec.annotation.CodecMicroserviceApplication` ``` 3. Implement the following Java interfaces and annotate them with: ```java @Component `org.springframework.stereotype.Component` ``` a. Implement the `supportedDevices` method of `com.cumulocity.microservice.lpwan.codec.Codec` to specify the device manufacturer, device name and the commands this custom codec service supports: ```java package com.cumulocity.microservice.lpwan.codec; public interface Codec { Set supportsDevices(); } ``` b. Implement the `decode` method of `com.cumulocity.microservice.customdecoders.api.service.DecoderService` to provide the decode functionality. The decode method receives the following input: * `inputData`- device payload to be decoded. * `deviceId`- device managed object ID. * `args`- a map which contains keys: * `deviceManufacturer`- device manufacturer. * `deviceModel`- device model. * `sourceDeviceEui`- device eui. * `fport`- fport (optional).
The library also provides the wrapper class `com.cumulocity.microservice.lpwan.codec.decoder.model.LpwanDecoderInputData` to extract the decoder inputs.
```java package com.cumulocity.microservice.customdecoders.api.service; public interface DecoderService { DecoderResult decode(String inputData, GId deviceId, Map args) throws DecoderServiceException; } ``` c. Implement the `encode` method of `com.cumulocity.microservice.customencoders.api.service.EncoderService` to provide the encode functionality: ```java package com.cumulocity.microservice.customencoders.api.service; public interface EncoderService { EncoderResult encode(EncoderInputData encoderInputData) throws EncoderServiceException; } ``` 4. Add the following permissions in the microservice manifest file `cumulocity.json`. Note that the respective field in the manifest is called `requiredRoles`, but what you actually add is a list of required permissions strings. ```json "requiredRoles": [ "ROLE_INVENTORY_ADMIN", "ROLE_INVENTORY_READ" ] ``` ### Deploying the sample codec microservice {#deploying-the-sample-codec-microservice} Steps to build the example codec `lora-codec-lansitec` microservice. 1. Clone the https://github.com/Cumulocity-IoT//cumulocity-examples.git repository. 2. Build the microservice using `mvn clean install`. This creates a ZIP file of the lanitec codec microservice. 3. Deploy the microservice by uploading the ZIP file using the Cumulocity Administration UI. 4. Open the Device Management application. Under **Device protocols**, you should now see the device protocols with type "lpwan" created by the lansitec codec microservice. The image below shows the device protocols option in the Device Management application. ![Device Protocols Page](https://cumulocity.com/docs/images/device-protocols/lpwan-custom-codec/lpwan-device-protocols-page.png) The image below shows an example of the device protocols created by the custom codec microservice on subscription. ![List of device protocols created on subscription](https://cumulocity.com/docs/images/device-protocols/lpwan-custom-codec/lpwan-device-protocols.png) The created device protocols will be listed in the dropdown during the device registration of LPWAN with any of the LPWAN agents. The Actility LoRa device registration is shown below. ![Device Registration](https://cumulocity.com/docs/images/device-protocols/lpwan-custom-codec/lpwan-protocol-list-device-registration.png) You can also assign the device protocol from the **LPWAN** device tab. To do so, navigate to a particular device. Then, switch to the **LPWAN** tab and click **New device protocol** to view the device protocols created above. ![Device protocol mapping](https://cumulocity.com/docs/images/device-protocols/lpwan-custom-codec/lpwan-device-page-lpwantab.png) Supported device commands are available in the **Predefined commands option** from the **Device shell** tab. ![Device supported commands](https://cumulocity.com/docs/images/device-protocols/lpwan-custom-codec/lpwan-custom-codec-device-commands.png)