rbAmp
PT
Loja
Docs
Atualizado · Editar no GitHub (Edit on GitHub)

08 · Home Assistant — análise aprofundada

Este capítulo cobre os detalhes específicos do HA para trabalhar com o rbAmp: descoberta, API nativa, painel de Energia, estatísticas de longo prazo, cartões Lovelace, automações e funcionamento em ambientes onde o HA corre em Docker ou WSL.

Cross-references:


1 · Descoberta: mDNS ou IP manual

Os nós ESPHome anunciam-se por mDNS (multicast DNS) quando o YAML contém um bloco api:. A integração ESPHome do HA escuta estes anúncios e propõe automaticamente os novos dispositivos.

O que a descoberta automática precisa para funcionar:

  • O ESP32 e o HA têm de estar no mesmo segmento de rede de Camada 2 (uma VLAN, sem router entre eles). O mDNS é multicast e não atravessa um router sem configuração extra (reflector mDNS / proxy Avahi).
  • O multicast UDP não pode ser bloqueado pelo router nem por uma funcionalidade de isolamento de clientes no ponto de acesso. Os APs de consumo têm frequentemente uma funcionalidade de "AP isolation" ou "wireless isolation" — bloqueia o multicast entre dispositivos. Desative-a para a VLAN IoT ou para os dispositivos específicos.
  • O HA tem de resolver corretamente o mDNS. Em implementações Docker / WSL isto por vezes exige configuração de rede extra (ver §10).

Fluxo de descoberta:

  1. Grave o ESP32 e deixe-o arrancar. Liga-se ao WiFi e começa a anunciar-se por mDNS como .local.
  2. No HA: Definições (Settings) → Dispositivos e Serviços (Devices & Services) → Integrações (Integrations). Aparece um banner "New devices found", ou procure o ESPHome na lista de integrações com um distintivo de descoberta.
  3. Clique em "Configurar" (Configure) na nova entrada. O HA pede a chave de encriptação, se estiver configurada (§3).
  4. Todos os sensores são adicionados ao dispositivo automaticamente.

Adição manual (se o mDNS estiver bloqueado)

Definições (Settings) → Dispositivos e Serviços (Devices & Services) → Adicionar integração (Add Integration) → ESPHome.

Introduza o IP do ESP32 (verifique a tabela DHCP do router ou o registo de arranque do ESPHome — a linha [I][wifi:189]: IP: 192.168.x.y). A porta predefinida é 6053.

Atribua uma concessão DHCP estática para o endereço MAC do ESP32 no router, para que o IP não mude após um reinício do router.


2 · API nativa do ESPHome (porta 6053) vs MQTT

O ESPHome suporta dois transportes. Ambos funcionam com o rbAmp.

Propriedade API nativa (porta 6053) MQTT
Integração com o HA De primeira classe: uma integração ESPHome dedicada com descoberta automática Genérico: requer um broker MQTT, configuração manual de entidades ou descoberta MQTT
Encriptação Incorporado (protocolo de ruído, opcional) Depende da configuração TLS do broker
Latência Baixa — TCP direto sem broker Depende do broker
Fiabilidade Reconexão automática Depende da disponibilidade do broker
Sem o HA Inútil (a API é específica do HA) Qualquer subscritor MQTT pode consumi-lo
Complexidade da instalação Sem infraestrutura adicional Requer um broker MQTT em execução

Recomendação: use a API nativa (bloco api:) quando o HA for o principal consumidor. Adicione mqtt: apenas se precisar de um consumidor paralelo não-HA (Grafana, Node-RED, scripts personalizados). Ambos podem coexistir no mesmo YAML.

A API nativa é o caminho descrito neste documento. Os detalhes de MQTT estão em 07_diy_integrations.md §2.


3 · Chave de encriptação

Por predefinição a API nativa não é encriptada — qualquer máquina na rede local pode ligar-se à porta 6053. Isto é aceitável para uma rede doméstica de confiança. Para mais segurança, acrescente uma chave:

YAML
api:
  encryption:
    key: "BASE64_ENCODED_32_BYTE_KEY"

Gerar uma chave:

Shell
python3 -c "import base64, os; print(base64.b64encode(os.urandom(32)).decode())"

