Setup

In the following section we describe how to setup and activate a Tributech Agent with an existing Tributech Node. We assume that all Requirements are met and a running Tributech Node is accessable. The goal is to create a basic setup with a Simulated Tributech Source that will generate random data and send it to the Tributech Agent via MQTT. The Tributech Agent will create proofs for the received values which can later be inspected in the Tributech Node.

⚠️ Requirements must be satisfied

⚠️ Tributech Node must be running and accessable

We will use Docker Engine and Docker Compose in our examples to show how to get an edge device up and running with all the required services.

General Process Overview

In this section we want to show how a Tributech Agent is setup up and can be used to securely transfer customer data from an edge device to the Tributech Node for inspection and verification. The Tributech Node is the common management point for all Tributech Agents connected to the Node. How a Tributech Agent operates and which Tributech Sources will be able to submit data is defined in Digital Twin Configuration of an Agent. This management of Agent is required after completing successfully the Agent Enrollment Process.

The communication between Tributech Sources and the Tributech Agent will take place on the same edge device via a local Message Broker connection. This channel is used on the one hand to send configurations and commands from Tribtech Agent to the Tributech Source and on the other hand to send data streams from the Tributech Source to the Agent.

Authentication Certificates (Enrollment)

Before starting a Tributech Agent we need to get a Certificate signed by the Tributech Node that is used during the initial authentication process to indicate that a Tribtech Agent is allowed to establish a MQTTS connection to the Tributech Node. The certificate handling and initial establishing of a connection to the Tributech Node is called Enrollment and more information can be found in agent management.

In order to create the certificate we visit the Enrollment section in the Tributech Node UI and select + Add Enrollment.

This action leads to the following window, which contains all the information the user needs to create the certificate.

Download the script for the operating system of your choice Linux/Windows and execute the script in a empty folder named enrollment. Its important to note that the operating system does not need to be identical to the Edge Device operating system. These Certificate Signing Request and certificates can be created once and reused for multiple Tributech Agents. After successful execution of the script upload the enrollment.csr in the Tributech Node UI Upload Dialog and submit it by clicking GENERATE CERTIFICATE. A enrollment.crt file is returned after the successful generation and should be saved in the same folder next to the script. If problems or questions occur during this process please consult the README for more details.

With the certificates present in a local folder, we call enrollment, we can now provide the certificates in two different ways to the Tributech Agent either via environment variables or via docker volumes which we will show later in detail during the Tributech Agent startup.

⚠️ enrollment.key file in the referenced folder must contain the enrollment key in the format:

-----BEGIN PRIVATE KEY-----
MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQDB910tiUPf3jp3
...
JoTeVZlyPgWSr6ckDiYrXZCINfeupxIpUNa2dOTssJ7frddsOc65TjYaEGtQFhN9
UuhRTNXXB3LPeUekmFqAFw==
-----END PRIVATE KEY-----

⚠️ enrollment.crt file in the referenced folder must contain the enrollment certificate in the format:

-----BEGIN CERTIFICATE-----
MIIEhDCCAmygAwIBAgIVAMJHgTEKo6BAjM2x17MzqEoBAAAAMA0GCSqGSIb3DQEB
...
rTGtd7jookqEziPG7j9oN6Q4jQZI/fGeTDpz5JvEPriFWg4niwdZZVTVi4Axk0wT
Xb7SLA93BKc=
-----END CERTIFICATE-----

Docker volumes

Docker Volumes are the preferred mechanism for persisting data generated by and used by Docker containers. To make local certificates folders available to a docker container we need to add the mount to our tributech-agent service. The folder for the certificates can be adjusted as needed (./enrollment) only the :/app/enrollment needs to stay the same.

docker-compose.yml section

