07 · DIY-интеграции
Эта глава — о применении rbAmp за пределами стандартной панели Energy в HA: экспорт во внешние базы временных рядов, публикация по MQTT без HA, управление нагрузкой с обратной связью и чтение rbAmp с мастеров, не являющихся ESPHome.
Cross-references:
- Схема YAML:
09_api_reference.md - Особенности HA:
08_has_integrations.md - Клиентская библиотека Arduino:
rbamp-arduino - Клиентская библиотека ESP-IDF:
rbamp-esp-idf - Python (CPython + MicroPython):
rbamp-python
1 · InfluxDB и Grafana через Home Assistant
Самый простой путь к InfluxDB + Grafana не требует изменений YAML. Home Assistant экспортирует все состояния сущностей в InfluxDB через свою нативную интеграцию:
Home Assistant YAML (не ESPHome) — идёт в конфигурацию Home Assistant, а не в 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
Каждая публикация датчика rbAmp (раз в update_interval) становится точкой в InfluxDB. Grafana затем запрашивает InfluxDB и строит дашборды.
Минимальная панель Grafana для мгновенной мощности:
SELECT mean("value") FROM "state"
WHERE "entity_id" = 'sensor.rbamp_ui1_mains_power'
AND $timeFilter
GROUP BY time(1m)
Для 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 (в обход HA)
Состояние HA записывает только изменения состояния. Для плотного ряда с точкой каждые 60 с (стандартный update_interval) HA подходит. Если нужно разрешение меньше минуты, уменьшите update_interval и пусть рекордер HA + интеграция InfluxDB пишут с этой частотой:
rbamp:
id: meter1
update_interval: 10s # 10-second resolution — ×6 I²C traffic, acceptable
2 · Прямая публикация MQTT (без HA)
В ESPHome есть встроенный компонент mqtt:, который публикует состояния всех датчиков в брокер. Датчики rbAmp публикуются при каждом update_interval, как и любые другие.
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"
С topic_prefix: rbamp/ui1 ESPHome публикует:
| Топик MQTT | Payload |
|---|---|
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 |
Любой подписчик MQTT — Node-RED, InfluxDB Telegraf, OpenHAB, собственный скрипт Python — может читать эти топики напрямую.
Сохранённые сообщения MQTT
Добавьте retain: true к каждому датчику, если подписчики, подключающиеся после публикации, должны сразу видеть последнее значение:
Предполагается, что в YAML узла уже есть блок mqtt:.
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
MQTT retain и OTA — что нужно знать
Сохранённые сообщения переживают перезапуск ESP32 (это их основное назначение). Есть два сценария, о которых стоит знать заранее:
- OTA-обновление узла. После прошивки ESP32 перезагружается. Старые сохранённые значения остаются у брокера и видны подписчикам ~5..30 секунд (пока узел не переподключится и не опубликует новые). Если узел не возвращается (повреждённая прошивка, фатальный сбой при загрузке), старые сохранённые значения будут показываться бессрочно. Это скрывает офлайн-состояние от дашбордов, которые читают только
stateбезstatus.
Смягчение: всегда задавайте will_message: (LWT) для топика status (как в примере выше). Брокер установит payload offline, когда соединение оборвётся; подписчики могут следить за status, чтобы обнаружить зависшие узлы. Топики датчиков в этом случае сохранят старые значения — это нормально, но подписчики знают, что данные устарели.
- Смена
topic_prefix:между сборками прошивки. Если вы переименуетеtopic_prefix:(например,rbamp/ui1→rbamp/kitchen) и обновите узел по OTA, сохранённые сообщения под старым префиксом навсегда останутся у брокера. Подписчики, не знающие об изменении, продолжают получать устаревшие данные из «зомби»-топиков.
Смягчение: перед OTA с переименованным префиксом очистите старые сохранённые сообщения, публикуя пустую полезную нагрузку с retain: true в каждом старом топике (CLI: mosquitto_pub -h ). Иначе «зомби» будут висеть, пока их не очистят вручную.
- Сообщение о появлении и
start_session: trueдля переподключения после перезапуска брокера — см. документацию блокаmqtt:ESPHome по параметрамclean_session:иkeepalive:. Эти параметры определяют, как брокер обрабатывает ожидающие сообщения QoS 1/2 при разрыве связи.
3 · Действия lambda в ESPHome
Колбэк ESPHome on_value срабатывает при каждом новом показании датчика. Его можно использовать для пороговых действий, выполняемых целиком на ESP32, без обхода через HA.
Сигнал превышения тока
Предполагается, что у вас уже есть запись switch: с идентификатором, использованным ниже.
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
Обнаружение скачка нагрузки (собственный Lambda)
# 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;
Публикация в пользовательский топик MQTT по порогу
Предполагается, что в YAML узла уже есть блок mqtt:.
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 · Управление с обратной связью — PID водонагревателя
Типичный сценарий для учёта rbAmp в доме — самопотребление солнечной энергии: нагревать воду излишком солнечной мощности вместо выдачи в сеть.
Схема использует два модуля rbAmp: один на вводе сети (импорт / экспорт), один на цепи водонагревателя. ШИМ-реле или SSR на нагревателе обеспечивают регулируемую мощность.
# 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);
: двунаправленная мощность (отрицательные значения = выдача) требует модуля STANDARD (STD) с правильной полярностью проводки напряжения. На BASIC прошивка ограничивает среднюю активную мощность за период значением P ≥ 0 — мгновенная P всё ещё может быть отрицательной в момент генерации, но накопитель периода выдачи остаётся пустым. Поведение по уровням — в 02_tiers.md, проводка полярности — в 04_hardware.md.
5 · Цепочка обратных вызовов через API ESPHome
Нативный API ESPHome (порт 6053) можно использовать для запуска внешних скриптов Python через WebSocket API без постоянно работающего HA.
Python-библиотека aioesphomeapi (pip install aioesphomeapi) даёт прямой асинхронный доступ к состояниям сущностей:
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())
Этот шаблон полезен для:
- Передача показаний rbAmp в собственный контур управления, который не укладывается в модель YAML lambda ESPHome.
- Вывод в пользовательский формат или базу данных.
- Логика порогов на Python, когда 512 КБ RAM ESP32 — ограничение для сложной математики.
Клиент API работает на любом хосте с Python 3.8+ в той же сети — Raspberry Pi, контейнер Docker, ноутбук разработчика.
6 · Полная мощность — расчёт на стороне клиента
Если apparent_power объявлена в блоке sensor:, компонент вычисляет S = U_rms × I_rms[ch0] на ESP32 по двум свежим показаниям. Если нужна полная мощность для нескольких каналов (CH1, CH2) или её нужно вывести из сущностей HA, а не из самого компонента, используйте датчик template в HA:
Home Assistant YAML (не ESPHome) — идёт в конфигурацию Home Assistant, а не в 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) }}
Примечание: apparent_power в схеме ESPHome использует только ток CH0. Шаблон выше — рекомендуемый подход для CH1/CH2 на развёртываниях UI2/UI3.
7 · Чтение rbAmp без ESPHome
Модуль rbAmp — обычное ведомое устройство I²C. Любой мастер I²C может читать его по протоколу из справочника API модуля. Родственные клиентские библиотеки (репозитории дистрибуции — заглушки до публикации):
| Библиотека | Распространение | Язык | Целевая платформа |
|---|---|---|---|
| Arduino | rbamp-arduino |
C++ | ESP32 (фреймворк Arduino), AVR, RP2040 |
| ESP-IDF | rbamp-esp-idf |
C | ESP32 (фреймворк IDF) |
| Python (CPython + MicroPython) | rbamp-python |
Python 3 | Raspberry Pi, Linux SBC, ПК, ESP32/RP2040/STM32 на MicroPython |
Все библиотеки реализуют ту же карту регистров и протокол учёта по периодам, что и компонент ESPHome. Их можно использовать независимо или параллельно.
Когда НЕ использовать ESPHome
- У вас уже есть прошивка ESP32 не от ESPHome, и нужно добавить чтение rbAmp — используйте библиотеку ESP-IDF и вызывайте API напрямую.
- Мастер — Raspberry Pi или другой Linux SBC; используйте библиотеку Python.
- У вас ПЛК на STM32 или собственная плата — STM32 HAL.
- Быстрый прототип на Arduino UNO или Leonardo — библиотека Arduino.
Накопление энергии на разных платформах — примечание
Компонент ESPHome использует накопители double, сохраняемые в NVS, которые переживают перезагрузку (на модулях STANDARD дополнительно подпитываются собственными счётчиками энергии модуля). Смежные библиотеки могут использовать другие механизмы сохранения — подробности и прямую совместимость конкретной библиотеки см. в её 10_troubleshooting.md (раздел о сохранении энергии). Если вы переходите с ESPHome на bare-metal прошивку, спланируйте миграцию данных: выгрузите последнее значение Вт·ч из HA перед заменой и задайте им накопитель новой прошивки.
8 · Мосты Tasmota / WLED / OpenHAB
Tasmota
У Tasmota нет нативного драйвера rbAmp. Самый чистый мост — использовать ESPHome как считыватель rbAmp, а Tasmota как отдельный I²C-мастер для других устройств, не смешивая их.
Если вам нужен именно Tasmota для rbAmp, используйте скриптование Berry (Tasmota 12.x+), чтобы написать собственный драйвер, выполняющий чтение I²C — одиночный байт на фазу адреса для записей, опционально пакетное чтение для блока мгновенных значений (см. 09 · Справочник API). Библиотека MicroPython из rbamp-python — полезный справочник адресов регистров и декодирования float.
WLED
WLED (прошивка для LED-контроллеров) не открывает мастер I²C в пользовательских скриптах. rbAmp и WLED могут быть независимыми устройствами на одной шине, только если они на разных сегментах шины или имеют непересекающиеся адреса. Официального моста нет.
OpenHAB
ESPHome публикует данные по MQTT (см. Пример 2) или через нативный API (aioesphomeapi). Привязка OpenHAB MQTT может подписаться на топики ESPHome и передавать показания rbAmp в правила и Items OpenHAB. Настройка привязки MQTT описана в документации OpenHAB.
Исходники и вопросы: rb-amp/rbamp-esphome · эта страница в репозитории: docs/07_diy_integrations.md (v1.9.1)