Bosch IoT Device Management

Manage attributes via Hub HTTP API

In general, the Things service regards attributes as something that does not change very often.

However, by default you should be allowed to read and write attributes. See Examples > Policy examples > Initial policy.

Goal

Let us assume, your device hello-world-device-01 already has manufacturer attributes (like created in section Manage attributes via Bosch IoT Suite Console), and you want to add further attributes, or change a value.

Procedure

Navigate to the API docs

Bosch IoT Hub > HTTP Adapter > telemetry.

Authorize

The pop-up offers basic authentication.

In this example, you will mimic the hello-world-device.
Therefore, please authenticate with:

  • the username auth-ID@Hub-tenant-ID and

  • the password

as you have set them at the start, in the provisioning.

You can copy the Username from the Bosch IoT Suite console.

images/confluence/download/attachments/1634788021/hello-world-hub-username.png

Navigate Things > hello world > Device > Credentials, from there you can copy the Username to the clipboard and use it in the Authorization pop-up at the HTTP API docs.

images/confluence/download/attachments/1634788021/hub-basic-auth.png

Close the popup.

Publish telemetry data

  • Navigate to POST /telemetry.

  • Click Try it out - to get access to the input fields.

  • Setting the QoS-Level (Quality of Service) for publishing telemetry messages is optional and can stay empty.

  • Setting the hono-ttd (time ‘til disconnect) is optional and can stay empty.

  • Set the Request body.

    • The type must be application/json.

    • The content must respect the thing's notation.
      In our case the request body looks like this:

      {
      "topic": "xxx-add-your-namespace-xxx/hello-world-device-01/things/twin/commands/modify",
      "path": "/attributes/manufacturer/",
      "value": {
      "name": "ACME demo corp.",
      "location": "London",
      "serialno": "420",
      "model": "fancy"
      }
      }

      Make sure to replace "xxx-add-your-namespace-xxx" with your own namespace.
      To learn more about the protocol see https://www.eclipse.org/ditto/protocol-examples-modifyattributes.html.

  • Click Execute.

The response code 202 shows success.

Result

The changes are forwarded via the managed connection to Bosch IoT Things.

Check your work

The easiest way to see if setting a new serialno succeeded is to open the Attributes section in Bosch IoT Suite Console.

In case you see no manufacturer attributes at all, retry the request above with a merge command (instead of put).

In our example the Request body would be different:

  • Type for am merge request is application/merge-patch+json.

  • The content is with a different topic (merge instead of modify).

    {
    "topic": "xxx-add-your-namespace-xxx/hello-world-device-01/things/twin/commands/merge",
    "path": "/attributes/manufacturer/",
    "value": {
    "name": "ACME demo corp.",
    "location": "London",
    "serialno": "420",
    "model": "fancy"
    }
    }

See further Eclipse Ditto examples at https://www.eclipse.org/ditto/protocol-examples-mergeattributes.html.

Tips for debugging

In case the response is 202 but the Things service still cannot "digest" the data, you can trace at the connection how the payload looks like when it arrives at Bosch IoT Things.
Therefore, please check if the change has be applied.

  • From the Bosch IoT Console navigate to Connections/Integrations

  • Make sure the icon for the connection called Device via Bosch IoT Hub is plugged. In case it is unplugged open the connection and re-try to send the request from Bosch IoT Hub.

  • The tab Metrics might display numbers in a "failure" cell. In such a case, activate the Log entries and Refresh automatically.
    Re-try the POST request and see the detailed failure message, which might give a hint on what went wrong.