The Arduino library
The ThingFace library (the class DevUI, the header DevUI.h) is a thin C++ shell over the SDK in C, for the ESP32 family on the Arduino core 3.3 (ESP-IDF 5.5) and on PlatformIO with pioarduino, and for the ESP8266 on the core 3.1.2 (The SDK on the ESP8266, in Portuguese). Each method is one function of devui.h, with the same arguments, the same errors and the same task rules: the contract is the C API reference's.
The naming rule
The method is the C function's name without the devui_ prefix, in camelCase: devui_factory_reset is factoryReset, devui_db_insert is dbInsert, devui_get_prefs is getPrefs. The exceptions are Arduino's habits:
beginisdevui_start:DevUI.begin(DEVUI_BUNDLE)starts the SDK withDEVUI_CONFIG_DEFAULT()and the interfacedevui_bundle.hembeds;DevUI.begin(cfg), with a wholedevui_config_t(project_key,fw_version, the options...), which is copied;- the callbacks'
ctxand theflagsofsendare optional (nullptrand0, bytes); - the pairing code goes to
Serialwith no call of the sketch (unless withDEVUI_ARDUINO_SERIAL=0, below); DevUI.calltakes its parameters in another order thandevui_call: the callback and itsctxcome before the timeout, so the timeout may be left out. In C,devui_call(alias, data, len, timeout_ms, cb, ctx); on Arduino,DevUI.call(alias, data, len, cb, ctx = nullptr, timeout_ms = 0)(0 is the most, 10 s).
The methods
| Arduino | C | What it does |
|---|---|---|
begin(const DevUIBundle &ui) | devui_start | starts the SDK with the default configuration and this interface |
begin(const devui_config_t &cfg) | devui_start | starts the SDK with a whole configuration |
stop() | devui_stop | stops the SDK |
onMessage(cb, ctx) | devui_on_message | the callback of the tabs' messages |
onEvent(cb, ctx) | devui_on_event | the callback of the events (after begin's handler, which puts the code on the serial) |
send(session, data, len, flags) | devui_send | sends to a tab, or to all (DEVUI_ALL) |
reply(req, data, len) | devui_reply | answers a request of the page |
sessionInfo(session, &info) | devui_session_info | whether the session is open, its role and its kind |
status() | devui_status | stopped, connecting or online |
pairBegin() | devui_pair_begin | asks for a pairing code |
pairConfirm() | devui_pair_confirm | confirms the pairing by the button |
factoryReset() | devui_factory_reset | factory reset: tells the cloud and erases the key |
local() | devui_local | the local mode (Local mode) |
localSecret(text, size) | devui_local_secret | the local password |
localSecretRenew() | devui_local_secret_renew | draws another local password |
trustOrderLocal(order, len) | devui_trust_order_local | a trust order brought by a local path |
audit(text) | devui_audit | a business event in the device's log |
sessionClose(session, reason) | devui_session_close | the firmware closes a session (4405 refuses a machine) |
call(alias, data, len, cb, ctx, timeout_ms) | devui_call | calls another board by its alias (the order above) |
dbInsert(scope, table, record, cb, ctx) | devui_db_insert | writes a record (Database) |
dbUpdate(scope, table, id, set, cb, ctx) | devui_db_update | changes fields of a record |
dbDelete(scope, table, id, cb, ctx) | devui_db_delete | removes a record |
dbFind(scope, table, query, cb, ctx) | devui_db_find | finds records |
dbAggregate(scope, table, query, cb, ctx) | devui_db_aggregate | sum, average, minimum, maximum, count |
dbRequest(scope, op, table, query, cb, ctx) | devui_db_request | the generic request to the database |
dbQueue(where, maxRecords, maxBytes) | devui_db_queue | the queue of inserts with no cloud |
vaultPskText(text, size) | devui_vault_psk_text | the vault mode's PSK, as a person types it |
vaultReset(newPsk) | devui_vault_reset | erases the vault's access list (and, with true, draws a new PSK) |
vaultEnroll(open) | devui_vault_enroll | opens or closes the enrollment in the vault |
getPrefs(&prefs) | devui_get_prefs | the owner account's time zone and language (The account's preferences) |
deviceId() | devui_device_id | the device_id in base32, after begin |
The types, the events and the constants are the same as C's (devui_msg_t, devui_event_t, DEVUI_EV_*, DEVUI_DB_*...): DevUI.h includes devui.h.
The remote firmware update is the class DevUIOta (#include <DevUIOta.h>, before DevUI.begin), the same as the ESP-IDF's devui_ota, on the ESP32 and the ESP8266: Remote firmware update, sections Arduino-ESP32 and ESP8266.
What each board does not have
- Local mode: the Arduino package is built without
CONFIG_DEVUI_LOCAL;local,localSecretandlocalSecretRenewanswerESP_ERR_NOT_SUPPORTED, on the ESP32 and on the ESP8266. - Vault mode: only on the ESP32 with
CONFIG_DEVUI_VAULT, which the package does not turn on; without it, and always on the ESP8266,vaultPskText,vaultResetandvaultEnrollanswerESP_ERR_NOT_SUPPORTED. - ESP8266: no trust orders; the database's queue in the RAM only (
dbQueuewithDEVUI_DB_QUEUE_FLASHanswersESP_ERR_NOT_SUPPORTED); a request to the database up to 1,011 B; messages of up to 1 KB. There, the API holds only in the sketch's thread (setup(),loop()and the SDK's callbacks), and nothing needs to be called inloop().
An example
#include <WiFi.h>
#include <DevUI.h>
#include "devui_bundle.h"
void onWritten(const devui_db_result_t *r, void *) {
Serial.printf("db: %u %.*s\n", r->status, (int)r->len, r->answer ? r->answer : "");
}
void onMessage(const devui_msg_t *m, void *) {
DevUI.send(DEVUI_ALL, m->data, m->len); // echo to every tab
DevUI.dbInsert(DEVUI_DB_DEVICE, "creditos", "{\"valor\":550}", onWritten);
}
void setup() {
WiFi.begin("network", "password");
DevUI.onMessage(onMessage);
DevUI.begin(DEVUI_BUNDLE); // 1st boot: makes the key and puts the pairing code on the serial
}
void loop() {}
The sketch's web/ folder becomes devui_bundle.h with devui pack web/ (CLI reference). A firmware with no interface (in a product with its interface in the cloud) passes an empty DevUIBundle, {nullptr, 0, nullptr, 0, nullptr}, and does not include devui_bundle.h (Firmware without an interface).
The serial
DevUI.begin opens Serial at 115200 when the sketch has not, and the shell writes there the pairing code and the warnings of where the key is. On a board whose UART0 TX pin drives something else (a relay), build with -D DEVUI_ARDUINO_SERIAL=0 (on PlatformIO, in build_flags): the shell never calls Serial.begin nor writes to Serial, and the code reaches the app by the events DEVUI_EV_PAIR_CODE and DEVUI_EV_PAIR_CODE_ACCEPTED, for the product's display or page.
The partition table
The board's key lives in the devui partition of the SDK's table, which the library carries in the partitions.csv of each example's folder and in extras/partitions.csv. In the Arduino IDE, keep partitions.csv in the sketch's folder and pick Tools > Partition Scheme > "Minimal SPIFFS (1.9MB APP with OTA/128KB SPIFFS)"; on PlatformIO, board_build.partitions = <the library>/extras/partitions.csv. With the core's default table, the board makes a new identity in the common nvs and warns on the serial.
ESP32 without PSRAM
On the classic ESP32 without PSRAM, the core's mbedTLS as it ships holds ~40 KB in the SDK's connection, and a second TLS of the app (an HTTPS API) may not fit. The recommended recipe is to rebuild the core's mbedTLS with dynamic buffers: ESP32 without PSRAM on Arduino.
