Building the SOTA Client

The simplest way to build the client is via Docker, which is used for compiling and running the client. You’ll find a Makefile in the client repo that offers targets using Docker to build and run everything.

Alternatively, you can compile locally with Rust and Cargo. (You’ll need to go this route if you’re not building x86_64.) We recommend installing both via Rustup.

Building with Docker and make

Run make help to see the full list of targets, which are:

Target Description

run

Run the client inside a Docker container.

clean

Remove all compiled libraries, builds and temporary files.

test

Run all cargo tests.

doc

Generate documentation for the sota crate.

clippy

Run clippy lint checks using the nightly compiler.

client

Compile a new release build of the client.

image

Build a Docker image for running the client.

deb

Create an installable DEB package of the client.

rpm

Create an installable RPM package of the client.

version

Print the version that will be used for building packages.

Configuration

You can configure how the client starts with make run by setting the following environment variables:

Variable Default value Description

AUTH_SECTION

false

Set to true to authenticate on startup.

CONFIG_ONLY

false

Set to true to generate a config file then quit.

AUTH_SERVER

http://127.0.0.1:9001

The Auth server for client authentication.

CORE_SERVER

http://127.0.0.1:9000

The Core server for client communication.

REGISTRY_SERVER

http://127.0.0.1:8083

The server used for registering new devices.

OUTPUT_PATH

/etc/sota.toml

Path to write the newly generated config.

TEMPLATE_PATH

/etc/sota.toml.template

Path to the template for new config files.

DEVICE_VIN

(generated)

Use this VIN rather than generating a new one.

DEVICE_UUID

(generated)

Use this UUID rather than generating a new one.

AUTH_CLIENT_ID

(from registry server)

Use this client ID for authentication.

AUTH_CLIENT_SECRET

(from registry server)

Use this client secret for authentication.

For example, running CONFIG_ONLY=true make run will output a newly generated sota.toml to stdout then quit.

Further customization

Every value in the generated sota.toml config file can be overwritten in the run/sota.toml.env file.

In addition, each config value is available as a command line flag when starting the client. Command line flags take precedence over the values set in the config file. Run sota_client --help to see a full list.

Building locally

As long as you’re on a platform that Rust supports, you should be able to build the client. The general steps are:

  1. Install rust with rustup

  2. Make sure you have the necessary dependencies installed, particularly libdbus-dev and libssl-dev

  3. Clone the client repo (preferably the stable branch)

  4. Compile using cargo build --release

That’s really it! At the moment, there is one extra step: we need to pin a particular version of hyper, a Rust HTTP library, due to some ssl fixes that are not yet in the release branches. There’s a Makefile target for that, though; just run make rust-openssl before you build.

Example: Building sota_client on a fresh Raspbian install, Raspberry Pi 2
apt-get update && apt-get install -y autoconf git libdbus-1-dev libtool openssl \
  libssl-dev lshw jq
curl https://sh.rustup.rs -sSf | sh -s -- --default-toolchain stable -y
export PATH=/root/.cargo/bin:$PATH
git clone https://github.com/advancedtelematic/rvi_sota_client.git -b stable
cd rvi_sota_client
make rust-openssl
cargo build --release
cp run/sota_certificates /etc/
cp run/system_info.sh /usr/bin/

Once you have the client built, you’ll probably want to take a close look at the configuration guide and perhaps the commands and events reference.