v0.3

• 1: Getting Started
• 2: Architecture
• 3: Model
• 3.1: Characteristic Models
• 3.2: Common Descriptors
• 3.3: Event and Interaction Models
• 3.4: Intervention Models
• 3.5: Measurement Models
• 3.6: Production System Models
• 3.7: State Models
• 3.8: Worker Models
• 4: How to
• 4.1: Orchestrator REST API
• 4.2: IIoT Middleware
• 4.3: HDM REST API
• 4.4: Skills modelling

1 - Getting Started

Prerequisites

All the components are provided as Docker images, thus the following software is required:

• Docker
• Docker Compose

We tested our deployment on a machine running Ubuntu 22.04, with Docker v27.3.1, and Docker Compose v1.29.2.

Installation

Download the Clawdite repository from GitLab by executing the following command:

$ git clone git@gitlab-core.supsi.ch:dti-isteps/spslab/public/clawdite.git

Setup

Before running the containers, it is required to download the Docker images from their respective registries. While some images are publicly available, some other require credentials to be downloaded from private registries.

Images provided by SUPSI can be download from the GitLab container registry, which supports the token-based authentication. Please send your request for a new token to the repository maintainers.

Once you are provided with a username and a token, you can issue the following command to login to the private GitLab Docker registry and download the images:

$ docker login registry.example.com -u <username> -p <token>
$ docker-compose pull

Try it out!

Docker images are hosted in a private Docker Registry at gitlab-core.supsi.ch. Please contact the maintainers to get registry credentials.

Run containers using Docker Compose:

$ docker-compose up -d

To stop the containers and delete all the managed volumes:

$ docker-compose down -v

2 - Architecture

The whole Clawdite platform’s architecture has been designed in order to be interoperable, extensible, scalable and customizable.

Components

• Gateways: standard interfaces to access the IIoT Middleware, as they stream data to the IIoT Middleware according to predefined data formats. They could be deplyed on Raspberries, smartphones, tablets and PLCs.
• IIoT Middleware: responsible to make the different data streams available to each component of the architecture. Different Middlewares can be integrated to meet the specific application requirements.
• HDM (Historical Data Manager): retrieves and persists historical data coming from both Gateways and Functional Modules. Most middlewares (e.g., MQTT brokers) do not provide such functionality, thus this component is needed to enable reporting and analytics activities.
• Orchestrator: responsible for organizing and managing the entire platform and its Digital Twins instances. It knows how the platform and its architecture are structured, who the workers are, which are the installed modules, the connected sensors and the message schemas adopted by the different modules and sensors.
• Functional Modules: components external to the Platform that can be plugged to provide additional functionalities (e.g. Fatigue Monitoring System). They take data from the Orchestrator and the Middleware and provide the results of their processing to the Platform.

3 - Model

Clawdite’s reference model describes a HDT including human-centred elements but also contextual elements, relevant to characterise the workers and the surrounding environment in a production system. The model and its implementation aim at releasing an extensible, scalable and adaptable HDT. The advantage for the adopters of the proposed HDT model is two-fold: they can rely on a model built on the robustness of a scientific result; they are provided with ready-made packages of entities to instantiate their own HDT, by including also human-centred aspects (e.g., interactions, events), and software-based simulations/predictions (e.g., output of functional models predicting the state of factory entities).

There are 3 main types of data which are managed in Clawdite: measurements (dynamic data), characteristic (quasi-static data) and states (the output of functional modules).

Main elements

• Descriptor Elements (white, red, purple and blue boxes): contains the description and definition of all the HDT entities, and could be characterized by unit of measures, scales, category and taxonomies.
• Factory Elements (yellow boxes): The factory and its components are described by a hierarchical structure. The worker has a dedicated representation for enabling processing in the functional modules.
• Relationship Elements (green and orange boxes): events, interactions, interventions and exemptions describe the relationship between factory entities or workers.
• State Elements (sky blue boxes): Functional modules, based on the HDT knowledge, compute and provide insights related to factory entities and workers according to the defined block format.

3.1 - Characteristic Models

This set of classes allows to define quasi-static and static data describing workers and factory things.

Note that the required model attributes are indicated with a red asterisk ("*"). For mandatory relations, refer to the multiplicity instead, as relationships are defined on one side only (i.e., a specific relationship might be described within the other related entity).

CharacteristicDescriptor

The CharacteristicDescriptor allows the extension of AbstractDescriptor with a specific class dedicated to (quasi-)static data. The class can include any kind of characteristics relevant for the description of workers and other entities in the factory. For example, the height or the set of skills may be workers’ features modelled through the class CharacteristicDescriptor.

CharacteristicValue

The class CharacteristicValue allows the definition of the value that characterise a CharacteristicDescriptor of a specific factory entity, represented by the classFactoryEntity.

The CharacteristicValue is described by the following attributes:

The CharacteristicValue has the following relations:

3.2 - Common Descriptors

The classes belonging to the Common Descriptors allow the description of properties, characteristics, measurements, dimensions and states of the many entities operating in a factory, including workers, machines, robots and devices.

Note that the required model attributes are indicated with a red asterisk ("*"). For mandatory relations, refer to the multiplicity instead, as relationships are defined on one side only (i.e., a specific relationship might be described within the other related entity).

AbstractDescriptor

The AbstractDescriptor allows the description of any type of data managed by the HDT: characteristics, measurements and states. The descriptor can be enriched with different information such as its UnitOfMeasure, Category, TaxonomyItem and Scale. Thanks to these auxiliary classes, the AbstractDescriptor(s) can be of different nature, depending on the factory thing they describe.

The AbstractDescriptor is described by the following attributes:

The AbstractDescriptor has the following relations:

An AbstractDescriptor can be specialized into:

• CharacteristicDescriptor: it describes static or quasi-static data characterising entities in a factory (e.g., workers, robots). Examples of characteristics for workers are: a skill, an anthropometric characteristic, a job position. Examples of characteristics for machines are: weight, dimension.

• StateDescriptor: it describes the state of entities in a factory. For example, in the case of a worker, possible states are the current task, the next task to perform, the level of perceived fatigue, the current production performance.

• MeasurementDescriptor: it describes a measurement collected from a sensor (usually onboarded on a device), which refers to a factory entity. For example, in the case of a worker, a MeasurementDescriptor can describe the heart rate, measured by a wearable device.

UnitOfMeasure

The class UnitOfMeasure has been defined to facilitate the handling of the units of measure, which can refer to all the AbstractDescriptor(s) (i.e., CharacteristicDescriptor(s), StateDescriptor(s), and MeasurementDescriptor(s)). This class allows the definition of a unit of measurement.

The UnitOfMeasure is described by the following attributes:

Category

The class Category describes an AbstractDescriptor by means of an enumeration. For example, it can be "Anthropometric Characteristic", "Ability", "Skill", etc. It facilitates the organization and structuring of AbstractDescriptor(s).

The Category is described by the following attributes:

The Category has the following relations:

Taxonomy and TaxonomyItem

