Skip to content
ThingFace

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).

FieldTypeDescription
sessionuint16_tthe tab's session (1..0x7FFF; 0x8000..0xFFFE a local tab): devui_send to it answers that tab only
iduint32_tper connection: valid on the connection conn only; devui_reply uses it
flagsuint8_tDEVUI_TEXT, DEVUI_ACK_REQ, DEVUI_REQUEST
connuint32_tthe 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
dataconst uint8_t *the struct's comment: the message's bytes, valid during the callback only
lensize_tthe 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.

NameValueDescription
DEVUI_EV_ONLINE0the connection is up (HELLO_ACK); the owner is known
DEVUI_EV_OFFLINE1the connection ended (result: why, close_code); the SDK reconnects by itself
DEVUI_EV_SESSION_OPEN2a tab opened: session, role, user (pseudonym), reopened, session_kind
DEVUI_EV_SESSION_CLOSE3session
DEVUI_EV_PAIR_CODE4a new code: pair_code, pair_url, pair_ttl_s (show it as XXXX-XXXX)
DEVUI_EV_PAIR_BUTTON5the portal asks for the button: devui_pair_confirm at each press, within pair_ttl_s
DEVUI_EV_PAIRED6the device has an owner now (against the last owner kept in the NVS, across boots)
DEVUI_EV_UNPAIRED7back 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_SYNCED8the cloud has the embedded UI
DEVUI_EV_BUNDLE_REJECTED9result: 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_READY10the send queue has room again after an ESP_ERR_NO_MEM
DEVUI_EV_DUPLICATE11the 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_SET12the 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_ADVISED13the firmware is below the safe version: update it
DEVUI_EV_OWNER_CHANGED14The 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_ORDER15A 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_ACCEPTED16The 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_PREFS17The 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.

NameValueDescription
DEVUI_OFFLINE_UNKNOWN0the enum's comment: no cause seen
DEVUI_OFFLINE_NETWORK1the Wi-Fi fell, or the connection dropped with no close frame (TCP, TLS)
DEVUI_OFFLINE_CLOUD2the cloud closed it: close_code says why (1012 a deploy, 4409 a clone, 4410...)
DEVUI_OFFLINE_DEVICE3the SDK closed it: close_code says why (a protocol error, a GOAWAY, its queue)
DEVUI_OFFLINE_SILENT4no sign of the connection past the ping interval plus the pong timeout
DEVUI_OFFLINE_SEND_STALLED5a send found no room in the socket for 10 s: the connection was abandoned
DEVUI_OFFLINE_STOPPED6devui_stop or devui_factory_reset

devui_event_t

typedef struct { ... } devui_event_t;

An event. Valid during the callback only, pointers included.

FieldTypeDescription
typedevui_event_type_tthe enum devui_event_type_t, whose members say which fields each event fills
sessionuint16_tthe events of a tab (SESSION_OPEN, SESSION_CLOSE): its session, as devui_msg_t.session
roleuint8_tSESSION_OPEN: 1 owner, 2 operator, 3 reader
reopenedboolSESSION_OPEN: the tab was open before a reconnection
resultuint8_tBUNDLE_REJECTED: why (above); OFFLINE: a devui_offline_reason_t
pair_codeconst 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_urlconst char *(the same comment as the line above)
pair_ttl_suint16_tPAIR_CODE, PAIR_CODE_ACCEPTED: seconds the code has left; PAIR_BUTTON: the window
userconst 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_codeuint16_tOFFLINE: the WebSocket close code that ended the connection, received (CLOUD) or sent (DEVICE); 0 when none
owner_genuint32_tOWNER_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_eventuint8_tTRUST_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_kinduint8_t(the same comment as the line above)
order_reasonuint8_t(the same comment as the line above)
order_sequint32_t(the same comment as the line above)
session_kinduint8_tSESSION_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).
prefsconst 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.

FieldTypeDescription
time_zonechar [65]the IANA name, 1 to 64 characters ("America/Sao_Paulo"); the device has no IANA database
posix_tzchar [65]the same zone as a POSIX TZ rule, 1 to 64 ("<-03>3", "EST5EDT,M3.2.0,M11.1.0")
localechar [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.

FieldTypeDescription
openboolfunction 7, devui_session_info: whether the session is open
roleuint8_tfunction 7, devui_session_info, and devui_event_t.role
kinduint8_tDEVUI_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.

NameValueDescription
DEVUI_STATUS_STOPPED0function 8, devui_status: stopped
DEVUI_STATUS_CONNECTING1waiting for the network or the handshake, or between attempts
DEVUI_STATUS_ONLINE2function 8, devui_status: online

devui_config_t

typedef struct { ... } devui_config_t;

Documented in: function 1, devui_start, and the comment of each member.

FieldTypeDescription
bundleconst 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_sizesize_t(the same comment as the line above)
manifestconst uint8_t *(the same comment as the line above)
manifest_sizesize_t(the same comment as the line above)
project_keyconst char *optional: the product's public key
fw_versionconst char *optional: the app's version, sent in the HELLO (shown at pairing)
optionsuint32_tDEVUI_OPT_*; 0 by default
adc_holdvoid (*)(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_ctxvoid *(the same comment as the line above)
task_wdtboolthe 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_tokenconst 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_sigconst 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_sizesize_t(the same comment as the line above)
hostconst char *the gateway, as in the certificate and the signed transcript
portuint16_tThe 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_pemconst char *the roots, PEM; NULL: those of the build's trust profile
vaultboolThe 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_tzboolThe 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.

FieldTypeDescription
statusuint8_tDEVUI_CALL_*
resultuint8_tthe cloud's answer as it came (status, for the cloud's; 0 for the SDK's own)
dataconst uint8_t *DEVUI_CALL_OK: the callee's answer (len 0 when it answered nothing)
lensize_tits bytes
textboolthe answer came as text (the callee's devui_reply of a DEVUI_TEXT message)
retry_after_msuint32_tDEVUI_CALL_LIMIT: the wait the cloud asks for (0: none said)
error_codeuint16_tDEVUI_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.

FieldTypeDescription
statusuint8_tDEVUI_DB_*
resultuint8_tthe cloud's answer as it came; 0 when the SDK says DEVUI_DB_UNAVAILABLE itself
answerconst char *the answer in JSON, NOT NUL-terminated (len bytes); NULL when none came
lensize_tthe bytes of answer
retry_after_msuint32_tDEVUI_DB_LIMIT, DEVUI_DB_UNAVAILABLE: the wait the cloud asks for (0: none said)
error_codeuint16_tDEVUI_DB_ERROR: the code of the cloud's ERROR, 0 when it was an unknown answer
queuedboolan 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-...").