Pular para o conteúdo principal

SenseCAP Indicator com Home Assistant via MQTT

Este guia mostra como transformar o SenseCAP Indicator em um painel complementar do Home Assistant. Após a configuração, o Indicator publica as leituras de seus sensores integrados no Home Assistant por meio de MQTT, e o Home Assistant pode enviar comandos de interruptor e controle deslizante de volta para a tela do Indicator.

Adquira agora

O que você vai construir​

A integração usa três tópicos MQTT fixos:

DireçãoTópicoFinalidade
Indicator para Home Assistantindicator/sensorPublica leituras de temperatura, umidade, CO2 e tVOC
Home Assistant para Indicatorindicator/switch/setEnvia comandos de interruptor e controle deslizante
Indicator para Home Assistantindicator/switch/statePublica o estado atual do interruptor e do controle deslizante

No lado do Home Assistant, você criará quatro entidades de sensor, seis entidades de interruptor e duas entidades numéricas. No lado do Indicator, você configurará o Wi-Fi e o broker MQTT e, em seguida, usará a tela como um painel de controle local.

Pré-requisitos​

  • SenseCAP Indicator D1 ou hardware SenseCAP Indicator compatível
  • Uma instância do Home Assistant em execução
  • Um broker MQTT acessível tanto pelo Home Assistant quanto pelo Indicator
  • ESP-IDF v5.4.x instalado se você planeja compilar o firmware a partir do código-fonte
  • Um cabo USB para gravação e monitoramento serial

Antes de continuar, leia o guia do usuário do SenseCAP Indicator se você não estiver familiarizado com a placa.

1. Prepare o Home Assistant​

Se você já tem o Home Assistant e um broker MQTT, pode pular para a Etapa 3: Compile e grave o firmware.

O Home Assistant OS é o caminho mais simples porque oferece suporte a Add-ons, incluindo o broker Mosquitto e o File editor.

nota

O Home Assistant pode ser executado em vários modos de instalação. Se você usar o Home Assistant Container, os Add-ons não estarão disponíveis, portanto será necessário executar separadamente um broker MQTT como Mosquitto ou EMQX.

Home Assistant Green é uma forma plug-and-play de começar a usar o Home Assistant.

Siga o guia de instalação oficial do Home Assistant para o seu dispositivo. Quando a configuração inicial estiver concluída, você deverá chegar ao painel do Home Assistant.

2. Instale o Mosquitto e ative o MQTT​

Instalar Add-ons​

No Home Assistant OS, instale dois Add-ons:

  • Mosquitto broker para mensagens MQTT
  • File editor para editar configuration.yaml pela interface web do Home Assistant

Vá em Settings > Add-ons > Add-on Store e instale ambos os Add-ons.

Para maior conveniência, ative Show in sidebar para o File editor.

Após a instalação, você deverá ver ambos os Add-ons.

Ativar a integração MQTT​

Vá em Settings > Devices & services > Integrations, procure por MQTT e siga o fluxo de configuração.

dica

Se o Home Assistant não descobrir seu broker automaticamente, insira o host do broker manualmente. Isso é comum quando você usa um broker externo em vez do Add-on Mosquitto.

Criar credenciais MQTT​

Se o seu broker MQTT exigir autenticação, crie um nome de usuário e senha para o Indicator. No Add-on Mosquitto broker, adicione um usuário e mantenha as credenciais à mão; você irá inseri-las no Indicator mais tarde.

Add User Button
Create User Form

3. Compile e grave o firmware​

O firmware atual para Home Assistant é mantido no repositório sensecap-indicator-ha.

git clone https://github.com/Love4yzp/sensecap-indicator-ha
cd sensecap-indicator-ha

Instale o ESP-IDF v5.4.x e exporte IDF_PATH no seu shell. Em seguida, compile, grave e abra o monitor serial:

./dev build
./dev flash
./dev monitor

Para sair do monitor serial, pressione Ctrl-].

dica

./dev flash detecta automaticamente a porta serial. Se você precisar especificar uma porta, execute ./dev flash -p /dev/ttyUSB0 ou use o nome de dispositivo serial correspondente ao seu sistema operacional.

Comandos manuais do ESP-IDF

Se você preferir chamar o ESP-IDF diretamente:

. "$IDF_PATH/export.sh"
idf.py build
idf.py -p /dev/ttyUSB0 -b 460800 flash monitor

O firmware do ESP32-S3 usa ESP-IDF v5.4.x e LVGL 9. Mantenha as configurações do sdkconfig.defaults do projeto, especialmente CONFIG_LV_MEM_CUSTOM=y, PSRAM em modo OCT a 120 MHz, CPU a 240 MHz e flash QIO a 120 MHz.

4. Configure Wi-Fi e MQTT no Indicator​

