Developer tools

The Command Line Interface (CLI)

The thin-edge.io command-line interface (tedge CLI) is a set of commands used to create and manage thin-edge.io resources.

Tedge command

tedge 0.2.0
tedge is the cli tool for thin-edge.io

USAGE:
    tedge <SUBCOMMAND>

FLAGS:
    -h, --help       Print help information
    -V, --version    Print version information

SUBCOMMANDS:
    cert          Create and manage device certificate
    config        Configure Thin Edge
    connect       Connect to connector provider
    disconnect    Remove bridge connection for a provider
    help          Print this message or the help of the given subcommand(s)
    mqtt          Publish a message on a topic and subscribe a topic

Tedge config command

tedge-config 0.2.0
Configure Thin Edge

USAGE:
    tedge config <SUBCOMMAND>

FLAGS:
    -h, --help       Print help information
    -V, --version    Print version information

SUBCOMMANDS:
    get      Get the value of the provided configuration key
    help     Print this message or the help of the given subcommand(s)
    list     Print the configuration keys and their values
    set      Set or update the provided configuration key with the given value
    unset    Unset the provided configuration key

Get

tedge-config-get 0.2.0
Get the value of the provided configuration key

USAGE:
    tedge config get <key>

FLAGS:
    -h, --help       Print help information
    -V, --version    Print version information

ARGS:
    <key>    Configuration key. Run `tedge config list --doc` for available keys

Set

tedge-config-set 0.2.0
Set or update the provided configuration key with the given value

USAGE:
    tedge config set <key> <value>

FLAGS:
    -h, --help       Print help information
    -V, --version    Print version information

ARGS:
    <key>      Configuration key. Run `tedge config list --doc` for available keys
    <value>    Configuration value

List

tedge-config-list 0.2.0
Print the configuration keys and their values

USAGE:
    tedge config list [FLAGS]

FLAGS:
    -h, --help       Print help information
        --all        Print all the configuration keys, even those without a configured value
        --doc        Print all keys and descriptions with example values
    -V, --version    Print version information

Unset

tedge-config-unset 0.2.0
Unset the provided configuration key

USAGE:
    tedge config unset <key>

FLAGS:
    -h, --help       Print help information
    -V, --version    Print version information

ARGS:
    <key>    Configuration key. Run `tedge config list --doc` for available keys

Tedge cert command

tedge-cert 0.2.0
Create and manage device certificate

USAGE:
    tedge cert <SUBCOMMAND>

FLAGS:
    -h, --help       Print help information
    -V, --version    Print version information

SUBCOMMANDS:
    create    Create a self-signed device certificate
    help      Print this message or the help of the given subcommand(s)
    remove    Remove the device certificate
    show      Show the device certificate, if any
    upload    Upload root certificate

Create

tedge-cert-create 0.2.0
Create a self-signed device certificate

USAGE:
    tedge cert create --device-id <id>

FLAGS:
    -h, --help       Print help information
    -V, --version    Print version information

OPTIONS:
        --device-id <id>    The device identifier to be used as the common name for the certificate

Show

tedge-cert-show 0.2.0
Show the device certificate, if any

USAGE:
    tedge cert show

FLAGS:
    -h, --help       Print help information
    -V, --version    Print version information

Remove

tedge-cert-remove 0.2.0
Remove the device certificate

USAGE:
    tedge cert remove

FLAGS:
    -h, --help       Print help information
    -V, --version    Print version information

Upload

tedge-cert-upload 0.2.0
Upload root certificate

USAGE:
    tedge cert upload <SUBCOMMAND>

FLAGS:
    -h, --help       Print help information
    -V, --version    Print version information


SUBCOMMANDS:
    c8y     Upload root certificate to Cumulocity IoT
    help    Print this message or the help of the given subcommand(s)

Tedge connect command

tedge-connect 0.2.0
Connect to connector provider

USAGE:
    tedge connect <SUBCOMMAND>

FLAGS:
    -h, --help       Print help information
    -V, --version    Print version information


SUBCOMMANDS:
    az      Create connection to Azure
    c8y     Create connection to Cumulocity IoT
    help    Print this message or the help of the given subcommand(s)

Azure

tedge-connect-az 0.2.0
Create connection to Azure

