Develop your business application

Task description

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.

images/confluence/download/attachments/894251204/iot-app-flow-2.png

  1. Login

    • 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.

  2. Data request

    • 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).

  3. Response

    • 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

  • 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.

images/confluence/download/attachments/894251204/things-connections.png

For details see Bosch IoT Things > Basic concepts > Which API to use?

Further integration

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: info-things@bosch-si.com.