Via telemetry you can send messages from your device to your application. There are no acknowledgement messages whether the messages really arrive their target.

Schematic view

images/confluence/download/attachments/1634788133/telemetry-example.png

Prerequisites

At this point we assume that you went through all steps described at Getting started and have already a device and a thing.

{
  "thingId": "<your.namespace>:<your-device-name>",
  "policyId": "<your.namespace>:<your-device-name>",
  "attributes": {
    "manufacturer": "Robert Bosch GmbH"
 }
}

Let us assume, as soon as the device is instantiated, it needs to add a featureZ.

Such a command can be simulated via an HTTP API call.

If you want to try out the example several times, use private browser tabs: one for authenticating for Hub APIs, and another one to use the Things API (or the Things UI).

Telemetry request

https://apidocs.bosch-iot-suite.com > Bosch IoT Hub - HTTP Adapter > telemetry/post_telemetry

Authorize
- Set authId@tenantID - as the username
- Set the password.
- Click Authorize and Close the dialog.
Execute first with the default body part shown in their API docs UI, just to try it out.
If the response code is 202, at least the authorization is correct.
Note: If your browser opens a Certificate Selection Popup Dialog, please cancel it and continue.
If you have activated the ConnectionStatus for your connection (see Reflect device connectivity status in thing) set additionally the hono-ttd .
As the Request body part was just valid JSON but not conforming the Bosch IoT Things protocol, there will be no effect on the thing entity.
Now try the "real" body part which is applicable to your thing.

Replace <your.namespace> and <your-device-name> with the real values of your thing.

{"topic":"<your.namespace>/<your-device-name>/things/twin/commands/modify","path":"/features/featureZ","value":{"properties":{"temperature":5}}}
Response - 202 is ok.
This time, we expect that the request really has an impact on the thing.

Update the thing

This part happens automatically within the Bosch IoT Things service.

Given that the thing policy allows to apply the change, the thing is enlarged with featureZ or with the new temperature value.

Potential listeners with read permission would additionally get an event.

Request the thing

Here we want to check that Bosch IoT Things has processed the command

Additionally, the solution subscribing for events of this thing should have received an event respectively.

https://apidocs.bosch-iot-suite.com - Things HTTP API > GET /things

Get a new Suite token and authorize with this at the Things API docs
Get things request to see the change has been delivered to the thing
- Click Try it out.
- Set the Id to
  <your.namespace>:<your-device-name>
- Click Execute.

The response might look as in the following code block.

{
  "thingId": "<your.namespace>:<your-device-name>",
  "policyId": "<your.namespace>:<your-device-name>",
  "attributes": {
    "manufacturer": "Robert Bosch GmbH"
  },
  "features": {
    "featureZ": {
      "properties": {
        "temperature": 5
      }
    }
  }
}

Congratulations,
you have just executed successfully the first twin command.

Find the complete ditto protocol specification examples at
https://www.eclipse.org/ditto/protocol-specification-things-create-or-modify.html#create-or-modify-all-features-of-a-thing