rbAmp
ES
Tienda
Docs
Actualizado · Editar en GitHub

07 · Integraciones DIY

Este capítulo trata de usar rbAmp más allá del panel de energía estándar de HA: exportación a bases de datos de series temporales externas, publicación por MQTT sin HA, control de carga en lazo cerrado y lectura de rbAmp desde maestros que no son ESPHome.

Cross-references:


1 · InfluxDB y Grafana mediante Home Assistant

La vía más sencilla hacia InfluxDB + Grafana no requiere cambios en el YAML. Home Assistant exporta todos los estados de entidades a InfluxDB mediante su integración nativa:

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

YAML
# configuration.yaml in HA
influxdb:
  host: 192.168.0.100    # your InfluxDB host
  port: 8086
  database: homeassistant
  default_measurement: state
  include:
    entities:
      - sensor.rbamp_ui1_mains_voltage
      - sensor.rbamp_ui1_mains_current
      - sensor.rbamp_ui1_mains_power
      - sensor.rbamp_ui1_mains_energy
      - sensor.rbamp_ui1_mains_power_factor
      - sensor.rbamp_ui1_mains_frequency

Cada publicación de sensor de rbAmp (una vez por update_interval) se convierte en un punto de InfluxDB. Grafana consulta entonces InfluxDB y construye los paneles.

Un panel de Grafana mínimo para la potencia en directo:

Text
SELECT mean("value") FROM "state"
WHERE "entity_id" = 'sensor.rbamp_ui1_mains_power'
AND $timeFilter
GROUP BY time(1m)

Para InfluxDB 2.x (Flux):

Text
from(bucket: "homeassistant")
  |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
  |> filter(fn: (r) => r["entity_id"] == "sensor.rbamp_ui1_mains_power")
  |> aggregateWindow(every: 1m, fn: mean, createEmpty: false)

InfluxDB de alta resolución (sin pasar por HA)

La máquina de estados de HA solo registra cambios de estado. Para una serie densa con un punto cada 60 s (el update_interval predeterminado), HA basta. Si necesita resolución inferior al minuto, baje el update_interval y deje que el recorder de HA y la integración de InfluxDB capturen a esa frecuencia:

YAML
rbamp:
  id: meter1
  update_interval: 10s     # 10-second resolution — ×6 I²C traffic, acceptable

2 · Publicación MQTT directa (sin HA)

ESPHome tiene un componente mqtt: integrado que publica todos los estados de los sensores en un broker. Los sensores de rbAmp se publican en cada update_interval, igual que cualquier otro.

YAML
esphome:
  name: rbamp-mqtt

esp32:
  board: esp32dev
  framework:
    type: arduino

logger:
  level: INFO

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

# NOTE: use mqtt: OR api: — not both at the same time, unless you
# specifically need both the HA native API and MQTT in parallel
# (supported, but non-standard).
mqtt:
  broker: 192.168.0.200      # IP of your MQTT broker
  port: 1883
  username: !secret mqtt_user
  password: !secret mqtt_pass
  topic_prefix: rbamp/ui1    # all sensor topics under this prefix
  birth_message:
    topic: rbamp/ui1/status
    payload: online
  will_message:
    topic: rbamp/ui1/status
    payload: offline

i2c:
  sda: GPIO21
  scl: GPIO22
  frequency: 50kHz
  scan: true

external_components:
  - source:
      type: local
      path: ../components
    components: [rbamp]

rbamp:
  id: meter1
  address: 0x50
  update_interval: 60s
  ct_model: SCT_013_030

sensor:
  - platform: rbamp
    rbamp_id: meter1
    voltage:
      name: "Mains Voltage"
    current:
      name: "Mains Current"
    power:
      name: "Mains Power"
    energy:
      name: "Mains Energy"
    frequency:
      name: "Mains Frequency"
    power_factor:
      name: "Mains Power Factor"

Con topic_prefix: rbamp/ui1, ESPHome publica:

Tema MQTT Carga útil
rbamp/ui1/sensor/mains_voltage/state 226.70
rbamp/ui1/sensor/mains_current/state 0.755
rbamp/ui1/sensor/mains_power/state 92.80
rbamp/ui1/sensor/mains_energy/state 1024.341
rbamp/ui1/sensor/mains_frequency/state 50
rbamp/ui1/sensor/mains_power_factor/state 0.542
rbamp/ui1/status online / offline