services:
  tributech-agent:
    image: ${DOCKER_REGISTRY-tributech.azurecr.io/}tributech-agent:${AGENT_TAG:-latest}
    depends_on:
      - mosquitto-server
    environment:
      - MqttOptions__MQTTHost=mosquitto-server
      - EdgeDeviceOptions__AgentID=${AGENT_ID:?"The Tributech Agent requires a GUID"}
      - EdgeDeviceOptions__NodeUrl=${NODE_URL:?"The Tributech Node Url is required"}
    volumes:
      - ./bin/data:/app/data #default directory for keys and datatwin file
      - ./enrollment:/app/enrollment # local enrollment folder mounted to /app/enrollment
    restart: unless-stopped

  mosquitto-server:
    image: eclipse-mosquitto:${MQTT_TAG:-1.6}
    restart: unless-stopped

Environment Variables

The second way to add enrollment certificates to a Tributech Agent is to use environment variables. The content of the certificate files needs to be converterted into a base64 encoded string without whitespaces, i.e. detailed information on how to convert a file into a base64 representation can be found here for Windows and Unix. We then add the base64 encoded content of the enrollment.crt (Certificate) as EnrollmentOptions__EnrollmentCertBase64 value and the EnrollmentOptions__EnrollmentKeyBase64 contains base64 encoded enrollment.key content.

docker-compose.yml section

services:
  tributech-agent:
    image: ${DOCKER_REGISTRY-tributech.azurecr.io/}tributech-agent:${AGENT_TAG:-latest}
    depends_on:
      - mosquitto-server
    environment:
      - MqttOptions__MQTTHost=mosquitto-server
      - EdgeDeviceOptions__AgentID=${AGENT_ID:?"The Tributech Agent requires a GUID"}
      - EdgeDeviceOptions__NodeUrl=${NODE_URL:?"The Tributech Node Url is required"}
      - EnrollmentOptions__EnrollmentCertBase64=LS0tLS1CR...VEUgS0VZLS0tLS5X
      - EnrollmentOptions__EnrollmentKeyBase64=LS0tLS1CRU...VEUgS0VZLS0tLS0K
    volumes:
      - ./bin/data:/app/data #default directory for keys and datatwin file
    restart: unless-stopped

  mosquitto-server:
    image: eclipse-mosquitto:${MQTT_TAG:-1.6}
    restart: unless-stopped

Starting a Tributech Agent

After we have prepared the Tributech Agent certificates for the enrollment we can now startup whole environment. In our example, we will use the certificate reference via environment variables. If docker volumes are preferred the tributech-agent-simulated docker-compose.yml file in the following examples must be adapted as described in the previous section.

⚠️ In our examples for the setup documentation, we will use different container images and configurations compared to the Quickstart. Please use a new empty folder for the files to prevent any configuration mix.

We have a docker-compose.yml prepared for an quick and easy setup containing a MQTT Message Broker, a Tributech Agent and a Tributech Simulated Source. Note that the local MQTT Message Broker is required for the communication between the Tributech Agent and a Tributech Simulated Source on the Edge Device and will not be used for interactions with the Tributech Node.

docker-compose.yml

version: "3.6"

