rbAmp
PT
Loja
Docs
Atualizado · Editar no GitHub (Edit on GitHub)

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:


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ó.

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

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:

Text
SELECT mean("value") FROM "state"
WHERE "entity_id" = 'sensor.rbamp_ui1_mains_power'
AND $timeFilter
GROUP BY time(1m)

Para InfluxDB 2.x (Flux):

Text
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:

YAML
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.

YAML
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ó.

YAML
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:

  1. 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 state sem status.

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.

  1. Alterar topic_prefix: entre compilações de firmware. Se renomear topic_prefix: (por exemplo rbamp/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 -t '' -r -n). Sem isto, os zombies ficam até alguém os limpar manualmente.

  1. Mensagem de nascimento e start_session: true para reconectar após um reinício do broker — ver a documentação do bloco mqtt: do ESPHome para as opções clean_session: e keepalive:. 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.

YAML
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)

YAML
# 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ó.

YAML
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.

YAML
# 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);
Nota

: 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:

Python
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ó.

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) }}

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)