The command will create config and start edge relay from the device to az instance

USAGE:
    tedge connect az [FLAGS]

FLAGS:
    -h, --help       Print help information
        --test       Test connection to Azure
    -V, --version    Print version information

Cumulocity IoT

tedge-connect-c8y 0.2.0
Create connection to Cumulocity IoT

The command will create config and start edge relay from the device to c8y instance

USAGE:
    tedge connect c8y [FLAGS]

FLAGS:
    -h, --help       Print help information
        --test       Test connection to Cumulocity IoT
    -V, --version    Print version information

Tedge disconnect command

tedge-disconnect 0.2.0
Remove bridge connection for a provider

USAGE:
    tedge disconnect <SUBCOMMAND>

FLAGS:
    -h, --help       Print help information
    -V, --version    Print version information

SUBCOMMANDS:
    az      Remove bridge connection to Azure
    c8y     Remove bridge connection to Cumulocity IoT
    help    Print this message or the help of the given subcommand(s)

Azure

tedge-disconnect-az 0.2.0
Remove bridge connection to Azure

USAGE:
    tedge disconnect az

FLAGS:
    -h, --help       Print help information
    -V, --version    Print version information

Cumulocity IoT

tedge-disconnect-c8y 0.2.0
Remove bridge connection to Cumulocity IoT

USAGE:
    tedge disconnect c8y

FLAGS:
    -h, --help       Print help information
    -V, --version    Print version information

Tedge mqtt command

tedge-mqtt 0.2.0
Publish a message on a topic and subscribe a topic

USAGE:
    tedge mqtt <SUBCOMMAND>

FLAGS:
    -h, --help       Print help information
    -V, --version    Print version information

SUBCOMMANDS:
    help    Print this message or the help of the given subcommand(s)
    pub     Publish a MQTT message on a topic
    sub     Subscribe a MQTT topic

Pub

tedge-mqtt-pub 0.2.0
Publish a MQTT message on a topic

USAGE:
    tedge mqtt pub [OPTIONS] <topic> <message>

FLAGS:
    -h, --help       Print help information
    -V, --version    Print version information

OPTIONS:
    -q, --qos <qos>    QoS level (0, 1, 2) [default: 0]

ARGS:
    <topic>      Topic to publish
    <message>    Message to publish

Sub

tedge-mqtt-sub 0.2.0
Subscribe a MQTT topic

USAGE:
    tedge mqtt sub [FLAGS] [OPTIONS] <topic>

FLAGS:
    -h, --help        Print help information
        --no-topic    Avoid printing the message topics on the console
    -V, --version     Print version information

OPTIONS:
    -q, --qos <qos>    QoS level (0, 1, 2) [default: 0]

ARGS:
    <topic>    Topic to subscribe to

MQTT topics

This document lists the MQTT topics that are supported by thin-edge.io.

Thin Edge JSON MQTT topics

To send the Thin Edge JSON measurements to a supported IoT cloud, the device should publish the measurements on the tedge/measurements topic. Internally the tedge-mapper will consume the measurements from this topic and translate and send them to the cloud that the device has been connected to by the tedge connect command.

Cumulocity IoT MQTT topics

The topics follow the below format <protocol>/<direction><type>[/<template>][/<child id>]

Protocol	Direction	Type
s = standard	u = upstream	s = static (built-in)
t = transient	d = downstream	c = custom (device-defined)
	e = error	d = default (defined in connect)
		t = template
		cr = credentials

SmartREST 2.0 topics

All Cumulocity IoT topics have been prefixed by c8y/.

Registration topics
- c8y/s/dcr
- c8y/s/ucr
Creating template topics
- c8y/s/dt
- c8y/s/ut/#
Static templates topics
- c8y/s/us
- c8y/t/us
- c8y/q/us
- c8y/c/us
- c8y/s/ds
Debug topics
- c8y/s/e
Custom template topics
- c8y/s/uc/#
- c8y/t/uc/#
- c8y/q/uc/#
- c8y/c/uc/#
- c8y/s/dc/#

C8Y JSON topics

c8y/measurement/measurements/create
c8y/error

You can find more information about Cumulocity IoT topics in our Tech Community.

Azure MQTT topics

