Bosch IoT Device Management - will be discontinued by mid 2024

AMQP adapter

The AMQP protocol adapter exposes AMQP based endpoints for the Telemetry, Event and Command&Control APIs of the device connectivity layer.

The AMQP adapter requires clients to authenticate during connection establishment. The adapter supports both username/password based authentication as well as client certificate based authentication as part of a TLS handshake for that purpose.

In order to do so, clients need to provide a username and a password or a client certificate when connecting to the AMQP adapter. The username must have the format auth-id@tenant-id.

The server certificate of the device connectivity layer is issued by Let’s Encrypt. Some devices directly trust Let’s Encrypt root certificate, in such case downloading the server certificate is not necessary. If that is not the case, you need to import the Let’s Encrypt certificate of the device connectivity layer in your trust store to establish a TLS connection to the AMQP adapter.

The device connectivity layer uses Let's Encrypt ISRG Root X1 certificate. The certificate can be downloaded as follows:

curl -o ISRGRootX1.crt https://letsencrypt.org/certs/isrgrootx1.pem

For the examples below the Eclipse Hono 1.12.2 command line client containing an AMQP command-line client is used.

More details on the AMQP adapter can be found in the Hono Documentation.

Table of contents

Communication patterns

Publishing telemetry data

The AMQP adapter supports publishing of telemetry data using either AT MOST ONCE (QoS 0) or AT LEAST ONCE (QoS 1) delivery semantics.

Publishing events

The AMQP adapter supports publishing of events using AT LEAST ONCE (QoS 1) delivery semantic.

Command & control

The AMQP adapter supports receiving commands by means of opening a receiver link using a device specific source address. When a device no longer wants to receiving commands anymore, it can simply close the link.

All above mentioned communication patterns can be used by devices connecting directly to the AMQP protocol adapter or by gateways connecting to the AMQP protocol adapter and acting on behalf of the actual devices.

Devices connected directly to AMQP adapter

Publishing telemetry data

  • Message Address: telemetry or t

  • Authentication: required with credentials of device

  • Message Body:

    • (optional) Arbitrary payload

Example:

Publish some JSON data for a device:

# in the directory where hono cli jar file and server certificate are located
java -jar hono-cli-*-exec.jar --spring.profiles.active=amqp-send --hono.client.host=amqp.bosch-iot-hub.com --hono.client.port=5671 --hono.client.trustStorePath=ISRGRootX1.crt --hono.client.username={auth-id}@{tenant-id} --hono.client.password={password} --message.address=telemetry --message.payload='{"temperature":20}'

Publishing events

  • Message Address: event or e

  • Authentication: required with credentials of device

  • Message Body:

    • (optional) Arbitrary payload

Example:

Publish some JSON data for a device:

# in the directory where hono cli jar file and server certificate are located
java -jar hono-cli-*-exec.jar --spring.profiles.active=amqp-send --hono.client.host=amqp.bosch-iot-hub.com --hono.client.port=5671 --hono.client.trustStorePath=ISRGRootX1.crt --hono.client.username={auth-id}@{tenant-id} --hono.client.password={password} --message.address=event --message.payload='{"alarm": 1}'


Receiving commands

  • Address of the command receiver: command

  • Authentication: required with credentials of device

  • The payload of the message contains the command payload

Start the AMQP adapter client:

# in the directory where hono cli jar file and server certificate are located
java -jar hono-cli-*-exec.jar --spring.profiles.active=amqp-command --hono.client.host=amqp.bosch-iot-hub.com --hono.client.port=5671 --hono.client.trustStorePath=ISRGRootX1.crt --hono.client.username={auth-id}@{tenant-id} --hono.client.password={password}


After successfully starting the client, a message indicating that the device is ready to receiving commands will be printed to standard output. The device is now waiting to receiving commands from the application.

To send a command to the device, open a new terminal shell and start the command application, as shown below:

java -jar hono-cli-*-exec.jar --hono.client.host=messaging.bosch-iot-hub.com --hono.client.username=messaging@{tenant-id} --hono.client.password={password} --spring.profiles.active=command,ssl


Once the command application starts successfully, enter a command name, payload and content-type of the command to send to the device.

>>>>>>>>> Enter name of command for device [{tenant-id}:{device-id}] (prefix with 'ow:' to send one-way command):
setBrightness
>>>>>>>>> Enter command payload:
some-payload
>>>>>>>>> Enter content type:
text/plain


After sending the command, the device (i.e. AMQP command client) will print out the command name and payload that it receives and automatically sends a command response to the application.

Received Command Message : [Command name: setBrightness, Command payload: some-payload]
Command response sent [outcome: Accepted{}]


Gateways connected to AMQP adapter

Gateways publish data on behalf of other devices which do not connect to a protocol adapter directly but instead are connected to the gateway. In this case the credentials provided by the gateway during connection establishment with the protocol adapter are used to authenticate the gateway whereas the message address is used to identify the device that the gateway publishes data for.

In the Gateway Mode {device-id} is the ID of an actual device, while credentials are the credentials of the gateway.

In the Gateway Mode {device-id} is the ID of an actual device, while credentials are the credentials of the gateway.

Publishing telemetry data

  • Message Address: telemetry/tenant-id/device-id or t/tenant-id/device-id

  • Authentication: required with credentials of gateway

  • Message Body:

    • (optional) Arbitrary payload

Example:

Publish some JSON data for a device through gateway:

# in the directory where hono cli jar file and server certificate are located
java -jar hono-cli-*-exec.jar --spring.profiles.active=amqp-send --hono.client.host=amqp.bosch-iot-hub.com --hono.client.port=5671 --hono.client.trustStorePath=ISRGRootX1.crt --hono.client.username={auth-id}@{tenant-id} --hono.client.password={password} --message.address=t/tenant-id/device-id

Publishing events

  • Message Address: event/tenant-id/device-id or e/tenant-id/device-id

  • Authentication: required with credentials of gateway

  • Message Body:

    • (optional) Arbitrary payload

Example:

Upload a JSON string for device through gateway:

# in the directory where hono cli jar file and server certificate are located
java -jar hono-cli-*-exec.jar --spring.profiles.active=amqp-send --hono.client.host=amqp.bosch-iot-hub.com --hono.client.port=5671 --hono.client.trustStorePath=ISRGRootX1.crt --hono.client.username={auth-id}@{tenant-id} --hono.client.password={password} --message.address=e/tenant-id/device-id

Receiving commands

An authenticated gateway receives commands and sends a device’s response to a command it has received on behalf of the device

  • Address of the command receiver:

    • gateway receiving commands for all devices it acts on behalf of: command

    • gateway receiving commands for a specific device it acts on behalf of: command/{tenant-id}/{device-id}

  • Authentication: required with credentials of gateway

  • The payload of the message contains the command payload

Error Handling

The AMQP adapter distinguishes between two types of errors when a message is published using AT LEAST ONCE delivery semantics:

  • An error caused by the client side, e.g. invalid message address, content-type, adapter disabled for tenant etc.

  • An error caused by the server side, e.g. no northbound consumers registered, messaging connection loss etc.

For a client side error, the adapter settles the message transfer with the rejected outcome and provides an error description in the corresponding disposition frame. In the case of a server-side error, the adapter settles the message with the released outcome, indicating to the client that the message itself was OK, but it cannot be delivered due to a failure beyond the control of the client. In the latter case, a client may attempt to re-send the message unaltered.

In case of terminal errors the AMQP connection to the device is closed. The errors that are classified as terminal are listed below.

  • The adapter is disabled for the tenant that the client belongs to.

  • The authenticated device or gateway is disabled or not registered.

  • The tenant is disabled or does not exist.