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:
Chip Placa LED Pino padrão ESP32 ESP32-DevKitC e clones LED simples GPIO 2 (a DevKitC original não tem LED de usuário: veja o fim do passo 9) ESP32-S3 ESP32-S3-DevKitC-1 RGB endereçável GPIO 48 (v1.0) ou 38 (v1.1) ESP32-C3 ESP32-C3-DevKitM-1 RGB endereçável GPIO 8 ESP32-C6 ESP32-C6-DevKitC-1 RGB endereçável GPIO 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/ttyUSB0ou/dev/ttyACM0(o usuário precisa estar no grupodialout). - 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.
7. Passar o Wi-Fi e pegar o link de pareamento
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ãopair 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_ACKdo protocolo, desde 25/10). Com uma nuvem anterior aoCODE_ACK, que nunca o manda, sai 5 s depois do envio, se a nuvem não o recusou nesse tempo; depois do primeiroCODE_ACKdo 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; ottlé 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_beginrecusa 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 eventoDEVUI_EV_PAIR_CODEe o Improv não esperam: o app recebe cada código na hora. ODEVUI_EV_PAIR_CODE_ACCEPTEDvem 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 aoCODE_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_LOGIda tagdevui. Um firmware que baixa o nível do log abaixo de INFO (CONFIG_LOG_DEFAULT_LEVEL, ouesp_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
Seriala 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, embuild_flags): o SDK não abre nem escreve na Serial, e a linha não sai. O código continua chegando ao app peloDEVUI_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
- 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.
- 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.
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 codedo 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).
- 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.0ou 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
- 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.
- 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. - Clique em Alternar. Ao lado do botão aparece
feitoquando a placa confirma, e logo depois a linha passa aLED: aceso; o LED acende, e o monitor logaled: 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.
- 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_keydele (pk_...). Ponha-o no exemplo emidf.py -B build/esp32 menuconfig, "devui LED example", "EXAMPLE_PROJECT_KEY", e grave de novo (passos 5 e 6, sem oerase-flash): a placa passa a ser desse produto. - 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. Mude algo em
examples/led/web/index.htmle publique, da raiz do SDK:python tools/devui.py publish examples/led/web --project-key pk_... --key-file ~/.devui-chaveNum CI, a chave vem da variável
DEVUI_PUBLISH_KEY(o segredo do CI), e o--key-filesai do comando.- 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.
- 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. - No portal, em Desenvolvedor > o produto > Chaves de assinatura, registre a chave pública (pede o segundo fator).
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.0Num 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ódigo | O que houve |
|---|---|
| 0 | publicado |
| 1 | resposta fora do esperado (403 da borda, 404 de um --api errado, outro hash) |
| 2 | uso errado, ou a pasta quebra uma regra do empacotador; nada foi enviado |
| 3 | sem a chave (nem token OIDC), ou o texto não é uma chave; nada foi enviado |
| 4 | chave recusada: errada, de outro produto, vencida, revogada ou conta suspensa; ou o token OIDC recusado; nada mudou |
| 5 | bundle recusado pela nuvem (grande demais ou inválido, com o motivo) |
| 6 | bundle bloqueado pela administração |
| 7 | acabaram as publicações do dia da conta (20 por dia), ou trocas de token OIDC demais; a mensagem diz quando tentar de novo |
| 8 | rede: sem conexão, erro de TLS ou tempo esgotado |
| 9 | nuvem indisponível agora; a mensagem diz quando tentar de novo, se a nuvem disser |
| 10 | a 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.
- 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 exemplomain) 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 comopull_request_target, que roda com o ramo do repositório base, também publica. No workflow do GitHub Actions, dê ao job o
id-token: writee rode opublishsem 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úblicohttps://api.thingface.com, o que a nuvem de produção exige;--oidc-audience(ouDEVUI_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
- Referência da API em C: cada função de
devui.h, com os erros e as regras de task; a biblioteca Arduino e o binding Rust são cascas sobre ela. - Referência da CLI: todos os comandos, opções e códigos de saída do
devui. - Banco de dados, Preferências da conta: fuso e idioma e Modo local: o que a placa faz além da interface.
- Limites e números medidos e Compatibilidade.
- ESP32 sem PSRAM no Arduino: a receita para o app que, além da nuvem, abre o próprio TLS.
Quando algo não sai como aqui
| O que aparece | O que fazer |
|---|---|
| Nenhuma porta nova ao ligar a placa | Troque 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 received | Segure 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.py | Feche o monitor (Ctrl+]) ou outro programa com a porta aberta, confira a PORTA e rode de novo. |
erro: sem conexão no improv_cli.py | Senha 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 log | O 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, repetida | A 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 venceu | Rode 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ário | O cadastro só abre pelo link do e-mail do convite (passo 8.1). |
| Confirme seu e-mail antes de parear | Abra o link do e-mail do passo 8.2 (olhe a pasta de spam). |
pareamento: a placa já tem dono e nenhum código | A 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 respondeu | Siga o que ela pede (apagar os dados do site de conteúdo no navegador) e clique em Recarregar. |
| O botão Alternar fica cinza | A placa está offline: veja no monitor se ela está sem rede. |
