rbAmp
ES
Tienda
Docs
Actualizado · Editar en GitHub

08 · Home Assistant — análisis en profundidad

Este capítulo cubre los detalles específicos de HA para trabajar con rbAmp: descubrimiento, API nativa, panel de energía, estadísticas a largo plazo, tarjetas Lovelace, automatizaciones y funcionamiento en entornos donde HA se ejecuta en Docker o WSL.

Cross-references:


1 · Descubrimiento: mDNS o IP manual

Los nodos ESPHome se anuncian por mDNS (multicast DNS) cuando el YAML contiene un bloque api:. La integración ESPHome de HA escucha estos anuncios y ofrece automáticamente los nuevos dispositivos.

Lo que necesita el descubrimiento automático para funcionar:

  • El ESP32 y HA deben estar en el mismo segmento de red de capa 2 (una sola VLAN, sin router entre ellos). mDNS es multidifusión y no cruza un router sin configuración adicional (reflector mDNS / proxy Avahi).
  • El multicast UDP no debe bloquearlo el router ni una función de aislamiento de clientes en el punto de acceso. Los puntos de acceso de consumo suelen tener una función de «AP isolation» o «wireless isolation», que bloquea el multicast entre dispositivos. Desactívela para la VLAN de IoT o para los dispositivos concretos.
  • HA debe resolver mDNS correctamente. En despliegues con Docker / WSL esto a veces requiere configuración de red adicional (vea §10).

Flujo de descubrimiento:

  1. Grabe el ESP32 y deje que arranque. Se conecta al WiFi y empieza a anunciarse por mDNS como .local.
  2. En HA: Ajustes → Dispositivos y servicios → Integraciones. Aparece un aviso de «Nuevos dispositivos encontrados», o busque ESPHome en la lista de integraciones con una insignia de descubrimiento [Settings → Devices & Services → Integrations].
  3. Pulse «Configurar» [Configure] en la nueva entrada. HA le pide la clave de cifrado si hay una configurada (§3).
  4. Todos los sensores se añaden automáticamente al dispositivo.

Alta manual (si mDNS está bloqueado)

Ajustes → Dispositivos y servicios → Añadir integración → ESPHome [Settings → Devices & Services → Add Integration → ESPHome].

Introduzca la IP del ESP32 (compruebe la tabla DHCP del router o la línea de arranque de ESPHome: [I][wifi:189]: IP: 192.168.x.y). El puerto por defecto es 6053.

Asigne una concesión DHCP estática para la MAC del ESP32 en el router, para que la IP no cambie tras reiniciar el router.


2 · API nativa de ESPHome (puerto 6053) frente a MQTT

ESPHome admite dos transportes. Ambos funcionan con rbAmp.

Propiedad API nativa (puerto 6053) MQTT
Integración con HA De primera clase: una integración ESPHome dedicada con autodescubrimiento Genérico: requiere un broker MQTT, configuración manual de entidades o descubrimiento MQTT
Cifrado Integrado (protocolo de ruido, opcional) Depende de la configuración TLS del broker
Latencia Baja: TCP directo sin broker Depende del broker
Fiabilidad Reconexión automática Depende de la disponibilidad del broker
Sin HA Inútil (la API es específica de HA) Cualquier suscriptor MQTT puede consumirlo
Complejidad de la instalación Sin infraestructura adicional Requiere un broker MQTT en funcionamiento

Recomendación: use la API nativa (bloque api:) cuando HA sea el consumidor principal. Añada mqtt: solo si necesita un consumidor paralelo no HA (Grafana, Node-RED, scripts personalizados). Ambos pueden coexistir en un mismo YAML.

La API nativa es la vía descrita en este documento. Los detalles de MQTT están en 07_diy_integrations.md §2.


3 · Clave de cifrado

Por defecto la API nativa no está cifrada: cualquier equipo de la red local puede conectarse al puerto 6053. Eso es aceptable en una red doméstica de confianza. Para más seguridad, añada una clave:

YAML
api:
  encryption:
    key: "BASE64_ENCODED_32_BYTE_KEY"

Generación de una clave:

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

