Protocol - specification

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:

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

Eclipse Ditto Protocol

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.

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

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

tip 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

Headers

Protocol messages contain headers as JSON object with arbitrary content. There are some pre-defined headers which have special meanings:

Header key Description Possible values
correlation-id Used for correlating Protocol messages (e.g. a command would have the same correlation-id as the sent back response message. String
version Determines in which schema version the message should be interpreted. Number - currently: [1,2]
response-required Configures for command whether a response should be sent back. Boolean - default: true
If-Match Used for conditional requests. String
If-None-Match Used for conditional requests. String
ditto-originator Contains the first authorization subject of the command that caused the sending of this message. Set by IoT Things. String

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
    • ditto-*
    • 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
Imprint Legal info Privacy statement