Quando adicionar o dispositivo ao HA (Definições → Dispositivos e Serviços → ESPHome → Adicionar), introduza a mesma chave. O HA guarda-a na configuração da integração e usa-a automaticamente em todas as ligações seguintes a este nó.

Coloque a chave em secrets.yaml:

YAML
# secrets.yaml (untracked, next to the device YAML)
api_key: "BASE64_ENCODED_32_BYTE_KEY"
YAML
# device YAML
api:
  encryption:
    key: !secret api_key

Se alterar a chave, tem de remover e voltar a adicionar o dispositivo no HA.


4 · Configuração do painel de energia

Os sensores energy do rbAmp (e energy_1, energy_2, energy_exported, energy_total, energy_exported_total, etc.) chegam já configurados com (energy_net usa state_class: total porque pode diminuir; reactive_energy* estão em varh):

YAML
device_class: energy
state_class: total_increasing
unit_of_measurement: Wh

Esta é exatamente a combinação que o painel Energia do HA espera para sensores de consumo ou geração acumulados. Não são necessários sensores template extra. Cada sensor de energia precisa de voltage e current declarados no mesmo bloco sensor: (adicione internal: true para os ocultar do Home Assistant).

Adicionar sensores ao painel Energia

Definições (Settings) → Painéis (Dashboards) → Energia (Energy). O painel tem quatro secções:

Secção Qual sensor rbAmp usar
Consumo da rede energy (importação da rede) ou energy_total (STANDARD (STD), todos os canais)
Retorno à rede Precisa de um módulo STANDARD (STD) — um módulo BASIC lê sempre 0 para a exportação. energy_exported precisa de bidirectional: true mais voltage e current no mesmo bloco; energy_exported_total cobre todos os canais (apenas STANDARD (STD))
Painéis solares energy de um módulo que mede a saída do inversor solar (módulo STANDARD (STD) se o mesmo módulo também tiver de reportar a exportação)
Bateria doméstica Não aplicável (o rbAmp não mede DC)
Dispositivos individuais energy_1, energy_2, etc. de um módulo multi-canal

Para uma instalação única na casa inteira:

  1. Clique em "Add consumption" em Grid consumption. [Adicionar consumo / Consumo da rede]
  2. Selecione a entidade Mains Energy. [Mains Energy]
  3. Opcionalmente, defina uma tarifa (EUR/kWh ou a moeda local) para o controlo de custos.

Para uma instalação de três módulos (rede + solar + VE do Exemplo 11 em 06_examples.md):

  1. Consumo da rede: House Energy (de meter_house).
  2. Retorno à rede: Solar Energy Exported (de meter_solar, STANDARD (STD); deixar vazio no BASIC).
  3. Painéis solares: Solar Energy (a partir de meter_solar). [Energia solar]
  4. Dispositivo individual: EV Charger Energy (de meter_evcharger).

Persistência NVS e painel de Energia

O componente ESPHome guarda a energia total na NVS do ESP32 a cada 5 minutos (e no encerramento limpo, como um reinício ou OTA). Num módulo STANDARD os totais vêm dos próprios contadores de energia do módulo, pelo que também sobrevivem a reinícios do módulo e se mantêm monótonos. No arranque os valores são restaurados da NVS e publicados de imediato — antes de o HA se ligar e antes de disparar o primeiro update_interval.

Isto impede que o painel de Energia interprete um 0 Wh momentâneo como uma reposição de contador. Se o HA vir um valor total_increasing descer para 0, trata a diferença como um limite de período de faturação e descarta o histórico acumulado.

A perda de dados no pior caso numa falha de energia súbita é até 5 minutos de acumulação (≈5 Wh com uma carga média de 60 W — invisível nos totais diários).

last_reset após OTA ou reinício do ESP32

O painel Energia do HA usa device_class energy + state_class total_increasing sem vinculação explícita de last_reset — esta é a configuração recomendada do ESPHome. Num reinício do ESP32, o componente restaura o valor a partir da NVS antes do primeiro publish_state, pelo que o HA vê uma série contínua e monotonicamente crescente e não insere uma reposição sentinela no gráfico. Isto funciona por desenho.

