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

09 · Référence du schéma YAML

Carte des registres rbAmp — espace d'adresses de la page 0 (0x00..0xFF)

Instantané de période atomique — une écriture clôt la période et en ouvre une nouvelle

Ce chapitre est la référence complète du schéma YAML du composant externe rbamp pour ESPHome. Si une clé n'est pas listée ici, elle n'existe pas dans le schéma.

Un seul YAML pour les deux gammes de modules. Au démarrage, le composant identifie la gamme connectée (BASIC ou STANDARD (STD)) et s'adapte automatiquement : le nombre de canaux, la variante et les fonctions viennent du module lui-même, donc aucune clé topology: ni changement de niveau n'est nécessaire dans le YAML. Les clés propres à une seule génération sont signalées ci-dessous ; une clé que le module connecté ne peut pas honorer est ignorée avec une ligne de journal, jamais un échec bloquant.

Contents:

  1. Bloc de composant — rbamp:
  2. Plateforme capteur — sensor.platform: rbamp
  3. Flux de données et temporisation
  4. Réglages du bus I²C

1. Bloc de composant — rbamp:

Le bloc de premier niveau rbamp: enregistre une instance de composant. Il hérite de PollingComponent (qui fournit update_interval) et de i2c.I2CDevice (qui fournit address et le handle du bus I²C). MULTI_CONF: True signifie qu'un nombre quelconque de blocs rbamp: peut coexister dans un même YAML, chacun référençant son propre esclave I²C.

YAML
rbamp:
  id: meter1
  address: 0x50
  update_interval: 60s
  drdy_pin: GPIO4
  sensor_class: SCT_013
  ct_model: SCT_013_030
  # or, for a UI3 with mixed clamps:
  # ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
  bidirectional: false
  new_address: 0x51
  fleet_gc_enable: false
  group_id: 0
  latch_interval: 60s
  start_current_ua: 400     # STANDARD only, see below
  # ct_model_force: true    # service option, see below

Chaque clé est facultative. topology: et broadcast_latch: restent acceptées par rétrocompatibilité (voir leurs entrées).


id

Attribut Valeur
Type id (identifiant ESPHome)
Par défaut Généré automatiquement
Requis Non

Attribue un identifiant stable à l'instance. Les capteurs le référencent via rbamp_id: meter1. Avec plusieurs blocs rbamp:, un id explicite est requis.

YAML
rbamp:
  id: kitchen_meter

address

Attribut Valeur
Type i2c_address (7 bits, 0x08..0x77)
Par défaut 0x50
Requis Non

L'adresse I²C actuelle du module rbAmp. La valeur d'usine est 0x50. Après application d'un changement d'adresse (via new_address), mettez à jour cette clé avec la nouvelle valeur et retirez new_address.

Plage valide : 0x08..0x77 (les adresses I²C réservées sur 7 bits sont exclues).

YAML
rbamp:
  address: 0x52   # three modules on the bus: 0x50, 0x51, 0x52

Renvoi : le protocole du bus I²C dans la référence API ; changement d'adresse à l'exécution pour modifier l'adresse après le démarrage.


update_interval

Attribut Valeur
Type time (chaîne de durée ESPHome)
Par défaut 60s
Requis Non

