Command and control - request-response

Request-response commands are sent from a connected business solution through the Bosch IoT Things and Bosch IoT Hub to a connected device.

We assume your device is ready to listen and that you send a command. This will be forwarded automatically to your device.
After the command has been processed by the device, the device indicates the status of execution with a HTTP status code.
Additionally it can send back a generic payload as response to the command.

The application can use request-response type of communication to invoke an action on the device, e.g. "print the barcode" or "water the flowers". After execution the device informs the business application about success or failure of this action.

Schematic view

images/confluence/download/attachments/894252912/request-response.png

Prerequisites

Create command subscriber

This step is similar as in the use case with one-way command.

mosquitto_sub -d -h mqtt.bosch-iot-hub.com -p 8883 -u <authId>@<tenantId> -P <your-password> --cafile iothub.crt -k 30 -t control/+/+/req/#

Make sure you replace all parameters correctly.

Send a message via Things API

  • Open Suite API docs - Things HTTP API 2

  • Authorize with Suite OAuth token.

    images/confluence/download/attachments/894252912/auth-things-api.png
  • Message resource

    • POST /things/{thingId}/inbox/messages/{messageSubject} - Send a message TO a specific thing

    • Set the thing ID (this is required)

    • Set the messageSubject (this is required) - in our case it is: "do-something".

    • Set the timeout (this is required) - in our example we have set it to 60 seconds.

    • Set the body.
      The body can be sent in JSON format (choose application/json), octet-stream (choose application/octet-stream) or plain text (choose text/plain).
      Our example shows plain text format.
      images/confluence/download/attachments/894252912/2019-04-30_15h58_04.png

    • Execute

    • You have sent a command which will wait 60 seconds for the response.

Receive a request-response command

You should see the command message printed out on the command line:

Client mosqsub/XXXXXX-XXXXXXS received PUBLISH (d0, q0, r0, m0, 'control///req/024da27b390-9361-4a4e-a272-3ace509c5b59replies/do-something', ... (637 bytes))
 
{
"topic": "<your.namespace>/<your-device-name>/things/live/messages/do-something",
"headers": {
 "correlation-id": "024da27b390-9361-4a4e-a272-3ace509c5b59",
"x-forwarded-port": "443",
"version": 2,
"timeout":"60",
"accept":"*/*",
"host":"things.eu-1.bosch-iot-suite.com",
"content-type":"text/plain",
"accept-encoding":"gzip, deflate, br",
"timestamp":"2019-07-24T15:33:30.588+02:00"}
},
"path": "/inbox/messages/do-something",
"value": "Execute the task."
}

The topic of the command message was published and contains in this example the following information:

  • A request ID (see value of the header "x-request-id") - this is the unique ID of the command message for which this answer is for in Bosch IoT Hub.

  • The message subject is do-something (see last word in the path) - it describes the command message sent to the device.

The body of the command message contains in this example the following information:

  • A correlation ID (see value of the header " correlation-id ") - this is the unique ID of the message for which this answer is for in Bosch IoT Things.

  • The payload of the command message.

Send the response from device back to the cloud services

Send the response of the command message using the mosquitto_pub command:

mosquitto_pub -d -h mqtt.bosch-iot-hub.com -p 8883 -u <authId>@<tenantId> -P <your-password> --cafile iothub.crt -k 30 -t 'control///res/024da27b390-9361-4a4e-a272-3ace509c5b59replies/200' -m \
"{\"topic\":\"<your.namespace>/<your-device-name>/things/live/messages/do-something\",
\"headers\":{\"correlation-id\":\"<your-correlation-id>\",
\"version\":2,
\"content-type\":\"text/plain\"},
\"path\":\"/inbox/messages/do-something\",
\"value\":\"success: true\",
\"status\": 200 }"

The topic of the response contains in this example the following information:

  • A request ID (in our example 024da27b390-9361-4a4e-a272-3ace509c5b59replies ) - this is exactly the unique ID of the command for which this answer is for in Bosch IoT Hub.

  • <authId> the ID of the credential that was created during device provisioning.

  • <tenantId> the ID of your tenant.

  • <your-password> the password that was registered with the credential.

The body of the response contains in this example the following information:

  • A correlation ID (in our example da27b390-9361-4a4e-a272-3ace509c5b59) - this is the unique ID of the message for which this answer is for in Things.

  • The payload of the response.

  • 200 the return status code of message.

Forward the response to the solution (via Things)

Bosch IoT Things automatically applies the change and forwards the received response to the solution.

images/confluence/download/attachments/894252912/Response_Things.png