Al añadir el dispositivo a HA (Ajustes → Dispositivos y servicios → ESPHome → Añadir), introduzca la misma clave. HA la guarda en la configuración de la integración y la usa automáticamente en todas las conexiones posteriores a este nodo.

Ponga la clave en 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

Si cambia la clave, debe eliminar y volver a añadir el dispositivo en HA.


4 · Configuración del panel de energía

Los sensores energy de rbAmp (y energy_1, energy_2, energy_exported, energy_total, energy_exported_total, etc.) llegan ya configurados con (energy_net usa state_class: total porque puede disminuir; reactive_energy* están en varh):

YAML
device_class: energy
state_class: total_increasing
unit_of_measurement: Wh

Es exactamente la combinación que espera el panel de energía de HA para sensores de consumo o generación acumulados. No hacen falta sensores template adicionales. Cada sensor de energía necesita voltage y current declarados en el mismo bloque sensor: (añada internal: true para ocultarlos de Home Assistant).

Añadir sensores al panel de energía

Ajustes → Paneles → Energía [Settings → Dashboards → Energy]. El panel tiene cuatro secciones:

Sección Qué sensor de rbAmp usar
Consumo de red energy (importación desde la red) o energy_total (STANDARD (STD), todos los canales)
Vuelta a la red Necesita un módulo STANDARD (STD): un módulo BASIC siempre lee 0 de exportación. energy_exported necesita bidirectional: true más voltage y current en el mismo bloque; energy_exported_total cubre todos los canales (solo STANDARD (STD))
Paneles solares energy de un módulo que mide la salida del inversor solar (módulo STANDARD (STD) si el mismo módulo también debe informar de la exportación)
Batería doméstica No aplicable (rbAmp no mide CC)
Dispositivos individuales energy_1, energy_2, etc. de un módulo multicanal

Para una instalación única de vivienda completa:

  1. Haga clic en "Add consumption" [Añadir consumo] en Grid consumption [Consumo de red].
  2. Seleccione la entidad Mains Energy.
  3. Opcionalmente, fije una tarifa (EUR/kWh o la moneda local) para el seguimiento de costes.

Para una instalación de tres módulos (red + solar + VE del Ejemplo 11 de 06_examples.md):

  1. Consumo de red: House Energy (de meter_house).
  2. Retorno a la red: Solar Energy Exported (de meter_solar, STANDARD (STD); déjelo vacío en BASIC).
  3. Paneles solares: Solar Energy (desde meter_solar).
  4. Dispositivo individual: EV Charger Energy (de meter_evcharger).

Persistencia NVS y panel de energía

El componente de ESPHome guarda la energía total en la NVS del ESP32 cada 5 minutos (y en un apagado limpio, como un reinicio o una OTA). En un módulo STANDARD los totales proceden de los contadores de energía propios del módulo, de modo que también sobreviven a los reinicios del módulo y se mantienen monótonos. Al arrancar, los valores se restauran desde la NVS y se publican de inmediato, antes de que HA se conecte y antes de que se dispare el primer update_interval.

Esto evita que el panel de energía interprete un 0 Wh momentáneo como un reinicio del contador. Si HA ve que un valor total_increasing cae a 0, interpreta la diferencia como un límite de período de facturación y descarta el historial acumulado.

La pérdida de datos en el peor caso ante un corte de alimentación repentino es de hasta 5 minutos de acumulación (≈5 Wh con una carga media de 60 W, invisible en los totales diarios).

last_reset tras una OTA o un reinicio del ESP32

El panel de energía de HA usa device_class: energy + state_class: total_increasing sin vinculación explícita de last_reset; es la configuración de ESPHome recomendada. Al reiniciarse el ESP32, el componente restaura el valor desde NVS antes del primer publish_state, de modo que HA ve una serie continua y monótonamente creciente y no inserta un reinicio centinela en la gráfica. Esto funciona por diseño.

