Skip to content
ThingFace

Compatibility: SDK, protocol and lib

Three pieces talk: the SDK in the firmware, the cloud (gateway and relay) and the page's lib (/_devui/v1.js). They speak the devui.1 protocol in minor versions: 1.0 since 13/10/2026, 1.1 since 14/10 and 1.2 since 16/10. Pieces of different versions work together both ways, with nobody needing to update at the same time.

How the version is chosen

The device states its version in the HELLO. The cloud uses the lower of its own and the device's, and never sends what the device does not understand. The device need not know the cloud's version: what a new version brings comes in a frame or a field that an older cloud simply does not send. A device version above the one the cloud knows counts as the cloud's and is never refused. Whoever gets a field or a frame type it does not know ignores it and logs it.

The matrix

Device (SDK)CloudWhat happens
1.21.2Everything: the change of owner told to the firmware (OWNER_CHANGED, OWNER_GEN), trust orders (TRUST_ORDER), the last state and the plan's allowance.
1.11.2The cloud does not send what belongs to 1.2. The last state works if the product has the opt-in (the 1.1 SDK already sends STATE). A spent allowance reaches the app as error 4429. On a change of owner, the former owner's tabs close as with a 1.2, and the portal warns both owners and recommends a reset.
1.01.2As the 1.1, and still without pairing through the protocol (PAIR).
1.21.1The cloud treats the device as 1.1 and keeps no state. Nothing in the 1.2 SDK depends on the 1.2 cloud: with no OWNER_GEN, it keeps the stored generation and raises no event.
LibRelayWhat happens
1.21.2Everything, with lastKnown (the last state) and the cloud's time on the updates.
1.11.2The lib ignores the new fields: lastKnown stays null, and a spent allowance shows as RATE_LIMITED.
1.21.1With no last state, lastKnown is null at the opening; with no cloud time, the updates' time is the local one.

The ESP8266 ("8266" profile, since 18/10) speaks the same 1.2 without the trust orders: a TRUST_ORDER is logged and dropped, and changing the endpoint or the CA means flashing the board again (The SDK on the ESP8266, in Portuguese). The HELLO's diagnostic fields (LAST_DROP, WIFI_RSSI, 21/10) are optional: a cloud that does not know them ignores them, and an SDK that does not send them leaves the device's health without them.

The business event (devui_audit, 26/10) does not change the version: a cloud that takes it says so in the HELLO_ACK (AUDIT_QUOTA), and the SDK sends it to that cloud only. With an earlier cloud, devui_audit answers ESP_ERR_NOT_SUPPORTED and nothing goes on the wire; an earlier SDK ignores the new field of the HELLO_ACK and never sends the event.

The interface's signature in the HELLO (BUNDLE_SIG, 26/10) does not change the version either: an earlier cloud ignores the field and takes the interface as unsigned; an earlier SDK does not send it, and ignores the REFUSAL of the HELLO_ACK (it sees only the REJECT, as with the daily ceiling).

The refusal of the firmware's interface in a product with its interface in the cloud (REFUSAL 4, since 11/11) does not change the version either: the cloud sends the REJECT with REFUSAL 4, and the SDK says on the serial why and stays connected, as at every REJECT; an earlier SDK sees the REJECT, logs the 4 as a number and stays connected all the same. An earlier cloud never sends it. A firmware with no interface (no web/) announces no bundle in the HELLO, and nothing is refused, with any cloud.

