Pular para o conteúdo
ThingFace

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.json

    O push confere 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 em versão N das tabelas do produto. O get imprime as tabelas em vigor, prontas para o próximo push (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 tipo text, number, boolean ou date. Os nomes seguem a regra do nome da tabela, e id, ts, device e account sã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 de read, insert, update e delete:
    • device.device (obrigatório): nos próprios registros (o escopo DEVUI_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 escopo DEVUI_DB_ACCOUNT, os compartilhados entre as placas da conta); sem ela, só read.
  • guest (opcional): o que o convidado pode fazer, em device (nos registros do dispositivo para o qual foi convidado) e em account (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 escopoLerInserirAlterarRemover
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 continua invalido.
  • Trocar o tipo de um campo, existente ou removido antes: nunca. A nuvem recusa a declaração (o tables push sai 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; o tables push nã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çãoO que fazA 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_wherea 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).

statusO que quer dizer
DEVUI_DB_OKfeito; answer tem a resposta
DEVUI_DB_INVALIDo pedido ou o registro fora do esquema da tabela; a resposta diz o campo
DEVUI_DB_FORBIDDENa 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_FOUNDa tabela não foi declarada (nem na conta, nem no produto), o produto a removeu, ou o registro não existe
DEVUI_DB_QUOTAa cota do plano (registros guardados ou escritas do mês)
DEVUI_DB_LIMITescritas ou leituras demais por minuto, ou 4 pedidos de uma vez; retry_after_ms diz quanto esperar
DEVUI_DB_UNAVAILABLEo banco fora do ar, sem resposta em 10 s, ou a conexão caiu antes: pode ter sido feito
DEVUI_DB_TOO_LARGEum 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_ERRORuma 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 com DEVUI_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

LimiteValorQuem fixa
Escritas por placa60 por minuto, com rajada de 10a nuvem (DEVUI_DB_LIMIT)
Leituras por placa120 por minuto, com rajada de 20a nuvem (DEVUI_DB_LIMIT)
Pedidos esperando resposta ao mesmo tempo4a placa (DEVUI_ERR_DB_LIMIT, sem ir ao fio) e a nuvem
Pedido, em JSONaté 4.083 B (1.011 B no ESP8266); a inserção da fila, até 4.055 B (983 B), que ganha o op_ida placa (ESP_ERR_INVALID_SIZE)
Registroaté 2 KB e 32 camposa nuvem (DEVUI_DB_TOO_LARGE)
Espera pela resposta10 s; depois, DEVUI_DB_UNAVAILABLEa placa
Fila de inserções na NVSaté 2.048 Ba placa (DEVUI_DB_QUEUE_FLASH_MAX)
Tabelas do produtoaté 64, de 1 a 32 campos cadaa nuvem e a CLI
Registros guardados e escritas do mêsa cota do plano da conta donaa nuvem (DEVUI_DB_QUOTA)

Os outros limites da conexão estão em Limites e números medidos.