MQTT Adapter

The MQTT protocol adapter exposes an MQTT topic hierarchy for publishing messages and events to Bosch IoT Hub’s Telemetry and Event endpoints.

The adapter does not behave like a general purpose MQTT broker. Therefore the following applies to the adapter: * Supports MQTT 3.1.1 only. * Does not maintain session state for clients. Therefore setting the clean session flag on the client side does not have an impact on the adapter. The adapter will set the session present to 0 in the CONNACK packet in any case. * Ignores any Will contained in the CONNECT packet. * Only supports the topic names mentioned in the sections below. Custom topics are not supported. * Does not support retaining messages. But if the retain flag is present in a message, then a x-opt-retain message annotation is added to the AMQP 1.0 message sent to the business application. The application can then decide to react upon the presence of this annotation.

Establishing the connection

The MQTT adapter requires clients to authenticate during connection establishment. The adapter supports both username/password based authentication as well as client certificate based authentication. In order to do so, clients need to provide a username and a password in the MQTT CONNECT packet or a client certificate. The username must have the format auth-id@tenant-id.

The server certificate of Bosch IoT Hub is issued by Let’s Encrypt. Some devices directly trust the 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 Bosch IoT Hub in your trust store to establish a TLS connection to the MQTT adapter.

For the examples below mosquitto_pub is used. mosquitto_pub needs the server certificate to establish a TLS connection to Bosch IoT Hub. The certificate can be downloaded as follows:

curl -o iothub.crt https://docs.bosch-iot-suite.com/hub/cert/iothub.crt

Inactivity Timeout

The client should provide a Keep Alive value of less than 60s in the MQTT CONNECT packet to ensure that connection issues can be detected. Connected devices which are neither sending nor receiving data will be disconnected after one and a half times the Keep Alive time period, or after 60s, whichever comes first. To keep the connection open a device must send MQTT PINGREQ packages if needed to indicate to the server that the device is still active.

Note that if a device is subscribed to receive commands and the MQTT connection fails, a subsequent successful new connection and command subscription by the client may still result in commands not getting delivered until the Keep Alive time period has elapsed and the server detects the connection failure. This should be taken into consideration when choosing the Keep Alive value.

Communication Patterns

Publishing Telemetry Data

The MQTT adapter supports publishing of telemetry data by means of MQTT PUBLISH packets using QoS 0 or QoS 1.

Publishing Events

The MQTT adapter supports publishing of events by means of MQTT PUBLISH packets using QoS 1 only. The adapter will send an MQTT PUBACK packet to the client once the event has been settled with the accepted outcome by the AMQP 1.0 Messaging Network.

Command and Control

The MQTT adapter supports receiving commands by means of MQTT SUBSCRIBE. Devices can subscribe to commands with QoS 0 or QoS 1. The responses to commands can being published using either QoS 0 or QoS 1.

All above mentioned communication patterns can be used by devices connecting directly to the MQTT protocol adapter or by gateways connecting to the MQTT protocol adapter and acting on behalf of the actual devices. See Gateway Mode for a more detailed description.

Devices connected directly to MQTT Adapter

Publish Telemetry Data

  • Topic: telemetry
  • Authentication: required with credentials of device
  • Payload:
    • (required) Arbitrary payload

Example

Upload a JSON string for device:

mosquitto_pub -h mqtt.bosch-iot-hub.com -p 8883 -u {auth-id}@{tenant-id} -P {password} -t telemetry -m '{"temp": 5}' --cafile iothub.crt

Publish Events

  • Topic: event
  • Authentication: required with credentials of device
  • Payload:
    • (required) Arbitrary payload

Example

Upload a JSON string for device:

mosquitto_pub -h mqtt.bosch-iot-hub.com -p 8883 -u {auth-id}@{tenant-id} -P {password} -t event -m '{"alarm": 1}' -q 1 --cafile iothub.crt

Receive Commands

  • Topic Filter: command///req/#

  • The actual topic is structured as follows:

    • for one-way commands: command///req//{command-subject}
    • for request/response commands command///req/{req-id}/{command-subject}

    Parameters:

    command-subject: The command subject (e.g. the name of the command to execute)

  • QoS: Devices can subscribe with QoS 1 or QoS 0.

  • Authentication: required with credentials of device.

  • The payload of the message contains the command payload.