The account's preferences (the PREFS frame, 0x66, since 10/11) do not change the version: the SDK announces it knows them by bit 7 of OPTIONS in the HELLO, always, and the cloud sends PREFS only to whoever announced it. With an earlier cloud, which does not send it, the board stays without the preferences (devui_get_prefs answers ESP_ERR_NOT_FOUND) and with the firmware's TZ; an earlier SDK does not announce the bit and never gets the frame (The account's preferences).

The database (the frames DB, 0x26, and DB_REPLY, 0x27, since 10/11) changes neither the version nor the HELLO: only a board that calls devui_db_* sends DB. A cloud from before the database ignores the frame, as every type it does not know, and the request ends in DEVUI_DB_UNAVAILABLE after 10 s; an earlier SDK never sends it (Database).

The local mode (since 31/10) does not go through the cloud: the local tabs are sessions from 0x8000 to 0xFFFE that never go on the wire, and the board serves it with any cloud, also with none (Local mode).

The SDK's versions

The SDK has a number of its own, MAJOR.MINOR.PATCH, in devui/devui_version.h (devui_version() returns it), and the board sends it in the HELLO. It is not the protocol's version: each version of the SDK says in What changed which protocol it speaks, and a new minor version of the protocol brings a MINOR version of the SDK, never the other way. Until the launch, the versions stay below 1.0.0:

Goes upWhen
MINOR (0.1.0 → 0.2.0, PATCH back to 0)something new for whoever uses the SDK: a new function, type or constant in the API (devui.h, DevUI.h); a new frame, field or OPTIONS bit; a new minor version of the protocol; a new command or option of the CLI; a new format the project must change to; a new example or port; a new partition table or build requirement
PATCH (0.1.0 → 0.1.1)a fix with nothing new to use: a defect, security, performance, memory, a log text, a CLI message
nothingonly documentation, tests or tools that do not go in the package

In doubt, MINOR. The number goes up with each change that reaches the board or the CLI, so two boards with the same number run the same SDK; a board built before the first version, 0.1.0, sends 0.0.0. The CLI (devui, in the User-Agent), the Arduino library, the ESP-IDF component and the Rust binding carry the same number. A change of documentation only does not raise the number: in What changed, its entry stays under "Not versioned yet", in "Documentation", and goes with the next version. The v1 API is frozen (below): a break of it would be announced prominently in What changed.

The HELLO carries two versions, of two different things:

SDK_VERSIONFW_VERSION
WhoseThingFace's: the SDK linked into the firmwarethe maker's: their firmware
Set bydevui_version.h, fixed at buildthe app, in fw_version of devui_config_t (optional)
FormatMAJOR.MINOR.PATCH, below 1.0.0 until the launchfree, up to 32 bytes
What the cloud doeschecks the minimum safe version and the end of support of each line (MAJOR.MINOR), and the product's minimum versiononly shows it (device health, pairing, fleet)

The SDK does not write its own number in fw_version: the LED example sends the ESP-IDF app's version (esp_app_get_description()->version).

The SDK's and the lib's API

The SDK's v1 API (devui.h and the Rust binding) and the lib's (v1.d.ts) are frozen since 16/10/2026: nothing is removed or changes its signature or meaning, and only compatible additions go in. The new functions since then: devui_trust_order_local (in 1.2); devui_audit (26/10); devui_session_close and devui_call (27/10); devui_local_secret, devui_local_secret_renew, devui_vault_psk_text, devui_vault_reset and devui_vault_enroll (31/10); devui_db_request, devui_db_insert, devui_db_update, devui_db_delete, devui_db_find, devui_db_aggregate, devui_db_queue and devui_get_prefs (10/11). And the fields, events and constants that came with them: session_kind and prefs in devui_event_t, kind in devui_session_info_t, provision_token and bundle_sig (reserved before), vault and manual_tz in devui_config_t, the events DEVUI_EV_PAIR_CODE_ACCEPTED and DEVUI_EV_PREFS. In the Arduino library, each one got its method of the same name (The Arduino library). A break needs a v2, served beside the v1. The exception, by the decision of 26/10: the kind field of Event::SessionOpen and of SessionInfo in the Rust binding, which asks for .. from code that destructures those types (What changed). In the page, a switch over an error code, a close reason, a state or a role keeps a default, because a new version may add values.

The whole rule is in the protocol's specification, devui.1.