Link Search Menu Expand Document

File Update

This guide will show you the most simple use case applicable to the Thistle Update Client: how to update a single file. You may run the update client directly on a desktop/laptop computer (Linux, macOS, or Windows) as it will run in the same manner on an embedded device.

Tools needed

To get started you need to obtain:

  • The Thistle Update Client for your platform
  • The Thistle Release Helper to help packaging your updates
  • On the Thistle App. Visit the settings section of a project to obtain the API token (“Project Access Token”) to be used as THISTLE_TOKEN in the configuration step below.

"Project's Access Token"

Configuration 

# Set up your project's access token - Bash, on Linux/Unix or Windows Subsystem for Linux (WSL)
$ export THISTLE_TOKEN=$(cat)
(paste access token, press enter, then ctrl-d)

# Set up your project's access token - Windows PowerShell
$ $env:THISTLE_TOKEN = "[Access Token Obtained from Thistle App's Project Settings section]"

$ ./trh init -p="/tmp/persist"
Device enrollment token: [REDACTED]
Deriving a key from the password and decrypting the secret key... done
Private key stored at: "/home/user/.minisign/minisign.key"
Manifest generated at: "./manifest.json"
Configuration generated at path "./config.json"

First we initialize the local development environment by executing the init command. This will set the device trust model to Trust On First Use (TOFU) where devices are to be trusted upon joining the network.

The init command requires the path to an on-device persistent directory. This path will be used by the client to store persistent data between restarts./tmp/persist was used in this example. The signing key and device configuration file config.json will also be generated.

What’s in an update

We will now package our first update. For the purpose of this test, the update will contain a single binary called my_app, that will be installed at path /tmp/my_app. Complete “rootfs” system update are also possible using similar commands. Updates are defined by manifest files, they contain the assets’ definition and a cryptographic signature.

$ mkdir -p ./example
$ echo "hello world" > ./example/my_app

# my_app will be installed on target system at /tmp/my_app
$ ./trh prepare --target="./example" --file-base-path="/tmp"
...
Manifest amended successfully

Upload and test deployed release

Now that we have prepared the update bundle, we can use the trh tool to upload the release and its assets.

$ ./trh release
Read manifest at "./manifest.json"
Uploaded asset my_app
...
Manifest uploaded successfully
Compressed artifacts removed locally

With the manifest fully uploaded to the Thistle Backend, alongside with its payload, it is now possible to fetch and install this update from any device running the Thistle Update Client, and the configuration we generated earlier on.

$ ./tuc -c ./config.json
!! Thistle client starting with no bootloader set - file only mode
!! installing update 1 => 2
!! setting update status to Started
!! setting update status to Pass
# by default the TUC continues running. Use ctrl-C to exit from it.

# verify installation below
$ cat /tmp/my_app
hello world

Upload a new update bundle

To update the manifest we just released with newer content, we need to re-run the prepare and release commands. All the devices using the configuration file config.json will then receive this update.

$ echo "hello new world" > ./example/my_app

$ ./trh prepare --target="./example" --file-base-path="/tmp"
...
Manifest amended successfully

$ ./trh release
Read manifest at "./manifest.json"
Uploaded asset my_app
...
Backup manifest uploaded successfully
Manifest uploaded successfully
Compressed artifacts removed locally

Signing an update bundle with a key in KMS

If one does not want to manage a local signing key, a Thistle-managed, Cloud KMS-backed ECDSA-P256 key can be used to sign OTA update bundles. Add option --signing-method="remote" to all the above trh commands to use this remotely managed signing key. For example,

trh --signing-method="remote" init ...
trh --signing-method="remote" prepare ...
trh --signing-method="remote" release

More options

In this get started guide, we explained the usage of the Thistle Update Client alongside the Thistle Release Helper to perform updates on a single file - but many more use cases are supported!