Introduction

Digital Twin can be defined as a virtual model of physic assets or industrial processes that continually learn, provide data and respond to changes made in their environment. The concept of Digital Twin originally was used in CAD and simulation environments but is now commonly used in IoT technologies. According to Gartner, Digital Twin technology will be one of the 10 top strategic and disruptive technologies in 2018.

As said before, a Digital Twin is the virtual representation of a system or a physical device. This representation is defined by three elements:

• Status: value of each of its properties, representing in real time what the device is “doing”; e.g. an engine turning at 1800 rpm at an optimal work temperature.

• Actions: external actions or commands that can be applied to the device or that the device can respond to; e.g. an engine can be turned off.

• Events: notifications that can be sent a device by certain events; e.g. an engine can send a turn-off event if its working temperature exceeds a threshold value.

In order to create a standard Digital Twin representation, we use Mozilla’s “Web Thing API” (https://iot.mozilla.org/api). This standard is considered one of the market leaders due its easiness to adopt technology standards: easy and readable JSON data structures, data exchange protocol independence and providing an implementation for two of the most extended interfaces standards: REST and WebSockets.

This virtual representations (Digital Twins) modelled within the platform allow to:

• Manage physical devices, getting in real time its status.

• Perform operations sending commands or actions.

• Enrich its behaviour by the continuous ingest of data and process of events.

• Create complex systems through the orchestration of different Digital Twins.

• Ease depuration and simulation. The platform performs the same actions as a Digital Twin or as a real system: they are changeable.

Example: Sense Hat as a Digital Twin

This post will guide you through a complete demo scenario of the Digital Twin functionalities. It aims to show the strong capabilities of this innovative functionality from different points of view:

• As a developer: it will show how to model both the Digital Twin type and the Digital Twin itself. Furthermore, it will explain how a developer can monitor and manage every modelled Digital Twin from Onesait Platform Control Panel.

• As an end user: it will explain how to access to the demo scenario and describe an example of how to use a Digital Twin.

We will be modelling the following system:

Open

The RaspberryPi SenseHat add-on board (https://www.raspberrypi.org/products/sense-hat/) will be modelled. This device is very popular among Open Hardware developers, who commonly extend the original board with multiple devices such as joysticks and LED arrays.

The goal is to model the SenseHat board (from Onesait Platform Control Panel) and generate a code so that, whenever a device is executed, it connects to the platform and starts to send temperature, humidity and atmospheric pressure events. In the joystick’s case, events will be sent whenever the user press it so the LED array will be updated (with an arrow). At the same time, this information is sent to the platform to update the status of the Digital Twin, based on the status of the physic SenseHat board.

A developer must be able to follow the following flow when developing a Digital Twin:

• Define the Digital Twin type: after the analysis of the system to be defined, the developer has identified one or several relevant entities in the system, their properties, the events they generate in their environment, and external actions they will respond to. With all of this, it is possible to define a type of Digital Twin per entity.

• Define instances (Digital Twins) specific for each type. A Digital Twin assumes a classification of a certain entity type. The real system will be made of instances of these types in execution, each with its own state depending on the environment where it is deployed.

• Monitor and control Digital Twins.

All this information about events allows the platform to manage the device's shadow, and developers to build applications (using digital representation APIs) in real time that can act by receiving events from the device. In the case of this demonstrator user story, a simple web application (consuming a digital representation API) will show in real time information and events, and simulate joystick events which, when received by the physical device, will update the LED array.

In this test, we are modelling a RaspberryPi Sensehat add-on board as a Digital Twin.

 1)    Go to Onesait Platform Control Panel (https://www.onesaitplatform.online/controlpanel/) and log in as developer. Firstly, create the Digital Twin type by defining its properties, actions and events according to the definitions provided by the “Web Thing Description” (https://iot.mozilla.org/api/#web-thing-description).

2)    To create the Digital Twin Type go to the following menu: Digital Twin >My Digital Twin Definitions.

Open

Once there, you will be able to start creating your Digital Twin type by pressing the Create button.

To speed up the test, the Digital Twin type has already been created with the name of “Sensehat” so, from this point, every step will provide information about how the creation of the “Sensehat” Digital Twin was made.

 To better understand the following the steps, you might find useful to click on the View button of the “Sensehat” Digital Twin (blue button to the right, just in the options column).

When creating the “Sensehat” Digital Twin Type, you should fill up the name, type and description fields, as well as all the required information in the following tabs:

• Type properties: these represent the status of the Digital Twin. Those are the variables that will be ingested and processed in the platform as a device shadow. In the case of the SenseHat board, the following has been defined:

• Actions: notifications and actions that a Digital Twin receives from the platform. In this case, we model actions notifications for the joystick movement. For that reason, we have to model one action for each of the possible joystick directions:

• Events: notifications and actions that the Digital Twin sends to the platform. There are different kinds of events:

  • Register: Digital Twin registration in the platform. An authentication key is necessary.

  • Ping: peforms periodic active pings to check the status of the Digital Twin (active or not active).

  • Update_Shadow: updates the properties values (status) of the Digital Twin in the platform. It is important to know that the platform stores the historic properties values in order to do some analytics actions.

  • Notebook, Rule, Flow, Pipeline: the Digital Twin sends a notification to the platform in order to execute a notebook, a rule, a flow or a pipeline.

  • Log: the Digital Twin can send logs to the platforms. These logs can be stored in order to be displayed.

  • Other: customized events.

In this case, we also used the joystick to define the events that the Digital Twin can send to the platform. We will add an event for each joystick movement, one Update_Shadow event that will update the value of the Digital Twin’s different properties and finally one log event that will allow us to store traces.

• Logic: the platform allows defining what kind of logic the Digital Twin will run. For this example, the logic is programmed in JavaScript. By default, when creating a Digital Twin, Type the following functions are added:

  • Init: executed only when registering the Digital Twin in the platform.

  • Main: periodically executes the Digital Twin.

  • onActionXXX: a method will be created for each action defined in the Actions section, where you can define the logic that you want to execute when the Digital Twin receives an action from the platform.

Note: In spite of using JavaScript in this demonstrator, the logic of the Digital Twin is not limited exclusively to this language; any device or system that supports REST or WebSocket standards can use the services of the Digital Twin broker.

We next analyze in detail the logic that we have programmed in JavaScript for the type of DigitalTwin “Sensehat”.

First, two Java APIs are imported. The first one imports the Java API to communicate with the platform in a very simple way. The second one imports the API to communicate with the SenseHat board. In the init function, we register the listeners in order to notify the SenseHat of the actions received from the platform; this operation is carried out through the SenseHat API. In addition, we initialize the Digital Twin’s shadow to add value to the properties that define it, which in this case are temperature, humidity and pressure. In the main function, which runs periodically, we simply update the shadow of the device.

Finally, we have two types of functions:

• Events Functions: these functions are executed whenever the event that defines them takes place, that is, when the Sensehat's joystick is physically moved to the right, then the joystickEventRight function would be executed. Then we would send the notification to the platform. Therefore, a custom event has been made and we send the order to the Sensehat to display an arrow to the right on its LED array. 

• Functions onActionXXX: these functions are executed each time the Digital Twin receives an action from platform. For example, when you send to the Digital Twin the action of pressing the joystick to the right, the onActionJoystickRight function would be executed, which would send the command to paint an arrow to the right in its LED array.
  
  JSON: once defined all the previous elements of the Digital Twin, we can generate the Digital Twin’s representation following the “Web Thing API” Standard for the “Web Thing Description”. In this case, we can see the following JSON schema:

Once created the Digital Twin Type “Sensehat”, the next step is to create a concrete instance of the Digital Twin.

3)    To create an instance of the Digital Twin go the following menu: Digital Twin > My Digital Twins.

