Device Registration 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 Device Registration API is used to make Hono aware of devices that will connect to the service and send telemetry data. It can be used by Protocol Adapters to register devices that are not directly connected to Hono using an AMQP 1.0 connection. Solutions and other consumers may use the API to obtain information about a single device that is registered to Hono. (tbd??)

The Device Registration 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.

Operations

The following operations can be used by clients to register devices. in real world scenarios the provisioning of devices will most likely be an orchestrated process spanning multiple components of which Hono will only be one. Conducting and orchestrating the overall provisioning process is not in scope of Hono. However, Hono's device registration API can easily be used as part of such an overall provisioning process.

Register/Deregister device

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 registration/${tenant_id}.
3. Client has established an AMQP link in role receiver with Hono using source address registration/${tenant_id} Open issue: use dynamic reply address

Message Flow

TODO add sequence diagram

Message Format

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

Name	Mandatory	Location	Type	Description
device_id	yes	application-properties	UTF-8 string	MUST contain the ID of the device.
action	yes	application-properties	UTF-8 string	MUST contain the action (add/remove) that should be executed.
message-id	yes	properties	UTF-8 string	MUST contain the message ID used to match incoming message with the response message containing result of execution.

The body of the message is empty.

AMQP message delivery states are used as follows:

Delivery State	Description
ACCEPTED	Indicates that Hono has successfully received and accepted the message for processing.
REJECTED	Indicates that Hono has received the message but was not able to process it. The error field contains information regarding the reason why. Clients should not try to re-send the message using the same message properties in this case.

Response

Name	Mandatory	Location	Type	Description
device_id	yes	application-properties	UTF-8 string	MUST contain the ID of the device.
tenant_id	yes	application-properties	UTF-8 string	MUST contain the tenant to which the device belongs to.
status	yes	application-properties	int	MUST contain the status code indicating the result of the operation.
correlation-id	yes	properties	UTF-8 string	MUST contain the ID of the request message that this message contains the result of execution for.

Depending on the status code the message body is either empty (success) or contains a detailed description of the error that occurred (error format tbd.).

Retrieve information about a registered device

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 registration/${tenant_id}.
3. Client has established an AMQP link in role receiver with Hono using source address registration/${tenant_id} Open issue: use dynamic reply address

Message Flow

TODO add sequence diagram

Message Format

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

Name	Mandatory	Location	Type	Description
device_id	yes	application-properties	UTF-8 string	MUST contain the ID of the device to be queried.
action	yes	application-properties	UTF-8 string	MUST contain the action get.
message-id	yes	properties	UTF-8 string	MUST contain the message ID used to match incoming message with the response message containing result of execution.

The message body is empty.

AMQP message delivery states are used as follows:

Delivery State	Description
ACCEPTED	Indicates that Hono has successfully received and has accepted the message for processing.
REJECTED	Indicates that Hono has received the message but was not able to process it. The error field contains information regarding the reason why. Clients should not try to re-send the message using the same message properties in this case.

Response

The client receives a response with status success if the device with the given device_id is registered or failure if the device_id is unknown to Hono.

Name	Mandatory	Location	Type	Description
device_id	yes	application-properties	UTF-8 string	MUST contain the ID of the device.
tenant_id	yes	application-properties	UTF-8 string	MUST contain the tenant to which the device belongs to.
status	yes	properties	int	MUST contain the status code indicating the result of the operation. 0 for success i.e. the device is registered, 1 for failure i.e was not found or the user has no permission to see it.
correlation-id	yes	properties	UTF-8 string	MUST contain the correlation ID used to match incoming message with the response message containing result of execution.

The message body is empty.