BY Daniel Simpson 17 December 2021
Find out how to use code-first digital twins with the Telstra Digital Twins library.
Two ways to create a digital twin
Azure Digital Twins (ADT) is a platform that enables you to create live digital twin graphs representing entities and their relationships. In today’s world – where your Integrated Development Environment (IDE) automatically detects your coding style and makes recommendations using machine learning – creating a digital twin might seem like more work than you’re accustomed to. First, you need to create a document using the Digital Twin Definition Language (DTDL). You then need to add it to Azure Digital Twins using a Restful API call, and repeat this process as changes are required.
Alternatively, you could use Plain Old Class Objects (POCO), which you may be familiar with if you’ve used Entity Framework Core. With POCO, you might find it easier to create and manage your digital twins using a code-first approach.
If you're currently using ADT but looking for a way to reduce the time it takes to create, read, write and deploy Digital Twins, then read on to find out how to use a specific library instead.
Looking for an introduction to Digital Twins? Check out our blogs here and here.
Figure 1: Twin model vs twin with a buildings example
Defining digital twins using DTDL
Digital twins can be defined in a variety of ways. In Azure Digital Twins, developers define digital entities that represent people, places, or things by creating a digital twin model. For clarity, hereafter we will refer to digital twin models as simply models and digital twins as simply twins.
As Microsoft describes it, models are defined in a JSON-like language called Digital Twins Definition Language (DTDL). Twins are described in terms of their state properties, telemetry events, commands, components, and relationships.
These models are then used to create twins that represents specific entities according to their defined model. Let’s take a look at one such Digital Twins example.
Creating a Building Twin Model using DTDL
Let’s say we want to create a digital twin model of a Telstra building in Sydney located at 400 George Street. The DTDL to create the building model is shown below.
{
"@id": "dtmi:com:telstra:building;1",
"@type": "Interface",
"displayName": "Building",
"contents": [
{
"@type": "Property",
"name": "name",
"schema": "string",
"writable": true
},
{
"@type": "Property",
"name": "address",
"schema": "string",
"writable": true
},
{
"@type": "Property",
"name": "city",
"schema": "string",
"writable": true
},
{
"@type": "Property",
"name": "state",
"schema": "string",
"writable": true
},
{
"@type": "Property",
"name": "zipcode",
"schema": "string",
"writable": true
},
{
"@type": "Relationship",
"name": "contains",
"target": "dtmi:com:telstra:Floor;1"
}
],
"@context": "dtmi:dtdl:context;2"
}Note that the @id is "dtmi:com:telstra:building;1". Where the identifier is made up of two parts, the id, "dtmi:com:telstra:building", and the model version, "1".
After creating a model for a building, a developer could create a twin for the Telstra building at 400 George Street, Sydney, Australia.
While witing this in DTDL provides the most flexibility, it requires developers to learn DTDL and write the necessary code in their solutions to read and write data in DTDL for both twin models and twins.
Although deployment using DTDL is straightforward, it can be more difficult than developers are accustomed to. As model changes are required, updates must be made to the DTDL and then deployed, preferably using a CI/CD automated process. In Azure Digital Twins, an API must be called for each model that needs to be created or updated. The same is true for the creation of each twin.
Introducing code-first digital twins
Telstra has developed a “code-first” approach that leverages common developer Plain Old Class Objects (POCO) together with Azure Digital Twins and a new Digital Twins library. This approach may be preferred to working with DTDL directly.
Figure 2: Automated generation of DTDL can save time.
A code-first approach enables developers to define digital twin models in code and then serialize them to create the twin models in Azure Digital Twins. This process can be automated in Azure DevOps using a simple pipeline step.
To date this code-first approach has drastically reduced the time it takes for developers to create, read, write, and deploy digital twins, as well as reducing the ongoing maintenance required.
Figure 4: Continuous deployment, including the separation of device twin models from ontology specific twin models to increase quality and separate concerns.
Creating a building twin model using a code-first approach
Now, how would we create a building digital twin using code first? First, let’s take a look at how we might do this using Entity Framework Core.
public class Building
{
public string Name { get; set; }
public string Address { get; set; }
public string City { get; set; }
public string State { get; set; }
public string ZipCode { get; set; }
}This class could then be used by Entity Framework Core to create a database table for storing buildings. To provide additional information to Entity Framework Core about the class we use attributes such as ColumnAttribute, KeyAttribute, and MaxLengthAttribute.
Code-first digital twins work in a similar way but require different attributes.
First, we need to indicate that the class represents a digital twin. To do this we use the DigitalTwinAttribute. Below we specify the version and the display name for the digital twin model.
[DigitalTwin(Version = 1, DisplayName = "Building")]
public class Building
{
…
}Next, we need to indicate which properties will be included in the digital twin model. We do this by adding the TwinPropertyAttribute to the relevant class properties.
[DigitalTwin(Version = 1, DisplayName = "Building")]
public class Building
{
[TwinProperty]
public string Name { get; set; }
[TwinProperty]
public string Address { get; set; }
[TwinProperty]
public string City { get; set; }
[TwinProperty]
public string State { get; set; }
[TwinProperty]
public string ZipCode { get; set; }
[TwinRelationship]
public List<Floor> Floors { get; } = new List<Floor>();
}An instance of the above class would result in the following digital twin DTDL.
{
"$dtId": "buildingTwin1",
"$etag": "686897696a7c876b7e",
"$metadata": {
"$model": "dtmi:telstra:examples:building;1",
"PropertyMetadata": {}
},
"name": "Telstra Building",
"address": "400 George Street",
"city": "Sydney",
"state": "NSW",
"zipCode": "2000"
}Find out more
All the code in this blog can be forked or downloaded from Telstra's GitHub.
To learn more about code-first digital twins and the Telstra Digital Twins library, reach out to us at TelstraDev@team.telstra.com or post in our Developer Forums and we'll put you in touch with the Telstra Digital Twins team.
Want to learn more about how to use Azure Digital Twins in practice? Check out our four-part blog series from one of our Telstra Purple consultants, who built a digital twin in his home garden. Start at the beginning in part one, or skip to the digital twins in part four