Casos-limite em que pode ver uma "reposição" visível:

  • A NVS está corrompida (o magic não corresponde ou o CRC falha). O componente arranca em 0 Wh e o HA regista uma descontinuidade. Sintoma: o painel mostra um "pico da manhã" no momento em que o nó arranca após um longo período parado. Correção: verifique no registo de arranque do ESP32 as mensagens [E][rbamp_nvs] — indicam a causa (um layout NVS incompatível, pouca carga no momento da escrita, etc.). Restaure a partir de uma cópia de segurança do histórico do HA ou elimine o pico fantasma com as ferramentas do HA.

  • Substituição de hardware (novo ESP32, mesmo módulo). O componente arranca em 0 Wh — o módulo não passa a sua contagem acumulada por I²C (o módulo e o componente mantêm acumuladores separados; o módulo só fornece valores instantâneos para integrar). O HA regista uma descontinuidade. Correção: depois de gravar o novo ESP32, semeie o valor inicial de energia com um mqtt.publish manual (para MQTT) ou com uma edição temporária do YAML com inicialização por lambda. Ou aceite a descontinuidade como um evento único.

  • update_interval: alterado entre compilações de firmware de forma notável (por exemplo 60 → 600 s). A alteração, por si só, não repõe nada, mas ciclos mais longos produzem "degraus" mais grosseiros no gráfico. Visualmente parece uma mudança de modo de acumulação; funcionalmente está correto.

  • O gravador do HA foi truncado ou restaurado a partir de uma cópia de segurança antiga. Isto não está do lado do ESPHome — é do lado do HA: o HA pode tratar alguns valores futuros como "passados" e redesenhar o gráfico. Não tem nada a ver com o ESPHome.

Durante uma regravação OTA de rotina, last_reset não é definido, o snapshot da NVS é restaurado ~50 ms antes de o HA se ligar, e o painel de Energia não vê descontinuidade. Este é o cenário de base.


5 · Contador de utilidade

A integração utility_meter do HA deriva sensores que se repõem periodicamente a partir de qualquer sensor total_increasing. Use-a para obter kWh diários, semanais e mensais além do acumulador bruto.

YAML do Home Assistant (não ESPHome) — vai para a configuração do Home Assistant, não para o YAML do nó.

YAML
# configuration.yaml
utility_meter:
  energy_daily:
    source: sensor.rbamp_ui1_mains_energy
    cycle: daily

  energy_monthly:
    source: sensor.rbamp_ui1_mains_energy
    cycle: monthly

  energy_yearly:
    source: sensor.rbamp_ui1_mains_energy
    cycle: yearly

O HA cria três entidades novas (sensor.energy_daily, etc.) que se repõem a 0 no início de cada período. São ótimas para vistas de dispositivo individual no painel Energia e como base para sensores template de custo.

Exemplos de custo e kWh/dia estão em 06_examples.md §10.


6 · Sensor de estatísticas para mín. / máx. / média

O sensor statistics do HA calcula mínimo, máximo, média e desvio-padrão deslizantes sobre uma janela temporal configurável, a partir do histórico de qualquer sensor:

YAML do Home Assistant (não ESPHome) — vai para a configuração do Home Assistant, não para o YAML do nó.

YAML
# configuration.yaml
sensor:
  - platform: statistics
    name: "Mains Power 1h Average"
    entity_id: sensor.rbamp_ui1_mains_power
    state_characteristic: mean
    sampling_size: 60          # last 60 points
    max_age:
      hours: 1

  - platform: statistics
    name: "Mains Power 24h Peak"
    entity_id: sensor.rbamp_ui1_mains_power
    state_characteristic: value_max
    max_age:
      hours: 24

Estes sensores derivados são úteis para gestão da procura (janela de consumo de pico, máximo mensal para faturação tarifária) e deteção de anomalias (se o máximo de potência de 24 horas subir de repente acima dos valores históricos).


7 · Estatísticas de longo prazo

O HA escreve os sensores com state_class: total_increasing e state_class: measurement na sua base de dados de estatísticas de longo prazo (LTS). Os dados LTS são mantidos indefinidamente (independentemente da retenção do gravador de curto prazo).

