This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

How-to guides

Explore the functionalities of Eclipse Kanto.

1 - Update software

Install a Debian package on your edge device.

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

2 - Upload files

Upload a log file from your edge device.

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 - Back up and restore files

Back up and restore a file from and to your edge device.

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.

4 - Monitor system metrics

Monitor system metrics from your edge device.

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).

5 - Bootstrap device

Automatically provision your device via bootstrapping.

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

6 - Offline explore edge device

Offline receive the structure of your 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