Skip to main content

Downlink

Sending downlink messages to devices (or other applications) allows to apply configurations or send signals to one or multiple devices (or applications). It can be used, for example, to adjust thermostats when temperature values change or create other more complex scenarios, such as set-point activation in energy communities.

Commands​

Within Apio IoT, downlink messages are represented as Commands, full fledged resources with their own REST endpoints, the structure of a command is the following:

{
  "name":"reboot",
  "projectId":"my-project-id",
  "deviceId":"my-device-1",
  "status":"pending",
  "parameters":{
    "wait":"8s"
  },
  "uuid":"810b7efb-f648-47eb-b03b-8edf290e0a27"
}

In this example, we have a command named reboot, with a single parameter, named wait holding a value equal to the string 8s. The other attributes are typically added by the platform, the most important of which status represent the status of the command. New commands are always marked pending and devices can use the API to alter its status to received completed or failed.

Receiving Commands​

info

Downlink messages are currently supported only for the MQTT protocol.

To receive commands you can subscribe to one of the relevant mqtt topics:

  • apio/core/projects/{projectId}/devices/{deviceId}/commands/downlink
  • apio/core/projects/{projectId}/commands/downlink

On this topics, you will receive messages for each submitted command, and the payload you should expect is a JSON string representing a single command, like in the example above.

Sending Commands​

HTTP API​

To send a command to a downlink device you can use the rest API as follows:

POSThttps://api.apio.network/projects/{`{projectId}`}/devices/{`{deviceId}`}/commands

Body:

{
  "name":"reboot",
  "parameters":{
    "wait":"8s"
  }
}