Event API Specification for AMQP 1.0

The Event API is used by Protocol Adapters to send event messages downstream. Business Applications and other consumers use the API to receive messages published by devices belonging to a particular tenant.

The Event API is defined by means of AMQP 1.0 message exchanges, i.e. a client needs to connect to Hono using AMQP 1.0 in order to invoke operations of the API as described in the following sections. Throughout the remainder of this page we will simply use AMQP when referring to AMQP 1.0.

The Event API for AMQP 1.0 is an alternative to the Event API for Kafka for applications that want to consume events from an AMQP Messaging Network instead of an Apache Kafka™ broker.

Southbound Operations

The following operations can be used by Protocol Adapters to forward event messages received from devices to downstream consumers like Business Applications.

Forward Event

Preconditions

1. Adapter has established an AMQP connection with the AMQP Messaging Network.
2. Adapter has established an AMQP link in role sender with the AMQP Messaging Network using target address event/${tenant_id} where ${tenant_id} is the ID of the tenant that the client wants to upload event messages for.
3. The device for which the adapter wants to send an event has been registered (see Device Registration API).

Hono supports AT LEAST ONCE delivery of Event messages only. A client therefore MUST use unsettled 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 may result in the termination of the link or connection (depending on the configuration of the AMQP Messaging Network).

The AMQP messages used to forward events to the AMQP Messaging Network MUST have their durable property set to true. The AMQP Messaging Network is expected to write such messages to a persistent store before settling the transfer with the accepted outcome.

Message Flow

The following sequence diagram illustrates the flow of messages involved in the MQTT Adapter forwarding an event to the downstream AMQP Messaging Network.

1. Device 4711 publishes an event using MQTT QoS 1.
   1. MQTT Adapter transfers data to AMQP 1.0 Messaging Network.
   2. AMQP 1.0 Messaging Network acknowledges reception of the message.
   3. MQTT Adapter acknowledges the reception of the message to the Device.

When the AMQP Messaging Network fails to settle the transfer of an event message or settles the transfer with any other outcome than accepted, the protocol adapter MUST NOT try to re-send such rejected messages but MUST indicate the failed transfer to the device if the transport protocol provides means to do so.

Message Format

See Telemetry API for definition of message format.

Northbound Operations

Receive Events

Hono delivers messages containing events reported by a particular device in the same order that they have been received in (using the Forward Event operation).

Hono supports multiple non-competing Business Application consumers of event messages for a given tenant. Hono allows each Business Application to have multiple competing consumers for event messages 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 event/${tenant_id} where ${tenant_id} represents the ID of the tenant the client wants to retrieve event messages for.

Hono supports AT LEAST ONCE delivery of Event messages only. A client therefore MUST use unsettled 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 the termination of the link.

Message Flow

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

1. AMQP 1.0 Messaging Network delivers event message to Business Application.
   1. Business Application acknowledges reception of message.

Message Format

See Telemetry API for definition of message format.

Well-known Event Message Types

Hono defines several well-known event types which have specific semantics. Events of these types are identified by means of the AMQP message’s content-type.

Empty Notification

An AMQP message containing this type of event does not have any payload, so the body of the message MUST be empty.

The AMQP 1.0 properties an event sender needs to set for an empty notification event are defined in the Telemetry API.

The relevant properties are listed again in the following table:

Connection Event

Protocol Adapters may send this type of event to indicate that a connection with a device has been established or has ended. Note that such events can only be sent for authenticated devices, though, because an event is always scoped to a tenant and the tenant of a device is established as part of the authentication process.

The AMQP message for a connection event MUST contain the following properties in addition to the standard event properties:

Each connection event’s payload MUST contain a UTF-8 encoded string representation of a single JSON object with the following fields:

The example below might be used by the MQTT adapter to indicate that a connection with a device using client identifier mqtt-client-id-1 has been established:

{
  "cause": "connected",
  "remote-id": "mqtt-client-id-1",
  "source": "hono-mqtt",
  "data": {
    "foo": "bar"
  }
}

Device Provisioning Notification

Device registries may send this event to convey provisioning related changes regarding a device. This may be used as a hook for north bound applications if further application specific logic should be implemented upon provisioning changes.

An AMQP message containing this type of event does not have any payload, so the body of the message MUST be empty.

The relevant properties are listed again in the following table: