Pular para o conteúdo
ThingFace

Modo local: a interface na rede local

No modo local, a placa serve a própria interface direto na rede local, para quando a nuvem está fora do ar ou longe: quem está na mesma rede (o Wi-Fi do lugar, o ponto de acesso do próprio produto, a Ethernet) abre http://<IP da placa>/ no navegador, entra com a senha local da placa e usa a mesma interface, a mesma lib (/_devui/v1.js) e as mesmas mensagens que pela nuvem. É do ESP-IDF, desligado por padrão.

Ligar

No menuconfig, ligue Local mode: the UI on the LAN and on the app's AP (CONFIG_DEVUI_LOCAL), ou ponha no sdkconfig.defaults do projeto:

CONFIG_DEVUI_LOCAL=y

Desligado, o servidor HTTP não entra no firmware (nem na flash, nem na RAM), e devui_local() responde ESP_ERR_NOT_SUPPORTED. Ligado, o app chama devui_local() depois do devui_start, de qualquer task:

ESP_ERROR_CHECK(devui_start(&cfg));
esp_err_t l = devui_local(); /* ESP_OK também quando já roda */

CONFIG_DEVUI_LOCAL_TABS (de 1 a 4; 2 por padrão) diz quantos navegadores abrem a interface na rede local ao mesmo tempo; o seguinte recebe 503 e tenta de novo.

No exemplo do LED, o sdkconfig.localmode liga o modo (CONFIG_EXAMPLE_LOCAL=y, que liga o CONFIG_DEVUI_LOCAL). Acrescente-o à lista do passo 5 do quickstart, numa pasta de build nova:

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

No boot, a serial mostra modo local: abra http://<IP da placa>/ na mesma rede; senha local XXXX-XXXX-XXXX-XXXX. A página do exemplo, aberta pela nuvem pelo dono, também pede a senha ({"senha_local":true}): a placa só a responde à aba do dono que veio pela nuvem, nunca a uma aba local nem a uma chamada da API.

A senha local

O navegador só abre a página depois do login da placa, com a senha local: 16 caracteres do base32 Crockford (XXXX-XXXX-XXXX-XXXX, 80 bits), sorteados na própria placa no primeiro devui_local, com a mesma guarda de entropia da chave. A nuvem nunca a vê, e o SDK nunca a põe no log. O app a dá ao dono por um caminho que pede a placa na mão ou o papel de dono:

  • devui_local_secret(texto, tamanho) a escreve em texto (pelo menos DEVUI_LOCAL_SECRET_SIZE, 20 bytes), para a tela do produto, uma etiqueta, a serial, ou a interface na nuvem, só para o dono;
  • devui_local_secret_renew() sorteia outra e a guarda na hora: todo navegador logado sai, e toda aba local fecha.

A senha sobrevive a um reinício e vai embora com o devui_factory_reset(). Cinco senhas erradas seguidas travam o login por 30 s, e a trava dobra a cada nova série, até 15 min. Um login vale 30 dias, ou até a placa reiniciar.

O que a placa serve

  • A interface do firmware: o bundle da configuração (a pasta web/ gravada na placa), nunca a publicação do produto, que mora na nuvem. Um firmware sem web/ (o recomendado num produto com a interface na nuvem: veja Firmware sem interface) não tem interface na rede local: a placa responde 404 às páginas. Quem quer o modo local num produto assim grava também a pasta web/ no firmware.
  • A lib (/_devui/v1.js), a mesma da nuvem.
  • O /_devui/env, com mode: "local", para a interface saber onde roda; ele diz também o locale e o time_zone da conta dona, ou null (Preferências da conta).

Cada aba local é uma sessão de 0x8000 a 0xFFFE, do tipo DEVUI_SESSION_LOCAL (devui_event_t.session_kind e devui_session_info_t.kind), com o papel de operador. devui_send, devui_reply, devui_session_info e devui_session_close valem para ela, e DEVUI_ALL chega às abas locais também (e às da nuvem, quando a placa está online). O firmware trata a aba local como trata as outras; para saber de onde ela veio, olha o tipo da sessão.

Segurança

  • HTTP sem TLS: nenhum navegador aceita um certificado para um IP privado, então o tráfego na rede local vai aberto. O que a interface manda ali, quem escuta aquela rede vê. A senha protege o acesso, não o conteúdo.
  • Nunca num ponto de acesso aberto: o ponto de acesso do app precisa de WPA2 ou WPA3; aberto, devui_local() responde ESP_ERR_INVALID_STATE.
  • A interface local é servida em todas as interfaces de rede que o app subiu, na porta 80.

Onde não existe

  • ESP8266: não tem modo local; devui_local() responde ESP_ERR_NOT_SUPPORTED.
  • Biblioteca Arduino (ESP32): o pacote é compilado sem o CONFIG_DEVUI_LOCAL, então DevUI.local(), DevUI.localSecret e DevUI.localSecretRenew respondem ESP_ERR_NOT_SUPPORTED.
  • Binding Rust: local() liga o modo, mas a senha local ainda não tem função no binding.

A referência completa: devui_local, devui_local_secret e devui_local_secret_renew.