Command And Control API

NB: THIS IS A FIRST DRAFT VERSION OF THE API SPEC AND THUS STILL SUBJECT TO DISCUSSION. IF YOU THINK THAT THE SPEC SHOULD BE CHANGED OR CAN BE IMPROVED PLEASE DO NOT HESITATE TO OPEN AN ISSUE OR DROP US A LINE ON THE MAILING LIST.

The Command and Control API is used by devices to receive control messages from IoT Connector. Control message can be used to execute device action, like updating a configuration, installing a software component or activating actuator.

A device can be connected to the IoT Connector directly (using AMQP connection) or via protocol adapter (for example via MQTT, LWM2M, etc). Device can also poll IoT Connector or protocol adapter periodically in order to command&control messages without maintaining a constant connection to Hono infrastructure.

The Telemetry API is defined by means of AMQP 1.0 message exchanges, i.e. a client needs to connect to Hono using an AMQP 1.0 client in order to invoke operations of the API as described in the following sections.

Use Cases

The following diagram provides an overview of the command&control related use cases Hono supports.

TODO add use case diagram

Southbound Operations

The following operations can be used by Protocol Adapters to receive command&control messages sent from the IoT Connector.

Receiving control message

Preconditions

1. Client has established an AMQP connection with Hono.
2. Client has established an AMQP link in role receiver with Hono using target address control/deviceId. Where deviceId is an ID of the device to receive the control message.

Message Flow

TODO add sequence diagram

Message Format

The following table provides an overview of the properties a client needs to set on a Control message.

Name	Mandatory	Location	Type	Description
device-id	yes	application-properties	UTF-8 string	MUST contain the ID of the device the data in the payload has been reported by.
tenant-id	no	application-properties	UTF-8 string	MAY be set by the client to indicate which tenant the the device belongs to.
command	yes	application-properties	UTF-8 string	MUST contain the command to be executed by device.

The body of the message MAY consist of a single AMQP Data section containing the telemetry data. The format and encoding of the data is indicated by the command. It is up to the device to interpret the incoming body by taking command into consideration.

Response

After execution of the control message on a device, device MUST sent a response message indicating the status of that execution.

Name	Mandatory	Location	Type	Description
status	yes	application-properties	UTF-8 string	MUST indicates the status of the execution. 0 for success. 1 for failure.
message	no	body	UTF-8 string	Returns descriptive message indicating what happended during the control message execution. Primarily used for monitoring and debugging purposes.

Northbound Operations

Send control message

Preconditions

1. Client has established an AMQP connection with Hono.
2. Client has established an AMQP link in role sender with Hono using source address control/deviceId/tenantId where deviceId represents a target device and tenantId represents the ID of the tenant the client.

Message Flow

TODO add sequence diagram

Message Format

The format of the messages containing the control message is the same as for the Receiving control message operation.

TODO specify delivery states used to signal successful transmission of data.