• 1: Getting started
• 1.1: Install Eclipse Kanto
• 1.2: Explore via Eclipse Hono
• 2: Concepts
• 2.1: AWS Connector
• 2.2: Suite connector
• 2.3: Container management
• 2.4: Software update
• 2.5: File upload
• 3: How-to guides
• 3.1: Update software
• 3.2: Upload files
• 3.3: Back up and restore files
• 3.4: Monitor system metrics
• 3.5: Bootstrap device
• 3.6: Offline explore edge device
• 4: References
• 4.1: Remote connectivity configuration
• 4.1.1: AWS Connector configuration
• 4.1.2: Suite connector configuration
• 4.1.3: Suite bootstrapping configuration
• 4.2: Local digital twins configuration
• 4.3: Container management configuration
• 4.3.1: Container configuration
• 4.3.2: Manager configuration
• 4.4: Software update configuration
• 4.5: File upload configuration
• 4.6: File backup configuration
• 4.7: System metrics configuration

1 - Getting started

1.1 - Install Eclipse Kanto

Before you begin

The containerd Debian package is required. You can install it manually or run:

curl -fsSL https://github.com/eclipse-kanto/kanto/raw/main/quickstart/install_ctrd.sh | sh

Install Eclipse Kanto

Choose the Eclipse Kanto Debian package for your target device architecture from the ones available at the project’s GitHub Releases page. Download and install it via executing the following (adjusted to your package name):

wget https://github.com/eclipse-kanto/kanto/releases/download/v0.1.0-M3/kanto_0.1.0-M3_linux_x86_64.deb && \
sudo apt install ./kanto_0.1.0-M3_linux_x86_64.deb

Verify

It’s important to check if all the services provided by the Eclipse Kanto package are up and running successfully. You can quickly do that via executing:

systemctl status \
suite-connector.service \
container-management.service \
software-update.service \
file-upload.service \
file-backup.service \
system-metrics.service

All listed services must be in an active running state.

What’s next

Explore via Eclipse Hono

1.2 - Explore via Eclipse Hono

By following the steps below you will connect your first device to a publicly available Eclipse Hono sandbox using Eclipse Kanto. A couple of simple Eclipse Hono northbound business applications written in Python are provided to explore the capabilities for remotely managing and monitoring your edge device.

Before you begin

The location where the Python applications and utility shell scripts will run does not have to be your edge device as they communicate remotely with Eclipse Hono only. To run them, you need:

• Python 3 and pip3

• The quickstart applications and provisioning scripts

  You can execute the script below to download them automatically:

  mkdir quickstart && cd quickstart && \
  wget https://github.com/eclipse-kanto/kanto/raw/main/quickstart/hono_commands.py && \
  wget https://github.com/eclipse-kanto/kanto/raw/main/quickstart/hono_events.py && \
  wget https://github.com/eclipse-kanto/kanto/raw/main/quickstart/requirements.txt && \
  wget https://github.com/eclipse-kanto/kanto/raw/main/quickstart/hono_provisioning.sh
  

• OpenSSL and the following SSL and SASL related libraries: pkg-config, swig, libsasl2-dev, libsasl2-2 libsasl2-modules-gssapi-mit and libssl-dev, e.g.:

  sudo apt install openssl pkg-config swig libsasl2-dev libsasl2-2 libsasl2-modules-gssapi-mit libssl-dev
  

• Required Python dependencies to run the scripts

  You can install them by using the downloaded requirements.txt file via executing:

  pip3 install -r requirements.txt
  

Provision the Eclipse Hono tenant and device

In order to be able to connect your device to Eclipse Hono, you need to have a dedicated tenant and a device instance provisioned for it. Fill in the required empty environmental variables definitions in the hono_provisioning.sh, e.g.:

# The Hono tenant to be created
export TENANT=demo
# The identifier of the device on the tenant
# Note! It's important for the ID to follow the convention namespace:name (e.g. demo:device)
export DEVICE_ID=demo:device
# The authentication identifier of the device
export AUTH_ID=demo_device
# A password for the device to authenticate with
export PWD=secret

Run the provisioning script and you will have your Eclipse Hono tenant and device ready to be connected:

./hono_provisioning.sh

Configure Eclipse Kanto

Eclipse Kanto uses the /etc/suite-connector/config.json to acquire all the remote communication, identification and authentication data to establish the remote connection. Update it with the following:

{
  "provisioningFile": "/etc/suite-connector/provisioning.json",
  "logFile": "/var/log/suite-connector/suite-connector.log",
  "address":"mqtts://hono.eclipseprojects.io:8883",
  "tenantId":"demo",
  "deviceId":"demo:device",
  "authId":"demo_device",
  "password":"secret"
}

Restart the Suite Connector service for the changes to take effect:

sudo systemctl restart suite-connector.service

Verify

To explore remote containerized applications management, we will use the two Python scripts to run, monitor and remove a simple InfluxDB container using its public container image available at Docker Hub.

First, start the monitoring application that requires the configured Eclipse Hono tenant (-t) and will print all received events triggered by the device:

python3 hono_events.py -t demo

In another terminal, we are ready to spin up an InfluxDB container instance at the edge via executing the second application that requires the command to execute (run), the Eclipse Hono tenant (-t), device identifier (-d) and the full container image reference to use (--img):

python3 hono_commands.py run -t demo -d demo:device --img docker.io/library/influxdb:1.8.4

