07 · Integraciones DIY
Cómo alimentar las lecturas de rbamp a sistemas de automatización autoalojados populares. Para cada plataforma hay un proyecto ESP-IDF mínimo funcional y la configuración correspondiente en el lado de la plataforma.
Integraciones en la nube / comerciales (AWS IoT, Azure, GCP, InfluxDB Cloud) — 08 · Integraciones en la nube.
| Plataforma | Transporte | Autodescubrimiento | Componentes de IDF |
|---|---|---|---|
| Home Assistant | MQTT | sí (HA MQTT Discovery) | espressif/esp_mqtt_client |
| ESPHome | API nativa + MQTT | sí (configuración YAML) | (marco alternativo — véase más abajo) |
| Node-RED | MQTT (o HTTP) | flujo manual | espressif/esp_mqtt_client |
| OpenHAB | MQTT (o REST) | .things manual |
espressif/esp_mqtt_client |
| Domoticz | MQTT (automático) o HTTP | sí (plugin MQTT) | esp_mqtt_client o esp_http_client |
| InfluxDB OSS + Grafana | Protocolo de línea HTTPS | no | esp_http_client |
Los proyectos listos para los dos escenarios principales están en examples/: examples/mqtt_publisher/ (publicador MQTT por canal) y examples/ha_discovery/ (autodescubrimiento de HA sobre mqtt_publisher).
Home Assistant: descubrimiento automático por MQTT
HA MQTT Discovery crea automáticamente el dispositivo y sus sensores cuando el ESP32 publica los temas de configuración. No hacen falta ediciones YAML en HA.
Proyecto ESP-IDF (rbamp + WiFi STA + esp_mqtt_client)
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/i2c_master.h"
#include "esp_event.h"
#include "esp_log.h"
#include "esp_wifi.h"
#include "mqtt_client.h"
#include "nvs_flash.h"
#include "rbamp.h"
#define DEVICE_ID "rbamp_main"
#define DEVICE_NAME "Mains rbAmp"
#define MQTT_URI "mqtt://192.168.1.10:1883"
static const char *TAG = "ha_discovery";
static esp_mqtt_client_handle_t mqtt;
static void publish_discovery_sensor(const char *key, const char *friendly,
const char *unit, const char *device_class,
const char *state_class) {
char topic[128], payload[512];
snprintf(topic, sizeof(topic),
"homeassistant/sensor/%s/%s/config", DEVICE_ID, key);
int n = snprintf(payload, sizeof(payload),
"{"
"\"name\":\"%s %s\","
"\"unique_id\":\"%s_%s\","
"\"state_topic\":\"rbamp/%s/state\","
"\"value_template\":\"{{ value_json.%s }}\","
"\"state_class\":\"%s\","
"\"device\":{"
"\"identifiers\":[\"%s\"],"
"\"name\":\"%s\","
"\"manufacturer\":\"rbAmp\","
"\"model\":\"UI*\""
"}",
DEVICE_NAME, friendly,
DEVICE_ID, key,
DEVICE_ID, key, state_class,
DEVICE_ID, DEVICE_NAME);
if (unit) n += snprintf(payload+n, sizeof(payload)-n,
",\"unit_of_measurement\":\"%s\"", unit);
if (device_class) n += snprintf(payload+n, sizeof(payload)-n,
",\"device_class\":\"%s\"", device_class);
snprintf(payload+n, sizeof(payload)-n, "}");
esp_mqtt_client_publish(mqtt, topic, payload, 0, /*qos*/1, /*retain*/1);
}
static void publish_discovery_all(void) {
publish_discovery_sensor("voltage", "Voltage", "V", "voltage", "measurement");
publish_discovery_sensor("current", "Current", "A", "current", "measurement");
publish_discovery_sensor("power", "Power", "W", "power", "measurement");
publish_discovery_sensor("energy", "Energy", "Wh", "energy", "total_increasing");
publish_discovery_sensor("frequency", "Frequency", "Hz", "frequency", "measurement");
publish_discovery_sensor("power_factor", "Power Factor", NULL, "power_factor", "measurement");
}
static void mqtt_event_handler(void *handler_args, esp_event_base_t base,
int32_t event_id, void *event_data) {
if (event_id == MQTT_EVENT_CONNECTED) {
publish_discovery_all(); /* publish discovery on every connect */
}
}
void app_main(void) {
/* ...nvs_flash_init + esp_netif_init + esp_event_loop_create_default +
* esp_wifi_init/start + wait for IP_EVENT_STA_GOT_IP... */
/* (pattern from 10 · Troubleshooting, "Watchdog timeout during WiFi") */
/* I²C bus + rbAmp handle */
i2c_master_bus_handle_t bus = NULL;
/* ...i2c_new_master_bus(...)... */
rbamp_handle_t dev = NULL;
ESP_ERROR_CHECK(rbamp_new(bus, 0x50, &dev)); /* new — never fails
* with valid arguments */
/* rbamp_begin may return NACK / VERSION on bus chatter or a cold
* boot of the module. A soft retry is better than an ESP_ERROR_CHECK
* abort — in production the network stack must survive a temporary
* loss of the slave. */
while (rbamp_begin(dev) != ESP_OK) {
ESP_LOGE(TAG, "rbamp_begin: %s — retry in 1 s",
rbamp_err_to_str(rbamp_last_error(dev)));
vTaskDelay(pdMS_TO_TICKS(1000));
}
/* set_sensor_class + set_ct_model — both block ~700 ms
* (flash write). set_sensor_class is a mandatory prerequisite
* for set_ct_model. Log failures, but do not abort. */
esp_err_t err;
if ((err = rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013)) != ESP_OK) {
ESP_LOGE(TAG, "set_sensor_class: %s", rbamp_err_to_str(err));
}
if ((err = rbamp_set_ct_model(dev, 3)) != ESP_OK) {
ESP_LOGE(TAG, "set_ct_model: %s", rbamp_err_to_str(err));
}
/* MQTT client */
const esp_mqtt_client_config_t mqtt_cfg = {
.broker.address.uri = MQTT_URI,
.credentials.client_id = DEVICE_ID,
.session.keepalive = 60,
.buffer.size = 1024, /* room for one discovery payload */
};
mqtt = esp_mqtt_client_init(&mqtt_cfg);
esp_mqtt_client_register_event(mqtt, MQTT_EVENT_CONNECTED,
mqtt_event_handler, NULL);
esp_mqtt_client_start(mqtt);
/* State-publish loop — once a minute */
while (1) {
vTaskDelay(pdMS_TO_TICKS(60000));
rbamp_period_snapshot_t snap;
if (rbamp_read_period_snapshot(dev, &snap, 50, false) != ESP_OK ||
!snap.valid) continue;
float u, i, pf, freq;
rbamp_read_voltage(dev, 0, &u);
rbamp_read_current(dev, 0, &i);
rbamp_read_power_factor(dev, 0, &pf);
rbamp_read_frequency(dev, &freq);
char state[384];
snprintf(state, sizeof(state),
"{\"voltage\":%.1f,\"current\":%.3f,\"power\":%.1f,"
"\"energy\":%.3f,\"frequency\":%.1f,\"power_factor\":%.3f}",
(double)u, (double)i, (double)snap.avg_p[0],
rbamp_energy_wh(dev, 0), (double)freq, (double)pf);
char topic[64];
snprintf(topic, sizeof(topic), "rbamp/%s/state", DEVICE_ID);
esp_mqtt_client_publish(mqtt, topic, state, 0, /*qos*/0, /*retain*/0);
}
}
Proyecto completo: examples/ha_discovery/.
Resultado en HA
Unos segundos después de la primera publicación, HA crea automáticamente el dispositivo «Mains rbAmp» con 6 sensores (Tensión, Corriente, Potencia, Energía, Frecuencia, Factor de potencia). El sensor de Energía tiene state_class: total_increasing y el device_class correcto: el Panel de Energía de HA lo acepta como fuente de consumo.
Para eliminar más adelante el dispositivo de HA, publique una carga vacía en homeassistant/sensor/.../config (la marca retained borra la entrada).
UI3 multicanal
Repita las llamadas publish_discovery_sensor() con claves con sufijo para los canales 1 y 2:
publish_discovery_sensor("current_1", "Current 1", "A", "current", "measurement");
publish_discovery_sensor("power_1", "Power 1", "W", "power", "measurement");
publish_discovery_sensor("energy_1", "Energy 1", "Wh", "energy", "total_increasing");
/* ...same for _2 */
Y amplíe el JSON de estado con los campos "current_1", "power_1" y "energy_1", rellenados desde rbamp_read_current(dev, 1, &i) / snap.avg_p[1] / rbamp_energy_wh(dev, 1).
ESPHome: alternativa mediante external_components
Si usa ESPHome (en lugar de ESP-IDF directo), existe un componente externo rbamp dedicado que sustituye por completo a este componente y gestiona su propia integración con HA a través de la API nativa de ESPHome:
external_components:
- source: github://rb-amp/rbamp-esphome
components: [rbamp]
refresh: 0s
i2c:
sda: 21
scl: 22
frequency: 50kHz # see 10 · Troubleshooting on baseline mitigation
sensor:
- platform: rbamp
address: 0x50
update_interval: 60s
voltage:
name: "rbAmp Voltage"
current:
name: "rbAmp Current"
power:
name: "rbAmp Power"
energy:
name: "rbAmp Energy"
frequency:
name: "rbAmp Frequency"
power_factor:
name: "rbAmp Power Factor"
ESPHome se integra de forma nativa con HA mediante la API de ESPHome (no MQTT): el dispositivo aparece en HA automáticamente al grabarlo.
El componente rbamp-esphome está en un repositorio aparte: consulte el índice principal de rbAmp para los enlaces. Use ESPHome en lugar de este componente; mezclar ESPHome y ESP-IDF puro en el mismo proyecto normalmente no compensa.
Node-RED
Suscríbase al tema MQTT del ESP32 en un flujo:
[
{
"id": "rbamp_in",
"type": "mqtt in",
"topic": "rbamp/main/state",
"qos": "0",
"datatype": "json"
},
{
"id": "rbamp_chart",
"type": "ui_chart",
"label": "Mains Power",
"chartType": "line",
"ymin": "0",
"ymax": "5000"
},
{
"id": "extract_power",
"type": "function",
"func": "msg.payload = msg.payload.power; return msg;"
}
]
Conecte rbamp_in → extract_power → rbamp_chart y obtendrá un gráfico de potencia en tiempo real. Haga lo mismo para la energía, la tensión y el FP.
Si Node-RED se ejecuta en la misma Pi que el broker MQTT, use el host localhost. Para brokers remotos use 192.168.X.Y:1883 más credenciales si el broker exige autenticación.
El lado del ESP32 es el mismo boceto que en la sección de Home Assistant anterior; la carga JSON es común: solo cambia el consumidor.
OpenHAB
OpenHAB 4.x + binding MQTT:
# things/rbamp.things
Bridge mqtt:broker:local "MQTT Broker" [ host="192.168.1.10", port=1883 ] {
Thing topic rbamp_main "rbAmp Main" {
Channels:
Type number : voltage "Voltage" [ stateTopic="rbamp/main/state", transformationPattern="JSONPATH:$.voltage" ]
Type number : current "Current" [ stateTopic="rbamp/main/state", transformationPattern="JSONPATH:$.current" ]
Type number : power "Power" [ stateTopic="rbamp/main/state", transformationPattern="JSONPATH:$.power" ]
Type number : energy "Energy" [ stateTopic="rbamp/main/state", transformationPattern="JSONPATH:$.energy" ]
}
}
# items/rbamp.items
Number:ElectricPotential rbAmp_Voltage "Voltage [%.1f V]" { channel="mqtt:topic:local:rbamp_main:voltage" }
Number:ElectricCurrent rbAmp_Current "Current [%.3f A]" { channel="mqtt:topic:local:rbamp_main:current" }
Number:Power rbAmp_Power "Power [%.1f W]" { channel="mqtt:topic:local:rbamp_main:power" }
Number:Energy rbAmp_Energy "Energy [%.3f Wh]" { channel="mqtt:topic:local:rbamp_main:energy" }
El lado ESP32 es el mismo proyecto que en la sección de Home Assistant de más arriba. La carga JSON es compartida: solo cambia el consumidor.
Domoticz
El plugin de autodescubrimiento MQTT de Domoticz entiende los mismos temas de descubrimiento homeassistant/.... Habilite el plugin en la configuración de Domoticz y el proyecto ESP32 de la sección de HA anterior registrará automáticamente el dispositivo en Domoticz, igual que lo hace en HA.
Una alternativa es la API HTTP nativa de Domoticz mediante esp_http_client:
#include "esp_http_client.h"
#include "esp_log.h"
static const char *TAG = "domoticz";
static void publish_to_domoticz(int idx, float power, double e_wh) {
char url[256];
/* Energy in Wh, Power in W — Domoticz format: "POWER;ENERGY_WH" */
snprintf(url, sizeof(url),
"http://192.168.1.20:8080/json.htm?type=command¶m=udevice"
"&idx=%d&svalue=%.1f;%.0f", idx, (double)power, e_wh);
esp_http_client_config_t cfg = {
.url = url,
.method = HTTP_METHOD_GET,
.timeout_ms = 5000,
};
esp_http_client_handle_t client = esp_http_client_init(&cfg);
esp_err_t err = esp_http_client_perform(client);
int status = esp_http_client_get_status_code(client);
esp_http_client_cleanup(client);
if (err != ESP_OK || status != 200) {
ESP_LOGW(TAG, "domoticz HTTP %d (err %s)", status, esp_err_to_name(err));
}
}
/* In the 60-second loop: */
publish_to_domoticz(123 /* your idx */, snap.avg_p[0], rbamp_energy_wh(dev, 0));
Cree un dispositivo en la interfaz de Domoticz de tipo General → kWh (contador incremental), obtenga su idx e introdúzcalo en el proyecto.
InfluxDB OSS + Grafana
Escriba puntos en formato line-protocol en InfluxDB directamente desde el ESP32 mediante esp_http_client:
#include "esp_http_client.h"
#include "esp_log.h"
#define INFLUX_HOST "192.168.1.30:8086"
#define INFLUX_ORG "homelab"
#define INFLUX_BKT "energy"
#define INFLUX_TOKEN "your-token-here"
static const char *TAG = "influx";
static void push_influx(float u, float p, double e_wh) {
char url[256], body[256];
snprintf(url, sizeof(url),
"http://" INFLUX_HOST "/api/v2/write?org=%s&bucket=%s&precision=s",
INFLUX_ORG, INFLUX_BKT);
snprintf(body, sizeof(body),
"rbamp,device=main voltage=%.1f,power=%.1f,energy=%.3f",
(double)u, (double)p, e_wh);
esp_http_client_config_t cfg = {
.url = url,
.method = HTTP_METHOD_POST,
.timeout_ms = 5000,
};
esp_http_client_handle_t client = esp_http_client_init(&cfg);
esp_http_client_set_header(client, "Authorization", "Token " INFLUX_TOKEN);
esp_http_client_set_header(client, "Content-Type", "text/plain");
esp_http_client_set_post_field(client, body, strlen(body));
esp_err_t err = esp_http_client_perform(client);
int status = esp_http_client_get_status_code(client);
esp_http_client_cleanup(client);
if (err != ESP_OK || status != 204) {
ESP_LOGW(TAG, "influx HTTP %d (err %s)", status, esp_err_to_name(err));
}
}
/* In the 60-second loop: */
rbamp_period_snapshot_t snap;
if (rbamp_read_period_snapshot(dev, &snap, 50, false) == ESP_OK && snap.valid) {
float u;
rbamp_read_voltage(dev, 0, &u);
push_influx(u, snap.avg_p[0], rbamp_energy_wh(dev, 0));
}
En Grafana, añada un origen de datos de InfluxDB y después un panel con una consulta Flux:
from(bucket: "energy")
|> range(start: -24h)
|> filter(fn: (r) => r._measurement == "rbamp" and r.device == "main")
|> filter(fn: (r) => r._field == "power")
Para un despliegue de larga duración, envíe además una carga de diagnóstico a una medición separada que incluya el nivel de heap (mediante esp_get_free_heap_size()) y los contadores de instantáneas de período correctas / fallidas: así puede vigilar la salud del bus y del WiFi en el mismo gráfico que los datos de energía:
snprintf(body, sizeof(body),
"rbamp_diag,device=main heap_free=%u,snap_ok=%lu,snap_fail=%lu",
(unsigned)esp_get_free_heap_size(),
(unsigned long)snap_ok_count,
(unsigned long)snap_fail_count);
/* ...push to InfluxDB... */
: los contadores internos de reintentos y de coherencia del componente no se exponen en la API pública (vea 10 · Solución de problemas, «Sobre los contadores de reintentos y coherencia»). Cuente snap_ok_count / snap_fail_count usted mismo en la aplicación, a partir de los valores devueltos por rbamp_read_period_snapshot().
Multiplataforma: difusión desde un único ESP32
Si necesita a la vez autodescubrimiento de HA, InfluxDB y Node-RED, publique el JSON de estado una vez en MQTT y deje que cada consumidor se suscriba a rbamp/+/state. El ESP32 habla solo con el broker MQTT; el propio broker reparte a los suscriptores. No envíe desde el ESP32 a N endpoints HTTP directamente: eso acopla el dispositivo a consumidores concretos.
Para un flujo de muy alta frecuencia (RT a 10 Hz), ejecute en la Pi un script auxiliar de Python junto al broker: suscríbase al tema rápido, reduzca la frecuencia de muestreo y vuelva a publicar en los temas lentos. El bucle I²C del ESP32 (una tarea de FreeRTOS con llamadas rbamp_read_*()) debe quedar centrado, libre de sobrecarga HTTP.
Enlaces
-
06 · Ejemplos: los proyectos base sobre los que se construyen estas integraciones (incluidos
mqtt_publisheryha_discovery) -
08 · Integraciones en la nube — AWS IoT / Azure / GCP / InfluxDB Cloud / webhook genérico
-
10 · Solución de problemas — patrones para la desconexión de MQTT, el manejador de eventos de WiFi y el presupuesto de heap para TLS
Código fuente y incidencias: rb-amp/rbamp-esp-idf · esta página en el repositorio: docs/07_diy_integrations.md (v1.7.3)