Telemetry 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 Telemetry API is used by Protocol Adapters to send data received from connected devices upstream. Solutions and other consumers use the API to receive data published by devices belonging to a particular tenant.

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 telemetry related use cases Hono supports.

TODO add use case diagram

Southbound Operations

The following operations can be used by Protocol Adapters to publish telemetry data received from connected devices for consumption by upstream consumers.

Upload Telemetry Data

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 telemetry/upload.

Message Flow

TODO add sequence diagram

Message Format

The following table provides an overview of the properties a client needs to set on an Upload Telemetry Data 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.
content-type	yes	properties	symbol	MUST be set to application/octet-stream if content is to be considered opaque binary data.
sample-time	no	application-properties	timestamp	MAY contain the point in time the data has been sampled by the device.
longitude	no	application-properties	float	MAY contain the longitude of the position of the device that reported the data in the payload. If this property is set latitude MUST also be set.
latitude	no	application-properties	float	MAY contain the latitude of the position of the device that reported the data in the payload. If this property is set longitude MUST also be set.

The body of the message MUST consist of a single AMQP Data section containing the telemetry data. The format and encoding of the data MUST be indicated by the content-type and (optional) content-encoding properties of the message.

Note that Hono does not return any application layer message back to the client in order to signal the outcome of the operation. Instead, AMQP message delivery states are used for that purpose as follows:

Delivery State	Description
ACCEPTED	Indicates that Hono has successfully received and processed the message.
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.

Northbound Operations

Receive Telemetry Data

Preconditions

1. Client has established an AMQP connection with Hono.
2. Client has established an AMQP link in role receiver with Hono using source address telemetry/upload/${tenantId} where ${tenantId} represents the ID of the tenant the client wants to retrieve telemetry data for.

Message Flow

TODO add sequence diagram

Message Format

The format of the messages containing the telemetry data is the same as for the Upload Telemetry Data operation.

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