Pular para o conteúdo
ThingFace

A biblioteca Arduino

A biblioteca ThingFace (classe DevUI, cabeçalho DevUI.h) é uma casca fina em C++ sobre o SDK em C, para a família ESP32 no core Arduino 3.3 (ESP-IDF 5.5) e no PlatformIO com o pioarduino, e para o ESP8266 no core 3.1.2 (O SDK no ESP8266). Cada método é uma função de devui.h, com os mesmos argumentos, os mesmos erros e as mesmas regras de task: o contrato é o da referência da API em C.

A regra do nome

O método é o nome da função C sem o prefixo devui_, em camelCase: devui_factory_reset é factoryReset, devui_db_insert é dbInsert, devui_get_prefs é getPrefs. As exceções são do jeito do Arduino:

  • begin é o devui_start: DevUI.begin(DEVUI_BUNDLE) sobe o SDK com o DEVUI_CONFIG_DEFAULT() e a interface que o devui_bundle.h embute; DevUI.begin(cfg), com um devui_config_t inteiro (project_key, fw_version, as opções...), que é copiado;
  • o ctx dos callbacks e as flags do send são opcionais (nullptr e 0, bytes);
  • o código de pareamento vai para a Serial sem o sketch pedir (a não ser com DEVUI_ARDUINO_SERIAL=0, abaixo);
  • DevUI.call tem os parâmetros numa ordem diferente da do devui_call: o callback e o ctx vêm antes do prazo, para o prazo poder ser omitido. Em C, devui_call(apelido, dados, tamanho, prazo_ms, cb, ctx); no Arduino, DevUI.call(apelido, dados, tamanho, cb, ctx = nullptr, prazo_ms = 0) (0 é o máximo, 10 s).

Os métodos

ArduinoCO que faz
begin(const DevUIBundle &ui)devui_startsobe o SDK com a configuração padrão e esta interface
begin(const devui_config_t &cfg)devui_startsobe o SDK com uma configuração inteira
stop()devui_stoppara o SDK
onMessage(cb, ctx)devui_on_messageo callback das mensagens das abas
onEvent(cb, ctx)devui_on_evento callback dos eventos (depois do tratador do begin, que põe o código na serial)
send(sessao, dados, tamanho, flags)devui_sendmanda a uma aba, ou a todas (DEVUI_ALL)
reply(pedido, dados, tamanho)devui_replyresponde a um pedido da página
sessionInfo(sessao, &info)devui_session_infose a sessão está aberta, o papel e o tipo
status()devui_statusparado, conectando ou online
pairBegin()devui_pair_beginpede um código de pareamento
pairConfirm()devui_pair_confirmconfirma o pareamento pelo botão
factoryReset()devui_factory_resetreset de fábrica: avisa a nuvem e apaga a chave
local()devui_localo modo local (Modo local)
localSecret(texto, tamanho)devui_local_secreta senha local
localSecretRenew()devui_local_secret_renewsorteia outra senha local
trustOrderLocal(ordem, tamanho)devui_trust_order_localuma ordem de confiança trazida por um caminho local
audit(texto)devui_auditum evento de negócio no log do dispositivo
sessionClose(sessao, motivo)devui_session_closeo firmware fecha uma sessão (4405 recusa uma máquina)
call(apelido, dados, tamanho, cb, ctx, prazo_ms)devui_callchama outra placa pelo apelido (a ordem acima)
dbInsert(escopo, tabela, registro, cb, ctx)devui_db_insertgrava um registro (Banco de dados)
dbUpdate(escopo, tabela, id, set, cb, ctx)devui_db_updatemuda campos de um registro
dbDelete(escopo, tabela, id, cb, ctx)devui_db_deleteremove um registro
dbFind(escopo, tabela, consulta, cb, ctx)devui_db_findbusca registros
dbAggregate(escopo, tabela, consulta, cb, ctx)devui_db_aggregatesoma, média, mínimo, máximo, contagem
dbRequest(escopo, op, tabela, consulta, cb, ctx)devui_db_requesto pedido genérico ao banco
dbQueue(onde, maxRegistros, maxBytes)devui_db_queuea fila de inserções sem nuvem
vaultPskText(texto, tamanho)devui_vault_psk_texto PSK do modo cofre, como a pessoa digita
vaultReset(novoPsk)devui_vault_resetapaga a lista de acesso do cofre (e, com true, sorteia PSK novo)
vaultEnroll(aberta)devui_vault_enrollabre ou fecha a inscrição no cofre
getPrefs(&prefs)devui_get_prefso fuso e o idioma da conta dona (Preferências da conta)
deviceId()devui_device_ido device_id em base32, depois do begin