MQTT clients on Thin Edge devices must use the below topics to communicate with the Azure cloud. The Azure topics are prefixed by az/.

az/messages/events/ - Use this topic to send messages from the device to the cloud. The messages are forwarded to the Azure topic named devices/{device_id}/messages/events/ where device_id is the Thin Edge device ID.
az/messages/devicebound/# - Use this topic to subscribe for the messages that were sent from the cloud to the device. Any message published by Azure on one of the subtopics of devices/{device_id}/messages/devicebound/# is republished here.

Collectd topics

When the device monitoring feature is enabled, monitoring metrics are emitted by collectd on a hierarchy of MQTT topics.

collectd/$HOSTNAME/# - All the metrics collected on the device with hostname $HOSTNAME.
collectd/$HOSTNAME/$PLUGIN/# - All the metrics collected by a given collectd plugin, named $PLUGIN.
collectd/$HOSTNAME/$PLUGIN/$METRIC - The topic for a given metric, named $METRIC. All the measurements are published as a pair of a Unix timestamp in milli-seconds and a numeric value in the format $TIMESTAMP:$VALUE. For example: 1623155717:98.6.

The collectd-mapper daemon process ingests these measurements and emits translated messages to the tedge/measurements topic. This process groups the atomic measurements that have been received in the same time-window (currently 200 ms) and produces a single Thin Edge JSON for the whole group of measurements.

Package Manager Plugin API

Thin Edge uses plugins to delegate all the software management operations to the appropriate package managers and installers: installation of packages, uninstallations and queries.

A package manager plugin acts as a facade for a specific package manager. A plugin is an executable that follows the plugin API. On a device, several plugins can be installed to deal with different kinds of software modules. Each plugin is given a name that is used by Thin Edge to determine the appropriate plugin for a software module. All the actions on a software module are directed to the plugin that is named like the module type name. Among all the plugins, one can be distinguished as the default plugin. The default plugin is invoked when no software module type can be determined by the system. Several plugins can co-exist for a given package manager as long as they have different names. Each plugin can implement a specific software management policy.

Plugin repository

To be used by Thin Edge, a plugin has to be stored in the directory /etc/tedge/sm-plugins. The same plugin can have different names, using virtual links. One of the plugins can have the name default. This plugin is then used as the default plugin.

On start-up and sign-up, the sm-agent registers the plugins as follows:

Iterate over the executable file of the directory /etc/tedge/sm-plugins.
Check if the executable is indeed a plugin, calling the list command.

Plugin API

A plugin must implement all the commands used by the sm-agent of Thin Edge, and support all the options for these commands. A plugin should not support additional commands or options. A plugin might have a configuration file. It can be a list of remote repositories, or a list of software modules to be excluded. These configuration files can be managed from the cloud via the sm-agent.

Input, output and errors

The plugins are called by the sm-agent using a child process for each action. For the current list of commands there is no input beyond the command arguments, and a plugin can close its stdin. The stdout and stderr of the process running a plugin command are captured by the sm-agent. These streams don’t have to be the streams returned by the underlying package manager. It can be a one sentence summary of the error, redirecting the administrator to the package manager logs. A plugin must return the appropriate exit status after each command. In no cases, the error status of the underlying package manager should be reported.

The exit statuses are interpreted by sm-agent as follows:

0: success.
1: usage. The command arguments cannot be interpreted, and the command has not been launched.
2: failure. The command failed and there is no point in retrying.
3: retry. The command failed but might be successful later (for instance, when the network will be back).

If the command fails to return within 5 minutes, the sm-agent reports a timeout error:

4: timeout.

List command

When called with the list command, a plugin returns the list of software modules that have been installed with this plugin.

$ debian-plugin list
...
{"name":"collectd-core","version":"5.8.1-1.3"}
{"name":"mosquitto","version":"1.5.7-1+deb10u1"}
...

This command takes no arguments. If an error status is returned, the executable is removed from the list of plugins. The list is returned using the jsonlines format. The parameter name ishe name of the module. This is the name that has been used to install it and must be used to remove it. The parameter version is he version currently installed. This is a string that can only been interpreted in the context of the plugin.

Prepare command

The prepare command is invoked by the sm-agent before a sequence of install and remove commands.

