Skip to content
ThingFace

From zero to the LED on the page

This guide takes you from an ESP32 board in its box to an LED that lights up from a page in the cloud, with the SDK's ready-made example (examples/led). No code to write: you install ESP-IDF, flash the board, give it the Wi-Fi over USB, pair the board with your account in the portal and click the button on its page.

How long: with ESP-IDF already installed, the target is to reach the LED in up to 15 minutes. Installing ESP-IDF from scratch takes longer, and the time depends on your internet: see step 1.

The portal's buttons and the board's log are quoted here as they appear in Portuguese; the portal in English shows its own labels in the same places.

Today (a closed beta, by invitation), this guide needs an invite and an environment sheet. Until the service opens to the public, whoever follows this guide gets by e-mail the invite to create the account (step 8) and a sheet with three items: the portal's address, the gateway's address and port, and a roots file (.pem). Step 4 says where each one goes. Without the sheet, the board has nothing to connect to; without the invite, the portal does not open the sign-up.

What you need

  • A board with an ESP32, ESP32-S3, ESP32-C3 or ESP32-C6. The example lights the LED the board already has:

    ChipBoardLEDDefault pin
    ESP32ESP32-DevKitC and clonesplain LEDGPIO 2 (the original DevKitC has no user LED: see the end of step 9)
    ESP32-S3ESP32-S3-DevKitC-1addressable RGBGPIO 48 (v1.0) or 38 (v1.1)
    ESP32-C3ESP32-C3-DevKitM-1addressable RGBGPIO 8
    ESP32-C6ESP32-C6-DevKitC-1addressable RGBGPIO 8

    The board needs a flash of 4 MB or more (the DevKits above have it).

  • A USB data cable (a charge-only cable does not show up as a serial port).
  • A computer with Windows, Linux or macOS and about 5 GB free for ESP-IDF (for the ESP32 alone it took 4.5 GB: 2.2 GB of code and 2.3 GB of tools).
  • A 2.4 GHz Wi-Fi network with internet, and its password. The ESP32 does not see 5 GHz networks.
  • The e-mail that got the invite, open now: the sign-up starts from the invite's link, and the account is confirmed by another link, which comes to the same address.

1. Install ESP-IDF 5.5.5

The SDK is tested with ESP-IDF 5.5.5. Another version may compile, but it is not the one the SDK vouches for.

Windows: use Espressif's official installer and pick version v5.5.5 (https://docs.espressif.com/projects/esp-idf/en/v5.5.5/esp32/get-started/windows-setup.html). It creates in the Start menu an ESP-IDF terminal shortcut (PowerShell or CMD) that already loads the environment: every command of this guide runs in that terminal.

