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/${tenant-id}. If the target address contains a value for tenant-id then each message sent to Hono on this link MUST also contain the tenant-id application-property having the same value. If the target address doesn't contain a tenant-id then Hono will determine the tenant the device belongs to dynamically for each message sent.

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.
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 reliable transmission of telemetry data, i.e. messages containing telemetry data MAY be lost.

Message Flow

The following sequence diagram illustrates the flow of messages involved in a Protocol Adapter uploading a telemetry data message to Hono.

Note that the sequence diagram is based on the Hybrid Connection Model topology option.

1. Telemetry Endpoint connects to Dispatch Router. Dispatch Router successfully verifies credentials.

2. Protocol Adapter connects to Telemetry Endpoint.

3. Telemetry Endpoint successfully verifies credentials using Auth Service.

4. Protocol Adapter establishes link with Telemetry Endpoint for sending telemetry data for tenant TENANT.

5. Telemetry Endpoint establishes link with Dispatch Router for sending telemetry data for tenant TENANT.

6. Protocol Adapter sends temperature reading for device 4711.

7. Telemetry Endpoint successfully verifies that client is allowed to publish data for device 4711 of tenant TENANT using Auth Service.

   Open issue: should the Telemetry Endpoint also check if device really belongs to tenant?

8. Telemetry Endpoint sends temperature reading to Dispatch Router.

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
to	yes	properties	UTF-8 string	MUST be set to telemetry/${device-id} with device-id being the ID of the device the data in the payload has been reported by. The device-id used here MUST be the same as the value of the device-id application-property.
content-type	yes	properties	symbol	MUST be set to application/octet-stream if content is to be considered opaque binary data.
device-id	yes	application-properties	UTF-8 string	MUST contain the ID of the device the data in the payload has been reported by. The value of this property MUST be the same as the ${device-id} part of the to field value.
tenant-id	no	application-properties	UTF-8 string	MAY be set by the client to indicate which tenant the device belongs to. If set then this property MUST have the same value as the tenant-id given in the target address during link-establishment. If not set then the value is determined from the tenant-id given in the target address during link-establishment. Open issue: this property seems to be obsolete because we can always determine it from the link address.

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

Hono delivers messages containing telemetry data reported by a particular device in the same order that they have been received in (using the Upload Telemetry Data operation defined above). Hono MAY drop telemetry messages that it cannot deliver to any consumers. Reasons for this include that there are no consumers connected to Hono or the existing consumers are not able to process the messages from Hono fast enough. Hono supports multiple non-competing Business Application consumers of telemetry data for a given tenant. Hono allows each Business Application to have multiple competing consumers for telemetry data for a given tenant to share the load of processing the messages.

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/${tenantId} where ${tenantId} represents the ID of the tenant the client wants to retrieve telemetry data for. If the client omits the tenant-id then a default tenant is assumed.

Hono supports AT MOST ONCE delivery of messages only. A client therefore MUST use settled for the snd-settle-mode and first for the rcv-settle-mode fields of its attach frame during link establishment. All other combinations are not supported by Hono and result in a termination of the link.

A client MAY indicate to Hono during link establishment that it wants to distribute the telemetry messages received for a given tenant among multiple consumers by including a link property subscription-name whose value is shared by all other consumers of the tenant. Hono ensures that messages from a given device are delivered to the same consumer. Note that this also means that load MAY not be evenly distributed among consumers.

In addition a client MAY include a boolean link property ordering-required with value false during link establishment in order to indicate to Hono that it does not require messages being delivered strictly in order per device but instead allows for messages being distributed evenly among the consumers.

Message Flow

The following sequence diagram illustrates the flow of messages involved in a Business Application receiving a telemetry data message from Hono.

Note that the sequence diagram is based on the Hybrid Connection Model topology option.

1. Business Application connects to Dispatch Router. Dispatch Router successfully verifies credentials.
2. Business Application establishes link with Dispatch Router for receiving telemetry data for tenant TENANT. Dispatch Router successfully verifies that client is allowed to receive data for tenant TENANT (How?).
3. Dispatch Router delivers telemetry message to Business Application. Note The Business Application can only receive telemetry messages that have been uploaded to Hono after the Business Application has established the link with the Dispatch Router because telemetry messages are not stored-and-forwarded.

Message Format

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