Command & Control

Command & Control messages provide a way to send messages to a device from your application via Bosch IoT Hub.

The Bosch IoT Hub supports two types of commands:

One-way Commands

Bosch IoT Hub One-Way Command flow

One-way commands are sent from a connected business application through the Bosch IoT Hub to a connected device. These type of command is neither confirmed nor answered by the device.

The following table provides an overview of the structure of an one-way command message.

Property Mandatory Description
subject yes The name of the command to be executed by the device.
message-id yes An identifier that uniquely identifies the message at the sender side.
content-type no If present, MUST contain a Media Type as defined by RFC 2046 which describes the semantics and format of the command’s input data contained in the message payload. However, not all protocol adapters will support this property as not all transport protocols provide means to convey this information, e.g. MQTT 3.1.1 has no notion of message headers.

Request/Response Commands

Bosch IoT Hub One-Way Command flow

Request/Response commands are sent from a connected business application through the Bosch IoT Hub to a connected device. After the command was received by a device, the device confirms the receipt of the command with a HTTP status code. Additionally it can send back a generic payload as response to the command. The command sending application waits a certain amount of time for the command to complete. If the command does not return within that time it is considered failed.

The following table provides an overview of the structure of a request/response command message.

Property Mandatory Description
subject yes The name of the command to be executed by the device.
message-id yes An identifier that uniquely identifies the message at the sender side.
content-type no If present, MUST contain a Media Type as defined by RFC 2046 which describes the semantics and format of the command’s input data contained in the message payload. However, not all protocol adapters will support this property as not all transport protocols provide means to convey this information, e.g. MQTT 3.1.1 has no notion of message headers.
reply-to yes MUST contain the source address that the application wants to receive the response from. This address MUST be the same as the source address used for establishing the client’s receiver link.
correlation-id no If present, MUST contain an ID used to correlate a response message to the original request. If set, it is used as the correlation-id property in the response, otherwise the value of the message-id property is used.

For request/Response commands the business application must configure the reply-to property on which it is listening to receive the command response. The value of this property contains an AMQP 1.0 address in the format:

control/<tenant-id>/<reply-id>

The reply-id part may be chosen arbitrarily by the client, the specific use case for sending commands should be considered when doing so. The following hints might help with creating an appropriate reply-id:

  • if only one command response is expected from the device, the reply-id could be set to the device-id plus an arbitrary string to scope the command sender instance and closed again after receiving the response.
  • if several command responses are expected from the device (e.g. since multiple commands were or will be sent to it), such a link should usually remain open after the reception of any response.
  • if all command responses for the reply-id shall be received in the application, the reply-id could be set to just an arbitrary (short) string to scope the command sender instance. Such a link should usually remain open after the reception of any response.

When to use Command & Control?

Command & Control covers all use cases where you want to perform an action on connected devices. This could be for example the update of a configuration settings on that devices.

Command Delivery State

The Bosch IoT Hub confirms the receipt of the command (for one-way commands as well as for request/response commands) using a AMQP delivery state:

Delivery State Description
accepted The command has been sent to the device for processing.
released The command has not been delivered to the device because the device is (currently) not connected.
rejected The command has not been delivered to the device because it does not contain all required information.

Please note that the actual semantic of the accepted state relies on the particular protocol adapter to deliver commands to devices. Depending on the used transport protocol and the adapter’s implementation, the accepted outcome may thus indicate any of the following:

  • An attempt has been made to deliver the command to the device. However, it is unclear if the device has received (or processed) the command.
  • The device has acknowledged the reception of the command but has not processed the command yet.
  • The device has received and processed the command.

If a connected business application must ensure that a command is received and properly handled by the device, a request/repsonse-command with proper re-try handling needs to be used.

Remarks

  • To send a command to a device, the device needs currently to be connected to the Bosch IoT Hub. If a device is not connected, the sending of the command will fail with a “no credits available” exception.

  • To receive a response from a device, the business application needs to be connected to the Bosch IoT Hub. Responses to commands are not queued in the Bosch IoT Hub, devices will receive an “application unavailable” status code when no business application has a valid receiver link open.