Referência da CLI
A CLI do SDK, tools/devui.py, empacota a interface (a pasta web/), publica e despublica a interface do produto, grava as tabelas do banco do produto, publica e implanta o firmware do produto (OTA) e cria a chave de assinatura. É só Python 3, com a biblioteca padrão: nada a instalar. Cada comando sai com um código, para um CI decidir sem ler a mensagem.
python tools/devui.py pack <pasta web> [<saída>] [opções]
python tools/devui.py publish <pasta web | bundle.dvu> --project-key pk_... [opções]
python tools/devui.py unpublish --project-key pk_... [opções]
python tools/devui.py tables push <tabelas.json> --project-key pk_... [opções]
python tools/devui.py tables get --project-key pk_... [opções]
python tools/devui.py firmware publish <app.bin> --chip CHIP --project-key pk_... [opções]
python tools/devui.py firmware releases|rollout|status|pause|resume|complete|advance ... --project-key pk_... [opções]
python tools/devui.py keygen <arquivo da chave privada>
python tools/devui.py pubkey <arquivo da chave privada>
python tools/devui.py --help, e --help depois de cada comando, mostram as opções.
A chave e o endereço
Os comandos que falam com a nuvem (publish, unpublish, tables e firmware) levam as mesmas opções:
| Opção | O que é |
|---|---|
--project-key pk_... | o project_key do produto (obrigatório) |
--key-file ARQ | um arquivo só com a chave de publicação; --key-file - a lê da entrada padrão. Sem ele, a variável DEVUI_PUBLISH_KEY |
--api URL | a API da nuvem; padrão: https://api.thingface.com. HTTP sem TLS só para um endereço de loopback |
--oidc-token-file ARQ | sem chave: um arquivo só com o token OIDC do CI (- lê a entrada padrão); sem ele, a variável DEVUI_OIDC_TOKEN ou o próprio GitHub Actions |
--oidc-audience AUD | o público (aud) do token OIDC pedido ao GitHub Actions; padrão: a variável DEVUI_OIDC_AUDIENCE ou https://api.thingface.com |
--timeout S | segundos de espera pela nuvem; padrão: 60 |
A chave nunca vai na linha de comando, porque ali qualquer usuário da máquina a vê na lista de processos: um argumento que parece uma chave (ou um token OIDC) é recusado antes de tudo, com o código 2, sem ser repetido na saída. A chave se cria no portal: Desenvolvedor > o produto > Chaves de publicação. Com chave e token ao mesmo tempo, vale a chave; sem nenhum dos dois, o comando pede o token ao GitHub Actions (o job precisa de permissions: id-token: write) e o troca na nuvem por uma credencial de 15 minutos daquele produto (Publicar pelo CI sem chave guardada). A CLI nunca segue um redirecionamento, para a chave não ir junto.
devui pack
Empacota a pasta web/ num contêiner DVU1 e no manifesto dele, sempre do mesmo jeito (a mesma pasta dá os mesmos bytes), sem mandar nada.
python tools/devui.py pack examples/led/web saida/
| Opção | O que faz |
|---|---|
<saída> | a pasta onde ficam o bundle.dvu e o bundle.manifest.json (e o bundle.sig, com --sign-key) |
--product NOME | o produto no manifesto (padrão: devui-app); para o manifesto do firmware sair igual ao da publicação, o project_key |
--version V | a versão da interface no manifesto (padrão: 0.0.0) |
--c-source ARQ | também um arquivo C com o contêiner e o manifesto em vetores de bytes, para o firmware embutir |
--arduino ARQ | o devui_bundle.h de um sketch Arduino. Sem <saída>, sem --c-source e sem --arduino, o devui_bundle.h vai ao lado da pasta web/, na pasta do sketch |
--target CHIP | o IDF_TARGET (esp32, esp32s3, esp32c3...), em minúsculas e sem hífen, para o aviso de tamanho; sem ele, ou com um chip nunca medido, vale o menor limiar entre os chips medidos. ESP32-S3 ou s3 são recusados |
--sign-key ARQ | a chave privada de assinatura (de devui keygen): assina o bundle, e os 72 bytes da assinatura vão no firmware |
--security-version N | a versão de segurança no manifesto, um inteiro de 0 a 4294967295: a nuvem recusa a publicação assinada abaixo da maior que o produto já aceitou |
--acoes ARQ | as ações com nome, um JSON; sem ele, o acoes.json ao lado da pasta web/, se houver (Ações com nome) |
O empacotador recusa o que a nuvem recusaria: um caminho absoluto fora de /_devui/ no HTML, no CSS ou no JS, uma extensão fora da lista, um contêiner acima de 512 KiB ou arquivos que somam mais de 4 MiB descomprimidos. Ele avisa (sem falhar) quando o firmware com a interface pode não caber no app da tabela de partições padrão do ESP-IDF; no ESP32-C3 e no ESP32-C6, o exemplo do LED já não cabe nela, e esses chips usam a tabela do SDK. Um tabelas.json ao lado da pasta web/ é erro: as tabelas do banco são do produto (Banco de dados).
| Código | O que houve |
|---|---|
| 0 | empacotado |
| 2 | uso errado, ou a pasta quebra uma regra (caminho, extensão, tamanho, contagem, caminho absoluto, ações, tabelas.json), ou a chave de assinatura não se lê; nada foi escrito |
devui publish
Publica a interface para o produto: ela passa a ser a de todos os dispositivos do produto, e nenhuma placa a tira do ar (Trocar a interface sem regravar a placa). Aceita a pasta web/ (empacotada na hora, como o pack) ou um bundle.dvu já empacotado.
python tools/devui.py publish examples/led/web --project-key pk_... --key-file ~/.devui-chave
Além das opções da chave e do endereço:
| Opção | O que faz |
|---|---|
--sign-key ARQ | a chave privada que assina o manifesto (de devui keygen); sem ela, a variável DEVUI_SIGN_KEY_FILE; sem nenhuma, a publicação vai sem assinatura |
--version V | a versão da interface no manifesto assinado (padrão: 0.0.0; até 64 caracteres entre letras, dígitos e . + _ -) |
--security-version N | a versão de segurança no manifesto assinado; só com --sign-key |
--acoes ARQ | as ações com nome, que vão no manifesto, assinado ou não; sem ele, o acoes.json ao lado da pasta web/ |
A saída termina em publicado: hash ... (e, assinada, assinada pela chave <impressão>). Sem assinatura, o contêiner vai até 512 KiB; assinado, o teto é o do plano da conta (de 512 KiB no Grátis a 4 MiB no Fabricante). A conta recebe um e-mail a cada publicação, e cada conta tem 20 publicações por dia.
| 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, ou a chave de assinatura não se lê; 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, inválido, assinatura que não confere, produto travado sem assinatura, ou versão de segurança abaixo da do produto (com o motivo); nada mudou |
| 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 |
devui unpublish
Tira do ar a publicação do produto em vigor, em todos os dispositivos dele, como o botão Despublicar da página do produto, com a mesma chave (ou o OIDC) do publish. Leva só as opções da chave e do endereço.
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 do produto na nuvem, as abas ficam sem interface até a próxima publicação; no dispositivo, cada placa volta a servir a do próprio firmware.
| Código | O que houve |
|---|---|
| 0 | despublicado |
| 1 | resposta fora do esperado (403 da borda, 404 de um --api errado, 200 sem o hash retirado) |
| 2 | uso errado; nada foi enviado |
| 3 | sem a chave (nem token OIDC), ou o texto não é uma chave; nada foi enviado |
| 4 | chave ou token OIDC recusado; nada mudou |
| 5 | sem publicação em vigor, ou o produto está travado (a publicação assinada fica), com o motivo; nada mudou |
| 7 | pedidos demais agora (429), 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 |
| 10 | a nuvem não aceita token OIDC |
devui tables
Grava (push) ou mostra (get) as tabelas do banco de dados do produto, com a mesma chave (ou o OIDC) do publish. O formato e o que acontece ao mudar a declaração com placas em campo estão em Banco de dados. Os dois levam só as opções da chave e do endereço; o push, também o arquivo.
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
O push confere o arquivo na sua máquina, pelas regras da nuvem, antes de mandar qualquer coisa, e termina em versão N das tabelas do produto. O get imprime as tabelas em vigor em JSON na saída padrão, prontas para um push, e a contagem na saída de erro. O push não pergunta antes de remover uma tabela (e os registros dela, em todas as contas): confira a lista antes de mandar.
| Código | O que houve |
|---|---|
| 0 | gravadas (push) ou mostradas (get) |
| 1 | resposta fora do esperado (403 da borda, 404 de um --api errado, resposta sem a versão ou sem a lista) |
| 2 | uso errado, ou o arquivo quebra uma regra (com a tabela e o campo; a lista antiga do device, "device": [...], sai mostrando a forma nova, {"device": [...], "account": [...]}); nada foi enviado |
| 3 | sem a chave (nem token OIDC), ou o texto não é uma chave; nada foi enviado |
| 4 | chave ou token OIDC recusado; nada mudou |
| 5 | tabelas recusadas pela nuvem (por exemplo, o tipo de um campo trocado), com o motivo; nada mudou |
| 7 | pedidos demais agora (429), 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 |
| 10 | a nuvem não aceita token OIDC |
devui firmware
Publica o firmware do produto na nuvem e o implanta nas placas pelo OTA, com a mesma chave (ou o OIDC) do publish e sem segundo fator: o CI do fabricante publica e dispara só com a chave. Todos levam as opções da chave e do endereço.
python tools/devui.py firmware publish build/termostato.bin --chip esp32s3 --security-version 1 --commit "$GIT_SHA" --notes-file NOTAS.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 placas.txt --no-phases --project-key pk_...
python tools/devui.py firmware status --project-key pk_...
python tools/devui.py firmware status <implantação> --project-key pk_...
python tools/devui.py firmware pause|resume|complete|advance <implantação> --project-key pk_...
O publish manda o .bin cru do app (o build/<projeto>.bin do ESP-IDF ou o .bin do Arduino, nunca o merged; no máximo o slot de OTA do SDK, 1,875 MB). A nuvem confere o cabeçalho da imagem e o chip, exige a versão de segurança no piso do produto ou acima, assina o envelope com a chave de firmware do produto e guarda a release seguinte (as 5 mais novas ficam).
Opção do publish | O que faz |
|---|---|
--chip CHIP | o chip-alvo, o nome do HELLO (esp32, esp32s3, esp32c3, esp32c6, esp8266...); obrigatório |
--version V | a versão da release, de 1 a 32 bytes; obrigatória no ESP8266 (a imagem dele não traz versão); no ESP-IDF, se vier, tem de ser a da imagem |
--security-version N | a versão de segurança da release, de 0 a 4294967295; sem ela, o piso do produto (a maior já publicada). Abaixo do piso, a nuvem recusa |
--key-id HEX | assina com esta chave de firmware do produto (16 hex): a release de transição, depois de girar a chave, assinada pela anterior, que leva a pública nova às placas |
--commit C | o commit do código, guardado com a release (até 64 de [0-9A-Za-z._/-]) |
--notes TEXTO | as notas da release: texto simples, sem HTML, até 2.000 caracteres e 4.000 bytes de UTF-8, sem caractere de controle além da quebra de linha e da tabulação. A nuvem as guarda com a release (fora do envelope assinado: a placa não as vê) e as mostra no portal, no app do dono (quando ele pode adiar) e nos e-mails ao dono da atualização aplicada e da adiada, sempre como texto. Um texto que começa com - vai como --notes="- ..." |
--notes-file ARQ | as notas lidas de um arquivo de texto em UTF-8, no lugar de --notes (não os dois) |
O rollout --release N abre a implantação de uma release, uma aberta por produto: o produto inteiro (--product, inclusive as placas que chegarem depois), uma placa (--device ID) ou uma lista (--devices ARQ: um id por linha, com comentários #, até 1.000; - lê a entrada padrão, mas não junto com --key-file - ou --oidc-token-file -).
A lista e o produto vão em fases por padrão, sem precisar pedir: 1 % → 10 % → 100 % das placas, cada fase com pelo menos o mínimo de placas novas. A fase seguinte só abre depois do tempo mínimo e das confirmações, e a parada automática pausa a implantação quando, nas fases abertas, mais que o limite das placas falhou ou reverteu (as falhas de rede também contam); os administradores do produto recebem um e-mail com o motivo e a taxa. Uma placa sozinha (--device) nunca vai em fases.
Opção do rollout | O que faz |
|---|---|
--no-phases | a lista ou o produto de uma vez, sem fases (o corpo leva phased: false) |
--failure-pct P | o limite da parada automática: mais que P % das placas das fases abertas (de 0 a 100; padrão 5) |
--failure-min N | as placas que a taxa pede antes de valer e as que cada fase acrescenta no mínimo (de 1 a 1.000; padrão 3) |
--phase-minutes M | o tempo mínimo de cada fase, em minutos (de 0 a 10.080, uma semana; padrão 60) |
Os limites não combinam com --no-phases nem com --device (código 2, nada é enviado). Uma release de ESP8266, que não volta sozinha se a imagem nova falhar, só vai a mais de uma placa depois de aplicada numa placa-piloto: antes, a nuvem responde 409 pilot_required, e a CLI diz o caminho (rollout --release N --device <placa>, esperar o applied no status, concluir essa implantação e então disparar para a lista ou o produto).
O status sem id lista as implantações do produto; com o id, mostra a implantação e o estado de cada placa (todas as páginas). O resumo diz a fase (fase 2 de 3, até 6 placas) e por que ela está pausada: à mão, ou pela parada automática, com quantas placas falharam ou reverteram e o limite. pause só impede ofertas novas (o download já aceito termina), resume retoma (depois da parada automática também: retomar aceita as falhas que já houve, e a parada volta a valer para as novas), complete conclui, liberando o produto para a próxima, e advance abre a fase seguinte à mão, sem esperar o tempo mínimo nem as confirmações, para quando as placas da fase aberta ficam desligadas (fica no registro do produto; na última fase, ou sem fases, a nuvem responde 409 no_next_phase).
Cada comando imprime o JSON da nuvem na saída padrão, para o CI ler (o número da release, o id da implantação), e um resumo na saída de erro. Publicar e mexer numa implantação pedem uma chave criada por um administrador do produto (a de um desenvolvedor da organização só lê) e um plano pago. Girar e revogar a chave de firmware continuam só no portal, com o segundo fator.
| Código | O que houve |
|---|---|
| 0 | feito |
| 1 | resposta fora do esperado (403 da borda, 404 de um --api errado, resposta sem a release ou a implantação) |
| 2 | uso errado, ou um arquivo que não é imagem de app (o primeiro byte não é 0xE9), acima do teto, o ESP8266 sem --version, um id ruim na lista; nada foi enviado |
| 3 | sem a chave (nem token OIDC), ou o texto não é uma chave; nada foi enviado |
| 4 | chave ou token OIDC recusado: errada, de outro produto, vencida, revogada ou conta suspensa; nada mudou |
| 5 | recusado pela nuvem, com o motivo: a imagem de outro chip, a versão que falta ou diverge, abaixo do piso, a chave de firmware revogada ou desconhecida, outra implantação aberta, a release que já saiu da guarda, placas de outro produto, a release ou a implantação que não existe, a release de ESP8266 sem a placa-piloto, os limites das fases fora da faixa, nenhuma fase a avançar; nada mudou |
| 7 | pedidos demais agora (429), ou trocas de token OIDC demais |
| 8 | rede: sem conexão, erro de TLS ou tempo esgotado |
| 9 | nuvem indisponível agora |
| 10 | a nuvem não aceita token OIDC |
| 11 | sem permissão no produto: a chave é de um desenvolvedor (só o administrador publica e dispara), ou a conta está no Grátis; nada mudou |
devui keygen e devui pubkey
python tools/devui.py keygen ~/.devui-assinatura.pem
python tools/devui.py pubkey ~/.devui-assinatura.pem
keygen cria uma chave de assinatura Ed25519 nova no arquivo (PKCS#8 PEM, o mesmo do openssl genpkey -algorithm ed25519), nunca por cima de um arquivo que já existe, e o deixa legível só pelo seu usuário (no Windows também: o comando troca as permissões herdadas da pasta por uma só, a sua). Depois mostra a impressão e a chave pública, para registrar no portal (Desenvolvedor > o produto > Chaves de assinatura). pubkey mostra de novo a impressão e a chave pública de uma chave que já existe. A chave privada nunca vai à nuvem (Interface assinada).
| Código | O que houve |
|---|---|
| 0 | feito |
| 2 | uso errado, o arquivo já existe, ou não deu para criá-lo legível só por você (nada foi escrito) |
| 3 | pubkey: o arquivo não é uma chave de assinatura que se lê |
As variáveis de ambiente
| Variável | No lugar de |
|---|---|
DEVUI_PUBLISH_KEY | --key-file |
DEVUI_SIGN_KEY_FILE | --sign-key do publish |
DEVUI_OIDC_TOKEN | --oidc-token-file |
DEVUI_OIDC_AUDIENCE | --oidc-audience |
