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.
Table of contents:
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, and Google.
In case you need a custom OAuth2 provider, this involves further preparation steps.
See Configure a custom OAuth2 authorization provider.
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.
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 or its feature does not exist (or the user is not authorized - via the policy) the response will report the failure with a respective description.
Get familiar with the resources that can be requested by API
Here is 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 - HTTP
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 - HTTP
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.
For quality of service 1 (at least once) you can also request Acknowledgements.
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 Policy of a thing.
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 Ditto Java Client
which implements our API to communicate with the Things service in Java. The client itself uses the WebSocket protocol.
A WebSocket endpoint for interacting based on the Eclipse Ditto protocol
Data ingestion and device control via Bosch IoT Hub connection - based on Apache Kafka - See Connections.
Managed connections to external messaging/communication endpoints - based on Eclipse Ditto protocol or using payload mapping:
connecting to HTTP endpoints POST, PUT or PATCH requests
connecting to Advanced Message Queuing Protocol (AMQP) brokers (currently we support AMQP 0.9.1 and AMQP 1.0)
connecting to Message Queuing Telemetry Transport (MQTT) brokers (currently we support MQTT 3.1.1 and MQTT 5)
connecting to Apache Kafka (currently we support Kafka 2.x)
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 https://bosch-iot-suite.com/support/.