After the script exits with success, you can check out the new container running on your edge device via executing:

sudo kanto-cm list

Looking at the terminal where the monitoring application is running, you will be able to see all the events triggered by the operation.

To remove the newly created container, execute the same application script only this time with the rm command and the identifier of the container to remove (--id), e.g.:

python3 hono_commands.py rm -t demo -d demo:device --id e6f7fbea-0e95-433c-acc7-16ef21b9c033

2 - Concepts

2.1 - AWS Connector

AWS Connector enables the remote connectivity to an AWS IoT cloud ecosystem. It provides the following use cases:

• Enriched remote connection
  • Optimized - to pass the messages via a single underlying connection
  • Secured - to protect the edge identity and data via TLS with basic and certificate-based authentication
  • Maintained - with a reconnect exponential backoff algorithm
  • Synchronized - on a connectivity recovering via a message buffering
• Application protection - AWS Connector is the only one component with a remote connectivity i.e. all local applications are protected from exposure to the public network
• Offline mode - local applications don’t need to care about the status of the remote connection, they can stay fully operable in offline mode
• Device Shadow - messages sent to the Twin Channel are converted to messages more suitable for AWS Device Shadow service and sent to it.

How it works

The AWS Connector plays a key role in two communication aspects - local and remote.

Cloud connectivity

To initiate its connection, the edge has to be manually or automatically provisioned. The result of this operation is different parameters and identifiers. Currently, AWS Connector supports MQTT transport as a connection-oriented and requiring less resources in comparison to AMQP. Once established, the connection is used as a channel to pass the edge telemetry and event messages. The IoT cloud can control the edge via commands and responses.

In case of a connection interruption, the AWS Connector will switch to offline mode. The message buffer mechanism will be activated to ensure that there is no data loss. Reconnect exponential backoff algorithm will be started to guarantee that no excessive load will be generated to the IoT cloud. All local applications are not affected and can continue to operate as normal. Once the remote connection is restored, all buffered messages will be sent and the edge will be fully restored to online mode.

Local communication

Ensuring that local applications are loosely coupled, Eclipse Hono™ MQTT definitions are in use. The event-driven local messages exchange is done via a MQTT message broker - Eclipse Mosquitto™. The AWS Connector takes the responsibility to forward these messages to the IoT cloud and vice versa.

Monitoring of the remote connection status is also enabled locally as well, along with details like the last known state of the connection, timestamp and a predefined connect/disconnect reason.

2.2 - Suite connector

Suite connector enables the remote connectivity to an IoT cloud ecosystem of choice, powered by Eclipse Hono™ (e.g. Eclipse Cloud2Edge and Bosch IoT Suite). It provides the following use cases:

• Enriched remote connection
  • Optimized - to pass the messages via a single underlying connection
  • Secured - to protect the edge identity and data via TLS with basic and certificate-based authentication
  • Maintained - with a reconnect exponential backoff algorithm
  • Synchronized - on a connectivity recovering via a message buffering
• Application protection - suite connector is the only one component with a remote connectivity i.e. all local applications are protected from exposure to the public network
• Offline mode - local applications don’t need to care about the status of the remote connection, they can stay fully operable in offline mode

How it works

The suite connector plays a key role in two communication aspects - local and remote.

Cloud connectivity

To initiate its connection, the edge has to be manually or automatically provisioned. The result of this operation is different parameters and identifiers. Currently, suite connector supports MQTT transport as a connection-oriented and requiring less resources in comparison to AMQP. Once established, the connection is used as a channel to pass the edge telemetry and event messages. The IoT cloud can control the edge via commands and responses.

In case of a connection interruption, the suite connector will switch to offline mode. The message buffer mechanism will be activated to ensure that there is no data loss. Reconnect exponential backoff algorithm will be started to guarantee that no excessive load will be generated to the IoT cloud. All local applications are not affected and can continue to operate as normal. Once the remote connection is restored, all buffered messages will be sent and the edge will be fully restored to online mode.

Local communication

Ensuring that local applications are loosely coupled, Eclipse Hono™ MQTT definitions are in use. The event-driven local messages exchange is done via a MQTT message broker - Eclipse Mosquitto™. The suite connector takes the responsibility to forward these messages to the IoT cloud and vice versa.

The provisioning information used to establish the remote communication is available locally both on request via a predefined message and on update populated via an announcement. Applications that would like to extend the edge functionality can further use it in Eclipse Hono™ and Eclipse Ditto™ definitions.

Monitoring of the remote connection status is also enabled locally as well, along with details like the last known state of the connection, timestamp and a predefined connect/disconnect reason.

2.3 - Container management

Container management enables a lightweight standard runtime which is capable to run containerized applications with all advantages of the technology: isolation, portability and efficiency. The deployment and management are available both locally and remotely via an IoT cloud ecosystem of choice. The following use cases are provided:

• Standardized approach - with OCI (Open Container Initiative) compliant container images and runtime
• Lightweight runtime - with a default integration of containerd and a possibility for another container technology of choice like podman, LXC and more
• Isolation - with a default isolation from other containerized applications and the host system
• Portability - with an option to run one and the same containerized application on different platforms
• Pluggable architecture - with extension points on different levels

How it works

A container image packs the application executable along with all its needed dependencies into a single artifact that can be built by a tooling of choice. The built image is made available for usage by being pushed to a container image registry where the runtime can refer it to.