Casos límite en los que puede ver un «reinicio» visible:

  • La NVS está corrupta (la cabecera no coincide o falla el CRC). El componente arranca en 0 Wh y HA registra una discontinuidad. Síntoma: el panel muestra un «pico de la mañana» en el momento en que el nodo arranca tras un periodo largo inactivo. Solución: revise en el registro de arranque del ESP32 los mensajes [E][rbamp_nvs]; indican la causa (un diseño NVS incompatible, poca carga en el momento de la escritura, etc.). Restaure desde una copia de seguridad del historial de HA o elimine el pico fantasma con las utilidades de HA.

  • Sustitución de hardware (ESP32 nuevo, mismo módulo). El componente empieza en 0 Wh: el módulo no transfiere su recuento acumulado por I²C (el módulo y el componente mantienen acumuladores separados; el módulo solo proporciona valores instantáneos para integrar). HA registra una discontinuidad. Solución: tras grabar el ESP32 nuevo, siembre el valor inicial de energía con un mqtt.publish manual (para MQTT) o con una edición temporal del YAML con una inicialización lambda. O acepte la discontinuidad como un evento puntual.

  • update_interval: cambiado entre versiones de firmware en una cantidad apreciable (por ejemplo, de 60 a 600 s). El cambio por sí mismo no reinicia nada, pero los ciclos más largos producen «escalones» más gruesos en la gráfica. Visualmente parece un cambio de modo de acumulación; funcionalmente es correcto.

  • El registrador de HA se truncó o se restauró desde una copia de seguridad antigua. Esto no está en el lado de ESPHome, sino en el de HA: HA puede tratar algunos valores futuros como «pasados» y redibujar la gráfica. No tiene que ver con ESPHome.

Durante una recarga OTA de rutina, last_reset no se activa, la instantánea NVS se restaura unos 50 ms antes de que HA se conecte y el panel de energía no ve ninguna discontinuidad. Este es el escenario de referencia.


5 · Contador de servicio

La integración utility_meter de HA deriva sensores de reinicio periódico a partir de cualquier sensor total_increasing. Úsela para obtener kWh diarios, semanales y mensuales además del acumulador en bruto.

YAML de Home Assistant (no ESPHome): va en la configuración de Home Assistant, no en el YAML del nodo.

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

HA crea tres entidades nuevas (sensor.energy_daily, etc.) que se ponen a 0 al inicio de cada periodo. Son muy útiles para vistas de dispositivo individual en el panel de energía y como base de los sensores template de seguimiento de costes.

Hay ejemplos de coste y de kWh/día en 06_examples.md §10.


6 · Sensor de estadísticas para mín / máx / media

El sensor statistics de HA calcula el mínimo, máximo, media y desviación estándar móviles en una ventana de tiempo configurable a partir del historial de cualquier sensor:

YAML de Home Assistant (no ESPHome): va en la configuración de Home Assistant, no en el YAML del nodo.

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

Estos sensores derivados sirven para la gestión de la demanda (ventana de consumo máximo, máximo mensual para la facturación por tarifa) y la detección de anomalías (si el máximo de potencia de 24 horas supera de pronto los valores históricos).


7 · Estadísticas a largo plazo

HA escribe los sensores con state_class: total_increasing y state_class: measurement en su base de datos de estadísticas a largo plazo (LTS). Los datos de LTS se conservan indefinidamente (independientemente de la retención del registrador de corto plazo).

Para comprobar que un sensor de rbAmp llega a LTS:

  1. Herramientas para desarrolladores → Estadísticas (Developer Tools → Statistics).
  2. Localice la entidad (por ejemplo sensor.rbamp_ui1_mains_energy).
  3. Compruebe que su fila tiene un statistic_id y un last_stats_ts reciente.

El LTS lo usa el panel de energía para las vistas históricas, y se exporta mediante «Download statistics» de HA.

Al sustituir un módulo rbAmp (hardware nuevo, nuevo entity ID), el historial LTS antiguo no se migra automáticamente. Para conservarlo, mantenga el mismo name: para cada sensor en el YAML nuevo: ESPHome genera el entity ID a partir del nombre del nodo y del nombre del sensor; los nombres coincidentes dan el mismo statistic_id.


8 · Tarjetas Lovelace

Tarjeta de flujo de energía (integrada)

El panel de energía integrado de HA ya incluye una tarjeta de flujo de energía en la parte superior de la página de ajustes de Energía. Se dibuja una vez configurado el panel de energía (consumo de red, solar, batería). No hace falta ninguna configuración adicional.

Medidor

