Pular para o conteúdo
ThingFace

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çãoO que é
--project-key pk_...o project_key do produto (obrigatório)
--key-file ARQum 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 URLa API da nuvem; padrão: https://api.thingface.com. HTTP sem TLS só para um endereço de loopback
--oidc-token-file ARQsem 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 AUDo público (aud) do token OIDC pedido ao GitHub Actions; padrão: a variável DEVUI_OIDC_AUDIENCE ou https://api.thingface.com
--timeout Ssegundos 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çãoO que faz
<saída>a pasta onde ficam o bundle.dvu e o bundle.manifest.json (e o bundle.sig, com --sign-key)
--product NOMEo produto no manifesto (padrão: devui-app); para o manifesto do firmware sair igual ao da publicação, o project_key
--version Va versão da interface no manifesto (padrão: 0.0.0)
--c-source ARQtambém um arquivo C com o contêiner e o manifesto em vetores de bytes, para o firmware embutir
--arduino ARQo 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 CHIPo 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 ARQa chave privada de assinatura (de devui keygen): assina o bundle, e os 72 bytes da assinatura vão no firmware
--security-version Na 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 ARQas 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ódigoO que houve
0empacotado
2uso 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çãoO que faz
--sign-key ARQa 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 Va versão da interface no manifesto assinado (padrão: 0.0.0; até 64 caracteres entre letras, dígitos e . + _ -)
--security-version Na versão de segurança no manifesto assinado; só com --sign-key
--acoes ARQas 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ó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, ou a chave de assinatura não se lê; 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, 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
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

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ódigoO que houve
0despublicado
1resposta fora do esperado (403 da borda, 404 de um --api errado, 200 sem o hash retirado)
2uso errado; nada foi enviado
3sem a chave (nem token OIDC), ou o texto não é uma chave; nada foi enviado
4chave ou token OIDC recusado; nada mudou
5sem publicação em vigor, ou o produto está travado (a publicação assinada fica), com o motivo; nada mudou
7pedidos demais agora (429), 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
10a 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ódigoO que houve
0gravadas (push) ou mostradas (get)
1resposta fora do esperado (403 da borda, 404 de um --api errado, resposta sem a versão ou sem a lista)
2uso 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
3sem a chave (nem token OIDC), ou o texto não é uma chave; nada foi enviado
4chave ou token OIDC recusado; nada mudou
5tabelas recusadas pela nuvem (por exemplo, o tipo de um campo trocado), com o motivo; nada mudou
7pedidos demais agora (429), 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
10a 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 publishO que faz
--chip CHIPo chip-alvo, o nome do HELLO (esp32, esp32s3, esp32c3, esp32c6, esp8266...); obrigatório
--version Va 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 Na 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 HEXassina 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 Co commit do código, guardado com a release (até 64 de [0-9A-Za-z._/-])
--notes TEXTOas 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 ARQas 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 rolloutO que faz
--no-phasesa lista ou o produto de uma vez, sem fases (o corpo leva phased: false)
--failure-pct Po limite da parada automática: mais que P % das placas das fases abertas (de 0 a 100; padrão 5)
--failure-min Nas 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 Mo 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ódigoO que houve
0feito
1resposta fora do esperado (403 da borda, 404 de um --api errado, resposta sem a release ou a implantação)
2uso 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
3sem a chave (nem token OIDC), ou o texto não é uma chave; nada foi enviado
4chave ou token OIDC recusado: errada, de outro produto, vencida, revogada ou conta suspensa; nada mudou
5recusado 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
7pedidos demais agora (429), ou trocas de token OIDC demais
8rede: sem conexão, erro de TLS ou tempo esgotado
9nuvem indisponível agora
10a nuvem não aceita token OIDC
11sem 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ódigoO que houve
0feito
2uso errado, o arquivo já existe, ou não deu para criá-lo legível só por você (nada foi escrito)
3pubkey: o arquivo não é uma chave de assinatura que se lê

As variáveis de ambiente

VariávelNo 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