Linux, macOS or Windows without the installer: with git and Python 3 installed (on Linux, also the packages of Espressif's prerequisites page), in a folder with a short path and no spaces (on Windows, for example C:\esp: in a long path, cloning a submodule fails with '$GIT_DIR' too big),

git clone -b v5.5.5 --recursive --depth 1 --shallow-submodules https://github.com/espressif/esp-idf.git esp-idf-v5.5.5
cd esp-idf-v5.5.5
./install.sh esp32          # on Windows (PowerShell): .\install.ps1 esp32

Replace esp32 with your chip (esp32s3, esp32c3, esp32c6) or pass several separated by commas. Then, in every new terminal, load the environment:

. ./export.sh               # on Windows (PowerShell): . .\export.ps1

On a Windows PC with fast internet (15/10/2026), the git clone took 1 min 45 s and install.ps1 esp32, 1 min 14 s; on a slower connection, expect more.

Check: idf.py --version answers ESP-IDF v5.5.5. If it answers another version, another ESP-IDF is loaded in this terminal: open a new terminal and load the export of the right folder. Before the version, the lines fatal: No names found, cannot describe anything. and WARNING: Git version unavailable may come: they are from the clone without history and do no harm.

2. Get the example

cd thingface-sdk/examples/led

Every command from here on runs inside examples/led, in the terminal with ESP-IDF loaded.

Until the SDK is published, it comes with your beta invitation.

In a project of your own, without cloning the SDK: the SDK is also an ESP-IDF component, thingface/devui (the ESP Component Registry's package; the examples do not come in it, which is why this guide clones the repository). Once it is published in the Registry, idf.py add-dependency "thingface/devui", in the project's folder, adds it to main/idf_component.yml; until then, with the package's archive (devui_<version>.tgz) unpacked in a folder, the thingface/devui dependency of main/idf_component.yml points to it with override_path. Either way, the project needs, as this example's sdkconfig.defaults has, the development profile (CONFIG_DEVUI_TRUST_DEV=y) and the SDK's partition table (the component's partitions.csv).

3. Find the board's serial port

Plug the board into USB.

  • Windows: Device Manager, under "Ports (COM & LPT)" ("Portas (COM e LPT)" on a Windows in Portuguese): the board shows up as COM<n> (a "Silicon Labs CP210x" or "USB-SERIAL CH340/CH9102" bridge or, on the S3, C3 and C6 through the native USB, "USB Serial Device", which a Windows in Portuguese calls "Dispositivo serial USB"). If it shows a yellow warning, the bridge's driver (CP210x or CH340) is missing: Windows Update usually has it.
  • Linux: /dev/ttyUSB0 or /dev/ttyACM0 (the user must be in the dialout group).
  • macOS: /dev/cu.usbserial-*, /dev/cu.wchusbserial-* or /dev/cu.usbmodem*.

In the commands below, replace PORT with it. Unplugged and plugged it again? The port's number may change.

4. Point the example at the sheet's environment

If the sheet says gw.thingface.com, port 443, skip this step: since 16/10 it is the example's default gateway, whose staging roots already come in the SDK. The two files below are for another gateway. Without sdkconfig.local, drop the ;sdkconfig.local from the command of step 5: ESP-IDF stops when a file of that list does not exist.

Create, inside examples/led, a file named sdkconfig.local with the sheet's gateway (a name or an IP), written exactly as it is there (it is what the gateway's certificate carries):

CONFIG_EXAMPLE_GATEWAY_HOST="the-sheet's-gateway-address"
CONFIG_EXAMPLE_GATEWAY_PORT=the-sheet's-port

Create it in a text editor (Notepad, VS Code) and save it as UTF-8: in Windows PowerShell 5.1, echo ... > sdkconfig.local writes UTF-16, which ESP-IDF does not read. Git ignores this file.

Then copy the sheet's roots file to main/ca.pem (the name must be this one; the command works in PowerShell and in Linux/macOS):

cp path/to/the-sheet's-file.pem main/ca.pem

Without it, the board trusts only the staging roots that come in the SDK (the example is a development build) and refuses the sheet's gateway with a certificate error: the certificate check is never turned off.

The Wi-Fi does not go here: the board gets the network over USB in step 7 and keeps it.

5. Build

Pick your chip's line. The command is long, but it is one: it creates the folder build/<chip> with the example's configuration plus your sdkconfig.local (if you skipped step 4, without the ;sdkconfig.local).

idf.py -B build/esp32 -D IDF_TARGET=esp32 -D SDKCONFIG=build/esp32/sdkconfig -D "SDKCONFIG_DEFAULTS=sdkconfig.defaults;sdkconfig.local" build

For another chip, replace the three occurrences of esp32 with esp32s3, esp32c3 or esp32c6. On the S3-DevKitC-1 v1.1 (LED on GPIO 38), use "SDKCONFIG_DEFAULTS=sdkconfig.defaults;sdkconfig.local;sdkconfig.led38".

In the middle of the output comes the line devui: confiança dev: N raiz(es) ... O=... STAGING ...; M chave(s) de ordens .... It counts only the roots the SDK compiles in the development profile (the staging ones), not those of the main/ca.pem of step 4: those go into the firmware apart, and the board uses only them when the file is not empty. With the sheet's ca.pem, the line still names STAGING, and that is right.

The first build downloads two components from the ESP Component Registry and takes a few minutes. It ends with Project build complete and suggests idf.py flash: do not use that suggestion, use the command of step 6, which carries the -B build/<chip>.

