07 · Intégrations DIY
Ce chapitre traite de l'usage de rbAmp au-delà du tableau de bord Énergie standard de HA : export vers des bases de séries temporelles externes, publication via MQTT sans HA, contrôle de charge en boucle fermée, et lecture de rbAmp depuis des maîtres non-ESPHome.
Cross-references:
- Schéma YAML :
09_api_reference.md - Particularités HA :
08_has_integrations.md - Bibliothèque cliente Arduino :
rbamp-arduino - Bibliothèque cliente ESP-IDF :
rbamp-esp-idf - Python (CPython + MicroPython) :
rbamp-python
1 · InfluxDB et Grafana via Home Assistant
Le chemin le plus simple vers InfluxDB + Grafana ne demande aucune modification YAML. Home Assistant exporte tous les états d'entités vers InfluxDB via son intégration native :
YAML Home Assistant (pas ESPHome) — à placer dans votre configuration Home Assistant, pas dans le YAML du nœud.
# 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
Chaque publication de capteur rbAmp (une fois par update_interval) devient un point dans InfluxDB. Grafana interroge ensuite InfluxDB et construit les tableaux de bord.
Un panneau Grafana minimal pour la puissance en direct :
SELECT mean("value") FROM "state"
WHERE "entity_id" = 'sensor.rbamp_ui1_mains_power'
AND $timeFilter
GROUP BY time(1m)
Pour 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 haute résolution (en contournant HA)
L'état de la machine HA n'enregistre que les changements d'état. Pour une série dense avec un point toutes les 60 s (le update_interval par défaut), HA suffit. Si vous avez besoin d'une résolution inférieure à la minute, réduisez le update_interval et laissez l'enregistreur HA + l'intégration InfluxDB capturer à ce rythme :
rbamp:
id: meter1
update_interval: 10s # 10-second resolution — ×6 I²C traffic, acceptable
2 · Publication MQTT directe (sans HA)
ESPHome dispose d'un composant mqtt: intégré qui publie tous les états des capteurs vers un broker. Les capteurs rbAmp sont publiés à chaque update_interval, comme les autres.
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"
Avec topic_prefix: rbamp/ui1, ESPHome publie :
| Sujet MQTT | Charge utile |
|---|---|
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 |
Tout abonné MQTT — Node-RED, InfluxDB Telegraf, OpenHAB, un script Python personnalisé — peut consommer ces topics directement.
Messages MQTT retenus
Ajoutez retain: true à chaque capteur si les abonnés qui se connectent après une publication doivent voir immédiatement la dernière valeur :
Suppose que vous disposez déjà d'un bloc mqtt: dans le YAML du nœud.
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
Rétention MQTT et OTA — ce qu'il faut savoir
Les messages conservés survivent à un redémarrage de l'ESP32 (c'est leur rôle premier). Cela crée deux scénarios à connaître à l'avance :
- Mise à jour OTA d'un nœud. Après le flash, l'ESP32 redémarre. Les anciennes valeurs conservées restent dans le broker et restent visibles pour les abonnés pendant ~5..30 secondes (jusqu'à ce que le nœud se reconnecte et publie de nouvelles valeurs). Si le nœud ne revient jamais (firmware corrompu, plantage fatal au démarrage), les anciennes valeurs conservées s'afficheront indéfiniment. Cela masque l'état hors ligne aux tableaux de bord qui ne lisent que
statesansstatus.
Atténuation : configurez toujours un will_message: (LWT) sur le topic status (comme dans l'exemple ci-dessus). Le broker publiera le payload offline lorsque la connexion tombera ; les abonnés peuvent surveiller status pour détecter les nœuds bloqués. Les topics de capteurs conserveront alors les anciennes valeurs — c'est normal, mais les abonnés savent que les données sont périmées.
- Modification de
topic_prefix:entre les builds du firmware. Si vous renommeztopic_prefix:(par ex.rbamp/ui1→rbamp/kitchen) et mettez à jour le nœud par OTA, les messages retenus sous l'ancien préfixe restent indéfiniment dans le broker. Les abonnés qui ignorent le changement continuent de voir des données périmées venant de ces topics fantômes.
Atténuation : avant une OTA avec un préfixe renommé, effacez les anciens messages conservés en publiant une charge vide avec retain: true sur chaque ancien sujet (CLI : mosquitto_pub -h ). Sans cela, les zombies restent jusqu'à ce que quelqu'un les efface manuellement.
- Message de naissance et
start_session: truepour la reconnexion après un redémarrage du broker — voir la documentation du bloc ESPHomemqtt:pour les optionsclean_session:etkeepalive:. Ces paramètres contrôlent la gestion par le broker des messages QoS 1/2 en attente lors d'une déconnexion.
3 · Actions Lambda ESPHome
Le callback on_value d'ESPHome se déclenche à chaque nouvelle lecture de capteur. Vous pouvez l'utiliser pour des actions à seuil exécutées entièrement sur l'ESP32, sans aller-retour par HA.
Alarme de seuil de courant
Suppose que vous disposez déjà d'une entrée switch: avec l'identifiant utilisé ci-dessous.
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
Détection d'un échelon de charge (Lambda personnalisé)
# 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;
Publication sur un topic MQTT personnalisé au franchissement d'un seuil
Suppose que vous disposez déjà d'un bloc mqtt: dans le YAML du nœud.
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 · Régulation en boucle fermée — PID de chauffe-eau
Un cas d'usage typique du comptage domestique rbAmp est l'autoconsommation solaire : chauffer l'eau avec le surplus solaire au lieu de l'injecter dans le réseau.
Le motif utilise deux modules rbAmp : un sur l'arrivée réseau (import / export), un sur le circuit du chauffe-eau. Un relais PWM ou un SSR sur le chauffage permet une régulation de puissance variable.
# 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);
: puissance bidirectionnelle (valeurs négatives = export) requiert un module STANDARD (STD) avec un câblage de polarité de tension correct. Sur BASIC, le firmware ramène la puissance active moyenne sur la période à P ≥ 0 — la puissance instantanée P se lit toujours négative au moment de la production, mais l'accumulateur de période d'export reste vide. Le comportement par gamme figure dans 02_tiers.md, le câblage de polarité dans 04_hardware.md.
5 · Chaînage des callbacks via l'API ESPHome
L'API native ESPHome (port 6053) peut servir à déclencher des scripts Python externes via l'API WebSocket, sans que HA ne fonctionne en permanence.
La bibliothèque Python aioesphomeapi (pip install aioesphomeapi) donne un accès asynchrone direct aux états des entités :
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())
Le motif est utile pour :
- Injecter les relevés rbAmp dans une boucle de régulation personnalisée qui ne rentre pas dans le modèle lambda YAML d'ESPHome.
- Journalisation vers un format ou une base de données personnalisés.
- Logique de seuils en Python, lorsque les 512 Ko de RAM de l'ESP32 sont une limite pour des calculs complexes.
Le client API fonctionne sur tout hôte Python 3.8+ du même réseau — un Raspberry Pi, un conteneur Docker, un ordinateur portable de développement.
6 · Puissance apparente — calcul côté client
Lorsque apparent_power est déclaré dans le bloc sensor:, le composant calcule S = U_rms × I_rms[ch0] sur l'ESP32 à partir de deux lectures fraîches. Si vous avez besoin de la puissance apparente pour plusieurs canaux (CH1, CH2), ou voulez la dériver d'entités HA plutôt que du composant lui-même, utilisez un capteur template dans HA :
YAML Home Assistant (pas ESPHome) — à placer dans votre configuration Home Assistant, pas dans le YAML du nœud.
# 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) }}
Remarque : apparent_power dans le schéma ESPHome n'utilise que le courant CH0. Le modèle ci-dessus est l'approche recommandée pour CH1/CH2 sur les déploiements UI2/UI3.
7 · Lire rbAmp sans ESPHome
Le module rbAmp est un esclave I²C ordinaire. Tout maître I²C peut le lire en suivant le protocole de la référence API du module. Les bibliothèques clientes sœurs (dépôts de distribution — espaces réservés jusqu'à publication) :
| Bibliothèque | Distribution | Langue | Plateforme cible |
|---|---|---|---|
| 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 sous MicroPython |
Toutes les bibliothèques implémentent la même table de registres et le même protocole de comptage par période que le composant ESPHome. Elles peuvent être utilisées séparément ou en parallèle.
Quand NE PAS utiliser ESPHome
- Vous disposez déjà d'un firmware ESP32 non ESPHome et devez ajouter des lectures rbAmp — utilisez la bibliothèque ESP-IDF et appelez l'API directement.
- Le maître est un Raspberry Pi ou un autre SBC Linux — utilisez la bibliothèque Python.
- Vous disposez d'un automate STM32 ou d'une carte personnalisée — STM32 HAL.
- Un prototype rapide sur un Arduino UNO ou Leonardo — la bibliothèque Arduino.
Accumulation d'énergie multiplateforme — une remarque
Le composant ESPHome utilise des accumulateurs double persistés en NVS qui survivent à un redémarrage (sur les modules STANDARD, ils sont en plus alimentés par les compteurs d'énergie du module). Les bibliothèques sœurs peuvent utiliser d'autres mécanismes de persistance — pour les détails et la compatibilité ascendante d'une bibliothèque donnée, voir sa section 10_troubleshooting.md (section persistance de l'énergie). Si vous migrez d'ESPHome vers un firmware bare-metal, prévoyez la migration des données : exportez la dernière valeur de Wh depuis HA avant le changement et initialisez l'accumulateur du nouveau firmware avec elle.
8 · Ponts Tasmota / WLED / OpenHAB
Tasmota
Tasmota n'a pas de pilote natif rbAmp. Le pont le plus propre consiste à utiliser ESPHome comme lecteur rbAmp et Tasmota comme maître I²C distinct pour d'autres appareils, sans les mélanger.
Si vous avez précisément besoin de Tasmota pour rbAmp, utilisez le scripting Berry (Tasmota 12.x+) pour écrire un pilote personnalisé qui effectue les lectures I²C — un octet par phase d'adresse pour les écritures, lecture en rafale facultative pour le bloc de valeurs instantanées (voir 09 · Référence API). La bibliothèque MicroPython de rbamp-python est une référence utile pour les adresses de registres et le décodage des flottants.
WLED
WLED (firmware pour contrôleurs de LED) n'expose pas de maître I²C dans les scripts utilisateur. rbAmp et WLED ne peuvent être des appareils indépendants sur le même bus que s'ils sont sur des segments de bus séparés ou ont des adresses non conflictuelles. Il n'existe pas de pont officiel.
OpenHAB
ESPHome publie les données via MQTT (voir l'exemple 2) ou par l'API native (aioesphomeapi). Le binding MQTT d'OpenHAB peut s'abonner aux topics ESPHome et transmettre les valeurs rbAmp aux règles et Items d'OpenHAB. La configuration du binding MQTT est décrite dans la documentation d'OpenHAB.
Source et signalements : rb-amp/rbamp-esphome · cette page dans le dépôt : docs/07_diy_integrations.md (v1.9.1)