06 · Livre de recettes YAML
Ce chapitre s'ouvre sur les scénarios phares — les schémas de déploiement réels pour lesquels le composant a été conçu en v1.3 (arrivée secteur + N sous-charges sur un bus avec synchronisation fleet_gc_enable, flux de provisionnement, CT mixtes multi-canaux, synchronisation GC de flotte). Viennent ensuite les scénarios mono-module, du UI1 minimal à un déploiement en production avec automatisations HA.
Chaque exemple est autonome : copiez-le, renseignez le nom de votre carte et vos identifiants Wi-Fi, compilez et flashez. Chaque fois qu'un exemple s'écarte du modèle minimal, une explication vous indique pourquoi.
Cross-references:
- Schéma du composant, carte des registres, protocole de comptage par période, topologie multi-modules, synchronisation GC de flotte et règle de tolérance NACK : 09 · Référence API
| # | Scénario | Topologie | Quand l'utiliser |
|---|---|---|---|
| 1 | Secteur + N sous-charges : le canon des 80 % | UI1 + N× I2/I3 | Mesure de l'ensemble du logement avec ventilation par sous-branches |
| 2 | Flux de provisionnement (vierge → parc) | séquentiel unique | Mise en service d'un nouveau lot de modules |
| 3 | CT mixtes multi-canaux (UI3 avec des pinces différentes) | UI3 | Mesure de charges mixtes avec optimisation de précision |
| 4 | Synchronisation de flotte GC (synchronie serrée) | N× UI/I | Grappes multi-locataires et sous-comptage |
| 5 | UI1 — canal unique (minimal) | UI1 | Hello-world monomodule |
| 6 | UI1 avec personnalisation | UI1 | Tous les réglages ESPHome standard |
| 7 | UI3 — trois canaux avec pinces mixtes | UI3 | Multi-canaux sur un seul module |
| 8 | Bus multi-modules (synchronisation GC) | N× UI/I | fleet_gc_enable + group_id sur trois modules |
| 9 | Changement d'adresse I²C unique | single | Provisionnement d'un module unique |
| 10..20 | Intégrations et automatisations HA | mixte | Schémas de déploiement en production |
| 21 | Module STANDARD (STD) — totaux d'énergie embarqués | tout | Totaux généraux, énergie réactive, start_current_ua: |
| 22 | Changement du calibre SCT, ct_model_force |
tout | Changement de calibre sans perte de précision |
Les scénarios 1-4 sont les vitrines, ciblant le déploiement canonique v1.3 du paquet. Leur code utilise fleet_gc_enable + la surface d'identité + la lecture-comparaison-écriture, et est exercé sur une configuration hétérogène UI1+I2+I3. Les scénarios 5-22 sont des motifs monomodules et compacts. Le scénario 8 est la courte configuration de bus à trois modules.
1 · Arrivée secteur + N sous-charges (le canon des 80 %) — système de comptage intégré
Objectif : le déploiement canonique du paquet — un système de mesure cohérent sur une flotte hétérogène, bouclé dans un seul démarrage ESPHome (découverte → configuration → activation GC → boucle [publish_state + tick GC auto-émis]).
Matériel (banc de test UI1 + I2 + I3) : UI1@0x50 + I2@0x51 + I3@0x52 ; charge ~0.58 A ; tirages selon la ligne « 3 modules » du tableau de 04_hardware.md (coupez tout, une paire externe de 2.7–3.3 kΩ).
esphome:
name: home-fleet
esp32:
board: esp32dev
framework:
type: arduino
logger:
level: INFO
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
api:
ota:
- platform: esphome
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz
scan: true
external_components:
- source:
type: local
path: ../components
components: [rbamp]
# Three rbAmp modules on shared bus, all with fleet_gc_enable + group_id=1
# for synchronized period snapshots (tight sync between mains + sub-meters).
rbamp:
- id: mains_meter # UI1 on the mains feed
address: 0x50
sensor_class: SCT_013
ct_model: SCT_013_030
fleet_gc_enable: true
group_id: 1
- id: boiler_meter # I2 on the boiler + washing machine
address: 0x51
sensor_class: SCT_013
ct_models: [SCT_013_020, SCT_013_010]
fleet_gc_enable: true
group_id: 1
- id: panel_meter # I3 on the distribution-panel branches
address: 0x52
sensor_class: SCT_013
ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
fleet_gc_enable: true
group_id: 1
sensor:
- platform: rbamp
rbamp_id: mains_meter
voltage: { name: "Mains Voltage" }
current: { name: "Mains Current" }
power: { name: "Mains Power", id: mains_power_state }
power_factor: { name: "Mains PF" }
energy: { name: "Mains Energy" }
frequency: { name: "Mains Frequency" }
- platform: rbamp
rbamp_id: boiler_meter
# I2 is a current-only module: it has no voltage input, so it reports currents only
# (power and energy need a UI module with voltage).
current: { name: "Boiler Current" } # 20A CT
current_1: { name: "Washer Current" } # 10A CT
- platform: rbamp
rbamp_id: panel_meter
current: { name: "Lighting Current" } # 5A CT
current_1: { name: "Appliances Current" } # 30A CT
current_2: { name: "Sub-panel Current" } # 20A CT
# Optional: template sensor for the household power (same sensor: list, not a second sensor: key)
- platform: template
name: "Household Total Power"
update_interval: 60s
accuracy_decimals: 0
unit_of_measurement: "W"
device_class: power
lambda: |-
// Sum of power from the mains meter only (sub-meters are a subset of the same mains)
auto v = id(mains_power_state);
return v.has_state() ? v.state : 0.0f;
Exemple de sortie (charge ~0.58 A)
[I][i2c:136]: Found i2c device at address 0x50
[I][i2c:136]: Found i2c device at address 0x51
[I][i2c:136]: Found i2c device at address 0x52
[C][rbamp:450]: mains_meter: variant=UI1, capability=0x…, fleet_gc=on, group=1
[C][rbamp:450]: boiler_meter: variant=I2, capability=0x…, fleet_gc=on, group=1
[C][rbamp:450]: panel_meter: variant=I3, capability=0x…, fleet_gc=on, group=1
[I][rbamp:493]: GC latch enabled fleet-wide: 3 modules in group 1
ITER 1 @ 60s: GC tick=1, 3/3 in_sync
mains: V=232.6 I=5.79 P=1259 W E_total: 0 → 0.35 Wh
boiler: I=[11.58, 3.87] ; current-only
panel: I=[3.84, 2.55, 5.84] ; current-only
Remarques d'utilisation
-
Une seule boucle synchronisée — tout le système. À chaque tick
update_interval, l'ESP32 émet une trame GC vers 0x00 → les 3 modules prennent un instantané de leurs accumulateurs de période au même instant sur le fil (validé 3/3 in_sync sous charge). -
mains_powerdans une flotte hétérogène = la puissance active de UI1 (mains_meter). Les sous-compteurs (I2/I3) ne mesurent que le courant, sans P canonique. Dans le canon 80 %,mains_power≈ la puissance totale de toutes les charges (mains_meter couvre l'alimentation). -
Les Wh sur les modules BASIC sont intégrés sur l'ESP32 par rapport à sa propre horloge (le temps entre instantanés), donc tous les modules de la flotte partagent une même base de temps. Les modules STANDARD conservent leurs propres compteurs d'énergie, que le composant accumule.
-
Tolérant aux pannes (MISS). Si un module sort du bus (provisionnement / coupure d'alimentation), les autres continuent de fonctionner ; HA affiche « Unavailable » pour ses entités jusqu'à son rétablissement.
2 · Flux de provisionnement (vierge → flotte)
Objectif : la procédure de mise en service canonique des nouveaux modules, de l'adresse d'usine 0x50 aux adresses de flotte uniques. Elle démontre la validation d'adresse en deux phases (v1.3, prête pour la production) et la discipline requise « un seul vierge sur le bus à la fois ».
Étape 2.1 — provisionner UI1 secteur (0x50 → 0x50, sensor_class + ct_model)
# Connect ONLY the UI1 to the bus. Flash this YAML.
rbamp:
- id: provisioning_target
address: 0x50
# new_address not needed — 0x50 is already fine for UI1
sensor_class: SCT_013
ct_model: SCT_013_030
fleet_gc_enable: true
group_id: 1
sensor:
- platform: rbamp
rbamp_id: provisioning_target
voltage: { name: "Provision UI1 Voltage" }
current: { name: "Provision UI1 Current" }
text_sensor:
- platform: template
name: "Provision UI1 variant"
update_interval: 5s
lambda: 'return id(provisioning_target).get_variant_str();'
- platform: template
name: "Provision UI1 UID"
update_interval: 5s
lambda: 'return id(provisioning_target).get_uid_hex();'
- platform: template
name: "Provision UI1 capability"
update_interval: 5s
lambda: 'return id(provisioning_target).get_capability_hex();'
Vérification : dans HA, vous devez voir sensor.provision_ui1_variant == "UI1" + sensor.provision_ui1_capability affichant une matrice de bits hexadécimale non nulle ("0x0000" signifie firmware ancien). Notez l'UID pour le suivi d'inventaire.
Étape 2.2 — provisionner I2 (0x50 → 0x51 via validation en deux phases)
Débranchez le UI1 du bus (sinon il y aura un conflit d'adresse). Connectez le module I2. Flashez le YAML mis à jour :
rbamp:
- id: provisioning_target
address: 0x50 # virgin address
new_address: 0x51 # ⚠ two-phase commit — production-OK on v1.3
sensor_class: SCT_013
ct_models: [SCT_013_020, SCT_013_010]
fleet_gc_enable: true
group_id: 1
Ce qui se passe au démarrage :
[I][rbamp:xxx]: provisioning_target: probe at 0x50 → OK (variant=I2)
[I][rbamp:xxx]: provisioning_target: new_address=0x51 requested
[I][rbamp:xxx]: provisioning_target: two-phase address change supported → production path
[D][rbamp:xxx]: provisioning_target: stage REG_I2C_ADDRESS=0x51
[D][rbamp:xxx]: provisioning_target: write REG_ADDR_COMMIT_MAGIC=0xA5
[D][rbamp:xxx]: provisioning_target: send CMD_COMMIT_ADDR → wait 700ms
[I][rbamp:xxx]: provisioning_target: re-probe 0x51 → OK, re-enumeration complete
[I][rbamp:xxx]: provisioning_target: i2c address handle updated to 0x51
Après succès : mettez à jour le YAML en address: 0x51 et retirez new_address:. Le prochain démarrage n'exécutera pas la procédure de changement.
Étape 2.3 — provisionner I3 (0x50 → 0x52) + répéter pour le reste
Même motif que 2.2 : déconnectez l'I2, connectez l'I3 vierge, flashez le YAML avec new_address: 0x52, attendez la réénumération, puis mettez à jour le YAML sur address: 0x52.
🛑 IMPÉRATIF : un seul module vierge sur le bus à la fois. Si deux modules vierges sont tous deux sur 0x50, les deux répondront pendant la phase d'adresse et tireront SDA l'un contre l'autre → état indéterminé, et aucune procédure de provisionnement ne fonctionnera.
Étape 2.4 — assembler la flotte
Une fois le provisionnement de tous les modules terminé, mettez à jour le YAML vers la configuration de flotte finale (voir le scénario §1 ci-dessus), désactivez les tirages internes sur tous les modules (3 modules = tout couper) et ajoutez une paire externe de 2.7–3.3 kΩ sur l'ESP32 — voir le tableau des tirages dans 04_hardware.md. Flashez le YAML final — tous les modules doivent être découverts :
[D][i2c:136]: Found i2c device at address 0x50
[D][i2c:136]: Found i2c device at address 0x51
[D][i2c:136]: Found i2c device at address 0x52
Modes de défaillance (provisionnement)
| Symptôme | Cause | Récupération |
|---|---|---|
Probe failed at 0x50 après le flash |
Module non alimenté ou contact défectueux | Vérifiez la connectivité VCC + GND + SDA + SCL |
[W] changement d'adresse en deux phases non pris en charge |
Module sur firmware hérité (v1.0-v1.2) | Le repli monophasé requiert le mode provisionnement en usine (voir 04_hardware.md) |
[E] address change committed but re-probe at 0x51 failed |
Bus marginal ou commit interrompu | Relancez le démarrage ; si cela se répète, la résistance de tirage externe est trop faible ou il y a une rafale d'EMI |
[W] WARN_FACTORY_MODE_REQUIRED |
Firmware hérité sans changement d'adresse en deux phases | Le fournisseur active le mode usine (hors du périmètre de la bibliothèque) |
3 · Mixte multi-canaux (UI3 avec des pinces différentes)
Objectif : montrer que le modèle de pince CT sur différents canaux d'un même module peut être mixé selon la caractéristique de charge. Le composant lie les canaux un par un ; l'ordre n'a pas d'importance.
rbamp:
- id: panel_meter
address: 0x52
sensor_class: SCT_013
# Mixed-CT: small/medium/large on channels 0/1/2
ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
# The component binds channels one by one; the order does not matter.
# Each channel keeps its own model: ch0 = 5 A, ch1 = 30 A, ch2 = 20 A
fleet_gc_enable: true
group_id: 1
sensor:
- platform: rbamp
rbamp_id: panel_meter
current: { name: "Panel Lighting (5A CT)" } # ch0
current_1: { name: "Panel Appliances (30A CT)" } # ch1
current_2: { name: "Panel Boiler (20A CT)" } # ch2
# No voltage / power — this is an I3 SKU, current-only
text_sensor:
- platform: template
name: "Panel last error"
update_interval: 30s
lambda: 'return id(panel_meter).get_last_error_str();'
# → "OK" in a healthy state; "ERR_PARAM" if a CT model code is rejected
Vérifier la liaison de la pince au démarrage
Après le flash et le démarrage, dans le journal :
[D][rbamp:xxx]: panel_meter: REG_CT_MODEL_CH0 mirror = 1 (SCT_013_005)
[D][rbamp:xxx]: panel_meter: REG_CT_MODEL_CH1 mirror = 3 (SCT_013_030)
[D][rbamp:xxx]: panel_meter: REG_CT_MODEL_CH2 mirror = 6 (SCT_013_020)
[I][rbamp:xxx]: panel_meter: CT binding verified, all mirrors match YAML request
[C][component:246]: Setup panel_meter took ~2100ms (cold install: 3 × 700ms flash + verify)
Lors d'un démarrage à chaud (les miroirs correspondent), sans écriture flash :
[I][rbamp:xxx]: panel_meter: CT_MODEL[0..2] match YAML → SKIP flash erase
[C][component:246]: Setup panel_meter took 72ms (warm boot: read-compare only)
Comportement observé
- Liaison de pince mixte : codes [1, 3, 6] sur un module à trois canaux à 0x52 — chacun est conservé sur son propre canal.
-
Rejet de code invalide : une tentative avec un code hors de l'ensemble accepté par la classe →
esphome configrejette le schéma (cv.Invalid). Si le YAML passe malgré le validateur (édition manuelle / build ancien), le firmware renvoieREG_ERROR = 0xFE DEV_ERR_PARAM, le miroir restant à sa valeur précédente. -
Durée d'une installation à froid : ~2.1 s sur l'UI3 (3 × ~700 ms d'effacement flash).
- Durée du démarrage à chaud : ~70 ms (la lecture-comparaison-écriture saute tout l'effacement flash).
- Mesure de latence : ~1.4 s entre le début de
setup()et la première publication (banc d'essai).
4 · Synchronisation de flotte GC (synchronie serrée)
Objectif : montrer que la synchronisation de flotte 3/3 n'est pas théorique mais une exigence réelle pour les déploiements multi-locataires (sous-comptage d'appartements sur un tableau partagé) et pour un sous-comptage précis (le secteur UI1 doit égaler la somme des puissances des sous-compteurs à la durée d'une seule période près).
# Fleet config — all modules in one group for synchronized snapshots:
rbamp:
- id: tenant1_mains
address: 0x50
sensor_class: SCT_013
ct_model: SCT_013_030
fleet_gc_enable: true
group_id: 1
- id: tenant1_panel
address: 0x51
sensor_class: SCT_013
ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
fleet_gc_enable: true
group_id: 1
- id: tenant2_mains # Independent tenant (separate group)
address: 0x52
sensor_class: SCT_013
ct_model: SCT_013_030
fleet_gc_enable: true
group_id: 2 # ⚠ different group → independent sync timeline
# Native API services for manual sync verification:
api:
port: 6053
services:
- service: emit_gc_tenant1
then:
- lambda: 'id(tenant1_mains).transmit_gc_frame();' # group = tenant1_mains group_id
- service: emit_gc_tenant2
then:
- lambda: 'id(tenant2_mains).transmit_gc_frame();' # group = tenant2_mains group_id
- service: check_sync_all
then:
- lambda: |-
uint16_t t1m = id(tenant1_mains).read_gc_tick_received();
uint16_t t1p = id(tenant1_panel).read_gc_tick_received();
uint16_t t2m = id(tenant2_mains).read_gc_tick_received();
ESP_LOGI("rbamp", "GC tick state: tenant1[mains=%u, panel=%u] tenant2[mains=%u]",
t1m, t1p, t2m);
text_sensor:
- platform: template
name: "Tenant1 GC tick (mains)"
update_interval: 30s
lambda: 'return std::to_string(id(tenant1_mains).read_gc_tick_received());'
- platform: template
name: "Tenant1 GC tick (panel)"
update_interval: 30s
lambda: 'return std::to_string(id(tenant1_panel).read_gc_tick_received());'
Exemple de sortie (test de synchronisation sur 10 itérations)
[I][rbamp:572]: GC frame emit: group=1, tick=42, all 2 tenant1 modules ACK'd
[I][rbamp:580]: check_sync: tenant1_mains.tick=42 tenant1_panel.tick=42 → 2/2 in_sync
[I][rbamp:572]: GC frame emit: group=2, tick=42, tenant2 module ACK'd
[I][rbamp:580]: check_sync: tenant2_mains.tick=42 → 1/1 in_sync (tenant2 isolated)
ROUND 0: GC tick=1 → tenant1[1, 1] tenant2[1] → 3/3 in_sync
ROUND 1: GC tick=2 → tenant1[2, 2] tenant2[2] → 3/3 in_sync
ROUND 2: GC tick=3 → tenant1[3, 3] tenant2[3] → 3/3 in_sync
...
ROUND 9: GC tick=10 → tenant1[10,10] tenant2[10] → 3/3 in_sync
L8 soak: 180 cycles, 0 sync drops, 0 identity drops
Comment group_id aide en multi-locataires
Sans group_id, il n'y a pas de séparation des locataires — tous les modules réagissent à toute trame GC. Avec group_id :
- Les modules du locataire 1 ne répondent qu'aux trames GC avec
group=1(ou l'appel généralgroup=0) - Les modules du locataire 2 ne répondent qu'aux trames GC avec
group=2
Cela permet au maître d'émettre des trames GC distinctes pour les locataires à des instants indépendants — par exemple, par période de locataire :
YAML Home Assistant (pas ESPHome) — à placer dans votre configuration Home Assistant, pas dans le YAML du nœud.
automation:
- alias: "Tenant 1 period snapshot"
trigger:
platform: time_pattern
seconds: "/60" # every 60 s
action:
- service: esphome._emit_gc_tenant1
- alias: "Tenant 2 period snapshot"
trigger:
platform: time_pattern
seconds: "/15" # every 15 s (high-resolution tenant)
action:
- service: esphome._emit_gc_tenant2
Validation en production
- Capteur template HA« mains_minus_subsum » — un indicateur d'écart :YAML
sensor: - platform: template name: "Mains - SubSum (W)" update_interval: 60s unit_of_measurement: "W" lambda: |- // here the sub-meters are current-only, so this is a rough estimate: // mains_power - sum(sub_currents × V_mains) float v_mains = id(mains_voltage_state).state; float sub_i = id(sub_i0).state + id(sub_i1).state + id(sub_i2).state; return id(mains_power_state).state - sub_i * v_mains;
Un écart inférieur à 1 % de mains_power sur le banc = synchronisation correcte.
- Intégration sur horloge murale — même avec la synchronisation GC 3/3, les modules BASIC sont intégrés selon l'horloge propre de l'ESP32, donc un léger décalage entre modules ne fausse pas les Wh.
5 · UI1 — un seul canal (minimal)
Source : ../example/ui1.yaml
La configuration utile la plus simple : un canal de tension, un canal de courant, et six grandeurs dérivées de ceux-ci. Un point de départ pour tout nouveau déploiement — ajoutez-y d'autres champs au besoin.
esphome:
name: rbamp-ui1
esp32:
board: esp32dev
framework:
type: arduino
logger:
level: DEBUG
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
ap:
ssid: "rbAmp UI1 Fallback"
password: !secret ap_password
captive_portal:
api:
ota:
- platform: esphome
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz # recommended on ESP32; 100 kHz causes periodic NACKs due to ESP-IDF i2c_master driver interaction;
# 50 kHz reduces them ~5-10× — see the chapter end link.
scan: true
external_components:
- source:
type: local
path: ../components
components: [rbamp]
rbamp:
id: meter1
address: 0x50
update_interval: 60s
ct_model: SCT_013_030 # CT clamp model — change it to match yours
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"
Ce qu'il démontre : la configuration minimale viable. Les six capteurs couvrent le cas de base — comptage de toute la maison ou d'une seule charge. Le capteur energy a déjà device_class: energy + state_class: total_increasing définis, il va donc directement dans le tableau de bord Énergie de HA sans configuration supplémentaire. Le protocole de comptage par période (instantané / temporisation de 50 ms / lecture de la puissance moyenne, intégrée sur l'horloge maître) est documenté dans 09 · Référence API.
6 · UI1 avec personnalisation — tous les réglages ESPHome standard
rbAmp est un composant ESPHome « bien élevé ». Chaque emplacement (voltage, current, power, …) est un objet sensor: ESPHome ordinaire. L'ensemble standard des propriétés et des filtres s'y applique. Vous n'avez besoin ni de lambda:, ni de modèles personnalisés — tout ce que vous faites avec pzemac / atm90e32 / cse7766 fonctionne ici exactement de la même façon. L'exemple montre les personnalisations les plus courantes dans un seul bloc :
esphome:
name: rbamp-ui1-tuned
esp32:
board: esp32dev
framework:
type: arduino
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
api:
ota:
- platform: esphome
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: 10s # ↑ Poll once / 10 s instead of the default 60 s —
# a denser graph, ~6× the I²C traffic.
ct_model: SCT_013_030
sensor:
- platform: rbamp
rbamp_id: meter1
# ──────────── Customizing names + precision + filters ────────────
voltage:
name: "Mains voltage" # Any name — it becomes the HA entity_id
accuracy_decimals: 1 # 226.7 instead of the default 226.70
filters:
# Linear calibration against a reference multimeter:
- calibrate_linear:
- 0.0 -> 0.0
- 230.0 -> 230.5
# Smoothing of sharp spikes (standard ESPHome):
- exponential_moving_average:
alpha: 0.3
send_every: 1
current:
name: "Load current"
accuracy_decimals: 3 # 0.755 instead of 0.75
filters:
# Mask the noise floor — drop values below 50 mA (50 mW at 230 V).
# The equivalent of the `noise_floor` option in pzemac / cse7766.
- lambda: 'return x < 0.05 ? 0.0f : x;'
power:
name: "Power"
accuracy_decimals: 1
filters:
# Throttle publications: no more than once / 30 s, even with update_interval 10 s.
- throttle: 30s
energy:
name: "Energy (Wh)"
# The standard device_class: energy + state_class: total_increasing
# are already set by the component — the Energy dashboard works.
filters:
# Convert Wh → kWh for a more familiar scale in Lovelace.
# (The HA Energy dashboard itself expects Wh, but if you want a graph in kWh,
# declare a second template sensor with a division rather than changing units here.)
- multiply: 0.001
unit_of_measurement: "kWh" # ← overrides the default "Wh"
accuracy_decimals: 3
frequency:
name: "Mains frequency"
accuracy_decimals: 2
power_factor:
name: "Power factor"
accuracy_decimals: 3
# Optional: a filter to hide PF at zero load (P ~ 0)
filters:
- lambda: 'return isnan(x) ? 0.0f : x;'
Ce que cela démontre :
-
Noms personnalisés (
name:) deviennent leentity_idde HA — par exemplesensor.rbamp_ui1_tuned_mains_voltage. Les noms dans toutes les langues, y compris le cyrillique, fonctionnent. -
Précision de sortie (
accuracy_decimals:) est indépendante du module ; le module renvoie un float32 à précision maximale, et ESPHome le tronque pour l'interface. -
update_interval:n'a pas besoin d'être modifié par capteur — c'est une propriété du composant (PollingComponent), réglée une fois dans le blocrbamp:. Si vous voulez publier certains capteurs moins souvent, ajoutezfilters: - throttle:. -
filters:— l'ensemble complet ESPHome : -
calibrate_linear— calibrage ponctuel par rapport à votre référence (multimètre, ampèremètre de référence). -
exponential_moving_average/sliding_window_moving_average— lissage. lambda— une transformation arbitraire (masque de bruit de fond, zéro conditionnel).multiply/offset— arithmétique (par exemple Wh → kWh).throttle/delta— réduction du rythme de publication.-
unit_of_measurement:peut être remplacé (par exemple parkWhavecmultiply: 0.001). HA prend automatiquement la nouvelle unité en compte. -
Aucun
lambda:pour le fonctionnement de base — tous les calculs RMS, puissance, fréquence et PF sont effectués par le module. L'ESP32 ne fait que renommer, formater et filtrer.
⚠ Ne surchargez pas device_class: pour energy — le tableau de bord Énergie de HA exige strictement device_class: energy + state_class: total_increasing. La conversion d'unités via multiply + unit_of_measurement: reste compatible, mais modifier le device_class casse le tableau de bord.
La liste complète des propriétés et filtres standard des capteurs se trouve dans la documentation officielle du Sensor Component d'ESPHome. Cette documentation est entièrement applicable aux emplacements rbAmp — il n'y a aucune dérogation au standard.
7 · UI3 — trois canaux avec pinces mixtes
Source : ../example/ui3.yaml
La référence UI3 possède une entrée de tension et trois canaux de courant indépendants. Le scénario de référence consiste à placer des modèles de pince différents sur des canaux différents : une petite pince sur les consommateurs à faible courant (pour une résolution maximale) et une grande sur l'alimentation principale (pour la marge sur les pointes).
esphome:
name: rbamp-ui3
esp32:
board: esp32dev
framework:
type: arduino
logger:
level: DEBUG
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
api:
ota:
- platform: esphome
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
# drdy_pin: GPIO15
ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
# CH0=5A for standby consumers and LED lighting,
# CH1=30A for the main household loads,
# CH2=20A for the boiler / a medium-power branch (~3-5 kW)
# For currents above 50 A use SCT_013_060 (60 A) or SCT_013_100 (100 A).
sensor:
- platform: rbamp
rbamp_id: meter1
# Common (topology-independent)
voltage:
name: "Mains Voltage"
frequency:
name: "Mains Frequency"
apparent_power:
name: "CH0 Apparent Power"
# Channel 0 — primary current input (small consumers, 5A)
current:
name: "CH0 Current"
power:
name: "CH0 Power"
energy:
name: "CH0 Energy"
power_factor:
name: "CH0 Power Factor"
reactive_power:
name: "CH0 Reactive Power"
# Channel 1 — main loads (30A)
current_1:
name: "CH1 Current"
power_1:
name: "CH1 Power"
energy_1:
name: "CH1 Energy"
power_factor_1:
name: "CH1 Power Factor"
reactive_power_1:
name: "CH1 Reactive Power"
# Channel 2 — boiler / medium-power branch (20A)
current_2:
name: "CH2 Current"
power_2:
name: "CH2 Power"
energy_2:
name: "CH2 Energy"
power_factor_2:
name: "CH2 Power Factor"
reactive_power_2:
name: "CH2 Reactive Power"
Ce que cela démontre : les trois canaux de la référence UI3 + des modèles de pince mixtes via ct_models:. Le validateur de schéma vérifie que power_N et energy_N (ainsi que power_factor_N, reactive_power_N) requièrent current_N et voltage — si vous déclarez power_1 sans current_1, la compilation échoue avec un message clair. Chaque canal a son propre accumulateur energy_* persisté en NVS. Si tous les canaux utilisent le même modèle de pince, utilisez le ct_model: global au lieu de ct_models:.
8 · Bus multi-modules (trois rbAmp aux adresses 0x50 / 0x51 / 0x52)
Source : ../example/multi_module.yaml
Trois modules sur un même bus I²C — l'alimentation principale du logement, la sortie de production solaire et la recharge VE. Chacun a son propre bloc rbamp: (dans le schéma du composant, MULTI_CONF = True).
esphome:
name: rbamp-multi
esp32:
board: esp32dev
framework:
type: arduino
logger:
level: INFO
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
api:
ota:
- platform: esphome
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz # recommended: at 100 kHz the ESP-IDF i2c_master driver interaction causes periodic
# NACKs are almost inevitable on every cycle
scan: true
external_components:
- source:
type: local
path: ../components
components: [rbamp]
# Three independent rbamp: blocks — MULTI_CONF = True in the schema.
# On v1.3 firmware the general-call snapshot is opt-in via fleet_gc_enable +
# group_id (capability-gated on the firmware side). Modules in the same
# group snapshot in a single transaction, with ~540 µs skew per module. On legacy
# firmware (v1.0..v1.2) the component falls back to a sequential snapshot
# and logs an informational line. (The old broadcast_latch: key is still
# accepted by the schema but has no effect.)
rbamp:
- id: meter_house
address: 0x50
update_interval: 60s
fleet_gc_enable: true
group_id: 1
- id: meter_solar
address: 0x51
update_interval: 60s
fleet_gc_enable: true
group_id: 1
bidirectional: true # needed for energy_exported_*; on BASIC it
# publishes 0, on STANDARD it is real export energy
- id: meter_evcharger
address: 0x52
update_interval: 60s
fleet_gc_enable: true
group_id: 1
sensor:
- platform: rbamp
rbamp_id: meter_house
voltage:
name: "House Voltage"
current:
name: "House Current"
power:
name: "House Power"
energy:
name: "House Energy"
frequency:
name: "Mains Frequency"
- platform: rbamp
rbamp_id: meter_solar
voltage:
name: "Solar Voltage"
internal: true # hidden from HA — the same mains as House Voltage
current:
name: "Solar Current"
power:
name: "Solar Power"
energy:
name: "Solar Energy"
energy_exported:
name: "Solar Energy Exported"
- platform: rbamp
rbamp_id: meter_evcharger
voltage:
name: "EV Charger Voltage"
internal: true
current:
name: "EV Charger Current"
power:
name: "EV Charger Power"
energy:
name: "EV Charger Energy"
Ce qu'il démontre : le motif MULTI_CONF = True — déclarez autant de blocs rbamp: que de modules sur le bus. Chacun gère son propre accumulateur NVS, dont la clé est dérivée de l'adresse I²C, de sorte que les trois compteurs restent indépendants d'un redémarrage à l'autre. Le drapeau internal: true sur les capteurs de tension en double masque dans HA les trois entités de tension secteur presque identiques lorsque tous les modules mesurent la même phase. Pour la procédure d'attribution d'adresse, voir l'exemple 2 ci-dessous.
Sémantique de internal: true. Le drapeau ne désactive pas la lecture du registre depuis le module — le composant lit toujours la tension de chaque module à chaque update_interval (c'est nécessaire au calcul de puissance). Le drapeau masque seulement le capteur de l'API Home Assistant : aucune entité n'est créée, il n'apparaît pas dans Lovelace et n'est pas compté dans le tableau de bord Énergie. Si vous voulez réduire le trafic I²C, ne déclarez pas du tout l'emplacement voltage: sous sensor.platform: rbamp — le composant n'interroge alors pas le registre. Si vous le déclarez, le drapeau internal: est purement cosmétique.
Une seconde contrainte concerne l'unicité des adresses sur le bus :
⚠ L'unicité des adresses relève de la configuration. Le schéma du composant (MULTI_CONF = True) ne vérifie pas le chevauchement des valeurs address: entre les blocs rbamp:. Si deux blocs indiquent la même address: 0x50, les deux déclarations sont acceptées, et sur le bus les deux cibles répondront en même temps — attendez-vous à des conflits I²C, des réponses brouillées ou des symptômes ressemblant à un module absent. Avant de valider le YAML, vérifiez que toutes les valeurs address: sont uniques (et qu'elles n'entrent pas en collision avec d'autres appareils I²C du bus). Après chaque attribution new_address:, mettez à jour la section rbamp: à la nouvelle adresse — l'ancienne entrée n'est pas invalidée automatiquement.
Tirages sur un bus multi-modules
Les trois modules sont livrés avec des tirages d'usine de 4.7 kΩ. Sur un bus de trois modules, la combinaison parallèle vaut ~1.6 kΩ — consommation de courant plus élevée et intégrité du signal marginale à 50 kHz. Coupez les straps de tirage sur les trois modules et placez une paire externe de 2.7–3.3 kΩ à côté de l'ESP32 (la ligne 3 modules du tableau de 04_hardware.md).
Avancé : cadence d'instantané découplée pour les flottes multi-modules (v1.4+)
Les installations multi-modules paient le coût du cycle d'instantané par module et par cycle : sur un bus de 3 modules interrogé à update_interval: 10s, cela fait 3× l'écriture de l'instantané + 3× la fenêtre de stabilisation de 50 ms toutes les 10 s — plus les lectures du bloc RT en plus. Sur les hôtes ESP8266 (mono-cœur ; les ISR WiFi se disputent le CPU pendant les transactions I²C) ou les bus I²C partagés avec d'autres appareils, ce surcoût devient visible sous forme de glitches WiFi ou de relevés figés sur des entités non-rbAmp.
latch_interval: (disponible depuis la v1.4, modules BASIC) découple les deux cadences : les lectures du bloc RT (V/I/P/PF/Q) restent à update_interval: — le lecteur voit toujours des valeurs fraîches sur le tableau de bord — tandis que l'intégration instantané → Wh ne tourne qu'à chaque latch_interval:. L'intégration utilise le temps réel réel écoulé entre les événements d'instantané, donc un intervalle d'instantané de 60 s produit simplement des pas d'intégration de 60 s de large (et toujours justes). latch_interval doit être ≥ update_interval.
rbamp:
- id: mod_mains
address: 0x50
update_interval: 10s # dashboard: fresh V/I/P/PF every 10 s
latch_interval: 60s # bus: snapshot + Wh integration once a minute
ct_models: [SCT_013_050, SCT_013_030, SCT_013_030]
fleet_gc_enable: true
group_id: 1
- id: mod_branches
address: 0x51
update_interval: 10s
latch_interval: 60s
ct_models: [SCT_013_005, SCT_013_030, SCT_013_050]
fleet_gc_enable: true
group_id: 1
Réduction de charge du bus par rapport à la même flotte sans latch_interval: : pour update_interval: 10s, chaque module apporte ~15 ms de lecture RT + ~65 ms d'instantané et de stabilisation par cycle → ~80 ms par module et par cycle. Avec latch_interval: 60s, l'instantané et la stabilisation ne se déclenchent qu'une fois par minute → les lectures RT restent peu coûteuses toutes les 10 s, plus une courte rafale d'instantané toutes les 60 s, soit environ 3× moins d'occupation moyenne du bus. Les grandes flottes réalisent des économies proportionnellement plus importantes.
Quand omettre latch_interval: : déploiements mono-module sur des hôtes ESP32 où le coût de base n'est pas gênant — la cadence unique par défaut de la v1.3 est plus simple et tout aussi juste.
9 · Changement d'adresse I²C unique (0x50 → 0x51)
Source : ../example/address_change.yaml
Tous les modules rbAmp sortent d'usine à l'adresse 0x50. Pour placer plusieurs modules sur un même bus, vous devez reflasher chacun avec sa propre adresse unique avant de les connecter en parallèle.
esphome:
name: rbamp-addr-change
esp32:
board: esp32dev
framework:
type: arduino
logger:
level: DEBUG # DEBUG shows the address-change lines
api:
ota:
- platform: esphome
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz
scan: true
external_components:
- source:
type: local
path: ../components
components: [rbamp]
rbamp:
id: meter1
address: 0x50 # current address — before the change
new_address: 0x51 # one-time target — DELETE this line after success
sensor:
- platform: rbamp
rbamp_id: meter1
voltage:
name: "rbAmp Voltage (post-relocate)"
current:
name: "rbAmp Current (post-relocate)"
Ce qu'il démontre : le flux de changement d'adresse unique. Flasher ce YAML fait exécuter la procédure une seule fois au démarrage par le composant :
-
Sondez
0x50. Si0x50est silencieux et que0x51répond déjà, le changement a été appliqué lors d'un démarrage précédent ; le composant s'adapte et journalise un avertissement vous demandant de nettoyer le YAML. -
Vérifiez que le module est prêt à accepter une opération de provisionnement.
-
Écrire la nouvelle adresse en flash (~700 ms), une réinitialisation logicielle (~300 ms), et reverrouiller sur le cycle secteur.
-
Confirmez à la nouvelle adresse. En cas de succès — le journal
Address change confirmed at 0x51etIMPORTANT: update YAML to address: 0x51 and remove new_address:.
Compatibilité firmware : sur le firmware v1.3+, le changement d'adresse est prêt pour la production — le composant utilise le protocole de validation en deux phases (préparer → armer → valider → redémarrer) sans mode spécial. Sur le firmware historique (v1.0-v1.2), le repli monophasé exige le mode provisionnement en usine ; consultez la documentation du module ou votre fournisseur pour la procédure d'activation temporaire.
Après succès : modifiez le YAML en address: 0x51 et retirez la ligne new_address: 0x51. Reflashez. À partir du prochain démarrage, le composant utilise 0x51 normalement et la procédure de changement ne s'exécute plus.
Liste de contrôle de retour arrière après un provisionnement réussi
Pour ne pas laisser de variante de provisionnement « pendante » dans le dépôt (deux alternatives, ne jamais en coller les deux dans un même fichier) :
# BEFORE (provisioning):
rbamp:
id: meter1
address: 0x50 # the module's current address
new_address: 0x51 # the provisioning target
update_interval: 60s
# AFTER (production — applied next flash):
rbamp:
id: meter1
address: 0x51 # ← replaced with the new address
# new_address: 0x51 # ← DELETE the line (do not comment it out)
update_interval: 60s
Exactement trois modifications :
- Remplacez la valeur de
address:par la nouvelle. - Supprimez (ne commentez pas) la ligne
new_address:. - Reflashez par OTA ou par USB.
Après l'étape 3, le journal doit afficher une ligne dump_config normale, sans l'avertissement address change requested but current address matches new_address — ce qui signifie que la restauration était correcte. Voir aussi 10_troubleshooting §4 « OTA juste après le provisionnement new_address: ne se charge pas » si la première OTA après la restauration ne démarre pas.
10 · Configuration de banc avec secrets
Source : ../example/bench-ui1.yaml
Le motif bench-*.yaml sert aux postes de développement où les identifiants Wi-Fi doivent figurer dans la configuration sans finir dans un commit. example/.gitignore exclut bench-*.yaml et secrets.yaml du contrôle de version.
esphome:
name: rbamp-ui1
esp32:
board: esp32dev
framework:
type: arduino
logger:
level: DEBUG
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
ap:
ssid: "rbAmp UI1 Fallback"
password: !secret ap_password
captive_portal:
api:
ota:
- platform: esphome
web_server:
port: 80
version: 3 # optional: a local HTTP UI — handy for bench testing
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"
Le fichier secrets.yaml correspondant (dans example/, non suivi) :
wifi_ssid: "YourNetworkName"
wifi_password: "YourPassword"
ap_password: "rbamprbamp"
Ce que cela démontre : séparer les identifiants de compilation du YAML versionné grâce à !secret d'ESPHome. Lister bench-*.yaml dans .gitignore permet de garder autant de variantes de banc que voulu sans risque de fuite. Utilisez esphome run --device 192.168.0.173 example/bench-ui1.yaml pour l'OTA après la première connexion réseau, ou esphome run --device COM6 example/bench-ui1.yaml pour le premier flash USB.
11 · Chute de tension et perte du secteur
Lorsque le secteur est interrompu, le frontal analogique isolé du module ne reçoit plus de signal. Le registre de tension retombe à 0.0 V — un float IEEE 754 fini valide qui passe le filtre de cohérence isfinite() du composant. La politique de filtrage du composant est intentionnelle :
AUCUNE borne physique basse — la chute de tension (U=0 V à la déconnexion du secteur), l'affaissement de tension, le test hors réseau / UPS et le déclenchement du disjoncteur DOIVENT être transmis à HA, afin que l'utilisateur voie l'état réel.
Aucune configuration YAML particulière n'est nécessaire pour détecter une perte de secteur — le capteur voltage lui-même lit 0.0 V.
sensor:
- platform: rbamp
rbamp_id: meter1
voltage:
name: "Mains Voltage" # reads 0.0 V when mains is disconnected
current:
name: "Mains Current"
power:
name: "Mains Power"
energy:
name: "Mains Energy"
Automatisation HA : alerte en cas de perte du secteur
YAML Home Assistant (pas ESPHome) — à placer dans votre configuration Home Assistant, pas dans le YAML du nœud.
# configuration.yaml or the Automations UI
automation:
- alias: "rbAmp mains loss alert"
trigger:
- platform: numeric_state
entity_id: sensor.rbamp_ui1_mains_voltage
below: 10 # U < 10 V = mains disconnected or a severe brownout
for:
seconds: 5 # debounce: sustained, not transient
action:
- service: notify.mobile_app_your_phone
data:
title: "Mains power lost"
message: >
Voltage dropped to {{ states('sensor.rbamp_ui1_mains_voltage') }} V
at {{ now().strftime('%H:%M:%S') }}.
Ce que cela démontre : utiliser le comportement de passage du 0 V comme source d'un événement de « perte de secteur ». Comme le composant publie 0.0 V au lieu de sauter la publication, les automatisations HA et le tableau de bord Énergie voient l'événement de baisse de tension en temps réel. La condition for: 5 seconds bloque les déclenchements intempestifs pendant la mise en chauffe au démarrage (~250 ms, quand les registres lisent 0 avant la première mesure valide).
12 · Tableau de bord Énergie de HA
Le capteur energy (et energy_1, energy_2, energy_exported, etc.) est automatiquement configuré avec device_class: energy et state_class: total_increasing — exactement ce qu'attend le tableau de bord Énergie de HA pour les capteurs de consommation ou de production cumulée. Aucun YAML supplémentaire n'est nécessaire.
Après la découverte :
- Paramètres → Tableaux de bord → Énergie.
-
Ajoutez une consommation → choisissez « Mains Energy » (Énergie secteur) ou l'entité de comptage d'import souhaitée.
-
Si vous avez du solaire — Add Production (Ajouter une production) → choisissez Solar Energy (Énergie solaire) à partir de
meter_solardans l'exemple multi-modules.
Les valeurs d'énergie sont en Wh. HA les convertit lui-même en kWh pour l'affichage. La persistance NVS du composant garantit que l'accumulateur survit à un redémarrage de l'ESP32 sans fausse « remise à zéro du compteur » dans les statistiques HA.
# Example: consumption + solar export for the HA Energy dashboard
# (assumes the rbamp: blocks meter_house and meter_solar from the multi-module example)
# energy / energy_exported need voltage AND current in the same block;
# internal: true keeps them out of Home Assistant.
sensor:
- platform: rbamp
rbamp_id: meter_house
voltage:
name: "House Voltage"
internal: true
current:
name: "House Current"
internal: true
energy:
name: "House Grid Import" # → HA Energy: grid consumption
- platform: rbamp
rbamp_id: meter_solar
voltage:
name: "Solar Voltage"
internal: true
current:
name: "Solar Current"
internal: true
energy:
name: "Solar Production" # → HA Energy: solar production
energy_exported:
name: "Solar Grid Export" # → HA Energy: return to grid
# needs bidirectional: true in rbamp:;
# real values on STANDARD (STD) modules,
# reads 0 on BASIC
13 · Automatisations HA sur les capteurs rbAmp
8.8 Flux d'événements de seuil — écriture du seuil → déclenchement → effacement W1C (api-reference)
Délestage : un relais coupe lorsqu'un seuil est dépassé
YAML Home Assistant (pas ESPHome) — à placer dans votre configuration Home Assistant, pas dans le YAML du nœud.
automation:
- alias: "Load shedding — turn off non-critical loads at 3 kW"
trigger:
- platform: numeric_state
entity_id: sensor.rbamp_multi_house_power
above: 3000 # 3 kW threshold
for:
seconds: 10
action:
- service: switch.turn_off
target:
entity_id: switch.ev_charger_relay # the non-critical load relay
- alias: "Load shedding — restore when it drops below 2 kW"
trigger:
- platform: numeric_state
entity_id: sensor.rbamp_multi_house_power
below: 2000
for:
seconds: 30
action:
- service: switch.turn_on
target:
entity_id: switch.ev_charger_relay
Rappel sur la correction du facteur de puissance
YAML Home Assistant (pas ESPHome) — à placer dans votre configuration Home Assistant, pas dans le YAML du nœud.
automation:
- alias: "Poor power factor notification"
trigger:
- platform: numeric_state
entity_id: sensor.rbamp_ui1_mains_power_factor
below: 0.7
for:
minutes: 5
action:
- service: persistent_notification.create
data:
title: "Low power factor"
message: >
Power factor is {{ states('sensor.rbamp_ui1_mains_power_factor') }}.
Check for large inductive loads (motors, old lighting ballasts).
Alerte de dépassement du budget journalier
YAML Home Assistant (pas ESPHome) — à placer dans votre configuration Home Assistant, pas dans le YAML du nœud.
automation:
- alias: "Daily energy budget — warning at 10 kWh"
trigger:
- platform: template
value_template: >
{{ states('sensor.energy_daily') | float(0) > 10000 }}
action:
- service: notify.mobile_app_your_phone
data:
message: "Daily energy usage exceeded 10 kWh."
14 · Cartes Lovelace
Jauge — puissance en direct
YAML Home Assistant (pas ESPHome) — à placer dans votre configuration Home Assistant, pas dans le YAML du nœud.
type: gauge
entity: sensor.rbamp_ui1_mains_power
min: 0
max: 3600
name: "Live Power"
segments:
- from: 0
color: green
- from: 1500
color: orange
- from: 2500
color: red
Apex Charts — puissance dans le temps
YAML Home Assistant (pas ESPHome) — à placer dans votre configuration Home Assistant, pas dans le YAML du nœud.
type: custom:apexcharts-card
header:
title: "Power (W)"
show: true
graph_span: 4h
series:
- entity: sensor.rbamp_ui1_mains_power
name: Power
stroke_width: 2
curve: smooth
Apex Charts — comparaison d'énergie entre trois canaux
YAML Home Assistant (pas ESPHome) — à placer dans votre configuration Home Assistant, pas dans le YAML du nœud.
type: custom:apexcharts-card
header:
title: "Channel Energy (Wh)"
show: true
graph_span: 24h
series:
- entity: sensor.rbamp_ui3_ch0_energy
name: CH0
- entity: sensor.rbamp_ui3_ch1_energy
name: CH1
- entity: sensor.rbamp_ui3_ch2_energy
name: CH2
Mini graphe — tension
YAML Home Assistant (pas ESPHome) — à placer dans votre configuration Home Assistant, pas dans le YAML du nœud.
type: custom:mini-graph-card
entities:
- sensor.rbamp_ui1_mains_voltage
name: "Mains Voltage"
hours_to_show: 12
points_per_hour: 4
line_width: 2
15 · Compteur de services — agrégation par jour / semaine / mois
ESPHome publie les totaux cumulés en Wh. L'intégration HA utility_meter remet le compteur à zéro à intervalles configurables et publie le delta comme capteur distinct — pratique pour les bilans journaliers ou mensuels.
YAML Home Assistant (pas ESPHome) — à placer dans votre configuration Home Assistant, pas dans le YAML du nœud.
# configuration.yaml
utility_meter:
energy_daily:
source: sensor.rbamp_ui1_mains_energy
cycle: daily
name: "Daily Energy"
energy_monthly:
source: sensor.rbamp_ui1_mains_energy
cycle: monthly
name: "Monthly Energy"
energy_weekly:
source: sensor.rbamp_ui1_mains_energy
cycle: weekly
name: "Weekly Energy"
HA crée trois entités : sensor.energy_daily, sensor.energy_monthly, sensor.energy_weekly. Chacune revient à 0 au début de sa période respective et accumule le delta du capteur source total_increasing.
Capteur kWh/jour dérivé
utility_meter sort des Wh par défaut. Pour afficher en kWh, ajoutez un capteur template :
YAML Home Assistant (pas ESPHome) — à placer dans votre configuration Home Assistant, pas dans le YAML du nœud.
template:
- sensor:
- name: "Daily Energy kWh"
unit_of_measurement: "kWh"
state_class: total_increasing
device_class: energy
state: >
{{ (states('sensor.energy_daily') | float(0) / 1000) | round(3) }}
Capteur de coût journalier
YAML Home Assistant (pas ESPHome) — à placer dans votre configuration Home Assistant, pas dans le YAML du nœud.
template:
- sensor:
- name: "Daily Energy Cost"
unit_of_measurement: "EUR"
icon: mdi:currency-eur
state: >
{% set kwh = states('sensor.energy_daily') | float(0) / 1000 %}
{% set rate = 0.28 %} # EUR/kWh — set your own tariff
{{ (kwh * rate) | round(2) }}
16 · Sous-comptage par charge (3 modules aux adresses 0x50 / 0x51 / 0x52)
Installer trois modules rbAmp dans un tableau de distribution permet un comptage d'énergie par circuit sans tableau intelligent ni matériel supplémentaire.
YAML Home Assistant (pas ESPHome) — à placer dans votre configuration Home Assistant, pas dans le YAML du nœud.
# Extending the multi-module example with per-circuit utility meters
utility_meter:
kitchen_daily:
source: sensor.rbamp_multi_house_energy
cycle: daily
name: "Kitchen Circuit Daily"
solar_monthly:
source: sensor.rbamp_multi_solar_energy
cycle: monthly
name: "Solar Production Monthly"
ev_daily:
source: sensor.rbamp_multi_ev_charger_energy
cycle: daily
name: "EV Charging Daily"
Combiné au tableau de bord Énergie de HA, vous obtenez des relevés mensuels par circuit sans calculs supplémentaires kWh × tarif.
17 · rbAmp + un relais — régulation en boucle fermée
Un chauffe-eau avec commande par relais
# ESPHome YAML on the same ESP32 as rbAmp
switch:
- platform: gpio
pin: GPIO5
id: heater_relay
name: "Water Heater"
Avec rbAmp et un relais sur le même ESP32, vous pouvez construire une boucle fermée directement dans ESPHome (via un Lambda ou on_value), sans aller-retour par HA :
Suppose que vous disposez déjà d'une entrée switch: avec l'identifiant utilisé ci-dessous.
sensor:
- platform: rbamp
rbamp_id: meter1
power:
name: "House Power"
on_value:
then:
- if:
condition:
lambda: 'return x > 3000.0f;'
then:
- switch.turn_off: heater_relay
else:
- switch.turn_on: heater_relay
Ce que cela démontre : utiliser le callback on_value d'un capteur rbAmp pour piloter un relais sans intervention de HA. Le callback se déclenche sur l'ESP32 à chaque update_interval (60 s) et met à jour l'état du relais à partir de la dernière lecture de puissance. Pour une régulation plus serrée (boucle de moins de 60 s), réduisez update_interval à 10s — cela augmente proportionnellement la charge du bus I²C. Un exemple de boucle fermée plus complet pour une chaudière se trouve dans 07_diy_integrations.md.
18 · Intégration DRDY
La broche DRDY à drain ouvert du module délivre une impulsion LOW d'environ 10 µs toutes les ~100 ms après la mise à jour des registres instantanés. Vous pouvez la relier à une GPIO de l'ESP32. Le composant journalise la broche DRDY ; les lectures sont pilotées par minuterie (update_interval).
rbamp:
id: meter1
address: 0x50
update_interval: 60s # energy integration still happens every 60 s
drdy_pin:
number: GPIO15
mode:
input: true
pullup: true # DRDY is open-drain; it needs a pull-up
inverted: true # the DRDY pulse is LOW; inverted=true gives a rising edge
: sur le firmware actuel, le composant journalise drdy_pin dans dump_config mais n'implémente pas les lectures RT pilotées par interruption — le update_interval fixe toujours la cadence d'interrogation.
19 · Capteurs phasés (variantes biphasées / triphasées)
Pour les modules avec plus d'une entrée de tension, le composant propose un groupe de capteurs phasés (voltage_a/b/c, current_a/b/c, power_a/b/c, energy_a/b/c, power_factor_a/b/c, reactive_power_a/b/c, power_total, plus voltage_angle_b/c). Un emplacement ne publie que lorsque le module connecté signale le canal correspondant ; sur un module à tension unique, les emplacements phasés restent sans valeur. Le schéma vérifie que les groupes monophasés et phasés ne sont pas mélangés dans un même bloc sensor:.
sensor:
- platform: rbamp
rbamp_id: meter1
voltage_a:
name: "Phase A Voltage"
voltage_b:
name: "Phase B Voltage"
voltage_c:
name: "Phase C Voltage"
current_a:
name: "Phase A Current"
current_b:
name: "Phase B Current"
current_c:
name: "Phase C Current"
power_a:
name: "Phase A Power"
power_b:
name: "Phase B Power"
power_c:
name: "Phase C Power"
power_total:
name: "Total Power"
voltage_angle_b:
name: "Phase B Angle" # degrees vs phase A
voltage_angle_c:
name: "Phase C Angle"
phase_sequence:
name: "Phase Sequence" # 1 forward, 2 reverse, 3 abnormal
frequency:
name: "Grid Frequency"
Ce qu'il démontre : le groupe de champs phasés. Mélanger des champs monophasés et phasés dans un même bloc sensor: produit une erreur à la compilation — choisissez le groupe correspondant à votre module. Les détails figurent dans 09 · Référence API §2.2.
20 · Migration depuis d'autres composants de mesure ESPHome
Depuis pzem004t
La plateforme pzem004t exporte les mêmes noms de champs que rbamp pour les grandeurs alternatives courantes. Le remplacement se fait bloc pour bloc avec des noms de capteurs identiques :
# Before (pzem004t, UART)
uart:
rx_pin: GPIO16
tx_pin: GPIO17
baud_rate: 9600
sensor:
- platform: pzem004t
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"
# After (rbamp, I²C) — the same sensor names → the same entity IDs in HA
# (replaces the block above; do not paste both)
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz
rbamp:
id: meter1
address: 0x50
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"
Des champs name: identiques donnent des entity IDs identiques dans HA. L'historique du tableau de bord Énergie est conservé lors du remplacement : le capteur total_increasing reprend là où il s'était arrêté. Retirez le bloc uart: s'il n'est pas partagé avec un autre composant.
Depuis cse7766 (Sonoff POW R2)
Même schéma. cse7766 fournit voltage, current, power, energy, power_factor, apparent_power — tous présents dans rbamp. Remplacez platform: cse7766 par platform: rbamp, ajoutez rbamp_id: meter1, supprimez uart:, et ajoutez i2c: ainsi que le bloc rbamp:.
21 · Module STANDARD — totaux d'énergie embarqués
Sur un module STANDARD, le composant accumule les compteurs d'énergie propres du module. Les totaux survivent aux redémarrages de l'ESP32 comme du module et restent monotones. Le même YAML fonctionne aussi sur un module BASIC, sauf que les clés de total général ne publient alors jamais.
rbamp:
id: meter1
address: 0x50
update_interval: 30s
bidirectional: true # per-channel energy_exported
start_current_ua: 400 # no energy counted below 400 µA per channel
sensor:
- platform: rbamp
rbamp_id: meter1
voltage:
name: "Mains Voltage"
current:
name: "Mains Current"
power:
name: "Mains Power"
energy_total:
name: "Energy Imported" # all channels, total_increasing
energy_exported_total:
name: "Energy Exported" # all channels, total_increasing
energy_net:
name: "Energy Net" # import - export, may decrease
reactive_energy:
name: "Reactive Energy Imported" # varh
reactive_energy_exported:
name: "Reactive Energy Exported"
Ce qu'il démontre : les capteurs de total général, qui n'ont pas besoin de déclaration current/voltage associée ; start_current_ua: (0 = désactivé, sinon 10..2540 par pas de 10) pour que le bruit à vide ne s'ajoute pas aux compteurs d'import et d'export (les relevés instantanés ne sont pas affectés). Pour le tableau de bord Énergie de HA, utilisez energy_total comme consommation réseau et energy_exported_total comme retour réseau.
22 · Changer le calibre SCT et dérogation de service
rbamp:
id: meter1
ct_model: SCT_013_010 # module was delivered with the SCT-013-030
Les relevés restent justes après la bascule : sur les firmwares de module jusqu'à 1.4.19, le composant termine l'écriture du modèle avec le redémarrage requis du module (visible dans le journal) et met à l'échelle le courant, la puissance et l'énergie vers le capteur sélectionné ; les firmwares plus récents le font sur le module. Une valeur déjà détenue par le module n'est jamais réécrite, et sur un module fourni calibré avec son propre capteur intégré (sensor_class: WIRED_CT / BUILTIN_CT), le changement est refusé avec une ligne de journal. Uniquement pour une réapplication délibérée d'un préréglage :
rbamp:
id: meter1
ct_model: SCT_013_010
ct_model_force: true # one-off service option; remove both lines afterwards
Récapitulatif des règles de validation YAML
| Règle | Imposé par |
|---|---|
power / energy / power_factor / reactive_power requièrent current |
Validateur de schéma (_SINGLE_SLOT_DEPS) |
P/Q/PF/E pour tout canal nécessitent voltage |
Validateur de schéma |
Les groupes monophasés et phasés ne sont pas mélangés dans un même sensor: |
_validate_topology_consistency |
new_address ≠ address |
_validate_new_address |
address dans la plage 0x08..0x77 |
cv.i2c_address |
update_interval minimum 1s, imposé |
Validateur de schéma |
latch_interval ≥ update_interval |
Validateur de schéma |
ct_model: et ct_models: s'excluent mutuellement |
Validateur de schéma |
ct_models: a de 1 à 16 entrées |
Validateur de schéma |
ct_model_force: true exige ct_model: ou ct_models: |
Validateur de schéma |
start_current_ua vaut 0 ou 10..2540 par pas de 10 |
Validateur de schéma |
Le code de modèle CT est valide pour le sensor_class épinglé |
Validateur de schéma |
Les erreurs de validation sont signalées à esphome compile, avec un message lisible pointant la clé fautive. Il n'est pas nécessaire de flasher le matériel pour trouver une erreur de configuration.
Source et signalements : rb-amp/rbamp-esphome · cette page dans le dépôt : docs/06_examples.md (v1.9.1)