Pular para o conteúdo
ThingFace

Do zero ao LED na página

Este guia leva você de uma placa ESP32 na caixa até um LED que acende por uma página na nuvem, com o exemplo pronto do SDK (examples/led). Não é preciso escrever código: você instala o ESP-IDF, grava a placa, passa o Wi-Fi para ela pela USB, pareia a placa com a sua conta no portal e clica no botão da página dela.

Quanto tempo: com o ESP-IDF já instalado, a meta é chegar ao LED em até 15 minutos. Instalar o ESP-IDF do zero leva mais, e o tempo depende da sua internet: veja o passo 1.

Hoje (beta fechado, por convite), este guia pede um convite e uma ficha do ambiente. Até o serviço abrir ao público, quem segue este guia recebe por e-mail o convite para criar a conta (passo 8) e uma ficha com três itens: o endereço do portal, o endereço e a porta do gateway, e um arquivo de raízes (.pem). O passo 4 diz onde cada um entra. Sem a ficha, a placa não tem a que se conectar; sem o convite, o portal não abre o cadastro.

O que você precisa

  • Uma placa com ESP32, ESP32-S3, ESP32-C3 ou ESP32-C6. O exemplo acende o LED que a placa já tem:

    ChipPlacaLEDPino padrão
    ESP32ESP32-DevKitC e clonesLED simplesGPIO 2 (a DevKitC original não tem LED de usuário: veja o fim do passo 9)
    ESP32-S3ESP32-S3-DevKitC-1RGB endereçávelGPIO 48 (v1.0) ou 38 (v1.1)
    ESP32-C3ESP32-C3-DevKitM-1RGB endereçávelGPIO 8
    ESP32-C6ESP32-C6-DevKitC-1RGB endereçávelGPIO 8

    A placa precisa de flash de 4 MB ou mais (as DevKits acima têm).

  • Um cabo USB de dados (cabo só de carga não aparece como porta serial).
  • Um computador com Windows, Linux ou macOS e uns 5 GB livres para o ESP-IDF (só para o ESP32, foram 4,5 GB: 2,2 GB do código e 2,3 GB das ferramentas).
  • Uma rede Wi-Fi de 2,4 GHz com internet, e a senha dela. O ESP32 não enxerga redes de 5 GHz.
  • O e-mail que recebeu o convite, aberto agora: o cadastro começa pelo link do convite, e a conta é confirmada por outro link, que chega no mesmo endereço.

1. Instalar o ESP-IDF 5.5.5

O SDK é testado com o ESP-IDF 5.5.5. Outra versão pode até compilar, mas não é a que o SDK garante.