YAML de Home Assistant (no ESPHome): va en la configuración de Home Assistant, no en el YAML del nodo.

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

Tarjeta de lista de sensores

YAML de Home Assistant (no ESPHome): va en la configuración de Home Assistant, no en el YAML del nodo.

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)

Tarjeta de minigráfico (HACS)

Instalado mediante HACS (§11):

YAML de Home Assistant (no ESPHome): va en la configuración de Home Assistant, no en el YAML del nodo.

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 de Home Assistant (no ESPHome): va en la configuración de Home Assistant, no en el YAML del nodo.

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 · Automatizaciones de HA frente a on_value de ESPHome

Tanto las automatizaciones de HA como los callbacks on_value de ESPHome reaccionan a los cambios de los sensores de rbAmp. Cómo elegir la herramienta:

Escenario Automatización de HA on_value de ESPHome
Notificación push Sí — acceso a todos los servicios de HA (notify, TTS, etc.) No — el ESP32 no tiene servicio de notificaciones
Accionar un relé en el mismo ESP32 Posible (HA → interruptor), pero añade latencia Sí: funciona en el propio dispositivo, sin dependencia de la red
Disparo cuando HA está fuera de línea No Sí: el ESP32 actúa de forma autónoma
Condiciones complejas (combinando entidades, historial, calendario) Sí Limitado — Lambda en C++, sin acceso al estado de HA
Latencia de reacción ~1–5 s (ida y vuelta WiFi + API) ~0 ms (el mismo bucle de eventos)
Reaccionar a una publicación MQTT Sí (disparador MQTT) N/A

Consejo práctico: use on_value de ESPHome para acciones locales de baja latencia (activar un relé, un indicador LED, un zumbador) y las automatizaciones de HA para lo que necesite servicios de HA (notificaciones, activación de escenas, programación de calendario, combinaciones con otras entidades).

Ejemplo de automatización en HA que combina rbAmp y un interruptor de HA:

YAML de Home Assistant (no ESPHome): va en la configuración de Home Assistant, no en el YAML del nodo.

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 y Docker

HA suele ejecutarse en Docker (con la imagen homeassistant/home-assistant o con Home Assistant OS en una VM). ESPHome se ejecuta como complemento de HA (en el mismo entorno de contenedores) o como contenedor Docker independiente.

mDNS en Docker / WSL

mDNS (UDP multidifusión 5353) no atraviesa las fronteras de red de Docker por defecto. Si HA está en Docker y el ESP32 está en la LAN física:

  • Red host de Docker (--network host en Linux) da al contenedor acceso a multidifusión y normalmente resuelve el problema.
  • Reflector mDNS: herramientas como avahi-daemon con un allow-interfaces correcto o mdns-repeater hacen de puente de multidifusión entre el puente Docker (docker0) y la interfaz LAN física.
  • Alta manual: omita mDNS por completo: añada el ESP32 a la integración ESPHome de HA manualmente por IP.

En Windows con WSL2, la VM de WSL2 tiene su propio adaptador de red virtual. Los contenedores Docker dentro de ella pueden estar detrás de dos capas de NAT (Windows → WSL2 → puente Docker). Es casi seguro que mDNS no funcione: añada por IP.

Complemento ESPHome de Add-on frente a ESPHome independiente

Al usar el complemento ESPHome de HA, el contenedor del complemento comparte el espacio de nombres de red con HA (suponiendo red host, que es la predeterminada para HA OS). mDNS y el descubrimiento de dispositivos funcionan sin configuración adicional.

Si ejecuta ESPHome como contenedor Docker independiente, asegúrese de que el contenedor tenga acceso a la LAN física (--network host en Linux) y de que /dev/ttyUSB0 (o su puerto COM) esté disponible para la grabación 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ática para una OTA fiable

En un entorno Docker / VLAN se recomiendan encarecidamente concesiones DHCP estáticas para los ESP32 de rbAmp. Evitan que:

  • Una dirección IP obsoleta registrada en HA para la entrada de la integración ESPHome.
  • Un fallo de la carga OTA (esphome upload --device 192.168.x.y).
  • Un fallo de cualquier automatización que use la API por IP.

11 · HACS (Home Assistant Community Store)

