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)
Communication protocol envelope
The communication protocol envelope is defined by the underlying
messaging system used to transport/serialize the messages over the
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
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
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|
||Used for correlating Protocol messages (e.g. a command would have the same correlation-id as the sent back response message.||
||Determines in which schema version the message should be interpreted.||
||Configures for command whether a response should be sent back.||
||Used for conditional requests.||
||Used for conditional requests.||
||Contains the first authorization subject of the command that caused the sending of this message. Set by IoT Things.||
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
- 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)
A user sets a RGB based color via UI. The correct order is provided via the value of such a header, in our example:
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
If these headers are set in the protocol message, they will be ignored and will not be delivered.