Skip to content
ThingFace

Local mode: the interface on the local network

In the local mode, the board serves its own interface straight on the local network, for when the cloud is down or far: whoever is on the same network (the place's Wi-Fi, the product's own access point, the Ethernet) opens http://<the board's IP>/ in the browser, signs in with the board's local password and uses the same interface, the same lib (/_devui/v1.js) and the same messages as through the cloud. It is ESP-IDF's, off by default.

Turning it on

In menuconfig, turn on Local mode: the UI on the LAN and on the app's AP (CONFIG_DEVUI_LOCAL), or put in the project's sdkconfig.defaults:

CONFIG_DEVUI_LOCAL=y

Off, the HTTP server does not go into the firmware (neither in the flash nor in the RAM), and devui_local() answers ESP_ERR_NOT_SUPPORTED. On, the app calls devui_local() after devui_start, from any task:

ESP_ERROR_CHECK(devui_start(&cfg));
esp_err_t l = devui_local(); /* ESP_OK also when it already runs */

CONFIG_DEVUI_LOCAL_TABS (1 to 4; 2 by default) says how many browsers open the interface on the local network at the same time; the next one gets 503 and tries again.

In the LED example, sdkconfig.localmode turns the mode on (CONFIG_EXAMPLE_LOCAL=y, which turns on CONFIG_DEVUI_LOCAL). Add it to the list of step 5 of the quickstart, in a new build folder:

idf.py -B build/esp32 -D IDF_TARGET=esp32 -D SDKCONFIG=build/esp32/sdkconfig -D "SDKCONFIG_DEFAULTS=sdkconfig.defaults;sdkconfig.local;sdkconfig.localmode" build

At boot, the serial shows modo local: abra http://<IP da placa>/ na mesma rede; senha local XXXX-XXXX-XXXX-XXXX ("local mode: open http://<the board's IP>/ on the same network; local password ..."). The example's page, opened by the owner through the cloud, also asks for the password ({"senha_local":true}): the board answers it only to the owner's tab that came through the cloud, never to a local tab nor to an API call.

The local password

The browser opens the page only after the board's login, with the local password: 16 characters of Crockford base32 (XXXX-XXXX-XXXX-XXXX, 80 bits), drawn on the board itself at the first devui_local, with the same entropy guard as the key. The cloud never sees it, and the SDK never logs it. The app hands it to the owner by a way that needs the board in hand or the owner's role:

  • devui_local_secret(text, size) writes it in text (at least DEVUI_LOCAL_SECRET_SIZE, 20 bytes), for the product's display, a label, the serial, or the interface in the cloud, to the owner only;
  • devui_local_secret_renew() draws another and keeps it at once: every browser signed in leaves, and every local tab closes.

The password survives a restart and goes with devui_factory_reset(). Five wrong passwords in a row lock the login for 30 s, and the lock doubles at each new run, up to 15 min. A login lasts 30 days, or until the board restarts.

What the board serves

  • The firmware's interface: the bundle of the configuration (the web/ folder flashed on the board), never the product's publication, which lives in the cloud. A firmware with no web/ (the recommended one in a product with its interface in the cloud: see Firmware without an interface) has no interface on the local network: the board answers 404 to the pages. Whoever wants the local mode in such a product flashes the web/ folder in the firmware too.
  • The lib (/_devui/v1.js), the same as the cloud's.
  • /_devui/env, with mode: "local", for the interface to know where it runs; it also says the owner account's locale and time_zone, or null (The account's preferences).

Each local tab is a session from 0x8000 to 0xFFFE, of the kind DEVUI_SESSION_LOCAL (devui_event_t.session_kind and devui_session_info_t.kind), with the operator's role. devui_send, devui_reply, devui_session_info and devui_session_close work for it, and DEVUI_ALL reaches the local tabs too (and the cloud's, when the board is online). The firmware treats the local tab as it treats the others; to know where it came from, it looks at the session's kind.

Security

  • HTTP with no TLS: no browser takes a certificate for a private IP, so the traffic on the local network goes in the clear. What the interface sends there, whoever listens to that network sees. The password protects the access, not the content.
  • Never on an open access point: the app's access point needs WPA2 or WPA3; open, devui_local() answers ESP_ERR_INVALID_STATE.
  • The local interface is served on every network interface the app brought up, on port 80.

Where it does not exist

  • ESP8266: no local mode; devui_local() answers ESP_ERR_NOT_SUPPORTED.
  • Arduino library (ESP32): the package is built without CONFIG_DEVUI_LOCAL, so DevUI.local(), DevUI.localSecret and DevUI.localSecretRenew answer ESP_ERR_NOT_SUPPORTED.
  • Rust binding: local() turns the mode on, but the local password has no function in the binding yet.

The whole reference: devui_local, devui_local_secret and devui_local_secret_renew.