Os tipos, os eventos e as constantes são os mesmos do C (devui_msg_t, devui_event_t, DEVUI_EV_*, DEVUI_DB_*...): o DevUI.h inclui o devui.h.

A atualização remota de firmware é a classe DevUIOta (#include <DevUIOta.h>, antes do DevUI.begin), a mesma do devui_ota do ESP-IDF, no ESP32 e no ESP8266: Atualização remota de firmware, seções Arduino-ESP32 e ESP8266.

O que não existe em cada placa

  • Modo local: o pacote Arduino é compilado sem o CONFIG_DEVUI_LOCAL; local, localSecret e localSecretRenew respondem ESP_ERR_NOT_SUPPORTED, no ESP32 e no ESP8266.
  • Modo cofre: só no ESP32 com o CONFIG_DEVUI_VAULT, que o pacote não liga; sem ele, e sempre no ESP8266, vaultPskText, vaultReset e vaultEnroll respondem ESP_ERR_NOT_SUPPORTED.
  • ESP8266: sem ordens de confiança; a fila do banco só na RAM (dbQueue com DEVUI_DB_QUEUE_FLASH responde ESP_ERR_NOT_SUPPORTED); pedido ao banco até 1.011 B; mensagens de até 1 KB. Lá, a API só vale na thread do sketch (setup(), loop() e os callbacks do SDK), e nada precisa ser chamado no loop().

Um exemplo

#include <WiFi.h>
#include <DevUI.h>
#include "devui_bundle.h"

void aoGravar(const devui_db_result_t *r, void *) {
  Serial.printf("banco: %u %.*s\n", r->status, (int)r->len, r->answer ? r->answer : "");
}

void aoMensagem(const devui_msg_t *m, void *) {
  DevUI.send(DEVUI_ALL, m->data, m->len);  // eco para todas as abas
  DevUI.dbInsert(DEVUI_DB_DEVICE, "creditos", "{\"valor\":550}", aoGravar);
}

void setup() {
  WiFi.begin("rede", "senha");
  DevUI.onMessage(aoMensagem);
  DevUI.begin(DEVUI_BUNDLE);  // 1º boot: gera a chave e põe o código de pareamento na serial
}

void loop() {}

A pasta web/ do sketch vira o devui_bundle.h com devui pack web/ (Referência da CLI). Um firmware sem interface (num produto com a interface na nuvem) passa um DevUIBundle vazio, {nullptr, 0, nullptr, 0, nullptr}, e não inclui devui_bundle.h (Firmware sem interface).

A Serial

DevUI.begin abre a Serial a 115200 quando o sketch não a abriu, e a casca escreve ali o código de pareamento e os avisos de onde está a chave. Numa placa cujo pino de TX da UART0 aciona outra coisa (um relé), compile com -D DEVUI_ARDUINO_SERIAL=0 (no PlatformIO, em build_flags): a casca nunca chama Serial.begin nem escreve na Serial, e o código chega ao app pelos eventos DEVUI_EV_PAIR_CODE e DEVUI_EV_PAIR_CODE_ACCEPTED, para a tela ou a página do produto.

A tabela de partições

A chave da placa mora na partição devui da tabela do SDK, que a biblioteca traz no partitions.csv da pasta de cada exemplo e em extras/partitions.csv. No Arduino IDE, deixe o partitions.csv na pasta do sketch e escolha Ferramentas > Partition Scheme > "Minimal SPIFFS (1.9MB APP with OTA/128KB SPIFFS)"; no PlatformIO, board_build.partitions = <a biblioteca>/extras/partitions.csv. Com a tabela padrão do core, a placa cria uma identidade nova na nvs comum e avisa na serial.

ESP32 sem PSRAM

No ESP32 clássico sem PSRAM, o mbedTLS do core como ele vem prende ~40 KB na conexão do SDK, e um segundo TLS do app (uma API HTTPS) pode não caber. A receita recomendada é recompilar o mbedTLS do core com buffers dinâmicos: ESP32 sem PSRAM no Arduino.