# Digital Twin concept

# Introduction

A Digital Twin is a virtual representation of a real or an abstract object (e.g., an item, a device, a system, a process, an organisation, a service, or a person). A Digital Twin exists independently among cooperating partners in a form of shared knowledge. It does not belong solely to a single partner or organisation. Therefore, a Digital Twin cannot be stored in a single partner's or organisation's infrastructure. It must exist in the cloud.

The Trusted Twin platform is a developer platform which allows you to create and share Digital Twins. It acts as an exchange layer in the technology stack, so that knowledge storing and sharing is decentralized, flexible, and secure.

# Digital Twin

A Digital Twin is dynamically created by all users involved in the process:

  • Each user can attach their data (in form of Identities, Ledgers, and Docs) to the Digital Twin and retain control over these data.
  • Each user has access to data of other users attached to the Digital Twin to an extent granted by users who own the data.
  • Each user can create any number of Identities and decide about their visibility. Identities can be resolved to Twin UUIDs.

On the Trusted Twin platform, a single Digital Twin consists of:

  • A Twin (main object of the Trusted Twin platform, many per account). A Twin ties together knowledge coming from different accounts through Ledgers, Identities, and Docs.
  • Ledgers (one per Twin per account). A Ledger is a JSON document storing information about the state of the Twin. Ledgers are dictionaries which store Entries (key-value pairs).
  • Identities (many per Twin per account). Identities are user-defined unique identifiers of Twins. Identities can be private or public.
  • Docs (many per Twin per account). Each Doc is as static file of any type (such as text, video, audio) and size.

# Advanced Digital Twin services

The Trusted Twin offers platform offers as well advanced services.

  • The History service lets you store historical values of Entries of a Ledger.

Digital Twins can be as well aggregated or viewed by users in form of a relational SQL database as:

  • Timeseries tables (many per account to store Digital Twin history).

  • Indexes tables (many per account to store Digital Twin states).

  • You can also automatically invoke external services via publish/notify service (e.g., webhooks) by using the Notifications service.

# Twin

A Twin is the main object of the Trusted Twin platform as it aggregates knowledge coming from different accounts. It ties together knowledge from different users and accounts through Identities, Ledgers, and Docs attached by different users.

The Twin itself is created by a single user - the creator and initial owner of the account. The ownership of a Twin can be transferred.

# Identity

Each Twin in the Trusted Twin platform has a unique system ID (Twin UUID) that is generated upon creation of the Twin. This unique system ID is used access the Twin via REST API.

However, you might need to use other user-defined IDs relevant for your business to identify a Twin. Such IDs could be a registration number, an RFID tag, or a product serial number. You can use Identities to identify Twins with such IDs. An Identity is created by a user in the context of an account and a Twin, and it must be unique within this context. This means that the same Identities can be attached to multiple Twins, and that they can be used to group Twins.

Among many operations that you can perform on Identities, the resolve_twin_identity operation is of great importance as it provides a list of Twins a given Identity is attached to.

# Ledger

A Ledger is a JSON document that stores information about the state of the Twin. A Ledger is a dictionary which stores Entries (key-value pairs). There is exactly one Ledger for an account-Twin pair. A Ledger is independent and separated from other Ledgers owned by different accounts.

The visibility of a Ledger can be private or public. It depends on the visibility of Entries in the Ledger:

  • If the "visibility" of an Entry is null, the Entry is private. Private Entries are visible only to users of the account that owns the Ledger. If all Entries of the Ledger are private, the Ledger is private.
  • If the "visibility" of an Entry is not null, the Entry is public. Public Entries are visible to users of the account that owns the Ledger and also visible to users of other accounts if the visibility rule for the given Entry evaluates to True. A visibility rule can be set independently for each Entry. If any of the Entries of the Ledger is public, the Ledger is public.

Each Entry stores a single value of a JSON type (a number, a string, a list, an object). The value can be provided directly by a call to the respective API endpoint or reference a value of a different Ledger. Such "ref" (reference) type values are guaranteed to reflect changes of the value to which we provide a reference.

If you need to store historic values of Entries, you can use the "history" attribute to define the time period for which the Entries will be stored. You can retrieve the history of Ledger Entries at any time through the get_twin_ledger_entry_history endpoint.

If the Timeseries service is enabled for your account, the Entry can also have a "timeseries" attribute. The "timeseries" attribute allows you to create structured and multidimensional views of Digital Twin history that are updated automatically each time an Entry is being changed for a measurement.

If the Indexes service is enabled for your account, you can create structured and multidimensional views of Digital Twin states. Indexes are updated automatically each time an Entry is being changed for a property.

The "publish" attribute (which consists of a "rule" and a "topic") allows you to create Notifications. Notifications allow you to automatically invoke external services each time a Ledger Entry is changed.

# Doc

A Doc on the Trusted Twin platform stores static content (text, audio, video files etc.).

The process of attaching a Doc to a Twin consists of two steps:

  1. Generation of a temporary upload URL through the create_upload_url endpoint. You will use the upload URL to upload the Doc to temporary storage.
  2. Attaching of a copy of the Doc to the given Twin through the attach_twin_doc endpoint.

A single Doc can be attached to multiple Twins.