This section goes into the conceptual steps of your application, which will monitor or remotely control your devices.
The business application will not need to implement all device-specific protocols, but can benefit from the digital twin representation offered at the Bosch IoT Things service.
What are digital twins?
A digital twin helps to orchestrate all aspects of an IoT device and provides a unified and simplified model and API to work with this device.
Each digital twin is represented as a thing entity, and the aspects are represented as features within this thing. Some of these features might represent a state with properties, while others represent an interface to some functionality (e.g. operations or events), and some features are both.
The standard definition of how all these features can structure the status values, or which type of interfaces and functionality needs to be available, can be created using Eclipse Vorto (as function blocks). The contracts/mappings on what values are valid for each feature, operation, message, etc. we call indeed definition. The references to those definitions are kept within the Things service with the feature information.
Validating against the schemas in the definitions helps to avoid invalid twin representations.
However, some features may also be “free form”, i.e. there is no contract that defines its state/functionality.
Finally, there needs to be a place where the orchestration is described. The Things service provides policies which can be used to control the orchestration. The orchestration is effectively defined by granting access rights on different resources to various subjects.
How to execute
Create a generic sketch of your use case
Following schematic view of a user request might help you keep your application as simple as possible and use the cloud services as the “backend” for your IoT apps.
Identify who tries to use your app.
You can re-direct such a request to an identity provider of your choice.
Bosch IoT Things integrates smoothly with Bosch-ID, Bosch IoT Permissions and Google.
The request specifies which data the user is interested in
While implementing your application, please keep in mind that the Bosch IoT Things service will require various headers
(e.g. user authentication with Basic Auth, OAuth2 token, etc. as well as the API token).
The request is processed at the Bosch IoT Things service.
In case the user is allowed to see the data requested, this will be presented (in JSON notation)
In case the Thing/Feature does not exist or the user is not authorized (in the Policy) the response will report the failure with a respective description.
Get familiar with the resources that can be requested by API
Here a list of the main requests your application will probably need to implement:
Reading the thing resources:
Use a Things > GET or
Search request with the possibility to use filtering
Count things could be helpful for dashboards
Subscribe for device/thing changes
Your application can be informed about all changes.
Once the digital twin has been updated (e.g. telemetry data or events from the device have been applied) we send events to applications, which have read permission on the entity.
Such info can be forwarded via WebSocket or you can configure the connection to message brokers.
Control your device functionality
Send new configuration settings to your device
Bosch IoT Hub supports command and control patterns
See example Command and control - request-response
Change device properties
For simply setting a property value on a device that is "online" and "listening", a simple PUT request might be sufficient.
See example Command and control - one-way
For operations where you need to make sure the device has received the desired change, most probably you will need to apply the request-response pattern.
Change access rights
Additionally to your patterns for controlling the access on your business application level, the Bosch IoT Things provides policies.
Your can decide if each thing needs its own policy, or if you want to re-use the same policy for multiple things.
Find details at Policies
Decide which API fits best
Bosch IoT Things service provides various ways to interact:
A REST-like HTTP API
with a sophisticated resource layout, that allows to create, read, update and delete things and the thing's data.
A Things Java Client
which implements our API to communicate with the Things service in Java. The client itself uses the WebSocket protocol.
A Things Protocol (powered by Eclipse Ditto) which can be used
via plain WebSocket technology
via Advanced Message Queuing Protocol (AMQP)
(currently we support AMQP 0.9.1 and AMQP 1.0)
via Message Queuing Telemetry Transport (MQTT)
(currently we support MQTT 3.1.1)
to Apache Kafka
(currently we support Kafka 2.x)
Data ingestion and device control via the Bosch IoT Hub service
based on AMQP 1.0.
For details see Bosch IoT Things > Basic concepts > Which API to use?
If you need to discuss further integration, usage options, or the steps from your first prototyping, building, testing etc. towards series engineering and mass production to bring your product to life, do not hesitate to contact us via email: firstname.lastname@example.org.