Configuração do ESP RainMaker

Esta página descreve a configuração do ESP RainMaker para o OpenSprinklerPro. Nomes técnicos, eventos e campos de API permanecem inalterados.

Este documento descreve como o firmware do OpenSprinkler lida com o provisionamento do ESP RainMaker, abrangendo os métodos BLE Claiming e On-Network.

Visão Geral

O ESP RainMaker requer duas etapas antes que um dispositivo possa ser controlado na nuvem:

  1. Claiming (Registro) — O dispositivo obtém certificados TLS do servidor de registro da Espressif. Esses certificados autenticam a comunicação MQTT criptografada do dispositivo com a nuvem RainMaker.
  2. Mapeamento de Nó de Usuário — O dispositivo é vinculado à conta RainMaker do usuário para que ele possa gerenciar o aspersor pelo aplicativo móvel.

Métodos de Provisionamento

BLE Claiming (Configuração Inicial)

Utilizado quando o dispositivo não possui certificados TLS (primeira inicialização ou após restauração de fábrica).

Fluxo de Trabalho:

  1. O firmware detecta que não há certificado de cliente TLS no NVS de fábrica (esp_rmaker_factory_get("client_cert")).
  2. O núcleo do RainMaker é iniciado (RMaker.start()).
  3. O provisionamento BLE começa via WiFiProv.beginProvision(NETWORK_PROV_SCHEME_BLE, ...).
  4. O dispositivo anuncia-se como um dispositivo BLE (nome do serviço: PROV_XXXXXX).
  5. O usuário abre o aplicativo móvel ESP RainMaker → "Add Device" (Adicionar Dispositivo) → escaneia o rádio BLE.
  6. O aplicativo do celular conecta via BLE e:
  7. Encaminha o CSR (Certificate Signing Request) para o servidor de registro da Espressif.
  8. Retorna o certificado TLS assinado para o dispositivo.
  9. Opcionalmente fornece credenciais de rede WiFi.
  10. O dispositivo armazena os certificados sob o NVS de fábrica.
  11. O evento RMAKER_EVENT_CLAIM_SUCCESSFUL é disparado.
  12. O dispositivo se conecta ao MQTT via rede WiFi ou Ethernet.

Prioridade: Durante o claiming BLE, o rádio Bluetooth é usado exclusivamente para provisionamento. O monitoramento de sensores BLE (sensor_radio_early_init()) é adiado até que o pareamento termine. Após o evento CLAIM_SUCCESSFUL, o BLE é liberado e o escaneamento de sensores virtuais é retomado.

Configuração On-Network (Vinculação de Usuário)

Utilizado quando os certificados TLS já existem no dispositivo, mas é necessário vinculá-lo à conta de um novo usuário.

Fluxo de Trabalho:

  1. O firmware detecta um certificado TLS de cliente válido → inicia no modo normal.
  2. O núcleo do RainMaker inicia e estabelece a conexão MQTT.
  3. O serviço de controle local é ativado (esp_local_ctrl) em uma porta TCP.
  4. O mDNS anuncia o serviço _esp_local_ctrl._tcp para descoberta no aplicativo móvel.
  5. O usuário abre o aplicativo ESP RainMaker → "Add Device" → "On Network".
  6. O aplicativo localiza o dispositivo via mDNS na rede local.
  7. O usuário insere o código PIN PoP (Proof of Possession).
  8. A solicitação de mapeamento é enviada para a nuvem RainMaker.

Requisito: O celular e o dispositivo devem estar na mesma rede de internet (WiFi ou cabo Ethernet).

Suporte para Ethernet

Ambos os métodos funcionam quando conectado diretamente via cabo de rede Ethernet:

  • Ethernet + BLE Claiming: O dispositivo possui rede ativa via Ethernet. O Bluetooth é usado apenas para a troca de dados inicial (CSR via app do celular). A interface Web do OpenSprinkler permanece disponível normalmente durante o claiming BLE. Ao finalizar, o MQTT conecta via Ethernet.
  • Ethernet + On-Network: O controle local e anúncios mDNS são publicados tanto na interface WiFi quanto na interface Ethernet. O aplicativo no celular poderá descobrir o controlador na mesma rede local por qualquer uma das vias.

Prioridade de Sensores

Durante o claiming BLE, os sensores que dependem de Bluetooth (ex: sensores de temperatura e solo BLE) são pausados:

  • sensor_radio_early_init() é ignorado quando OSRainMaker::sensors_deferred() retorna verdadeiro.
  • sensor_api_connect() é atrasado até a conclusão do claiming.
  • Após o CLAIM_SUCCESSFUL, ocorre um intervalo de 3 segundos para liberação do canal de rede (HANDLER_FREE_BLE).
  • Em seguida, o sensor_radio_early_init() é executado de forma automática, seguido do sensor_api_connect().

Isso ocorre apenas na primeira ativação do dispositivo. Em boots subsequentes, os sensores são ativados imediatamente.

Endpoint de API

A chamada GET /rk?pw=<hash> retorna o estado de provisionamento:

Campo Tipo Descrição
provisioning 0/1 Indica se há provisionamento ativo (BLE ou On-Network)
ble_claiming 0/1 Indica claiming assistido via Bluetooth em andamento
sensors_deferred 0/1 Indica se a inicialização de sensores BLE está aguardando provisionamento
local_ctrl_active 0/1 Indica se a busca local via mDNS (On-Network) está ativa
pop string Código PIN de Proof of Possession (vindo do eFuse)
prov_service string Nome de serviço do rádio BLE para identificação no app

PoP (Proof of Possession)

O código PIN PoP é gerado a partir do endereço de rede MAC eFuse físico do chip do dispositivo e é único para cada controlador:

  • É exibido no log serial durente o boot da placa.
  • É mostrado no display de LCD durante o provisionamento BLE.
  • É exposto na interface do usuário (menu suspenso do RainMaker → PoP PIN).
  • Pode ser lido pelo endpoint de API /rk.

Timeout e Fallback

  • O provisionamento BLE possui um timeout de 5 minutos.
  • Caso o aplicativo de celular não faça a conexão em 5 minutos, o controlador retorna ao modo WiFi padrão (Estação + Access Point).
  • A interface gráfica de controle torna-se acessível pelo IP de AP local (192.168.4.1) ou por cabo Ethernet.
  • Um reinício do equipamento reinicia a tentativa de claiming BLE caso os dados ainda estejam ausentes.

Logs de Debug

Todos os eventos são exibidos sob a tag RMAKER com o nível de nível INFO utilizando macros customizadas:

I (xxx) RMAKER: === RainMaker BLE CLAIMING mode ===
I (xxx) RMAKER: BLE provisioning has PRIORITY over sensor BLE — sensors deferred
I (xxx) RMAKER: Starting BLE provisioning: service=PROV_XXXXXX pop=XXXXXXXX
I (xxx) RMAKER: Event: CLAIM_STARTED — contacting claiming server...
I (xxx) RMAKER: Event: CLAIM_SUCCESSFUL — TLS certs provisioned!
I (xxx) RMAKER: === Claiming successful — TLS certs received ===
I (xxx) RMAKER: Sensor BLE init will resume after BLE cleanup (~3s)

Arquivos Fonte

  • opensprinkler_rainmaker.h / .cpp — Lógica e controle de integração do RainMaker.
  • main.cpp — Máquina de estados WiFi, atraso na inicialização de sensores de rádio.