Command Line Tools

Thistle command line tools for OTA updates

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

In normal circumstances, the Thistle Update Client will be executed simply with a configuration file. The 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