rbAmp
FR
Boutique
Docs
Mis à jour le · Modifier sur GitHub (Edit on GitHub)

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
Remarque

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Ω).

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

Text
[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_power dans 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)

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

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

Text
[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.

Remarque

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

Text
[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.

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

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

Text
[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 config rejette le schéma (cv.Invalid). Si le YAML passe malgré le validateur (édition manuelle / build ancien), le firmware renvoie REG_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).

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

Text
[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éral group=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.

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

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

YAML
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 le entity_id de HA — par exemple sensor.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 bloc rbamp:. Si vous voulez publier certains capteurs moins souvent, ajoutez filters: - 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 par kWh avec multiply: 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.

Sécurité

⚠ 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).

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

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

Remarque

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 :

Sécurité

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

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

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

  1. Sondez 0x50. Si 0x50 est silencieux et que 0x51 ré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.

  2. Vérifiez que le module est prêt à accepter une opération de provisionnement.

  3. Écrire la nouvelle adresse en flash (~700 ms), une réinitialisation logicielle (~300 ms), et reverrouiller sur le cycle secteur.

  4. Confirmez à la nouvelle adresse. En cas de succès — le journal Address change confirmed at 0x51 et IMPORTANT: 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) :

YAML
# BEFORE (provisioning):
rbamp:
  id: meter1
  address: 0x50               # the module's current address
  new_address: 0x51           # the provisioning target
  update_interval: 60s
YAML
# 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 :

  1. Remplacez la valeur de address: par la nouvelle.
  2. Supprimez (ne commentez pas) la ligne new_address:.
  3. 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.

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

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

Sécurité

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.

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

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

  1. Paramètres → Tableaux de bord → Énergie.
  2. Ajoutez une consommation → choisissez « Mains Energy » (Énergie secteur) ou l'entité de comptage d'import souhaitée.

  3. Si vous avez du solaire — Add Production (Ajouter une production) → choisissez Solar Energy (Énergie solaire) à partir de meter_solar dans 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.

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

YAML
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

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

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