Banco de dados
A placa grava, lê e soma registros em tabelas na nuvem pela própria conexão, sem HTTP, sem chave no firmware e sem uma segunda conexão TLS. As tabelas são declaradas fora do firmware (na conta dona ou no produto), e os registros ficam na conta dona da placa. Esta página diz de onde vêm as tabelas, o formato delas, a API da placa e os limites. O exemplo completo é o examples/banco.
De onde vêm as tabelas
Uma tabela tem de existir na conta dona antes de a placa usá-la (sem ela, a resposta é nao_existe). Ela vem de um de dois lugares:
- Da conta: o dono a declara no portal, na tela do banco da conta; vale só para aquela conta.
- Do produto: quem fabrica a declara uma vez no produto, e ela chega a todas as contas donas de placas do produto no primeiro uso. A conta dona não muda uma tabela que veio do produto, e quem fabrica nunca vê os registros das contas.
As tabelas do produto são do produto, nunca do firmware: uma placa não muda o que vale para a frota inteira. Há dois caminhos, que gravam a mesma declaração, com uma versão própria, independente das publicações da interface:
- no portal: Desenvolvedor > o produto > a aba Banco de dados, onde se criam, mudam e removem tabelas;
na CLI do SDK, com a mesma chave de publicação do
devui publish(Referência da CLI):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.jsonO
pushconfere o arquivo na sua máquina, pelas regras da nuvem, antes de mandar qualquer coisa (um arquivo inválido sai com o código 2, apontando a tabela e o campo) e termina emversão N das tabelas do produto. Ogetimprime as tabelas em vigor, prontas para o próximopush(o JSON vai na saída padrão, e a contagem, na de erro).
Guarde o arquivo longe da pasta web/ do firmware: um tabelas.json ao lado dela faz o devui pack (e o devui_add_bundle) sair com erro, porque as tabelas não vão mais no manifesto da interface. Quem tinha o arquivo ali manda o mesmo conteúdo com devui tables push e o tira de perto da pasta web/.
O formato
O arquivo é uma lista de até 64 tabelas:
[
{
"table": "creditos",
"fields": {"valor": "number", "maquina": "text", "pago_em": "date", "estornado": "boolean"},
"device": {"device": ["read", "insert"], "account": []}
},
{
"table": "precos",
"fields": {"produto": "text", "valor": "number"},
"device": {"device": [], "account": ["read"]},
"guest": {"device": ["read"], "account": ["read"]}
}
]
table: o nome, de[a-z][a-z0-9_]{0,31}, sem repetir.fields: de 1 a 32 campos, cada um com o tipotext,number,booleanoudate. Os nomes seguem a regra do nome da tabela, eid,ts,deviceeaccountsão reservados (a nuvem os põe em cada registro).device(obrigatório): o que as placas podem fazer, nos dois escopos, cada um com uma lista deread,insert,updateedelete:device.device(obrigatório): nos próprios registros (o escopoDEVUI_DB_DEVICE, os que a placa gravou). A lista pode ser vazia,[]: a placa não mexe nos próprios registros. Uma placa nunca vê os registros de outra.device.account(opcional): nos registros da conta (o escopoDEVUI_DB_ACCOUNT, os compartilhados entre as placas da conta); sem ela, sóread.
guest(opcional): o que o convidado pode fazer, emdevice(nos registros do dispositivo para o qual foi convidado) e emaccount(nos registros da conta), com as mesmas quatro palavras; sem ela, nada.
Nenhum outro campo é aceito, nem na tabela, nem no device, nem no guest.
Dê a cada escopo só o que o firmware usa. No exemplo, a placa grava créditos e soma os do mês nos próprios registros: na creditos, insert e read (a soma e a busca são leituras), e nada nos da conta. Na precos, ela só lê os preços da conta, que o dono grava. Uma tabela em que a placa só grava, sem reler, mudar nem remover o que gravou (as leituras de um sensor, que a conta dona consulta no portal, por exemplo), leva só insert:
{"table": "leituras", "fields": {"valor": "number"}, "device": {"device": ["insert"], "account": []}}
Nela, a busca, a soma, a mudança e a remoção da placa voltam DEVUI_DB_FORBIDDEN.
A lista sozinha de antes ("device": ["read", "insert"], que valia para os registros da conta) é recusada: o tables push sai com o código 2, com a tabela e a forma nova, e a nuvem recusa de novo. Para manter o que ela fazia, leve a lista para device.account e ponha em device.device o que a placa faz nos próprios registros (as quatro palavras, para ficar como era).
Na tela do portal
A tela Declarar tabela (na aba Banco de dados do produto e no banco da conta) mostra as permissões numa grade de quem × escopo, com as quatro ações:
| Quem e escopo | Ler | Inserir | Alterar | Remover |
|---|---|---|---|---|
Placa, nos próprios registros (device.device) | ||||
Placa, nos registros da conta (device.account) | ✓ | |||
Convidado, no dispositivo do convite (guest.device) | ||||
Convidado, nos registros da conta (guest.account) |
Assim começa uma tabela nova: a linha da placa nos próprios registros vem vazia, e quem declara escolhe. Na edição de uma tabela, a grade mostra o que está guardado.
As tabelas declaradas antes
As tabelas declaradas antes desta permissão (nas contas e nos produtos) ficaram com as quatro ações da placa nos próprios registros, o que ela já podia: nenhuma placa em campo passa a receber proibido. O tables get devolve cada tabela já na forma nova, com as quatro listas explícitas, pronta para o próximo push; para tirar da placa o que ela não usa, mude o device.device e mande de novo.
Mudar a declaração com placas em campo
- Adicionar uma tabela ou um campo: sempre.
- Remover um campo: a placa antiga que ainda o manda continua gravando: o campo removido é descartado na gravação (da inserção e do
set), e o resto grava. Num filtro, ele conta como ausente. Um campo que nunca existiu na tabela continuainvalido. - Trocar o tipo de um campo, existente ou removido antes: nunca. A nuvem recusa a declaração (o
tables pushsai com o código 5 e o motivo); para isso, crie outra tabela. - Remover uma tabela: ela sai de todas as contas donas com os registros, sem volta; depois disso, o pedido da placa a ela é
nao_existe. A aba do produto avisa antes; otables pushnão pergunta, então confira a lista antes de mandar.
Na placa
A placa precisa ter dono (no limbo, a resposta é proibido). Os registros ficam na nuvem em texto claro, fora da cifragem de ponta a ponta do modo cofre.
Cada pedido diz o escopo: DEVUI_DB_DEVICE (os registros desta placa) ou DEVUI_DB_ACCOUNT (os da conta dona). Em cada um, a placa só faz o que a tabela deixa naquele escopo (device.device ou device.account). O SDK monta o pedido em JSON e põe nele o escopo; o app nunca o escreve.
| Função | O que faz | A resposta (JSON) |
|---|---|---|
devui_db_insert(escopo, tabela, registro, cb, ctx) | grava um registro (um objeto JSON plano: {"valor":550}) | {"id":"<24 hex>","ts":"<ISO>"} |
devui_db_update(escopo, tabela, id, set, cb, ctx) | muda os campos de set no registro id (null remove um campo) | {"ok":true} |
devui_db_delete(escopo, tabela, id, cb, ctx) | remove o registro id | {"ok":true} |
devui_db_find(escopo, tabela, consulta, cb, ctx) | registros por filter, sort, limit (1 a 100; sem consulta, os 50 primeiros por ts) e cursor | {"records":[...],"cursor":...} |
devui_db_aggregate(escopo, tabela, consulta, cb, ctx) | soma, média, mínimo, máximo e contagem (calc, até 8), por group_by (um campo, day, week ou month) no fuso tz (UTC por padrão) | {"groups":[...]} |
devui_db_request(escopo, op, tabela, consulta, cb, ctx) | o genérico, também com update_where e delete_where | a da operação |
O exemplo grava um crédito e soma os do mês:
static void on_inserted(const devui_db_result_t *r, void *ctx)
{
if (r->status == DEVUI_DB_OK) {
printf("gravado: %.*s\n", (int)r->len, r->answer); /* answer não termina em NUL */
}
}
devui_db_insert(DEVUI_DB_DEVICE, "creditos", "{\"valor\":550}", on_inserted, NULL);
devui_db_aggregate(DEVUI_DB_DEVICE, "creditos",
"{\"filter\":{\"ts\":{\"gte\":\"2026-11-01\",\"lt\":\"2026-12-01\"}},\"tz\":\"America/Sao_Paulo\","
"\"calc\":{\"total\":{\"sum\":\"valor\"},\"quantidade\":{\"count\":true}}}",
on_sum, NULL);
O callback vem uma vez, na task do SDK (curto, sem bloquear, como os outros), com um devui_db_result_t: o status, a resposta em JSON (answer e len, sem NUL no fim, válida só durante o callback) e a espera pedida (retry_after_ms).
status | O que quer dizer |
|---|---|
DEVUI_DB_OK | feito; answer tem a resposta |
DEVUI_DB_INVALID | o pedido ou o registro fora do esquema da tabela; a resposta diz o campo |
DEVUI_DB_FORBIDDEN | a placa está no limbo, ou a tabela não deixa as placas fazerem isso no escopo pedido (nos próprios registros ou nos da conta) |
DEVUI_DB_NOT_FOUND | a tabela não foi declarada (nem na conta, nem no produto), o produto a removeu, ou o registro não existe |
DEVUI_DB_QUOTA | a cota do plano (registros guardados ou escritas do mês) |
DEVUI_DB_LIMIT | escritas ou leituras demais por minuto, ou 4 pedidos de uma vez; retry_after_ms diz quanto esperar |
DEVUI_DB_UNAVAILABLE | o banco fora do ar, sem resposta em 10 s, ou a conexão caiu antes: pode ter sido feito |
DEVUI_DB_TOO_LARGE | um registro acima de 2 KB ou de 32 campos, ou uma resposta maior do que a placa recebe (peça menos registros por página) |
DEVUI_DB_ERROR | uma resposta que esta versão não conhece, ou a nuvem recusou o quadro (error_code) |
A chamada em si devolve ESP_OK (o callback vem), ou recusa na hora, sem mandar nada: ESP_ERR_INVALID_ARG (um escopo, uma tabela, um id ou um JSON que o SDK recusa), ESP_ERR_INVALID_SIZE (o pedido acima do teto, abaixo), ESP_ERR_INVALID_STATE (sem nuvem e sem a fila), DEVUI_ERR_DB_LIMIT (4 pedidos esperam resposta) ou ESP_ERR_NO_MEM (a fila de envio do SDK cheia). A lista inteira está na referência da API em C.
Na biblioteca Arduino, os mesmos pedidos são DevUI.dbInsert, dbUpdate, dbDelete, dbFind, dbAggregate, dbRequest e dbQueue (A biblioteca Arduino). O binding Rust ainda não os tem.
Sem nuvem: a fila de inserções
Sem nuvem, um pedido é recusado na hora (ESP_ERR_INVALID_STATE), a não ser que o app ligue a fila de inserções:
devui_db_queue(DEVUI_DB_QUEUE_FLASH, 50, 2048); /* até 50 registros em 2 KB, guardados também na NVS */
Com ela ligada, toda inserção passa por ela, com nuvem ou sem: espera com um op_id sorteado na placa (16 dígitos hex) e vai na ordem, uma de cada vez, quando a conexão está pronta. Depois de limite, indisponivel, 10 s sem resposta ou uma queda, vai de novo com o mesmo op_id, e a nuvem não grava de novo um op_id que já gravou nas últimas 24 h: o registro que a nuvem gravou antes de a conexão cair, sem que a resposta chegasse, aparece uma vez.
DEVUI_DB_QUEUE_RAM: na RAM; um reinício perde o que esperava.DEVUI_DB_QUEUE_FLASH: na RAM e na NVS, regravada a cada mudança; sobrevive a um reinício. AtéDEVUI_DB_QUEUE_FLASH_MAX(2.048 B), porque a fila divide a NVS do SDK com a chave. No ESP8266, só a RAM.DEVUI_DB_QUEUE_OFF: desliga (o padrão); o que esperava termina comDEVUI_DB_UNAVAILABLE.
Só as inserções entram na fila: uma busca, uma soma, uma mudança ou uma remoção sem nuvem é recusada na hora. O modo local não é nuvem: vale o mesmo. A fila é do dono: uma troca de dono, ou a volta ao limbo, a esvazia, e cada registro termina com DEVUI_DB_FORBIDDEN.
Limites
| Limite | Valor | Quem fixa |
|---|---|---|
| Escritas por placa | 60 por minuto, com rajada de 10 | a nuvem (DEVUI_DB_LIMIT) |
| Leituras por placa | 120 por minuto, com rajada de 20 | a nuvem (DEVUI_DB_LIMIT) |
| Pedidos esperando resposta ao mesmo tempo | 4 | a placa (DEVUI_ERR_DB_LIMIT, sem ir ao fio) e a nuvem |
| Pedido, em JSON | até 4.083 B (1.011 B no ESP8266); a inserção da fila, até 4.055 B (983 B), que ganha o op_id | a placa (ESP_ERR_INVALID_SIZE) |
| Registro | até 2 KB e 32 campos | a nuvem (DEVUI_DB_TOO_LARGE) |
| Espera pela resposta | 10 s; depois, DEVUI_DB_UNAVAILABLE | a placa |
| Fila de inserções na NVS | até 2.048 B | a placa (DEVUI_DB_QUEUE_FLASH_MAX) |
| Tabelas do produto | até 64, de 1 a 32 campos cada | a nuvem e a CLI |
| Registros guardados e escritas do mês | a cota do plano da conta dona | a nuvem (DEVUI_DB_QUOTA) |
Os outros limites da conexão estão em Limites e números medidos.