Para verificar que um sensor rbAmp chega ao LTS:

  1. Ferramentas de Programador → Estatísticas. [Developer Tools → Statistics]
  2. Encontre a entidade (por exemplo sensor.rbamp_ui1_mains_energy).
  3. Confirme que a respetiva linha tem um statistic_id e um last_stats_ts recente.

O LTS é usado pelo painel de Energia para vistas históricas e é exportado através de "Download statistics" do HA. [Descarregar estatísticas]

Ao substituir um módulo rbAmp (hardware novo, novo entity ID), o histórico LTS antigo não é migrado automaticamente. Para preservar o histórico, mantenha o mesmo name: de cada sensor no novo YAML. O ESPHome gera o entity ID a partir do nome do nó mais o nome do sensor; nomes iguais dão o mesmo statistic_id.


8 · Cartões Lovelace

Cartão de fluxo de energia (integrado)

O painel Energia integrado do HA já inclui um cartão de fluxo de energia no topo da página de definições de Energia. É desenhado depois de o painel Energia estar configurado (consumo da rede, solar, bateria). Não é necessária configuração extra.

Medidor

YAML do Home Assistant (não ESPHome) — vai para a configuração do Home Assistant, não para o YAML do nó.

YAML
type: gauge
entity: sensor.rbamp_ui1_mains_power
min: 0
max: 5000
name: "Live Power"
unit: W
severity:
  green: 0
  yellow: 2000
  red: 3500

Cartão de lista de sensores

YAML do Home Assistant (não ESPHome) — vai para a configuração do Home Assistant, não para o YAML do nó.

YAML
type: entities
title: "rbAmp UI1"
entities:
  - entity: sensor.rbamp_ui1_mains_voltage
    name: Voltage
  - entity: sensor.rbamp_ui1_mains_current
    name: Current
  - entity: sensor.rbamp_ui1_mains_power
    name: Power
  - entity: sensor.rbamp_ui1_mains_power_factor
    name: Power Factor
  - entity: sensor.rbamp_ui1_mains_frequency
    name: Frequency
  - entity: sensor.rbamp_ui1_mains_energy
    name: Energy (total)

Cartão de gráfico mini (HACS)

Instalado via HACS (§11):

YAML do Home Assistant (não ESPHome) — vai para a configuração do Home Assistant, não para o YAML do nó.

YAML
type: custom:mini-graph-card
entities:
  - entity: sensor.rbamp_ui1_mains_power
    name: Power
hours_to_show: 6
points_per_hour: 4
line_width: 2
show:
  extrema: true
  average: true

Apex Charts (HACS)

YAML do Home Assistant (não ESPHome) — vai para a configuração do Home Assistant, não para o YAML do nó.

YAML
type: custom:apexcharts-card
header:
  title: "Power (W)"
  show: true
graph_span: 24h
span:
  end: now
series:
  - entity: sensor.rbamp_ui1_mains_power
    name: Power
    type: area
    stroke_width: 2
    fill_raw: last
  - entity: sensor.rbamp_ui1_mains_power
    name: 1h avg
    type: line
    stroke_width: 1
    color: orange
    group_by:
      func: avg
      duration: 1h

9 · Automatismos do HA vs on_value do ESPHome

Tanto os automatismos do HA como os callbacks on_value do ESPHome reagem a alterações nos sensores rbAmp. Escolher a ferramenta:

Cenário Automação do HA on_value do ESPHome
Notificação push Sim — acesso a todos os serviços do HA (notify, TTS, etc.) Não — o ESP32 não tem serviço de notificação
Acionar um relé no mesmo ESP32 Possível (HA → interruptor), mas acrescenta latência Sim — funciona no próprio dispositivo, sem dependência da rede
Acionamento quando o HA está offline Não Sim — o ESP32 atua de forma autónoma
Condições complexas (combinando entidades, histórico, calendário) Sim Limitado — Lambda em C++, sem acesso ao estado do HA
Latência de reação ~1–5 s (ida e volta Wi-Fi + API) ~0 ms (o mesmo ciclo de eventos)
Reagir a uma publicação MQTT Sim (acionador MQTT) N/A