To create a new container instance, the container management uses such an image reference and a configuration for it to produce a fully functional container. The container lifecycle (start, update, stop, remove) and environment (memory constraints, restart policy, etc.) are also handled by the runtime. The container management continuously ensures the applications availability via state awareness and restart policies, provides monitoring via flexible logging and fine-grained resources management. All of that is achieved on top of an underlying runtime of choice (containerd by default) that takes care of the low-level isolation mechanisms.

2.4 - Software update

Software update enables the deployment and management of various software artifacts, both locally and remotely via an IoT cloud ecosystem of choice. It provides the following use cases:

• Robust download - with a retry and resume mechanism when the network connection is interrupted
• Artifact validation - with an integrity validation of every downloaded artifact
• Universal installation - with customizable install scripts to handle any kind of software
• Operation monitoring - with a status reporting of the download and install operations

How it works

When the install operation is received at the edge, the download process is initiated. Retrieving the artifacts will continue until they are stored at the edge or their size threshold is reached. If successful, the artifacts are validated for integrity and further processed by the configured script. It is responsible to apply the new software and finish the operation. A status report is announced on each step of the process enabling its transparent monitoring.

On start up, if there have been any ongoing operations, they will be automatically resumed as the operation state is persistently stored.

What’s next

How to update software

2.5 - File upload

File upload enables sending of files to a backend storage of choice. It can be used both locally and remotely via a desired IoT cloud ecosystem. The following use cases are provided:

• Storage diversity - with ready to use integrations with Azure Blob Storage, Amazon S3 and standard HTTP upload
• Automatic uploads - with periodically triggered uploads at a specified interval in a given time frame
• Data integrity - with an option to calculate and send the integrity check required information
• Operation monitoring - with a status reporting of the upload operation

How it works

It’s not always possible to inline all the data into exchanged messages. For example, large log files or large diagnostic files cannot be sent as a telemetry message. In such scenarios, file upload can assist enabling massive amount of data to be stored to the backend storage.

There are different triggers which can initiate the upload operation: periodic or explicit. Once initiated, the request will be sent to the IoT cloud for confirmation or cancellation transferred back to the edge. If starting is confirmed, the files to upload will be selected according to the specified configuration, their integrity check information can be calculated and the transfer of the binary content will begin. A status report is announced on each step of the upload process enabling its transparent monitoring.

What’s next

How to upload files

3 - How-to guides

3.1 - Update software

By following the steps below you will install ahello Debian package via a publicly available Eclipse Hono sandbox using Eclipse Kanto. A couple of simple Eclipse Hono northbound business applications written in Python are provided to explore the capabilities for remotely installing and monitoring. On the edge side, a basic install_hello.sh script will be downloaded and executed.

Before you begin

To ensure that your edge device is capable to execute the steps in this guide, you need:

• Debian-based linux distribution and the apt command line tool

• If you don’t have an installed and running Eclipse Kanto, follow Install Eclipse Kanto

• If you don’t have a connected Eclipse Kanto to Eclipse Hono sandbox, follow Explore via Eclipse Hono

• The software update application

  Navigate to the quickstart folder where the resources from the Explore via Eclipse Hono guide are located and execute the following script:

  wget https://github.com/eclipse-kanto/kanto/raw/main/quickstart/hono_commands_su.py
  

• Executing hello in the terminal will return that the command is not found

Install Debian package

To explore the software management, we will use two Python scripts to install and monitor the hello Debian package. The location where the Python applications will run does not have to be your edge device as they communicate remotely with Eclipse Hono only.

First, start the monitoring application that requires the configured Eclipse Hono tenant (-t) and will print all received events triggered by the device:

python3 hono_events.py -t demo

In another terminal, we are ready to spin up a hello Debian package at the edge via executing the second application that requires the Eclipse Hono tenant (-t) and the device identifier (-d):

python3 hono_commands_su.py -t demo -d demo:device

Verify

You can check out that the new package is installed on your edge device via executing:

hello

The command now displays: Hello, world!

Clean up

The installed hello Debian package can be removed via executing:

sudo apt remove hello

3.2 - Upload files

By following the steps below you will upload an example log file to your HTTP file server via a publicly available Eclipse Hono sandbox using Eclipse Kanto. A simple Eclipse Hono northbound business application written in Python is provided to explore the capabilities for remotely uploading and monitoring.

Before you begin

To ensure that all steps in this guide can be executed, you need:

• servefile installed

  This is a small Python HTTP server used in the example to serve the uploads. It does not have to be running on your edge device but it has to be accessible from there. You can install it by executing:

  pip3 install servefile
  

• If you don’t have an installed and running Eclipse Kanto on your edge device, follow Install Eclipse Kanto

• If you don’t have a connected Eclipse Kanto to Eclipse Hono sandbox, follow Explore via Eclipse Hono

• The file upload application

  Navigate to the quickstart folder where the resources from the Explore via Eclipse Hono guide are located and execute the following script:

  wget https://github.com/eclipse-kanto/kanto/raw/main/quickstart/hono_commands_fu.py
  

Upload log file

By default, all files in /var/tmp/file-upload/ directory can be uploaded. For example, grab the suite connector log file and place it in the directory via executing:

mkdir -p /var/tmp/file-upload/ && sudo cp /var/log/suite-connector/suite-connector.log /var/tmp/file-upload/