Bear in mind that, as before, the Digital Twin instance has been already created so there is no need to create one. You can just view the Digital Twin instance properties by clicking on the option button (in the option column).

A Digital Twin, being an instance of a Digital Twin Type, will be defined by its "Web Thing Description" and will have specific configuration properties. For this example, we will create a Sensehat Digital Twin located in Helsinki.

We can choose the location of the Digital Twin thanks to a map interface provided by the platform:

In addition, we will establish the specific configuration of this Digital Twin with the following fields:

Where:

• Digital Twin Type corresponds to the Digital Twin Type that has been created previously and therefore defines the Web Thing Description. In addition, when selecting the type of Digital Twin, we assign the logic defined for this type.

• URL scheme, interface, port, ContextPath and IPV6: These provide the Digital Twin with the necessary information to infer its URL and that it be sent to the platform in the Registration message. Therefore, the platform can notify the actions. 

• Broker endpoint is the URL to notify the Digital Twin events on a platform. 

• DigitalTwinKey is the key with which the Digital Twin can be authenticated against the platform.

Once we have defined our Digital Twin, the platform allows to generate the corresponding code. In the current platform version, the code is generated in Java.

4)    To see the Digital Twin's generated code, go again to Digital Twin > My Digital Twin and select the already created “SenseHatHelsinki” Digital Twin instance.

To generate the code, you must select the following options:

Then click on Generate and the Maven project will be compiled (Java) and downloaded, ready to be executed. Furthermore, it includes the API and drivers dependency for a SenseHat device project.

Bear in mind that this project, together with the corresponding Java JAR, will be available in the Platform Market Place, along with the Digital Twin Demonstrator.

Monitor and control Digital Twins

1)    Once the “SenseHatHelsinki” Digital Twin has been deployed, you can monitor its status by executing a query from the following menu option: Digital Twin > Digital Twin Status.

Once there, you will see the following screen:

Here you can configure the query using: 

• Type: Digital Twin Type. In this case, select “Sensehat”.

• Device: Digital Twin instance that implements the selected Digital Twin type. In this case, select “SensehatHelsinki”.

• Operation: Type of operation you want to query. You can filter by the following operations:

  • Shadow: Historical status of the property values defined for the Digital Twin.

  • Register: Historical events sent from the Digital Twin and registered in the platform.

  • Ping: Historical pings.

  • Log: Historical log traces sent from the Digital Twin.

  • Notebook, Pipeline, Rule, Flow, Other: Historical events sent by the Digital Twin to the platform. If you choose the option Other, you can filter by the name of the customized event.

  • Action name: available to consult the performed actions.

• Number of results per device.

 As useful examples, you can see how to perform different type of queries and their results:

2)    Select Operation “Register” and the number of results for this query; e.g. “1”. Then click on “Execute Query” and see the result:

 3)    Go back and select the operation Logs and the desired number of results for this query; e.g. “2”. Then click on “Execute Query” and see the result:

4)    Go back and select the operation Pings and the desired number of results for this query; e.g. “1”. Then click on “Execute Query” and see the result:

5)    Go back and select the operation Shadow and the desired number of results for this query; e.g. “3”. Then click on “Execute Query” and see the result:

6)    Go back and select the operation Other (which will show you the events from the joystick operations defined previously when creating and modelling the Digital Twin type, in the actions tab). Then select the Custom Event Name “JoystickEventup” and the desired number of results for this query; e.g. “3”. Then click on “Execute Query” and see the result:

7)    Go back and select the operation Action. Then, select the desired number of results for this query; e.g. “3”. Then click on “Execute Query” and see the result: