rbAmp
IT
Negozio
Docs
Aggiornato · Modifica su GitHub

07 · Integrazioni fai-da-te

Questo capitolo tratta l'uso di rbAmp oltre la dashboard Energia standard di HA: esportazione verso database di serie temporali esterni, pubblicazione via MQTT senza HA, controllo dei carichi ad anello chiuso e lettura di rbAmp da master non ESPHome.

Cross-references:


1 · InfluxDB e Grafana tramite Home Assistant

Il percorso più semplice verso InfluxDB + Grafana non richiede modifiche al YAML. Home Assistant esporta tutti gli stati delle entità verso InfluxDB tramite la sua integrazione nativa:

YAML di Home Assistant (non ESPHome) — va nella configurazione di Home Assistant, non nel YAML del nodo.

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

Ogni pubblicazione di sensore rbAmp (una volta per update_interval) diventa un punto in InfluxDB. Grafana poi interroga InfluxDB e costruisce le dashboard.

Un pannello Grafana minimo per la potenza in tempo reale:

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

Per 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 ad alta risoluzione (bypassando HA)

La macchina a stati di HA registra solo le variazioni di stato. Per una serie densa con un punto ogni 60 s (il predefinito update_interval), HA va bene. Se serve una risoluzione sotto il minuto, abbassare update_interval e lasciare che il recorder di HA + l'integrazione InfluxDB catturino a quella frequenza:

YAML
rbamp:
  id: meter1
  update_interval: 10s     # 10-second resolution — ×6 I²C traffic, acceptable

2 · Pubblicazione MQTT diretta (senza HA)

ESPHome ha un componente mqtt: integrato che pubblica tutti gli stati dei sensori su un broker. I sensori rbAmp vengono pubblicati a ogni update_interval, come tutti gli altri.

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"

Con topic_prefix: rbamp/ui1, ESPHome pubblica:

Topic 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

Qualsiasi abbonato MQTT — Node-RED, InfluxDB Telegraf, OpenHAB, uno script Python personalizzato — può consumare direttamente questi topic.

Messaggi MQTT retained

Aggiungi retain: true a ciascun sensore se gli abbonati che si connettono dopo una pubblicazione devono vedere subito l'ultimo valore:

Presuppone che esista già un blocco mqtt: nel YAML del nodo.

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

Ritenzione MQTT e OTA — cosa occorre sapere

I messaggi retained sopravvivono al riavvio dell'ESP32 (è il loro scopo principale). Questo crea due scenari di cui è utile essere consapevoli in anticipo:

  1. Aggiornamento OTA di un nodo. Dopo il flash, l'ESP32 si riavvia. I vecchi valori retained restano nel broker e rimangono visibili agli abbonati per ~5..30 secondi (finché il nodo non si riconnette e pubblica di nuovo). Se il nodo non torna mai (firmware corrotto, crash fatale all'avvio), i vecchi valori retained verranno mostrati a tempo indeterminato. Questo maschera lo stato offline alle dashboard che leggono solo state senza status.

Mitigazione: impostare sempre un will_message: (LWT) sul topic status (come nell'esempio sopra). Il broker imposta il payload offline quando la connessione cade; gli abbonati possono osservare status per rilevare nodi bloccati. I topic dei sensori conserveranno in questo caso i vecchi valori — è normale, ma gli abbonati sanno che i dati sono obsoleti.

  1. Modifica di topic_prefix: tra una build del firmware e l'altra. Se si rinomina topic_prefix: (ad esempio rbamp/ui1 → rbamp/kitchen) e si aggiorna il nodo via OTA, i messaggi retained sotto il prefisso vecchio restano per sempre nel broker. Gli abbonati che non conoscono la modifica continuano a ricevere dati obsoleti dai topic zombie.

Mitigazione: prima di un OTA con un prefisso rinominato, cancella i vecchi messaggi retained pubblicando un payload vuoto con retain: true su ciascun vecchio topic (CLI: mosquitto_pub -h -t '' -r -n). Senza questo, gli zombie restano finché qualcuno non li cancella a mano.

  1. Messaggio di nascita e start_session: true per riconnettersi dopo un riavvio del broker — vedere la documentazione del blocco ESPHome mqtt: per le opzioni clean_session: e keepalive:. Questi parametri controllano come il broker gestisce i messaggi QoS 1/2 in sospeso alla disconnessione.

3 · Azioni Lambda di ESPHome

Il callback on_value di ESPHome scatta a ogni nuova lettura del sensore. Puoi usarlo per azioni a soglia eseguite interamente sull'ESP32, senza passare da HA.

Allarme a soglia di corrente

Presuppone che esista già una voce switch: con l'id usato sotto.

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

Rilevamento di un salto di carico (Lambda personalizzata)

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;

Pubblicazione su un topic MQTT personalizzato a una soglia

Presuppone che esista già un blocco mqtt: nel YAML del nodo.

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 · Controllo ad anello chiuso — PID per scaldabagno

Un caso d'uso tipico per la misura domestica con rbAmp è l'autoconsumo solare: scaldare l'acqua con la potenza solare in eccesso invece di immetterla in rete.

Il pattern usa due moduli rbAmp: uno sull'alimentazione di rete (importazione / esportazione), uno sul circuito dello scaldabagno. Un relè PWM o un SSR sullo scaldabagno consente il controllo di potenza variabile.

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

: potenza bidirezionale (valori negativi = esportazione) richiede un modulo STANDARD (STD) con cablaggio corretto della polarità di tensione. Su BASIC il firmware riporta la media della potenza attiva sul periodo a P ≥ 0 — la potenza istantanea P risulta ancora negativa nel momento della generazione, ma l'accumulatore di periodo per l'esportazione resta vuoto. Il comportamento per livello è in 02_tiers.md, il cablaggio della polarità è in 04_hardware.md.


5 · Concatenamento di callback tramite l'API ESPHome

L'API nativa di ESPHome (porta 6053) può essere usata per avviare script Python esterni tramite l'API WebSocket, senza un'istanza HA sempre in esecuzione.

La libreria Python aioesphomeapi (pip install aioesphomeapi) dà accesso asincrono diretto agli stati delle entità:

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

Il pattern è utile per:

  • Inserire le letture di rbAmp in un controllo personalizzato che non rientra nel modello YAML Lambda di ESPHome.
  • Registrazione in un formato personalizzato o in un database.
  • Logica di soglia in Python, quando i 512 KB di RAM dell'ESP32 sono un limite per calcoli complessi.

Il client API gira su qualsiasi host Python 3.8+ della stessa rete — un Raspberry Pi, un container Docker, un laptop di sviluppo.


6 · Potenza apparente — calcolo lato client

Quando apparent_power è dichiarata nel blocco sensor:, il componente calcola S = U_rms × I_rms[ch0] sull'ESP32 da due letture fresche. Se serve la potenza apparente per più canali (CH1, CH2), o si vuole derivarla dalle entità di HA anziché dal componente stesso, usare un sensore template in HA:

YAML di Home Assistant (non ESPHome) — va nella configurazione di Home Assistant, non nel YAML del nodo.

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: apparent_power nello schema ESPHome usa solo la corrente CH0. Il template qui sopra è l'approccio raccomandato per CH1/CH2 nelle installazioni UI2/UI3.


7 · Lettura di rbAmp senza ESPHome

Il modulo rbAmp è un normale slave I²C. Qualsiasi master I²C può leggerlo usando il protocollo del riferimento API del modulo. Le librerie client gemelle (repository di distribuzione — segnaposto fino alla pubblicazione):

Libreria Distribuzione Lingua Piattaforma di destinazione
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 con MicroPython

Tutte le librerie implementano la stessa mappa dei registri e lo stesso protocollo di misura per periodi del componente ESPHome. Possono essere usate in modo indipendente o in parallelo.

Quando NON usare ESPHome

  • Hai già un firmware ESP32 non ESPHome e devi aggiungere letture rbAmp — usa la libreria ESP-IDF e chiama direttamente l'API.
  • Il master è un Raspberry Pi o un altro SBC Linux — usare la libreria Python.
  • Si dispone di un PLC STM32 o di una scheda personalizzata — STM32 HAL.
  • Un prototipo rapido su Arduino UNO o Leonardo — la libreria Arduino.

Accumulo di energia multipiattaforma — una nota

Il componente ESPHome usa accumulatori double persistiti in NVS che sopravvivono a un riavvio (sui moduli STANDARD sono inoltre alimentati dai contatori di energia integrati del modulo). Le librerie sorelle possono usare meccanismi di persistenza diversi — per i dettagli e la compatibilità futura di una specifica libreria, vedi il suo 10_troubleshooting.md (sezione sulla persistenza dell'energia). Se migri da ESPHome a un firmware bare-metal, pianifica la migrazione dei dati: esporta l'ultimo valore in Wh da HA prima del passaggio e inizializza con quello l'accumulatore del nuovo firmware.


8 · Ponti Tasmota / WLED / OpenHAB

Tasmota

Tasmota non ha un driver nativo per rbAmp. Il ponte più pulito è usare ESPHome come lettore rbAmp e Tasmota come master I²C separato per altri dispositivi, senza mescolarli.

Se ti serve specificamente Tasmota per rbAmp, usa lo scripting Berry (Tasmota 12.x+) per scrivere un driver personalizzato che esegua le letture I²C — un solo byte per fase di indirizzo per le scritture, lettura a raffica facoltativa per il blocco dei valori istantanei (vedi 09 · Riferimento API). La libreria MicroPython di rbamp-python è un utile riferimento per gli indirizzi dei registri e la decodifica dei float.

WLED

WLED (firmware per controller LED) non espone un master I²C negli script utente. rbAmp e WLED possono essere dispositivi indipendenti sullo stesso bus solo se sono su segmenti di bus separati o hanno indirizzi non in conflitto. Non esiste un ponte ufficiale.

OpenHAB

ESPHome pubblica i dati via MQTT (vedere l'Esempio 2) o tramite l'API nativa (aioesphomeapi). Il binding MQTT di OpenHAB può sottoscrivere i topic ESPHome e portare le letture rbAmp nelle regole e negli Item di OpenHAB. La configurazione del binding MQTT è descritta nella documentazione di OpenHAB.


Fonte e segnalazioni: rb-amp/rbamp-esphome · questa pagina nel repository: docs/07_diy_integrations.md (v1.9.1)