Choose a directory where the log file will be uploaded, open a new terminal there and run servefile:

servefile -u .

To explore the file upload, we will use a Python script to request and monitor the operation. The location where the Python application will run does not have to be your edge device as it communicates remotely with Eclipse Hono only.

Now we are ready to request the log file upload from the edge via executing the application that requires the Eclipse Hono tenant (-t) and the device identifier (-d):

python3 hono_commands_fu.py -t demo -d demo:device

Verify

You can check out that the log file is on your HTTP file server by listing the content of servefile working directory.

Clean up

Stop servefile and clean up its working directory.

3.3 - Back up and restore files

By following the steps below you will back up a simple text file to an HTTP file server and then restore it back via a publicly available Eclipse Hono sandbox using Eclipse Kanto. A simple Eclipse Hono northbound business application written in Python is provided to explore the capabilities for remotely backing up and restoring files.

Before you begin

To ensure that all steps in this guide can be executed, you need:

• servefile installed

  This is a small Python HTTP server used in the example to serve the uploads and downloads. It does not have to be running on your edge device, but it has to be accessible from there. You can install it by executing:

  pip3 install servefile
  

• If you don’t have an installed and running Eclipse Kanto on your edge device, follow Install Eclipse Kanto

• If you don’t have a connected Eclipse Kanto to Eclipse Hono sandbox, follow Explore via Eclipse Hono

• The file backup and restore application

  Navigate to the quickstart folder where the resources from the Explore via Eclipse Hono guide are located and execute the following script:

  wget https://github.com/eclipse-kanto/kanto/raw/main/quickstart/hono_commands_fb.py
  

Back up

By default, all directories in /var/tmp/file-backup/ or the directory itself can be backed up. For this example, create a file data.txt which will be later backed up:

sudo mkdir -p /var/tmp/file-backup && sudo echo "This is the first line in the file!" >> /var/tmp/file-backup/data.txt

You can verify that the file was successfully created by executing the following command:

cat /var/tmp/file-backup/data.txt

This should produce This is the first line in the file! as an output.

Choose a directory where the text file will be uploaded, open a new terminal there and run servefile with the flag -u to enable a file upload:

servefile -u .

To explore the file backup, we will use a Python script to request and monitor the operation. The location where the Python application will run does not have to be your edge device as it communicates remotely with Eclipse Hono only.

Now we are ready to request the text file backup from the edge via executing the application that requires the command to execute (backup), Eclipse Hono tenant (-t), the device identifier (-d) and the host where the backup will be uploaded to:

python3 hono_commands_fb.py backup -t demo -d demo:device -h localhost

You can check out that the backup file data.zip is on your HTTP file server by listing the content of the servefile working directory.

Restore

To explore the restore capabilities you will first modify the data.txt file, and then you will restore it to the version before the changes by using the backup, that was created earlier.

You can modify the data.txt file with the following command:

sudo echo "This is the second line in the file!" >> /var/tmp/file-backup/data.txt

You can verify that the file was successfully updated by executing the following command:

cat /var/tmp/file-backup/data.txt

This output should be:

This is the first line in the file!
This is the second line in the file!

Navigate to the terminal where servefile was started and terminate it. Start it again with the flag -l to enable a file download:

servefile -l .

To explore the file restore, we will use a Python script to request and monitor the operation. The location where the Python application will run does not have to be your edge device as it communicates remotely with Eclipse Hono only.

Now we are ready to request the text file restore from the edge via executing the application that requires the command to execute (restore), Eclipse Hono tenant (-t), the device identifier (-d) and the host where the backup file will be downloaded from:

python3 hono_commands_fb.py restore -t demo -d demo:device -h localhost

Verify

You can check out that the original file is restored by executing the following command:

cat /var/tmp/file-backup/data.txt

This should produce This is the first line in the file! as an output.

Clean up

Stop servefile and clean up its working directory. Remove the data.txt file from the /var/tmp/file-backup directory.

3.4 - Monitor system metrics

By following the steps below you will be able to monitor the system metrics from your edge device via a publicly available Eclipse Hono sandbox using Eclipse Kanto. A simple Eclipse Hono northbound business application written in Python is provided to explore the capabilities for remotely monitoring the CPU and memory utilization.

Before you begin

To ensure that all steps in this guide can be executed, you need:

• Plotly and Dash installed

  Plotly is an open-source plotting library and Dash is a framework for building data application in Python. They are used in this example to run a simple HTTP server and visualize the incoming system metrics data in real time, and they do not have to be running on your edge device. You can install them by executing:

  pip3 install plotly dash
  

• If you don’t have an installed and running Eclipse Kanto on your edge device, follow Install Eclipse Kanto

• If you don’t have a connected Eclipse Kanto to Eclipse Hono sandbox, follow Explore via Eclipse Hono

• The system metrics application

  Navigate to the quickstart folder where the resources from the Explore via Eclipse Hono guide are located and execute the following script:

  wget https://github.com/eclipse-kanto/kanto/raw/main/quickstart/hono_commands_sm.py
  

Monitor system metrics

To explore the system metrics, we will use a Python script to request and monitor the CPU and memory utilization. The location where the Python application will run does not have to be your edge device as it communicates remotely with Eclipse Hono only.

Now we are ready to request the system metrics from the edge via executing the application that requires the Eclipse Hono tenant (-t) and the device identifier (-d):

python3 hono_commands_sm.py -t demo -d demo:device

