Digital Twins

An IOTICS Digital Twin is a virtual representation of a real entity. A real entity can be a physical asset, a sensor or device, a person, a concept, a data source or data consumer, or anything else that you'd like it to represent.

📘

We often use Twin as an abbreviation for Digital Twin

On this page we will cover:


An Introduction to IOTICS Digital Twins

Take a look at our Digital Twin Introductory Video for a high-level overview:

On a technical level Digital Twins consist of metadata properties of the twin and the object it represents, as well as streaming data feeds.

The separation of metadata and data is a core concept of IOTICS and makes Digital Twins machine-readable and machine-actionable. The use of semantic web linked-data patterns allows the twin to be a “pointer” to other data sources, e.g. a web-accessible dataset.

Implementing Digital Twins first requires the creation of a Model of a Digital Twin. A Model is the “template” ie. the structure of the future twins. The Model describes the properties and fields the twin should have, whereas the Digital Twins describe the instance of the real asset, person or concept itself.

Digital Twin instances are then created based on a chosen Model. They contain the specific metadata and data of the modelled asset, concept or person.

Digital Twin structure

An IOTICS Digital Twin is made of five parts:

  1. Its IOTICS unique Identity
  2. Metadata Properties
  3. Relationship Properties
  4. Streaming Data Feeds
  5. Behaviour
868868

1. Identity

Each twin has a unique identifier - a self-sovereign identity conforming to the W3C “Decentralised ID” (DID) specification. Read more about DIDs in our Identity section.

2. Metadata Properties

The Metadata properties are used to:

  • describe the real asset, person or concept being represented - serial number, location, owner, etc
  • link or reference “outside” IOTICSpace using URLs - to a static dataset, a website, etc
  • describe the Digital Twin itself - created, last updated, etc
  • set the level of findability and accessibility - visibility setting, access permissions, etc

3. Relationship Property

The Relationship properties are used to describe the relationship between Digital Twins, for example "has", "relates to", etc. Semantic modelling is more flexible than relationships implemented in a hierarchical method. For example:

  • Engine A: belongs to Car A => hierarchical relationship
  • Car A: relates to Bicycle B => not hierarchical relationship
  • Car A: being driven by Person B => temporary association
  • Car A: has 3 or 4 wheels => relationship + condition, it has to be related to either 3 or 4 wheels

4. Data Feeds

Digital Twins can publish or follow one or more data feeds and are used to:

  • contain real-time updates to the state of the twin when the dataset has changed
  • contain one or more data fields, with each data field containing metadata about itself
  • read more about sharing data and following feeds here

5. Behaviour

A Digital Twin can contain custom logic to import, manipulate or export its published or followed metadata and data feeds. It can be classified as:

  • Twin-to-Twin interactions: by following data from one or more twins, logic can be added to interoperate the data and re-publish one or more new data feeds
  • Interactions with the outside world through "connectors". These are applications that sync the "real" asset's state with the Digital Twin's state. Connectors run continuously and are used to either:
    • send data from an external data source to a Digital Twin, or
    • send data from a Digital Twin to an external data consumer.

Digital Twin types

IOTICS distinguishes between three different types:

  1. Digital Twin
  2. Digital Twin Model
  3. Host Twin

1. Digital Twin: the virtual representation or an "instance" of a real asset, person or concept.

  • This is the "generic" type.
  • They contain the specific metadata and data of the modelled real asset, concept or person.

2. Digital Twin Model: the template or structure of one or more Digital Twins of the same type.

  • It is used to define the properties, feeds and fields the Digital Twins in Point 1. should have.
  • A Digital Twin Model has the same structure as a Digital Twin and can be managed and manipulated in the same way.
  • You can distinguish Models from Digital Twins by their type = Model.
  • Have a look at our Create Twin Models page for a step-by-step guide.

3. Host Twin: the virtual representation of the IOTICSpace (Host).

  • Each IOTICSpace only has one Host Twin, which is automatically created and by default public.
  • It serves to control access permissions for the IOTICSpace as a whole.
  • A Host Twin has the same structure as a Digital Twin and can be managed and manipulated in the same way. However, its access is restricted as only admins can update it.
  • You can distinguish Host Twins from Digital Twins by their type = HostTwin.

Enable powerful search with semantically described Digital Twins

IOTICS believes that semantically described data is the only way to truly, flexibly and consistently interoperate data across domains and companies, for both humans and machines.

What is semantics?

Semantics is the study of reference, meaning and truth. For humans, this means a more consistent understanding across domains, companies and languages. For machines, semantically described data is the prerequisite for machine-readability and machine-actionability.

Semantically described Digital Twins

Digital Twins by their very nature are true to the FAIR principles to make data Findable, Accessible, Interoperable and Reusable. This is enabled by:

  1. the separation of metadata (metadata properties and relationship properties) and data (data feeds), and
  2. semantically described metadata to enable a common understanding and meaning across twins and IOTICSpaces.

Good semantically described metadata relies on:

  1. Your and your colleagues' knowledge about your data's meaning and structure
  2. Semantic dictionaries called "Ontologies" to serve as written documentation for the description and structure of your data
  3. Linking each of the Digital Twin's metadata properties to a specific Ontology's data description.

If you have never worked with semantics before this may seem daunting. But fear not, we have made it easy. You can try the following:

  • Go to your IOTICSpace user interface for an intuitive way on how to create your Digital Twin Model. We guide you through the process of selecting an appropriate Ontology and data description.
  • If you have any questions or would like us to run a semantics workshop for you and your colleagues, contact IOTICS Support.

Digital Twin access permissions

When working with Digital Twins you can set an access level for complete control over who can access your data.