Cualquier suscriptor MQTT — Node-RED, InfluxDB Telegraf, OpenHAB, un script Python propio — puede consumir estos temas directamente.

Mensajes MQTT retenidos

Añada retain: true a cada sensor si los suscriptores que se conectan después de una publicación deben ver de inmediato el último valor:

Supone que ya tiene un bloque mqtt: en el YAML del nodo.

YAML
sensor:
  - platform: rbamp
    rbamp_id: meter1
    voltage:
      name: "Mains Voltage"
      # ESPHome MQTT does not set retain on sensor state by default. For retain,
      # use a manual publish action:
      on_value:
        - mqtt.publish:
            topic: "rbamp/ui1/voltage"
            payload: !lambda 'return to_string(x);'
            retain: true

Retención MQTT y OTA — lo que debe saber

Los mensajes retenidos sobreviven a un reinicio del ESP32 (ese es su propósito principal). Esto crea dos escenarios que conviene conocer de antemano:

  1. Actualización OTA de un nodo. Tras grabar, el ESP32 se reinicia. Los valores retenidos antiguos permanecen en el broker y siguen visibles para los suscriptores durante ~5..30 segundos (hasta que el nodo se reconecta y publica otros nuevos). Si el nodo no vuelve (firmware corrupto, fallo fatal al arrancar), los valores retenidos antiguos se mostrarán indefinidamente. Esto oculta el estado sin conexión a los paneles que leen solo state sin status.

Mitigación: defina siempre un will_message: (LWT) en el tema status (como en el ejemplo de arriba). El broker publicará la carga offline cuando se caiga la conexión; los suscriptores pueden vigilar status para detectar nodos colgados. Los temas de sensor seguirán conteniendo los valores antiguos en este caso: es normal, pero los suscriptores saben que los datos están obsoletos.

  1. Cambiar topic_prefix: entre compilaciones de firmware. Si renombra topic_prefix: (por ejemplo rbamp/ui1 → rbamp/kitchen) y actualiza el nodo por OTA, los mensajes retenidos bajo el prefijo antiguo permanecen para siempre en el broker. Los suscriptores que no conocen el cambio siguen viendo datos obsoletos de esos temas zombi.

Mitigación: antes de una OTA con un prefijo renombrado, borre los mensajes retenidos antiguos publicando una carga vacía con retain: true en cada tema antiguo (CLI: mosquitto_pub -h -t '' -r -n). Sin esto, los zombis permanecen hasta que alguien los borre a mano.

  1. Mensaje de nacimiento y start_session: true para reconectar tras un reinicio del broker: consulte la documentación del bloque mqtt: de ESPHome para las opciones clean_session: y keepalive:. Estos parámetros controlan cómo gestiona el broker los mensajes QoS 1/2 pendientes al desconectarse.

3 · Acciones lambda de ESPHome

El callback on_value de ESPHome se dispara con cada nueva lectura del sensor. Puede usarlo para acciones de umbral ejecutadas íntegramente en el ESP32, sin pasar por HA.

Alarma de umbral de corriente

Supone que ya tiene una entrada switch: con el id usado abajo.

YAML
sensor:
  - platform: rbamp
    rbamp_id: meter1
    current:
      name: "Mains Current"
      on_value:
        then:
          - if:
              condition:
                lambda: 'return x > 15.0f;'    # over-current threshold 15 A
              then:
                - logger.log:
                    level: WARN
                    format: "Over-current: %.2f A — triggering alarm relay"
                    args: [x]
                - switch.turn_on: alarm_relay

Detección de un escalón de carga (lambda personalizado)

YAML
# Detecting a sharp increase in load (e.g. a compressor start)
globals:
  - id: prev_power
    type: float
    initial_value: '0.0'

sensor:
  - platform: rbamp
    rbamp_id: meter1
    voltage:                  # power needs voltage AND current in the same block
      name: "Mains Voltage"
      internal: true
    current:
      name: "Mains Current"
      internal: true
    power:
      name: "Mains Power"
      on_value:
        then:
          - lambda: |-
              float delta = x - id(prev_power);
              if (delta > 500.0f) {
                ESP_LOGI("rbamp", "Large load step detected: +%.0f W", delta);
              }
              id(prev_power) = x;

Publicación en un tema MQTT personalizado al superar un umbral

Supone que ya tiene un bloque mqtt: en el YAML del nodo.