Fréquence d'appel de update(). Chaque appel :

  1. Envoie la commande d'instantané et programme un délai non bloquant de 50 ms pour lire l'instantané de période (modules BASIC ; sur les modules STANDARD, l'énergie provient des compteurs propres du module, voir energy_total).
  2. Vérifie le registre d'état ; si le module est prêt, publie tous les capteurs instantanés liés.

La valeur par défaut de 60 s est raisonnable : le module met à jour en interne sa puissance moyenne par période environ toutes les ~100 ms, mais l'intégration de l'énergie côté maître exige une fenêtre suffisamment longue pour être juste. À 60 s et une charge moyenne de 60 W, un instantané manqué fait perdre ≤ 1 Wh.

La valeur minimale autorisée est 1s : le schéma rejette toute valeur inférieure, et esphome config signale un diagnostic. Les valeurs inférieures à 5-10 s n'apportent rien à une synchronisation serrée et encombrent le bus.

YAML
rbamp:
  update_interval: 30s   # more frequent dashboard updates, more traffic

latch_interval

Attribut Valeur
Type time (chaîne de durée ESPHome)
Par défaut Identique à update_interval
Requis Non
Depuis v1.4

Fréquence à laquelle le composant envoie la commande d'instantané et intègre un échantillon en Wh. Lorsqu'elle est définie, elle découple le cycle d'instantané de la cadence de lecture RT — update_interval: continue de régler la fréquence de lecture et de publication des registres V/I/P/PF/Q, tandis que latch_interval: règle la fréquence de capture de l'accumulateur de période et d'intégration des Wh.

L'intégration d'énergie n'ajoute aucune erreur propre au-delà de la précision de puissance active du module, quel que soit le rapport : l'intégration côté maître utilise le dt réel entre événements d'instantané successifs, donc des intervalles d'instantané plus longs produisent simplement des pas d'intégration plus grossiers.

Doit être >= update_interval (la valeur plus courte est rejetée à la validation de la configuration — les instantanés supplémentaires ne produiraient aucune donnée observable).

Lorsqu'il n'est pas défini, l'instantané s'exécute à chaque appel update() (comportement à cadence unique de la v1.3, rétrocompatible).

YAML
rbamp:
  update_interval: 3s        # RT V/I/P/PF refreshed every 3 s
  latch_interval: 60s        # snapshot + Wh integration once a minute

Utile lorsque la charge du bus ou la concurrence CPU côté maître compte — flottes multi-modules, hôtes ESP8266 (mono-cœur ; les ISR WiFi se disputent le CPU pendant les transactions I²C), ou bus I²C partagés avec d'autres appareils.


drdy_pin

Attribut Valeur
Type gpio_input_pin_schema
Par défaut Aucune (facultatif)
Requis Non

Relie la sortie DRDY à drain ouvert du module à une GPIO de l'ESP32. Lorsqu'elle est indiquée, la broche est configurée dans setup() au démarrage.

Remarque

La broche est consignée dans dump_config mais n'est pas utilisée comme déclencheur de lecture — les registres instantanés sont interrogés à update_interval. Déclarer la broche ne change pas le comportement.

YAML
rbamp:
  drdy_pin: GPIO4

sensor_class

Attribut Valeur
Type enum (SCT_013, WIRED_CT, BUILTIN_CT)
Par défaut SCT_013
Requis Non

Fixe la famille de capteurs de courant côté module. Sur le firmware v1.2+, la valeur est écrite en flash et devient une condition préalable à l'écriture du modèle de pince : le module refusera d'écrire le modèle si la classe n'est pas définie. Sur les firmwares antérieurs, la valeur est acceptée par le schéma et appliquée automatiquement lors de la mise à jour.

Valeur Signification
SCT_013 Pinces SCT-013 à noyau fendu — la valeur par défaut
WIRED_CT Module fourni étalonné avec son propre capteur monté
BUILTIN_CT Module fourni calibré avec son propre capteur intégré

Garde-fou d'écriture. Le composant n'écrit jamais une classe que le module possède déjà (un démarrage répété n'écrit rien). Sur un module étalonné en paire avec son capteur monté (WIRED_CT / BUILTIN_CT), un changement de classe ou de modèle depuis le YAML est refusé avec une ligne de journal explicite — l'écriture remplacerait l'étalonnage individuel par un réglage générique. Omettez sensor_class: et ct_model: du YAML pour ces modules, ou voir ct_model_force.

YAML
rbamp:
  sensor_class: SCT_013   # default; may be omitted

Pour en savoir plus sur le choix de la pince et de la famille, voir 03_sensor_selection.md.


ct_model

Attribut Valeur
Type enum (SCT_013_005, _010, _020, _030, _050)
Par défaut Aucune (facultatif)
Requis Non

Écrit l'identifiant du modèle de pince CT dans la flash du module. Sur le firmware v1.2+, cela charge automatiquement les coefficients d'usine du modèle choisi — aucune étape de calibrage supplémentaire n'est requise. Une valeur identique à celle déjà présente dans le module n'est pas réécrite.

Valeur YAML Code Courant nominal Statut v1.3
SCT_013_005 1 5 A production
SCT_013_010 2 10 A production
SCT_013_020 6 20 A production (nouveau en v1.3)
SCT_013_030 3 30 A production (SKU par défaut)
SCT_013_050 4 50 A production
Remarque

L'ensemble des codes admis par classe pour SCT_013 est {1, 2, 3, 4, 5, 6, 7} (SCT_013_100 correspond au code 5, SCT_013_060 au code 7 ; l'ordre des codes n'est pas l'ordre des calibres). Les valeurs non conformes sont rejetées à esphome config via cv.Invalid. Pour en savoir plus, voir 03 · Choix du capteur de courant.

YAML
rbamp:
  ct_model: SCT_013_030

Appliqué une fois dans setup(). Chaque écriture s'accompagne d'un flash d'environ 700 ms (le module refuse toutes les opérations I²C pendant ce temps — le composant alimente le watchdog automatiquement).

Changer le calibre SCT conserve la précision. Chaque module SCT est calibré en usine avec le SCT-013-030. Lorsque vous sélectionnez un autre calibre, le courant, la puissance et l'énergie restent justes : sur les firmwares jusqu'à 1.4.19, le composant termine l'écriture du modèle avec un redémarrage du module (cela fait partie du flux normal et apparaît dans le journal), puis met à l'échelle les relevés vers le capteur sélectionné ; les firmwares plus récents effectuent la bascule sur le module et le composant laisse les relevés intacts. La tension et le facteur de puissance ne sont pas affectés. Aucune modification YAML n'est nécessaire pour cela.

Protection en écriture. Une valeur identique n'est jamais réécrite, et sur un module appairé en usine (sensor_class: WIRED_CT / BUILTIN_CT) l'écriture est refusée avec une ligne de journal — voir sensor_class.

Mutuellement exclusif avec ct_models: — une seule des deux peut être utilisée par bloc rbamp:.

Pour en savoir plus, voir 03_sensor_selection.md. Renvoi : la référence ct_model.


ct_models

Attribut Valeur
Type liste de 1–16 valeurs d'énumération
Par défaut Aucune (facultatif)
Requis Non

Modèles de pince CT par canal — pour les modules avec des pinces mixtes sur différents canaux. Accepte les mêmes valeurs d'énumération que ct_model:. Le schéma accepte de 1 à 16 entrées ; la position dans la liste est l'indice du canal. Le composant applique autant d'entrées que le module a de canaux (1 pour UI1, 2 pour UI2, 3 pour UI3, etc.) ; les entrées en trop sont ignorées avec un avertissement.

YAML
rbamp:
  id: ui3_meter
  ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
  # CH0=5A for standby loads (maximum resolution),
  # CH1=30A for main household loads,
  # CH2=20A for a water heater / medium-power branch (~3-5 kW)
  # For currents above 50 A use SCT_013_060 (60 A) or SCT_013_100 (100 A)

Sur le firmware v1.2+, chaque canal reçoit son propre jeu de coefficients d'usine, indépendamment. Le temps de configuration total au démarrage est d'environ 2–3 secondes (~700 ms d'écriture en flash par canal).

Modules STANDARD. Les modèles par canal ne sont stockés que par les modules qui annoncent un stockage persistant par canal. Sur un module qui ne le fait pas, le composant refuse bruyamment (un avertissement indiquant que ct_models: n'est pas pris en charge par cet appareil, clés ignorées) au lieu d'écrire une valeur qui reviendrait silencieusement après une coupure — utilisez alors le ct_model: unique.

Les mêmes garde-fous d'écriture que pour ct_model: s'appliquent (les valeurs égales ne sont pas réécrites ; les modules appairés en usine refusent le changement).

Mutuellement exclusif avec ct_model:.


ct_model_force

Attribut Valeur
Type bool
Par défaut false
Requis Non

Option de service. Elle contourne la protection en écriture : le composant applique alors le préréglage ct_model: / ct_models: même si le module est appairé en usine ou porte déjà la même valeur. Cela remplace la calibration individuelle du module par le préréglage générique de ce modèle : ne l'utilisez que délibérément, exécutez-la une fois puis retirez-la.

Le schéma rejette ct_model_force: true sauf si ct_model: ou ct_models: est aussi présent, si bien que le drapeau ne peut pas rester armé dans le YAML en attendant une ligne de modèle ultérieure.

YAML
rbamp:
  ct_model: SCT_013_030
  ct_model_force: true   # one-off; remove both lines after the operation

start_current_ua

Attribut Valeur
Type entier, microampères
Valeurs autorisées 0 (désactivé) ou 10..2540 par pas de 10
Par défaut Aucune (la valeur par défaut du module s'applique)
Requis Non
S'applique à Modules STANDARD avec compteurs d'énergie embarqués ; ignoré avec un avertissement ailleurs

Courant de démarrage pour le comptage d'énergie. Tant que le courant d'un canal est inférieur à cette valeur, le module ne compte aucune énergie sur ce canal. Sans cela, à vide, la puissance mesurée est un bruit de signe quelconque qui s'ajoute lentement aux compteurs d'import comme d'export. Les relevés instantanés (courant, puissance, ...) ne sont pas affectés — seuls les compteurs d'énergie le sont.

Les valeurs hors de l'ensemble autorisé (par exemple 15 ou 3000) sont rejetées par le schéma, de sorte qu'une valeur invalide n'atteint jamais le bus. Le réglage est stocké sur le module et vérifié après l'écriture ; une valeur égale à celle déjà stockée n'est pas réécrite.

YAML
rbamp:
  start_current_ua: 400

Vous pouvez relire la valeur stockée depuis un lambda avec id(meter1).read_start_current_ua() (renvoie 65535 si indisponible).


period_banks

Attribut Valeur
Type liste d'entrées de banc
Entrées par liste 1..8, chaque bank: (0..7) listée une seule fois
Par défaut Aucune
Requis Non
S'applique à Modules STANDARD qui annoncent des banques d'instantanés (image 0x7E et ultérieure) ; sur tout autre module, les entrées restent indisponibles et le journal le signale une fois au démarrage

Le module conserve huit bancs d'instantanés indépendants. Chaque entrée mesure une période — le temps entre deux captures du même banc, cadencé par l'horloge de l'ESP32 — et publie les moyennes, pics et énergie de la période. À utiliser pour « énergie par heure », « courant de crête depuis la dernière pression » et questions similaires auxquelles les totaux courants ne répondent pas.

Clé Signification
bank Numéro de banc 0..7. Le banc 0 est libre sur les modules disposant de compteurs d'énergie embarqués ; sur un module sans compteurs, le composant utilise lui-même le banc 0 et l'entrée est ignorée avec un avertissement.
interval Cadence de capture automatique facultative, d'au moins 1s. Sans elle, le banc n'est capturé que par l'action rbamp.latch_bank.
power, reactive_power, apparent_power Moyenne sur la période.
energy, energy_exported Wh importés / exportés sur la période (pas des compteurs — ils portent state_class: measurement).
max_power, max_current, max_voltage, min_voltage Extrêmes à l'intérieur de la période.
period_length La durée de la période en secondes, mesurée par l'ESP32.
channels Liste facultative, une entrée par canal de courant (première entrée = canal 0), chacune avec power, energy, energy_exported.

Le premier verrouillage d'une banque après le démarrage, ou après redémarrage du module, ne fait que démarrer la période ; ses valeurs sont écartées et les capteurs ne publient qu'à partir du verrouillage suivant. Les verrouillages de banques différentes sont espacés d'au moins 150 ms.

YAML
rbamp:
  id: meter1
  period_banks:
    - bank: 1
      interval: 1h
      power: {name: "Hour average power"}
      energy: {name: "Hour energy"}
      max_current: {name: "Hour peak current"}
    - bank: 2                    # latched by hand
      energy: {name: "Energy since last press"}
      period_length: {name: "Since last press, s"}

button:
  - platform: template
    name: "Latch bank 2"
    on_press:
      - rbamp.latch_bank:
          id: meter1
          bank: 2

Un exemple complet se trouve dans example/std_banks.yaml.


bidirectional

Attribut Valeur
Type bool
Par défaut false
Requis Non

Active le chemin d'énergie d'export par canal (energy_exported, energy_exported_1, energy_exported_2). Lorsque true, l'énergie d'export est accumulée séparément de l'énergie d'import.

Sur un module STANDARD, l'énergie d'export provient des compteurs propres du module, elle survit donc aux redémarrages et reste monotone. Sur un module BASIC, la ligne est unidirectionnelle : les capteurs energy_exported_* sont acceptés par le schéma mais publient 0.

Déclarez energy_exported (ou _1 / _2) sous sensor.platform: rbamp uniquement si bidirectional: true est défini. Les capteurs de totaux généraux energy_exported_total et energy_net n'ont pas besoin de cette clé.

YAML
rbamp:
  bidirectional: true   # needed for the per-channel energy_exported* sensors

new_address

Attribut Valeur
Type i2c_address (0x08..0x77)
Par défaut Aucune (facultatif)
Requis Non

Déclenche un changement d'adresse I²C unique au démarrage. Doit différer de address — le validateur lève une erreur si elles sont égales.

Sur le firmware v1.3, un commit en deux phases est utilisé — production-OK sans verrouillage du provisionnement usine. Comportement de compatibilité :

Firmware Comportement
Annonce le commit d'adresse en deux phases (v1.3+) Chemin production — écriture en deux temps, confirmation explicite, commit, nouvelle énumération.
N'annonce pas cette capacité (historique v1.0-v1.2) Repli hérité — écriture d'une phase unique, nécessite le mode de provisionnement usine. Journalise WARN_FACTORY_MODE_REQUIRED si vous n'êtes pas en provisionnement.

Les modules STANDARD prennent aussi en charge new_address: ; le composant l'applique et se relie à la nouvelle adresse de la même manière.

Le déroulement complet s'exécute une fois dans setup() :

  1. Sondez l'address actuelle. Si le module ne répond pas là mais répond à new_address, le composant s'adapte à la nouvelle adresse avec un avertissement (en supposant qu'un démarrage précédent a déjà appliqué le changement) et saute l'écriture.
  2. Vérifiez si le firmware annonce le commit en deux phases. Oui → chemin production (voir ci-dessous). Non → chemin hérité avec vérification du mode de provisionnement.
  3. Chemin de production (v1.3) : préparez la nouvelle adresse, confirmez, validez → attendez ~700 ms → relancez la sonde sur new_address. Aucun verrouillage par mode usine n'est requis.
  4. Voie historique (v1.0-v1.2) : écriture monophasée, exige le mode provisionnement en usine côté module.
  5. Le composant bascule son adresse I²C interne via i2c::I2CDevice::set_i2c_address() vers new_address et vérifie que le module répond.
  6. Si le module ne répond pas après le changement, le composant appelle mark_failed() et s'arrête.

Après un changement réussi : mettez à jour le YAML en address: et retirez new_address:. Si le module est à la nouvelle adresse au démarrage suivant mais que new_address: est toujours dans le YAML, la sonde de l'ancienne adresse échoue au démarrage, celle de la nouvelle réussit, le composant s'adapte avec un avertissement, et aucune réécriture n'a lieu.

Sécurité

⚠ Mode usine uniquement sur le firmware historique (v1.0-v1.2).

Les modules de série standard fournis avec un firmware hérité étaient livrés avec le mode de provisionnement désactivé. Écrire new_address: sur un tel module sans mode usine sera rejeté (avertissement WARN_FACTORY_MODE_REQUIRED). Sur le firmware v1.3, cette restriction disparaît : le composant détecte automatiquement le chemin production-OK.

Réénumération après validation. Après une validation réussie, le module se réinitialise et se réénumère à la nouvelle adresse. Les appels suivants dans le même setup() sont dirigés de façon transparente vers la nouvelle adresse — mais tout autre maître du bus (un outil I²C brut, une sonde de débogage, un autre ESP32) considère encore le module à l'ancienne adresse tant qu'il n'a pas mis à jour son propre état.

YAML
rbamp:
  address: 0x50
  new_address: 0x51   # remove this line after the first successful boot

Récupération : si le changement d'adresse a été appliqué mais que le module ne répond pas, voir 10_troubleshooting.md → « Address changed, but the module doesn't respond ».

Renvoi : la référence du changement d'adresse à l'exécution.


fleet_gc_enable (v1.3 NOUVEAU)

Attribut Valeur
Type bool
Par défaut false
Requis Non
S'applique à Modules BASIC avec prise en charge de l'instantané par appel général (firmware v1.3+) ; ignoré avec une ligne de journal sur STANDARD

Option : active la réception de la diffusion d'instantané par appel général (General-Call) depuis le maître. Lorsque l'ESP32 émet une trame GC de 5 octets vers l'adresse 0x00, tous les modules avec fleet_gc_enable: true (et un group_id: correspondant) prennent de façon atomique un instantané de leurs accumulateurs de période à un instant unique sur le fil. Cela assure une synchronisation serrée entre les sous-compteurs.

Comportement de capacité : au démarrage, le composant vérifie si le firmware annonce l'instantané par appel général. Si ce n'est pas le cas → avertissement + passage sans application :

Text
[W][rbamp:xxx]: fleet_gc_enable requested but the module does not advertise general-call latch;
firmware v1.0-v1.2 doesn't support General-Call. Falling back to sequential
latch (~270 µs × N inter-module skew at 50 kHz).

Persistance : à l'application, le composant écrit REG_FLEET_CONFIG.bit0, sauvegarde en flash via CMD_SAVE_USER_CONFIG, et RÉINITIALISE l'appareil — le mode GC est configuré à l'initialisation, non modifiable à chaud. Par lecture-comparaison-écriture, cela n'arrive qu'au premier démarrage ; les démarrages suivants l'ignorent.

YAML
rbamp:
  - id: mains
    fleet_gc_enable: true     # opt-in, capability-gated
    group_id: 1               # see below
  - id: boiler
    fleet_gc_enable: true
    group_id: 1               # same group → synchronized

Renvoi : la référence Fleet Group-Commit, 04_hardware.md Flotte multi-modules.


group_id (v1.3 NOUVEAU)

Attribut Valeur
Type uint8_t (0..255)
Par défaut 0
Requis Non
S'applique à Modules BASIC ; ignoré avec une ligne de journal sur STANDARD

Un identifiant de cluster pour un instantané GC sélectif. Le module n'accepte une trame GC que si le champ de groupe de la trame correspond à ce group_id OU vaut 0x00 (appel général).

Cas d'usage :

  • Multi-locataire : un ESP32 pilote plusieurs grappes indépendantes de modules (par ex. 3 appartements dans un même tableau). Grappe 1 = group_id: 1, grappe 2 = group_id: 2. Le maître émet une trame GC avec group=1 → seule la grappe 1 prend un instantané.

  • Mono-locataire : laissez group_id: 0 (appel global) ou réglez group_id: 1 comme étiquette — le comportement est identique, tous les modules prennent un instantané.

Persistance : écrit dans REG_GROUP_ID et sauvegardé en flash par relecture-comparaison-écriture. La modification nécessite un démarrage.

YAML
rbamp:
  - id: apt1_mains
    group_id: 1
  - id: apt2_mains
    group_id: 2

broadcast_latch (obsolète, héritage v0.4.0)

Attribut Valeur
Type bool
Par défaut false
Requis Non
Statut Obsolète — remplacé par fleet_gc_enable: (v1.3+).

Un alias historique du instantané de diffusion General-Call. En v1.3, cette clé est acceptée par le schéma comme no-op (pour une migration sans rupture depuis le YAML v0.4.0), mais elle n'a aucun effet. Pour le nouveau code, utilisez fleet_gc_enable: — elle est conditionnée par les capacités et fonctionne sur le firmware v1.3.

Elle sera supprimée dans une future version mineure ; un avertissement de dépréciation apparaît dans le journal :

Text
[W][rbamp:xxx]: 'broadcast_latch:' is deprecated since v1.3 — use
'fleet_gc_enable:' instead. This key has no effect.

Renvoi : la référence Fleet Group-Commit.


topology

Attribut Valeur
Type enum (SINGLE, SPLIT_PHASE, THREE_PHASE)
Par défaut SINGLE
Requis Non

Indication facultative, conservée pour la compatibilité ascendante. Elle n'est pas nécessaire sur les modules STANDARD : le composant lit le nombre de canaux, la variante et les fonctions depuis le module lui-même et dimensionne l'ensemble des entités à partir de là. Sur les modules BASIC, le nombre de canaux est déduit des emplacements current[_1/_2] que vous déclarez, et topology: ne modifie que la ligne affichée par dump_config.

YAML
rbamp:
  topology: SINGLE         # cosmetic; may be omitted

2. Plateforme capteur — sensor.platform: rbamp

Chaque bloc sensor: déclare un ensemble de capteurs nommés, liés au composant parent rbamp:. La seule clé obligatoire du bloc est rbamp_id.

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

Tous les champs du bloc sensor: sont facultatifs, avec une règle : power, energy, power_factor, reactive_power et apparent_power requièrent voltage ET current déclarés dans le même bloc (les capteurs de canaux numérotés power_N, energy_N, power_factor_N, reactive_power_N requièrent current_N et voltage) ; sinon esphome config échoue avec « power requires current to also be declared ». Ajoutez internal: true à un capteur requis que vous ne voulez pas comme entité Home Assistant. Ne déclarez que les grandeurs dont votre scénario a besoin — le composant ne lit que les registres correspondant aux capteurs déclarés.

rbamp_id

Attribut Valeur
Type use_id(RbAmpComponent)
Requis Oui

Référence le bloc rbamp: auquel ce groupe de capteurs est lié.


2.1 Champs monophasés

Utilisé pour les modules à tension unique (UI1, UI2, UI3, I1, I2, I3 et variantes à plus de canaux). Tous les champs sont facultatifs. Les mélanger avec les champs par phase (voltage_a, voltage_angle_b, etc.) déclenche une erreur de validation.

Des emplacements existent pour jusqu'à sept canaux de courant : current et current_1 ... current_6, et de même power, energy et power_factor avec les mêmes suffixes (power_3, energy_5, ...). energy_exported existe pour les canaux 0..2 (energy_exported, energy_exported_1, energy_exported_2). Un emplacement au-delà du nombre de canaux que le module annonce ne publie jamais. reactive_power n'existe que pour les canaux 0..2 (reactive_power, reactive_power_1, reactive_power_2) ; reactive_power_3 ... reactive_power_6 sont acceptés par le schéma mais ne publient jamais.

Chaque champ accepte les sous-clés standard sensor.sensor_schema d'ESPHome : name, id, filters, unit_of_measurement, accuracy_decimals, icon, etc.

voltage

Attribut Valeur
Unité V
device_class voltage
state_class measurement
accuracy_decimals 1
Source Tension efficace du secteur (registre instantané du module)

Tension efficace (RMS) du secteur. Lue à chaque update() une fois le module prêt. Le flottant de 4 octets est lu avec une nouvelle tentative par octet (3 essais × 5 ms) puis validé par std::isfinite() ainsi que par |val| < 10000.

Zéro est une valeur valide à publier : une coupure ou un creux de tension donne U ≈ 0 V et passe jusqu'à HA sans filtrage — le filtre de cohérence ne rejette que NaN/Inf, pas les zéros légitimes.

YAML
voltage:
  name: "Mains Voltage"
  filters:
    - sliding_window_moving_average:
        window_size: 3
        send_every: 1

current / current_1 ... current_6

Attribut Valeur
Unité A
device_class current
state_class measurement
accuracy_decimals 3

Courant efficace RMS pour les canaux 0, 1, 2, ... Le canal 0 est la pince CT principale ; les canaux 1 et 2 sont présents sur les variantes UI2 / UI3 et I2 / I3, les canaux 3..6 sur les variantes à plus de canaux.

Sur un module BASIC, le nombre de canaux actifs est déduit du nombre d'emplacements déclarés : si seul current est déclaré, le composant utilise 1 canal ; avec current et current_1, 2 ; en ajoutant current_2, 3. Sur un module STANDARD, le nombre de canaux vient du module lui-même ; les emplacements déclarés au-delà ne publient simplement jamais.

YAML
current:
  name: "Phase Current"
current_1:
  name: "Load 1 Current"
current_2:
  name: "Load 2 Current"

power / power_1 ... power_6

Attribut Valeur
Unité W
device_class power
state_class measurement
accuracy_decimals 1
Dépendances power nécessite current + voltage ; power_N nécessite current_N + voltage

Puissance active en watts, signée. Valeurs négatives = flux inverse (injection vers le réseau) sur les modules STANDARD. Sur BASIC, les valeurs instantanées négatives dans la fenêtre de période sont ramenées à 0 au niveau du firmware — la moyenne par période est ≥ 0. La puissance active instantanée peut encore se lire négative au moment de la production.

Déclarer power sans current + voltage lève une erreur de validation : power requires current to also be declared.

YAML
power:
  name: "Active Power"

energy / energy_1 ... energy_6

Attribut Valeur
Unité Wh
device_class energy
state_class total_increasing
accuracy_decimals 3
Dépendances energy requiert current + voltage ; energy_N requiert current_N + voltage

Énergie consommée (import) cumulée en Wh pour le canal.

  • Modules STANDARD — le composant accumule les compteurs d'énergie propres du module. Les totaux survivent aux redémarrages de l'ESP32 et du module et sont monotones (ils ne reculent pas lorsque le module redémarre ou qu'un compteur est remis à zéro).
  • Modules BASIC — calculé sur l'ESP32 à partir de la puissance moyenne de période renvoyée par le module après chaque instantané :
Text
E_Wh[ch] += avg_P_W[ch] * master_dt_s / 3600

Dans les deux cas, la valeur est sauvegardée en flash de l'ESP32 (NVS) toutes les 5 minutes et à l'arrêt propre (redémarrage / OTA), puis restaurée avant le premier publish_state au démarrage — ceci empêche le tableau de bord Énergie de HA d'interpréter un 0 instantané comme une remise à zéro du compteur. Sur BASIC, une coupure brutale fait perdre au plus les 5 dernières minutes d'énergie (≈ 5 Wh à une moyenne de 60 W). Lorsque la disposition NVS change (montée de version), le compteur repart de 0.

state_class: total_increasing est requis pour le tableau de bord Énergie de HA. La valeur croît de façon monotone ; elle ne diminue pas en fonctionnement normal.

YAML
energy:
  name: "Mains Energy"

energy_exported / energy_exported_1 / energy_exported_2

Attribut Valeur
Unité Wh
device_class energy
state_class total_increasing
accuracy_decimals 3
Dépendances Nécessite current + voltage + bidirectional: true

Énergie exportée (production) en Wh pour les canaux 0..2, accumulée séparément de energy. Définissez bidirectional: true dans le bloc rbamp: lors de la déclaration de ces capteurs. Sur les modules STANDARD, les valeurs proviennent des compteurs du module (persistants, monotones). Sur les modules BASIC, les capteurs sont acceptés mais publient 0.

power_factor / power_factor_1 ... power_factor_6

Attribut Valeur
Unité (dimensionless)
device_class power_factor
state_class measurement
accuracy_decimals 3
Dépendances Exige current + voltage pour l'emplacement correspondant

Facteur de puissance dans la plage −1..+1. Un FP négatif signifie une charge en avance ou en retard ; la convention de signe est définie par le firmware. Le filtre de cohérence (§B.5) rejette les valeurs hors de |pf| > 10000 ; il n'y a pas de borne inférieure.

YAML
power_factor:
  name: "Power Factor"

reactive_power / reactive_power_1 / reactive_power_2

Attribut Valeur
Unité VAr
device_class reactive_power
state_class measurement
accuracy_decimals 1
Dépendances Exige current + voltage pour l'emplacement correspondant

Puissance réactive en var. Non signée (≥ 0), calculée comme √(S² − P²), inclut la distorsion ; aucune précision indiquée. Les charges inductives et capacitives ne sont pas distinguées. Lue depuis le module à chaque cycle update() ; publiée pour les canaux 0..2 seulement (reactive_power_3 ... reactive_power_6 sont acceptés par le schéma mais ne publient jamais). Aucune précision n'est indiquée pour la puissance réactive.

YAML
reactive_power:
  name: "Reactive Power"
Remarque

Remarque sur device_class: reactive_power — ESPHome l'accepte (la constante DEVICE_CLASS_REACTIVE_POWER) et la valeur est transmise à Home Assistant. Cependant, la liste officielle des device_class de Home Assistant a évolué : dans certaines versions reactive_power est disponible dans l'interface et fonctionne avec l'unité VAr, tandis que dans d'autres il s'affiche comme capteur générique, sans icône spécialisée ni conversion d'unité. Les données sont toujours publiées (c'est un simple state) ; seule la façon dont HA affiche le capteur dans Lovelace varie. Si le capteur apparaît comme inconnu dans votre version de HA, c'est cosmétique, pas une régression fonctionnelle. Supprimez la clé reactive_power: du YAML si vous n'utilisez pas ce capteur.

apparent_power

Attribut Valeur
Unité VA
device_class apparent_power
state_class measurement
accuracy_decimals 1
Source Calculé sur le maître : S = V_rms × I_rms[0]
Dépendances Nécessite current + voltage

Puissance apparente en VA. Calculée par le composant à partir des valeurs U_rms et I0_rms lues dans le même cycle update() — aucun registre séparé n'est lu. Les deux lectures doivent réussir dans le même cycle ; si une seule échoue (nouvelles tentatives épuisées), aucun état n'est publié dans ce cycle et la dernière valeur dans HA est conservée.

apparent_power est dans SHARED_FIELDS et fonctionne avec toute topologie, mais dépend de voltage et current pour le calcul V × I.

YAML
apparent_power:
  name: "Apparent Power"

2.2 Champs phasés (variantes à plusieurs tensions)

Pour les modules avec plus d'une entrée de tension (variantes biphasées et triphasées), les capteurs sont déclarés par phase. Le schéma accepte le groupe phasé sur tout module ; un emplacement ne publie que si le module connecté signale réellement le canal correspondant, sinon il reste sans valeur.

Les champs monophasés et phasés sont mutuellement exclusifs au sein d'un même bloc sensor:. Le validateur lève une erreur :

Text
Cannot mix single-phase fields (voltage, current, current_1, ...) with
phased fields (voltage_a/b/c, current_a/b/c, ...).

Tous les champs phasés partagent les mêmes valeurs par défaut de sensor_schema que leurs équivalents monophasés (mêmes unités, device_class, state_class, accuracy_decimals).

Champ Unité device_class
voltage_a / _b / _c V tension
current_a / _b / _c A courant
power_a / _b / _c W power
power_total W power
energy_a / _b / _c Wh energy
energy_exported_a / _b / _c Wh energy
power_factor_a / _b / _c — power_factor
reactive_power_a / _b / _c VAr reactive_power
voltage_angle_b / _c ° —

voltage_angle_b et voltage_angle_c publient l'angle de phase des tensions B et C en degrés, par rapport à la phase A (la phase A est la référence à 0°, il n'y a donc pas de voltage_angle_a). Elles nécessitent un firmware du module qui fournit les angles ; sur un firmware plus ancien, le composant journalise un avertissement au démarrage et les capteurs ne publient jamais. Tant que l'angle ne peut être déterminé, la valeur est « inconnue ».

Remarque

La validation de dépendance par phase n'est pas imposée pour les champs par phase (seulement _SINGLE_SLOT_DEPS pour le monophasé).

Example:

YAML
rbamp:
  id: panel_meter
  address: 0x50

sensor:
  - platform: rbamp
    rbamp_id: panel_meter
    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_total:
      name: "Total Active Power"
    voltage_angle_b:
      name: "Phase B Angle"
    voltage_angle_c:
      name: "Phase C Angle"

2.3 Champs partagés (indépendants de la topologie)

Ces champs fonctionnent dans tout groupe de topologie, y compris le cas où aucun capteur de courant monophasé ou phasé n'est déclaré (déploiement tension seule ou fréquence seule).

frequency

Attribut Valeur
Unité Hz
device_class frequency
state_class measurement
accuracy_decimals 0

Fréquence du secteur. Les valeurs non plausibles (le module indique « pas encore mesuré ») sont écartées sans publication, ce qui évite une transition « Inconnue » → 0 Hz → 50 Hz dans l'entité HA pendant le préchauffage.

YAML
frequency:
  name: "Mains Frequency"

apparent_power

Voir l'entrée sous les champs individuels ci-dessus. apparent_power requiert current et voltage, il doit donc figurer dans un bloc de capteur monophasé.

energy_total / energy_exported_total / energy_net

Capteur Unité state_class Signification
energy_total Wh total_increasing Énergie importée, tous les canaux du module
energy_exported_total Wh total_increasing Énergie exportée, tous les canaux du module
energy_net Wh total Import moins export. Peut diminuer.

Totaux généraux sur tous les canaux du module, issus des compteurs d'énergie propres du module (modules STANDARD). Ils survivent aux redémarrages de l'ESP32 et du module, sont monotones à travers les redémarrages du module et les remises à zéro des compteurs (sauf energy_net, qui est la différence de deux valeurs monotones), et sont aussi sauvegardés en NVS toutes les 5 minutes et à l'arrêt propre. Ils n'ont besoin ni de la clé bidirectional: ni d'une déclaration compagnon current/voltage.

Sur un module sans compteurs d'énergie embarqués (BASIC), ces clés se valident mais ne publient jamais ; le composant journalise un avertissement au démarrage. Utilisez-y les capteurs energy par canal.

YAML
sensor:
  - platform: rbamp
    rbamp_id: meter1
    energy_total:
      name: "Energy Imported"
    energy_exported_total:
      name: "Energy Exported"
    energy_net:
      name: "Energy Net"

reactive_energy / reactive_energy_exported

Attribut Valeur
Unité varh
state_class total_increasing
accuracy_decimals 3

Énergie réactive (import / export) sur tous les canaux, issue des mêmes compteurs embarqués et avec la même persistance que energy_total. Modules STANDARD uniquement ; sur les autres, les clés valident mais ne publient jamais.

phase_sequence

Attribut Valeur
Unité —
accuracy_decimals 0

Rotation de phase d'un module à trois tensions : 1 = sens direct, 2 = sens inverse, 3 = anormal. « Unknown » tant que cela ne peut être déterminé (moins de trois entrées de tension actives). Nécessite un firmware de module qui le fournit ; sinon le composant journalise un avertissement au démarrage et le capteur ne publie jamais. Dans un lambda, id(meter1).get_phase_sequence_str() renvoie "forward", "reverse", "abnormal", "n/a" ou "unavailable".


2.4 Règles de validation du schéma

Le validateur Python _validate_topology_consistency applique deux catégories de règles lors de esphome config / compilation — avant l'exécution de tout code C++.

Exclusion mutuelle des topologies

Les champs monophasés (voltage, current, current_1, etc.) et les champs phasés (voltage_a, voltage_b, etc.) ne peuvent pas coexister dans un même bloc sensor:. Une tentative de les mélanger :

Text
Cannot mix single-phase fields (voltage, current, current_1, ...) with
phased fields (voltage_a/b/c, current_a/b/c, ...). Pick one group based
on your rbAmp SKU.

Le groupe phasé inclut voltage_angle_b / voltage_angle_c.

Exigences de compagnon par emplacement (monophasé uniquement)

Chaque champ dérivé nécessite les champs d'entrée dont le module a besoin pour le calculer :

Champ déclaré Compagnons requis
power / _1 ... _6 current (ou _1 ... _6, même suffixe) + voltage
energy / _1 ... _6 current (ou _1 ... _6, même suffixe) + voltage
power_factor / _1 ... _6 current (ou _1 ... _6, même suffixe) + voltage
reactive_power / _1 / _2 current (ou _1 ... _6, même suffixe) + voltage
apparent_power current + voltage

energy_exported*, energy_total, energy_exported_total, energy_net, reactive_energy* et phase_sequence n'ont aucune exigence de capteur compagnon.

Un compagnon manquant déclenche :

Text
`power` requires `current` to also be declared — the underlying chip
cannot compute it without that input.

Autres règles au niveau du bloc rbamp:

Règle Description
ct_model: ↔ ct_models: s'excluent mutuellement Un seul des deux peut être utilisé par bloc rbamp: — sinon erreur de validation.
new_address ≠ address Si elles concordent — cv.Invalid.
address dans la plage 0x08..0x77 cv.i2c_address est appliqué.
update_interval ≥ 1s Les intervalles plus courts sont rejetés.
latch_interval ≥ update_interval Une cadence d'instantané plus courte est rejetée.
ct_models: a de 1 à 16 entrées Les listes plus longues sont rejetées.
group_id va de 0 à 255 Les valeurs hors plage sont rejetées.
start_current_ua vaut 0 ou 10..2540 par pas de 10 Toute autre valeur est rejetée.
ct_model_force: true exige ct_model: ou ct_models: Rejeté seul.
period_banks: — chaque bank une fois, interval ≥ 1s Un doublon de banque, une banque hors de 0..7 ou un intervalle plus court est rejeté.
Code de modèle CT valide pour le sensor_class épinglé Un code non autorisé pour la classe est rejeté, avec la liste des valeurs autorisées.

Toutes les erreurs de validation sont signalées pendant 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.


3. Flux de données et temporisation

Le déroulement conceptuel d'un cycle update() :

Text
Module (autonomous)                  ESP32 (ESPHome component)
─────────────────────────────────   ────────────────────────────────────────────
Measures & computes the
instantaneous block (RMS / P / PF / Q)
  ↓ (~100 ms per cycle)
Atomically publishes the block       update() fires every update_interval (60 s)
of instantaneous registers            ↓
  ↓                                 phase 1 — snapshot:
                                      write the snapshot command
Closes the period accumulator,        50 ms timeout (non-blocking)
opens a new one                       ↓ (main loop keeps running)
  ↓
  wait 50 ms                        phase 2 — period snapshot:
                                      read the valid flag
                                      read per-channel average powers
                                      E_Wh[ch] += avg_P × dt_s / 3600
                                      save to NVS if 5 minutes elapsed
                                      ↓
                                    phase 3 — instantaneous values:
                                      read the status register
                                      read U_rms, I[0..n]_rms, P[0..n],
                                            PF[0..n], Q[0..n], frequency
                                      publish all bound sensors
                                      ↓
                                    Push state to HA over the native API
Remarque

Le schéma montre le flux basé sur les instantanés du BASIC. Un module STANDARD conserve ses propres compteurs d'énergie : à chaque update(), le composant lit les valeurs instantanées et l'instantané des compteurs (une transaction cohérente) et ajoute la différence à ses totaux courants, de sorte que l'étape d'instantané n'est pas utilisée pour l'énergie.

Temporisations caractéristiques :

Événement Cadence
Validation interne du bloc instantané par le module ~100 ms
Appel update() update_interval (60 s par défaut)
Délai de stabilisation après la commande d'instantané 50 ms (non bloquant)
Sauvegarder en NVS Toutes les 5 minutes
Pause entre les nouvelles tentatives par octet 5 ms, jusqu'à 3 tentatives
Fenêtre d'écriture flash lors de l'écriture du modèle ~700 ms (le module renvoie NACK pendant toute la durée)

La temporisation de stabilisation de l'instantané n'est pas bloquante — l'ordonnanceur coopératif d'ESPHome continue de servir le WiFi, l'API et les autres composants pendant les 50 ms d'attente. Les phases restantes de update() (lecture des registres instantanés) s'exécutent immédiatement au retour de la phase d'instantané.

L'avertissement [W][component:522]: rbamp took a long time for an operation (XXX ms) est attendu et sans danger lorsqu'il apparaît. Sur le firmware v1.3, le composant lit le bloc de valeurs instantanées par une lecture en rafale unique (READ auto-incrément), de sorte qu'un cycle sain reste bien en dessous de 30 ms. L'avertissement apparaît lorsque le chemin en rafale retombe sur des lectures registre par registre (4 transactions par flottant, jusqu'à 36 transactions à 50 kHz, plus les nouvelles tentatives) — généralement à cause d'un bus marginal ou d'un firmware hérité sans la capacité de lecture en rafale.


4. Réglages du bus I2C

Le composant rbamp hérite du bus I²C configuré dans le bloc de premier niveau i2c:. Réglages recommandés sur le firmware actuel :

YAML
i2c:
  sda: GPIO21
  scl: GPIO22
  frequency: 50kHz   # 100 kHz causes periodic NACKs; 50 kHz reduces them ~5x
  scan: true         # optional: logs the addresses found at boot

Vitesse du bus : utilisez 50kHz sur les maîtres basés sur ESP-IDF (ESP32 avec ESPHome ou Arduino). Le module envoie périodiquement des NACK à 100 kHz (une part notable des transactions) en raison d'une interaction connue avec le pilote ESP-IDF i2c_master (confirmée dans esp-idf issue #9426, marquée « Won't Do » par Espressif). Les firmwares v1.1/v1.3 ont durci le côté module, mais l'interaction avec le pilote persiste — 50 kHz reste la recommandation permanente. La triple atténuation du composant (relance + cohérence + 50 kHz) ramène le taux effectif de lectures erronées sous 1 %.

Résistances de tirage : 4.7 kΩ vers 3.3 V sur SDA et SCL sont recommandées. Des valeurs plus élevées (10 kΩ) augmentent le temps de montée et le taux de NACK à 100 kHz.

Appareils multiples : le bus I²C de l'ESP32 prend en charge jusqu'à 112 appareils à des adresses 7 bits distinctes. Utilisez address: et new_address: pour attribuer une adresse unique à chaque module. scan: true dans le bloc i2c: journalise chaque adresse qui répond au démarrage — vérifiez que chaque module est détecté avant d'activer l'interrogation par période.

Remarque

La table complète des registres au niveau du fil et le jeu de commandes du module figurent sur la page publique de référence API. Pour l'utilisateur type du schéma YAML, ce chapitre suffit — chaque registre est masqué derrière l'interface déclarative du composant.


5. Surface d'identité (v1.3 NOUVEAU) — méthodes C++ publiques

Le composant v1.3 expose des accesseurs d'identité et de diagnostic utilisables depuis un lambda: YAML et via la plateforme template. Toutes les méthodes renvoient une std::string (pour la compatibilité text_sensor) ou des types primitifs — aucune exception n'est levée, tout passe par l'état en cache.

Méthode Type de retour Source Description
get_variant_str() std::string REG_HW_VARIANT (0x55) "UI1"/"UI2"/"UI3"/"I1"/"I2"/"I3"/"UNK" — la variante du module
get_capability_hex() std::string registre de capacités "0xNNNN" — le bitmap de capacités sur 16 bits, pour le diagnostic
get_uid_hex() std::string REG_UID (0x5C × 12 octets) 24 caractères hexadécimaux (UID de puce 96 bits)
get_last_error_str() std::string REG_ERROR (0x02) "OK"/"ERR_PARAM"/"ERR_BUSY"/"ERR_LATCH"/"ERR_CRC"
get_event_flags() uint8_t REG_EVENT_FLAGS (0x03) bits collants : bit3=ERR_LATCH, bit5=ADDR_CHANGED, etc.
get_firmware_version() uint8_t REG_VERSION (0x01) l'octet de version du module (par exemple 0x04 sur le firmware BASIC v1.3)
get_std_image_version() uint32_t STANDARD uniquement Version de l'image du module en fonctionnement ; 0 = inconnue ou BASIC
get_phase_sequence_str() std::string STANDARD uniquement "forward"/"reverse"/"abnormal"/"n/a"/"unavailable"
read_start_current_ua() uint16_t STANDARD uniquement Lecture fraîche du courant de démarrage stocké en µA ; 65535 = indisponible
read_gc_tick_received() uint16_t REG_GC_LAST_TICK (0x58) dernière valeur de tick capturée depuis la trame GC
get_capability_cached() uint16_t bitmap de capacités en cache le bitmap lu au démarrage, sans transaction sur le bus

Mise en cache : variant / capability / uid / firmware_version sont lus une seule fois dans setup() et mis en cache — les appels répétés ne vont pas sur le bus. last_error_str() / event_flags() / gc_tick sont lus à chaque appel pour la fraîcheur.

Utilisation via un text_sensor template

YAML
text_sensor:
  - platform: template
    name: "Mains variant"
    update_interval: 30s
    lambda: 'return id(mains_meter).get_variant_str();'
    # → entity_id: sensor.mains_variant, value: "UI1"

  - platform: template
    name: "Mains capability"
    update_interval: 30s
    lambda: 'return id(mains_meter).get_capability_hex();'
    # → the capability bitmap as hex, "0xNNNN" (diagnostics only)

  - platform: template
    name: "Mains UID"
    update_interval: 30s
    lambda: 'return id(mains_meter).get_uid_hex();'

  - platform: template
    name: "Mains last error"
    update_interval: 30s
    lambda: 'return id(mains_meter).get_last_error_str();'

  - platform: template
    name: "Mains firmware version"
    update_interval: 30s
    lambda: 'char b[8]; snprintf(b, sizeof(b), "0x%02X", id(mains_meter).get_firmware_version()); return std::string(b);'

Ces text_sensors apparaissent dans HA sous la forme sensor.mains_variant, etc. — pratiques pour les tableaux de bord d'inventaire, le suivi d'actifs et la vérification après flash.

À utiliser via lambda: dans les automatisations

YAML
sensor:
  - platform: rbamp
    rbamp_id: mains
    energy: { name: "Mains Energy" }

# Read the stored values from a lambda (e.g. in an on_boot automation)
esphome:
  on_boot:
    then:
      - lambda: |-
          ESP_LOGI("meter", "variant=%s", id(mains).get_variant_str().c_str());

6. Synchronisation flotte et GC (v1.3 NOUVEAU)

transmit_gc_frame() — émission GC programmatique

C++
bool transmit_gc_frame();

Émet une trame d'instantané General-Call de 5 octets à l'adresse de bus 0x00. L'octet de groupe est le group_id: de l'instance et le tick est un compteur auto-incrémenté ; la méthode renvoie true lorsque l'écriture sur le bus a réussi. Modules BASIC uniquement — sur un module STANDARD, elle journalise un avertissement et ne fait rien :

Text
START | 0x00 | A | 0xA5 | A | 0x27 | A | group | A | tick_lo | A | tick_hi | A | STOP

Tous les modules avec fleet_gc_enable: true + un group_id: correspondant (ou group_id: 0) prennent un instantané de leurs accumulateurs de période simultanément, à un instant filaire unique. La valeur de tick est stockée par chaque module pour la vérification de synchronisation (read_gc_tick_received()).

Émission automatique : le composant émet une trame GC automatiquement dans update() si fleet_gc_enable: true et que le firmware annonce l'instantané par appel général. Une émission manuelle n'est nécessaire que pour une synchronisation supplémentaire (par exemple sur un déclencheur d'événement côté HA).

Vérification de capacité : si le firmware n'annonce pas l'instantané General-Call — avertissement, aucune émission.

fleet_apply_now() — force une nouvelle application lecture-comparaison-écriture

C++
bool fleet_apply_now();

Répète de force la relecture-comparaison-écriture pour les réglages de flotte : relit la configuration de flotte du module et l'identifiant de groupe, les compare avec fleet_gc_enable: / group_id: du YAML et écrit la différence. Renvoie false (et ne fait rien) sur un module STANDARD.

Cas d'usage : après une remise aux valeurs par défaut du module avec un outil de débogage, ou pour vérifier après OTA que la configuration de flotte a bien été appliquée.


7. Services API natifs (v1.3 NOUVEAU) — automatisations de récupération

Le composant v1.3 n'enregistre pas les services automatiquement — c'est le YAML qui le fait. Mais les méthodes publiques write_clear_error() / write_reset() / transmit_gc_frame() sont conçues pour être utilisées via le motif api: services:. Recettes canoniques :

YAML
api:
  port: 6053

  services:
    # Recovery: clear REG_ERROR + EVENT_FLAGS bit3
    - service: mains_clear_error
      then:
        - lambda: 'id(mains).write_clear_error();'

    # Maintenance: soft reset (preserves flash)
    - service: mains_reset
      then:
        - lambda: 'id(mains).write_reset();'

    # Fleet: manual GC snapshot (beyond the auto-emit in update())
    - service: fleet_latch_now
      then:
        - lambda: 'id(mains).transmit_gc_frame();'   # group = this instance's group_id, tick auto-increments

    # Maintenance: force fleet-config re-apply (post-OTA verify)
    - service: mains_fleet_apply
      then:
        - lambda: 'id(mains).fleet_apply_now();'

Ensuite, HA peut appeler les services depuis les automatisations :

YAML
automation:
  - alias: "Auto-clear meter error on detection"
    trigger:
      platform: state
      entity_id: sensor.mains_last_error
      from: "OK"
    action:
      - delay: 60s   # wait one update_interval to confirm a persistent error
      - service: esphome._mains_clear_error
      - condition: state
        entity_id: sensor.mains_last_error
        state: "ERR_PARAM"
      - service: persistent_notification.create
        data:
          title: "Meter parameter error"
          message: "Meter at {{ states('sensor.mains_capability') }} reports ERR_PARAM after auto-clear retry. Check YAML config."

8. Erreur et récupération (v1.3) — REG_ERROR vs EVENT_FLAGS bit3

En v1.3, le module dispose de deux canaux d'erreur indépendants :

Canal Registre Sémantique du verrou (latch) Effacement
Synchronisation (dernière écriture) REG_ERROR (0x02) la dernière écriture l'emporte, écrasée par l'opération suivante write_clear_error() ou l'opération réussie suivante
Asynchrone durable REG_EVENT_FLAGS bit3 (0x03) collant, réarme pendant quelques centaines de millisecondes si la cause première n'est pas résolue write_clear_error() (une seule opération efface les deux)

Schéma de lecture

C++
// Sync — fresh after the last operation
std::string err = id(mains).get_last_error_str();    // "ERR_PARAM" / "OK" / ...

// Durable — sticky bit3, sees errors even between polls
uint16_t flags = id(mains).get_event_flags();
bool latched_error = (flags & (1 << 3)) != 0;

Sémantique de récupération

Effacer REG_ERROR seul ne suffit pas si le firmware réarme le bit3 :

C++
id(mains).write_clear_error();                       // clears REG_ERROR + EVENT bit3
delay(300);                                          // wait for the re-latch window
uint16_t flags_after = id(mains).get_event_flags();
if (flags_after & (1 << 3)) {
    // Root cause not resolved — firmware re-latched bit3
    ESP_LOGW("rbamp", "ERROR persists after clear — check config / param");
}

Pour une récupération complète :

  1. Supprimez la cause (corrigez le code de modèle CT dans le YAML, corrigez sensor_class).
  2. write_clear_error() — efface REG_ERROR + le bit3 de EVENT_FLAGS.
  3. Vérifiez via get_event_flags() après ~300 ms que le bit3 n'est pas réarmé.

Voir 10_troubleshooting.md §6 Erreur et récupération.


Source et problèmes : rb-amp/rbamp-esphome · cette page dans le dépôt : docs/09_api_reference.md (v1.9.1)