Pular para o conteúdo
ThingFace

Compatibilidade: SDK, protocolo e lib

Três peças conversam: o SDK no firmware, a nuvem (gateway e relay) e a lib da página (/_devui/v1.js). Elas falam o protocolo devui.1 em versões menores: 1.0 desde 13/10/2026, 1.1 desde 14/10 e 1.2 desde 16/10. As peças de versões diferentes funcionam juntas nos dois sentidos, sem que ninguém precise atualizar ao mesmo tempo.

Como a versão é escolhida

O dispositivo diz a versão dele no HELLO. A nuvem usa a menor entre a dela e a dele, e nunca manda o que ele não entende. O dispositivo não precisa saber a versão da nuvem: o que uma versão nova traz chega por quadro ou campo que a nuvem velha só não manda. Uma versão do dispositivo acima da que a nuvem conhece vale como a da nuvem e nunca é recusada. Quem recebe um campo ou um tipo de quadro que não conhece o ignora e registra.

A matriz

Dispositivo (SDK)NuvemO que acontece
1.21.2Tudo: troca de dono avisada ao firmware (OWNER_CHANGED, OWNER_GEN), ordens de confiança (TRUST_ORDER), o último estado e a franquia do plano.
1.11.2A nuvem não manda o que é da 1.2. O último estado funciona se o produto tem o opt-in (o SDK 1.1 já manda STATE). A franquia esgotada chega ao app como erro 4429. Na troca de dono, as abas do dono antigo fecham como num 1.2, e o portal avisa os dois donos e recomenda o reset.
1.01.2Como o 1.1, e ainda sem o pareamento pelo protocolo (PAIR).
1.21.1A nuvem trata o dispositivo como 1.1 e não guarda estado. Nada no SDK 1.2 depende da nuvem 1.2: sem OWNER_GEN, ele mantém a geração guardada e não emite evento.
LibRelayO que acontece
1.21.2Tudo, com lastKnown (o último estado) e a hora da nuvem nas atualizações.
1.11.2A lib ignora os campos novos: lastKnown fica null, e a franquia esgotada aparece como RATE_LIMITED.
1.21.1Sem o último estado, lastKnown é null na abertura; sem a hora da nuvem, a das atualizações é a local.

O ESP8266 (perfil "8266", desde 18/10) fala a mesma 1.2, sem as ordens de confiança: uma TRUST_ORDER é registrada no log e descartada, e trocar o endpoint ou a CA pede regravar a placa (O SDK no ESP8266). Os campos de diagnóstico do HELLO (LAST_DROP, WIFI_RSSI, 21/10) são opcionais: uma nuvem que não os conhece os ignora, e um SDK que não os manda deixa a saúde do dispositivo sem eles.

O evento de negócio (devui_audit, 26/10) não muda a versão: a nuvem que o aceita diz isso no HELLO_ACK (AUDIT_QUOTA), e o SDK só o manda a ela. Com uma nuvem anterior, devui_audit responde ESP_ERR_NOT_SUPPORTED e nada vai ao fio; um SDK anterior ignora o campo novo do HELLO_ACK e nunca manda o evento.

A assinatura da interface no HELLO (BUNDLE_SIG, 26/10) também não muda a versão: uma nuvem anterior ignora o campo e aceita a interface como sem assinatura; um SDK anterior não o manda, e ignora o REFUSAL do HELLO_ACK (vê só o REJECT, como no teto do dia).

A recusa da interface do firmware num produto com a interface na nuvem (REFUSAL 4, desde 11/11) também não muda a versão: a nuvem manda o REJECT com o REFUSAL 4, e o SDK diz na serial por quê e segue conectado, como em todo REJECT; um SDK anterior vê o REJECT, registra o 4 como número e segue conectado do mesmo jeito. Uma nuvem anterior nunca o manda. Um firmware sem interface (sem web/) não anuncia bundle no HELLO, e nada é recusado, com qualquer nuvem.

As preferências da conta (o quadro PREFS, 0x66, desde 10/11) não mudam a versão: o SDK anuncia que as conhece pelo bit 7 de OPTIONS no HELLO, sempre, e a nuvem só manda o PREFS a quem anunciou. Com uma nuvem anterior, que não o manda, a placa fica sem as preferências (devui_get_prefs responde ESP_ERR_NOT_FOUND) e com o TZ do firmware; um SDK anterior não anuncia o bit e nunca recebe o quadro (Preferências da conta).

