Release firmware with the CLI¶
The CLI is in beta, as the install page explains.
Every command has --help with examples, and --json prints
machine-readable output
(schema).
Log in¶
The CLI uses an API token you make in the dashboard.
| Token | Prefix | Reaches | Make it |
|---|---|---|---|
| Personal | soto_pat_ |
Every project your account can open | API tokens in the account menu |
| Project | soto_proj_ |
One project | Issue token on the project page, with the api scope |
Use a personal token on your own machine, and a project token in CI. See
Tokens for the scopes. A device-scope token cannot
upload or deploy.
Paste the token at the prompt. In a graphical session (not over SSH),
pressing Enter at the prompt instead opens the API tokens page in your
browser; --no-browser turns that off. You can also pipe the token in:
The token is checked with the server, then stored in the OS keychain, or in a
0600 file in the config directory when there is no keychain (or
SIMPLEOTA_NO_KEYRING is set). If SIMPLEOTA_TOKEN is set, it is used
instead of the stored token.
Check what the CLI will act on:
status shows the CLI's version, the account, the current project and the
signing key new builds would be signed with.
Choose a project¶
Most commands act on the current project, the first of these that applies:
--project <slug|id>SIMPLEOTA_PROJECT- the project chosen with
simpleota project use(personal tokens only) - the only project the token can see; a project token sees just its own
Projects are created in the dashboard.
Make a signing key¶
Skip this section to release basic (unsigned) builds.
This makes an Ed25519 key pair on your machine, saves the private key
encrypted with a passphrase you choose, and registers only the public key
with the project. The first key you generate becomes the default for signing.
key generate needs a personal token.
Devices pin at most two keys, so make a backup key before your first signed release and keep it offline:
Each key generate prints a signing_keys snippet for the 1.0 Arduino and
ESP-IDF clients that pins the new key and your default key, so the backup
key's snippet pins both. Put that one in your firmware. See
Signed firmware for what the device checks and
how to rotate or revoke a key.
Release a build¶
release signs, uploads and deploys a binary in one step:
- Pass the application image:
build/<sketch>.ino.binfrom Arduino, orbuild/<project>.binfrom ESP-IDF. The CLI refuses the bootloader, partition table, merged and filesystem images it can recognise by name. - The chip is read from the image header. The framework defaults to the
project's; pass
--framework arduinoor--framework esp_idfto override it. - The build is signed with the first key found:
--key-file, thenSIMPLEOTA_SIGNING_KEY, then your default key. With no key it is uploaded as basic.--security-mode basicor--security-mode signedmakes the choice explicit. - The server assigns the build number.
- The deployment goes to the
stablechannel unless you pass--channel, which must name an existing channel.--percentdefaults to 100.
The result names the build, the deployment ID, and the count of active devices in the deployment's audience whose last reported metadata is compatible with the build. That count ignores the rollout percentage, and a device's next check-in can change it.
The upload is sent once and never retried, because every accepted upload
uses a build number and counts toward your plan's monthly limit. If the
project already has this binary, release stops before uploading, so it is
safe to run again after a failed upload. If the first upload was accepted, for
example when the connection dropped after the server took it, the rerun exits 1
without uploading or deploying. It then names the existing build and any
deployment of it that is still running or paused. If none is listed, deploy
the build with simpleota deployment create --build <n>, passing the same
--channel and --percent. Pass --allow-duplicate to upload the same bytes
as a new build.
Upload now, deploy later¶
simpleota build upload build/app.bin --version-label 1.0.0
simpleota deployment create --build 42 --channel beta --percent 10
deployment create targets channels (--channel), device groups
(--group), or every device (--all-devices). Repeat --channel or
--group for more than one. With both, a device must match one of each.
Manage deployments¶
| Command | What it does |
|---|---|
simpleota deployment list |
List deployments, newest first |
simpleota deployment show [id] |
Show the build, state, percentage and device counts; the newest deployment without an ID |
simpleota deployment devices [id] |
List the compatible devices the release count included |
simpleota deployment ramp <id> --percent 50 |
Raise the percentage. It cannot go down |
simpleota deployment pause <id> |
Stop offering the build |
simpleota deployment resume <id> |
Offer it again at the same percentage |
simpleota deployment complete <id> |
Mark the deployment finished |
simpleota deployment cancel <id> |
Stop the deployment for good |
In a project with two or more devices, resuming a deployment that
targets every device needs --all-devices again.
Several deployments can be active on one channel, and each device installs the
highest build offered to it. release lists the other active deployments for
the same chip on its channel; stop one with deployment complete.
There is no rollback command: devices are never offered a build at or below the one they run. To go back, release the previous source again as a new, higher build. See Promoting deployments and Pausing deployments.
Other commands¶
| Command | What it does |
|---|---|
simpleota device list |
List devices, filtered by --channel, --group or --state |
simpleota device show <device> |
Show one device |
simpleota device events <device> |
Show its recent update checks and why it was or was not offered a build |
simpleota device update <device> --channel beta |
Move a device to a channel; --name and --state rename or (de)activate it |
simpleota channel list, channel create <name> |
List or create release channels |
simpleota group list, group create <name> |
List or create device groups |
simpleota group member add <group> <device>... |
Add devices to a group; list and remove work the same way |
simpleota build list, build show <n> |
List builds or show one |
simpleota build archive <n> |
Take a build out of service; unarchive returns it |
simpleota audit |
Show the project's audit log |
Name a device by the device ID its firmware reports, such as a MAC address, or by its SimpleOTA UUID. Devices register themselves on their first check-in.
In CI¶
You need three secrets:
SIMPLEOTA_TOKEN: a project token with theapiscope, issued for the job.SIMPLEOTA_SIGNING_KEY: the encrypted private key, fromsimpleota key exporton the machine that holds it.SIMPLEOTA_SIGNING_KEY_PASSPHRASE: its passphrase.
For example, with the GitHub CLI:
A project token acts on its own project, so the job needs no --project.
Install a pinned version on the runner, then release with
--require-devices:
- name: Install the SimpleOTA CLI
run: |
curl -fsSL https://github.com/wassie-dev/simpleOTA-cli/releases/download/v0.2.0/install.sh | SIMPLEOTA_VERSION=0.2.0 SIMPLEOTA_INSTALL_DIR="$HOME/.local/bin" SIMPLEOTA_NO_MODIFY_PATH=1 sh
echo "$HOME/.local/bin" >> "$GITHUB_PATH"
- name: Release firmware
env:
SIMPLEOTA_TOKEN: ${{ secrets.SIMPLEOTA_TOKEN }}
SIMPLEOTA_SIGNING_KEY: ${{ secrets.SIMPLEOTA_SIGNING_KEY }}
SIMPLEOTA_SIGNING_KEY_PASSPHRASE: ${{ secrets.SIMPLEOTA_SIGNING_KEY_PASSPHRASE }}
run: simpleota release build/app.bin --version-label "${GITHUB_REF_NAME}" --percent 10 --require-devices
Define the three secrets as CI/CD variables. The job image needs curl
or wget, tar, and sha256sum or shasum.
release-firmware:
rules:
- if: $CI_COMMIT_TAG
script:
- curl -fsSL https://github.com/wassie-dev/simpleOTA-cli/releases/download/v0.2.0/install.sh | SIMPLEOTA_VERSION=0.2.0 SIMPLEOTA_INSTALL_DIR="$HOME/.local/bin" SIMPLEOTA_NO_MODIFY_PATH=1 sh
- export PATH="$HOME/.local/bin:$PATH"
- simpleota release build/app.bin --version-label "$CI_COMMIT_TAG" --percent 10 --require-devices
Devices may check in only once a day, so the job does not wait for them.
With --require-devices, the job fails with exit code 4 when no active device
in the audience has reported metadata compatible with the build. The
deployment stays active, and you can follow it afterwards with
simpleota deployment show.
On GitHub, the SimpleOTA actions do the same job as workflow steps.
Exit codes¶
| Code | Meaning |
|---|---|
| 0 | OK |
| 1 | Error, or the command was interrupted |
| 2 | Usage error, including no current project when the token sees several |
| 3 | Not logged in, or the token was rejected |
| 4 | With --require-devices, no active device in the audience has compatible metadata |
With --require-devices, an unknown count exits 1, for example when the
server is too old to report it.
Environment variables¶
| Variable | Use |
|---|---|
SIMPLEOTA_TOKEN |
API token; used instead of the stored one |
SIMPLEOTA_PROJECT |
Project slug or ID; used instead of project use |
SIMPLEOTA_SIGNING_KEY |
Exported key, encrypted or PEM |
SIMPLEOTA_SIGNING_KEY_PASSPHRASE |
Passphrase for an encrypted key |
SIMPLEOTA_API_URL |
API URL (default https://simpleota.com) |
SIMPLEOTA_CONFIG_DIR |
Config directory (default: the OS user config directory) |
SIMPLEOTA_NO_KEYRING |
Store the token in a 0600 file instead of the keychain |
SIMPLEOTA_DOWNLOAD_URL |
Mirror for update downloads (https, or http on localhost) |
NO_COLOR |
Turn off colour |