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

  • Version 1.6.0 (or above) of TUC and TRH for your platform
  • On the Thistle Contrl Center 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 and initialization

# 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 --signing-method="remote" init
First we initialize the local development environment by executing the init command. This creates a Cloud-KMS-backed OTA update bundle signing key pair on the Thistle backend, 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.
Your local working environment is now ready.

​
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 --signing-method="remote" prepare --target="./example" --file-base-path="/tmp"
Upon success, manifest.json will be amended and signed for the OTA release.

​
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 --signing-method="remote" release
With the OTA update artifacts and manifest uploaded to the Thistle Backend, we are now ready to run the Thistle Update Client (TUC) to fetch and install the OTA update on a device. First generate a device configuration file config.json for group enrollment (cf. Enrollment on first boot). 
./trh --signing-method="remote" gen-device-config \
--device-name="my-demo-device" \
--enrollment-type="group-enroll" \
--persist="${HOME}/thistle-ota"
The above command generates config.json in the current directory. It configures the client to store persistent data between device reboots in path ~/thistle-ota/. Place config.json on a device to receive the OTA update, and run TUC with this configuration. In this guide we will run TUC on the same machine where TRH is run. 
./tuc -c ./config.json
# by default the TUC continues running. Use ctrl-C to exit from it.

# verify installation below
$ cat /tmp/my_app
hello world
You can confirm your file was installed as defined by looking at the install path /tmp/my_app.

​
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 device configuration file config.json will then receive this update. 
echo "hello new world" > ./example/my_app
./trh --signing-method="remote" prepare --target="./example" --file-base-path="/tmp"
./trh --signging-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 - and many more use cases are supported!