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 Hono. Control message can be used to execute device action, like updating a configuration, installing a software component or activating actuator.

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

The Command&Control 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 Hono.

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
correlation-id	yes	properties	UTF-8 string	MUST contain the correlation ID used to match incoming control message with the response message containing result of execution.
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	yes	application-properties	UTF-8 string	MAY be set by the client to indicate which tenant the the device belongs to.
command	no	application-properties	UTF-8 string	MUST contain the command to be executed by a device.

If a control message requires additional data to be properly executed, the body of the message MUST consist of a single AMQP Data section containing a control message 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 a consideration.

Sending back control message execution result

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

Preconditions

1. Client has established an AMQP connection with Hono.
2. Client has established an AMQP link in role sender with Hono using target address control-reply/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
correlation-id	yes	properties	UTF-8 string	MUST contain the correlation ID used to match incoming control message with the response message containing result of execution.
status	yes	application-properties	UTF-8 string	MUST indicates the status of the execution. 0 for success. 1 for failure.

If a control message response contains some additional diagnostic information, the body of the message MUST consist of a single AMQP Data section containing a control message data. The body must be a descriptive message indicating what happened during the control message execution. It is primarily used for monitoring and debugging purposes. The format and encoding of the data MUST be indicated by the content-type and (optional) content-encoding properties of the message.

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 target address control/tenantId/deviceId 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.