Device Resource management

Resources are sensors and actuators in a device. Device Resource management means, for example, reading a temperature value or controlling a device-activated door lock.

You can use the Device Management services to manage device Resources and execute actions on the devices. The functionality relies on integration of:

• Device Management Connect API to your web-server application.
• Device Management Client API to your device application.

Managing resources in the device

Resource management is based on read, write, create and execute operations. All communication to the device is asynchronous and the result of an operation is delivered as an event through the event notification channel. To ensure the delivery, Device Management queues the operations and provides protocol agnostic retry logic.

Device Management Client supports Resource value reporting that can be triggered periodically, by events or tresholds. To see the value changes in the devices, you need to subscribe to the Resource and set the notification rules for periodic or treshold-triggered reporting.

The overall device communication flow:

1. Devices register to make their Resources discoverable in a standard way. See the Connecting section.
2. A web application is notified of the device registration.
3. A web application places a request for a device using POST /v2/device-requests/{device-id}.
4. Device Management queues the command for delivery and responds with 202 Accepted. See Guaranteed command delivery.
5. Device Management ensures the request is delivered to the device.
6. The device responds to Device Management.
7. Device Management sends the final asynchronous response (AsyncIDResponse) notification to the web application's event notification channel.

Guaranteed command delivery

Device Management ensures command delivery to sleepy, low bandwidth devices that may be available only occasionally, independent on the connectivity technology used. Device Management queues the commands for a device, which brings multiple benefits from the web application point of view. Messages remain in the queue until they are delivered, or they expire.

The web application:

• can issue (queue) multiple commands to a device. The device handles only one command at a time.
• does not need to spend resources on waiting for responses from limited bandwidth connections.
• does not need to have transmission retry logic for different devices and connectivity technologies.

The web application can focus on the business logic as guaranteed command delivery hides the connectivity issues.

When a command is issued to the queue, the delivery to a device in normal mode is attempted immediately. For queue mode devices, the delivery is attempted when they wake up and send a registration update to Device Management.

Guaranteed command delivery is based on server side queuing and two properties; expiry-seconds and retry. Both are command-specific and set by the web application. This enables the web application to define different messaging profiles based on the lifetime and severity of the command.

Properties

See POST /v2/device-requests/{device-id} for more information on sending commands and queuing.

Limitations

• Max 20 commands per device are stored in the queue.
• A device reconnecting frequently (less than two minute interval) may not be served at every reconnect. Resending of a queued command has a grace period to ensure meaningful use of connections and resources. If a device reconnects soon after the previous connection, the command delivery may not be triggered (this will not consume the retry count) and the command is delivered later when the device reconnects.
• A command expiring in the queue does not trigger an immediate error response (AsyncIDResponse) notification. Expired commands are cleaned out from the queues in one minute interval, which triggers the error response notification. The queue management checks the command validity before triggering the sending.
• Command expiry during transmission is not handled. The transmission logic depends on the protocol and configurations used. In CoAP protocol, the retransmission interval is around two minutes (progressive retry back off with retry intervals of 2, 4, 8, 16... 64 seconds). If the command expires during this time, retransmissions are not stopped. If a transmission succeeds, the delivery of the command is considered a success. If the transmission fails, the command falls back to the queue, which triggers a failure response REQUEST_EXPIRED

Guaranteed delivery flow to a queue mode device

In the UDP_QUEUE mode, a device tells the service not to call. For devices in this mode, the delivery attempt is triggered only when the device connects to Device Management. The device can sleep without the server trying to communicate with it:

1. A queue mode device registers to Device Management
2. The web application requests for sending a read command to the device.
3. Device Management puts the command in queue and responds with 202 Accepted.
4. The device wakes up and connects to Device Management.
5. Device Management discovers queued commands for devices and makes the first delivery attempt.
6. The device receives and processes the command and provides a response.
7. Device Management sends an AsyncIDResponse event to the web application.
8. If there are more commands in the queue, Device management tries to send the next one. For the first delivery without a response, Device Management assumes the device went back to sleep and waits for the device to reconnect.

Guaranteed delivery flow to a non-queue mode device

In non-queue mode (TCP mode) devices, the first delivery attempt takes place immediately if the server side command queue is empty. If there are commands in the queue, the new command is added to it as the last item:

1. A non-queue mode device has registered and is assumed to be connected.
2. The web application requests for sending a read command to the device.
3. Device Management puts the command in queue and responds with 202 Accepted.
4. Device Management tries to deliver the command immediately to the device but discovers that the device is not connected. If there is no response from the device within the set time, the delivery attempt stops. The command stays in the queue as the first item to be sent.
5. The device reconnects to Device Management.
6. Device Management discovers queued commands and another delivery attempt is triggered.
7. The device receives the command and provides a response.
8. Device Management sends an AsyncIDResponse event to the web application.
9. If there are more commands in the queue, Device Management tries to send the next one. For the first delivery without a response, Device Management assumes the device is temporarily out of connectivity and waits for a reconnect.

About the documentation

This section reviews the Resource model Device Management Connect uses, then explains how to use the APIs to:

1. Create and configure Objects and Resources.
2. Access and use Objects and Resources.
3. Observe Resource values.
4. Manage Resources through the Device Management Portal.