IOTICS distinguishes between two settings:

  1. Visibility: whether a Digital Twin's metadata is visible (or not) to another IOTICSpace (the F in FAIR)
    • this is set by updating the Host Twin's or Digital Twin's Visibility property
  2. Accessibility: whether a Digital twin's data can be accessed (or not) by a Digital Twin from another IOTICSpace (the A in FAIR)
    • this is set by updating the Host Twin's or Digital Twin's AllowList property
    • it can be enabled for the entire IOTICSpace and selectively on a twin-by-twin basis

For more information about access permissions, including for examples of how to update them, go to Selective Data Sharing.

API functions for Digital Twins

The below table summarises all functions for you to find, access, interoperate and reuse your and other parties' Digital Twins. For more detailed information on each of the functions please go to the specific page or the API Reference directly.

FunctionDescriptionMore details
CreateCreate a new Digital TwinCreate Twins
UpdateUpdate a Digital Twin with feeds and metadataUpdate Twins
UpsertCreate and Update a Digital Twin with feeds and metadataUpsert Twins
SearchSearch for yours and others' Digital TwinsSearch & Describe Twins
DescribeDescribe a Digital TwinSearch & Describe Twins
ListList all Digital Twins you are authorised to findSearch & Describe Twins
FollowSet your Digital Twin to follow another Digital Twin's data feedShare Data & Follow Feeds
DeleteDelete a Digital TwinDelete Twins

API prerequisite: user credentials to work with the API

Click to see the prerequisites

For the purposes of illustration, we will look at an example implementation in Python. It is best practice to create a Python virtual environment with all the dependencies needed to run the API. You can do that through the following commands:

  1. Create a new virtual environment named iotics: python3 -m venv iotics
  2. Activate the virtual environment: source iotics/bin/activate
  3. Install the required dependencies: pip install -U pip setuptools wheel iotics-identity

Follow these steps to get started. They're a prerequisite before calling any of the above API functions.

  1. Create your user and agent credentials
  2. Delegate the agent to work on behalf of the user
  3. Create your token
  4. Create your API headers

1. Create your user credentials

In order to use the API you first need to create your user and agent seeds, and in turn, create your user and agent credentials.

Simply copy-paste the following snippet to get started, or go to our Identity and Credentials page for more details.

from iotics.lib.identity.api.high_level_api import get_rest_high_level_identity_api

api = get_rest_high_level_identity_api(resolver_url="resolver_url")

USER_KEY_NAME = "00"  # Feel free to change it
AGENT_KEY_NAME = "00"  # Feel free to change it
USER_SEED = api.create_seed()
AGENT_SEED = api.create_seed()

print("USER_SEED:", USER_SEED.hex())
print("AGENT_SEED:", AGENT_SEED.hex())
print("USER_KEY_NAME:", USER_KEY_NAME)
print("AGENT_KEY_NAME:", AGENT_KEY_NAME)

❗️

Store Credentials

Make sure you store the credentials generated with the script above in a safe place as they will be used any time you want to use the API. If you lose them you will not be able to interact with your twins anymore.

2. Delegate the agent so it can work on behalf of the user

In IOTICS, agents (and not users) create and update Digital Twins. Therefore it is important that you as the user (or the application that acts as the user) authorise the agent to work on the user's behalf.

from iotics.lib.identity.api.high_level_api import get_rest_high_level_identity_api

api = get_rest_high_level_identity_api(resolver_url="resolver_url")

(
    user_registered_id,
    agent_registered_id,
) = api.create_user_and_agent_with_auth_delegation(
    user_seed=USER_SEED,
    user_key_name=USER_KEY_NAME,
    agent_seed=AGENT_SEED,
    agent_key_name=AGENT_KEY_NAME,
    delegation_name="#AuthDeleg",
)

3. Create your token to interact with your Host (IOTICSpace)

In order for the agent to create and update Digital Twins, the agent needs to be authenticated and authorised. IOTICS uses tokens to check these permissions.

All brokered interactions have a lifetime. When its lifetime expires, the connection has to be reformed, requiring a new token, re-verification of identity, authentication and authorisation. This enables stolen tokens or intercepted messages to have a limited lifetime.

from iotics.lib.identity.api.high_level_api import get_rest_high_level_identity_api

token = api.create_agent_auth_token(
    agent_registered_identity=agent_registered_id,  # Generated in the previous snippet
    user_did=user_registered_id.did,  # Generated in the previous snippet
    duration=600,  # Expressed in seconds
)

🚧

Be aware that the token has a pre-defined duration expressed in seconds. When it expires it will need to be manually re-generated in order to keep interacting with the Host.

4. Create headers to be added alongside the API request

When you use the API you will have to set some mandatory headers so that the Host can check whether you are allowed to interact with it and reply back to you.

headers = {
    "accept": "application/json",
    "Iotics-ClientAppId": "example_code",
    "Authorization": f"Bearer {token}",  # Generated in the previous snippet
    "Content-Type": "application/json"
}
Click to see all the previous code in a single snippet

from iotics.lib.identity.api.high_level_api import get_rest_high_level_identity_api


api = get_rest_high_level_identity_api(resolver_url="resolver_url")

USER_KEY_NAME = "00"
AGENT_KEY_NAME = "00"
USER_SEED = api.create_seed()
AGENT_SEED = api.create_seed()

(
    user_registered_id,
    agent_registered_id,
) = api.create_user_and_agent_with_auth_delegation(
    user_seed=USER_SEED,
    user_key_name=USER_KEY_NAME,
    agent_seed=AGENT_SEED,
    agent_key_name=AGENT_KEY_NAME,
    delegation_name="#AuthDeleg",
)

token = api.create_agent_auth_token(
    agent_registered_identity=agent_registered_id,
    user_did=user_registered_id.did,
    duration=30,
)

headers = {
    "accept": "application/json",
    "Iotics-ClientAppId": "example_code",
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
}