Após a gravação, configure o Wi-Fi e o MQTT na tela sensível ao toque do Indicator. O endereço do broker MQTT deve apontar para o broker usado pelo Home Assistant.

Você também pode configurar o MQTT pelo console serial:

ComandoDescrição
mqtthelpImprime exemplos de broker, tópico e payload
haconfigImprime a configuração atual de MQTT e do Home Assistant
setmqtt -a <addr>Define o endereço do broker
setmqtt -a <addr> -c <client-id> -u <user> -p <pass>Define o endereço do broker, ID do cliente, nome de usuário e senha

Exemplos:

setmqtt -a 192.168.1.10 -c indicator-01 -u mqtt_user -p mqtt_password
setmqtt --addr mqtt://192.168.1.10:1883
setmqtt --addr mqtt://broker.emqx.io

Depois que o setmqtt for bem-sucedido, a configuração será salva na memória não volátil e o cliente MQTT será reiniciado automaticamente.

cuidado

O Indicator e o Home Assistant devem conseguir alcançar o mesmo broker MQTT. Se eles estiverem em redes ou VLANs diferentes, verifique o roteamento, as regras de firewall e as configurações de escuta do broker.

5. Adicione entidades MQTT ao Home Assistant​

O Home Assistant precisa de definições de entidades que correspondam aos tópicos do firmware. Abra o File editor, escolha configuration.yaml e adicione o seguinte bloco sob a chave de nível superior mqtt:.

cuidado

Não substitua todo o seu configuration.yaml. Se você já tiver uma seção mqtt:, acrescente as entradas sensor, switch e number dentro dessa seção existente.

YAML de entidades MQTT
mqtt:
  sensor:
    - unique_id: indicator_temperature
      name: "Indicator Temperature"
      state_topic: "indicator/sensor"
      suggested_display_precision: 1
      unit_of_measurement: "°C"
      value_template: "{{ value_json.temp }}"
    - unique_id: indicator_humidity
      name: "Indicator Humidity"
      state_topic: "indicator/sensor"
      unit_of_measurement: "%"
      value_template: "{{ value_json.humidity }}"
    - unique_id: indicator_co2
      name: "Indicator CO2"
      state_topic: "indicator/sensor"
      unit_of_measurement: "ppm"
      value_template: "{{ value_json.co2 }}"
    - unique_id: indicator_tvoc
      name: "Indicator tVOC"
      state_topic: "indicator/sensor"
      unit_of_measurement: ""
      value_template: "{{ value_json.tvoc }}"
  switch:
    - unique_id: indicator_switch1
      name: "Indicator Switch1"
      state_topic: "indicator/switch/state"
      command_topic: "indicator/switch/set"
      value_template: "{{ value_json.switch1 }}"
      payload_on: '{"switch1":1}'
      payload_off: '{"switch1":0}'
      state_on: 1
      state_off: 0
    - unique_id: indicator_switch2
      name: "Indicator Switch2"
      state_topic: "indicator/switch/state"
      command_topic: "indicator/switch/set"
      value_template: "{{ value_json.switch2 }}"
      payload_on: '{"switch2":1}'
      payload_off: '{"switch2":0}'
      state_on: 1
      state_off: 0
    - unique_id: indicator_switch3
      name: "Indicator Switch3"
      state_topic: "indicator/switch/state"
      command_topic: "indicator/switch/set"
      value_template: "{{ value_json.switch3 }}"
      payload_on: '{"switch3":1}'
      payload_off: '{"switch3":0}'
      state_on: 1
      state_off: 0
    - unique_id: indicator_switch4
      name: "Indicator Switch4"
      state_topic: "indicator/switch/state"
      command_topic: "indicator/switch/set"
      value_template: "{{ value_json.switch4 }}"
      payload_on: '{"switch4":1}'
      payload_off: '{"switch4":0}'
      state_on: 1
      state_off: 0
    - unique_id: indicator_switch6
      name: "Indicator Switch6"
      state_topic: "indicator/switch/state"
      command_topic: "indicator/switch/set"
      value_template: "{{ value_json.switch6 }}"
      payload_on: '{"switch6":1}'
      payload_off: '{"switch6":0}'
      state_on: 1
      state_off: 0
    - unique_id: indicator_switch7
      name: "Indicator Switch7"
      state_topic: "indicator/switch/state"
      command_topic: "indicator/switch/set"
      value_template: "{{ value_json.switch7 }}"
      payload_on: '{"switch7":1}'
      payload_off: '{"switch7":0}'
      state_on: 1
      state_off: 0
  number:
    - unique_id: indicator_switch5
      name: "Indicator Switch5"
      state_topic: "indicator/switch/state"
      command_topic: "indicator/switch/set"
      command_template: '{"switch5": {{ value }} }'
      value_template: "{{ value_json.switch5 }}"
    - unique_id: indicator_switch8
      name: "Indicator Switch8"
      state_topic: "indicator/switch/state"
      command_topic: "indicator/switch/set"
      command_template: '{"switch8": {{ value }} }'
      value_template: "{{ value_json.switch8 }}"

