C API reference (devui.h)
The SDK's public API on ESP-IDF and Arduino (the DevUI shell calls these functions, with the same errors). The text of each symbol is its comment in the header.
Overview
The public API of the SDK on ESP-IDF: twelve functions when it was frozen, on 16/10/2026, 29 today (besides devui_device_id), the other 17 added since (only additions). This header is the contract: each function says what it does, from which task it may be called and what each error means (the table below).
Threads. Everything runs in the SDK's own task, which owns the connection. The callbacks (devui_on_message, devui_on_event) run in that task too: they must be short and must not block (copy what they need and hand it to the app's own task). The functions may be called from any task, and from inside a callback. None may be called from an ISR.
The Wi-Fi belongs to the app: the SDK reacts to an IP on any interface (Wi-Fi or Ethernet) and to the loss of it.
Errors (devui_err_t is esp_err_t), the same meaning in every function:
ESP_OK done (for devui_send and devui_reply: copied to the queue; the cloud has not seen it yet)
ESP_ERR_INVALID_ARG a NULL that may not be, a session out of 1..0x7FFF (or of 0x8000..0xFFFE, the local mode's,
with CONFIG_DEVUI_LOCAL), an option bit this version does not
know, a bundle_sig of other than 72 bytes, or devui_reply to a message that is not a
request
ESP_ERR_INVALID_STATE not now: the SDK is stopped (or already running, for devui_start), offline (devui_send),
no button window open (devui_pair_confirm), or no entropy source for a key or a pairing
code (a radio on, or adc_hold)
ESP_ERR_NO_MEM the send queue is full: wait for DEVUI_EV_TX_READY and send again; or no memory at start
ESP_ERR_INVALID_SIZE a message above the largest one (the queue of the SDK, announced as MAX_TX_MSG)
ESP_ERR_NOT_FOUND devui_session_info: no such session open; devui_start with CONFIG_DEVUI_FACTORY_ID and
no factory key (the eFuse key, or the flash encryption on the ESP32, is the
manufacturer's; the SDK never writes one) or no partition devui_id in the table
ESP_ERR_NOT_SUPPORTED a feature this build leaves out: devui_local() without CONFIG_DEVUI_LOCAL (never on the
ESP8266); or, in a release build (CONFIG_DEVUI_TRUST_RELEASE),
devui_start with another host, port or ca_pem than DEVUI_CONFIG_DEFAULT()'s
ESP_ERR_TIMEOUT the SDK's task did not answer within the call's worst case (devui_pair_begin,
devui_pair_confirm, devui_factory_reset): it was held by the app's callbacks or by sends
queued before the call, or it is stuck (a bug, report it); the call still runs in that task
ESP_FAIL devui_start could not set up its key, its storage or its task (a stack of the task out
of the DRAM included, logged)
DEVUI_ERR_OVER_QUOTA above the plan's quota (QUOTA_MSGS_PER_S, QUOTA_BYTES_PER_S): refused here, before the
cloud's 4429; the next send in a moment goes through
DEVUI_ERR_HAS_OWNER devui_pair_begin on a device that already has an owner
DEVUI_ERR_STALE_REQUEST
devui_reply to a request of a connection that ended (offline, or reconnected since):
nothing is sent, and never will be; drop the answer (its page already failed the request
with OFFLINE). A request id names a request of its own connection only. It says nothing
of the request's age: an old request of a connection still up is answered; dropping a
request that waited too long in the app's queue is the app's (docs/confirmacao.md)
A function may also pass on an error of the ESP-IDF it called (an NVS error from devui_start, for one).
Functions
1. devui_start
devui_err_t devui_start(const devui_config_t *cfg);
Creates or loads the key and starts connecting; returns once the SDK's task runs. ESP_ERR_INVALID_ARG with no cfg or no host, or an unknown option bit; ESP_ERR_INVALID_STATE when already running, or when the key does not exist yet and no entropy source is on (Wi-Fi or BT started, or adc_hold): the key is never born weak; ESP_ERR_NOT_SUPPORTED with a reserved field set; ESP_ERR_NOT_FOUND with CONFIG_DEVUI_FACTORY_ID and no factory key or no partition devui_id (the key is never born without the manufacturer's); ESP_ERR_INVALID_CRC when the manifest's container_sha256 is not the SHA-256 of the bundle (one of the two edited by hand, or of different packs: pack the web folder again); ESP_FAIL when the SDK's task cannot be set up, its stack out of the DRAM included (a task 3 to 10 times slower, refused, and logged). The config is copied; the strings and the bundle it points to must outlive the SDK. Call it after nvs_flash_init() and after starting the Wi-Fi.
2. devui_stop
devui_err_t devui_stop(void);
Closes the connection and stops the SDK (the key stays); ESP_ERR_INVALID_STATE when stopped. Returns at once: the status becomes DEVUI_STATUS_STOPPED shortly after, once the connection's memory (its TLS session) is back in the heap, so an app may stop the SDK to open a TLS of its own and wait for that status (a few hundred ms). With the client stuck in its close, STOPPED goes out anyway 20 s after the stop, and the log says the memory is not back. A devui_start afterwards connects again; the database's queue in the flash stays, and devui_db_queue takes it back.
3. devui_on_message
void devui_on_message(void (*cb)(const devui_msg_t *m, void *ctx), void *ctx);
The callback of the pages' messages; NULL removes it. Set it before devui_start, or swap it at any time, from any task (never from an ISR): the callback and its ctx go as one pair, so a callback is always called with the ctx given with it; and once this returns, the earlier callback is neither running nor called again (it waits for a call in progress to return), so its ctx can be freed. Since it waits, never call it holding what the callback may wait for (a mutex the callback takes, a queue that only the calling task drains): each would wait for the other for ever. From inside a callback it does not wait: the calls that start after it get the new pair (the running one keeps its ctx until it returns).
4. devui_on_event
void devui_on_event(void (*cb)(const devui_event_t *ev, void *ctx), void *ctx);
The callback of the events; NULL removes it. As devui_on_message.
5. devui_send
devui_err_t devui_send(uint16_t session, const void *data, size_t len, uint32_t flags);
Copies to a bounded queue and returns at once; delivery is at most once, in order. session: a tab's session, or DEVUI_ALL; flags: DEVUI_TEXT, DEVUI_STATE. ESP_ERR_INVALID_STATE offline, ESP_ERR_NO_MEM queue full (wait for DEVUI_EV_TX_READY), ESP_ERR_INVALID_SIZE above the largest message, DEVUI_ERR_OVER_QUOTA above the plan's quota. A message waits in the SDK while the cloud gives no credit, in order, and goes in pieces when it is bigger than a frame. Nothing is kept across a reconnection: repeating is the app's choice.
6. devui_reply
devui_err_t devui_reply(const devui_msg_t *req, const void *data, size_t len);
The answer to a request (req->flags has DEVUI_REQUEST), to the tab that asked only. Call it in the callback or keep a copy of req's session, id, flags and conn. A request is answered only on the connection it came on: its id is that connection's, and on a later one it would name another request (decision of 16/10). ESP_ERR_INVALID_ARG when req is not a request; DEVUI_ERR_STALE_REQUEST, with nothing sent, when the request's connection ended (the SDK offline or stopped, or online again on a new connection; a conn of 0, never given, too); then ESP_ERR_NO_MEM, ESP_ERR_INVALID_SIZE and DEVUI_ERR_OVER_QUOTA as devui_send. A reply taken (ESP_OK) whose connection ends before it leaves the SDK is dropped, as a send is.
7. devui_session_info
devui_err_t devui_session_info(uint16_t session, devui_session_info_t *out);
Whether a session is open, its role and its kind (a person's tab or a call of the API): ESP_OK, ESP_ERR_NOT_FOUND, ESP_ERR_INVALID_ARG for session 0.
8. devui_status
devui_status_t devui_status(void);
Stopped, connecting or online.
9. devui_pair_begin
devui_err_t devui_pair_begin(void);
Pairing: a new code of 8 characters (40 bits of the RNG, under the entropy guard of the key; the retries' jitter draws from the common RNG, with no guard), told in DEVUI_EV_PAIR_CODE with its URL, sent to the cloud once online in the limbo and kept alive by the SDK (a new one 10 s before its 10 min end; the same one again on a reconnection with more than 60 s left; after a 4429, more than one a minute, the same one again once the wait passed) until the device is paired. A reboot keeps it too: the code is in the NVS with its end in the cloud's time, and the first connection of the new boot brings it back (the event with what it has left) when it has more than 60 s left, so a link already handed out still pairs. Offline, a code is handed out at once, so it can be shown before connecting: before the boot's first connection, the earlier boot's code when the NVS has one (the event with 600 s, the most it can have; the connection tells it again with what it has left or, with 60 s or less left, puts a new code in its place), else a new one, which stays at the connection. Runs in the SDK's task and waits for it up to 14.5 s (the code's send on a network with no room takes up to 12.5 s). ESP_OK; DEVUI_ERR_HAS_OWNER when the last HELLO_ACK (kept in the NVS, so also one of an earlier boot) said the device has an owner; ESP_ERR_INVALID_STATE when the SDK is stopped or has no entropy source.
10. devui_pair_confirm
devui_err_t devui_pair_confirm(void);
One press of the button, after DEVUI_EV_PAIR_BUTTON: the SDK counts the presses and tells the cloud 5 s after the last one, or at the end of the window. ESP_ERR_INVALID_STATE with no BUTTON open.
11. devui_factory_reset
devui_err_t devui_factory_reset(void);
Factory reset: with the SDK running and online, UNPAIR goes to the cloud (which tells the owner), signed with the device's key (the cloud checks it before it marks the reset), the connection closes with 1000, and only then the key and the SDK's data (its NVS namespace, but for the clock floor, which stays) are erased and the SDK stops; offline or stopped, it erases at once. DEVUI_EV_UNPAIRED follows, and the next devui_start makes a new key: a new device_id (with CONFIG_DEVUI_FACTORY_ID the factory key stays, in the partition devui_id or in the eFuse, and the device comes back with the same device_id). The app's own data (Wi-Fi, settings) are the app's to erase. Runs in the SDK's task and waits for it up to 17.5 s, the reset's worst case: the UNPAIR's send on a network with no room (up to 12.5 s), the close (up to 3 s) and the erase. With ESP_ERR_TIMEOUT the reset still ends in the SDK's task: restart only after DEVUI_EV_UNPAIRED, or the key may stay.
12. devui_local
devui_err_t devui_local(void);
The local mode (AP and LAN): the board serves its own UI (the bundle of the config), the lib and /_devui/env at http://<its IP>/ on port 80 of every interface the app brought up (the station on the LAN, the app's AP, the Ethernet), for when the cloud is out or far. Never without a password: a browser opens the page only after the board's login, with the local password (devui_local_secret) the app shows to the owner; 5 wrong tries in a row lock the login for 30 s, doubling up to 15 min; a login lives 30 days or until the board restarts. Never on an open AP: the app's AP must have WPA2 or WPA3. Each tab is a session of 0x8000..0xFFFE, kind DEVUI_SESSION_LOCAL, role operator: devui_send, devui_reply, devui_session_info and devui_session_close take it, and DEVUI_ALL reaches the local tabs too, the cloud's when online. The traffic on the LAN is plain HTTP (no certificate a browser takes for a private IP): what the UI sends there, anyone who listens to that network sees. Call it after devui_start, from any task: ESP_OK (also when it already runs); ESP_ERR_INVALID_STATE with the SDK stopped, with no entropy source for the password's first time (a radio on), or with the app's AP open; ESP_ERR_NOT_SUPPORTED in a build without CONFIG_DEVUI_LOCAL (and always on the ESP8266); ESP_FAIL when the HTTP server does not start; then ESP_ERR_TIMEOUT as the other calls that run in the SDK's task. devui_stop and devui_factory_reset end it.
devui_local_secret
devui_err_t devui_local_secret(char *out, size_t size);
The local password, as people read it ("XXXX-XXXX-XXXX-XXXX", 16 characters of Crockford base32: 80 bits born on the board, under the key's entropy guard, at the first devui_local). For the app to show it to the owner (a display, a label, the serial, or its UI in the cloud to the owner's role only): the cloud never sees it, and the SDK never logs it. It stays across reboots and goes with devui_factory_reset. out: DEVUI_LOCAL_SECRET_SIZE bytes or more. ESP_OK; ESP_ERR_INVALID_ARG (NULL, or too small); ESP_ERR_INVALID_STATE before the first devui_local; ESP_ERR_NOT_SUPPORTED without CONFIG_DEVUI_LOCAL. Added after the v1 was frozen (it grows only by additions).
devui_local_secret_renew
devui_err_t devui_local_secret_renew(void);
A new local password, kept at once: every browser logged in leaves and every local tab closes (its session event comes). ESP_OK; ESP_ERR_INVALID_STATE with the local mode off or no entropy; ESP_ERR_NOT_SUPPORTED without CONFIG_DEVUI_LOCAL; ESP_FAIL when the NVS does not keep it (the old one stays). Added after the v1 was frozen.
devui_trust_order_local
devui_err_t devui_trust_order_local(const uint8_t *order, size_t len);
A trust order brought by a local path (the serial, Improv, the maker's OTA): the same object the cloud sends in TRUST_ORDER ("DVO", up to 4,093 B), checked and kept exactly as one from the cloud, in the SDK's task (a DEVUI_EV_TRUST_ORDER event follows, as for one from the cloud). ESP_OK accepted; ESP_ERR_INVALID_ARG refused (the reason on the log: signature, scope, seq...) or no object; ESP_ERR_INVALID_STATE with the SDK stopped or a build with no order keys. Added in 1.2 (the v1 API grows only by additions).
devui_audit
devui_err_t devui_audit(const char *text);
A business event of the firmware for the device's log in the portal: "abriu o portão", in text, NUL-terminated, 1 to DEVUI_AUDIT_MAX bytes of UTF-8 with no control character (no line break) and none of the invisible ones that break or reorder a line: U+2028, U+2029, the bidirectional controls (U+061C, U+200E, U+200F, U+202A-U+202E, U+2066-U+2069) and the BOM (U+FEFF); the zero width joiner (U+200D) of the emoji is text. The device says only what happened: the cloud writes it with its own time (never the device's, which goes apart, and only when the device's clock is valid) and with who had the UI open then; with nobody, the event still counts. Runs in the SDK's task and returns once the event went to the connection: delivery is at most once, nothing is kept for a later connection, and the cloud does not confirm the write. The owner sees it on the device's events page.
ESP_OK sent
ESP_ERR_INVALID_ARG NULL, empty, longer than DEVUI_AUDIT_MAX, not UTF-8, or with a control character or one of
those invisible ones
ESP_ERR_INVALID_STATE stopped, offline, or with no owner (in the limbo an event has no page)
ESP_ERR_NOT_SUPPORTED the cloud of this connection takes no business event (an earlier one)
DEVUI_ERR_OVER_QUOTA above the cloud's bucket of events (AUDIT_QUOTA: a burst, refilled at a rate per hour; 10
and 360 by default), before the cloud's 4429
ESP_ERR_NO_MEM the way out holds frames and the event does not fit behind them (on the ESP8266): try again
ESP_ERR_TIMEOUT as the other calls that run in the SDK's task
Added after the v1 was frozen (it grows only by additions).
devui_session_close
devui_err_t devui_session_close(uint16_t session, uint16_t reason);
The firmware closes a session: a person's tab, an API call or a stream of events of the device API (devui_event_t.session_kind, devui_session_info_t.kind). The SDK sends SESSION_CLOSE with reason (a code of the single registry, 1000 to 4999; 0 for none, which the cloud reads as 1000) and forgets the session at once: devui_session_info answers ESP_ERR_NOT_FOUND, its messages still in the SDK's queue (devui_send, devui_reply waiting for credit) are dropped, and DEVUI_EV_SESSION_CLOSE does not come for it (the app asked). To refuse a machine, use 4405: the API call gets 403 proibido, and the stream of events ends with the event closed {"erro":"proibido"}. On the ESP32 it goes after what the app queued before it, in order; callable from the callbacks (DEVUI_EV_SESSION_OPEN included). A message of the cloud to it still in flight is dropped, and a devui_send to it afterwards is taken and dropped, as to any session closed (at most once).
ESP_OK closed (on the ESP32: queued for the SDK's task, behind what was queued before)
ESP_ERR_INVALID_ARG session 0 (DEVUI_ALL) or above the cloud's, or a reason not 0 outside 1000..4999
ESP_ERR_INVALID_STATE stopped or offline (offline, every session is already closed)
ESP_ERR_NOT_FOUND no such session open
ESP_ERR_NO_MEM the SDK's queue is full, or the way out holds frames and the close does not fit behind them
(on the ESP8266): the session stays open, try again
Added after the v1 was frozen (it grows only by additions).
devui_call
devui_err_t devui_call(const char *alias, const void *data, size_t len, uint32_t timeout_ms, void (*cb)(const devui_call_result_t *r, void *ctx), void *ctx);
Calls another device by the alias of a link its owner made in the portal (the device's page, "Ligar a outro dispositivo"): data (len bytes, opaque: the callee gets them as a request, DEVUI_REQUEST, in a session of DEVUI_SESSION_DEVICE) goes through this device's own connection, with no second TLS, and cb gets what came, once, in the SDK's task (keep it short, as the other callbacks): the callee's devui_reply, a refusal of the cloud, sem_resposta when nothing came in timeout_ms (0 or above 10,000: 10,000) and a few seconds more, or DEVUI_CALL_NOT_SENT when the connection ended before the call left. At most once: the SDK never repeats it; put a nonce in the data so the callee can tell a repetition, as with the device API. A call waits in the SDK's queue behind what the app queued before it, but takes no credit of the cloud. Callable from any task and from the callbacks (cb included). cb may be NULL (nobody hears the result); ctx goes to it as it is.
ESP_OK taken: cb comes, once
ESP_ERR_INVALID_ARG an alias that is not 1 to 32 of a-z, 0-9 and '-', or a NULL data with len
ESP_ERR_INVALID_SIZE len above DEVUI_CALL_MAX_LEN, or above what the SDK's queue holds
ESP_ERR_INVALID_STATE stopped or offline
ESP_ERR_NO_MEM 4 calls wait for their result (one's cb frees one), or the SDK's queue is full (wait for
DEVUI_EV_TX_READY)
DEVUI_ERR_OVER_QUOTA above the plan's quota (a call counts as a message of len bytes)
Added after the v1 was frozen (it grows only by additions).
devui_db_request
devui_err_t devui_db_request(uint8_t scope, const char *op, const char *table, const char *query, void (*cb)(const devui_db_result_t *r, void *ctx), void *ctx);
A request to the database: {"op":op,"table":table,"scope":"device"|"account"} and the members of query, a JSON object or NULL ("{\"filter\":{\"ts\":{\"gte\":\"2026-11-01\"}},\"calc\":{\"total\":{\"sum\":\"valor\"}}}"), built by the SDK: the app never writes the scope. op: insert, update, update_where, delete, delete_where, find or aggregate (one the cloud does not know comes back DEVUI_DB_INVALID); table: [a-z][a-z0-9_]{0,31}. The SDK checks the names, and that query (and the record or set of the thin ones) is one JSON object with nothing after it, followed through its strings and their escapes, so it never adds members to the request; query must not name, at its first level, op, table, scope, id, record, set nor op_id (the SDK writes them). The rest is the cloud's to check (DEVUI_DB_INVALID, with the field in answer). The largest request the SDK sends is 4,083 B of JSON (the room of its send queue; 1,011 B on the ESP8266), and 4,055 B for an insert of the queue (983 B on the ESP8266), which adds its op_id (28 B). cb gets what came, once, in the SDK's task (keep it short, as the other callbacks); cb may be NULL; ctx goes to it as it is, and must live until it comes (for a queued insert, maybe until the next connection). At most once, but the queue's inserts (devui_db_queue). Runs in the SDK's task and returns once the request is in the core. With no cloud (offline, connecting, the local mode only), an error at once, unless it is an insert and the queue is on: then it waits in the queue (ESP_OK) and goes when the connection is up, in order. Where the tables come from: the owner account declares its own in the portal, and a product declares the tables of all its devices on the product's page ("Banco de dados") or with devui tables push <file>, with a version of its own; they reach the owner account on first use. Never in the firmware: the packer refuses a tabelas.json beside web/, and the manifest has no tables. A field the product removed is dropped from an insert or a set (an old device that still sends it keeps writing), and a table the product removed is gone, records and all (DEVUI_DB_NOT_FOUND).
ESP_OK taken: cb comes, once
ESP_ERR_INVALID_ARG a scope, op, table, id or JSON object the SDK refuses
ESP_ERR_INVALID_SIZE the request's JSON above those 4,083 B (4,055 B for the queue's inserts; 1,011 B and 983 B
on the ESP8266)
ESP_ERR_INVALID_STATE stopped, offline (with the queue off, or for anything but an insert)
DEVUI_ERR_DB_LIMIT 4 requests wait for their answer (the queue's head counts): one's cb frees one
ESP_ERR_NO_MEM the SDK's send queue is full now (wait for DEVUI_EV_TX_READY), or the queue of inserts holds
its max_records or max_bytes (nothing of it is dropped: the oldest records stay)
ESP_FAIL DEVUI_DB_QUEUE_FLASH: the NVS did not keep the insert (it is not in the queue either)
ESP_ERR_TIMEOUT as the other calls that run in the SDK's task
Added after the v1 was frozen (it grows only by additions).
devui_db_insert
devui_err_t devui_db_insert(uint8_t scope, const char *table, const char *record, void (*cb)(const devui_db_result_t *r, void *ctx), void *ctx);
The thin ones, the same rules: an insert of record (a flat JSON object: {"valor":550,"maquina":"m3"}), the answer {"id":"<24 hex>","ts":"<ISO>"}; with the queue on, it always goes through it (with no cloud too), in order.
devui_db_update
devui_err_t devui_db_update(uint8_t scope, const char *table, const char *id, const char *set, void (*cb)(const devui_db_result_t *r, void *ctx), void *ctx);
The fields of set (a JSON object; null removes a field) in the record id (24 hex digits); the answer {"ok":true}.
devui_db_delete
devui_err_t devui_db_delete(uint8_t scope, const char *table, const char *id, void (*cb)(const devui_db_result_t *r, void *ctx), void *ctx);
Removes the record id; the answer {"ok":true}.
devui_db_find
devui_err_t devui_db_find(uint8_t scope, const char *table, const char *query, void (*cb)(const devui_db_result_t *r, void *ctx), void *ctx);
Records by query's members (filter, sort, limit 1 to 100, cursor; NULL: the first 50 by ts); the answer {"records":[{"id","ts",...}],"cursor":"<the next page's>"|null}.
devui_db_aggregate
devui_err_t devui_db_aggregate(uint8_t scope, const char *table, const char *query, void (*cb)(const devui_db_result_t *r, void *ctx), void *ctx);
Sums, averages, minimums, maximums and counts by query's members (filter, group_by: a field, day, week or month; tz, the IANA zone of the days, UTC by default; calc, up to 8); the answer {"groups":[{"key":...,"<name>":<number>}]}.
devui_db_queue
devui_err_t devui_db_queue(uint8_t where, uint16_t max_records, size_t max_bytes);
The queue of inserts with no cloud (off by default): where (DEVUI_DB_QUEUE_*), up to max_records records in max_bytes of the heap (each takes its JSON and under 40 B). With it on, every devui_db_insert goes through it, cloud or not: it waits with an op_id drawn on the board (16 hex digits) and goes in order, one at a time, when the connection is up; after limite or indisponivel (or no answer in 10 s, or a drop) it goes again, after the cloud's wait, with the same op_id, which the cloud takes once in 24 h: a resend never writes the record twice. Its cb comes once, with the answer that ended it. With DEVUI_DB_QUEUE_FLASH (max_bytes up to DEVUI_DB_QUEUE_FLASH_MAX), the records a restart or a devui_stop left in the NVS come back here (with no callback: theirs was of the last boot), and every change rewrites them there (the NVS levels the wear). A smaller queue never drops them: more records than max_records all come back (new inserts refused until it is below), and a max_bytes they do not fit in is refused (ESP_ERR_INVALID_SIZE, the NVS's copy as it is). The queue belongs to the owner (the device's records go with a change of owner): a new owner, or the limbo, empties it, each record's cb with DEVUI_DB_FORBIDDEN (and a copy kept in the NVS by the last owner is dropped). Called again, the queue goes off first; off (DEVUI_DB_QUEUE_OFF), the records waiting end with DEVUI_DB_UNAVAILABLE (their callbacks, in order) and the NVS's copy is emptied; from one of those callbacks this is refused. Call it after devui_start; devui_stop lets it go with no callback (the NVS's copy stays for the next start).
ESP_OK; ESP_ERR_INVALID_ARG (where unknown, max_records 0, max_bytes below 64, or above DEVUI_DB_QUEUE_FLASH_MAX with
DEVUI_DB_QUEUE_FLASH); ESP_ERR_INVALID_SIZE (the NVS's copy does not fit max_bytes); ESP_ERR_NO_MEM (no heap for
it); ESP_ERR_INVALID_STATE (stopped, or from a callback of the queue going off); ESP_ERR_NOT_SUPPORTED
(DEVUI_DB_QUEUE_FLASH on the ESP8266); ESP_ERR_TIMEOUT
Added after the v1 was frozen (it grows only by additions).
devui_vault_psk_text
devui_err_t devui_vault_psk_text(char *out, size_t size);
The vault's PSK as the user types it in the portal, once per browser (it goes with a check: a typo is caught before the handshake). Show it on the product's screen (and its QR, the same text), print it on a label at the factory, or write it on the serial (physical access); never send it through the cloud, nor log it where the cloud reads: who has it and the portal opens the device's pages. It stays across a factory reset (it may be on a label); devui_vault_reset with true draws a new one. Runs in the SDK's task. out: at least DEVUI_VAULT_PSK_TEXT_SIZE bytes.
ESP_OK out holds the text
ESP_ERR_INVALID_ARG out NULL or size below DEVUI_VAULT_PSK_TEXT_SIZE
ESP_ERR_INVALID_STATE stopped, or started without devui_config_t.vault
ESP_ERR_NOT_SUPPORTED a build without CONFIG_DEVUI_VAULT
ESP_ERR_TIMEOUT as the other calls that run in the SDK's task
Added after the v1 was frozen (it grows only by additions).
devui_vault_reset
devui_err_t devui_vault_reset(bool new_psk);
Erases the device's access list (the users' keys and roles that entered with the PSK) and, with new_psk, draws a new PSK and a new static key: for a product with a screen, after a physical reset (a button held), so the old PSK no longer opens it. Every tab does its handshake again (the open sessions are told closed). A change of owner, or the device back to the limbo, erases the list by itself; the PSK stays. Runs in the SDK's task.
ESP_OK done
ESP_ERR_INVALID_STATE stopped, started without devui_config_t.vault, or no entropy for a new PSK (the old one
stays)
ESP_ERR_NOT_SUPPORTED a build without CONFIG_DEVUI_VAULT
ESP_FAIL the new PSK could not be kept in the NVS (the old one stays)
ESP_ERR_TIMEOUT as the other calls that run in the SDK's task
Added after the v1 was frozen (it grows only by additions).
devui_vault_enroll
devui_err_t devui_vault_enroll(bool open);
Whether the access list takes new users (open, the default at each devui_start) or not: closed, a browser with the right PSK but a key not on the list is refused ("access refused by the board"). The first key on the list is the owner's; the next ones enter with the cloud's role, never as owner. Up to 8 keys. Runs in the SDK's task.
ESP_OK, ESP_ERR_INVALID_STATE (stopped, or without devui_config_t.vault), ESP_ERR_NOT_SUPPORTED (a build without
CONFIG_DEVUI_VAULT), ESP_ERR_TIMEOUT
Added after the v1 was frozen (it grows only by additions).
devui_get_prefs
devui_err_t devui_get_prefs(devui_prefs_t *out);
The owner account's preferences: the last ones the cloud sent and the SDK accepted, kept in its NVS across boots (DEVUI_EV_PREFS when they change). Call it after devui_start (also offline, also from a callback): a boot with no cloud reads the ones of the NVS. ESP_OK with out filled; ESP_ERR_NOT_FOUND when the device has none (it never got them from the cloud, the factory reset erased them, or devui_start was not called yet); ESP_ERR_INVALID_ARG with out NULL. Added after the v1 was frozen.
devui_device_id
const char *devui_device_id(void);
Diagnostics, outside the twelve: the device_id in base32 (26 characters), valid after devui_start.
Types
devui_err_t
typedef esp_err_t devui_err_t;
Documented in: the header's opening comment, "Errors (devui_err_t is esp_err_t)", and its table.
devui_msg_t
typedef struct { ... } devui_msg_t;
A message from a page. Valid during the callback only: copy what is needed (to answer a request later, its session, id, flags and conn).
| Field | Type | Description |
|---|---|---|
session | uint16_t | the tab's session (1..0x7FFF; 0x8000..0xFFFE a local tab): devui_send to it answers that tab only |
id | uint32_t | per connection: valid on the connection conn only; devui_reply uses it |
flags | uint8_t | DEVUI_TEXT, DEVUI_ACK_REQ, DEVUI_REQUEST |
conn | uint32_t | the connection the message came on: a number the SDK counts at each connection, never 0 (and never the same one again after a devui_stop and devui_start); devui_reply refuses a request of another one. A local tab's has bit 31 set: the tab's own, for as long as it lives |
data | const uint8_t * | the struct's comment: the message's bytes, valid during the callback only |
len | size_t | the struct's comment: the length of data |
devui_event_type_t
typedef enum { ... } devui_event_type_t;
The events. Values are fixed: a later version only adds at the end.
| Name | Value | Description |
|---|---|---|
DEVUI_EV_ONLINE | 0 | the connection is up (HELLO_ACK); the owner is known |
DEVUI_EV_OFFLINE | 1 | the connection ended (result: why, close_code); the SDK reconnects by itself |
DEVUI_EV_SESSION_OPEN | 2 | a tab opened: session, role, user (pseudonym), reopened, session_kind |
DEVUI_EV_SESSION_CLOSE | 3 | session |
DEVUI_EV_PAIR_CODE | 4 | a new code: pair_code, pair_url, pair_ttl_s (show it as XXXX-XXXX) |
DEVUI_EV_PAIR_BUTTON | 5 | the portal asks for the button: devui_pair_confirm at each press, within pair_ttl_s |
DEVUI_EV_PAIRED | 6 | the device has an owner now (against the last owner kept in the NVS, across boots) |
DEVUI_EV_UNPAIRED | 7 | back to the limbo (unlinked by the cloud, also while off), or a factory reset: erase what the app keeps of the owner here too, since the next pairing, by any account, is a PAIRED, not an OWNER_CHANGED |
DEVUI_EV_BUNDLE_SYNCED | 8 | the cloud has the embedded UI |
DEVUI_EV_BUNDLE_REJECTED | 9 | result: 1 other hash, 2 too large, 3 invalid container, 4 blocked by the cloud, 5 the cloud could not store it now: it asks for it again |
DEVUI_EV_TX_READY | 10 | the send queue has room again after an ESP_ERR_NO_MEM |
DEVUI_EV_DUPLICATE | 11 | the cloud closed the connection with 4409: another device with this identity took its place (a clone, or one key on two boards); the SDK waits 10 min. It comes right after the DEVUI_EV_OFFLINE of that close (close_code 4409), or alone when the 4409 came before DEVUI_EV_ONLINE (before it, only the OFFLINE) |
DEVUI_EV_CLOCK_SET | 12 | the system clock (time(), gettimeofday) was below the clock floor, so invalid (a board starts in 1970), and was set from the server's time of this connection, before its ONLINE; a valid clock (the app's SNTP) is never touched |
DEVUI_EV_UPDATE_ADVISED | 13 | the firmware is below the safe version: update it |
DEVUI_EV_OWNER_CHANGED | 14 | The device went to another owner (1.2): owner_gen. Erase what the app keeps of the old owner (its settings, its history, what it keeps by user pseudonym: the pseudonyms change too) before the callback returns, and say so with DEVUI_OPT_OWNER_EVENT. Online, it comes after the old owner's sessions closed and before any of the new owner's opens; a change made while the device was off comes with the next connection, before DEVUI_EV_ONLINE. The SDK keeps the generation in its NVS only after the callback returned: a device that goes down inside it gets the event again at the next connection, so erasing twice must be harmless. Never for the first owner (DEVUI_EV_PAIRED), never after a factory reset or an unlink (DEVUI_EV_UNPAIRED). |
DEVUI_EV_TRUST_ORDER | 15 | A trust order (1.2): an order signed offline by the order keys the firmware carries, to move the device to another endpoint, change its roots or its order keys, cancel a waiting one, or a sign of life. order_event says what happened (DEVUI_ORDER_*), with order_kind, order_reason and order_seq. The SDK checks, keeps and applies it by itself; the app only tells the owner (DEVUI_ORDER_PENDING starts the 7 days of operation in which the other key may cancel it) or logs it. |
DEVUI_EV_PAIR_CODE_ACCEPTED | 16 | The current pairing code is registered in the cloud: the cloud said so with a PAIR CODE_ACK of this code on this connection. pair_code, pair_url and pair_ttl_s (what it has left) as in PAIR_CODE. Hand out the code or its URL from here when it must already pair (a BLE characteristic, a link sent away); a display may show it at PAIR_CODE. It comes at each CODE_ACK, a reconnection's resend too: forget it at OFFLINE and at a new PAIR_CODE. Never with an owner, and never with a cloud that does not send CODE_ACK (one before 25/10): there the code still pairs, the SDK just cannot tell. |
DEVUI_EV_PREFS | 17 | The owner account's preferences came, or changed: prefs, the IANA zone, its POSIX rule and the language of the account that owns the device (of the owner, never of who operates it by invitation). The cloud sends them at each connection with an owner and again when the owner changes them; the event comes only when one of the three differs from the ones kept, the first one too. By then the SDK keeps them in its NVS (the local mode's /_devui/env and a boot with no cloud have them: devui_get_prefs) and, unless devui_config_t.manual_tz, has applied the rule with setenv("TZ", ...) and tzset(), so localtime() and strftime() already give the account's local time. A PREFS the SDK refuses (a rule out of the grammar) changes nothing and comes as no event. With prefs NULL: the device went to the limbo (unlinked, also while off, or sold) and the SDK erased the old owner's preferences, so whoever takes the board never sees them; TZ is back to the firmware's (devui_get_prefs answers ESP_ERR_NOT_FOUND, the local mode's env null). Added after the v1 was frozen (it grows only by additions). |
devui_offline_reason_t
typedef enum { ... } devui_offline_reason_t;
DEVUI_EV_OFFLINE's result: why the connection ended, the first cause seen. Values are fixed: a later version only adds at the end.
| Name | Value | Description |
|---|---|---|
DEVUI_OFFLINE_UNKNOWN | 0 | the enum's comment: no cause seen |
DEVUI_OFFLINE_NETWORK | 1 | the Wi-Fi fell, or the connection dropped with no close frame (TCP, TLS) |
DEVUI_OFFLINE_CLOUD | 2 | the cloud closed it: close_code says why (1012 a deploy, 4409 a clone, 4410...) |
DEVUI_OFFLINE_DEVICE | 3 | the SDK closed it: close_code says why (a protocol error, a GOAWAY, its queue) |
DEVUI_OFFLINE_SILENT | 4 | no sign of the connection past the ping interval plus the pong timeout |
DEVUI_OFFLINE_SEND_STALLED | 5 | a send found no room in the socket for 10 s: the connection was abandoned |
DEVUI_OFFLINE_STOPPED | 6 | devui_stop or devui_factory_reset |
devui_event_t
typedef struct { ... } devui_event_t;
An event. Valid during the callback only, pointers included.
| Field | Type | Description |
|---|---|---|
type | devui_event_type_t | the enum devui_event_type_t, whose members say which fields each event fills |
session | uint16_t | the events of a tab (SESSION_OPEN, SESSION_CLOSE): its session, as devui_msg_t.session |
role | uint8_t | SESSION_OPEN: 1 owner, 2 operator, 3 reader |
reopened | bool | SESSION_OPEN: the tab was open before a reconnection |
result | uint8_t | BUNDLE_REJECTED: why (above); OFFLINE: a devui_offline_reason_t |
pair_code | const char * | PAIR_CODE, PAIR_CODE_ACCEPTED: the 8 characters of Crockford base32, no hyphen, and the URL of the pairing page (the base the cloud sent in the HELLO_ACK + "?c=" + code, or "&c=" when the base has a query; NULL until a base was received, never a host of the firmware) |
pair_url | const char * | (the same comment as the line above) |
pair_ttl_s | uint16_t | PAIR_CODE, PAIR_CODE_ACCEPTED: seconds the code has left; PAIR_BUTTON: the window |
user | const uint8_t * | SESSION_OPEN: the user's pseudonym, 8 bytes (the same user on this device and in this epoch gets the same one; Q5), NULL when the cloud sent none |
close_code | uint16_t | OFFLINE: the WebSocket close code that ended the connection, received (CLOUD) or sent (DEVICE); 0 when none |
owner_gen | uint32_t | OWNER_CHANGED: the generation of the new ownership, never 0. Only a number: it names no account nor person, and a later one is not always larger (compare by equality, if at all) |
order_event | uint8_t | TRUST_ORDER: what happened (DEVUI_ORDER_*); the order's KIND (1 MOVE, 2 ROOTS, 3 KEYS, 4 CANCEL, 5 LIFE; 0 when a refused one did not get through its form); the reason of a refusal, in the order the SDK checks them (1 format, 2 signer, 3 scope, 4 seq, 5 expired, 6 origin, 7 signature, 8 pending, 9 cancel, 10 last-root; else 0); and its SEQ (0 when it did not get through its form) |
order_kind | uint8_t | (the same comment as the line above) |
order_reason | uint8_t | (the same comment as the line above) |
order_seq | uint32_t | (the same comment as the line above) |
session_kind | uint8_t | SESSION_OPEN: who opened the session, DEVUI_SESSION_BROWSER, DEVUI_SESSION_API or DEVUI_SESSION_DEVICE; 0 in the other events. Added after the v1 was frozen (it grows only by additions). |
prefs | const struct devui_prefs * | PREFS: the owner account's preferences, as now kept (devui_prefs_t), or NULL when the limbo erased them; NULL in the other events. Added after the v1 was frozen. |
devui_prefs_t
typedef struct { ... } devui_prefs_t;
The owner account's preferences, each a NUL-terminated ASCII text the SDK checked by the rules of the spec: DEVUI_EV_PREFS and devui_get_prefs.
| Field | Type | Description |
|---|---|---|
time_zone | char [65] | the IANA name, 1 to 64 characters ("America/Sao_Paulo"); the device has no IANA database |
posix_tz | char [65] | the same zone as a POSIX TZ rule, 1 to 64 ("<-03>3", "EST5EDT,M3.2.0,M11.1.0") |
locale | char [36] | the account's language tag, 2 to 35 ("pt-BR", "en") |
devui_session_info_t
typedef struct { ... } devui_session_info_t;
Documented in: function 7, devui_session_info.
| Field | Type | Description |
|---|---|---|
open | bool | function 7, devui_session_info: whether the session is open |
role | uint8_t | function 7, devui_session_info, and devui_event_t.role |
kind | uint8_t | DEVUI_SESSION_BROWSER, DEVUI_SESSION_API or DEVUI_SESSION_DEVICE; 0 when not open. Added after the v1 was frozen (it grows only by additions). |
devui_status_t
typedef enum { ... } devui_status_t;
Documented in: function 8, devui_status.
| Name | Value | Description |
|---|---|---|
DEVUI_STATUS_STOPPED | 0 | function 8, devui_status: stopped |
DEVUI_STATUS_CONNECTING | 1 | waiting for the network or the handshake, or between attempts |
DEVUI_STATUS_ONLINE | 2 | function 8, devui_status: online |
devui_config_t
typedef struct { ... } devui_config_t;
Documented in: function 1, devui_start, and the comment of each member.
| Field | Type | Description |
|---|---|---|
bundle | const uint8_t * | The UI embedded by devui_add_bundle (devui_bundle, devui_manifest of devui_bundle.h). NULL: the one of devui_add_bundle(web) when the app has one (the hello world names none), or no UI. |
bundle_size | size_t | (the same comment as the line above) |
manifest | const uint8_t * | (the same comment as the line above) |
manifest_size | size_t | (the same comment as the line above) |
project_key | const char * | optional: the product's public key |
fw_version | const char * | optional: the app's version, sent in the HELLO (shown at pairing) |
options | uint32_t | DEVUI_OPT_*; 0 by default |
adc_hold | void (*)(bool hold, void *ctx) | Without a radio on (a P4, an ESP32 with Ethernet only), the key, the pairing codes and the SDK's other random draws come from bootloader_random_enable(), and the app's ADC must be paused around each: hold true, then false, from the SDK's task (or from devui_start). NULL = no such source. |
adc_ctx | void * | (the same comment as the line above) |
task_wdt | bool | the SDK's task in the Task WDT while it runs (off by default): it leaves the watchdog for each bounded wait for the network or for the WebSocket client and comes back after it, and leaves it at devui_stop. The WebSocket task stays out: the SDK watches it by its silence. Needs the Task WDT of the ESP-IDF on. |
provision_token | const char * | The account's provisioning token, for fleets: the text bwp_... the portal shows once on the product's page. Optional: with it, a device in the limbo that declares the product's project_key enters the account with no code (DEVUI_EV_PAIRED, as a pairing); without it, or with a token the cloud does not take (revoked, past its end, full), the limbo and the code, as before. Built into the firmware or read by the app from its NVS; a secret: the SDK never logs it nor stores it, and the app keeps the string alive while the SDK runs. Up to 128 bytes (ESP_ERR_INVALID_ARG above). |
bundle_sig | const uint8_t * | The bundle's signature: the 72 bytes devui_pack.py --sign-key writes next to the bundle (devui_bundle_sig of devui_bundle.h), sent in the HELLO for the cloud to check with the product's keys. NULL and 0: the one of devui_add_bundle(web) when the build signed it and the app passed that bundle and manifest (devui_bundle, devui_manifest) or none; else no signature. Another size: ESP_ERR_INVALID_ARG. A bundle_sig with no bundle and manifest is not sent. |
bundle_sig_size | size_t | (the same comment as the line above) |
host | const char * | the gateway, as in the certificate and the signed transcript |
port | uint16_t | The endpoint and its roots. A product leaves them as DEVUI_CONFIG_DEFAULT() gives them: a release build (CONFIG_DEVUI_TRUST_RELEASE) refuses any other (ESP_ERR_NOT_SUPPORTED). The service's development build (CONFIG_DEVUI_TRUST_DEV) and the test or self-host build (CONFIG_DEVUI_ENDPOINT_TEST) take the host, the port and the ca_pem the app names: a test gateway and its CA, for one. |
ca_pem | const char * | the roots, PEM; NULL: those of the build's trust profile |
vault | bool | The vault mode (needs CONFIG_DEVUI_VAULT, else devui_start answers ESP_ERR_NOT_SUPPORTED): the product's browser sessions trade only messages sealed end to end with the portal's frame, which the cloud relays without reading (Noise_XXpsk3_25519_AESGCM_SHA256). The first devui_start draws the vault's PSK and the device's static key under the entropy guard and keeps them in the NVS (ESP_ERR_INVALID_STATE with no entropy source, as the key); the user types the PSK's text once per browser (devui_vault_psk_text: show it on a screen, print it on a label, write it on the serial; never send it through the cloud). What changes for the app: DEVUI_EV_SESSION_OPEN comes when the tab's handshake ends, with the effective role (the device's access list and the cloud's: the less privileged), and SESSION_CLOSE only for a session told open; devui_send to a session not open yet is ESP_ERR_INVALID_STATE, DEVUI_ALL goes to each open session, and the largest message is DEVUI_VAULT_OVERHEAD (26) bytes shorter. No sessions of the device API nor of another device (DEVUI_SESSION_API, DEVUI_SESSION_DEVICE): they bring clear text from the cloud. The cloud keeps no last state of the product. devui_start runs the vault's X25519 and the ECDSA of its attestation on the caller's stack: ~3.7 KB of the caller's task on the ESP32-S3 (measured on 01/11: app_main of the LED example, 3,692 B used of 8,192), above the IDF's default main task (3,584 B), which overflowed; give the task that calls devui_start 5 KB or more (CONFIG_ESP_MAIN_TASK_STACK_SIZE for app_main). Added after the v1 was frozen (it grows only by additions). |
manual_tz | bool | The owner account's time zone (DEVUI_EV_PREFS): false, the default, and the SDK applies its POSIX rule with setenv("TZ", ...) and tzset() when it comes or changes, and at devui_start with the one kept in the NVS, so localtime() gives the account's local time; when they go (the limbo, devui_factory_reset), TZ goes back to the firmware's own (the one it had before the SDK first set it; none: UTC). true: the SDK never touches TZ, and the app does with devui_prefs_t.posix_tz what it wants (a zone of its own, a menu of the product). Added after the v1 was frozen. |
devui_call_result_t
typedef struct { ... } devui_call_result_t;
What a call gave. Valid during the callback only: copy what is needed.
| Field | Type | Description |
|---|---|---|
status | uint8_t | DEVUI_CALL_* |
result | uint8_t | the cloud's answer as it came (status, for the cloud's; 0 for the SDK's own) |
data | const uint8_t * | DEVUI_CALL_OK: the callee's answer (len 0 when it answered nothing) |
len | size_t | its bytes |
text | bool | the answer came as text (the callee's devui_reply of a DEVUI_TEXT message) |
retry_after_ms | uint32_t | DEVUI_CALL_LIMIT: the wait the cloud asks for (0: none said) |
error_code | uint16_t | DEVUI_CALL_ERROR: the code of the cloud's ERROR, 0 when it was an unknown answer |
devui_db_result_t
typedef struct { ... } devui_db_result_t;
What a request gave. Valid during the callback only: copy what is needed.
| Field | Type | Description |
|---|---|---|
status | uint8_t | DEVUI_DB_* |
result | uint8_t | the cloud's answer as it came; 0 when the SDK says DEVUI_DB_UNAVAILABLE itself |
answer | const char * | the answer in JSON, NOT NUL-terminated (len bytes); NULL when none came |
len | size_t | the bytes of answer |
retry_after_ms | uint32_t | DEVUI_DB_LIMIT, DEVUI_DB_UNAVAILABLE: the wait the cloud asks for (0: none said) |
error_code | uint16_t | DEVUI_DB_ERROR: the code of the cloud's ERROR, 0 when it was an unknown answer |
queued | bool | an insert that went through the queue |
Macros
DEVUI_ERR_BASE
#define DEVUI_ERR_BASE 0x7D00
The SDK's own errors, apart from the ESP-IDF's (the table above).
DEVUI_ERR_OVER_QUOTA
#define DEVUI_ERR_OVER_QUOTA (DEVUI_ERR_BASE + 1)
above QUOTA_MSGS_PER_S or QUOTA_BYTES_PER_S of the plan
DEVUI_ERR_HAS_OWNER
#define DEVUI_ERR_HAS_OWNER (DEVUI_ERR_BASE + 2)
devui_pair_begin: the device has an owner
DEVUI_ERR_STALE_REQUEST
#define DEVUI_ERR_STALE_REQUEST (DEVUI_ERR_BASE + 3)
devui_reply: the request's connection ended; not its age, which the SDK checks only before the callback
DEVUI_ALL
#define DEVUI_ALL 0u
devui_send's session: every open session (broadcast).
DEVUI_TEXT
#define DEVUI_TEXT 0x04u
the data is UTF-8 text (JSON, for the lib); without it, bytes
DEVUI_ACK_REQ
#define DEVUI_ACK_REQ 0x02u
in devui_msg_t.flags: the cloud wants an ACK, sent by the SDK when the callback returns
DEVUI_STATE
#define DEVUI_STATE 0x10u
devui_send: the data is the device's whole state; the page sees meta.state. The cloud keeps the last one when the product opts in
DEVUI_REQUEST
#define DEVUI_REQUEST 0x20u
in devui_msg_t.flags: the page asked; answer with devui_reply
DEVUI_OPT_READER_DATA
#define DEVUI_OPT_READER_DATA 0x01u
the cloud delivers the DATA of reader sessions too (it drops them by default)
DEVUI_OPT_OWNER_EVENT
#define DEVUI_OPT_OWNER_EVENT 0x02u
The app handles DEVUI_EV_OWNER_CHANGED: it erases there what it keeps of the old owner. With it, the portal no longer recommends a factory reset to the two owners of a transfer; without it, it does.
DEVUI_SESSION_BROWSER
#define DEVUI_SESSION_BROWSER 0u
a person's tab, in the portal or the product's page
DEVUI_SESSION_API
#define DEVUI_SESSION_API 2u
A call of the cloud's HTTP API (POST /v1/devices/{id}/messages) with a device key the owner made: a session that lives for one request, with the key's role and a pseudonym of the key's own, never a person's. The cloud opens it only for a key the owner created; a firmware that serves only people answers its requests with an error of its own and acts on none (docs/api-de-dispositivos.md).
DEVUI_SESSION_DEVICE
#define DEVUI_SESSION_DEVICE 3u
Another device, by a link its owner made in the portal ("sala -> portao"): a session that lives for one request (devui_call on that device), with the link's role and a pseudonym of the link's own. The SDK serves it always (bit 3 of the HELLO's OPTIONS, the SDK's own); a firmware that serves only people refuses it by the kind, as an API call (docs/api-de-dispositivos.md).
DEVUI_SESSION_LOCAL
#define DEVUI_SESSION_LOCAL 4u
A tab of the local mode (devui_local): a browser on the LAN or on the app's AP that opened the board's own page with the local password. Its session is numbered 0x8000..0xFFFE, never through the cloud; its role is operator (2), and its user a pseudonym of that browser's login, never a person's of the cloud.
DEVUI_ORDER_APPLIED
#define DEVUI_ORDER_APPLIED 1u
accepted, and it holds at once (LIFE, CANCEL, a ROOTS that removes, KEYS by two)
DEVUI_ORDER_PENDING
#define DEVUI_ORDER_PENDING 2u
accepted, and it waits 7 days of operation (MOVE, a ROOTS that adds, KEYS by one)
DEVUI_ORDER_REFUSED
#define DEVUI_ORDER_REFUSED 3u
refused (order_reason): nothing changed, the device stays where it is
DEVUI_ORDER_DUE
#define DEVUI_ORDER_DUE 4u
the wait ended: a KEYS holds now; a MOVE or ROOTS is tried at the next connection
DEVUI_ORDER_CONFIRMED
#define DEVUI_ORDER_CONFIRMED 5u
the destination's HELLO_ACK: its endpoint and roots are the ones in use
DEVUI_ORDER_RETURNED
#define DEVUI_ORDER_RETURNED 6u
no HELLO_ACK of the destination in time: back to the endpoint before, order spent; or an accepted order the NVS could not keep: spent, nothing changed
DEVUI_RELEASE_HOST
#define DEVUI_RELEASE_HOST "gw.thingface.com"
The service's endpoint, the one of every release build (Q16).
DEVUI_RELEASE_PORT
#define DEVUI_RELEASE_PORT 443
The service's endpoint, the one of every release build (Q16).
DEVUI_CONFIG_DEFAULT
#define DEVUI_CONFIG_DEFAULT() {.host = CONFIG_DEVUI_ENDPOINT_HOST, .port = CONFIG_DEVUI_ENDPOINT_PORT}
With CONFIG_DEVUI_ENDPOINT_TEST.
Test or self-host build (CONFIG_DEVUI_ENDPOINT_TEST): the endpoint of the menuconfig
#define DEVUI_CONFIG_DEFAULT() {.host = CONFIG_DEVUI_DEV_HOST, .port = CONFIG_DEVUI_DEV_PORT}
With CONFIG_DEVUI_TRUST_DEV.
The service's development build (CONFIG_DEVUI_TRUST_DEV): the staging of the menuconfig
#define DEVUI_CONFIG_DEFAULT() {.host = DEVUI_RELEASE_HOST, .port = DEVUI_RELEASE_PORT}
With !(CONFIG_DEVUI_ENDPOINT_TEST) && !(CONFIG_DEVUI_TRUST_DEV).
DEVUI_LOCAL_SECRET_SIZE
#define DEVUI_LOCAL_SECRET_SIZE 20u
The room devui_local_secret needs: "XXXX-XXXX-XXXX-XXXX" and the NUL.
DEVUI_AUDIT_MAX
#define DEVUI_AUDIT_MAX 128u
The longest text of devui_audit, in bytes.
DEVUI_CALL_OK
#define DEVUI_CALL_OK 0u
the callee answered: data, len, text
DEVUI_CALL_OFFLINE
#define DEVUI_CALL_OFFLINE 1u
offline: the callee is not connected, or dropped during the call; if it dropped after the call reached it, it MAY have acted (as the device API's 503)
DEVUI_CALL_NO_REPLY
#define DEVUI_CALL_NO_REPLY 2u
sem_resposta: no answer in time; the callee MAY have acted (do not repeat blindly)
DEVUI_CALL_NOT_LINKED
#define DEVUI_CALL_NOT_LINKED 3u
nao_ligado: no link with this alias on this device (or it has no owner)
DEVUI_CALL_FORBIDDEN
#define DEVUI_CALL_FORBIDDEN 4u
proibido: blocked, the link's role refused, or the callee's firmware refused it
DEVUI_CALL_LIMIT
#define DEVUI_CALL_LIMIT 5u
limite: 60 calls a minute per link, 4 at once, or a quota; retry_after_ms
DEVUI_CALL_UNSUPPORTED
#define DEVUI_CALL_UNSUPPORTED 6u
firmware_sem_suporte: the callee's SDK takes no call of a device
DEVUI_CALL_BUSY
#define DEVUI_CALL_BUSY 7u
ocupado: the callee's sessions are full
DEVUI_CALL_TOO_LARGE
#define DEVUI_CALL_TOO_LARGE 8u
grande_demais: the call or the answer above what the other side takes
DEVUI_CALL_NOT_SENT
#define DEVUI_CALL_NOT_SENT 0xFEu
the connection ended (or the SDK stopped) before the call left: nothing was done
DEVUI_CALL_ERROR
#define DEVUI_CALL_ERROR 0xFFu
an answer this version does not know (result has it), or the cloud refused the call's frame (error_code)
DEVUI_CALL_ALIAS_MAX
#define DEVUI_CALL_ALIAS_MAX 32u
The longest alias of a link, and the largest call.
DEVUI_CALL_MAX_LEN
#define DEVUI_CALL_MAX_LEN 4096u
The longest alias of a link, and the largest call.
DEVUI_DB_DEVICE
#define DEVUI_DB_DEVICE 0u
this device's records (a device never sees another's)
DEVUI_DB_ACCOUNT
#define DEVUI_DB_ACCOUNT 1u
the owner account's, with no device: only what the table lets devices do (read, by default)
DEVUI_DB_OK
#define DEVUI_DB_OK 0u
done: answer has the JSON ({"id","ts"} of an insert, {"records","cursor"} of a find...)
DEVUI_DB_INVALID
#define DEVUI_DB_INVALID 1u
invalido: not the database's request language, a field off the table's schema; answer says which
DEVUI_DB_FORBIDDEN
#define DEVUI_DB_FORBIDDEN 2u
proibido: no owner, or the table does not let devices do it (DEVUI_DB_ACCOUNT)
DEVUI_DB_NOT_FOUND
#define DEVUI_DB_NOT_FOUND 3u
nao_existe: no such table, or no such record
DEVUI_DB_QUOTA
#define DEVUI_DB_QUOTA 4u
cota: the plan's records or writes of the month
DEVUI_DB_LIMIT
#define DEVUI_DB_LIMIT 5u
limite: 60 writes a minute per device, or 4 requests at once; retry_after_ms
DEVUI_DB_UNAVAILABLE
#define DEVUI_DB_UNAVAILABLE 6u
indisponivel: the service is out (retry_after_ms when known), or no answer came in 10 s, or the connection dropped first: it MAY have been done (an insert of the queue goes again by itself, with its op_id, and never lands twice)
DEVUI_DB_TOO_LARGE
#define DEVUI_DB_TOO_LARGE 7u
grande_demais: a record above 2 KB or 32 fields, or an answer above what the device takes (ask fewer records per page)
DEVUI_DB_ERROR
#define DEVUI_DB_ERROR 0xFFu
an answer this version does not know (result has it), or the cloud refused the frame (error_code)
DEVUI_ERR_DB_LIMIT
#define DEVUI_ERR_DB_LIMIT (DEVUI_ERR_BASE + 4)
devui_db_* return this when DEVUI_DB_MAX requests (4) wait for their answer: the cloud's limite, said at once, with nothing sent; one's callback frees one.
DEVUI_DB_QUEUE_OFF
#define DEVUI_DB_QUEUE_OFF 0u
no queue (the default): with no cloud, every request is an error at once
DEVUI_DB_QUEUE_RAM
#define DEVUI_DB_QUEUE_RAM 1u
in the RAM: lost on a restart
DEVUI_DB_QUEUE_FLASH
#define DEVUI_DB_QUEUE_FLASH 2u
in the RAM and in the NVS, rewritten at each change: they survive a restart (not on the ESP8266, which has only the RAM)
DEVUI_DB_QUEUE_FLASH_MAX
#define DEVUI_DB_QUEUE_FLASH_MAX 2048u
The largest max_bytes of DEVUI_DB_QUEUE_FLASH: the queue shares the SDK's NVS (16 KB, with the key, the owner and the clock floor), which it must never fill.
DEVUI_VAULT_OVERHEAD
#define DEVUI_VAULT_OVERHEAD 26u
The vault mode (devui_config_t.vault). What each message adds on the wire: the largest message of devui_send and devui_reply is the usual one less this.
DEVUI_VAULT_PSK_TEXT_SIZE
#define DEVUI_VAULT_PSK_TEXT_SIZE 66u
The size of devui_vault_psk_text's text with its NUL: 55 characters of Crockford base32 in 11 groups of 5 with hyphens ("XXXXX-XXXXX-...").