The Taxonomy class is used to classify an AbstractDescriptor accordingly with a taxonomy (either a well-know taxonomy, like (e.g., O*Net or ESCO for working skills, or a private one , e.g., a taxonomy that organises the roles in the company).

The Taxonomy is described by the following attributes:

The Taxonomy has the following relations:

A Taxonomy is composed by a set of TaxonomyItem(s), which represent the single items that compose a taxonomy (e.g., for the skills taxonomy, each TaxonomyItem represents a skill; in the case of the O*Net taxonomy, “Operation Monitoring”, “Quality Control Analysis”, and “Reading Comprehension” are TaxonomyItems).

The TaxonomyItem is described by the following attributes:

The TaxonomyItem has the following relations:

Scale

The Scale class is used to provide an AbstractDescriptor with a scale that narrows its possible values, making it easier to assign, understand, and interpret the measured value in a meaningful way.

The Scale is described by the following attributes:

3.3 - Event and Interaction Models

This section contains classes that are relevant for defining interactions between entities in the factory.

Note that the required model attributes are indicated with a red asterisk ("*"). For mandatory relations, refer to the multiplicity instead, as relationships are defined on one side only (i.e., a specific relationship might be described within the other related entity).

EventDescriptor and InteractionDescriptor

The EventDescriptor class describes the events that change the HDT status, evolving any of its entities or attributes. An event is related to a single entity. Events involving multiple entities are represented through Interaction(s).

The EventDescriptor is described by the following attributes:

The EventDescriptor has the following relations:

The InteractionDescriptor class specifies the EventDescriptor, requiring the event being an interaction between two or more FactoryEntityModel(s) (e.g., a collision between a robot and a worker, a worker that loads a pallet on an AGV, etc.).

The InteractionDescriptor has the following relations:

For example, a InteractionDescriptor can be “Impact between cobot and worker”, which aggregate the FactoryEntityModel(s) “Assembly Worker” and “Cobot UR10”.

Event and Interaction

The Event class defines an event described by an EventDescriptor.

The Event is described by the following attributes:

The Event class has the following relations:

As per the EventDescriptor class, also the Event class is extended by the Interaction class, which requires the event to involve at least two FactoryEntity(s). Indeed, the Interaction class has the following relations:

3.4 - Intervention Models

This set of classes allows to describe interventions to orchestrate the production system and the things acting within it, optimising performance and/or increasing workers’ wellbeing.

Note that the required model attributes are indicated with a red asterisk ("*"). For mandatory relations, refer to the multiplicity instead, as relationships are defined on one side only (i.e., a specific relationship might be described within the other related entity).

InterventionDescriptor and Intervention

The class InterventionDescriptor allows the definition of interventions that can be triggered to orchestrate the production system and its entities (i.e. the tasks to perform). Examples of intervention descriptors are: to deliver a notification to the operator, to set-up and activate a robot part-program, to turn-on a tool or to adjust the speed of a spindle. Interventions could be fired by the FunctionalModule(s) in charge of decision-making, defining workers and the things of the factory to be triggered.

The InterventionDescriptor is described by the following attributes:

The InterventionDescriptor has the following relations:

The class Intervention describes a triggered and actuated intervention.

The Intervention is described by the following attributes:

The Intervention class has the following relations:

Exemption

The class Exemption allows to specify which FactoryEntity(ies) are exempted from a specific InterventionDescriptor (i.e. task). An Exemption is related to a single entity-task tuple, in order to specify
exemptions related to multiple entities for the same task, or to assign multiple task exemptions to the same entity, it is needed to create different Exemption(s).

The Exemption is described by the following attributes:

The Exemption has the following relations:

3.5 - Measurement Models

This set of classes allows describing measurements and data collected from workers and things in the factory.

Note that the required model attributes are indicated with a red asterisk ("*"). For mandatory relations, refer to the multiplicity instead, as relationships are defined on one side only (i.e., a specific relationship might be described within the other related entity).

MeasurementDescriptor

The MeasurementDescriptor extends the AbstractDescriptor with a specific class dedicated to dynamic data, streamed by wearable devices, sensors and PLCs. These can include any kind of relevant data collected from factory entities. For example, hearth rate, galvanic skin response, vibrations, accelerations, temperature could be modelled through the class MeasurementDescriptor.

The MeasurementDescriptor is composed by the following attributes:

3.6 - Production System Models

This set of classes allows the definition of entities acting in the factory and collecting measurements to feed the HDT.

Note that the required model attributes are indicated with a red asterisk ("*"). For mandatory relations, refer to the multiplicity instead, as relationships are defined on one side only (i.e., a specific relationship might be described within the other related entity).

FactoryEntityModel

The FactoryEntityModel class describes the digital counterpart of the entities populating and thus acting in the factories such as robots, machines, pallets, workers, etc. . Characteristics, states, measurements and interactions of such entity models have to be included in the HDT. It is important to remark that the FactoryEntityModel is a generic representation of a factory entity, not its specific instance. For example, a FactoryEntityModel could be “assembly operator” or “Cobot UR10”. Specific instances of these models can be described in the Worker class, in case of a worker, and in the FactoryEntity in case of any other type of entity.

The FactoryEntityModel is described by the following attributes:

The FactoryEntityModel has the following relations:

For example, a FactoryEntityModel could be Cobot UR10 which could be composed by the following AbstractDescriptor(s):

• CharactersticDescriptor: reach, number of joints, installation date, etc.
• StateDescriptor: availability, current end-effector, current task, next task to be performed, etc.
• MeasurementDescriptor: joints position, workbench vibration, etc.

FactoryEntityModelCategory

The FactoryEntityModelCategory specifies the category of a FactoryEntityModel. In this way, it is possible to organize FactoryEntityModel(s). For example, the FactoryEntityModel “wearable device” may be assigned to two different categories: “wrist band” and “chest band”.

The FactoryEntityModelCategory is described by the following attributes:

DeviceModel

The DeviceModel is used to describe any device that generates measurements, including sensors, machines and wearables. Exactly like the FactoryEntityModel, the DeviceModel is a generic description of a device (it is not a specific instance). The need for this class arises from the fact that device models (e.g., vibration sensor SW-420, Siemens Simatic S7-1200), including wearables (e.g. Garmin Instinct) collect measurements in different ways and with different data structures. The DeviceModel class allows a particular device model to be described, enabling the mapping of physical device outputs to one or more MeasurementDescriptor(s) or StateDescriptor(s) in the HDT, minimizing the overhead of connecting devices of the same model.

The DeviceModel is described by the following attributes:

The DeviceModel has the following relations:

OutputMap

The OutputMap maps a physical parameter measured by a device with the field described by a MeasurementDescriptor, making the descriptor independent from the device models. A DeviceModel can produce different types of measurements (e.g., heart rate, blood pressure, etc.). This measurement must be created and described in the HDT using MeasurementDescriptor(s) so that other components can interact with it. Therefore, the stream of a device data must be mapped and connected to a MeasurementDescriptor. Moreover, different DeviceModel(s) may feed the same MeasurementDescriptor. For example, two wearable device models (e.g., Garmin Instinct and Polar OH1), may provide the same measurement (e.g., hearth rate). However, a user wants to have a unique representation of that measurement in the HDT. Therefore, a unique MeasurementDescriptor is created in the HDT, and each wearable model has an OutputMap, mapping the different outputs of the wearables to the same MeasurementDescriptor.

The OutputMap is described by the following attributes:

The OutputMap has the following relations:

FactoryEntity

The FactoryEntity class allows the creation of instances of entities in a factory described through a FactoryEntityModel. The FactoryEntity is a specific entity that populates the factory.

The FactoryEntity is described by the following attributes:

The FactoryEntity has the following relations:

Factory

The Factory class allows the definition of a factory where the FactoryEntity(s) act and operate, being able to have HDT representing entities in different production systems.

The Factory is described by the following attributes:

Session

The Session class allows data collection or working sessions to be defined; in such a way, the HDT tracks exactly when a particular FactoryEntity performs a specific activity, and to match Event(s), Interaction(s), and Intervention(s) with specific time slots.

The Session is composed by the following attributes:

The Session has the following relations:

3.7 - State Models

This set of classes aims at describing states characterizing factory entities. States are computed by functional modules, which describe all those computational processes that can elaborate entities and attributes, making the HDT capable of simulating, predicting, reasoning, and deciding. The class FunctionalModule aggregates one or more events that can be used to update the state of the HDT depending on the result of the computation performed. Inputs are defined and mapped through the class FunctionalModuleInput to the entities needed by the model (e.g., physiological parameters and worker conditions for detecting fatigue level). Internally, functional models can employ any mean of data processing and calculation such as mathematical functions, machine learning, or empirical models. These, if necessary, can be stored as binary blobs and annotated to be managed correctly.

Note that the required model attributes are indicated with a red asterisk ("*"). For mandatory relations, refer to the multiplicity instead, as relationships are defined on one side only (i.e., a specific relationship might be described within the other related entity).

StateDescriptor

The StateDescriptor extends the AbstractDescriptor with a specific class dedicated to the description of states of both workers and things in the factory. These states are computed by the FunctionalModule(s). The StateDescriptor can describe the state of a cobot in the form of the current pose, current part program, or the position or the fatigue level of a worker.

The StateDescriptor has the following relations:

FunctionalModule

The FunctionalModule class allows to describe any model that generates states. A model could be an AI algorithm or a simple data processor. The FunctionalModule defines a model that acts in the HDT and produces outputs that feed the HDT state. An example of FunctionalModule is the Fatigue Monitoring System or an Activity Detection Module.

The FunctionalModule is described by the following attributes:

The FunctionalModule has the following relations:

FunctionalModuleInput

The FunctionaModelInput supports the mapping that relates an AbstractDescriptor modelled into the HDT to an input that feeds the FunctionalModule. It allows the HDT to integrate modules that require input data with different structures than those described by MeasurementDescriptor(s), CharacteristicDescriptor(s) and StateDescriptor(s).

The FunctionalModule is described by the following attributes:

FunctionalModuleOutput

The FunctionalModulOutput supports the mapping that relates the outputs of a FunctionalModule and the related StateDescriptor(s) into the HDT. It allows the HDT to integrate modules that provide output data with different structures than those described as a StateDescriptor.

The FunctionalModule is described by the following attributes:

Block

The Block class is a utility entity that enables the formalization of the schema that describes the StateDescriptor(s), thus allowing the HDT to be aware of the data format. This helps FunctionalModule’s output validation against the schema, and also to translate/map an output schema of a module to an input schema of another module.

The Block structure describes every object's schema which contains coherent lists (a list that comprises elements of the same kind). For example, the location of different workers could be represented as follow (for simplicity the JSON format is used):

{
  "id": 10,
  "workers": [
    {"id": 10, "x": 10, "y": 20, "pose": "stand"},
    {"id": 20, "x": 23, "y": 40, "pose": "sit"},
    {"id": 30, "x": 10, "y": 20, "pose": "lying down"}
  ]
}

This example of output could be easily described through the use of the Block class:

• StructBased workerBlock:
  • “id” → NumberBased
  • “x” → NumberBased
  • “y” → NumberBased
  • “pose” → StringBased
• ListBased workersListBlock describe a list of workerBlock:
• StructBased overallBlock describes the whole object as it follows:
  • “id” → NumberBased
  • “workers” → workersListBlock

ListBased

The ListBased class inherits from Block and describes a list that contains elements structured as a Block, enabling the definition of a coherent list that comprises data of the same type.

StructBased

The StructBased class inherits from Block and describes a structure of Block(s). It can be seen as a dictionary with string keys and Block values.

The StructBased is described by the following attributes:

StringBased

The StringBased block describes a simple attribute of type string, which can be part of a StructBased or ListBased.

NumberBased

The NumberBased block describes a simple numerical attribute, which can be part of a StructBased or ListBased.

BooleanBased

The BooleanBased block describes a simple bo attribute, which can be part of a StructBased or ListBased.

3.8 - Worker Models

This section contains classes that are relevant for defining worker instances.

Worker

The class Worker allows the definition of worker instances. This class is used to represent a specific worker in the production system.

As of today, the class just inherits its parent’s properties and relationships, but it’s worth be noted that having a dedicated class enables a fine-grained management of the HDT entities by the HDT user. For example, measurements related to workers may require additional data preserving rules (e.g., when collecting biometrics data); moreover, workers can be “anonymized” within the HDT (e.g., the referenceCode may be missing or an anonymous code), while this operation is meaningless for other factory entities in almost all the cases. Moreover, the behaviour of factory entities is in general predictable with well-established models, while the behaviour of workers may be unpredictable (due to non-measurable features, like emotions), and this point plays a crucial role in an HDT. For this reason, it is important to distinguish workers from other nonhuman factory entities.

4 - How to

Interact with the platform

• Creating and reading entities and characteristics → Orchestrator REST API
• Saving and reading real-time metrics and states → IIoT Middleware
• Reading historical metrics and states → HDM REST API

4.1 - Orchestrator REST API

Create and read entities

The Orchestrator REST API enables to create and read all the different kinds of Digital Twin entities described in Model section.

This API is available through a dedicated Swagger interface for each Clawdite instance. Furthermore, it is possible to generate API clients for several languages, such as Python, Java and JavaScript. The mentioned clients are already generated and available within each Clawdite instance and make it possible to interact with Clawdite’s Orchestrator from external components.

In the following a few examples on entities management will be provided.

Install the Orchestrator client dependencies

In order to use the generated API clients inside external components it is needed to correctly setup and install the dependencies. Note that you need a personal GitLab token for accessing the registries. In case you don’t have it please contact the project’s maintainers.

• Language:
• Pip
• Maven

pip install orchestrator-python-client --index-url https://__token__:<your_personal_token>@gitlab-core.supsi.ch/api/v4/projects/86/packages/pypi/simple

<dependencies>
    <dependency>
      <groupId>ch.supsi.dti.isteps.hdt</groupId>
      <artifactId>orchestrator-java-client</artifactId>
      <version>0.2.3</version>
    </dependency>
</dependencies>

<repositories>
  <repository>
    <id>gitlab-maven</id>
    <url>https://gitlab-core.supsi.ch/api/v4/projects/86/packages/maven</url>
  </repository>
</repositories>

Create a Worker

In order to create a Worker entity (or a FactoryEntity in general) it is mandatory to define the associated FactoryEntityModelCategoty and FactoryEntityModel in advance.

• Language:
• Python
• Java

import os
from datetime import datetime
import orchestrator_python_client as hdt_client
from orchestrator_python_client import ApiClient, FactoryEntityModelCategoryDto, FactoryEntityModelDto, WorkerDto

# NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables

configuration = hdt_client.Configuration(host=os.getenv('HDT_ENDPOINT'))
configuration.api_key['apiKeyAuth'] = os.getenv('HDT_API_KEY')
api_client = hdt_client.ApiClient(configuration)

factory_entity_model_category_api = hdt_client.FactoryEntityModelCategoryApi(api_client)
factory_entity_model_api = hdt_client.FactoryEntityModelApi(api_client)
worker_api = hdt_client.WorkerApi(api_client)

operator_category = factory_entity_model_category_api.create_factory_entity_model_category(
                        FactoryEntityModelCategoryDto(name="Operator",
                            description="description")).payload

worker_model = factory_entity_model_api.create_factory_entity_model(
                        FactoryEntityModelDto(name="Worker",
                            description="description",
                            factory_entity_model_categories_id=[operator_category.id])).payload

worker = worker_api.create_worker(
                        WorkerDto(creation_date=datetime.now().isoformat(),
                            factory_entity_model_id=worker_model.id)).payload

import java.util.Collections;
import java.time.LocalDateTime;
import org.openapitools.client.ApiClient;
import org.openapitools.client.api.FactoryEntityModelCategoryApi;
import org.openapitools.client.api.FactoryEntityModelApi;
import org.openapitools.client.api.WorkerApi;
import org.openapitools.client.model.FactoryEntityModelCategoryDto;
import org.openapitools.client.model.FactoryEntityModelDto;
import org.openapitools.client.model.WorkerDto;

private void createWorker() {
    // NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables
    ApiClient apiClient = new ApiClient().setBasePath(System.getenv("HDT_ENDPOINT"));
    String apiKey = System.getenv("HDT_API_KEY");
    if(apiKey != null && !apiKey.isEmpty())
        apiClient.addDefaultHeader("x-api-key", apiKey);

    final FactoryEntityModelCategoryApi factoryEntityModelCategoryApi = new FactoryEntityModelCategoryApi(apiClient);
    final FactoryEntityModelApi factoryEntityModelApi = new FactoryEntityModelApi(apiClient);
    final WorkerApi workerApi = new WorkerApi(apiClient);

    FactoryEntityModelCategoryDto operatorCategory = factoryEntityModelCategoryApi.createFactoryEntityModelCategory(
            new FactoryEntityModelCategoryDto()
                    .setName("Operator")
                    .setDescription("description"));

    FactoryEntityModelDto workerModel = factoryEntityModelApi.createFactoryEntityModel(
            new FactoryEntityModelDto()
                    .setName("Worker")
                    .setDescription("description")
                    .setFactoryEntityModelCategoriesId(Collections.singletonList(operatorCategory.getId())));

    WorkerDto worker = workerApi.createWorker(
            new WorkerDto()
                    .setCreationDate(LocalDateTime.now().toString())
                    .setFactoryEntityModelId(workerModel.getId()));

}

Read a Worker

In order to retrieve a Worker entity (or an entity in general) it is mandatory to specify the associated entity ID.

• Language:
• Python
• Java

import os
import orchestrator_python_client as hdt_client
from orchestrator_python_client import ApiClient, WorkerDto

# NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables

configuration = hdt_client.Configuration(host=os.getenv('HDT_ENDPOINT'))
configuration.api_key['apiKeyAuth'] = os.getenv('HDT_API_KEY')
api_client = hdt_client.ApiClient(configuration)

worker_api = hdt_client.WorkerApi(api_client)

# NOTE: you need to specify the worker_id UUID
worker_id = "3fa85f64-5717-4562-b3fc-2c963f66afa6"

worker = worker_api.get_worker_by_id(worker_id)

import java.util.Collections;
import java.time.LocalDateTime;
import org.openapitools.client.ApiClient;
import org.openapitools.client.api.WorkerApi;
import org.openapitools.client.model.WorkerDto;

private void readWorker() {
    // NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables
    ApiClient apiClient = new ApiClient().setBasePath(System.getenv("HDT_ENDPOINT"));
    String apiKey = System.getenv("HDT_API_KEY");
    if(apiKey != null && !apiKey.isEmpty())
        apiClient.addDefaultHeader("x-api-key", apiKey);

    final WorkerApi workerApi = new WorkerApi(apiClient);

    // NOTE: you need to specify the workerId UUID
    workerId = "3fa85f64-5717-4562-b3fc-2c963f66afa6";

    WorkerDto worker = workerApi.getWorkerById(workerId);
}

Create a FunctionalModule

Despite the creation of a FunctionalModule entity in not dependent on other entities, it is important to define the associated FunctionalModuleInput, FunctionalModuleOutput and Block in order to correctly create the StateDescriptor related to the FunctionalModule (i.e. its output that will be sent to the IIoT Middleware).

• Language:
• Python
• Java

import os
from datetime import datetime
import orchestrator_python_client as hdt_client
from orchestrator_python_client import ApiClient, FunctionalModuleDto, FunctionalModuleInputDto,
    FunctionalModuleOutputDto, NumberBasedDto, StateDescriptorDto

# NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables

configuration = hdt_client.Configuration(host=os.getenv('HDT_ENDPOINT'))
configuration.api_key['apiKeyAuth'] = os.getenv('HDT_API_KEY')
api_client = hdt_client.ApiClient(configuration)

functional_module_api = hdt_client.FunctionalModuleApi(api_client)
functional_module_input_api = hdt_client.FunctionalModuleInputApi(api_client)
functional_module_output_api = hdt_client.FunctionalModuleOutputApi(api_client)
number_based_api = hdt_client.NumberBasedApi(api_client)
state_descriptor_api = hdt_client.StateDescriptorApi(api_client)

custom_module = functional_module_api.create_functional_module(
                        FunctionalModuleDto(name="CustomModule", description="description")).payload

custom_module_input = functional_module_input_api.create_functional_module_input(
                        FunctionalModuleInputDto(input_param_name="hr", path="HR", functional_module_id=custom_module.id,
                                    descriptor_id=hr_descriptor.id)).payload

custom_module_output = functional_module_output_api.create_functional_module_output(
                        FunctionalModuleOutputDto(functional_module_id=custom_module.id,
                                    output_param_name="CustomPrediction")).payload

number_based_dto = number_based_api.create_number_based(NumberBasedDto()).payload

custom_module_state_descriptor = state_descriptor_api.create_state_descriptor(
                        StateDescriptorDto(functional_module_output_id=custom_module_output.id,  # to know the origin of the State
                                    blockId=number_based_dto.id,  # link the data structure
                                    name="CustomModuleState",
                                    description="prediction",
                                    factory_entity_model_id=worker_model.id)  # the prediction is related workers
                    ).payload

import java.util.Collections;
import java.time.LocalDateTime;
import org.openapitools.client.ApiClient;
import org.openapitools.client.api.FactoryEntityModelCategoryApi;
import org.openapitools.client.api.FactoryEntityModelApi;
import org.openapitools.client.api.WorkerApi;
import org.openapitools.client.model.FactoryEntityModelCategoryDto;
import org.openapitools.client.model.FactoryEntityModelDto;
import org.openapitools.client.model.WorkerDto;

private void createFunctionalModule() {
    // NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables
    ApiClient apiClient = new ApiClient().setBasePath(System.getenv("HDT_ENDPOINT"));
    String apiKey = System.getenv("HDT_API_KEY");
    if(apiKey != null && !apiKey.isEmpty())
        apiClient.addDefaultHeader("x-api-key", apiKey);
    
    final FunctionalModuleApi functionalModuleApi = new FunctionalModuleApi(apiClient);
    final FunctionalModuleInputApi functionalModuleInputApi = new FunctionalModuleInputApi(apiClient);
    final FunctionalModuleOutputApi functionalModuleOutputApi = new FunctionalModuleOutputApi(apiClient);
    final NumberBasedApi numberBasedApi = new NumberBasedApi(apiClient);
    final StateDescriptorApi = new StateDescriptorApi(apiClient);

    FunctionalModuleDto customModule = FunctionalModuleApi.createFunctionalModule(
            new FunctionalModuleDto()
                    .setName("CustomName")
                    .setDescription("description"));

    FunctionalModuleInputDto customModuleInput = FunctionalModuleInputApi.createFunctionalModuleInput(
            new FunctionalModuleInputDto()
                    .setInputParameterName("hr")
                    .setPath("HR")
                    .setFunctionalModuleId(customModule.getId())
                    .setDescriptorId(hrDescriptor.getId()));

    FunctionalModuleOutputDto customModuleOutput = FunctionalModuleOutputApi.createFunctionalModuleOutput(
            new FunctionalModuleOutputDto()
                    .setFunctionalModuleId(customModule.getId())
                    .setOutputParameterName("CustomPrediction"));

    NumberBasedDto numberBased = NumberBasedApi.createNumberBased(new NumberBasedDto());

    StateDescriptorDto customModuleStateDescriptor = StateDescriptorApi.createStateDescriptor(
            new FunctionalModuleOutputDto()
                    .setFunctionalModuleOutputId(customModuleOutput.getId()) // to know the origin of the State
                    .setBlockId(numberBased.getId()) // link the data structure
                    .setName("CustomModuleState")
                    .setDescription("prediction")
                    .setFactoryEntityModelId(workerModel.getId())); // the prediction is related workers
}

4.2 - IIoT Middleware

Save and read real-time metrics and states

The IIoT Middleware enables dynamic data published from Gateways and Functional Modules to be collected and made available to other interested modules, such as the HDM which is in charge of persisting them.

Currently only the MQTT protocol is supported, so modules need to publish and subscribe to specific topics. MQTT clients are available for different languages, in the following a few examples in Python and Java will be provided. Please refer to the official documentation to learn more about how to use the client in your project.

The topic schema is HDT/{factory_entity_id}/{measurement/state}/{descriptor_id}/{value}.

The message schema is {timestamp}#{value}.

Publish a Metric

In order to publish a metric value to the IIoT Middleware for making it available to other components, specific topics structure and message format need to be used.

Note that, if the metric to be saved is composed by multiple fields, then the associated values need to be separated by a pipe "|". For example: "1752760778790#1|2|3.

• Language:
• Python
• Java

import os
from datetime import datetime
from paho.mqtt.client import Client
from paho.mqtt.enums import CallbackAPIVersion

def on_connect(client, userdata, flags, reason_code, properties):
    loguru.logger.debug(f'Connected with result code "{reason_code}"')


# NOTE: you need to specify the MQTT_HOST, MQTT_PORT, MQTT_USER and MQTT_PASSWORD environment variables
mqtt_client = Client(client_id='unique-id', callback_api_version=CallbackAPIVersion.VERSION2)
mqtt_client.username_pw_set(os.getenv("MQTT_USER"), os.getenv("MQTT_PASSWORD"))
mqtt_client.on_connect = on_connect
mqtt_client.connect(os.getenv('MQTT_HOST'), int(os.getenv("MQTT_PORT")))
quality_of_service = 1

# NOTE: you need to specify the measurement_descriptor_id and worker_id UUIDs
measurement_descriptor_id = "3fa85f64-5717-4562-b3fc-2c963f66afa6"
worker_id = "3fa85f64-5717-4562-b3fc-2c963f66afa6"
value = 15.0

mqtt_client.publish(f'HDT/{worker_id}/measurement/{measurement_descriptor_id}',
                    f'{int(datetime.now().timestamp() * 1000)}#{value}', quality_of_service)

time.sleep(1)  # wait for the messages to be sent
mqtt_client.disconnect()
                           

import org.eclipse.paho.client.mqttv3.MqttCallback;
import org.eclipse.paho.client.mqttv3.IMqttDeliveryToken;
import org.eclipse.paho.client.mqttv3.MqttClient;
import org.eclipse.paho.client.mqttv3.MqttConnectOptions;
import org.eclipse.paho.client.mqttv3.MqttException;
import org.eclipse.paho.client.mqttv3.MqttMessage;
import org.eclipse.paho.client.mqttv3.MqttCallbackExtended;
import java.util.UUID;
import java.util.concurrent.TimeUnit;

private void publishMetric() {
    // NOTE: you need to specify the MQTT_HOST, MQTT_PORT, MQTT_USER and MQTT_PASSWORD environment variables
    String broker = "tcp://" + System.getenv("MQTT_HOST") + ":" + System.getenv("MQTT_PORT");
    String clientId = "unique-id";
    int qos = 1;
    
    // NOTE: you need to specify the measurement_descriptor_id and worker_id UUIDs
    String measurementDescriptorId = "3fa85f64-5717-4562-b3fc-2c963f66afa6";
    String workerId = "3fa85f64-5717-4562-b3fc-2c963f66afa6";
    double value = 15.0;

    try {
        MqttClient mqttClient = new MqttClient(broker, "unique-id");
        MqttConnectOptions connOpts = new MqttConnectOptions();
        connOpts.setUserName(System.getenv("MQTT_USER"));
        connOpts.setPassword(System.getenv("MQTT_PASSWORD").toCharArray());

        // Set callback for connection
        mqttClient.setCallback(new MqttCallbackExtended() {
            @Override
            public void connectComplete(boolean reconnect, String serverURI) {
                System.out.println("Connected to " + serverURI);
            }

            @Override
            public void connectionLost(Throwable cause) {
                System.out.println("Connection lost: " + cause.getMessage());
            }

            @Override
            public void messageArrived(String topic, MqttMessage message) throws Exception {
                // Not used in this case, since we are publishing only
            }

            @Override
            public void deliveryComplete(IMqttDeliveryToken token) {
                System.out.println("Message delivered successfully");
            }
        });

        mqttClient.connect(connOpts);
        
        long timestamp = System.currentTimeMillis();
        String message = timestamp + "#" + value;
        mqttClient.publish("HDT/" + workerId + "/measurement/" + measurementDescriptorId,
                new MqttMessage(message.getBytes()));

        TimeUnit.SECONDS.sleep(1);
        mqttClient.disconnect();


    } catch (MqttException | InterruptedException e) {
        e.printStackTrace();
    }
}

Publish a State

In order to publish a state value to the IIoT Middleware for making it available to other components, specific topics structure and message format need to be used.

• Language:
• Python
• Java

import os
from datetime import datetime
from paho.mqtt.client import Client
from paho.mqtt.enums import CallbackAPIVersion

def on_connect(client, userdata, flags, reason_code, properties):
    loguru.logger.debug(f'Connected with result code "{reason_code}"')


# NOTE: you need to specify the MQTT_HOST, MQTT_PORT, MQTT_USER and MQTT_PASSWORD environment variables
mqtt_client = Client(client_id='unique-id', callback_api_version=CallbackAPIVersion.VERSION2)
mqtt_client.username_pw_set(os.getenv("MQTT_USER"), os.getenv("MQTT_PASSWORD"))
mqtt_client.on_connect = on_connect
mqtt_client.connect(os.getenv('MQTT_HOST'), int(os.getenv("MQTT_PORT")))
quality_of_service = 1

# NOTE: you need to specify the state_descriptor_id and worker_id UUIDs
state_descriptor_id = "3fa85f64-5717-4562-b3fc-2c963f66afa6"
worker_id = "3fa85f64-5717-4562-b3fc-2c963f66afa6"
value = {"fatigue": [5, 10]}

mqtt_client.publish(f'HDT/{worker_id}/state/{state_descriptor_id}',
                    f'{int(datetime.now().timestamp() * 1000)}#{value}', quality_of_service)

time.sleep(1)  # wait for the messages to be sent
mqtt_client.disconnect()

                               

import org.eclipse.paho.client.mqttv3.MqttCallback;
import org.eclipse.paho.client.mqttv3.IMqttDeliveryToken;
import org.eclipse.paho.client.mqttv3.MqttClient;
import org.eclipse.paho.client.mqttv3.MqttConnectOptions;
import org.eclipse.paho.client.mqttv3.MqttException;
import org.eclipse.paho.client.mqttv3.MqttMessage;
import org.eclipse.paho.client.mqttv3.MqttCallbackExtended;
import java.util.UUID;
import java.util.concurrent.TimeUnit;

private void publishState() {
    // NOTE: you need to specify the MQTT_HOST, MQTT_PORT, MQTT_USER and MQTT_PASSWORD environment variables
    String broker = "tcp://" + System.getenv("MQTT_HOST") + ":" + System.getenv("MQTT_PORT");
    String clientId = "unique-id";
    int qos = 1;

    // NOTE: you need to specify the state_descriptor_id and worker_id UUIDs
    String stateDescriptorId = "3fa85f64-5717-4562-b3fc-2c963f66afa6";
    String workerId = "3fa85f64-5717-4562-b3fc-2c963f66afa6";
    String value = "{\"fatigue\": [5, 10]}";

    try {
        MqttClient mqttClient = new MqttClient(broker, "unique-id");
        MqttConnectOptions connOpts = new MqttConnectOptions();
        connOpts.setUserName(System.getenv("MQTT_USER"));
        connOpts.setPassword(System.getenv("MQTT_PASSWORD").toCharArray());

        // Set callback for connection
        mqttClient.setCallback(new MqttCallbackExtended() {
            @Override
            public void connectComplete(boolean reconnect, String serverURI) {
                System.out.println("Connected to " + serverURI);
            }

            @Override
            public void connectionLost(Throwable cause) {
                System.out.println("Connection lost: " + cause.getMessage());
            }

            @Override
            public void messageArrived(String topic, MqttMessage message) throws Exception {
                // Not used in this case, since we are publishing only
            }

            @Override
            public void deliveryComplete(IMqttDeliveryToken token) {
                System.out.println("Message delivered successfully");
            }
        });

        mqttClient.connect(connOpts);

        long timestamp = System.currentTimeMillis();
        String message = timestamp + "#" + value;
        mqttClient.publish("HDT/" + workerId + "/state/" + stateDescriptorId,
                new MqttMessage(message.getBytes()));

        TimeUnit.SECONDS.sleep(1);
        mqttClient.disconnect();


    } catch (MqttException | InterruptedException e) {
        e.printStackTrace();
    }
}

Read a Metric

In order to read real-time metric values published to the IIoT Middleware, it is mandatory to subscribe to the topics of interest and to specify a callback for managing the received message.

• Language:
• Python
• Java

import os
import time
from paho.mqtt.client import Client
from paho.mqtt.enums import CallbackAPIVersion

# NOTE: you need to specify the measurement_descriptor_id and worker_id UUIDs
def on_connect(client, userdata, flags, reason_code, properties):
    measurement_descriptor_id = "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    worker_id = "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    topic = f'HDT/{worker_id}/measurement/{measurement_descriptor_id}'
    client.subscribe(topic, qos=1)

def on_message(client, userdata, msg):
    print(f'Received message: {msg.payload.decode()} on topic {msg.topic}')

# NOTE: you need to specify the MQTT_HOST, MQTT_PORT, MQTT_USER, and MQTT_PASSWORD environment variables
mqtt_client = Client(client_id='unique-id', callback_api_version=CallbackAPIVersion.VERSION2)
mqtt_client.username_pw_set(os.getenv("MQTT_USER"), os.getenv("MQTT_PASSWORD"))
mqtt_client.on_connect = on_connect
mqtt_client.on_message = on_message

mqtt_client.connect(os.getenv('MQTT_HOST'), int(os.getenv("MQTT_PORT")))
mqtt_client.loop_start()

import org.eclipse.paho.client.mqttv3.MqttCallback;
import org.eclipse.paho.client.mqttv3.IMqttDeliveryToken;
import org.eclipse.paho.client.mqttv3.MqttClient;
import org.eclipse.paho.client.mqttv3.MqttConnectOptions;
import org.eclipse.paho.client.mqttv3.MqttException;
import org.eclipse.paho.client.mqttv3.MqttMessage;
import org.eclipse.paho.client.mqttv3.MqttCallbackExtended;
import java.util.UUID;

private void readMetric() {
    // NOTE: you need to specify the MQTT_HOST, MQTT_PORT, MQTT_USER, and MQTT_PASSWORD environment variables
    String broker = "tcp://" + System.getenv("MQTT_HOST") + ":" + System.getenv("MQTT_PORT");
    String clientId = UUID.randomUUID().toString();
    
    // NOTE: you need to specify the measurementDescriptorId and workerId UUIDs
    String measurementDescriptorId = "3fa85f64-5717-4562-b3fc-2c963f66afa6";
    String workerId = "3fa85f64-5717-4562-b3fc-2c963f66afa6";
    topic = "HDT/"+workerId+"/measurement/"+measurementDescriptorId;

    try {
        MqttClient mqttClient = new MqttClient(broker, clientId);
        MqttConnectOptions connOpts = new MqttConnectOptions();
        connOpts.setUserName(System.getenv("MQTT_USER"));
        connOpts.setPassword(System.getenv("MQTT_PASSWORD").toCharArray());
    
        // Set callback for connection and message reception
        mqttClient.setCallback(new MqttCallbackExtended() {
            @Override
            public void connectComplete(boolean reconnect, String serverURI) {
                System.out.println("Connected to " + serverURI);
            }
    
            @Override
            public void connectionLost(Throwable cause) {
                System.out.println("Connection lost: " + cause.getMessage());
            }
    
            @Override
            public void messageArrived(String topic, MqttMessage message) throws Exception {
                String receivedMessage = new String(message.getPayload());
                System.out.println("Message received on topic " + topic + ": " + receivedMessage);
            }
    
            @Override
            public void deliveryComplete(IMqttDeliveryToken token) {
                // Not used in this case, since we are subscribing only
            }
        });
    
        mqttClient.connect(connOpts);
        mqttClient.subscribe(topic);
    
    } catch (MqttException e) {
        e.printStackTrace();
    }
}

Read a State

In order to read real-time state values published to the IIoT Middleware, it is mandatory to subscribe to the topics of interest and to specify a callback for managing the received message.

• Language:
• Python
• Java

import os
import time
from paho.mqtt.client import Client
from paho.mqtt.enums import CallbackAPIVersion

# NOTE: you need to specify the state_descriptor_id and worker_id UUIDs
def on_connect(client, userdata, flags, reason_code, properties):
state_descriptor_id = "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    worker_id = "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    topic = f'HDT/{worker_id}/state/{state_descriptor_id}'
    client.subscribe(topic, qos=1)

def on_message(client, userdata, msg):
    print(f'Received message: {msg.payload.decode()} on topic {msg.topic}')

# NOTE: you need to specify the MQTT_HOST, MQTT_PORT, MQTT_USER, and MQTT_PASSWORD environment variables
mqtt_client = Client(client_id='unique-id', callback_api_version=CallbackAPIVersion.VERSION2)
mqtt_client.username_pw_set(os.getenv("MQTT_USER"), os.getenv("MQTT_PASSWORD"))
mqtt_client.on_connect = on_connect
mqtt_client.on_message = on_message

mqtt_client.connect(os.getenv('MQTT_HOST'), int(os.getenv("MQTT_PORT")))
mqtt_client.loop_start()

import org.eclipse.paho.client.mqttv3.MqttCallback;
import org.eclipse.paho.client.mqttv3.IMqttDeliveryToken;
import org.eclipse.paho.client.mqttv3.MqttClient;
import org.eclipse.paho.client.mqttv3.MqttConnectOptions;
import org.eclipse.paho.client.mqttv3.MqttException;
import org.eclipse.paho.client.mqttv3.MqttMessage;
import org.eclipse.paho.client.mqttv3.MqttCallbackExtended;
import java.util.UUID;

private void readState() {
    // NOTE: you need to specify the MQTT_HOST, MQTT_PORT, MQTT_USER, and MQTT_PASSWORD environment variables
    String broker = "tcp://" + System.getenv("MQTT_HOST") + ":" + System.getenv("MQTT_PORT");
    String clientId = UUID.randomUUID().toString();

    // NOTE: you need to specify the stateDescriptorId and workerId UUIDs
    String stateDescriptorId = "3fa85f64-5717-4562-b3fc-2c963f66afa6";
    String workerId = "3fa85f64-5717-4562-b3fc-2c963f66afa6";
    topic = "HDT/"+workerId+"/state/"+stateDescriptorId;

    try {
        MqttClient mqttClient = new MqttClient(broker, clientId);
        MqttConnectOptions connOpts = new MqttConnectOptions();
        connOpts.setUserName(System.getenv("MQTT_USER"));
        connOpts.setPassword(System.getenv("MQTT_PASSWORD").toCharArray());
    
        // Set callback for connection and message reception
        mqttClient.setCallback(new MqttCallbackExtended() {
            @Override
            public void connectComplete(boolean reconnect, String serverURI) {
                System.out.println("Connected to " + serverURI);
            }
    
            @Override
            public void connectionLost(Throwable cause) {
                System.out.println("Connection lost: " + cause.getMessage());
            }
    
            @Override
            public void messageArrived(String topic, MqttMessage message) throws Exception {
                String receivedMessage = new String(message.getPayload());
                System.out.println("Message received on topic " + topic + ": " + receivedMessage);
            }
    
            @Override
            public void deliveryComplete(IMqttDeliveryToken token) {
                // Not used in this case, since we are subscribing only
            }
        });
    
        mqttClient.connect(connOpts);
        mqttClient.subscribe(topic);
    
    } catch (MqttException e) {
        e.printStackTrace();
    }
}

4.3 - HDM REST API

Read historical metrics and states

The HDM REST API enables to get all the historical data related to metrics and states (i.e. dynamic data) that were published to the IIoT Middleware and persisted through the HDM, as described in Architecture section.

This API is available through a dedicated Swagger interface for each Clawdite instance. Furthermore, it is possible to generate API clients for several languages, such as Python, Java and JavaScript. The mentioned clients are already generated and available within each Clawdite instance and make it possible to interact with Clawdite’s HDM from external components.

In the following a few examples on data retrieval will be provided. Independently on the type of data, there are 4 retrieval modalities:

• Get the last X data
• Get the first X data from a specific point in time
• Get the data included in a specific time-range (i.e. 1 hour, 1 day, 1 week…)
• Get the data included in a specific time-interval (i.e. from date X to date Y)

Install the HDM client dependencies

In order to use the generated API clients inside external components it is needed to correctly setup and install the dependencies. Note that you need a personal GitLab token for accessing the registries. In case you don’t have it please contact the project’s maintainers.

• Language:
• Pip
• Maven

pip install hdm-web-python-client --index-url https://__token__:<your_personal_token>@gitlab-core.supsi.ch/api/v4/projects/137/packages/pypi/simple

<dependencies>
    <dependency>
      <groupId>ch.supsi.dti.isteps.hdt</groupId>
      <artifactId>hdm-web-java-client</artifactId>
      <version>0.2.2</version>
    </dependency>
</dependencies>

<repositories>
  <repository>
    <id>gitlab-maven</id>
    <url>https://gitlab-core.supsi.ch/api/v4/projects/137/packages/maven</url>
  </repository>
</repositories>

Read Metrics

In this example the last 10 metrics are retrieved. The use of the other retrieval modalities is similar.

• Language:
• Python
• Java

import os
from datetime import datetime
import hdm_web_python_client as hdm_client
from orchestrator_python_client import ApiClient


# NOTE: you need to specify the HDM_ENDPOINT and HDM_API_KEY environment variables
configuration = hdm_client.Configuration(host=os.getenv('HDM_ENDPOINT'))
configuration.api_key['apiKeyAuth'] = os.getenv('HDM_API_KEY')
api_client = hdm_client.ApiClient(configuration)
hdm_api = hdm_client.HdmControllerApi(api_client)

# NOTE: you need to specify the measurement_descriptor_id and worker_id UUIDs
measurement_descriptor_id = "3fa85f64-5717-4562-b3fc-2c963f66afa6"
worker_id = "3fa85f64-5717-4562-b3fc-2c963f66afa6"

values = hdm_api.read_last_values(abstract_descriptor_id=measurement_descriptor_id,
                                          factory_entity_id=worker_id,
                                          number_of_last_values=10)                            

import java.util.Collections;
import java.time.LocalDateTime;
import org.openapitools.client.ApiClient;
import org.openapitools.client.api.HdmApi;
import org.openapitools.client.model.GenericValueDto;
import org.springframework.data.domain.Page;

private void readMetrics() {
    // NOTE: you need to specify the HDM_ENDPOINT and HDM_API_KEY environment variables
    ApiClient apiClient = new ApiClient().setBasePath(System.getenv("HDM_ENDPOINT"));
    String apiKey = System.getenv("HDM_API_KEY");
    if (apiKey != null && !apiKey.isEmpty())
        apiClient.addDefaultHeader("x-api-key", apiKey);
    final HdmApi hdmApi = new HdmApi(apiClient);
    
    // NOTE: you need to specify the measurementDescriptorId and workerId UUIDs
    measurementDescriptorId = "3fa85f64-5717-4562-b3fc-2c963f66afa6";
    workerId = "3fa85f64-5717-4562-b3fc-2c963f66afa6";
    numberOfLastValues = 10;

    Page<GenericValueDto> values = hdmApi.readLastValues(measurementDescriptorId, workerId, numberOfLastValues);
}

Read States

In this example the last 10 states are retrieved. The use of the other retrieval modalities is similar.

• Language:
• Python
• Java

import os
from datetime import datetime
import hdm_web_python_client as hdm_client
from orchestrator_python_client import ApiClient


# NOTE: you need to specify the HDM_ENDPOINT and HDM_API_KEY environment variables
configuration = hdm_client.Configuration(host=os.getenv('HDM_ENDPOINT'))
configuration.api_key['apiKeyAuth'] = os.getenv('HDM_API_KEY')
api_client = hdm_client.ApiClient(configuration)
hdm_api = hdm_client.HdmControllerApi(api_client)

# NOTE: you need to specify the state_descriptor_id and worker_id UUIDs
state_descriptor_id = "3fa85f64-5717-4562-b3fc-2c963f66afa6"
worker_id = "3fa85f64-5717-4562-b3fc-2c963f66afa6"

values = hdm_api.read_last_values(abstract_descriptor_id=state_descriptor_id,
                                          factory_entity_id=worker_id,
                                          number_of_last_values=10)

import java.util.Collections;
import java.time.LocalDateTime;
import org.openapitools.client.ApiClient;
import org.openapitools.client.api.HdmApi;
import org.openapitools.client.model.GenericValueDto;
import org.springframework.data.domain.Page;

private void readStates() {
    // NOTE: you need to specify the HDM_ENDPOINT and HDM_API_KEY environment variables
    ApiClient apiClient = new ApiClient().setBasePath(System.getenv("HDM_ENDPOINT"));
    String apiKey = System.getenv("HDM_API_KEY");
    if (apiKey != null && !apiKey.isEmpty())
        apiClient.addDefaultHeader("x-api-key", apiKey);
    final HdmApi hdmApi = new HdmApi(apiClient);

    // NOTE: you need to specify the stateDescriptorId and workerId UUIDs
    stateDescriptorId = "3fa85f64-5717-4562-b3fc-2c963f66afa6";
    workerId = "3fa85f64-5717-4562-b3fc-2c963f66afa6";
    numberOfLastValues = 10;

    Page<GenericValueDto> values = hdmApi.readLastValues(stateDescriptorId, workerId, numberOfLastValues);
}

4.4 - Skills modelling

Model operators skills

The Orchestrator REST API enables to create and read all the Digital Twin entities described in Model section, in particular the characteristics (i.e. quasi-static data). CharacteristicDescriptor and CharacteristicValue are used in order to model operator skills (e.g., work experience, manual dexterity), besides the general features (e.g., sex, age, handedness).

This API is available through a dedicated Swagger interface for each Clawdite instance. Furthermore, it is possible to generate API clients for several languages, such as Python, Java and JavaScript. The mentioned clients are already generated and available within each Clawdite instance and make it possible to interact with Clawdite’s Orchestrator from external components.

In the following a few examples about skills modelling will be provided.

Install the Orchestrator client dependencies

In order to use the generated API clients inside external components it is needed to correctly setup and install the dependencies. Note that you need a personal GitLab token for accessing the registries. In case you don’t have it please contact the project’s maintainers.

• Language:
• Pip
• Maven

pip install orchestrator-python-client --index-url https://__token__:<your_personal_token>@gitlab-core.supsi.ch/api/v4/projects/86/packages/pypi/simple

<dependencies>
    <dependency>
      <groupId>ch.supsi.dti.isteps.hdt</groupId>
      <artifactId>orchestrator-java-client</artifactId>
      <version>0.2.3</version>
    </dependency>
</dependencies>

<repositories>
  <repository>
    <id>gitlab-maven</id>
    <url>https://gitlab-core.supsi.ch/api/v4/projects/86/packages/maven</url>
  </repository>
</repositories>

Create a Skill

In order to define a skill it is needed to create a CharacteristicDescriptor with an associated CharacteristicValue. Note that a CharacteristicDescriptor is uniquely linked to an already existing FactoryEntityModel. Moreover, the Worker (or FactoryEntity in general) which possesses the skill (i.e., CharacteristicValue) needs to be defined in advance.

• Language:
• Python
• Java

import os
from datetime import datetime
from collections import OrderedDict
import orchestrator_python_client as hdt_client
from orchestrator_python_client import ApiClient, FactoryEntityModelCategoryDto, FactoryEntityModelDto, WorkerDto, 
    CharacteristicDescriptorDto, CharacteristicValueDto, FieldType

# NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables

configuration = hdt_client.Configuration(host=os.getenv('HDT_ENDPOINT'))
configuration.api_key['apiKeyAuth'] = os.getenv('HDT_API_KEY')
api_client = hdt_client.ApiClient(configuration)

factory_entity_model_category_api = hdt_client.FactoryEntityModelCategoryApi(api_client)
factory_entity_model_api = hdt_client.FactoryEntityModelApi(api_client)
worker_api = hdt_client.WorkerApi(api_client)
characteristic_descriptor_api = hdt_client.CharacteristicDescriptorApi(api_client)
characteristic_value_api = hdt_client.CharacteristicValueApi(api_client)

operator_category = factory_entity_model_category_api.create_factory_entity_model_category(
                        FactoryEntityModelCategoryDto(name="Operator",
                            description="description")).payload

worker_model = factory_entity_model_api.create_factory_entity_model(
                        FactoryEntityModelDto(name="Worker",
                            description="description",
                            factory_entity_model_categories_id=[operator_category.id])).payload

worker = worker_api.create_worker(
                        WorkerDto(creation_date=datetime.now().isoformat(),
                            factory_entity_model_id=worker_model.id)).payload

# "Gender" characteristic creation
gender_descriptor = characteristic_descriptor_api.create_characteristic_descriptor(
                        CharacteristicDescriptorDto(name="Gender",
                            description="Operator gender",
                            factory_entity_model_id=worker_model.id)).payload

worker_gender = characteristic_value_api.create_characteristic_value(
                        CharacteristicValueDto(values=OrderedDict({datetime.now().isoformat(): "Male"}),
                            type=FieldType.STRING,
                            characteristic_descriptor_id=gender_descriptor.id,
                            factory_entity_id=worker.id)).payload

# "Manual dexterity" skill creation
manual_dexterity_descriptor = characteristic_descriptor_api.create_characteristic_descriptor(
                        CharacteristicDescriptorDto(name="Manual dexterity",
                            description="Operator manual dexterity",
                            factory_entity_model_id=worker_model.id)).payload

worker_manual_dexterity = characteristic_value_api.create_characteristic_value(
                        CharacteristicValueDto(values=OrderedDict({datetime.now().isoformat(): "41"}),
                            type=FieldType.NUMBER,
                            characteristic_descriptor_id=manual_dexterity_descriptor.id,
                            factory_entity_id=worker.id)).payload

import java.util.Collections;
import java.time.LocalDateTime;
import org.openapitools.client.ApiClient;
import org.openapitools.client.api.FactoryEntityModelCategoryApi;
import org.openapitools.client.api.FactoryEntityModelApi;
import org.openapitools.client.api.WorkerApi;
import org.openapitools.client.api.CharacteristicDescriptorApi;
import org.openapitools.client.api.CharacteristicValueApi;
import org.openapitools.client.model.FactoryEntityModelCategoryDto;
import org.openapitools.client.model.FactoryEntityModelDto;
import org.openapitools.client.model.WorkerDto;
import org.openapitools.client.model.CharacteristicDescriptorDto;
import org.openapitools.client.model.CharacteristicValueDto;
import org.openapitools.client.model.FieldType

private void createSkill() {
    // NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables
    ApiClient apiClient = new ApiClient().setBasePath(System.getenv("HDT_ENDPOINT"));
    String apiKey = System.getenv("HDT_API_KEY");
    if(apiKey != null && !apiKey.isEmpty())
        apiClient.addDefaultHeader("x-api-key", apiKey);

    final FactoryEntityModelCategoryApi factoryEntityModelCategoryApi = new FactoryEntityModelCategoryApi(apiClient);
    final FactoryEntityModelApi factoryEntityModelApi = new FactoryEntityModelApi(apiClient);
    final WorkerApi workerApi = new WorkerApi(apiClient);
    final CharacteristicDescriptorApi characteristicDescriptorApi = new CharacteristicDescriptorApi(apiClient);
    final CharacteristicValueApi characteristicValueApi = new CharacteristicValueApi(apiClient);

    FactoryEntityModelCategoryDto operatorCategory = factoryEntityModelCategoryApi.createFactoryEntityModelCategory(
            new FactoryEntityModelCategoryDto()
                    .setName("Operator")
                    .setDescription("description"));

    FactoryEntityModelDto workerModel = factoryEntityModelApi.createFactoryEntityModel(
            new FactoryEntityModelDto()
                    .setName("Worker")
                    .setDescription("description")
                    .setFactoryEntityModelCategoriesId(Collections.singletonList(operatorCategory.getId())));

    WorkerDto worker = workerApi.createWorker(
            new WorkerDto()
                    .setCreationDate(LocalDateTime.now().toString())
                    .setFactoryEntityModelId(workerModel.getId()));

    // "Gender" characteristic creation

    CharacteristicDescriptorDto genderDescriptor = characteristicDescriptorApi.createCharacteristicDescriptor(
            new CharacteristicDescriptorDto()
                    .setName("Gender")
                    .setDescription("Worker gender")
                    .setFactoryEntityModelId(workerModel.getId()));

    CharacteristicValueDto workerGender = characteristicValueApi.createCharacteristicValue(
            new CharacteristicValueDto()
                    .setValues(new TreeMap<>() {{
                        put(LocalDateTime.now().toString(), "Male");
                    }})
                    .setType(FieldType.STRING)
                    .setCharacteristicDescriptorId(genderDescriptor.getId())
                    .setFactoryEntityId(worker.getId()));

    // "Manual dexterity" skill creation

    CharacteristicDescriptorDto manualDexterityDescriptor = characteristicDescriptorApi.createCharacteristicDescriptor(
            new CharacteristicDescriptorDto()
                    .setName("Manual dexterity")
                    .setDescription("Worker anual dexterity")
                    .setFactoryEntityModelId(workerModel.getId()));

    CharacteristicValueDto workerManualDexterity = characteristicValueApi.createCharacteristicValue(
            new CharacteristicValueDto()
                    .setValues(new TreeMap<>() {{
                        put(LocalDateTime.now().toString(), "41");
                    }})
                    .setType(FieldType.NUMBER)
                    .setCharacteristicDescriptorId(manualDexterityDescriptor.getId())
                    .setFactoryEntityId(worker.getId()));

}