YAML
sensor:
  - platform: rbamp
    rbamp_id: meter1
    voltage:                  # power needs voltage AND current in the same block
      name: "Mains Voltage"
      internal: true
    current:
      name: "Mains Current"
      internal: true
    power:
      name: "Mains Power"
      on_value:
        - if:
            condition:
              lambda: 'return x > 2500.0f;'
            then:
              - mqtt.publish:
                  topic: "alerts/high_power"
                  payload: !lambda >
                    return "HIGH_POWER:" + to_string((int)x) + "W";

4 · Control en lazo cerrado — PID de calentador de agua

Un caso de uso típico de medición doméstica con rbAmp es el autoconsumo solar: calentar agua con el excedente solar en lugar de exportarlo a la red.

El patrón usa dos módulos rbAmp: uno en la acometida de red (importación / exportación) y otro en el circuito del calentador de agua. Un relé PWM o un SSR en el calentador permite un control de potencia variable.

YAML
# Conceptual sketch — the concrete PID implementation depends on your
# relay / SSR and load. The PID controller component in ESPHome is the
# recommended building block.

globals:
  - id: solar_export_w
    type: float
    initial_value: '0.0'
  - id: heater_setpoint_w
    type: float
    initial_value: '0.0'

rbamp:
  - id: meter_grid
    address: 0x50
    update_interval: 10s     # tighter loop for responsive control

  - id: meter_heater
    address: 0x51
    update_interval: 10s

sensor:
  - platform: rbamp
    rbamp_id: meter_grid
    voltage: { name: "Grid Voltage", internal: true }   # power needs voltage AND current
    current: { name: "Grid Current", internal: true }
    power:
      name: "Grid Power"
      # Positive = import, negative = export (STANDARD (STD) with correct wiring)
      on_value:
        - lambda: |-
            // If grid power is negative, that is export (solar surplus).
            // Raise the heater setpoint to absorb the surplus.
            float export_w = -x;
            if (export_w > 100.0f) {
              float sp = std::min(export_w, 2000.0f);
              id(heater_setpoint_w) = sp;
            } else {
              id(heater_setpoint_w) = 0.0f;
            }

output:
  - platform: ledc          # PWM output to an SSR or 0-10V controller
    pin: GPIO5
    id: heater_pwm
    frequency: 100Hz

interval:
  - interval: 10s
    then:
      - lambda: |-
          // Drive PWM proportionally to the setpoint (0–2000 W → 0–100% duty)
          float duty = id(heater_setpoint_w) / 2000.0f;
          id(heater_pwm).set_level(duty);
Nota

: potencia bidireccional (valores negativos = exportación) requiere un módulo STANDARD (STD) con la polaridad de tensión cableada correctamente. En BASIC, el firmware fija la potencia activa media del período a P ≥ 0: la P instantánea sigue leyéndose negativa en el momento de la generación, pero el acumulador de período de exportación queda vacío. El comportamiento por nivel está en 02_tiers.md, el cableado de polaridad en 04_hardware.md.


5 · Encadenar callbacks a través de la API de ESPHome

La API nativa de ESPHome (puerto 6053) puede usarse para activar scripts Python externos mediante la API WebSocket sin un HA en ejecución continua.

La biblioteca Python aioesphomeapi (pip install aioesphomeapi) da acceso asíncrono directo a los estados de las entidades:

Python
import asyncio
from aioesphomeapi import APIClient

async def main():
    cli = APIClient("rbamp-ui1.local", 6053, "")
    await cli.connect(login=True)

    def on_state(state):
        # Called on every sensor publication
        print(f"State: {state}")

    await cli.subscribe_states(on_state)
    await asyncio.Event().wait()  # runs forever

asyncio.run(main())

El patrón es útil para:

  • Introducir las lecturas de rbAmp en un bucle de control propio que no encaja en el modelo de lambda YAML de ESPHome.
  • Registro en un formato personalizado o en una base de datos.
  • Lógica de umbrales en Python, cuando los 512 KB de RAM del ESP32 son un límite para cálculos complejos.

El cliente de la API se ejecuta en cualquier host con Python 3.8+ de la misma red: una Raspberry Pi, un contenedor Docker, un portátil de desarrollo.


6 · Potencia aparente: cálculo en el cliente

Cuando apparent_power se declara en el bloque sensor:, el componente calcula S = U_rms × I_rms[ch0] en el ESP32 a partir de dos lecturas recientes. Si necesita la potencia aparente de varios canales (CH1, CH2), o quiere derivarla de entidades de HA en lugar del propio componente, use un sensor template en HA:

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