HACS es un gestor de integraciones de terceros para HA que da acceso a tarjetas, integraciones y automatizaciones desarrolladas por la comunidad. No es necesario para el funcionamiento básico de rbAmp, pero es útil para las tarjetas Lovelace más completas del §8.

Instálelo desde https://hacs.xyz/. Después instale estas tarjetas de la comunidad:

Tarjeta Categoría HACS Uso con rbAmp
mini-graph-card Interfaz Gráfica de potencia / corriente a lo largo del tiempo
apexcharts-card Interfaz Gráficas de varias series
lovelace-card-mod Interfaz CSS personalizado en cualquier tarjeta
energy-flow-card-plus Interfaz Diagrama de flujo de energía mejorado

La instalación y gestión de HACS está cubierta en su documentación. Las tarjetas se documentan en sus respectivos repositorios de GitHub.


12 · Notificaciones push por umbral

La aplicación móvil de HA (home-assistant.io/integrations/mobile_app) ofrece notificaciones push en iOS y Android. Combinada con los sensores de rbAmp, recibe alertas inmediatas por sobrecorriente, sobrepotencia, pérdida de red o cualquier otro umbral:

YAML de Home Assistant (no ESPHome): va en la configuración de Home Assistant, no en el YAML del nodo.

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 el servicio notify.mobile_app_* esté disponible, la aplicación HA Companion debe estar instalada en el dispositivo de destino y la integración mobile-app configurada en HA. Los detalles están en https://companion.home-assistant.io/.


13 · Configuración del complemento ESPHome de HA

Cuando usa el complemento ESPHome de HA (recomendado para la mayoría de usuarios):

  1. El complemento guarda las configuraciones YAML en /config/esphome/ (accesible mediante el sistema de archivos de HA o el editor del complemento).
  2. secrets.yaml está junto a los archivos YAML del dispositivo, en /config/esphome/.
  3. Elexternal_componentsla ruta debe ser accesible desde dentro del contenedor del complemento. Opciones:
    • Recomendado: use la forma remota: source: github://rb-amp/rbamp-esphome@v1.9.0 (el componente se publica en GitHub).
    • Alternativamente, copie el directorio components/rbamp/ en /config/esphome/components/ y especifique path: components/ (relativo).
  4. OTA: el complemento realiza él mismo la carga OTA: haga clic en «Install» en la tarjeta del dispositivo y el complemento intenta una OTA a la última IP conocida. La carga por USB también está disponible mediante el puerto serie del complemento si el ESP32 está conectado al host de HA.

El complemento incluye un visor de logs integrado (el botón «Logs» de la tarjeta del dispositivo): el equivalente de esphome logs en la CLI.


14 · Nombres de entidad y estabilidad del entity ID

Los ID de entidad en HA se derivan del nombre del nodo ESPHome y del campo name: del sensor:

Text
sensor._

Para el nodo rbamp-ui1 y un sensor con name: "Mains Voltage":

Text
sensor.rbamp_ui1_mains_voltage

Los ID de entidad aparecen en las automatizaciones, los sensores de plantilla, los paneles Lovelace y la configuración del panel de energía. Cambiar el name: de un sensor en el YAML crea un ID de entidad nuevo y rompe todas las referencias al antiguo. Planifique los nombres de sus sensores antes del primer despliegue.

Para cambiar el nombre de un sensor sin romper el ID de entidad:

  1. Renombre el sensor en el YAML.
  2. Vuelva a grabar el dispositivo.
  3. En HA: Ajustes → Dispositivos y servicios → ESPHome → su dispositivo → pulse la entidad del sensor → pulse el icono de engranaje → renombre el ID de la entidad al valor anterior (o cámbielo a uno nuevo y actualice todas las referencias) [Settings → Devices & Services → ESPHome].

Una alternativa es la función de HA «Entity ID rename» (Ajustes → Entidades → buscar → hacer clic en la entidad → editar nombre / entity ID): permite separar el nombre mostrado del entity ID. Puede renombrar libremente el nombre mostrado sin afectar a las automatizaciones.


Fuente y incidencias: rb-amp/rbamp-esphome · esta página en el repositorio: docs/08_has_integrations.md (v1.9.1)