Skip to content

Commands

Commands are a way to remotely invoke an action on a device and retrieve its result. Commands are dependant on the interface used by the device: they require a bi-directional interface, like IoT Hub. Devices must be provisioned on at least one supported interface before being able to receive commands.

Note

Commands are not available when using the HTTP interface.

Commands are composed of two elements:

  • Name: formatted as string, they identify the action that the device is supposed to execute.
  • Payload: parameters passed to the device. The format depends on the underlying interface. For instance, the IoT Hub interface only supports JSON values (objects, null, raw strings, numbers, etc..).

Upon reception of the command, the device must execute it instantaneously, and return a result, whether it is successful or not. Once again, the format depends on the underlying interface.

Commands are sent through the API, after verification of the access rights of the user. They are executed synchronously: the API waits for the device response before responding to the client. Trying to execute a command on an offline device will result in an error, it will not be stored for a later execution.

Note

If synchronicity is required, it is preferable to use commands over configurations. If it is not required, configurations might be a better solution.

To understand how to send commands through the API, read the API Swagger documentation.

The following section describes how commands are handled based on the underlying interface.

IoT Hub

When using IoT Hub, commands use the direct method feature. The API forwards the command name and parameters to IoT Hub as a direct method, without reinterpreting the parameters.

Two kind of output are possible:

  • Device response: contains a status code and a payload set by the device, whether the command was successful or not
  • IoT Hub response: in case of error, for instance if the device is offline, the response will come directly from IoT Hub, and is forwarded to the client in the API response without reinterpretation.

When the API restart, it opens an IoT Hub client dedicated to the commands only when it receives a request from a client. This operation can take a few seconds, but the connection is kept alive afterwards. Consequently, the first call takes longer than the following ones, which will all benefit from the already open connection.