Digital Twins

The concept of a digital twin, its definition and thus the expectation vary from one manufacturer to another. At least all publications so far agree upon the task to provide a virtual representation of a physical asset. Adding further information and functionality enriches the digital twin into the more generally assumed holistic view that reflects all capabilities and aspects of a device/product asset.
In the context of Industrial IoT (IIoT) a digital twin is also called (asset) Administration Shell.
Bosch IoT Things is a cloud service implementing such a digital twin / administration shell concept for physical assets.
These digital twins can contain the virtual representation of a physical asset as well as other information and functionality to provide a holistic view accessible by API.

 

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 following shows an example of an electric bike that is represented as digital twin:

Real world Things service Your Application
Physical device Things entity Digital Twin - GUI
ebike ID = com.ebike:mod-01-23
Location ID/features/location bike location
latitude 48.767
longitude 9.252
Battery level ID/features/battery/ battery
full /mid /empty
Guarantee info ID/features/crm/ free form guarantee info from a CRM system

Now, if one needs to track where the bike is, or even send messages to the device by just talking to its twin, a definition of these structures is necessary and very useful.

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 components to various subjects.

eBike Digital Twin

The example shows that the location and battery features could rely on Eclipse Vorto function block definitions, while the guarantee feature is free form, to emphasis that using such definitions is optional.

When implementing your digital twin you can re-use already existing function blocks, or create some new ones, specific to your devices.

The data, where the status information for your digital twin come from, can be diverse.
You can imagine for example that:

  • the data representing the battery level comes from the ebike directly,
  • while the location coordinates are send by a navigation system which is coupled to the physical ebike,
  • and the guarantee information is stored in a CRM system.

Digital twins are typically composed of multiple implementations for their different features.

  • For features that mainly represent a state with properties (e.g. device state), the state management within Bosch IoT Things can be used. This state is then updated e.g. by the devices using a device connectivity layer like Bosch IoT Hub, or by a business application that updates configuration properties within this state.
    The Things service then cares about applying the state changes and notifying all relevant components about the changes.
  • Functionality that is not reflected as state (e.g. events, operations, triggers), is managed by Bosch IoT Things as messages. Messages can be sent to features and/or received from features. These messages are not processed within the Things service but are routed and dispatched to the respective implementation, which is provided separately.
    Functionality of IoT devices is handled this way using messages and the Things service routes the messages from/to the device connectivity layer, e.g. using Bosch IoT Hub. Depending on the type of operation, these messages are either one-way messages or are correlated with response messages in order to represent the result of an operation.
  • Features with other types of functionality or features representing state that is managed externally, must be implemented by integrating separate microservices/components. These microservices are responsible to listen to signals/notifications coming from the Things service, process the respective signal and optionally send responses. These microservices can use one of the provided bindings to integrate with the Things service (WebSocket, AMQP 1.0, or AMQP 0.91).

Summarized, this means that for “simple” digital twins, mainly consisting of device state and device functionality, the management of Bosch IoT Things integrated with a device connectivity layer like Bosch IoT Hub is sufficient. For more complex digital twins you can extend this pattern, by integrating separate microservices/components which implement specific features.

The following figure shows an example deployment of the multiple actors which can access the digital twin representation of the ebike.

ebike deployment example

Policies hold the information about who is allowed to see and work on which part of your digital twin.

In our example we assume the following setup:

  • the green user has all permissions, as he is supposed to be the owner of the ebike
  • the fuchsia user could be the manufacturer's applications interested only in gathering data regarding the battery lifetime
  • and the blue user could represent a support-group which is only allowed to read meta data about the ebike warranty conditions

However, the policy could describe whatever roles or responsibilities you need.

ebike policy

See full thing and policy below.

Ebike's digital twin in Thing notation

{
  "thingId": "org.example.ebike:mod-01-23",
  "policyId": "org.example.ebike:policy-a",
  "attributes": {
    "manufacturer": "Bosch"
  },
  "features": {
    "location": {
      "properties": {
        "geoposition": {
          "latitude": 48.767,
          "longitude": 9.252
        }
      }
    },
    "battery": {
      "properties": {
        "status": {
          "full": false,
          "mid": false,
          "empty": true
        }
      }
    },
    "guarantee": {
      "properties": {
        "status": {
          "country": "Germany",
          "sale mm-yyyy": "10-2016"
        }
      }
    }  
  }
}

Policy

{
  "policyId": "org.example.ebike:policy-a",
  "entries": {
    "OWNER": {
      "subjects": {
        "iot-permissions:5e7159e3-xxxx-xxxx-xxxx-84da6bc10945": {
          "type": "iot-permissions-userid"
        }
      },
      "resources": {
        "policy:/": {
          "grant": [
            "READ",
            "WRITE"
          ],
          "revoke": []
        },
        "thing:/": {
          "grant": [
            "READ",
            "WRITE"
          ],
          "revoke": []
        },
        "message:/": {
          "grant": [
            "READ",
            "WRITE"
          ],
          "revoke": []
        }
      }
    },
    "battery-driver": {
      "subjects": {
        "iot-things:918904f5-xxxx-xxxx-xxxx-cb73a5ba9dbf:my-client": {
          "type": "iot-things-clientid"
        },
        "integration:918904f5-xxxx-xxxx-xxxx-cb73a5ba9dbf:battery-hub": {
          "type": "iot-hub"
        }
      },
      "resources": {
        "thing:/features/battery": {
          "grant": [
            "READ",
            "WRITE"
          ],
          "revoke": []
        }
      }
    },
   "guarantee-crm": {
      "subjects": {
        "iot-things:918904f5-xxxx-xxxx-xxxx-cb73a5ba9dbf:guarantee-monitor": {
          "type": "iot-things-clientid"
        },
        "iot-permissions:e9ae2c3d-xxxx-xxxx-xxxx-4ddc902ff732": {
          "type": "iot-permissions-groupid"
        }
      },
      "resources": {
        "thing:/features/guarantee": {
          "grant": [
            "READ",
            "WRITE"
          ],
          "revoke": []
        }
      }
    }
  }
}

Find the source code of much more sophisticated example at GitHub.
https://github.com/bsinno/iot-things-examples/tree/master/digitaltwin-example