Conselho prático: use o on_value do ESPHome para ações locais de baixa latência (acionar um relé, um indicador LED, um buzzer) e as automações do HA para tudo o que precise de serviços do HA (notificações, ativação de cenas, agendamento de calendário, combinações com outras entidades).

Exemplo de automação do HA — combinando o rbAmp e um interruptor do HA:

YAML do Home Assistant (não ESPHome) — vai para a configuração do Home Assistant, não para o YAML do nó.

YAML
automation:
  - alias: "Cut dishwasher when peak tariff starts"
    trigger:
      - platform: time
        at: "16:00:00"              # start of the peak tariff
    condition:
      - condition: numeric_state
        entity_id: sensor.rbamp_ui1_mains_power
        above: 1500                 # only switch off if the load is high
    action:
      - service: switch.turn_off
        target:
          entity_id: switch.dishwasher_socket

10 · WSL e Docker

O HA costuma correr em Docker (através da imagem homeassistant/home-assistant ou do Home Assistant OS numa VM). O ESPHome corre quer como add-on do HA (no mesmo ambiente de contentores), quer como contentor Docker separado.

mDNS em Docker / WSL

O mDNS (UDP multicast 5353) não atravessa as fronteiras de rede Docker por predefinição. Se o HA estiver em Docker e o ESP32 estiver na LAN física:

  • Rede do host Docker (--network host em Linux) dá ao contentor acesso a multicast e normalmente resolve o problema.
  • Repetidor mDNS: ferramentas como avahi-daemon com allow-interfaces corretos ou mdns-repeater fazem a ponte do multicast entre a ponte Docker (docker0) e a interface LAN física.
  • Adição manual: contorne completamente o mDNS — adicione o ESP32 à integração ESPHome do HA manualmente pelo IP.

No Windows com WSL2, a VM WSL2 tem o seu próprio adaptador de rede virtual. Os contentores Docker dentro dela podem estar atrás de duas camadas de NAT (Windows → WSL2 → ponte Docker). O mDNS quase de certeza não funcionará — adicione por IP.

Add-on ESPHome vs ESPHome independente

Ao usar o add-on ESPHome do HA, o contentor do add-on partilha o namespace de rede com o HA (assumindo rede host, que é o padrão no HA OS). O mDNS e a descoberta de dispositivos funcionam sem configuração extra.

Quando executa o ESPHome como contentor Docker autónomo, certifique-se de que o contentor tem acesso à LAN física (--network host em Linux) e de que /dev/ttyUSB0 (ou a sua porta COM) está transmitida para a gravação por USB:

Shell
docker run -it --rm --network host \
  -v /path/to/configs:/config \
  --device /dev/ttyUSB0:/dev/ttyUSB0 \
  ghcr.io/esphome/esphome compile /config/ui1.yaml

IP estático para um OTA fiável

Num ambiente Docker / VLAN são fortemente recomendadas concessões DHCP estáticas para os dispositivos ESP32 rbAmp. Evitam:

  • Um endereço IP desatualizado registado no HA para a entrada da integração ESPHome.
  • Uma gravação OTA falhada (esphome upload --device 192.168.x.y).
  • Uma falha de qualquer automação que use a API por IP.

11 · HACS (Home Assistant Community Store)

O HACS é um gestor de integrações de terceiros para o HA que dá acesso a cartões, integrações e automações desenvolvidos pela comunidade. Não é necessário para o funcionamento básico do rbAmp, mas é útil para os cartões Lovelace mais ricos da §8.

Instale-o a partir de https://hacs.xyz/. Depois instale estes cartões da comunidade:

Cartão Categoria HACS Utilização com o rbAmp
mini-graph-card Frontend Gráfico de potência / corrente ao longo do tempo
apexcharts-card Frontend Gráficos de várias séries
lovelace-card-mod Frontend CSS personalizado em qualquer cartão
energy-flow-card-plus Frontend Diagrama de fluxo de energia melhorado

A instalação e a gestão do HACS estão descritas na respetiva documentação. Os cartões estão documentados nos respetivos repositórios GitHub.


12 · Notificações push por limiar

A aplicação móvel do HA (home-assistant.io/integrations/mobile_app) oferece notificações push em iOS e Android. Combinada com os sensores rbAmp, obtém alertas imediatos de sobrecorrente, sobrepotência, perda da rede ou qualquer outro limiar:

YAML do Home Assistant (não ESPHome) — vai para a configuração do Home Assistant, não para o YAML do nó.

YAML
automation:
  - alias: "rbAmp over-current alert"
    trigger:
      - platform: numeric_state
        entity_id: sensor.rbamp_ui1_mains_current
        above: 14.0           # alert at 14 A (below a typical 16 A breaker)
        for:
          seconds: 10
    action:
      - service: notify.mobile_app_your_phone_name
        data:
          title: "Over-current warning"
          message: >
            Current is {{ states('sensor.rbamp_ui1_mains_current') | round(2) }} A
            — approaching 16 A breaker limit.
          data:
            push:
              sound:
                name: default
                critical: 1    # a critical alert bypasses Do Not Disturb (iOS)
              interruption-level: critical

  - alias: "rbAmp mains loss alert"
    trigger:
      - platform: numeric_state
        entity_id: sensor.rbamp_ui1_mains_voltage
        below: 10
        for:
          seconds: 5
    action:
      - service: notify.mobile_app_your_phone_name
        data:
          title: "Mains power lost"
          message: "Voltage dropped to {{ states('sensor.rbamp_ui1_mains_voltage') }} V."

Para que o serviço notify.mobile_app_* fique disponível, a aplicação HA Companion tem de estar instalada no dispositivo de destino e a integração mobile-app tem de estar configurada no HA. Os detalhes estão em https://companion.home-assistant.io/.


13 · Configuração do Add-on ESPHome do HA

Ao usar o add-on ESPHome do HA (recomendado para a maioria dos utilizadores):

  1. O Add-on guarda as configurações YAML em /config/esphome/ (acessível através do sistema de ficheiros do HA ou do editor do Add-on).
  2. O secrets.yaml fica ao lado dos ficheiros YAML do dispositivo, em /config/esphome/.
  3. Oexternal_componentso caminho tem de ser acessível a partir do interior do contentor do Add-on. Opções:
    • Recomendado: use a forma remota: source: github://rb-amp/rbamp-esphome@v1.9.0 (o componente é publicado no GitHub).
    • Em alternativa, copie a pasta components/rbamp/ para /config/esphome/components/ e especifique path: components/ (relativo).
  4. OTA: o Add-on faz ele próprio o flash OTA — clique em "Install" no cartão do dispositivo e o Add-on tenta um OTA para o último IP conhecido. A gravação por USB também está disponível através da porta série do Add-on, se o ESP32 estiver ligado ao anfitrião do HA.

O add-on inclui um visualizador de logs integrado (o botão "Logs" no cartão do dispositivo) — o equivalente a esphome logs na CLI.


14 · Nomenclatura das entidades e estabilidade do entity ID

Os IDs das entidades no HA derivam do nome do nó ESPHome e do campo name: do sensor:

Text
sensor._

Para o nó rbamp-ui1 e um sensor com name: "Mains Voltage":

Text
sensor.rbamp_ui1_mains_voltage

Os IDs de entidade aparecem em automações, sensores de modelo, painéis Lovelace e na configuração do painel de Energia. Alterar o name: de um sensor no YAML cria um ID de entidade novo e quebra todas as referências ao antigo. Planeie os nomes dos sensores antes da primeira implementação.

Para mudar o nome de um sensor sem quebrar o entity ID:

  1. Renomeie o sensor no YAML.
  2. Volte a gravar o dispositivo.
  3. No HA: Definições (Settings) → Dispositivos e Serviços (Devices & Services) → ESPHome → o seu dispositivo → clique no sensor → clique no ícone de engrenagem → renomeie o ID da entidade de volta para o valor antigo (ou altere-o para um novo e atualize todas as referências).

Uma alternativa é a funcionalidade "Entity ID rename" do HA (Definições → Entidades → pesquisar → clicar na entidade → editar nome / entity ID) — permite separar o nome de apresentação do entity ID. Pode renomear livremente o nome de apresentação sem afetar as automações.


Fonte e problemas: rb-amp/rbamp-esphome · esta página no repositório: docs/08_has_integrations.md (v1.9.1)