07 · DIY-интеграции
Как передавать показания rbamp в популярные самохостируемые системы автоматизации. Для каждой платформы есть минимальный рабочий проект ESP-IDF и соответствующая настройка на стороне платформы.
Облачные и коммерческие интеграции (AWS IoT, Azure, GCP, InfluxDB Cloud) — 08 · Облачные интеграции.
| Платформа | Транспорт | Автообнаружение | Компоненты IDF |
|---|---|---|---|
| Home Assistant | MQTT | да (HA MQTT Discovery) | espressif/esp_mqtt_client |
| ESPHome | Нативный API + MQTT | да (конфигурация YAML) | (альтернативный фреймворк — см. ниже) |
| Node-RED | MQTT (или HTTP) | ручной поток | espressif/esp_mqtt_client |
| OpenHAB | MQTT (или REST) | ручной .things |
espressif/esp_mqtt_client |
| Domoticz | MQTT (авто) или HTTP | Да (плагин MQTT) | esp_mqtt_client или esp_http_client |
| InfluxDB OSS + Grafana | HTTPS line-protocol | нет | esp_http_client |
Готовые проекты для двух основных сценариев находятся в examples/: examples/mqtt_publisher/ (публикатор MQTT по каналам) и examples/ha_discovery/ (автообнаружение HA поверх mqtt_publisher).
Home Assistant — MQTT Auto-discovery
Автообнаружение MQTT в HA автоматически создаёт устройство и его датчики, когда ESP32 публикует темы конфигурации. Правки YAML в HA не нужны.
Проект 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);
}
}
Полный проект — examples/ha_discovery/.
Результат в HA
Через несколько секунд после первой публикации HA автоматически создаёт устройство «Mains rbAmp» с 6 датчиками (напряжение, ток, мощность, энергия, частота, коэффициент мощности). Датчик энергии имеет state_class: total_increasing и правильный device_class — панель энергии HA принимает его как источник потребления.
Чтобы позже удалить устройство из HA, опубликуйте пустую полезную нагрузку в homeassistant/sensor/.../config (флаг retained очищает запись).
Многоканальный UI3
Повторите вызовы publish_discovery_sensor() с суффиксированными ключами для каналов 1 и 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 */
И расширьте JSON состояния полями "current_1", "power_1", "energy_1", заполняемыми из rbamp_read_current(dev, 1, &i) / snap.avg_p[1] / rbamp_energy_wh(dev, 1).
ESPHome — альтернатива через external_components
Если вы используете ESPHome (а не голый ESP-IDF), есть отдельный внешний компонент rbamp, который полностью заменяет этот компонент и сам обеспечивает интеграцию с HA через нативный API 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 интегрируется с HA нативно через API ESPHome (не MQTT) — устройство появляется в HA автоматически после прошивки.
Компонент rbamp-esphome живёт в отдельном репозитории — ссылки см. в основном индексе rbAmp. Используйте ESPHome вместо этого компонента; смешивать ESPHome и «голый» ESP-IDF в одном проекте обычно не стоит.
Node-RED
Подпишитесь на MQTT-тему ESP32 в потоке:
[
{
"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;"
}
]
Подключите rbamp_in → extract_power → rbamp_chart — и получите график мощности в реальном времени. То же самое — для энергии / напряжения / PF.
Если Node-RED работает на том же Pi, что и брокер MQTT, используйте хост localhost. Для удалённых брокеров используйте 192.168.X.Y:1883 и учётные данные, если брокер требует аутентификацию.
Сторона ESP32 — тот же скетч, что и в разделе Home Assistant выше; JSON-полезная нагрузка общая — различается только потребитель.
OpenHAB
OpenHAB 4.x + MQTT binding:
# 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" }
Сторона ESP32 — тот же проект, что и в разделе Home Assistant выше. JSON-полезная нагрузка общая — различается только потребитель.
Domoticz
Плагин автообнаружения MQTT в Domoticz понимает те же темы обнаружения homeassistant/.... Включите плагин в настройках Domoticz — и проект ESP32 из раздела HA выше автоматически зарегистрирует устройство в Domoticz, так же как в HA.
Альтернатива — нативный HTTP API Domoticz через 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));
Создайте устройство в интерфейсе Domoticz типа General → kWh (инкрементальный счётчик), получите его idx и жёстко пропишите в проект.
InfluxDB OSS + Grafana
Записывайте точки line-protocol в InfluxDB напрямую с ESP32 через 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));
}
В Grafana добавьте источник данных InfluxDB, затем панель с запросом Flux:
from(bucket: "energy")
|> range(start: -24h)
|> filter(fn: (r) => r._measurement == "rbamp" and r.device == "main")
|> filter(fn: (r) => r._field == "power")
Для долгого испытательного развёртывания дополнительно отправляйте диагностическую полезную нагрузку в отдельное измерение с уровнем кучи (через esp_get_free_heap_size()) и счётчиками успешных / неуспешных снимков периода — так можно видеть состояние шины и Wi-Fi на том же графике, что и данные энергии:
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... */
: внутренние счётчики повторов / проверок компонента не выведены в публичный API (см. 10 · Устранение неполадок, «О счётчиках повторов / проверок»). Ведите snap_ok_count / snap_fail_count самостоятельно на стороне приложения по возвращаемым значениям rbamp_read_period_snapshot().
Несколько платформ — раздача с одного ESP32
Если нужны одновременно HA Auto-discovery, InfluxDB и Node-RED, публикуйте JSON состояния в MQTT один раз и позвольте каждому потребителю подписаться на rbamp/+/state. ESP32 общается только с брокером MQTT — сам брокер раздаёт сообщения подписчикам. Не отправляйте данные напрямую с ESP32 на N HTTP-адресов: это привяжет устройство к конкретным потребителям.
Для потока очень высокой частоты (RT 10 Гц) запустите на Pi вспомогательный скрипт Python рядом с брокером — подпишитесь на быструю тему, прореживайте и публикуйте повторно в медленные темы. Цикл I²C на ESP32 (задача FreeRTOS с вызовами rbamp_read_*()) должен оставаться сфокусированным, без накладных расходов HTTP.
Ссылки
-
06 · Примеры — базовые проекты, на которых строятся эти интеграции (включая
mqtt_publisherиha_discovery) -
08 · Облачные интеграции — AWS IoT / Azure / GCP / InfluxDB Cloud / общий webhook
-
10 · Устранение неполадок — шаблоны для разрыва MQTT, обработчика событий WiFi, бюджета кучи TLS
Исходники и задачи: rb-amp/rbamp-esp-idf · эта страница в репозитории: docs/07_diy_integrations.md (v1.7.3)