services:
  source-simulated:
    image: ${DOCKER_REGISTRY-tributech.azurecr.io/}tributech-source-simulated:${SOURCE_TAG:-latest}
    depends_on:
      - mosquitto-server-simulated
      - tributech-agent
    environment:
      - MqttOptions__MQTTHost=mosquitto-server-simulated
      - Logging__LogLevel__Default=Debug
    networks:
      - simulated-net
    restart: unless-stopped
    logging:
      driver: "json-file"
      options:
        max-size: "2m"
        max-file: "5"

  tributech-agent:
    image: ${DOCKER_REGISTRY-tributech.azurecr.io/}tributech-agent:${AGENT_TAG:-latest}
    depends_on:
      - mosquitto-server-simulated
    environment:
      - Logging__LogLevel__Default=Debug
      - Logging__Console__FormatterName=simple
      - MqttOptions__MQTTHost=mosquitto-server-simulated
      - EdgeDeviceOptions__AgentID=${AGENT_ID:?"The Tributech Agent requires a GUID"}
      - EdgeDeviceOptions__NodeUrl=${NODE_URL:?"The Tributech Node Url is required"}
      - EnrollmentOptions__EnrollmentCertBase64=${ENROLLMENT_CERT_BASE64:?"The base64 encoded Enrollment Cert is required"}
      - EnrollmentOptions__EnrollmentKeyBase64=${ENROLLMENT_KEY_BASE64:?"The base64 encoded Enrollment Key is required"}
    # ports:
    #   - "5000:8080"
    networks:
      - simulated-net
    volumes:
      - ./volumes/simulated/agent/:/app/data # volume mapping for permanent storage of keys and datatwin file
    restart: unless-stopped
    logging:
      driver: "json-file"
      options:
        max-size: "2m"
        max-file: "5"

  mosquitto-server-simulated:
    image: eclipse-mosquitto:${MQTT_TAG:-1.6}
    networks:
      - simulated-net
    # ports:
    # - '1883:1883' # MQTT
    # - "127.0.0.1:9001:9001" # web-socket
    restart: unless-stopped

networks:
  simulated-net:

Docker Compose provides a ready-made setup, but some settings must be adapted to the environment in which it is executed:

• EdgeDeviceOptions__AgentID is a GUID that can be freely chosen but must be unique for each agent connecting to the same Tributech Node
• EdgeDeviceOptions__NodeUrl is the absolute URL to the Tributech Node the agent should connect to
• EnrollmentOptions__EnrollmentCertBase64 and EnrollmentOptions__EnrollmentKeyBase64 are base64 encoded certifcates required to authenticate with a Tributech Node (see Agent Management)

Sample values:

env specific settings

tributech-agent:
    ...
    environment:
      ...
      - EdgeDeviceOptions__AgentID=00000000-0000-0000-0000-000000000007
      - EdgeDeviceOptions__NodeUrl=https://my-environment.tributech-node.com
      - EnrollmentOptions__EnrollmentCertBase64=LS0tLS1C...ZDdqb29rcUV
      - EnrollmentOptions__EnrollmentKeyBase64=AKS0tLS1C...ZDdqb29rcDE

We can now Startup the environment by running the following command (or docker-compose for older versions):

terminal

docker compose up -d

Validate that all containers are running. The output should return that every container is in the state Up

terminal

docker compose ps

If you encounter problems with starting the containers please consult the official docker documentation and revisit the requirements.

If all container are up and running we can inspect the Tributech Agent and check if its in the expect state by checking the logs for a recurring message Enrollment is not finished yet and needs to be confirmed by a user on the Node.

terminal

docker compose logs -f tributech-agent-simulated

This message means that we now have a running Tributech Agent which requires permission from the Tributech Node to establish a connection. Our current setup is started with the default values for the Tributech Agent and Tributech Source and requires to be configured in the Tributech Node in order to send sample data.

Activate Agent

After the docker containers have been startet successfully the Agent will connect to the specified environment automatically. The user has to check if the Agent is present in the enrollment section. To access the enrollment the user just has to click on Enrollment in the left management panel of the Tributech UI.

The Agent with our specific Agent ID should be in ne of the top most entries of the list and should be in the Pending state. If to many agents are listed we can search for the Agent with the AGENT_ID we defined docker compose file (value for EdgeDeviceOptions__AgentID in our example 00000000-0000-0000-0000-000000000007). By clicking on the Activate button we grant our agent the permission to connect and be management by this Tributech Node. For more information on agent management in the Tributech Node visit agent management.

After the successfully activating the agent state will switch from Pending to Online which indicates that the Tributech Agent is now ready to be configuration. In the current state the Tributech Agent has a connection to the Tributech Node established but does not have any configuration. This means he does not know of any Tributech Sources on the same Edge Device.

To complete the configuration of a Tribtech Agent visit the configuration section.