Sorry, you need to enable JavaScript to visit this website.

You are here

A code-first approach to digital twins

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
 

Related Blogs

anonymous's picture

By Michelle Howie

20/12/21

  • Telstra Messaging API
  • REST API

Good APIs start with the docs

With our new docs experience, it's easier than ever to get started with Telstra APIs. ...
anonymous's picture

By Michelle Howie

25/10/21

  • iot
  • arduino

AgTech and sustainable agribusiness

Our GovHack 2021 challege explored how AgTech can improve sustainable agribusiness.  ...
anonymous's picture

By Quinn Tran

25/9/21

  • iot
  • microsoft

Creative projects with Microsoft Azure

Get your creative juices flowing with the latest in computer vision innovation.   ...
anonymous's picture

By Michelle Howie

15/7/21

  • arduino
  • iot

Trigger an SMS alert when a device is dropped

Learn how Arduino can be used to trigger an SMS alert when a device has been dropped.  Autom...
anonymous's picture

By Michelle Howie

15/7/21

  • arduino
  • iot

Get environmental sensor data via SMS

Learn how to set up on-demand SMS updates for your IoT devices.  Potential use cases If y...
anonymous's picture

By Michelle Howie

15/7/21

  • arduino
  • iot

Use SMS to control your IoT device

In this blog, we look at how to use SMS commands from the Telstra Messaging API to control your IoT...
anonymous's picture

By Michelle Howie

2/7/21

  • iot
  • arduino

Changes to our IoT Developer Kit offer

The IoT Marketplace and Developer Kit trial were retired in July 2021.    Where we...
anonymous's picture

By Tim McMahon

2/6/21

  • Telstra Messaging API
  • bushfire

Air quality SMS alerts during bushfire season

I woke up one morning in January 2020 to discover that the air quality in Melbourne had dropped...
anonymous's picture

By Alan Quayle

18/5/21

  • iot
  • REST API

Unlocking the IoT: Telstra Track and Monitor API

As Australia’s longest serving telco, Telstra is expanding their developer program to provide...
anonymous's picture

By Sri Amirthalingam

31/3/21

  • iot
  • regional

Your regional mobile coverage questions answered

When developing an IoT solution for your business, coverage and access to a reliable network is crit...
anonymous's picture

By Michelle Howie

23/12/20

  • TDev
  • documentation

TelstraDev End of Year Wrap: 2020

We made it! Welcome to the end of 2020, may it soon be just a distant memory. Though it wasn’t...
iot home garden project with arduino and azure
anonymous's picture

By keith coutlemanis

10/11/20

  • arduino
  • azure

Azure IoT garden project with Arduino

In this blog, I'll showcase some of the interesting things you can do with the Internet of Thing...