$ /etc/tedge/sm-plugins/debian prepare
$ /etc/tedge/sm-plugins/debian install x
$ /etc/tedge/sm-plugins/debian install y
$ /etc/tedge/sm-plugins/debian remove z
$ /etc/tedge/sm-plugins/debian finalize

For many plugins this command will do nothing. However, it gives the plugin an opportunity to:

Update the dependencies before an operation, i.e. a sequence of actions. Notably, a debian plugin can update the apt cache issuing an apt-get update.
Start a transaction, in case the plugin is able to manage rollbacks.

This command takes no arguments. No output is expected. If the prepare command fails, then the planned sequences of actions (i.e. the whole sm operation) is cancelled.

Finalize command

The finalize command closes a sequence of install and remove commands started by a prepare command.

This can be a no-op, but it’s also an opportunity to:

remove any unnecessary software module after a sequence of actions.
commit or rollback the sequence of actions.
restart any processes using the modules, e.g. restart the analytics engines if the modules have changed.

This command takes no arguments. No output is expected. This command might check (but doesn’t have to) that the list of install and remove command has been consistent. For instance, a plugin might raise an error after the sequence prepare;install a; remove a-dependency; finalize. If the finalize command fails, then the planned sequences of actions (i.e. the whole sm operation) is reported as failed, even if all the atomic actions have been successfully completed.

Install command

The install command installs a software module, possibly of some expected version.

$ plugin install NAME [--version VERSION] [--file FILE]

The command requires a single mandatory argument: the software module name. This module name is meaningful only to the plugin.

An optional version string can be provided. This version string is meaningful only to the plugin and is transmitted unchanged from the cloud to the plugin. The version string can include constraints (as at least that version), from the sm-agent viewpoint this is no more than a string. If no version is provided the plugin is free to install the more appropriate version.

An optional file path can be provided. When the device administrator provides a URL, the sm-agent downloads the software module on the device, then invokes the install command with a path to that file. If no file is provided, the plugin has to derive the appropriate location from its repository and to download the software module accordingly. The command installs the requested software module and any dependencies that might be required.

It is up to the plugin to define if this command triggers an installation or an upgrade. It depends on the presence of a previous version on the device and on the ability of the package manager to deal with concurrent versions for a module. A plugin might not be able to install dependencies. In that case, the device administrator will have to request explicitly the dependencies to be installed first.

After a successful sequence prepare; install foo; finalize the module foo must be reported by the list command.

After a successful sequence prepare; install foo --version v; finalize the module foo must be reported by the list command with the version v. If the plugin manages concurrent versions, the module foo might also be reported with versions already installed before the operation.

A plugin is not required to detect inconsistent actions as prepare; install a; remove a-dependency; finalize. It will not result in an error if you run this command twice or if the module is already installed.

An error is reported if:

The module name is unknown.
There is no version for the module that matches the constraint provided by the --version option.
The file content provided by --file option:
- is not in the expected format,
- doesn’t correspond to the software module name,
- has a version that doesn’t match the constraint provided by the --version option (if any).
The module cannot be downloaded.
The module cannot be installed.

Remove command

The remove command uninstalls a software module, and possibly its dependencies if no other modules are dependent on those.

$ plugin remove NAME [--version VERSION]

The command requires a single mandatory argument: the module name. This module name is meaningful only to the plugin and is transmitted unchanged from the cloud to the plugin.

An optional version string can be provided. This version string is meaningful only to the plugin and is transmitted unchanged from the cloud to the plugin. The command uninstalls the requested module and possibly any dependencies that are no longer required.

If a version is provided, only the module of that version is removed. In practice this is only useful for a package manager that is able to install concurrent versions of a module.

After a successful sequence prepare; remove foo; finalize the module foo must no more be reported by the list command.

After a successful sequence prepare; remove foo --version v; finalize the module foo is no longer reported by the list command with the version v. If the plugin manages concurrent versions, the module foo might still be reported with versions already installed before the operation.

A plugin is not required to detect inconsistent actions as prepare; remove a; install a-reverse-dependency; finalize. It will not result in an error if you run this command twice or if the module is not installed.

An error is reported if:

The module name is unknown.
The module cannot be uninstalled.