Bosch IoT Device Management

Command and control messages

Command & control messages provide a way to send messages to a device from your application via the device connectivity layer.

The device connectivity layer supports two types of commands:

One-way commands

images/confluence/download/attachments/1982727091/command_one_way.png

One-way commands are sent from a connected business application through the device connectivity layer to a connected device. This 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

device_id

yes

The identifier of the device that the command is targeted at.

subject

yes

The name of the command to be executed by the device.

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

images/confluence/download/attachments/1982727091/command_request_response.png

Request/response commands are sent from a connected business application through the device connectivity layer 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

device_id

yes

The identifier of the device that the command is targeted at.

subject

yes

The name of the command to be executed by the device.

response-required

yes

MUST be set with a value of true, meaning that the device is required to send a response for the command.

correlation-id

yes

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.

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.

Commands in gateway mode

Gateway components can receive commands for devices which do not connect to a protocol adapter directly but instead are connected to the gateway. Corresponding devices have to be configured so that they can be used with a gateway.

If a device is configured in such a way that there can be one gateway, acting on behalf of the device, a command sent to this device will by default be directed to that gateway.

If a device is configured to be used with multiple gateways, the particular gateway that last acted on behalf of the device will be the target that commands for that device will be routed to. The mapping of device and gateway last used by the device is updated whenever a device sends a telemetry, event or command response message via the gateway. This means that for a device configured to be used via multiple gateways to receive commands, the device first has to send at least one telemetry or event message to establish which gateway to use for receiving commands for that device.

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.

Remarks

  • To send a command to a device, the device needs currently to be connected to the device connectivity layer. 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 device connectivity layer. Responses to commands are not queued in the device connectivity layer, devices will receive an “application unavailable” status code when no business application has a valid receiver link open.

  • The device connectivity layer does not guarantee the order in which the commands are sent to the device.

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