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 MQTT adapter requires clients to authenticate during connection establishment. In order to do so, clients need to provide a username and a password in the MQTT CONNECT packet. The username must have the form auth-id@tenant-id.

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

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

Publish Telemetry Data

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

Publish Telemetry Data from Device

  • 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 Telemetry Data from Gateway

  • 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

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.

Publish Events from Device

  • 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

Publish Events from Gateway

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

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

Command and Control

The MQTT adapter supports receiving commands by means of MQTT SUBSCRIBE.

Note: Previous versions of Bosch IoT Hub used control instead of command as topic prefix. Using the control prefix is still supported but deprecated. The deprecated endpoints will be supported by Bosch IoT Hub until the end of February 2020.

Receive commands

  • Topic Filter: command/+/+/req/#
    • The actual topic is structured as follows:
    • for one-way commands: command///req//{command-subject}[/*][/property-bag]
    • for request/response commands command///req/{req-id}/{command-subject}[/*][/property-bag]

    Parameters:

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

    property-bag: is an optional collection of properties intended for the receiver of the message. A property bag is only allowed at the very end of a topic. It always starts with a ? character, followed by pairs of URL encoded property names and values that are separated by &.

  • 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/#

Sending 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}'

Inactivity Timeout

Connected devices which are neither sending nor receiving data will be disconnected after 60 seconds of inactivity. To keep the connection open a device must send MQTT PINGREQ packages to indicate the server that the device is still active.