Skip to content
ThingFace

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:

  • begin is devui_start: DevUI.begin(DEVUI_BUNDLE) starts the SDK with DEVUI_CONFIG_DEFAULT() and the interface devui_bundle.h embeds; DevUI.begin(cfg), with a whole devui_config_t (project_key, fw_version, the options...), which is copied;
  • the callbacks' ctx and the flags of send are optional (nullptr and 0, bytes);
  • the pairing code goes to Serial with no call of the sketch (unless with DEVUI_ARDUINO_SERIAL=0, below);
  • DevUI.call takes its parameters in another order than devui_call: the callback and its ctx come 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

ArduinoCWhat it does
begin(const DevUIBundle &ui)devui_startstarts the SDK with the default configuration and this interface
begin(const devui_config_t &cfg)devui_startstarts the SDK with a whole configuration
stop()devui_stopstops the SDK
onMessage(cb, ctx)devui_on_messagethe callback of the tabs' messages
onEvent(cb, ctx)devui_on_eventthe callback of the events (after begin's handler, which puts the code on the serial)
send(session, data, len, flags)devui_sendsends to a tab, or to all (DEVUI_ALL)
reply(req, data, len)devui_replyanswers a request of the page
sessionInfo(session, &info)devui_session_infowhether the session is open, its role and its kind
status()devui_statusstopped, connecting or online
pairBegin()devui_pair_beginasks for a pairing code
pairConfirm()devui_pair_confirmconfirms the pairing by the button
factoryReset()devui_factory_resetfactory reset: tells the cloud and erases the key
local()devui_localthe local mode (Local mode)
localSecret(text, size)devui_local_secretthe local password
localSecretRenew()devui_local_secret_renewdraws another local password
trustOrderLocal(order, len)devui_trust_order_locala trust order brought by a local path
audit(text)devui_audita business event in the device's log
sessionClose(session, reason)devui_session_closethe firmware closes a session (4405 refuses a machine)
call(alias, data, len, cb, ctx, timeout_ms)devui_callcalls another board by its alias (the order above)
dbInsert(scope, table, record, cb, ctx)devui_db_insertwrites a record (Database)
dbUpdate(scope, table, id, set, cb, ctx)devui_db_updatechanges fields of a record
dbDelete(scope, table, id, cb, ctx)devui_db_deleteremoves a record
dbFind(scope, table, query, cb, ctx)devui_db_findfinds records
dbAggregate(scope, table, query, cb, ctx)devui_db_aggregatesum, average, minimum, maximum, count
dbRequest(scope, op, table, query, cb, ctx)devui_db_requestthe generic request to the database
dbQueue(where, maxRecords, maxBytes)devui_db_queuethe queue of inserts with no cloud
vaultPskText(text, size)devui_vault_psk_textthe vault mode's PSK, as a person types it
vaultReset(newPsk)devui_vault_reseterases the vault's access list (and, with true, draws a new PSK)
vaultEnroll(open)devui_vault_enrollopens or closes the enrollment in the vault
getPrefs(&prefs)devui_get_prefsthe owner account's time zone and language (The account's preferences)
deviceId()devui_device_idthe 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, localSecret and localSecretRenew answer ESP_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, vaultReset and vaultEnroll answer ESP_ERR_NOT_SUPPORTED.
  • ESP8266: no trust orders; the database's queue in the RAM only (dbQueue with DEVUI_DB_QUEUE_FLASH answers ESP_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 in loop().

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.