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:
- Schema YAML:
09_api_reference.md - Dettagli specifici di HA:
08_has_integrations.md - Libreria client Arduino:
rbamp-arduino - Libreria client ESP-IDF:
rbamp-esp-idf - Python (CPython + MicroPython):
rbamp-python
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.
# 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:
SELECT mean("value") FROM "state"
WHERE "entity_id" = 'sensor.rbamp_ui1_mains_power'
AND $timeFilter
GROUP BY time(1m)
Per 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 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:
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.
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.
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:
- 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
statesenzastatus.
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.
- Modifica di
topic_prefix:tra una build del firmware e l'altra. Se si rinominatopic_prefix:(ad esempiorbamp/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 ). Senza questo, gli zombie restano finché qualcuno non li cancella a mano.
- Messaggio di nascita e
start_session: trueper riconnettersi dopo un riavvio del broker — vedere la documentazione del blocco ESPHomemqtt:per le opzioniclean_session:ekeepalive:. 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.
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)
# 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.
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.
# 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);
: 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à:
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.
# 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)