Windows: use o instalador oficial da Espressif e escolha a versão v5.5.5 (https://docs.espressif.com/projects/esp-idf/en/v5.5.5/esp32/get-started/windows-setup.html). Ele cria no menu Iniciar um atalho de terminal do ESP-IDF (PowerShell ou CMD) que já carrega o ambiente: todos os comandos deste guia rodam nesse terminal.

Linux, macOS ou Windows sem o instalador: com git e Python 3 instalados (no Linux, também os pacotes da página de pré-requisitos da Espressif), numa pasta de caminho curto e sem espaços (no Windows, por exemplo C:\esp: num caminho longo, o clone de um submódulo falha com '$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          # no Windows (PowerShell): .\install.ps1 esp32

Troque esp32 pelo seu chip (esp32s3, esp32c3, esp32c6) ou passe vários separados por vírgula. Depois, em todo terminal novo, carregue o ambiente:

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

Num PC com Windows e internet rápida (15/10/2026), o git clone levou 1 min 45 s e o install.ps1 esp32, 1 min 14 s; numa conexão mais lenta, conte com mais.

Confira: idf.py --version responde ESP-IDF v5.5.5. Se responder outra versão, outro ESP-IDF está carregado neste terminal: abra um terminal novo e carregue o export da pasta certa. Antes da versão podem vir as linhas fatal: No names found, cannot describe anything. e WARNING: Git version unavailable: são do clone sem histórico e não atrapalham nada.

2. Pegar o exemplo

cd thingface-sdk/examples/led

Todos os comandos daqui em diante rodam dentro de examples/led, no terminal com o ESP-IDF carregado.

Enquanto o SDK não é publicado, ele chega junto com o convite do teste.

Num projeto seu, sem clonar o SDK: o SDK também é um componente do ESP-IDF, thingface/devui (o pacote do ESP Component Registry; os exemplos não vêm nele, por isso este guia clona o repositório). Depois da publicação no Registry, idf.py add-dependency "thingface/devui", na pasta do projeto, o acrescenta ao main/idf_component.yml; até lá, com o arquivo do pacote (devui_<versão>.tgz) desempacotado numa pasta, a dependência thingface/devui do main/idf_component.yml aponta para ela com override_path. Nos dois casos, o projeto precisa, como o sdkconfig.defaults deste exemplo, do perfil de desenvolvimento (CONFIG_DEVUI_TRUST_DEV=y) e da tabela de partições do SDK (o partitions.csv do componente).

3. Achar a porta serial da placa

Ligue a placa no USB.

  • Windows: Gerenciador de Dispositivos, em "Portas (COM e LPT)" ("Ports (COM & LPT)" no Windows em inglês): a placa aparece como COM<n> (ponte "Silicon Labs CP210x", "USB-SERIAL CH340/CH9102" ou, no S3, C3 e C6 pela USB nativa, "Dispositivo serial USB", que no Windows em inglês se chama "USB Serial Device"). Se aparecer com um aviso amarelo, falta o driver da ponte (CP210x ou CH340): o Windows Update costuma ter.
  • Linux: /dev/ttyUSB0 ou /dev/ttyACM0 (o usuário precisa estar no grupo dialout).
  • macOS: /dev/cu.usbserial-*, /dev/cu.wchusbserial-* ou /dev/cu.usbmodem*.

Nos comandos a seguir, troque PORTA por ela. Desligou e ligou de novo? O número da porta pode mudar.

4. Apontar o exemplo para o ambiente da ficha

Se a ficha disser gw.thingface.com, porta 443, pule este passo: desde 16/10 é o gateway padrão do exemplo, que já traz as raízes de staging dele no SDK. Os dois arquivos abaixo servem a outro gateway. Sem o sdkconfig.local, tire o ;sdkconfig.local do comando do passo 5: o ESP-IDF para quando um arquivo dessa lista não existe.

Crie, dentro de examples/led, um arquivo chamado sdkconfig.local com o gateway da ficha (um nome ou um IP), escrito exatamente como está nela (é o que o certificado do gateway traz):

CONFIG_EXAMPLE_GATEWAY_HOST="endereço-do-gateway-da-ficha"
CONFIG_EXAMPLE_GATEWAY_PORT=porta-da-ficha

Crie-o num editor de texto (Bloco de Notas, VS Code) e salve como UTF-8: no Windows PowerShell 5.1, o echo ... > sdkconfig.local grava em UTF-16, que o ESP-IDF não lê. O git ignora esse arquivo.

Depois, copie o arquivo de raízes da ficha para main/ca.pem (o nome tem de ser esse; o comando vale no PowerShell e no Linux/macOS):

cp caminho/do/arquivo-da-ficha.pem main/ca.pem

Sem ele, a placa confia só nas raízes de staging que vêm no SDK (o exemplo é um build de desenvolvimento) e recusa o gateway da ficha com erro de certificado: a verificação do certificado nunca é desligada.

O Wi-Fi não entra aqui: a placa recebe a rede pela USB no passo 7 e a guarda.

5. Compilar

Escolha a linha do seu chip. O comando é longo, mas é um só: ele cria a pasta build/<chip> com a configuração do exemplo mais o seu sdkconfig.local (se pulou o passo 4, sem o ;sdkconfig.local).

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

Para outro chip, troque as três ocorrências de esp32 por esp32s3, esp32c3 ou esp32c6. Na S3-DevKitC-1 v1.1 (LED no GPIO 38), use "SDKCONFIG_DEFAULTS=sdkconfig.defaults;sdkconfig.local;sdkconfig.led38".

No meio da saída aparece a linha devui: confiança dev: N raiz(es) ... O=... STAGING ...; M chave(s) de ordens .... Ela conta só as raízes que o SDK compila no perfil de desenvolvimento (as de staging), não as do main/ca.pem do passo 4: essas vão para o firmware à parte, e a placa usa só elas quando o arquivo não está vazio. Com o ca.pem da ficha, a linha continua citando STAGING, e está certo.

A primeira compilação baixa dois componentes do ESP Component Registry e leva alguns minutos. Termina com Project build complete e sugere idf.py flash: não use essa sugestão, use o comando do passo 6, que leva o -B build/<chip>.

Mudou o sdkconfig.local depois? Apague a pasta build/<chip> e compile de novo: a configuração só é lida quando a pasta é criada.

6. Gravar

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

O erase-flash apaga o que a placa tinha antes (outro firmware, outra identidade, outra rede Wi-Fi): use-o na primeira gravação. Para gravar de novo depois do pareamento, tire o erase-flash, ou a placa volta a ser um dispositivo novo, sem dono e sem Wi-Fi.

A identidade da placa fica na partição devui da tabela de partições do SDK, em 0x3D0000, depois dos apps, fora do alcance de qualquer gravação de app: a mesma tabela serve ao ESP-IDF, ao Rust e ao Arduino (IDE, arduino-cli e PlatformIO). Só a apagam um erase-flash (ou o "Erase All Flash" do Arduino IDE) e, num sketch gravado com a tabela padrão do core, formatar o SPIFFS ou o LittleFS dela. Gravar um sketch com a tabela padrão do core não apaga a identidade, mas o SDK não a enxerga e cria outra; gravar de novo com a tabela do SDK, sem apagar a flash, traz a de antes de volta. No Arduino IDE, a tabela do SDK vem no partitions.csv da pasta de cada exemplo da biblioteca (num sketch seu, copie esse arquivo para a pasta dele) e pede o esquema Ferramentas > Partition Scheme > "Minimal SPIFFS (1.9MB APP with OTA/128KB SPIFFS)", que dá ao app o limite do slot (1.966.080 B; no esquema padrão o IDE para em 1.310.720 B). Sem a partição devui na tabela, a biblioteca avisa na serial a cada partida. Os detalhes, e o PlatformIO e o arduino-cli: README.md do SDK, seção Arduino.

Placa gravada com a tabela antiga (de antes de 15/10/2026, com a devui em 0x12000): em campo, ela segue pela OTA sem erase e com a mesma identidade (o SDK acha a devui pelo nome, na tabela gravada na placa). Pela USB, a tabela nova grava o app por cima da devui antiga, e a placa ganha identidade nova: grave com o erase-flash acima, passe o Wi-Fi e pareie de novo (passos 7 e 8); o dispositivo antigo fica na conta até você desvinculá-lo em Dispositivos (menu de três pontos do cartão dele, Desvincular).

Termina com Hard resetting via RTS pin..., e o LED pisca 3 vezes. Se a gravação parar em Failed to connect ... No serial data received, segure o botão BOOT da placa enquanto o comando conecta.

Até o passo 7 a placa não tem rede: no log dela aparecem sem rede: nem no menuconfig, nem gravada; mande uma pelo Improv e erros de conexão com o gateway (Host is unreachable). É o esperado; siga para o passo 7.

Pela mesma USB, com o nome e a senha da sua rede (entre aspas simples, que valem no PowerShell e no Linux/macOS):

python ../../tools/improv_cli.py PORTA wifi 'nome-da-rede' 'senha-da-rede'

O comando fala Improv Serial com a placa e mostra o log dela (as linhas log:) enquanto espera. Em alguns segundos, ela entra na rede, fala com a nuvem e responde com o link de pareamento. Entre muitas linhas do Wi-Fi, aparecem estas (os números mudam, e o endereço do link é o do portal da sua ficha):

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

Antes da linha do IP podem vir erros de conexão (connect() error: Host is unreachable, esp_transport_connect() failed, conexão fechada, código 0): é a placa tentando a nuvem antes de ter rede. Ela tenta de novo sozinha quando o IP chega, e não é preciso fazer nada.

erro: nenhum só diz que a placa aceitou o pedido. Guarde o código e o link (url:). A placa guarda a rede: se reiniciar, ela volta sozinha para a mesma rede, e se a rede cair, tenta de novo sozinha, com esperas que crescem até 30 s.

Logo depois, quando a nuvem confirma que tem o código, a serial mostra também a linha devui: pair code K7Q2-M9XD ttl=598 (abaixo); a ferramenta já terminou, e ela aparece no monitor (idf.py -p PORTA monitor).

O código vale 10 minutos (o ttl da linha diz quanto ainda falta), e a placa troca por um novo sozinha antes de vencer. Passou desse tempo, ou perdeu o link? Peça o atual (a placa já está na rede, nada é gravado de novo):

python ../../tools/improv_cli.py PORTA state

A ferramenta precisa do pyserial, que já vem com o ESP-IDF. Ela não reinicia a placa.

A linha do código na serial

O SDK, e não o exemplo, põe o código de pareamento na serial numa linha de formato fixo:

I (7330) devui: pair code K7Q2-M9XD ttl=598     ESP-IDF e Rust: o log do ESP-IDF, nível INFO, tag devui
devui: pair code K7Q2-M9XD ttl=598              Arduino (ESP32 e ESP8266): a biblioteca DevUI, no Serial
  • Formato: pair code , o código com o hífen da exibição (dois grupos de 4 caracteres do base32 Crockford, em maiúsculas), ttl= e os segundos que o código ainda vale, em decimal. O portal lê a linha pela USB (Web Serial) com a expressão pair code ([0-9A-Z]{4})-([0-9A-Z]{4}) ttl=(\d+): é contrato, e não muda sem uma versão nova do portal que leia as duas.
  • Quando sai: só para um código que vale na nuvem, uma vez por código, depois de o SDK mandá-lo à nuvem com a conexão pronta e sem dono: na hora em que a nuvem confirma esse código (o CODE_ACK do protocolo, desde 25/10). Com uma nuvem anterior ao CODE_ACK, que nunca o manda, sai 5 s depois do envio, se a nuvem não o recusou nesse tempo; depois do primeiro CODE_ACK do boot, essa espera desliga, e um código que a nuvem não confirmou (um que ela não guardou, como o mesmo código em outro dispositivo) não ganha a linha. Vale para o código novo, o renovado antes de vencer e o do boot anterior que volta da NVS depois de um reinício; o ttl é o que o código ainda vale naquela hora. Uma reconexão que só reenvia o mesmo código não repete a linha.
  • Quando não sai: com dono (o devui_pair_begin recusa e não há código), nunca com um código vazio ou inválido, e não para um código que a nuvem ainda não tem: o pedido offline só ganha a linha quando o código chega à nuvem; recusado com 4429 (mais de um código por minuto), a linha espera o reenvio. O evento DEVUI_EV_PAIR_CODE e o Improv não esperam: o app recebe cada código na hora. O DEVUI_EV_PAIR_CODE_ACCEPTED vem a cada envio e reenvio que a nuvem confirma (a linha, uma vez por código, sai na primeira dessas confirmações); com uma nuvem anterior ao CODE_ACK, a linha sai pela espera de 5 s e o evento não.
  • Nível do log: no ESP-IDF, a linha vai pelo ESP_LOGI da tag devui. Um firmware que baixa o nível do log abaixo de INFO (CONFIG_LOG_DEFAULT_LEVEL, ou esp_log_level_set("devui", ...)) tira a linha junto: o SDK não escreve na serial por fora do log, que o firmware pode ter calado por usar a UART para outra coisa. Aí o código só sai pelo Improv, quando o firmware o tem, ou pela tela do produto.
  • Arduino sem a Serial: a biblioteca abre o Serial a 115200 quando o sketch não o abriu e escreve a linha nele. Numa placa cujo pino de TX da UART0 aciona outra coisa (um relé, por exemplo), compile com -D DEVUI_ARDUINO_SERIAL=0 (no PlatformIO, em build_flags): o SDK não abre nem escreve na Serial, e a linha não sai. O código continua chegando ao app pelo DEVUI_EV_PAIR_CODE, para a tela do produto (A biblioteca Arduino).
  • O texto em português dos exemplos (código de pareamento: ... (vale N s)) saiu; o portal só o lê enquanto houver placas com firmware anterior.

8. Criar a conta e parear

  1. Abra o e-mail Convite para criar sua conta e clique em Criar a conta: o link abre o cadastro no portal da ficha. No beta fechado, o cadastro só abre por esse link; o Ainda não tem conta? Crie uma da tela de entrada leva só ao aviso Cadastro por convite. Digite o e-mail que recebeu o convite (ele vale só para esse endereço) e uma senha de pelo menos 8 caracteres (uma frase serve; uma senha que aparece em vazamentos conhecidos é recusada). Marque Declaro que tenho 18 anos ou mais e, se aparecer, a caixa de aceite dos termos de uso e do aviso de privacidade. Se houver a verificação anti-robô da Cloudflare acima do botão, ela costuma se resolver sozinha; se pedir um clique, clique nela. Clique em Criar conta: a tela passa a Confira seu e-mail.
  2. Abra o e-mail Confirme seu e-mail e clique no link (Confirmar e-mail). Na página que abre, digite a senha de novo e clique em Confirmar e entrar. Se o portal oferecer uma passkey, Agora não serve.
  3. Abra o link do passo 7. O portal mostra o código do link e pede que você marque O meu dispositivo mostra este mesmo código: confira com a linha devui: pair code do passo 7 e clique em Continuar.

    Também dá para ir em Dispositivos, clicar no botão + do canto inferior direito da lista (o nome dele, para leitores de tela, é Parear um dispositivo; com a lista vazia, há também o Parear com o código) e digitar o código (com ou sem o hífen).

  4. A confirmação mostra o que a placa declara de si e a conta que vai recebê-la. O exemplo não declara produto nem chave de projeto, então esses dois aparecem como "não informado", e a versão do SDK aparece como a do SDK que você compilou (0.1.0 ou mais nova; As versões do SDK). Dê um nome (por exemplo, "LED da mesa") e clique em Parear. Se o portal abrir Confirme que é você, digite a senha da conta (e, se ela tiver o app autenticador ligado, o código dele) e clique em Confirmar: parear é uma ação de segurança, e o portal pede a senha de novo quando a entrada não é recente.

Pronto, a placa é sua. Para acompanhar o log dela daqui em diante, abra o monitor (para sair dele, Ctrl+]):

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

O monitor reinicia a placa ao abrir; ela volta à rede e à nuvem sozinha e loga pareamento: a placa já tem dono.

9. Abrir a página e acender o LED

  1. Em Dispositivos (a tela que abre quando você entra no portal), a placa aparece num cartão com o nome que você deu. Logo depois do pareamento ela pode aparecer como Offline por uns segundos, enquanto reconecta: recarregue a página até ver Online. Clique no nome da placa.
  2. A página do dispositivo mostra, numa moldura, a interface que veio gravada no firmware: a linha LED: apagado online (o estado do LED e o da conexão) e o botão Alternar. As outras linhas da moldura (Marcado como estado, Pergunta ao dispositivo) são do teste do exemplo e podem ser ignoradas.
  3. Clique em Alternar. Ao lado do botão aparece feito quando a placa confirma, e logo depois a linha passa a LED: aceso; o LED acende, e o monitor loga led: LED aceso pela página. Clique de novo para apagar.

Pronto: do zero ao LED na página.

Se a sua placa não tiver LED no pino do exemplo (a ESP32-DevKitC original não tem), a prova fica na página e na linha LED aceso pela página do monitor. Para usar outro pino, rode idf.py -B build/esp32 menuconfig, mude "devui LED example", "LED GPIO", e grave de novo sem o erase-flash.

10. Trocar a interface sem regravar a placa (opcional)

A interface que a página mostra é a pasta examples/led/web gravada no firmware. Para mudá-la sem gravar a placa de novo, a CLI do SDK (tools/devui.py, só Python, sem nada a instalar) empacota a pasta e a publica para o produto: ela passa a ser a interface de todos os dispositivos do produto, e nenhuma placa a tira do ar.

O produto tem a marcação Interface, na página dele: na nuvem (a do produto novo) ou no dispositivo. Na nuvem, as abas recebem só a publicação do produto, e a interface gravada no firmware não é usada: quando a placa a anuncia, a nuvem a recusa (a serial mostra bundle REJECT, REFUSAL 4: the product serves its interface from the cloud...), e a placa segue conectada, com estado, ações e banco. Assim, ao ligar a placa ao produto no passo 1, a página dela fica "sem interface" até a primeira publicação, no passo 3. No dispositivo, cada placa serve a interface que carrega enquanto o produto não tem publicação; com uma publicação, as abas recebem a publicação.

  1. No portal, abra o menu da conta (o botão Minha conta, no canto superior direito) e clique em Desenvolvedor. Na Área do desenvolvedor, crie um produto (Criar produto) e copie o project_key dele (pk_...). Ponha-o no exemplo em idf.py -B build/esp32 menuconfig, "devui LED example", "EXAMPLE_PROJECT_KEY", e grave de novo (passos 5 e 6, sem o erase-flash): a placa passa a ser desse produto.
  2. Na página do produto, em Chaves de publicação, clique em Criar chave e copie a chave: ela aparece uma vez só. Criar uma chave pede um segundo fator na conta (app autenticador ou passkey), que se liga na tela Minha conta, do mesmo menu. Guarde a chave num arquivo só seu, por exemplo ~/.devui-chave. Ela nunca vai na linha de comando, porque ali qualquer usuário da máquina a vê na lista de processos.
  3. Mude algo em examples/led/web/index.html e publique, da raiz do SDK:

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

    Num CI, a chave vem da variável DEVUI_PUBLISH_KEY (o segredo do CI), e o --key-file sai do comando.

  4. A saída termina em publicado: hash .... A moldura da página da placa recarrega com a interface nova, e a barra mostra "publicada pela CLI". A conta recebe um e-mail a cada publicação.

Para voltar à interface do firmware, marque a Interface do produto como no dispositivo e despublique, na página do produto ou pela CLI (veja Despublicar): gravar um firmware com outra pasta web/ não tira mais a publicação do ar.

Firmware sem interface

Num produto com a interface na nuvem, a pasta web/ do firmware só gasta flash: a nuvem nunca a usa. Feito sem ela, o firmware não anuncia interface nenhuma (o HELLO vai sem o hash do bundle), nada é recusado, e as abas recebem a publicação do produto. No ESP-IDF, tire o devui_add_bundle(web) do main/CMakeLists.txt (o DEVUI_CONFIG_DEFAULT() segue igual: sem bundle no build, o SDK sobe sem ele); é como o examples/banco já é. No Arduino, chame DevUI.begin com um DevUIBundle vazio, {nullptr, 0, nullptr, 0, nullptr}, como o ChamarOutro faz (ou com um devui_config_t sem bundle); sem a pasta web/, não há devui_bundle.h a incluir.

Sem a pasta web/, a placa fica sem interface também na rede local: o modo local serve o bundle do firmware, nunca a publicação do produto. Quem usa o modo local num produto com a interface na nuvem grava a pasta web/ no firmware assim mesmo; a nuvem a recusa (o REFUSAL 4), e só a rede local a usa.

python tools/devui.py pack examples/led/web saida/ só empacota (é o devui_pack.py, com as mesmas opções), e publish aceita também o saida/bundle.dvu assim gerado. O endereço padrão é o da nuvem de produção (https://api.thingface.com); --api aponta para outro, como o da ficha do ambiente de teste.

Interface assinada

Com uma chave de assinatura, a interface chega às placas com o selo "assinada": a nuvem confere que ela saiu de você e que nenhum byte mudou depois.

  1. Crie a chave uma vez: python tools/devui.py keygen ~/.devui-assinatura.pem. O arquivo é a chave privada, fica só na sua máquina (ou no segredo do CI) e nunca vai à nuvem; só o seu usuário lê o arquivo (no Windows também: o comando troca as permissões herdadas da pasta por uma só, a sua); o comando mostra a chave pública e a impressão dela.
  2. No portal, em Desenvolvedor > o produto > Chaves de assinatura, registre a chave pública (pede o segundo fator).
  3. Publique assinando:

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

    Num CI, o caminho do arquivo vem da variável DEVUI_SIGN_KEY_FILE. A saída termina em ..., assinada pela chave <impressão>. Uma chave revogada no portal, ou um bundle mexido depois de assinado, é recusada (código 5, com o motivo), e nada muda na nuvem. Sem --sign-key, a publicação vai sem assinatura, como antes.

Cada saída do publish tem um código, para um CI decidir sem ler a mensagem (os de cada comando, com o unpublish e o tables, estão na Referência da CLI):

CódigoO que houve
0publicado
1resposta fora do esperado (403 da borda, 404 de um --api errado, outro hash)
2uso errado, ou a pasta quebra uma regra do empacotador; nada foi enviado
3sem a chave (nem token OIDC), ou o texto não é uma chave; nada foi enviado
4chave recusada: errada, de outro produto, vencida, revogada ou conta suspensa; ou o token OIDC recusado; nada mudou
5bundle recusado pela nuvem (grande demais ou inválido, com o motivo)
6bundle bloqueado pela administração
7acabaram as publicações do dia da conta (20 por dia), ou trocas de token OIDC demais; a mensagem diz quando tentar de novo
8rede: sem conexão, erro de TLS ou tempo esgotado
9nuvem indisponível agora; a mensagem diz quando tentar de novo, se a nuvem disser
10a nuvem não aceita token OIDC (o OIDC está desligado nesse servidor); nada foi publicado

Publicar pelo CI sem chave guardada (OIDC)

Num CI, a chave não precisa ficar guardada como segredo: sem chave (nem --key-file nem DEVUI_PUBLISH_KEY), o publish pega o token OIDC do próprio CI e o troca na nuvem por uma credencial de 15 minutos, que só publica naquele produto. Nenhum token nem a credencial aparece na saída.

Hoje isso depende de a nuvem aceitar o emissor do token: a produção ainda não aceita nenhum. Até lá a troca responde 404, a CLI sai com o código 10, e a publicação pelo CI usa a chave.

  1. Na página do produto, em Publicação pelo CI, sem chave guardada (OIDC), autorize o repositório: o repositório (dono/repositório), o ramo (por exemplo main) e o id do repositório (o número dele no GitHub, que não se repete se alguém apagar o repositório e criar outro com o mesmo nome). O evento (push) e o workflow são opcionais, mas recomendados: sem eles, um evento como pull_request_target, que roda com o ramo do repositório base, também publica.
  2. No workflow do GitHub Actions, dê ao job o id-token: write e rode o publish sem chave:

    on:
      push:
        branches: [main]
    permissions:
      contents: read
      id-token: write   # o token OIDC do job; sem isso, não há token
    jobs:
      publicar:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - run: python thingface-sdk/tools/devui.py publish web --project-key pk_...

    O exemplo supõe o SDK dentro do repositório, em thingface-sdk/. A CLI pede o token ao GitHub com o público https://api.thingface.com, o que a nuvem de produção exige; --oidc-audience (ou DEVUI_OIDC_AUDIENCE) troca o público, para um servidor com outro, como o do ambiente de teste.

Outro CI, quando a nuvem aceitar o emissor dele, entrega o token pronto na variável DEVUI_OIDC_TOKEN (no GitLab, por id_tokens) ou num arquivo indicado por --oidc-token-file; como a chave, o token nunca vai na linha de comando. Se a nuvem recusar o token (código 4), confira na página do produto o repositório, o ramo e o id do repositório: é o que mais desencontra.

Despublicar

A publicação sai do ar para todos os dispositivos do produto pelo botão da página do produto ou, com a mesma chave do publish (ou o OIDC do CI), pela CLI:

python tools/devui.py unpublish --project-key pk_... --key-file ~/.devui-chave

A saída termina em a publicação <hash> saiu de todos os dispositivos do produto. Com a Interface na nuvem, as abas passam na hora para "sem interface" até a próxima publicação; no dispositivo, cada placa volta a servir a do próprio firmware. Um produto sem publicação em vigor, ou travado (a publicação assinada fica), sai com o código 5 e o motivo, e nada muda.

As tabelas do banco

As tabelas do banco de dados simples de um produto também são do produto, não do firmware: declaram-se na aba Banco de dados da página do produto ou com python tools/devui.py tables push tabelas.json --project-key pk_... --key-file ~/.devui-chave (e tables get mostra as em vigor). O formato, os tipos, o que acontece ao remover um campo ou uma tabela e a API da placa estão em Banco de dados. Um tabelas.json ao lado de web/ faz o devui pack sair com erro.

Para ir além

Quando algo não sai como aqui

O que apareceO que fazer
Nenhuma porta nova ao ligar a placaTroque o cabo (cabo só de carga não serve) e instale o driver da ponte USB (CP210x ou CH340).
Failed to connect ... No serial data receivedSegure BOOT enquanto o idf.py conecta; feche outro programa que esteja com a porta aberta (o monitor, o Arduino).
could not open port ou sem resposta no prazo no improv_cli.pyFeche o monitor (Ctrl+]) ou outro programa com a porta aberta, confira a PORTA e rode de novo.
erro: sem conexão no improv_cli.pySenha errada ou rede de 5 GHz: rode o passo 7 de novo com a rede e a senha certas. Nada precisa ser gravado de novo.
url: (nenhuma)A placa entrou na rede, mas ainda não falou com a nuvem. Espere uns segundos e rode o state do passo 7; se continuar, veja a linha abaixo.
sem raízes de confiança ou erro de certificado no logO main/ca.pem falta ou está vazio, ou o endereço do gateway não está igual ao da ficha (passo 4). Corrija, apague build/<chip> e repita os passos 5 e 6.
wifi: sem rede (motivo ...): nova tentativa em ... ms, repetidaA rede caiu ou mudou de senha. A placa tenta sozinha; se a senha mudou, passe a nova pelo passo 7.
O portal diz que o código é inválido ou venceuRode o state do passo 7 e use o código e o link que ele der: o código anterior deixa de valer quando sai um novo.
Cadastro por convite, sem formulárioO cadastro só abre pelo link do e-mail do convite (passo 8.1).
Confirme seu e-mail antes de parearAbra o link do e-mail do passo 8.2 (olhe a pasta de spam).
pareamento: a placa já tem dono e nenhum códigoA placa foi pareada antes. Desvincule-a em Dispositivos (menu de três pontos do cartão dela, Desvincular), ou grave de novo com erase-flash (passo 6) e repita o passo 7.
A moldura diz que a interface não respondeuSiga o que ela pede (apagar os dados do site de conteúdo no navegador) e clique em Recarregar.
O botão Alternar fica cinzaA placa está offline: veja no monitor se ela está sem rede.