O banco de dados (os quadros DB, 0x26, e DB_REPLY, 0x27, desde 10/11) não muda a versão nem o HELLO: só a placa que chama devui_db_* manda o DB. Uma nuvem anterior ao banco ignora o quadro, como todo tipo que não conhece, e o pedido termina em DEVUI_DB_UNAVAILABLE depois de 10 s; um SDK anterior nunca o manda (Banco de dados).

O modo local (desde 31/10) não passa pela nuvem: as abas locais são sessões de 0x8000 a 0xFFFE que nunca vão ao fio, e a placa o serve com qualquer nuvem, também sem nenhuma (Modo local).

As versões do SDK

O SDK tem um número próprio, MAJOR.MINOR.PATCH, em devui/devui_version.h (devui_version() o devolve), e a placa o manda no HELLO. Ele não é a versão do protocolo: cada versão do SDK diz em O que mudou qual protocolo fala, e uma versão menor nova do protocolo traz uma versão MINOR do SDK, nunca o contrário. Até o lançamento, as versões ficam abaixo de 1.0.0:

SobeQuando
MINOR (0.1.0 → 0.2.0, o PATCH volta a 0)entra algo novo para quem usa o SDK: função, tipo ou constante nova na API (devui.h, DevUI.h); quadro, campo ou bit de OPTIONS novo; versão menor nova do protocolo; comando ou opção nova da CLI; um formato novo que o projeto precisa mudar; exemplo ou porte novo; tabela de partições ou requisito de build novo
PATCH (0.1.0 → 0.1.1)uma correção sem nada novo para usar: defeito, segurança, desempenho, memória, texto de log, mensagem da CLI
nadasó documentação, testes ou ferramentas que não vão no pacote

Na dúvida, MINOR. O número sobe a cada mudança que chega à placa ou à CLI, então duas placas com o mesmo número rodam o mesmo SDK; uma placa compilada antes da primeira versão, o 0.1.0, manda 0.0.0. A CLI (devui, no User-Agent), a biblioteca Arduino, o componente do ESP-IDF e o binding Rust levam o mesmo número. Uma mudança só de documentação não sobe o número: em O que mudou, a entrada dela fica em "Ainda sem versão", sob "Documentação", e vai junto na próxima versão. A API v1 está congelada (abaixo): uma quebra dela seria avisada em destaque em O que mudou.

O HELLO leva duas versões, de duas coisas diferentes:

SDK_VERSIONFW_VERSION
De quemdo ThingFace: o SDK ligado ao firmwaredo fabricante: o firmware dele
Quem defineo devui_version.h, fixo no buildo app, em fw_version do devui_config_t (opcional)
FormatoMAJOR.MINOR.PATCH, abaixo de 1.0.0 até o lançamentolivre, até 32 bytes
O que a nuvem fazconfere a versão mínima segura e o fim do suporte de cada linha (MAJOR.MINOR), e a versão mínima do produtosó mostra (saúde do dispositivo, pareamento, frota)

O SDK não escreve o próprio número no fw_version: o exemplo do LED manda a versão do app do ESP-IDF (esp_app_get_description()->version).

A API do SDK e da lib

A API v1 do SDK (devui.h e o binding Rust) e a da lib (v1.d.ts) estão congeladas desde 16/10/2026: nada sai nem muda de assinatura ou de sentido, e só entram adições compatíveis. As funções novas desde então: devui_trust_order_local (na 1.2); devui_audit (26/10); devui_session_close e devui_call (27/10); devui_local_secret, devui_local_secret_renew, devui_vault_psk_text, devui_vault_reset e 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 e devui_get_prefs (10/11). E os campos, eventos e constantes que vieram com elas: session_kind e prefs em devui_event_t, kind em devui_session_info_t, provision_token e bundle_sig (antes reservados), vault e manual_tz em devui_config_t, os eventos DEVUI_EV_PAIR_CODE_ACCEPTED e DEVUI_EV_PREFS. Na biblioteca Arduino, cada uma ganhou o método de mesmo nome (A biblioteca Arduino). Uma quebra pede uma v2, servida ao lado da v1. A exceção, por decisão de 26/10: o campo kind de Event::SessionOpen e de SessionInfo no binding Rust, que pede .. a quem desmonta esses tipos (O que mudou). Na página, quem faz switch sobre um código de erro, um motivo de fechamento, um estado ou um papel mantém um default, porque uma versão nova pode acrescentar valores.

A regra inteira está na especificação do protocolo, devui.1.