Salve o arquivo e, em seguida, vá para Developer Tools > YAML e recarregue a configuração YAML.

Configuração YAML em Developer Tools
dica

Se as entidades não aparecerem, use primeiro Check configuration. Se a configuração for válida, mas as entidades ainda não aparecerem, reinicie o Home Assistant e confirme que o Indicator está publicando em indicator/sensor.

6. Criar um painel​

Você pode adicionar as novas entidades a qualquer painel. Para manter o Indicator separado, crie um painel dedicado em Settings > Dashboards.

Criar painel
Novo painel

Abra o painel, escolha Edit Dashboard e, em seguida, use o Raw configuration editor.

Editar painel
Assumir controle
YAML do painel
cuidado

Este YAML é para o editor de configuração bruta do painel Lovelace. Não cole isso em configuration.yaml.

views:
  - title: Indicator device
    icon: ''
    badges: []
    cards:
      - graph: line
        type: sensor
        detail: 1
        icon: mdi:molecule-co2
        unit: ppm
        entity: sensor.indicator_co2
      - graph: line
        type: sensor
        entity: sensor.indicator_temperature
        detail: 1
        icon: mdi:coolant-temperature
      - graph: line
        type: sensor
        detail: 1
        entity: sensor.indicator_humidity
      - graph: line
        type: sensor
        entity: sensor.indicator_tvoc
        detail: 1
        icon: mdi:air-filter
      - type: entities
        entities:
          - entity: switch.indicator_switch1
          - entity: switch.indicator_switch2
          - entity: switch.indicator_switch3
          - entity: switch.indicator_switch4
          - entity: number.indicator_switch5
          - entity: switch.indicator_switch6
          - entity: switch.indicator_switch7
          - entity: number.indicator_switch8
        title: Indicator control
        show_header_toggle: false
        state_color: true

Salve a configuração do painel.

Editor de configuração bruta
Salvar configuração

Agora você deve ver as leituras dos sensores e os controles do Indicator no Home Assistant.

Referência do protocolo MQTT​

Use esta seção quando quiser depurar o tráfego MQTT ou criar seus próprios cards do Home Assistant.

TópicoExemplo de payload
indicator/sensor{"temp":"23.5","humidity":"45","co2":"450","tvoc":"100"}
indicator/switch/set{"switch1":1,"switch5":50}
indicator/switch/state{"switch1":1,"switch2":0}

Chaves de sensor:

ChaveSignificado
tempTemperatura
humidityUmidade relativa
co2Concentração de CO2
tvocCompostos orgânicos voláteis totais

Chaves de controle:

ChaveTipo de entidade no Home AssistantFaixa
switch1 a switch4, switch6, switch7switch0 ou 1
switch5, switch8numberValor inteiro

Solução de problemas​

SintomaO que verificar
O Home Assistant não mostra entidadesConfirme que o YAML foi adicionado sob mqtt:, depois recarregue o YAML ou reinicie o Home Assistant
Os valores dos sensores permanecem desconhecidosConfirme que o Indicator está conectado ao Wi-Fi e publicando em indicator/sensor
Os controles não atualizam o IndicatorConfirme que o Home Assistant publica em indicator/switch/set e que o Indicator está conectado ao mesmo broker
Falha no login MQTTDigite novamente o endereço do broker, nome de usuário e senha no Indicator ou com setmqtt
Comando serial não está claroExecute mqtthelp no console serial

Para desenvolvedores​

O firmware usa um design com dois MCUs:

MCUFunção
ESP32-S3Display, toque, Wi-Fi, MQTT, lógica do Home Assistant, configurações e console
RP2040Aquisição de sensores internos e Grove, retransmitida para o ESP32-S3 via UART

O firmware do ESP32-S3 é construído com ESP-IDF v5.4.x e LVGL 9. Domínios de runtime são organizados como fatias de modelo/visão: o código do modelo é responsável pelo estado, NVS, MQTT e análise de sensores; o código da visão é responsável pelos objetos LVGL e callbacks da tela sensível ao toque.

Comandos úteis para desenvolvedores:

python3 scripts/dev_check.py --skip-build
python3 scripts/dev_check.py
./dev build

O simulador para PC pode ajudar ao iterar no layout da interface sem precisar gravar o hardware:

cmake -S sim -B sim/build && cmake --build sim/build -j4
./sim/build/sensecap_sim

Recursos​

Suporte técnico​

Precisa de ajuda com o seu SenseCAP Indicator? Visite o Canal oficial da Seeed no Discord ou inicie uma discussão em Discussões do SenseCAP Indicator SDK no GitHub.

Loading Comments...