Subscribe to command topic:

mosquitto_sub -d -h mqtt.bosch-iot-hub.com -p 8883 -u {auth-id}@{tenant-id} -P {secret} -k 30 --cafile iothub.crt -t command///req/#
Note: Previous versions of Bosch IoT Hub used topic filter command/+/+/req/# for subscribing to commands. This old topic is still supported but deprecated.

Send a Response to a Command

  • Topic: command///res/{req-id}/{status-code}
  • req-id: the unique identifier of the command execution request
  • status-code: a HTTP status code indicating the outcome of executing the command.
  • Authentication: required with credentials of device
  • Payload:
    • (required) Arbitrary command payload

Send back command response:

mosquitto_pub -d -h mqtt.bosch-iot-hub.com -p 8883 -u {auth-id}@{tenant-id} -P {secret} --cafile iothub.crt -t command///res/{req-id}/200 -m '{"greetingDurationInSec": 23}'

Gateways connected to MQTT Adapter

Publish Telemetry Data

  • Topic: telemetry/{tenant-id}/{device-id}
  • Authentication: required with credentials of gateway
  • Payload:
    • (required) Arbitrary payload

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

Example

Upload a JSON string for device through gateway:

mosquitto_pub -h mqtt.bosch-iot-hub.com -p 8883 -u {auth-id}@{tenant-id} -P {password} -t telemetry/{tenant-id}/{device-id} -m '{"temp": 5}' --cafile iothub.crt

Publish Events

  • Topic: event/{tenant-id}/{device-id}
  • Authentication: required with credentials of gateway
  • Payload:
    • (required) Arbitrary payload

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

Example

Upload a JSON string for device through gateway:

mosquitto_pub -h mqtt.bosch-iot-hub.com -p 8883 -u {auth-id}@{tenant-id} -P {password} -t event/{tenant-id}/{device-id} -m '{"alarm": 5}' -q 1 --cafile iothub.crt

Receive Commands

The gateway may receive commands for all devices in whose behalf it acts using topic filter command//+/req/# or for a specific device using topic filter command//${device-id}/req//{command-subject}.

  • Topic Filter to subscribe to commands for all devices in whose behalf a gateway acts: command//+/req/#
  • The actual topic is structured as follows:
    • for one-way commands for all devices: command//+/req//{command-subject}
    • for request/response commands for all devices: command//+/req/{req-id}/{command-subject}
  • Topic Filter to subscribe only to commands for a specific device, an authenticated gateway uses the topic filter command//${device-id}/req/#
  • The actual topic is structured as follows:
    • for one-way commands for a specific device: command//${device-id}/req//{command-subject}
    • for request/response commands for a specific device: command//${device-id}/req/{req-id}/{command-subject}
  • QoS: Devices can subscribe with QoS 1 or QoS 0.
  • Authentication: required with credentials of gateway.
  • The payload of the message contains the command payload.

​ Subscribe to command topic:

​ A subscription to commands for all devices that a gateway acts on behalf of looks like this:

mosquitto_sub -d -h mqtt.bosch-iot-hub.com -p 8883 -u {auth-id}@{tenant-id} -P {secret} -k 30 --cafile iothub.crt -t command//+/req/#

​ A subscription to commands for a specific device can be done like this:

mosquitto_sub -d -h mqtt.bosch-iot-hub.com -p 8883 -u {auth-id}@{tenant-id} -P {secret} -k 30 --cafile iothub.crt -t command//{device-id}/req/#   

Send a Response to a Command

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

  • Topic: command//${device-id}/res/${req-id}/${status-code}
    • req-id: the unique identifier of the command execution request
    • status-code: a HTTP status code indicating the outcome of executing the command.
  • Authentication: required with credentials of gateway
  • Payload:
    • (required) Arbitrary command payload

Send back command response:

mosquitto_pub -d -h mqtt.bosch-iot-hub.com -p 8883 -u {auth-id}@{tenant-id} -P {secret} --cafile iothub.crt -t command//{device-id}/res/{req-id}/200 -m '{"greetingDurationInSec": 23}'