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:
- Esquema YAML:
09_api_reference.md - Detalles de HA:
08_has_integrations.md - Biblioteca cliente Arduino:
rbamp-arduino - Biblioteca cliente ESP-IDF:
rbamp-esp-idf - Python (CPython + MicroPython):
rbamp-python
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.
# 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:
SELECT mean("value") FROM "state"
WHERE "entity_id" = 'sensor.rbamp_ui1_mains_power'
AND $timeFilter
GROUP BY time(1m)
Para InfluxDB 2.x (Flux):
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:
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.
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.
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:
- 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
statesinstatus.
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.
- Cambiar
topic_prefix:entre compilaciones de firmware. Si renombratopic_prefix:(por ejemplorbamp/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 ). Sin esto, los zombis permanecen hasta que alguien los borre a mano.
- Mensaje de nacimiento y
start_session: truepara reconectar tras un reinicio del broker: consulte la documentación del bloquemqtt:de ESPHome para las opcionesclean_session:ykeepalive:. 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.
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)
# 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.
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.
# 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);
: 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:
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.
# 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)