YAML
# configuration.yaml in HA
template:
  - sensor:
      - name: "CH1 Apparent Power"
        unit_of_measurement: "VA"
        device_class: apparent_power
        state_class: measurement
        state: >
          {% set u = states('sensor.rbamp_ui3_mains_voltage') | float(0) %}
          {% set i = states('sensor.rbamp_ui3_ch1_current') | float(0) %}
          {{ (u * i) | round(1) }}

      - name: "CH2 Apparent Power"
        unit_of_measurement: "VA"
        device_class: apparent_power
        state_class: measurement
        state: >
          {% set u = states('sensor.rbamp_ui3_mains_voltage') | float(0) %}
          {% set i = states('sensor.rbamp_ui3_ch2_current') | float(0) %}
          {{ (u * i) | round(1) }}

Nota: apparent_power en el esquema de ESPHome usa solo la corriente del CH0. La plantilla anterior es el enfoque recomendado para CH1/CH2 en despliegues UI2/UI3.


7 · Leer rbAmp sin ESPHome

El módulo rbAmp es un esclavo I²C corriente. Cualquier maestro I²C puede leerlo usando el protocolo de la referencia de la API del módulo. Las bibliotecas cliente hermanas (repositorios de distribución — marcadores de posición hasta su publicación):

Biblioteca Distribución Idioma Plataforma de destino
Arduino rbamp-arduino C++ ESP32 (framework Arduino), AVR, RP2040
ESP-IDF rbamp-esp-idf C ESP32 (framework IDF)
Python (CPython + MicroPython) rbamp-python Python 3 Raspberry Pi, SBC con Linux, PC, ESP32/RP2040/STM32 con MicroPython

Todas las bibliotecas implementan el mismo mapa de registros y el mismo protocolo de medición por período que el componente de ESPHome. Pueden usarse de forma independiente o en paralelo.

Cuándo NO usar ESPHome

  • Ya tiene firmware de ESP32 que no es ESPHome y necesita añadir lecturas de rbAmp: use la biblioteca ESP-IDF y llame a la API directamente.
  • El maestro es una Raspberry Pi u otro SBC Linux: use la biblioteca Python.
  • Tiene un PLC STM32 o una placa propia: STM32 HAL.
  • Un prototipo rápido en un Arduino UNO o Leonardo: la biblioteca de Arduino.

Acumulación de energía multiplataforma: una nota

El componente de ESPHome usa acumuladores double persistidos en NVS que sobreviven a un reinicio (en los módulos STANDARD además se alimentan de los contadores de energía propios del módulo). Las bibliotecas hermanas pueden usar otros mecanismos de persistencia: para los detalles y la compatibilidad futura de una biblioteca concreta, véase su 10_troubleshooting.md (sección de persistencia de energía). Si migra de ESPHome a firmware bare-metal, planifique la migración de datos: exporte el último valor de Wh desde HA antes del cambio y siembre con él el acumulador del nuevo firmware.


8 · Puentes Tasmota / WLED / OpenHAB

Tasmota

Tasmota no tiene un driver nativo de rbAmp. El puente más limpio es usar ESPHome como lector de rbAmp y Tasmota como maestro I²C independiente para otros dispositivos, sin mezclarlos.

Si necesita Tasmota específicamente para rbAmp, use scripting Berry (Tasmota 12.x+) para escribir un controlador personalizado que realice las lecturas I²C: un byte por fase de dirección en las escrituras y, opcionalmente, lectura en ráfaga para el bloque de valores instantáneos (véase 09 · Referencia de la API). La biblioteca MicroPython de rbamp-python es una referencia útil para las direcciones de registro y la decodificación de floats.

WLED

WLED (firmware para controladores de LED) no expone un maestro I²C en scripts de usuario. rbAmp y WLED solo pueden ser dispositivos independientes en el mismo bus si están en segmentos de bus separados o tienen direcciones no conflictivas. No existe un puente oficial.

OpenHAB

ESPHome publica datos por MQTT (vea el Ejemplo 2) o mediante la API nativa (aioesphomeapi). El binding MQTT de OpenHAB puede suscribirse a los temas de ESPHome y llevar las lecturas de rbAmp a las reglas e Items de OpenHAB. La configuración del binding MQTT está cubierta en la documentación de OpenHAB.


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