Downlink

Last modified: Jun 5, 2019 @ 06:29

HTTP Gateway also supports the downlink commands. Downlink operations start from IoT Accelerator APIs and terminate in the specified device. External applications can do READ, WRITE, EXECUTE, OBSERVE, and CANCELOBSERVE operations towards devices via IoT Accelerator APIs.

Note: These operations are part of the DDM APIs and they are compatible with LwM2M.

For an end-to-end successful downlink flow, the following criteria must be met on the device side:

  • Device must have been already registered to the gateway. This happens automatically when a TLS session is established between device and gateway.
  • Device must have a running HTTPS server with CA and signed Client Certificate.
  • Device must be publicly accessible.

Note:

  • TLS session can be established with 1 single certificate signed by the specified CA and it can be used as server certificate for downlink as well as client certificate for uplink.
  • The default server port for device is assumed to be 8443. In case to use a different port, then the device must have been registered with those parameters to the Gateway by using the register interface. See Uplink interface description section, for more details.

How it works

  • Downlink operation to a device may be sent over DDM REST APIs. The details are as given below.
  • After the request is received by DDM, the request is queued and the user gets a response right away. The rest of the flow happens asynchronously.
  • Gateway finds the device IP, URI Path, and Port from the database.
  • Then the Gateway performs a REST POST operation to the device URL.
  • If device is not reachable, then the Gateway performs a retry with pre-configured number of attempts and then logs the failure. The command is dropped, and the application must send it again.

Note: The Service Operator configures the retry numbers. The default value is 3.

The downlink commands can be sent to a device using any REST API supported client.

See Support for Downlink Commands, for more details.

Resource Read Success:

Send Read Request from DDM

The following pictures are examples of how a User performs a Read operation from DDM GUI:

Value After Read:

API mapping between IoT Accelerator side and device is listed in the table below:

Command Mapping

DDM API Device API
Operation Type: READ Message Body: Empty
GET /api/v3/resources/{id}/read GET https://{device.ip}:{device.port}/api/v1/{obj_id}/{obj_instance}/{resource_id}
Operation Type: READ Message Body: Senml (JSON)
PUT /api/v3/resources/{id}/read POST https://{device.ip}:{device.port}/api/v1/read
Operation Type: WRITE Message Body: Senml (JSON)
PUT /api/v3/resources/{id}/write PUT https://{device.ip}:{device.port}/api/v1/
Operation Type: EXECUTE Message Body: Senml (JSON)
POST /api/v3/resources/{id}/execute POST https://{device.ip}:{device.port}/api/v1/execute
Operation Type: OBSERVE Message Body: Senml (JSON)
PUT /api/v3/resources/{id}/observe POST https://{device.ip}:{device.port}/api/v1/observe
Operation Type: CANCEL_OBSERVE Message Body: Senml (JSON)
PUT /api/v3/resources/{id}/cancelobserve POST https://{device.ip}:{device.port}/api/v1/cancelobserve

Note: By default, “/api/v1/” is the device path but it can be overwritten by using the register api.

The following are examples of requests sent to a device as part of the different Downlink operations:

Refer to section Data Model Definition for detailed body format.

Example Curl RequestReading Temperature (READ)

$ curl 'https://{device.ip}:8443/api/v1/3303/0/5700' \    -i -X GET \    --cert client.crt \     --key client.key  \    --cacert rootca.crt

Example Curl Request: Turn on Lights (WRITE)

$ curl 'https://{device.ip}:8443/api/v1' \    -i -X PUT \    --cert client.crt \     --key client.key  \    --cacert rootca.crt \-d ‘[{“n":"3311/0/5850","vs":"On”}]'

Example Curl Request: Reboot the Device (EXECUTE)

$ curl 'https://{device.ip}:8443/api/v1/execute' \    -i -X POST \    --cert client.crt \     --key client.key  \    --cacert rootca.crt \-d ‘[{“n":"3/0/4","vs": ""}]'

Example Curl Request: Observe the Temperature (OBSERVE)

$ curl 'https://{device.ip}:8443/api/v1/observe' \    -i -X POST \    --cert client.crt \     --key client.key  \    --cacert rootca.crt \-d ‘[{“n":"3303/0/5700","vs": ""}]'

Example Curl Request: Observe the Temperature (CANCELOBSERVE)

$ curl 'https://{device.ip}:8443/api/v1/cancelobserve' \    -i -X POST \    --cert client.crt \     --key client.key  \    --cacert rootca.crt \-d ‘[{“n":"3303/0/5700","vs": ""}]'