Command and control - request-response - HTTP
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. It 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 the execution the device informs the business application about success or failure of this action.
Schematic view
Prerequisites
At this point we assume that you went through all steps described at Getting started and Telemetry example - HTTP.
Open the HTTP channel with an empty notification
Log in to Bosch IoT Hub - HTTP adapter.
In the Bosch IoT Hub - HTTP Adapter API:
Navigate to the event section and select the POST operation.
Click the Try it out button.
Select application/vnd.eclipse-hono-empty-notification as Request body type.
This application type is used to send an empty notification to Bosch IoT Hub. This event type can be used to indicate to the server that this client is able to receive command messages.
This notification type is used for an explicit query for a command on the server side. You may also specify the hono-ttd header on /telemetry and /event calls to receive commands (“piggybacking”).
Enter 60 seconds to keep the connection open in the hono-ttd header.
This specifies the number of seconds that the server keeps the HTTP connection to the client open to send a command downstream.Run the request by clicking the Execute button.
Send a message
You can use again the Bosch IoT Suite UI to send a message.
The open connection will be visualized there with a green plug icon.
The message is "do-something", type is Text and the text to send is Execute the task.
The message will wait itself for 60 seconds for a response from the device.
Alternatively, if you prefer to send the message via the plain Bosch IoT Things API, find details in the collapsed section.
Open Suite API docs - Bosch IoT Things HTTP API 2.
Authorize with a Suite OAuth token.
Message resource
Navigate to POST /things/{thingId}/inbox/messages/{messageSubject}.
Click Try it out to access the entry fields.
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 Request 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 text/plain format.
Click Execute.
You have sent a command which will wait 60 seconds for the response.
Receive a request-response command
Focus back to the Browser tab where you have sent the empty event.
In your Response body you will find the command
{"topic":"my.demo/device/things/live/messages/do-something","headers":{"version":2,"sec-fetch-site":"same-site","origin":"https://console.bosch-iot-suite.com","sec-fetch-mode":"cors","accept-language":"de-DE","dnt":"1","accept":"application/json, text/plain, */*","x-forwarded-scheme":"https","accept-encoding":"gzip, deflate, br","sec-fetch-dest":"empty","timeout":"60","response-required":true,"ditto-originator":"iot-suite:xxx/service-instance.xxx.iot-things@developer-console","requested-acks":[],"ditto-message-direction":"TO","ditto-message-subject":"do-something","ditto-message-thing-id":"my.demo:device","correlation-id":"xxx","content-type":"text/plain","timestamp":"2021-11-18T21:16:28.418193578+01:00"},"path":"/inbox/messages/do-something","value":"Execute the task."}In your Response headers you will find the headers
content-length: 880 content-type: text/plain hono-cmd-req-id: 224678a54e3-9442-46ed-90bc-f2df0c85d831 hono-command: do-something Copy the value of the hono-cmd-req-id to your clipboard, as you will need it for the next request.
Send the response from device back to the cloud services
As the UI is now waiting for a response within the given timeout, we will create a short answer via the Hub HTTP command.
Open the command section. In it:
POST/command/res/{commandRequestId} - Sending a Response to a Command
Enter the value copied above as the value of commandRequestId
Enter 200 for hono-cmd-status to signal success
The request body could hold {"value":"success": true"}
Forward the response to the solution (via Things)
Bosch IoT Things automatically applies the change and forwards the received response to the solution.
The UI where you triggered the message should display success. Furthermore, the red icon for the plug shows that the 60s from the very first call have expired and the device is again offline now.