Verify

You can check out that the CPU and memory utilization metrics are properly received and displayed by checking out the application dashboard (by default - http://127.0.0.1:8050).

3.5 - Bootstrap device

By following the steps below you will automatically provision a new device via a publicly available Eclipse Hono sandbox using Eclipse Kanto. A simple Eclipse Hono northbound business application written in Python is provided to explore the capabilities for device bootstrapping and automatically provision a new device.

First a bootstrapping request is sent from the edge. The custom Python application handles the request by automatically provisioning a new device. Upon successful automatically provisioning it sends back all mandatory remote communication, identification and authentication data. On the edge side, the response is handled by updating the connection configuration with the received data and by executing a basic post_bootstrap.sh script to restart the Suite Connector service for the changes to take effect.

Before you begin

To ensure that your edge device is capable to execute the steps in this guide, you need:

• If you don’t have an installed and running Eclipse Kanto, follow Install Eclipse Kanto

• If you don’t have a connected Eclipse Kanto to Eclipse Hono sandbox, follow Explore via Eclipse Hono

• The suite bootstrapping application and post bootstrap script

  Navigate to the quickstart folder where the resources from the Explore via Eclipse Hono guide are located and execute the following script:

  wget https://github.com/eclipse-kanto/kanto/raw/main/quickstart/hono_commands_sb.py && \
  wget https://github.com/eclipse-kanto/kanto/raw/main/quickstart/post_bootstrap.sh
  

• Grab the post script file and place it in the /var/tmp/suite-bootstrapping directory via executing:

  sudo mkdir -p /var/tmp/suite-bootstrapping/ && sudo cp ./post_bootstrap.sh /var/tmp/suite-bootstrapping/
  

• Back up /etc/suite-connector/config.json as this file will be modified from this guide

• Stop suite-connector.service. Suite bootstrapping automatically provision device and try to start the suite connector service with new device

  sudo systemctl stop suite-connector.service
  

Configure Suite Bootstrapping

Open file /etc/suite-connector/config.json, copy address, tenantId, deviceId, authId and password.

{
    ...
    "address": "mqtts://hono.eclipseprojects.io:8883",
    "tenantId": "demo",
    "deviceId": "demo:device",
    "authId": "demo_device",
    "password": "secret"
    ...
}

Bootstrapping uses the /etc/suite-bootstrapping/config.json to acquire all the remote communication, identification and authentication data to establish the remote connection for bootstrapping. It is also where you need to specify the path to the post bootstrapping script and where to store received response data. Update the configuration as shown below and replace tenantId, deviceId, authId and password with the settings that you copied in the previous step.

{
  "logFile": "/var/log/suite-bootstrapping/suite-bootstrapping.log",
  "postBootstrapFile": "/etc/suite-connector/config.json",
  "postBootstrapScript": ["/var/tmp/suite-bootstrapping/post_bootstrap.sh"],
  "caCert": "/etc/suite-bootstrapping/iothub.crt",
  "address": "mqtts://hono.eclipseprojects.io:8883",
  "tenantId": "demo",
  "deviceId": "demo:device",
  "authId": "demo_device",
  "password": "secret"
}

Restart the suite bootstrapping service for the changes to take effect:

sudo systemctl restart suite-bootstrapping.service

When configured correctly the Suite Bootstrapping service automatically sends the bootstrapping request.

Automatically provision via bootstrapping

To explore the suite bootstrapping, we will use a Python script to automatically provision and monitor the new device. The location where the Python application will run does not have to be your edge device as it communicates remotely with Eclipse Hono only.

Now we are ready to handle the bootstrapping request via executing the application that requires the Eclipse Hono tenant (-t), the device identifier (-d) and the password (-p) you wish to use for the new device:

python3 hono_commands_sb.py -t demo -d demo:device -p secret

Verify

The last event received for the application is with the new tenant id that is automatically provisioning for the Suite Connector. You can check out that the Suite Connector is now connected to the new device via its status.

sudo systemctl status suite-connector.service

Clean up

Revert previous back up /etc/suite-connector/config.json file. Remove temporary directory for post bootstrap file /var/tmp/suite-bootstrapping via executing:

sudo rm -r -f /var/tmp/suite-bootstrapping/

Stop suite bootstrapping service and restart suite connector service by executing:

sudo systemctl stop suite-bootstrapping.service && \
sudo systemctl restart suite-connector.service

3.6 - Offline explore edge device

By following the steps below, you will get the structure of the edge digital twins with all its features and properties using Eclipse Kanto. A simple Eclipse Hono northbound business application written in Python is provided to display the things’ and their features’ structure.

Before you begin

To ensure that your edge device is capable to execute the steps in this guide, you need:

• If you don’t have an installed and running Eclipse Kanto on your edge device, follow Install Eclipse Kanto

• If you don’t have a connected Eclipse Kanto to Eclipse Hono sandbox, follow Explore via Eclipse Hono

• Stop suite-connector.service. The local digital twins service is a replacement for the suite connector service, that is why either one of the services must be running.

  sudo systemctl stop suite-connector.service
  

• The offline explore application

  Navigate to the quickstart folder where the resources from the Explore via Eclipse Hono guide are located and execute the following script:

  wget https://github.com/eclipse-kanto/kanto/raw/main/quickstart/hono_commands_ldt.py
  

Configure Local digital twins

Open file /etc/suite-connector/config.json, copy tenantId, deviceId, authId and password.

{
    ...
    "tenantId": "demo",
    "deviceId": "demo:device",
    "authId": "demo_device",
    "password": "secret"
    ...
}

The local digital twins service uses the /etc/local-digital-twins/config.json to acquire all the remote communication, identification and authentication data to establish the remote connection. Update the configuration as shown below and replace tenantId, deviceId, authId and password with the settings that you copied in the previous step.

  {
    "logFile": "/var/log/local-digital-twins/local-digital-twins.log",
    "caCert": "/etc/local-digital-twins/iothub.crt",
    "thingsDb": "/var/lib/local-digital-twins/thing.db",
    "tenantId": "demo",
    "deviceId": "demo:device",
    "authId": "demo_device",
    "password": "secret"
  }

Save the configuration and start the local digital twins service using the following command:

sudo systemctl start local-digital-twins.service

Receive the structure of the edge device

Now we are ready to request the structure of the edge digital twins via executing the offline explore application that requires the local digital twins tenant (-t) and the device identifier (-d):

python3 hono_commands_ldt.py -t demo -d demo:device

Verify

On the shell there will be output of the structure of the edge digital twins with all its features and properties. Things with the following identifiers will be presented:

• demo:device
• demo:device:edge:containers

Clean up

Stop the local digital twins service and start suite connector service by executing:

sudo systemctl stop local-digital-twins.service && \
sudo systemctl restart suite-connector.service

4 - References

4.1 - Remote connectivity configuration

4.1.1 - AWS Connector configuration

Properties

To control all aspects of the suite connector behavior.

Example

The minimal required configuration to connect.

{
    "address": "tls://<AWS-endpoint-address>:8883",
    "caCert": "AmazonRootCA1.pem",
    "cert": "example-device.crt",
    "key": "example-device.key",
    "clientId": "org.eclipse.kanto:exampleDevice",
    "logFile": "/var/log/aws-connector/aws-connector.log"
}

Template

The configuration can be further adjusted according to the use case. The following template illustrates all possible properties with their default values.

{
    "topicFilter": "",
    "payloadFilters": [],
    "address": "",
    "alpn" : [],
    "tenantId": "default-tenant-id",
    "clientId": "",
    "caCert": "aws.crt",
    "cert": "",
    "key": "",
    "tpmDevice": "",
    "tpmHandle": 0,
    "tpmKeyPub": "",
    "tpmKey": "",
    "localAddress": "tcp://localhost:1883",
    "localUsername": "",
    "localPassword": "",
    "localCACert": "",
    "localCert": "",
    "localKey": "",
    "logFile": "logs/aws-connector.log",
    "logLevel": "INFO",
    "logFileCount": 5,
    "logFileMaxAge": 28,
    "logFileSize": 2
}

4.1.2 - Suite connector configuration

Properties

To control all aspects of the suite connector behavior.

Example

The minimal required configuration to connect the publicly available Eclipse Hono sandbox.

{
    "address": "hono.eclipseprojects.io:1883",
    "tenantId": "org.eclipse.kanto",
    "deviceId": "org.eclipse.kanto:exampleDevice",
    "authId": "org.eclipse.kanto_example",
    "password": "secret",
    "logFile": "/var/log/suite-connector/suite-connector.log"
}

Template

The configuration can be further adjusted according to the use case. The following template illustrates all possible properties with their default values.

{
    "provisioningFile": "provisioning.json",
    "address": "mqtts://mqtt.bosch-iot-hub.com:8883",
    "alpn" : [],
    "deviceId": "",
    "authId": "",
    "tenantId": "",
    "password": "",
    "username": "",
    "clientId": "",
    "policyId": "",
    "caCert": "iothub.crt",
    "cert": "",
    "key": "",
    "deviceIdPattern": "",
    "tpmDevice": "",
    "tpmHandle": 0,
    "tpmKeyPub": "",
    "tpmKey": "",
    "localAddress": "tcp://localhost:1883",
    "localUsername": "",
    "localPassword": "",
    "logFile": "log/suite-connector.log",
    "logLevel": "INFO",
    "logFileCount": 5,
    "logFileMaxAge": 28,
    "logFileSize": 2
}

4.1.3 - Suite bootstrapping configuration

Properties

To control all aspects of the suite bootstrapping behavior.

Example

The minimal required configuration to connect the publicly available Eclipse Hono sandbox and request automatic provisioning.

{
    "address": "hono.eclipseprojects.io:1883",
    "tenantId": "org.eclipse.kanto",
    "deviceId": "org.eclipse.kanto:exampleDevice",
    "authId": "org.eclipse.kanto_example",
    "password": "secret",
    "logFile": "/var/log/suite-bootstrapping/suite-bootstrapping.log"
}

Template

The configuration can be further adjusted according to the use case. The following template illustrates all possible properties with their default values.

{
    "preBootstrapScript": "",
    "preBootstrapFile": "",
    "postBootstrapScript": "",
    "postBootstrapFile": "",
    "bootstrapProvisioningFile": "",
    "maxChunkSize": 46080,
    "provisioningFile": "provisioning.json",
    "address": "mqtts://mqtt.bosch-iot-hub.com:8883",
    "deviceId": "",
    "authId": "",
    "tenantId": "",
    "password": "",
    "clientId": "",
    "policyId": "",
    "caCert": "iothub.crt",
    "cert": "",
    "key": "",
    "deviceIdPattern": "",
    "tpmDevice": "",
    "tpmHandle": 0,
    "tpmKeyPub": "",
    "tpmKey": "",
    "logFile": "log/suite-bootstrapping.log",
    "logLevel": "INFO",
    "logFileCount": 5,
    "logFileMaxAge": 28,
    "logFileSize": 2
}

4.2 - Local digital twins configuration

Properties

To control all aspects of the local digital twins behavior.

Example

The minimal required configuration to enable the local digital twins and their synchronization with the publicly available Eclipse Hono sandbox.

{
    "address": "hono.eclipseprojects.io:1883",
    "tenantId": "org.eclipse.kanto",
    "deviceId": "org.eclipse.kanto:exampleDevice",
    "authId": "org.eclipse.kanto_example",
    "password": "secret",
    "thingsDb": "/var/lib/local-digital-twins/thing.db",
    "logFile": "/var/log/local-digital-twins/local-digital-twins.log"
}

Template

The configuration can be further adjusted according to the use case. The following template illustrates all possible properties with their default values.

{
    "thingsDb": "things.db",
    "provisioningFile": "provisioning.json",
    "address": "mqtts://mqtt.bosch-iot-hub.com:8883",
    "deviceId": "",
    "authId": "",
    "tenantId": "",
    "password": "",
    "clientId": "",
    "policyId": "",
    "caCert": "iothub.crt",
    "cert": "",
    "key": "",
    "deviceIdPattern": "",
    "tpmDevice": "",
    "tpmHandle": 0,
    "tpmKeyPub": "",
    "tpmKey": "",
    "localAddress": "tcp://localhost:1883",
    "localUsername": "",
    "localPassword": "",
    "localCACert": "",
    "localCert": "",
    "localKey": "",
    "logFile": "log/local-digital-twins.log",
    "logLevel": "INFO",
    "logFileCount": 5,
    "logFileMaxAge": 28,
    "logFileSize": 2
}

4.3 - Container management configuration

4.3.1 - Container configuration

Properties

To control all aspects of the container instance behavior.

Example

The minimal required configuration to spin up an InfluxDB container instance.

{
  "image": {
    "name": "docker.io/library/influxdb:1.8.4"
  }
}

Template

The configuration can be further adjusted according to the use case. The following template illustrates all possible properties with their default values.

{
    "container_name": "",
    "image": {
        "name": "",
        "decrypt_config": {
            "keys": [],
            "recipients": []
        }
    },
    "domain_name": "",
    "host_name": "",
    "mount_points": [
        {
            "destination": "",
            "source": "",
            "propagation_mode": "rprivate"
        }
    ],
    "config": {
        "env": [],
        "cmd": []
    },
    "io_config": {
        "open_stdin": false,
        "tty": false
    },
    "host_config": {
        "devices": [
            {
                "path_on_host": "",
                "path_in_container": "",
                "cgroup_permissions": "rwm"
            }
        ],
        "network_mode": "bridge",
        "privileged": false,
        "extra_hosts": [],
        "port_mappings": [
            {
                "proto": "tcp",
                "container_port": 0,
                "host_ip": "0.0.0.0",
                "host_port": 0,
                "host_port_end": 0
            }
        ],
        "resources": {
            "memory": "",
            "memory_reservation": "",
            "memory_swap": ""
        },
        "restart_policy": {
            "type": "unless-stopped",
            "maximum_retry_count": 0,
            "retry_timeout": 0
        },
        "log_config": {
            "driver_config": {
                "type": "json-file",
                "max_files": 2,
                "max_size": "100M",
                "root_dir": ""
            },
            "mode_config": {
                "mode": "blocking",
                "max_buffer_size": "1M"
            }
        }
    }
}

4.3.2 - Manager configuration

Properties

To control all aspects of the container manager behavior.

Example

The minimal required configuration that sets a timeout period of 5 seconds for the managed containers to stop gracefully.

{
    "manager": {
        "default_ctrs_stop_timeout": 5
    },
    "log": {
        "log_file": "/var/log/container-management/container-management.log"
    }
}

Template

The configuration can be further adjusted according to the use case. The following template illustrates all possible properties with their default values.

{
    "manager": {
        "home_dir": "/var/lib/container-management",
        "exec_root_dir": "/var/run/container-management",
        "container_client_sid": "container-management.service.local.v1.service-containerd-client",
        "network_manager_sid": "container-management.service.local.v1.service-libnetwork-manager",
        "default_ctrs_stop_timeout": 30
    },
    "containers": {
        "default_ns": "kanto-cm",
        "address_path": "/run/containerd/containerd.sock",
        "exec_root_dir": "/var/run/container-management",
        "home_dir": "/var/lib/container-management",
        "image_dec_keys": [],
        "image_dec_recipients": [],
        "runc_runtime": "io.containerd.runc.v2",
        "image_expiry": "744h",
        "image_expiry_disable": false,
        "lease_id": "kanto-cm.lease",
        "registry_configurations": {
            "": {
                "credentials": {
                    "user_id": "",
                    "password": ""
                },
                "transport": {
                    "root_ca": "",
                    "client_cert": "",
                    "client_key": ""
                }
            }
        },
        "insecure_registries": [
            "localhost"
        ]
    },
    "network": {
        "home_dir": "/var/lib/container-management",
        "exec_root_dir": "/var/run/container-management",
        "default_bridge": {
            "name": "kanto-cm0",
            "ip4": "",
            "fcidr4": "",
            "enable_ip6": false,
            "mtu": 1500,
            "icc": true,
            "ip_tables": true,
            "ip_forward": true,
            "ip_masq": true,
            "userland_proxy": false
        }
    },
    "grpc_server": {
        "protocol": "unix",
        "address_path": "/run/container-management/container-management.sock"
    },
    "things": {
        "enable": true,
        "home_dir": "/var/lib/container-management",
        "features": [
            "ContainerFactory",
            "SoftwareUpdatable",
            "Metrics"
        ],
        "connection": {
            "broker_url": "tcp://localhost:1883",
            "keep_alive": 20000,
            "disconnect_timeout": 250,
            "client_username": "",
            "client_password": "",
            "connect_timeout": 30000,
            "acknowledge_timeout": 15000,
            "subscribe_timeout": 15000,
            "unsubscribe_timeout": 5000,
            "transport": {
                "root_ca": "",
                "client_cert": "",
                "client_key": ""
            }
        }
    },
    "log": {
        "log_file": "log/container-management.log",
        "log_level": "INFO",
        "log_file_count": 5,
        "log_file_size": 2,
        "log_file_max_age": 28,
        "syslog": false
    },
    "deployment": {
        "enable": true,
        "mode": "update",
        "home_dir": "/var/lib/container-management",
        "ctr_dir": "/etc/container-management/containers"
    }
}

4.4 - Software update configuration

Properties

To control all aspects of the software update behavior.

Example

The minimal required configuration that sets the software type to firmware.

{
    "moduleType": "firmware",
    "storageLocation": "/var/lib/software-update",
    "logFile": "/var/log/software-update/software-update.log"
}

Template

The configuration can be further adjusted according to the use case. The following template illustrates all possible properties with their default values.

{
    "featureId": "SoftwareUpdatable",
    "moduleType": "software",
    "artifactType": "archive",
    "install": [],
    "storageLocation": "./",
    "installDirs": [],
    "mode": "strict",
    "downloadRetryCount": 0,
    "downloadRetryInterval": "5s",
    "serverCert": "",
    "broker": "tcp://localhost:1883",
    "username": "",
    "password": "",
    "logFile": "log/software-update.log",
    "logLevel": "INFO",
    "logFileCount": 5,
    "logFileMaxAge": 28,
    "logFileSize": 2
}

4.5 - File upload configuration

Properties

To control all aspects of the file upload behavior.

Example

The minimal required configuration that sets the file type to log.

{
    "type": "log",
    "files": "/var/tmp/file-upload/*.*",
    "logFile": "/var/log/file-upload/file-upload.log"
}

Template

The configuration can be further adjusted according to the use case. The following template illustrates all possible properties with their default values.

{
    "featureId": "AutoUploadable",
    "type": "file",
    "context": "edge",
    "files": "",
    "mode": "strict",
    "singleUpload": false,
    "checksum": false,
    "stopTimeout": "30s",
    "delete": false,
    "serverCert": "",
    "active": false,
    "activeFrom": "",
    "activeTill": "",
    "period": "10h",
    "broker": "tcp://localhost:1883",
    "username": "",
    "password": "",
    "caCert": "",
    "cert": "",
    "key": "",
    "logFile": "log/file-upload.log",
    "logLevel": "INFO",
    "logFileCount": 5,
    "logFileMaxAge": 28,
    "logFileSize": 2
}

4.6 - File backup configuration

Properties

To control all aspects of the file backup behavior.

Example

The minimal required configuration that enables backing up a directory and sets the file type to config.

{
    "type": "config",
    "dir": "/var/tmp/file-backup",
    "mode": "scoped",
    "storage": "/var/lib/file-backup",
    "logFile": "/var/log/file-backup/file-backup.log"
}

Template

The configuration can be further adjusted according to the use case. The following template illustrates all possible properties with their default values.

{
  "featureId": "BackupAndRestore",
  "type": "file",
  "context": "edge",
  "dir": "",
  "mode": "strict",
  "backupCmd": "",
  "restoreCmd": "",
  "singleUpload": false,
  "checksum": false,
  "stopTimeout": "30s",
  "keepUploaded": false,
  "storage": "./storage",
  "serverCert": "",
  "active": false,
  "activeFrom": "",
  "activeTill": "",
  "period": "10h",
  "broker": "tcp://localhost:1883",
  "username": "",
  "password": "",
  "caCert": "",
  "cert": "",
  "key": "",
  "logFile": "log/file-backup.log",
  "logLevel": "INFO",
  "logFileCount": 5,
  "logFileMaxAge": 28,
  "logFileSize": 2
}

4.7 - System metrics configuration

Properties

To control all aspects of the system metrics behavior.

Example

The minimal required configuration that enables the auto reporting of system metrics.

{
    "frequency": "60s",
    "logFile": "/var/log/system-metrics/system-metrics.log"
}

Template

The configuration can be further adjusted according to the use case. The following template illustrates all possible properties with their default values.

{
    "frequency" : ""
    "broker": "tcp://localhost:1883",
    "username": "",
    "password": "",
    "logFile": "log/system-metrics.log",
    "logLevel": "INFO",
    "logFileCount": 5,
    "logFileMaxAge": 28,
    "logFileSize": 2
}