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 Devices to send data downstream. Business Applications 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.

Southbound Operations

The following operations can be used by Devices and/or Protocol Adapters to which the devices are connected to publish telemetry data for consumption by downstream consumers like Business Applications.

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. The client indicates its preferred message delivery mode by means of the snd-settle-mode and rcv-settle-mode fields of its attach frame during link establishment. Hono will receive messages using a delivery mode according to the following table: | snd-settle-mode | rcv-settle-mode | Delivery semantics | | :--------------------- | :--------------------- | :----------------- | | unsettled, mixed | first | Hono will acknowledge and settle received messages spontaneously. Hono will accept any re-delivered messages. This corresponds to AT LEAST ONCE delivery. | | settled | first | Hono will acknowledge and settle received messages spontaneously. This is the fastest mode of delivery. This corresponds to AT MOST ONCE delivery. | All other combinations are not supported by Hono and result in a termination of the link. In particular, Hono does not support EXACTLY ONCE delivery semantics for telemetry data for performance reasons.

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 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.

Any additional properties set by the client in either the properties or application-properties sections are preserved by Hono, i.e. these properties will also be contained in the message delivered to consumers.

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. The client indicates its preferred message delivery mode by means of the snd-settle-mode and rcv-settle-mode fields of its attach frame during link establishment. Hono will deliver messages to the according to the following table: | snd-settle-mode | rcv-settle-mode | Delivery semantics | | :--------------------- | :--------------------- | :----------------- | | unsettled | first | Hono will re-send unsettled messages if the connection to the client is lost during delivery. This corresponds to AT LEAST ONCE delivery. The client must be prepared to handle duplicate message in this mode. | | settled | first | Hono will send messages AT MOST ONCE, regardless of whether the client has acknowledged reception of the message or not. This is the fastest mode of delivery. | All other combinations are not supported by Hono and result in a termination of the link.

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.