Receive Commands via HTTP

This page shows you how to receive commands via a HTTP client from the Bosch IoT Hub. As exemplary device the Swagger UI of the Bosch IoT Suite API Docs is used.

Preconditions

  • Bosch IoT Hub service was subscribed.
  • A test device has been registered in Bosch IoT Hub.
  • Credentials for the given device have been created in Bosch IoT Hub.
  • A consumer application is connected to the Bosch IoT Hub.

Login to Suite API Docs

To send data through the HTTP Adapter you can use the provided UI of the Suite API Docs. You can open it in a new window and follow this guide:

Suite API Docs: HTTP Adapter

Only authenticated devices are allowed to send messages to Bosch IoT Hub. To prove its identity your device has to pass the credentials registered in the previous steps.

Login to the Suite API Docs by clicking the Authorize button. The username is made up of the auth-id defined for the credential followed by a @ and the id of your tenant.

So for example if you have chosen auth-id: credential001 and your tenant-id is t123456789abcdef123456789abcdef12, the username will be like: credential001@t123456789abcdef123456789abcdef12.

The password is the plaintext password that was created during the credential registration.

Receive one-way command

  1. Follow the instructions on the Connect command sending IoT Application page to start the command sender.

  2. Navigate to the event section selecting the POST operation.

  3. Press the Try it out button.

  4. Select the application/vnd.eclipse-hono-empty-notification as Request body type.

    • This application type is used to send an empty notification to the Bosch IoT Hub. This event type can be used to indicate the server that this client is able to receive command messages.

    • Note: This notification type is used for explicitly query for an command on server side. You may also specify the hono-ttd header on /telemetry and /event calls to receive commands (“piggybacking”).

  5. Enter the value 60 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.
  6. Run the request by hitting the Execute button.

  7. Follow the instructions on the Connect command sending IoT Application page to send a one-way command to the device.

  8. You can now see the command received by the client in the response section:

    Response body:

    {
        "greeting" : "Hi, How are you?"
    }
    

    Response headers:

    content-type: application/json
    hono-command: sayGreeting
    

Receive Request/Response Command

  1. Follow the steps 1-6 of the one-way command steps above.

  2. Follow the instructions on the Connect Command sending IoT Application page to send a request response command to the device.

  3. You see the command in the server response:

    Response body:

    {
        "greeting" : "Hi, How are you?"
    }
    

    Response headers:

    content-type: application/json
    hono-command: sayGreeting
    hono-cmd-req-id: 1010be56669a-3fe9-41e5-af46-42f1ce6f911d
    
  4. Navigate to the control section selecting the first POST operation.

  5. Press the Try it out button.

  6. Enter the following data in the request form:

    • The commandRequestId of the received command (see response header of step 3)
    • A valid http status code, e.g. 200
    • The body of the answer can contain the outcome of the command. In this example set it to:
      {
         "greetingDurationInSec": 23
      }
      
  7. Run the request by hitting the Execute button.

  8. The dispatched command response should now be visible in the command client.