--- name: cumulocity-provision-loriot-device description: "Select the Loriot connection, application, and device protocol, register a LoRa device on the Loriot network server, send a downlink command, and move the device to another Loriot application. Use when the user wants to register a LoRa device on Loriot, send it a downlink command, or move it to another Loriot application." compatibility: "Requires network access to a Cumulocity tenant and the C8Y_BASEURL, C8Y_TENANT, C8Y_USER, and C8Y_PASSWORD environment variables." --- # Register a Loriot LoRa device Source: https://cumulocity.com/docs/skills/device-management/provision-loriot-device/ Sector: Skills, Device management & connectivity Release: Latest Description: Select the Loriot connection, application, and device protocol, register a LoRa device on the Loriot network server, send a downlink command, and move the device to another Loriot application. ## Before you start Use these skills first: - `cumulocity-authentication` skill: [Authenticate REST API requests](https://cumulocity.com/docs/skills/platform-administration/authentication/index.md) Cumulocity connects to LoRa devices through the Loriot network server. The Loriot agent microservice registers a device on the Loriot network server and creates it in Cumulocity in one step. You send these requests to the agent under the path `/service/loriot`. For the integration and its configuration in the UI, see [Loriot LoRa](https://cumulocity.com/docs/device-integration/lpwan/#loriot-lora). The agent also creates devices automatically when they send uplink messages. These devices cannot receive downlink commands until you register them as described here. The registration associates the device with a connection and a device protocol. Before you start, check the following prerequisites: * Your tenant is subscribed to the Loriot agent. Otherwise, the requests to `/service/loriot` return HTTP 403 with the error "Microservice/Access Denied". * A Loriot connection is configured in the Administration application, see [Creating a Loriot LNS connection](https://cumulocity.com/docs/device-integration/lpwan/#creating-a-loriot-lns-connection-in-cumulocity). * A LoRa device protocol exists, see [Creating device protocols](https://cumulocity.com/docs/device-integration/lpwan/#loriot-creating-device-protocols). > **Requirements:** > ROLES & PERMISSIONS: > > * To list the Loriot connections: ROLE_LORIOT_READ or ROLE_LORIOT_ADMIN > * To list the Loriot applications: ROLE_LORIOT_ADMIN > * To register and move devices: ROLE_LORIOT_ADMIN, ROLE_INVENTORY_CREATE, or ROLE_INVENTORY_ADMIN > * To find the device protocol: ROLE_INVENTORY_READ > * To check the external ID: ROLE_IDENTITY_READ > * To send a downlink command: ROLE_DEVICE_CONTROL_ADMIN > * To delete the device: ROLE_INVENTORY_ADMIN The examples use `` for the name of the Loriot connection and `` for the device EUI. The agent returns plain JSON arrays and objects, without paging. ### To select the connection, application, and device protocol {#to-select-the-connection-application-and-device-protocol} 1. To list the Loriot connections of the tenant, send the following request to the agent: ```http GET /service/loriot/lns-connection ``` The agent returns HTTP 200 and the connections. Check that one of them has the `name` ``. Otherwise, create the connection first. 2. To list the applications of the connection, send the following request: ```http GET /service/loriot/applications?loriotConnectionName= ``` The agent returns HTTP 200 and an array of applications with their `_id`, `hexId`, `name`, `devices`, and `deviceLimit`. Select an application whose `devices` is lower than its `deviceLimit`. Note its `hexId` as ``. The agent returns the following errors: * **HTTP 401**: The agent cannot log in to Loriot. The username or the password of the connection is wrong. Update the connection. * **HTTP 403**: You do not have the role ROLE_LORIOT_ADMIN. * **HTTP 400**: The Loriot platform cannot be reached, or the request is invalid. 3. To find the ID of the device protocol by its name, send a [Retrieve all managed objects](https://cumulocity.com/api/core/#operation/getManagedObjectCollectionResource) request: ```http GET /inventory/managedObjects?query=$filter=name eq ''&pageSize=100 ``` URL-encode the value of the `query` parameter. The name must match exactly, including uppercase and lowercase letters. The platform returns HTTP 200. If the `managedObjects` array contains exactly one protocol, note its `id` as ``. If it contains no protocol or several protocols, the name does not identify one protocol. Check the name. ### To register the device {#to-register-the-device} Send the following request to the agent: ```http POST /service/loriot/newDeviceRequest Content-Type: application/json Accept: application/json { "title": "warehouse-sensor-01", "deveui": "", "appeui": "", "appkey": "", "appid": "", "deviceType": { "id": "", "name": "" }, "lnsConnectionName": "" } ``` The request has the following properties: * `title`: The title of the device. * `deveui`: The device EUI, 16 hexadecimal characters in uppercase. * `appeui`: The application EUI, 16 hexadecimal characters. * `appkey`: The AES-128 application key, 32 hexadecimal characters. * `appid`: The `hexId` of the Loriot application, in uppercase. * `deviceType`: The ID and the name of the device protocol. The agent stores the `id` with the device, so always send the ID, never the name. * `lnsConnectionName`: The name of the Loriot connection. The agent returns HTTP 201 and the managed object of the device. Its `name` is `Loriot Device `. Note its `id` as ``. The agent returns the following errors: * **HTTP 400** with a message that names a field: The value of the field does not have the required format, for example it is not uppercase hexadecimal. Correct it and send the request again. * **HTTP 401**: The agent cannot log in to Loriot. Check the credentials of the connection. * **HTTP 404**: The Loriot application does not exist. Check `` against the list of applications. The registration in the Device Management application uses the same fields, see [Device registration via the platform](https://cumulocity.com/docs/device-integration/lpwan/#device-registration-via-the-platform). ### To check the registration {#to-check-the-registration} The agent registers the device EUI as external ID of the type `c8y_LoriotEUI`. Send a [Retrieve a specific external ID](https://cumulocity.com/api/core/#operation/getExternalIDResource) request: ```http GET /identity/externalIds/c8y_LoriotEUI/ ``` The platform returns HTTP 200. The `managedObject.id` is ``. If the platform returns HTTP 404, the registration did not complete. ### To send a downlink command {#to-send-a-downlink-command} You send a command to the device as a shell operation. Its text is a hexadecimal string. The agent sends it to port 1 of the device. To use another port, add a colon and the port number, for example `0102AABB:2`. Send a [Create an operation](https://cumulocity.com/api/core/#operation/postOperationCollectionResource) request: ```http POST /devicecontrol/operations Content-Type: application/json Accept: application/json { "deviceId": "", "description": "LoRa downlink", "c8y_Command": { "text": "0102AABB" } } ``` The platform returns HTTP 201 and the operation with its `id` and `"status": "PENDING"`. The agent picks up pending commands on its own schedule, by default every 31 seconds. Follow the status of the operation for up to 3 minutes, see [Send an operation to a device](https://cumulocity.com/docs/skills/device-management/send-operation/#to-follow-the-status-of-the-operation): * **SUCCESSFUL**: The agent sent the command to the Loriot platform. This does not confirm that the device received it. * **FAILED**: The command is invalid, or Loriot rejected it. The `failureReason` describes why. For details, see [Sending operations](https://cumulocity.com/docs/device-integration/lpwan/#loriot-sending-operations). ### To move the device to another Loriot application {#to-move-the-device-to-another-loriot-application} The example uses `` for the `hexId` of the application that the device moves to. Send the following request to the agent: ```http POST /service/loriot/transferDevice//device/ Content-Type: application/json Accept: application/json { "destinationId": "", "deviceId": "", "originId": "", "lnsConnectionName": "" } ``` The agent returns HTTP 204 without a body. The device now belongs to the target application. The agent returns the following errors: * **HTTP 400**: A value in the path or in the body is not uppercase hexadecimal. Correct it and send the request again. * **HTTP 401**: The agent cannot log in to Loriot. Check the credentials of the connection. * **HTTP 404**: The source or the target application does not exist. Check both IDs against the list of applications. ### To delete the device {#to-delete-the-device} Send a [Remove a specific managed object](https://cumulocity.com/api/core/#operation/deleteManagedObjectResource) request: ```http DELETE /inventory/managedObjects/ ``` The platform returns HTTP 204 and removes the device and its external IDs from the tenant. If the deletion takes longer than 30 seconds, the platform returns HTTP 202 and completes it in the background. ## API reference ### Core API Reference: https://cumulocity.com/api/core/ - [GET /inventory/managedObjects](https://cumulocity.com/api/core/#operation/getManagedObjectCollectionResource): Retrieve all managed objects - [GET /identity/externalIds/{type}/{externalId}](https://cumulocity.com/api/core/#operation/getExternalIDResource): Retrieve a specific external ID - [POST /devicecontrol/operations](https://cumulocity.com/api/core/#operation/postOperationCollectionResource): Create an operation - [DELETE /inventory/managedObjects/{id}](https://cumulocity.com/api/core/#operation/deleteManagedObjectResource): Remove a specific managed object ## Linked from the documentation - [LPWAN > Loriot LoRa](https://cumulocity.com/docs/device-integration/lpwan/#loriot-lora)