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 nameddevices/{device_id}/messages/events/
wheredevice_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 ofdevices/{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 anapt-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.