Documentation Index
Fetch the complete documentation index at: https://docs.thistle.tech/llms.txt
Use this file to discover all available pages before exploring further.
Two command line tools are offered, both to help package the update bundles, and to install them. The update client is designed to apply updates to a given device safely and securely. It only accepts a subset of manual command line operations, as it receives its operating instructions from the Thistle Backend, as defined by update manufacturers.
The Thistle Release Helper is here to assist with the packaging of updates. This helper program will help with creating new configuration files for devices, as well as manifest files - defining the update itself. Uploading assets is also possible directly from this tool.
Update Client Usage
$ tuc --help
Thistle Update Client (TUC) 1.6.0
TUC is responsible for downloading, verifying, and applying file updates & root filesystem updates
to embedded platforms, as well as managing all communications with Thistle's backend.
Refer to https://docs.thistle.tech/ for more information
USAGE:
tuc [OPTIONS] [SUBCOMMAND]
OPTIONS:
-c, --config <CONFIG> Set configuration file path. [default: config.json]
-h, --help Print help information
--log-file <LOG_FILE> Set optional log file path.
--log-level <LOG_LEVEL> Set logging level. Possible values are 'trace', 'info', 'warn',
and 'error'. [default: error]
-V, --version Print version information
SUBCOMMANDS:
help Print this message or the help of the given subcommand(s)
install Install a manifest from a local file or a URL
install subcommand can be helpful to locally test
out a single given manifest file, as it makes it accepts local paths.
Thistle Release Helper Usage
$ trh --help
Thistle Release Helper (TRH) 1.6.0
Manage Thistle assets, updates and developer workflow.
Examples:
Initialize: ./trh init
Prepare assets: ./trh prepare -t=file-or-filetree
Upload and release assets: ./trh release
Prepare and upload a Zephyr release: ./trh zephyr
USAGE:
trh [OPTIONS] [TOKEN] <SUBCOMMAND>
ARGS:
<TOKEN> Credentials used to authenticate against Thistle's Backend
[env: THISTLE_TOKEN=]
OPTIONS:
-s, --secret-key <SECRET_KEY>
Path to secret key used for signing assets
[env: THISTLE_KEY=]
-p, --password <PASSWORD>
Password used to protect secret key. If none provided, user will be prompted
[env: THISTLE_KEY_PASS=]
--signing-method <SIGNING_METHOD>
Signing method to use. Can be "local" for local minisign key, "remote" for Thistle KMS
, or "external" for using an external signing command [default: local]
--external-sign <EXTERNAL_SIGN>
(Optional) External signing command to use if signing-method specified as "external" The
command will be executed with the asset file to sign as the last argument, and should
return the signature in the first line of stdout
--public-key <PUBLIC_KEY>
(Optional) Public key to use if using an external signing method
-m, --manifest-path <MANIFEST_PATH>
Path used to fetch manifest
[default: ./manifest.json]
-t, --tags <TAGS>
(Optional) Tags for this release bundle.
Tags are used to filter releases on the Thistle Backend.
NOTE: This option only applies to the fetch-current and release commands, and is
ignored by all other commands
-h, --help
Print help information
-V, --version
Print version information
SUBCOMMANDS:
init Initialize a new Thistle OTA update manifest and return a signing
keypair
prepare Prepare manifest with assets indicated
release Release manifest to Thistle Backend
zephyr Prepare and release a Zephyr application
fetch-current Fetch current manifest
gen-device-config
identity Generate a device specific identity file
keygen Generate a new keypair for signing assets, and return the public key.
If a keypair already exists, simply return the existing public key
All trh subcommands require the THISTLE_TOKEN environment variable to be set
to a valid project access token, which can be obtained from Thistle Control
Center (TCC). Init subcommand
init creates an OTA update bundle signing key pair (locally or on Thistle
backend, depending on the --signing-method), and an OTA update manifest file
manifest.json locally in the current directory, if they do not exist. If they
already exist, the public key portion of the key pair and the latest manifest
file will be obtained.
# initialize a new OTA release environment
$ ./trh init
Prepare subcommand
The prepare subcommand packages the indicated target, compresses it, adds it to
the manifest, and signs this manifest with the private key.
More options are available to add pre and post install scripts. See trh --help
for more information related to the supported options.
# prepare the manifest with a filesystem tree under /path/to/dir. When `--file-base-path` is
# not present, the filesystem tree which will be installed on-device to a path
# relative to the directory where `tuc` is executed.
$ ./trh prepare --target=/path/to/dir
# prepare the manifest with a filesystem tree under /path/to/dir. When `--file-base-path` is
# present, the filesystem tree is installed on-target under /opt/project.
$ ./trh prepare --target=/path/to/dir --file-base-path=/opt/project
# prepare the manifest with a single rootfs
$ ./trh prepare --target=rootfs.img
Release subcommand
The release subcommand publishes the assets previously prepared, amends the
manifest with the new remote URLs, resigns this manifest, and uploads it
according to the supplied authenticated token.
Note that this command will automatically increase the release version in the
manifest, and update the timestamp.
# upload assets and manifest
$ ./trh release
Fetch-current subcommand
This subcommand can be used to fetch the latest manifest the Thistle Backend is
currently holding for a given THISTLE_TOKEN. The manifest will be fetched and
written on disk at the specified path.
# fetch current manifest for a given
$ ./trh fetch-current
Gen-device-config subcommand
gen-device-config generates a device configuration file for group enrollment
or pre-enrollment of devices. The configuration file is used by TUC to obtain
OTA update releases from Thistle backend, and install the update on a device.
Please refer to Device Provisioning for the two flavors
of device enrollment.
$ trh gen-device-config --help
trh-gen-device-config
USAGE:
trh gen-device-config [OPTIONS] --persist <PERSIST> --device-name <DEVICE_NAME>
OPTIONS:
-p, --persist <PERSIST>
Required. Path to directory on device to store persistent data
--device-name <DEVICE_NAME>
Required. Device name. This name will be used to identify the device in the Thistle
Backend
-e, --enrollment-type <ENROLLMENT_TYPE>
Optional. Device enrollment type: group-enroll (default) or pre-enroll. Group enrollment
allows multiple devices to obtain a global DET (device enrollment token) for device
enrollment later. Pre-enrollment allows a device to be enrolled and obtain
device-unique credentials (device ID, device token, device private key, device
certificate) [default: group-enroll]
-c, --config-path <CONFIG_PATH>
(Optional) Path where the configuration file is written [default: ./config.json]
-h, --help
Print help information
Identity subcommand
identity subcommand helps create an identity file. If the pre-enroll option
is used, a device will be pre-enrolled with the Thistle Backend and the
enrollment credentials will be appended in the identity file.
# Enroll a device with Thistle & create an identity file with the new credentials
$ ./trh identity --device-name "tutorial" --pre-enroll
