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é odevui_start:DevUI.begin(DEVUI_BUNDLE)sobe o SDK com oDEVUI_CONFIG_DEFAULT()e a interface que odevui_bundle.hembute;DevUI.begin(cfg), com umdevui_config_tinteiro (project_key,fw_version, as opções...), que é copiado;- o
ctxdos callbacks e asflagsdosendsão opcionais (nullptre0, bytes); - o código de pareamento vai para a
Serialsem o sketch pedir (a não ser comDEVUI_ARDUINO_SERIAL=0, abaixo); DevUI.calltem os parâmetros numa ordem diferente da dodevui_call: o callback e octxvê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
| Arduino | C | O que faz |
|---|---|---|
begin(const DevUIBundle &ui) | devui_start | sobe o SDK com a configuração padrão e esta interface |
begin(const devui_config_t &cfg) | devui_start | sobe o SDK com uma configuração inteira |
stop() | devui_stop | para o SDK |
onMessage(cb, ctx) | devui_on_message | o callback das mensagens das abas |
onEvent(cb, ctx) | devui_on_event | o callback dos eventos (depois do tratador do begin, que põe o código na serial) |
send(sessao, dados, tamanho, flags) | devui_send | manda a uma aba, ou a todas (DEVUI_ALL) |
reply(pedido, dados, tamanho) | devui_reply | responde a um pedido da página |
sessionInfo(sessao, &info) | devui_session_info | se a sessão está aberta, o papel e o tipo |
status() | devui_status | parado, conectando ou online |
pairBegin() | devui_pair_begin | pede um código de pareamento |
pairConfirm() | devui_pair_confirm | confirma o pareamento pelo botão |
factoryReset() | devui_factory_reset | reset de fábrica: avisa a nuvem e apaga a chave |
local() | devui_local | o modo local (Modo local) |
localSecret(texto, tamanho) | devui_local_secret | a senha local |
localSecretRenew() | devui_local_secret_renew | sorteia outra senha local |
trustOrderLocal(ordem, tamanho) | devui_trust_order_local | uma ordem de confiança trazida por um caminho local |
audit(texto) | devui_audit | um evento de negócio no log do dispositivo |
sessionClose(sessao, motivo) | devui_session_close | o firmware fecha uma sessão (4405 recusa uma máquina) |
call(apelido, dados, tamanho, cb, ctx, prazo_ms) | devui_call | chama outra placa pelo apelido (a ordem acima) |
dbInsert(escopo, tabela, registro, cb, ctx) | devui_db_insert | grava um registro (Banco de dados) |
dbUpdate(escopo, tabela, id, set, cb, ctx) | devui_db_update | muda campos de um registro |
dbDelete(escopo, tabela, id, cb, ctx) | devui_db_delete | remove um registro |
dbFind(escopo, tabela, consulta, cb, ctx) | devui_db_find | busca registros |
dbAggregate(escopo, tabela, consulta, cb, ctx) | devui_db_aggregate | soma, média, mínimo, máximo, contagem |
dbRequest(escopo, op, tabela, consulta, cb, ctx) | devui_db_request | o pedido genérico ao banco |
dbQueue(onde, maxRegistros, maxBytes) | devui_db_queue | a fila de inserções sem nuvem |
vaultPskText(texto, tamanho) | devui_vault_psk_text | o PSK do modo cofre, como a pessoa digita |
vaultReset(novoPsk) | devui_vault_reset | apaga a lista de acesso do cofre (e, com true, sorteia PSK novo) |
vaultEnroll(aberta) | devui_vault_enroll | abre ou fecha a inscrição no cofre |
getPrefs(&prefs) | devui_get_prefs | o fuso e o idioma da conta dona (Preferências da conta) |
deviceId() | devui_device_id | o 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,localSecretelocalSecretRenewrespondemESP_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,vaultResetevaultEnrollrespondemESP_ERR_NOT_SUPPORTED. - ESP8266: sem ordens de confiança; a fila do banco só na RAM (
dbQueuecomDEVUI_DB_QUEUE_FLASHrespondeESP_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 noloop().
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.
