07 · Integrações DIY
Este capítulo trata de usar o rbAmp para além do painel Energia padrão do HA: exportação para bases de dados de séries temporais externas, publicação por MQTT sem o HA, controlo de carga em malha fechada e leitura do rbAmp a partir de mestres não-ESPHome.
Cross-references:
- Esquema YAML:
09_api_reference.md - Especificidades do HA:
08_has_integrations.md - Biblioteca cliente Arduino:
rbamp-arduino - Biblioteca cliente ESP-IDF:
rbamp-esp-idf - Python (CPython + MicroPython):
rbamp-python
1 · InfluxDB e Grafana através do Home Assistant
O caminho mais simples para InfluxDB + Grafana não exige alterações ao YAML. O Home Assistant exporta todos os estados das entidades para o InfluxDB através da sua integração nativa:
YAML do Home Assistant (não ESPHome) — vai para a configuração do Home Assistant, não para o YAML do nó.
# 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 publicação de sensor rbAmp (uma vez por update_interval) torna-se um ponto no InfluxDB. O Grafana consulta depois o InfluxDB e constrói os painéis.
Um painel Grafana mínimo para a potência em tempo real:
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 resolução (contornando o HA)
A máquina de estados do HA regista apenas alterações de estado. Para uma série densa com um ponto a cada 60 s (o update_interval predefinido), o HA chega. Se precisar de resolução inferior a um minuto, reduza o update_interval e deixe o recorder do HA + a integração InfluxDB capturar a essa cadência:
rbamp:
id: meter1
update_interval: 10s # 10-second resolution — ×6 I²C traffic, acceptable
2 · Publicação MQTT direta (sem HA)
O ESPHome tem um componente mqtt: incorporado que publica todos os estados dos sensores num broker. Os sensores rbAmp são publicados a cada update_interval, tal como quaisquer outros.
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"
Com topic_prefix: rbamp/ui1, o ESPHome publica:
| Tópico 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 |
Qualquer subscritor MQTT — Node-RED, InfluxDB Telegraf, OpenHAB, um script Python personalizado — pode consumir estes tópicos diretamente.
Mensagens MQTT retidas
Acrescente retain: true a cada sensor se os subscritores que se ligam após uma publicação tiverem de ver imediatamente o último valor:
Pressupõe que já tem um bloco mqtt: no YAML do nó.
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
Retenção MQTT e OTA — o que precisa de saber
As mensagens retidas sobrevivem a um reinício do ESP32 (essa é a sua função principal). Isto cria dois cenários que convém conhecer antecipadamente:
- Atualização OTA de um nó. Após a gravação, o ESP32 reinicia. Os valores retidos antigos permanecem no broker e continuam visíveis para os subscritores durante ~5..30 segundos (até o nó voltar a ligar-se e publicar novos valores). Se o nó nunca voltar (firmware corrompida, falha fatal no arranque), os valores retidos antigos serão apresentados indefinidamente. Isto mascara o estado offline nos painéis que leem apenas
statesemstatus.
Mitigação: defina sempre um will_message: (LWT) no tópico status (como no exemplo acima). O broker definirá a carga offline quando a ligação cair; os subscritores podem vigiar status para detetar nós bloqueados. Os tópicos dos sensores continuarão a conter os valores antigos neste caso — isso é normal, mas os subscritores ficam a saber que os dados estão desatualizados.
- Alterar
topic_prefix:entre compilações de firmware. Se renomeartopic_prefix:(por exemplorbamp/ui1→rbamp/kitchen) e atualizar o nó por OTA, as mensagens retidas sob o prefixo antigo ficam no broker para sempre. Os subscritores que não estão cientes da alteração continuam a ver dados obsoletos dos tópicos fantasma.
Mitigação: antes de um OTA com prefixo renomeado, limpe as mensagens retidas antigas publicando um payload vazio com retain: true em cada tópico antigo (CLI: mosquitto_pub -h ). Sem isto, os zombies ficam até alguém os limpar manualmente.
- Mensagem de nascimento e
start_session: truepara reconectar após um reinício do broker — ver a documentação do blocomqtt:do ESPHome para as opçõesclean_session:ekeepalive:. Estes parâmetros controlam como o broker trata mensagens QoS 1/2 pendentes na desconexão.
3 · Ações Lambda do ESPHome
O callback on_value do ESPHome dispara em cada nova leitura do sensor. Pode usá-lo para ações de limiar executadas inteiramente no ESP32, sem passar pelo HA.
Alarme de limiar de corrente
Pressupõe que já tem uma entrada switch: com o id usado abaixo.
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
Deteção de um degrau 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;
Publicar num tópico MQTT personalizado ao atingir um limiar
Pressupõe que já tem um bloco mqtt: no YAML do nó.
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 · Controlo em malha fechada — PID de esquentador
Um caso de uso típico da medição doméstica com rbAmp é o autoconsumo solar: aquecer água com a energia solar excedentária em vez de a exportar para a rede.
O padrão usa dois módulos rbAmp: um na alimentação da rede (importação / exportação), outro no circuito do esquentador. Um relé PWM ou SSR no aquecedor permite um controlo de potência variável.
# 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);
: potência bidirecional (valores negativos = exportação) requer um módulo STANDARD (STD) com a polaridade de tensão correta na cablagem. No BASIC a firmware limita a média da potência ativa do período a P ≥ 0 — a P instantânea continua negativa no momento da produção, mas o acumulador de período de exportação fica vazio. O comportamento por nível está em 02_tiers.md, a cablagem de polaridade está em 04_hardware.md.
5 · Encadear callbacks através da API do ESPHome
A API nativa do ESPHome (porta 6053) pode ser usada para acionar scripts Python externos através da API WebSocket, sem um HA em execução contínua.
A biblioteca Python aioesphomeapi (pip install aioesphomeapi) dá acesso assíncrono direto aos estados das 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())
O padrão é útil para:
- Alimentar as leituras do rbAmp num circuito de controlo personalizado que não encaixa no modelo de lambda YAML do ESPHome.
- Registo num formato personalizado ou numa base de dados.
- Lógica de limiares em Python, quando a RAM de 512 KB do ESP32 é um limite para cálculos complexos.
O cliente da API corre em qualquer host Python 3.8+ na mesma rede — um Raspberry Pi, um contentor Docker, um portátil de desenvolvimento.
6 · Potência aparente — cálculo do lado do cliente
Quando apparent_power está declarada no bloco sensor:, o componente calcula S = U_rms × I_rms[ch0] no ESP32 a partir de duas leituras recentes. Se precisar de potência aparente para vários canais (CH1, CH2), ou quiser derivá-la de entidades do HA em vez do próprio componente, use um sensor template no HA:
YAML do Home Assistant (não ESPHome) — vai para a configuração do Home Assistant, não para o YAML do nó.
# 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: o apparent_power no esquema do ESPHome usa apenas a corrente CH0. O modelo acima é a abordagem recomendada para CH1/CH2 em implementações UI2/UI3.
7 · Ler o rbAmp sem o ESPHome
O módulo rbAmp é um escravo I²C comum. Qualquer mestre I²C pode lê-lo usando o protocolo da referência da API do módulo. As bibliotecas cliente irmãs (repositórios de distribuição — marcadores até à publicação):
| Biblioteca | Distribuição | 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 Linux, PC, ESP32/RP2040/STM32 em MicroPython |
Todas as bibliotecas implementam o mesmo mapa de registos e o mesmo protocolo de medição por período que o componente ESPHome. Podem ser usadas de forma independente ou em paralelo.
Quando NÃO usar o ESPHome
- Já tem firmware ESP32 que não é ESPHome e precisa de acrescentar leituras do rbAmp — use a biblioteca ESP-IDF e chame a API diretamente.
- O mestre é um Raspberry Pi ou outro SBC Linux — use a biblioteca Python.
- Tem um PLC STM32 ou uma placa personalizada — STM32 HAL.
- Um protótipo rápido num Arduino UNO ou Leonardo — a biblioteca Arduino.
Acumulação de energia multiplataforma — uma nota
O componente ESPHome usa acumuladores double persistidos na NVS que sobrevivem a um reinício (nos módulos STANDARD são também alimentados pelos contadores de energia do próprio módulo). As bibliotecas irmãs podem usar mecanismos de persistência diferentes — para os detalhes e a compatibilidade futura de uma biblioteca específica, consulte o seu 10_troubleshooting.md (secção de persistência de energia). Se migrar do ESPHome para firmware bare-metal, planeie a migração de dados: exporte o último valor de Wh do HA antes da troca e semeie com ele o acumulador da nova firmware.
8 · Pontes Tasmota / WLED / OpenHAB
Tasmota
O Tasmota não tem driver rbAmp nativo. A ponte mais limpa é usar o ESPHome como leitor rbAmp e o Tasmota como mestre I²C separado para outros dispositivos, sem os misturar.
Se precisar especificamente do Tasmota para o rbAmp, use scripting Berry (Tasmota 12.x+) para escrever um driver personalizado que faça as leituras I²C — um byte por fase de endereço nas escritas, e leitura em rajada opcional para o bloco de valores instantâneos (ver 09 · Referência da API). A biblioteca MicroPython de rbamp-python é uma referência útil para os endereços de registos e a descodificação de floats.
WLED
O WLED (firmware para controladores de LED) não expõe um mestre I²C em scripts de utilizador. O rbAmp e o WLED só podem ser dispositivos independentes no mesmo barramento se estiverem em segmentos de barramento separados ou tiverem endereços não conflituantes. Não existe uma ponte oficial.
OpenHAB
O ESPHome publica dados por MQTT (ver Exemplo 2) ou pela API nativa (aioesphomeapi). O binding MQTT do OpenHAB pode subscrever os tópicos do ESPHome e entregar leituras rbAmp em regras e Items do OpenHAB. A configuração do binding MQTT está documentada na documentação do OpenHAB.
Fonte e problemas: rb-amp/rbamp-esphome · esta página no repositório: docs/07_diy_integrations.md (v1.9.1)