The Bosch IoT Things service is built upon the Eclipse Ditto project and therfore uses its protocol. The Ditto Protocol defines a JSON-based text protocol for communicating with live devices and their digital twins.

General protocol structure and envelopes

The protocol is defined by the Eclipse Ditto project and applied for the Bosch IoT Things service respectively.

In order to comply with the protocol, a message must consist of the following three parts: Eclipse Ditto Protocol

  • A communication protocol envelope
    (e.g. AMQP, WebSocket)
  • A Ditto protocol envelope (JSON)
  • A Ditto protocol payload (JSON)



Communication protocol envelope

The communication protocol envelope is defined by the underlying messaging system used to transport/serialize the messages over the wire.
Messages are supported from a system to the Bosch IoT Things service, and from our service towards another system.
Please refer to the respective communication protocol binding for information how to encode the data in a protocol specific way.
See section Protocol bindings.

Ditto protocol envelope

The Ditto protocol envelope describes the content of the message (the affected thing entity, a message type, protocol version etc.) and allows the message to be routed by intermediary nodes to its final destination without parsing the actual payload.

As the Bosch IoT Things service is built upon the Eclipse Ditto project, the specification documented there applies accordingly. https://www.eclipse.org/ditto/protocol-specification.html#dittoProtocolEnvelope

Ditto protocol payload (JSON)

The Ditto model payload contains the application data e.g. an updated sensor value.

As the Bosch IoT Things service is built upon the Eclipse Ditto project, the specification documented there applies accordingly. https://www.eclipse.org/ditto/protocol-specification.html#dittoProtocolPayload

Ditto protocol response

When sending a command, a response can be requested. A response, can either indicate the success or the failure of the command.

As the Bosch IoT Things service is built upon the Eclipse Ditto project, the specification documented there applies accordingly. https://www.eclipse.org/ditto/protocol-specification.html#dittoProtocolResponse

Custom message headers

Custom headers of messages are delivered verbatim. When naming custom headers, it is best to attach a prefix specific to your application that does not conflict with HTTP protocol and internal headers of Things, for example ditto-*.

  • Permanent HTTP headers are to be avoided.
  • Bosch IoT Things uses the following header for messages (e.g. operation request to a gateway or device)
    • x-things-parameter-order
      Example:
      A user sets a RGB based color via UI. The correct order is provided via the value of such a header, in our example: [“red”,“green”,“blue”].
      Thus, the request body can be set in JSON notation, and the intended order of the structure is kept within the header. Only top-level keys are added to the array.
  • Bosch IoT Things uses the following headers and header prefixes internally.
    If these headers are set in the protocol message, they will be ignored and will not be delivered.
    • channel
    • direction
    • feature-id
    • raw-request-uri
    • read-subjects
    • solution-*
    • subject
    • thing-id
    • timeout-access
    • x-b3-*
    • x-cf-*
    • x-cr-*
    • x-forwarded-*
    • x-real-ip
    • x-request-*
    • x-ssl-*
    • x-url-scheme