CLI reference
The SDK's CLI, tools/devui.py, packs the interface (the web/ folder), publishes and unpublishes the product's interface, writes the tables of the product's database, publishes and rolls out the product's firmware (OTA) and makes the signing key. It is Python 3 alone, with the standard library: nothing to install. Each command exits with a code, so a CI decides without reading the message. Its messages are in Portuguese.
python tools/devui.py pack <web folder> [<out>] [options]
python tools/devui.py publish <web folder | bundle.dvu> --project-key pk_... [options]
python tools/devui.py unpublish --project-key pk_... [options]
python tools/devui.py tables push <tabelas.json> --project-key pk_... [options]
python tools/devui.py tables get --project-key pk_... [options]
python tools/devui.py firmware publish <app.bin> --chip CHIP --project-key pk_... [options]
python tools/devui.py firmware releases|rollout|status|pause|resume|complete|advance ... --project-key pk_... [options]
python tools/devui.py keygen <private key file>
python tools/devui.py pubkey <private key file>
python tools/devui.py --help, and --help after each command, show the options.
The key and the address
The commands that talk to the cloud (publish, unpublish, tables and firmware) take the same options:
| Option | What it is |
|---|---|
--project-key pk_... | the product's project_key (required) |
--key-file FILE | a file with the publishing key alone; --key-file - reads it from the standard input. Without it, the variable DEVUI_PUBLISH_KEY |
--api URL | the cloud's API; default: https://api.thingface.com. HTTP with no TLS only for a loopback address |
--oidc-token-file FILE | with no key: a file with the CI's OIDC token alone (- reads the standard input); without it, the variable DEVUI_OIDC_TOKEN or GitHub Actions itself |
--oidc-audience AUD | the audience (aud) of the OIDC token asked of GitHub Actions; default: the variable DEVUI_OIDC_AUDIENCE or https://api.thingface.com |
--timeout S | seconds to wait for the cloud; default: 60 |
The key never goes on the command line, because there any user of the machine sees it in the process list: an argument that looks like a key (or an OIDC token) is refused before anything else, with code 2, without being echoed. The key is created in the portal: Desenvolvedor ("Developer") > the product > Chaves de publicação ("Publishing keys"). With a key and a token at once, the key wins; with neither, the command asks GitHub Actions for the token (the job needs permissions: id-token: write) and exchanges it in the cloud for a credential of 15 minutes of that product (Publishing from the CI with no key kept). The CLI never follows a redirect, so the key does not go along.
devui pack
Packs the web/ folder into a DVU1 container and its manifest, always the same way (the same folder gives the same bytes), sending nothing.
python tools/devui.py pack examples/led/web out/
| Option | What it does |
|---|---|
<out> | the folder where bundle.dvu and bundle.manifest.json go (and bundle.sig, with --sign-key) |
--product NAME | the product in the manifest (default: devui-app); for the firmware's manifest to come out the same as the publication's, the project_key |
--version V | the interface's version in the manifest (default: 0.0.0) |
--c-source FILE | also a C file with the container and the manifest as byte arrays, for the firmware to embed |
--arduino FILE | the devui_bundle.h of an Arduino sketch. With no <out>, no --c-source and no --arduino, devui_bundle.h goes beside the web/ folder, in the sketch's folder |
--target CHIP | the IDF_TARGET (esp32, esp32s3, esp32c3...), lower case and with no hyphen, for the size warning; without it, or with a chip never measured, the smallest threshold among the measured chips holds. ESP32-S3 or s3 are refused |
--sign-key FILE | the signing private key (from devui keygen): signs the bundle, and the 72 bytes of the signature go in the firmware |
--security-version N | the security version in the manifest, an integer from 0 to 4294967295: the cloud refuses a signed publication below the highest the product already took |
--acoes FILE | the named actions, a JSON; without it, the acoes.json beside the web/ folder, if there is one (Named actions, in Portuguese) |
The packer refuses what the cloud would refuse: an absolute path outside /_devui/ in the HTML, the CSS or the JS, an extension outside the list, a container above 512 KiB or files that add up to more than 4 MiB decompressed. It warns (without failing) when the firmware with the interface may not fit the app of ESP-IDF's default partition table; on the ESP32-C3 and the ESP32-C6, the LED example no longer fits it, and those chips take the SDK's table. A tabelas.json beside the web/ folder is an error: the database's tables belong to the product (Database).
| Code | What happened |
|---|---|
| 0 | packed |
| 2 | wrong usage, or the folder breaks a rule (path, extension, size, count, absolute path, actions, tabelas.json), or the signing key does not read; nothing was written |
devui publish
Publishes the interface for the product: it becomes the interface of every device of the product, and no board takes it off the air (Change the interface without reflashing the board). It takes the web/ folder (packed on the spot, as pack does) or a bundle.dvu already packed.
python tools/devui.py publish examples/led/web --project-key pk_... --key-file ~/.devui-chave
Besides the options of the key and the address:
| Option | What it does |
|---|---|
--sign-key FILE | the private key that signs the manifest (from devui keygen); without it, the variable DEVUI_SIGN_KEY_FILE; with neither, the publication goes unsigned |
--version V | the interface's version in the signed manifest (default: 0.0.0; up to 64 characters among letters, digits and . + _ -) |
--security-version N | the security version in the signed manifest; only with --sign-key |
--acoes FILE | the named actions, which go in the manifest, signed or not; without it, the acoes.json beside the web/ folder |
The output ends in publicado: hash ... ("published") and, signed, assinada pela chave <fingerprint> ("signed by the key"). Unsigned, the container goes up to 512 KiB; signed, the ceiling is the account's plan's (from 512 KiB in the Free plan to 4 MiB in the Fabricante). The account gets an e-mail at each publication, and each account has 20 publications a day.
| Code | What happened |
|---|---|
| 0 | published |
| 1 | an answer out of the expected (403 from the edge, 404 from a wrong --api, another hash) |
| 2 | wrong usage, or the folder breaks a rule of the packer; nothing was sent |
| 3 | no key (nor OIDC token), or the text is not a key, or the signing key does not read; nothing was sent |
| 4 | key refused: wrong, of another product, expired, revoked or the account suspended; or the OIDC token refused; nothing changed |
| 5 | bundle refused by the cloud: too large, invalid, a signature that does not verify, a locked product with no signature, or a security version below the product's (with the reason); nothing changed |
| 6 | bundle blocked by the administration |
| 7 | the account's publications of the day are over (20 a day), or too many OIDC token exchanges; the message says when to try again |
| 8 | network: no connection, a TLS error or a time out |
| 9 | the cloud is unavailable now; the message says when to try again, if the cloud says |
| 10 | the cloud takes no OIDC token (the OIDC is off in that server); nothing was published |
devui unpublish
Takes the product's publication in force off the air, on every device of the product, as the Despublicar ("Unpublish") button of the product's page does, with the same key (or OIDC) as publish. It takes only the options of the key and the address.
python tools/devui.py unpublish --project-key pk_... --key-file ~/.devui-chave
The output ends in a publicação <hash> saiu de todos os dispositivos do produto ("the publication left every device of the product"). With the product's Interface in the cloud, the tabs have no interface until the next publication; on the device, each board serves its own firmware's again.
| Code | What happened |
|---|---|
| 0 | unpublished |
| 1 | an answer out of the expected (403 from the edge, 404 from a wrong --api, 200 without the retired hash) |
| 2 | wrong usage; nothing was sent |
| 3 | no key (nor OIDC token), or the text is not a key; nothing was sent |
| 4 | key or OIDC token refused; nothing changed |
| 5 | no publication in force, or the product is locked (its signed publication stays), with the reason; nothing changed |
| 7 | too many requests now (429), or too many OIDC token exchanges; the message says when to try again |
| 8 | network: no connection, a TLS error or a time out |
| 9 | the cloud is unavailable now |
| 10 | the cloud takes no OIDC token |
devui tables
Writes (push) or shows (get) the tables of the product's database, with the same key (or OIDC) as publish. The format and what happens when the declaration changes with boards in the field are in Database. Both take only the options of the key and the address; push, also the file.
python tools/devui.py tables push tabelas.json --project-key pk_... --key-file ~/.devui-chave
python tools/devui.py tables get --project-key pk_... --key-file ~/.devui-chave > tabelas.json
push checks the file on your machine, by the cloud's rules, before sending anything, and ends in versão N das tabelas do produto ("version N of the product's tables"). get prints the tables in force in JSON on the standard output, ready for a push, and the count on the standard error. push does not ask before removing a table (and its records, in every account): check the list before sending.
| Code | What happened |
|---|---|
| 0 | written (push) or shown (get) |
| 1 | an answer out of the expected (403 from the edge, 404 from a wrong --api, an answer without the version or the list) |
| 2 | wrong usage, or the file breaks a rule (with the table and the field; the old list of device, "device": [...], comes out showing the new form, {"device": [...], "account": [...]}); nothing was sent |
| 3 | no key (nor OIDC token), or the text is not a key; nothing was sent |
| 4 | key or OIDC token refused; nothing changed |
| 5 | tables refused by the cloud (for example, the type of a field changed), with the reason; nothing changed |
| 7 | too many requests now (429), or too many OIDC token exchanges; the message says when to try again |
| 8 | network: no connection, a TLS error or a time out |
| 9 | the cloud is unavailable now |
| 10 | the cloud takes no OIDC token |
devui firmware
Publishes the product's firmware in the cloud and rolls it out to the boards by OTA, with the same key (or OIDC) as publish and no second factor: the maker's CI publishes and starts a rollout with the key alone. All of them take the options of the key and the address.
python tools/devui.py firmware publish build/termostato.bin --chip esp32s3 --security-version 1 --commit "$GIT_SHA" --notes-file NOTES.txt --project-key pk_...
python tools/devui.py firmware releases --project-key pk_...
python tools/devui.py firmware rollout --release 3 --product --project-key pk_...
python tools/devui.py firmware rollout --release 3 --product --failure-pct 2 --phase-minutes 120 --project-key pk_...
python tools/devui.py firmware rollout --release 3 --devices boards.txt --no-phases --project-key pk_...
python tools/devui.py firmware status --project-key pk_...
python tools/devui.py firmware status <rollout> --project-key pk_...
python tools/devui.py firmware pause|resume|complete|advance <rollout> --project-key pk_...
publish sends the app's raw .bin (ESP-IDF's build/<project>.bin or the Arduino's .bin, never the merged one; at most the SDK's OTA slot, 1.875 MB). The cloud checks the image's header and the chip, demands the security version at the product's floor or above, signs the envelope with the product's firmware key and keeps the next release (the 5 newest stay).
publish option | What it does |
|---|---|
--chip CHIP | the target chip, the HELLO's name (esp32, esp32s3, esp32c3, esp32c6, esp8266...); required |
--version V | the release's version, 1 to 32 bytes; required for the ESP8266 (its image carries no version); on ESP-IDF, when given, it must be the image's |
--security-version N | the release's security version, 0 to 4294967295; without it, the product's floor (the highest already published). Below the floor, the cloud refuses |
--key-id HEX | signs with this firmware key of the product (16 hex): the transition release, after rotating the key, signed by the previous one, which carries the new public key to the boards |
--commit C | the code's commit, kept with the release (up to 64 of [0-9A-Za-z._/-]) |
--notes TEXT | the release notes: plain text, no HTML, up to 2,000 characters and 4,000 bytes of UTF-8, no control character but the line break and the tab. The cloud keeps them with the release (outside the signed envelope: the board does not see them) and shows them in the portal, in the owner's app (when they can postpone) and in the owner's e-mails of the update applied and postponed, always as text. A text starting with - goes as --notes="- ..." |
--notes-file FILE | the notes read from a UTF-8 text file, instead of --notes (not both) |
rollout --release N opens the rollout of a release, one open per product: the whole product (--product, the boards arriving later included), one board (--device ID) or a list (--devices FILE: one id a line, with # comments, up to 1,000; - reads the standard input, though not with --key-file - or --oidc-token-file -).
A list and the product go in phases by default, with nothing asked: 1 % → 10 % → 100 % of the boards, each phase with at least the minimum of new boards. The next phase only opens after the minimum time and the confirmations, and the automatic stop pauses the rollout when, in the open phases, more than the limit of the boards failed or reverted (network failures count too); the product's administrators get an e-mail with the reason and the rate. A single board (--device) never goes in phases.
rollout option | What it does |
|---|---|
--no-phases | the list or the product at once, with no phases (the body carries phased: false) |
--failure-pct P | the automatic stop's limit: more than P % of the boards of the open phases (0 to 100; default 5) |
--failure-min N | the boards the rate needs before it counts and the least each phase adds (1 to 1,000; default 3) |
--phase-minutes M | the minimum time of each phase, in minutes (0 to 10,080, a week; default 60) |
The limits do not go with --no-phases nor with --device (code 2, nothing is sent). An ESP8266 release, which does not go back by itself if the new image fails, only goes to more than one board after it was applied on a pilot board: before that, the cloud answers 409 pilot_required, and the CLI says the way (rollout --release N --device <board>, wait for applied in status, complete that rollout and then start it for the list or the product).
status with no id lists the product's rollouts; with the id, it shows the rollout and the state of every board (every page). The summary says the phase (fase 2 de 3, até 6 placas) and why it is paused: by hand, or by the automatic stop, with how many boards failed or reverted and the limit. pause only stops new offers (a download already taken goes to its end), resume resumes (after the automatic stop too: resuming accepts the failures so far, and the stop applies again to new ones), complete completes it, freeing the product for the next one, and advance opens the next phase by hand, without waiting for the minimum time or the confirmations, for when the boards of the open phase stay off (it goes in the product's log; in the last phase, or with no phases, the cloud answers 409 no_next_phase).
Each command prints the cloud's JSON on the standard output, for the CI to read (the release's number, the rollout's id), and a summary on the standard error. Publishing and moving a rollout want a key created by an administrator of the product (an organization developer's only reads) and a paid plan. Rotating and revoking the firmware key stay in the portal only, with the second factor.
| Code | What happened |
|---|---|
| 0 | done |
| 1 | an answer out of the expected (403 from the edge, 404 from a wrong --api, an answer without the release or the rollout) |
| 2 | wrong usage, or a file that is not an app image (the first byte is not 0xE9), above the ceiling, the ESP8266 with no --version, a bad id in the list; nothing was sent |
| 3 | no key (nor OIDC token), or the text is not a key; nothing was sent |
| 4 | key or OIDC token refused: wrong, of another product, expired, revoked or the account suspended; nothing changed |
| 5 | refused by the cloud, with the reason: an image of another chip, the version missing or different, below the floor, the firmware key revoked or unknown, another rollout open, a release no longer kept, boards of another product, a release or rollout that does not exist, an ESP8266 release with no pilot board, the phases' limits out of range, no phase to advance; nothing changed |
| 7 | too many requests now (429), or too many OIDC token exchanges |
| 8 | network: no connection, a TLS error or a time out |
| 9 | the cloud is unavailable now |
| 10 | the cloud takes no OIDC token |
| 11 | no permission on the product: the key is a developer's (only the administrator publishes and starts a rollout), or the account is on the Grátis; nothing changed |
devui keygen and devui pubkey
python tools/devui.py keygen ~/.devui-assinatura.pem
python tools/devui.py pubkey ~/.devui-assinatura.pem
keygen makes a new Ed25519 signing key in the file (PKCS#8 PEM, the same as openssl genpkey -algorithm ed25519), never over a file that already exists, and leaves it readable only by your user (on Windows too: the command replaces the permissions inherited from the folder by one, yours). Then it shows the fingerprint and the public key, to register in the portal (Desenvolvedor > the product > Chaves de assinatura, "Signing keys"). pubkey shows again the fingerprint and the public key of a key that already exists. The private key never goes to the cloud (Signed interface).
| Code | What happened |
|---|---|
| 0 | done |
| 2 | wrong usage, the file already exists, or it could not be made readable by you alone (nothing was written) |
| 3 | pubkey: the file is not a signing key that reads |
The environment variables
| Variable | Instead of |
|---|---|
DEVUI_PUBLISH_KEY | --key-file |
DEVUI_SIGN_KEY_FILE | publish's --sign-key |
DEVUI_OIDC_TOKEN | --oidc-token-file |
DEVUI_OIDC_AUDIENCE | --oidc-audience |
