Protocol - specification

The Bosch IoT Things service is built upon the Eclipse Ditto project and therefore 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. The keys of the JSON object are the header names; the values of the JSON object are the header values.

The header names are case-insensitive and case-preserving in the following sense:

  • Case-insensitive: Capitalization of header names does not affect evaluation of the headers; setting correlation-id or CORRELATION-ID has the same effect.
  • Case-preserving: Capitalization of headers by the sender of a Ditto protocol message is visible to the receiver, provided Bosch IoT Things does not discard or overwrite those headers.

There are some pre-defined headers which have special meanings:

Header key Description Possible values
content-type The content-type of the message, for Ditto Protocol messages: application/vnd.eclipse.ditto+json. String
correlation-id Used for correlating Protocol messages (e.g. a command would have the same correlation-id as the sent back response message. String
ditto-originator Contains the first authorization subject of the command that caused the sending of this message. Set by IoT Things. String
if-match Used for conditional requests. Has the same semantics as defined for the HTTP API. String
if-none-match Used for conditional requests. Has the same semantics as defined for the HTTP API. String
response-required Configures for command whether or not a response should be sent back. Boolean - default: true
requested-acks Defines which acknowledgements are requested for a command processed by Ditto. JsonArray of String - default: ["twin-persisted"]
ditto-weak-ack Marks weak acknowledgements issued by the Bosch IoT Things service. Boolean - default: false
timeout Defines how long the Ditto server should wait, e.g. applied when waiting for requested acknowledgements. String - e.g.: 42s or 250ms or 1m - default: 60s
version Determines in which schema version the message should be interpreted. Number - currently: [1,2]

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
    • sec-websocket-accept,
    • sec-websocket-key,
    • sec-websocket-extensions,
    • sec-websocket-protocol,
    • sec-websocket-version,
    • postman-token
Corporate information Data protection notice Legal information Support Free plans