Changed sdkconfig.local afterwards? Delete the folder build/<chip> and build again: the configuration is only read when the folder is created.

6. Flash

idf.py -B build/esp32 -p PORT erase-flash flash

erase-flash erases what the board had before (another firmware, another identity, another Wi-Fi network): use it on the first flash. To flash again after the pairing, drop erase-flash, or the board becomes a new device again, with no owner and no Wi-Fi.

The board's identity lives in the devui partition of the SDK's partition table, at 0x3D0000, after the apps, out of reach of any app flash: the same table serves ESP-IDF, Rust and Arduino (IDE, arduino-cli and PlatformIO). Only an erase-flash (or the Arduino IDE's "Erase All Flash") erases it and, in a sketch flashed with the core's default table, formatting its SPIFFS or LittleFS. Flashing a sketch with the core's default table does not erase the identity, but the SDK does not see it and creates another; flashing again with the SDK's table, without erasing the flash, brings the old one back. In the Arduino IDE, the SDK's table comes in the partitions.csv of each library example's folder (in a sketch of your own, copy that file into its folder) and needs the scheme Tools > Partition Scheme > "Minimal SPIFFS (1.9MB APP with OTA/128KB SPIFFS)", which gives the app the slot's limit (1,966,080 B; in the default scheme the IDE stops at 1,310,720 B). Without the devui partition in the table, the library warns on the serial at every boot. The details, and PlatformIO and arduino-cli: the SDK's README.md, Arduino section.

A board flashed with the old table (from before 15/10/2026, with the devui at 0x12000): in the field, it goes on by OTA with no erase and with the same identity (the SDK finds the devui by name, in the table on the board). Over USB, the new table writes the app over the old devui, and the board gets a new identity: flash with the erase-flash above, give the Wi-Fi and pair again (steps 7 and 8); the old device stays in the account until you unlink it in Dispositivos (the three-dot menu of its card, Desvincular, "Unlink").

It ends with Hard resetting via RTS pin..., and the LED blinks 3 times. If flashing stops at Failed to connect ... No serial data received, hold the board's BOOT button while the command connects.

Until step 7 the board has no network: its log shows sem rede: nem no menuconfig, nem gravada; mande uma pelo Improv and errors connecting to the gateway (Host is unreachable). That is expected; go on to step 7.

Over the same USB, with your network's name and password (in single quotes, which work in PowerShell and in Linux/macOS):

python ../../tools/improv_cli.py PORT wifi 'network-name' 'network-password'

The command speaks Improv Serial with the board and shows its log (the log: lines) while it waits. In a few seconds, it joins the network, talks to the cloud and answers with the pairing link. Among many Wi-Fi lines, these show up (the numbers change, and the link's address is your sheet's portal):

erro: nenhum
estado: provisionando
log: I (...) wifi: IP 192.168.0.57
estado: provisionado
log: I (...) led: ou abra https://app.thingface.com/parear?c=K7Q2M9XD
url: https://app.thingface.com/parear?c=K7Q2M9XD

Before the IP line, connection errors may come (connect() error: Host is unreachable, esp_transport_connect() failed, conexão fechada, código 0): it is the board trying the cloud before it has a network. It tries again by itself when the IP comes, and nothing needs to be done.

erro: nenhum only says the board accepted the request. Keep the code and the link (url:). The board keeps the network: if it reboots, it goes back to the same network by itself, and if the network drops, it tries again by itself, with waits that grow up to 30 s.

Right after, once the cloud confirms it has the code, the serial also shows the line devui: pair code K7Q2-M9XD ttl=598 (below); the tool has already finished, and it shows up in the monitor (idf.py -p PORT monitor).

The code is valid for 10 minutes (the line's ttl says how much is left), and the board swaps it for a new one by itself before it expires. Past that time, or lost the link? Ask for the current one (the board is already on the network, nothing is flashed again):

python ../../tools/improv_cli.py PORT state

The tool needs pyserial, which already comes with ESP-IDF. It does not reset the board.

The code's line on the serial

The SDK, not the example, puts the pairing code on the serial in a line of fixed format:

I (7330) devui: pair code K7Q2-M9XD ttl=598     ESP-IDF and Rust: the ESP-IDF log, level INFO, tag devui
devui: pair code K7Q2-M9XD ttl=598              Arduino (ESP32 and ESP8266): the DevUI library, on Serial
  • Format: pair code , the code with the display's hyphen (two groups of 4 characters of Crockford base32, in upper case), ttl= and the seconds the code is still valid, in decimal. The portal reads the line from the USB (Web Serial) with the expression pair code ([0-9A-Z]{4})-([0-9A-Z]{4}) ttl=(\d+): it is a contract, and it does not change without a new portal that reads both.
  • When it comes out: only for a code that is valid in the cloud, once per code, after the SDK sent it to the cloud with the connection ready and no owner: the moment the cloud confirms that code (the protocol's CODE_ACK, since 25/10). With a cloud before CODE_ACK, which never sends it, it comes out 5 s after the send, if the cloud did not refuse it in that time; after the boot's first CODE_ACK that wait is off, and a code the cloud did not confirm (one it did not keep, such as the same code on another device) gets no line. That holds for the new code, the one renewed before it expires and the earlier boot's code that comes back from the NVS after a reboot; the ttl is what the code still has at that moment. A reconnection that only sends the same code again does not repeat the line.
  • When it does not: with an owner (devui_pair_begin refuses and there is no code), never with an empty or invalid code, and not for a code the cloud does not have yet: one asked for offline only gets its line once it reaches the cloud; refused with 4429 (more than one code a minute), the line waits for the resend. The DEVUI_EV_PAIR_CODE event and Improv do not wait: the app gets each code at once. DEVUI_EV_PAIR_CODE_ACCEPTED comes at each send and resend the cloud confirms (the line, once per code, comes at the first of those confirmations); with a cloud before CODE_ACK, the line comes by the 5 s wait and the event does not.
  • Log level: on ESP-IDF the line goes through the ESP_LOGI of the tag devui. A firmware that lowers the log below INFO (CONFIG_LOG_DEFAULT_LEVEL, or esp_log_level_set("devui", ...)) drops the line with it: the SDK does not write to the serial outside the log, which the firmware may have silenced because it uses the UART for something else. Then the code only comes out through Improv, when the firmware has it, or on the product's display.
  • Arduino without the Serial: the library opens Serial at 115200 when the sketch has not, and writes the line there. On a board whose UART0 TX pin drives something else (a relay, for example), build with -D DEVUI_ARDUINO_SERIAL=0 (on PlatformIO, in build_flags): the SDK neither opens nor writes to the Serial, and the line does not come out. The code still reaches the app through DEVUI_EV_PAIR_CODE, for the product's display (The Arduino library).
  • The Portuguese text of the examples (código de pareamento: ... (vale N s)) is gone; the portal reads it only while there are boards with an earlier firmware.

8. Create the account and pair

  1. Open the e-mail Convite para criar sua conta ("Invite to create your account") and click Criar a conta ("Create the account"): the link opens the sign-up in the sheet's portal. In the closed beta, the sign-up opens only through that link; the login screen's Ainda não tem conta? Crie uma ("No account yet? Create one") leads only to the notice Cadastro por convite ("Sign-up by invite"). Type the e-mail that got the invite (it is valid for that address only) and a password of at least 8 characters (a sentence will do; a password found in known leaks is refused). Tick Declaro que tenho 18 anos ou mais ("I declare I am 18 or older") and, if it shows, the box accepting the terms of use and the privacy notice. If Cloudflare's anti-bot check shows above the button, it usually solves itself; if it asks for a click, click it. Click Criar conta ("Create account"): the screen turns into Confira seu e-mail ("Check your e-mail").
  2. Open the e-mail Confirme seu e-mail ("Confirm your e-mail") and click the link (Confirmar e-mail, "Confirm e-mail"). On the page that opens, type the password again and click Confirmar e entrar ("Confirm and sign in"). If the portal offers a passkey, Agora não ("Not now") will do.
  3. Open the link of step 7. The portal shows the link's code and asks you to tick O meu dispositivo mostra este mesmo código ("My device shows this same code"): compare it with the devui: pair code line of step 7 and click Continuar ("Continue").

    You can also go to Dispositivos ("Devices"), click the + button on the list's lower right corner (its name, for screen readers, is Parear um dispositivo, "Pair a device"; with an empty list, there is also Parear com o código, "Pair with the code") and type the code (with or without the hyphen).

  4. The confirmation shows what the board declares about itself and the account that will receive it. The example declares no product nor project key, so those two show as "não informado" ("not given"), and the SDK's version shows as the one of the SDK you built (0.1.0 or newer; The SDK's versions). Give it a name (for example, "Desk LED") and click Parear ("Pair"). If the portal opens Confirme que é você ("Confirm it is you"), type the account's password (and, if it has the authenticator app on, its code) and click Confirmar ("Confirm"): pairing is a security action, and the portal asks for the password again when the sign-in is not recent.

Done, the board is yours. To follow its log from here on, open the monitor (to leave it, Ctrl+]):

idf.py -B build/esp32 -p PORT monitor

The monitor resets the board when it opens; it comes back to the network and to the cloud by itself and logs pareamento: a placa já tem dono.

9. Open the page and light the LED

  1. In Dispositivos (the screen that opens when you sign in to the portal), the board shows up in a card with the name you gave it. Right after the pairing it may show as Offline for a few seconds, while it reconnects: reload the page until you see Online. Click the board's name.
  2. The device's page shows, in a frame, the interface that came flashed in the firmware: the line LED: apagado online (the LED's state and the connection's) and the Alternar ("Toggle") button. The frame's other lines (Marcado como estado, Pergunta ao dispositivo) are the example's test and can be ignored.
  3. Click Alternar. Next to the button, feito ("done") shows up when the board confirms, and right after the line turns into LED: aceso; the LED lights up, and the monitor logs led: LED aceso pela página. Click again to turn it off.

Done: from zero to the LED on the page.

If your board has no LED on the example's pin (the original ESP32-DevKitC has none), the proof is on the page and in the monitor's LED aceso pela página line. To use another pin, run idf.py -B build/esp32 menuconfig, change "devui LED example", "LED GPIO", and flash again without erase-flash.

10. Change the interface without reflashing the board (optional)

The interface the page shows is the folder examples/led/web flashed in the firmware. To change it without flashing the board again, the SDK's CLI (tools/devui.py, Python only, nothing to install) packs the folder and publishes it for the product: it becomes the interface of every device of the product, and no board takes it off the air.

The product has the Interface setting, on its page: na nuvem ("in the cloud", a new product's) or no dispositivo ("on the device"). In the cloud, the tabs get only the product's publication, and the interface flashed in the firmware is not used: when the board announces it, the cloud refuses it (the serial shows bundle REJECT, REFUSAL 4: the product serves its interface from the cloud...), and the board stays connected, with state, actions and database. So, once the board is tied to the product in step 1, its page shows "sem interface" ("no interface") until the first publication, in step 3. On the device, each board serves the interface it carries while the product has no publication; with a publication, the tabs get the publication.

  1. In the portal, open the account's menu (the Minha conta, "My account", button on the upper right corner) and click Desenvolvedor ("Developer"). In the Área do desenvolvedor ("Developer area"), create a product (Criar produto, "Create product") and copy its project_key (pk_...). Put it in the example with idf.py -B build/esp32 menuconfig, "devui LED example", "EXAMPLE_PROJECT_KEY", and flash again (steps 5 and 6, without erase-flash): the board becomes this product's.
  2. On the product's page, under Chaves de publicação ("Publishing keys"), click Criar chave ("Create key") and copy the key: it shows only once. Creating a key needs a second factor on the account (an authenticator app or a passkey), which is turned on in the Minha conta screen, from the same menu. Keep the key in a file of your own, for example ~/.devui-chave. It never goes on the command line, because there any user of the machine sees it in the process list.
  3. Change something in examples/led/web/index.html and publish, from the SDK's root:

    python tools/devui.py publish examples/led/web --project-key pk_... --key-file ~/.devui-chave

    In a CI, the key comes from the variable DEVUI_PUBLISH_KEY (the CI's secret), and --key-file leaves the command.

  4. The output ends in publicado: hash .... The frame of the board's page reloads with the new interface, and the bar shows "publicada pela CLI" ("published by the CLI"). The account gets an e-mail at each publication.

To go back to the firmware's interface, set the product's Interface to no dispositivo and unpublish, on the product's page or with the CLI (see Unpublishing): flashing a firmware with another web/ folder no longer takes the publication off the air.

Firmware without an interface

In a product with its interface in the cloud, the firmware's web/ folder only spends flash: the cloud never uses it. Built without it, the firmware announces no interface (the HELLO goes without the bundle's hash), nothing is refused, and the tabs get the product's publication. On ESP-IDF, take devui_add_bundle(web) out of main/CMakeLists.txt (DEVUI_CONFIG_DEFAULT() stays the same: with no bundle in the build, the SDK starts without one); that is how examples/banco already is. On Arduino, call DevUI.begin with an empty DevUIBundle, {nullptr, 0, nullptr, 0, nullptr}, as ChamarOutro does (or with a devui_config_t with no bundle); with no web/ folder, there is no devui_bundle.h to include.

With no web/ folder, the board has no interface on the local network either: the local mode serves the firmware's bundle, never the product's publication. Whoever uses the local mode in a product with its interface in the cloud flashes the web/ folder in the firmware all the same; the cloud refuses it (the REFUSAL 4), and only the local network uses it.

python tools/devui.py pack examples/led/web out/ only packs (it is devui_pack.py, with the same options), and publish also takes the out/bundle.dvu made that way. The default address is the production cloud's (https://api.thingface.com); --api points to another, such as the test environment's sheet.

Signed interface

With a signing key, the interface reaches the boards with the seal "signed": the cloud checks that it came from you and that no byte changed afterwards.

  1. Make the key once: python tools/devui.py keygen ~/.devui-assinatura.pem. The file is the private key, stays on your machine only (or in the CI's secret) and never goes to the cloud; only your user reads the file (on Windows too: the command replaces the permissions inherited from the folder by one, yours); the command shows the public key and its fingerprint.
  2. In the portal, in Developer > the product > Signing keys, register the public key (it asks for the second factor).
  3. Publish signing:

    python tools/devui.py publish examples/led/web --project-key pk_... --key-file ~/.devui-chave \
        --sign-key ~/.devui-assinatura.pem --version 1.0.0

    In a CI, the file's path comes from the variable DEVUI_SIGN_KEY_FILE. The output ends in ..., assinada pela chave <fingerprint>. A key revoked in the portal, or a bundle changed after signing, is refused (code 5, with the reason), and nothing changes in the cloud. Without --sign-key, the publication goes unsigned, as before.

Each outcome of publish has a code, so a CI decides without reading the message (those of each command, with unpublish and tables, are in the CLI reference):

CodeWhat happened
0published
1an answer out of the expected (403 from the edge, 404 from a wrong --api, another hash)
2wrong usage, or the folder breaks a rule of the packer; nothing was sent
3no key (nor OIDC token), or the text is not a key; nothing was sent
4key refused: wrong, of another product, expired, revoked or the account suspended; or the OIDC token refused; nothing changed
5bundle refused by the cloud (too large or invalid, with the reason)
6bundle blocked by the administration
7the account's publications of the day are over (20 a day), or too many OIDC token exchanges; the message says when to try again
8network: no connection, a TLS error or a time out
9the cloud is unavailable now; the message says when to try again, if the cloud says
10the cloud takes no OIDC token (the OIDC is off in that server); nothing was published

Publishing from the CI with no key kept (OIDC)

In a CI, the key does not need to be kept as a secret: with no key (neither --key-file nor DEVUI_PUBLISH_KEY), publish takes the CI's own OIDC token and exchanges it in the cloud for a credential of 15 minutes, which only publishes in that product. Neither token nor the credential shows in the output.

Today this depends on the cloud taking the token's issuer: production takes none yet. Until then the exchange answers 404, the CLI exits with code 10, and publishing from the CI uses the key.

  1. On the product's page, under Publicação pelo CI, sem chave guardada (OIDC) ("Publishing from the CI, with no key kept"), authorize the repository: the repository (owner/repository), the branch (for example main) and the repository's id (its number on GitHub, which does not repeat if someone deletes the repository and creates another with the same name). The event (push) and the workflow are optional, but recommended: without them, an event such as pull_request_target, which runs with the base repository's branch, also publishes.
  2. In the GitHub Actions workflow, give the job id-token: write and run publish with no key:

    on:
      push:
        branches: [main]
    permissions:
      contents: read
      id-token: write   # the job's OIDC token; without it, there is no token
    jobs:
      publish:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - run: python thingface-sdk/tools/devui.py publish web --project-key pk_...

    The example assumes the SDK inside the repository, in thingface-sdk/. The CLI asks GitHub for the token with the audience https://api.thingface.com, which the production cloud requires; --oidc-audience (or DEVUI_OIDC_AUDIENCE) changes the audience, for a server with another one, such as the test environment's.

Another CI, once the cloud takes its issuer, hands the ready token in the variable DEVUI_OIDC_TOKEN (on GitLab, through id_tokens) or in a file named by --oidc-token-file; like the key, the token never goes on the command line. If the cloud refuses the token (code 4), check on the product's page the repository, the branch and the repository's id: it is what most often does not match.

Unpublishing

The publication leaves every device of the product through the button on the product's page or, with the same key as publish (or the CI's OIDC), through the CLI:

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 Interface in the cloud, the tabs switch at once to "sem interface" ("no interface") until the next publication; on the device, each board serves its own firmware's again. A product with no publication in force, or a locked one (its signed publication stays), exits with code 5 and the reason, and nothing changes.

The database's tables

The tables of a product's simple database belong to the product too, not to the firmware: they are declared on the product's page, tab Banco de dados ("Database"), or with python tools/devui.py tables push tabelas.json --project-key pk_... --key-file ~/.devui-chave (and tables get prints the ones in force). The format, the types, what happens when a field or a table is removed and the board's API are in Database. A tabelas.json beside web/ makes devui pack exit with an error.

Going further

When something does not go as here

What shows upWhat to do
No new port when plugging the boardChange the cable (a charge-only cable will not do) and install the USB bridge's driver (CP210x or CH340).
Failed to connect ... No serial data receivedHold BOOT while idf.py connects; close another program that has the port open (the monitor, Arduino).
could not open port or sem resposta no prazo in improv_cli.pyClose the monitor (Ctrl+]) or another program with the port open, check the PORT and run it again.
erro: sem conexão in improv_cli.pyA wrong password or a 5 GHz network: run step 7 again with the right network and password. Nothing needs to be flashed again.
url: (nenhuma)The board joined the network but has not talked to the cloud yet. Wait a few seconds and run step 7's state; if it goes on, see the line below.
sem raízes de confiança or a certificate error in the logmain/ca.pem is missing or empty, or the gateway's address is not the sheet's (step 4). Fix it, delete build/<chip> and repeat steps 5 and 6.
wifi: sem rede (motivo ...): nova tentativa em ... ms, repeatedThe network dropped or its password changed. The board tries by itself; if the password changed, give the new one through step 7.
The portal says the code is invalid or expiredRun step 7's state and use the code and link it gives: the previous code stops being valid when a new one comes.
Cadastro por convite ("Sign-up by invite"), with no formThe sign-up opens only through the link of the invite's e-mail (step 8.1).
Confirme seu e-mail antes de parear ("Confirm your e-mail before pairing")Open the link of the e-mail of step 8.2 (look in the spam folder).
pareamento: a placa já tem dono and no codeThe board was paired before. Unlink it in Dispositivos (the three-dot menu of its card, Desvincular), or flash again with erase-flash (step 6) and repeat step 7.
The frame says the interface did not answerDo what it asks (clear the content site's data in the browser) and click Recarregar ("Reload").
The Alternar button stays greyThe board is offline: check in the monitor whether it has no network.