01 · Vue d'ensemble
Qu'est-ce que rbAmp
rbAmp est un module matériel compact pour la mesure de précision des paramètres du secteur alternatif. Du point de vue de l'intégrateur, c'est un esclave I²C ordinaire : alimentez, lisez un registre, et vous obtenez une valeur prête à l'emploi en unités physiques. Aucun traitement du signal n'est requis côté maître. L'étalonnage d'usine est effectué une fois en production et stocké dans la flash du module ; il ne reste à l'utilisateur qu'à choisir le modèle de pince CT (voir 03_sensor_selection.md) et à câbler le bus.
Flux de données (en une ligne)
L'argument clé : les grandeurs physiques arrivent du module prêtes à l'emploi. Côté ESP32, il n'y a ni traitement du signal, ni tables de calibrage, ni calcul RMS/puissance. Le composant ESPHome est un client I²C léger + un accumulateur d'énergie + une couche de publication vers HA. Aucun calcul lambda: n'est requis pour le fonctionnement de base.
rbAmp dans l'écosystème ESPHome
Si vous avez déjà utilisé les compteurs d'énergie intégrés (pzemac via UART, atm90e32 via SPI, cse7766 via UART), c'est exactement la même structure. Le composant rbamp est un « bon citoyen » d'ESPHome : il utilise le transport standard i2c:, la syntaxe standard sensor.platform: rbamp, des emplacements de capteurs standard avec device_class / state_class / unit_of_measurement, et prend en charge l'ensemble standard des filtres et propriétés de capteurs.
Comparez l'anatomie (le modèle mental est identique) :
# ATM90E32 (SPI meter) — shown for comparison only, not part of an rbAmp config:
spi:
clk_pin: GPIO18
miso_pin: GPIO19
mosi_pin: GPIO23
sensor:
- platform: atm90e32
cs_pin: GPIO5
voltage_a:
name: "Mains Voltage"
power_a:
name: "Mains Power"
# rbAmp (I²C meter) — a separate file, do not paste both:
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz
rbamp:
id: meter1
address: 0x50
sensor:
- platform: rbamp
rbamp_id: meter1
voltage:
name: "Mains Voltage"
current: # power needs voltage AND current declared
name: "Mains Current"
power:
name: "Mains Power"
Les seules différences sont le transport (i2c: au lieu de spi:) et le fait que rbamp: est déclaré comme bloc séparé (il a besoin d'un id: + address: pour un bus multi-modules). Le reste est de l'ESPHome classique : les noms d'emplacements (voltage, current, power, energy, frequency, power_factor) sont reconnaissables, et la personnalisation (name, update_interval, accuracy_decimals, filters:) fonctionne comme d'habitude. Pour un exemple de personnalisation détaillé, voir 06_examples.md §1.1 « UI1 avec personnalisation — tous les réglages ESPHome standard ».
Déploiement canonique — une flotte multi-modules
Le cas d'usage principal de rbAmp dans ESPHome est la surveillance de plusieurs charges depuis un maître ESP32 unique. Une maison, un atelier ou un tableau dispose généralement d'une arrivée secteur et de plusieurs branches : un chauffe-eau, une climatisation, un VE, des pièces individuelles. Un rbAmp UI1 est placé sur l'arrivée et compte la puissance et l'énergie totales ; plusieurs modules rbAmp I2/I3 sont placés sur les branches et ne comptent que les courants de chaque canal.
Tous les modules vivent sur un bus I²C unique de l'ESP32 — chacun avec son adresse dans la plage 0x50..0x77. Le composant prend en charge MULTI_CONF = True, donc un seul fichier YAML peut déclarer plusieurs blocs rbamp: et les publier tous comme ensembles d'entités indépendants dans Home Assistant.
Dans ce scénario, l'ESP32 est le seul maître : il émet une diffusion General-Call snapshot partagée lorsque fleet_gc_enable: true, et tous les modules démarrent atomiquement une nouvelle période d'accumulation à un instant unique sur le fil. Cela donne une synchronisation serrée entre les sous-compteurs — les sommes des canaux concordent avec la somme du départ à la durée d'une seule période près.
Une configuration mono-module (UI1 sur le secteur, sans sous-compteurs) est le cas minimal, non le canon. En v1.3, les deux sont valides ; la configuration multi-modules est recommandée dès le premier chapitre de la documentation, car 80 % des déploiements sur le terrain sont exactement de ce type.
Ce que vous mesurez
| Grandeur | Emplacement YAML | Plage | Précision typique |
|---|---|---|---|
| Tension efficace (RMS) | voltage |
0..300 V | ±0.5% |
| Courant RMS (par canal) | current / current_1 / current_2 |
0..100 A (selon la référence) | ±0.5..1 % (module) |
| Puissance active (signée) | power / power_1 / power_2 |
±23 kW | ±1 % (module) |
| Facteur de puissance (signé) | power_factor / power_factor_1 / power_factor_2 |
−1..+1 | ±0.01 à PF ≈ 1 (charge résistive) avec des capteurs SCT-013 de calibre 10 A et plus ; le capteur 5 A ajoute jusqu'à ~0.015 d'erreur de lecture par son propre déphasage — une charge purement résistive lit ~0.985–0.993 |
| Puissance réactive (non signée, √(S² − P²), inclut la distorsion ; aucune précision indiquée) | reactive_power / reactive_power_1 / reactive_power_2 |
identique à P | — |
| Puissance apparente | apparent_power (CH0 uniquement ; pour CH1/CH2 utilisez un capteur de modèle HA, voir Intégrations DIY §6) |
identique à P | ±2% |
| Fréquence du secteur | frequency |
50 / 60 Hz (détecté sur BASIC) | — |
| Énergie accumulée (Wh) | energy / energy_1 / ... (par canal) ; energy_total / energy_exported_total / energy_net (STANDARD (STD), tous les canaux) |
64-bit | dépend de la précision P |
| Énergie réactive (varh) | reactive_energy / reactive_energy_exported (STANDARD) |
64-bit | — |
Ce sont les chiffres propres au module. Ce que vous lisez correspond au module plus le capteur que vous montez ; le total dépend donc du capteur et de son calibre : les planchers détectables, les planchers lisibles et les classes de précision par calibre pour la famille SCT-013 sont publiés dans le tableau de précision BASIC. Les modules avec un capteur CT appairé en usine, ainsi que les modules STD, y sont spécifiés séparément.
Des emplacements existent pour jusqu'à sept canaux de courant (current_3 ... current_6 et les power_N, energy_N, power_factor_N correspondants sur les variantes à plus de canaux).
Toutes les grandeurs instantanées sont mises à jour par le module de façon autonome, par pas d'environ 100 ms. Sur les modules BASIC, l'accumulation en Wh est faite par l'ESP32 à partir de la puissance moyenne renvoyée par le module sur l'intervalle entre deux appels update() ; sur les modules STANDARD, le composant accumule les compteurs d'énergie propres du module. Le composant ESPHome masque ces protocoles — l'utilisateur ne voit que des entités de capteurs prêtes à l'emploi dans Home Assistant.
Ce que le composant ESPHome ajoute
- Capteurs HA prêts à l'emploi — chaque slot a déjà son
device_class, sonstate_classet ses unités définis. Le capteurenergyapparaît immédiatement dans le tableau de bord Énergie, sans configuration manuelle. - Un seul YAML pour les deux lignes de modules — au démarrage, le composant détermine si un module BASIC ou STANDARD est connecté et tire le nombre de canaux, la variante et les fonctions du module lui-même.
topology:n'est pas nécessaire. Les clés qui ne concernent qu'une génération sont ignorées avec une ligne de journal sur l'autre. - Énergie embarquée (STANDARD) — le module conserve ses propres compteurs cumulés ; le composant les accumule, donc les totaux survivent aux redémarrages de l'ESP32 et du module et restent monotones. Capteurs de totaux généraux :
energy_total,energy_exported_total,energy_net,reactive_energy,reactive_energy_exported.start_current_ua:fixe le courant en dessous duquel un canal ne compte aucune énergie. - Persistance NVS des Wh — l'énergie totale est écrite dans la flash de l'ESP32 toutes les 5 minutes (et lors d'un arrêt propre, afin qu'un redémarrage ou une OTA ne perde pas le dernier intervalle) et restaurée avant le premier
publish_state. Home Assistant ne voit jamais de zéro momentané après un redémarrage et ne l'interprète jamais comme une remise à zéro du compteur. - Configuration déclarative des capteurs — deux lignes YAML (
sensor_class:+ct_models:pour UI3, ouct_model:pour UI1) figent la famille et le modèle de pince pour chaque canal. Les coefficients d'usine sont chargés automatiquement par le module — aucune étape de calibrage dans la séquence de démarrage. - Calendrier d'interrogation via
PollingComponent::update()avec unupdate_intervalconfigurable (60 s par défaut). - Cadences de lecture RT et d'instantané découplées (v1.4+) — la clé facultative
latch_interval:permet au cycle instantané → intégration en Wh de tourner à sa propre cadence, tandis queupdate_interval:continue de contrôler la fréquence de lecture du bloc temps réel V/I/P/PF/Q par le composant ESPHome. Usage typique :update_interval: 3s+latch_interval: 60s— valeurs du tableau de bord rafraîchies toutes les 3 s, charge d'instantané sur le bus une seule fois par minute. L'intégration de l'énergie n'ajoute aucune erreur propre au-delà de la précision de puissance active du module (l'intégration côté maître utilise le dt réel entre événements d'instantané). - Résilience aux NACK — une discipline en trois couches est implémentée : 50 kHz par défaut, relance par octet et filtre de cohérence NaN/Inf. Détails ci-dessous.
- Attribution d'adresse en un seul passage — la clé
new_address:modifie l'adresse I²C du module en un seul cycle de démarrage. Sur le firmware v1.3, elle fonctionne en mode production sans verrouillage du provisionnement usine (validation d'adresse en deux phases, détectée automatiquement). Pratique pour la configuration en série d'un lot d'appareils une fois installés dans un tableau. - Bus multi-modules —
MULTI_CONF = Truepermet de déclarer plusieurs blocsrbamp:sur un ESP32 et de les interroger tour à tour. - Synchronisation de flotte par appel général (v1.3) — la clé
fleet_gc_enable: trueactive la réception de la diffusion d'instantané GC depuis l'ESP32. Tous les modules avec ce drapeau et ungroup_id:correspondant démarrent une nouvelle période simultanément. Conditionnée par la capacité ; sur le firmware historique, elle journalise un avertissement et passe sans appliquer. Modules BASIC uniquement. - Surface d'identité (v1.3) — les méthodes publiques
get_variant_str()/get_capability_hex()/get_uid_hex()/get_firmware_version()/get_last_error_str()sont accessibles depuislambda:et via untext_sensor.platform: template. Elles permettent d'exposer dans HA la variante courante du module (UI1/UI3/I2…), sa matrice de capacités, son UID et sa version de firmware. - Démarrage lecture-comparaison-écriture (v1.3) —
sensor_class:/ct_model:/ct_models:ne sont écrits en flash que si la valeur demandée diffère de la valeur stockée. La réécriture de configuration au démarrage passe d'environ 2.8 s (installation neuve UI3) à ~0 ms sur une configuration stable. L'ancien conseil « retirerct_model:du YAML après vérification » est obsolète — la configuration est idempotente. - Protection de la calibration d'usine (v1.8.1+) — sur un module calibré en couple avec son propre capteur intégré (
WIRED_CT/BUILTIN_CT), un changement de classe ou de modèle depuis le YAML est refusé avec une ligne de journal. L'option de servicect_model_force: truele contourne délibérément. - La bascule de calibre SCT conserve la précision (v1.9) — sélectionner un autre calibre SCT-013 via
ct_model:conserve la calibration d'usine unitaire : sur les firmwares jusqu'à 1.4.19, le composant termine la bascule avec le redémarrage requis du module et met à l'échelle les relevés ; les firmwares plus récents le font sur le module.
Architecture
Le moteur de mesure réside dans le module ; l'ESP32 sert de pont vers HA. Sur les modules BASIC, les Wh sont intégrés sur l'ESP32 par rapport à sa propre horloge, ce qui garde l'accumulation cohérente entre plusieurs modules. Les modules STANDARD conservent eux-mêmes leurs compteurs d'énergie cumulée et l'ESP32 les accumule.
Flux de données dans un seul update()
La description ci-dessous est le flux BASIC. Sur un module STANDARD, la branche instantanée est la même ; la branche par période est remplacée par une lecture cohérente unique des compteurs d'énergie du module, dont la différence avec l'instantané précédent est ajoutée aux totaux courants (sans étape d'instantané).
Chaque appel update() sur un module BASIC exécute deux branches en parallèle :
Branche 1 — valeurs instantanées (bloc RT)
- Vérifiez le registre d'état. Si le module est occupé (démarrage, fenêtre d'écriture flash), passez sans écrire.
- Pour chaque capteur RT déclaré, lisez un float32 à partir du registre correspondant.
- Filtre de cohérence
std::isfinite()— rejette NaN/Inf, qui peuvent provenir d'un déchirement lors de la lecture de registres non atomiques. sensor->publish_state(val).
Sur le firmware v1.3, le bloc des valeurs instantanées (U / I / P / PF / Q pour tous les canaux déclarés) est lu en une seule rafale grâce à l'incrémentation automatique en lecture — une phase d'adresse suivie des octets du bloc. Si la rafale échoue ou si le firmware ne prend pas en charge cette capacité, le composant revient à des lectures par registre (4 transactions par float, chacune avec sa propre phase d'adresse). L'incrémentation automatique en écriture n'est pas prise en charge ; les écritures par registre passent toujours octet par octet.
Branche 2 — mesure par période (accumulation d'énergie)
- Enregistrez
t_latch = millis(). - Envoyez la commande d'instantané — elle clôt la période d'accumulation en cours et ouvre immédiatement la suivante. Une seule transaction ferme et ouvre ; aucun échantillon n'est perdu à la frontière.
- Après 50 ms (délai d'attente non bloquant), lisez l'indicateur de validité. Si le module n'a pas fini d'intégrer (interrogation plus rapide que la période d'intégration, ou instantané périmé), passez — le cycle suivant récupérera l'intervalle manqué.
- Lisez la puissance active moyenne sur la période pour chaque canal.
E_Wh[ch] += avg_p_W[ch] × (t_latch − last_latch_ms_) / 3_600_000.- Mettez à jour
last_latch_ms_seulement après réussite sur tous les canaux. - Sauvegarder en NVS si plus de 5 minutes se sont écoulées depuis la dernière sauvegarde.
Le premier instantané après le démarrage réinitialise l'accumulateur du module et cale l'horloge maître ; son résultat est écarté via l'indicateur primed_.
Persistance de l'énergie en NVS
Les valeurs accumulées sont stockées dans la structure RbAmpPrefData (total par canal pour jusqu'à sept canaux + export par canal pour les canaux 0..2) :
struct RbAmpPrefData {
double energy_total_wh[7];
double energy_export_wh[3];
} __attribute__((packed));
Sur les modules STANDARD, les accumulateurs de total général et réactifs (energy_total, energy_exported_total, reactive_energy*) résident dans un second emplacement NVS distinct, de sorte que les valeurs par canal ne sont pas affectées par une mise à jour. Les deux emplacements sont écrits toutes les 5 minutes et lors d'un arrêt propre (redémarrage / OTA).
La clé NVS est dérivée de l'identifiant du composant combiné par XOR à RBAMP_PREF_VERSION (0x52424D31 = « RBM1 »). Si la structure change un jour, incrémenter la constante de version écarte silencieusement les données périmées au lieu de les mal interpréter.
Au démarrage, setup() restaure les totaux avant le premier update(). Si le composant publiait d'abord 0 Wh puis sautait à la valeur sauvegardée, Home Assistant interpréterait ce saut comme une remise à zéro du compteur et démarrerait un nouveau segment d'historique. Restaurer avant la première publication l'empêche.
La fréquence de sauvegarde est régie par deux conditions :
- Par le temps — toutes les 5 minutes (
SAVE_INTERVAL_MS = 300000). - Par événement — après chaque cycle d'intégration complet réussi (tous les canaux lus sans NACK), et à l'arrêt propre.
La perte de données la pire en cas de coupure brutale de l'ESP32 est de 5 minutes d'énergie accumulée. Pour une charge moyenne de 60 W, cela représente 5 Wh — en dessous de la résolution de la barre journalière du tableau de bord Énergie.
Usure de la NVS — la mémoire flash peut-elle « s'user » ?
Chaque sauvegarde écrit ~16 octets dans la section NVS de l'ESP32. La couche NVS de l'ESP-IDF regroupe les petites écritures dans un bloc unique et n'efface une page (4 Ko) que lorsque le bloc est plein. Sur un cycle de 5 minutes :
| Métrique | Valeur |
|---|---|
| Économies par jour | 288 |
| Sauvegardes par an | ~105120 |
| Taille d'écriture | ~16 octets |
| Taille de page NVS | 4096 octets |
| Effacements de pages par an | ~411 (≈ 105120 × 16 ÷ 4096) |
| Limite de cycles d'effacement (fiche technique de la mémoire flash NOR de l'ESP32) | 100000 cycles |
| Durée jusqu'à la panne (TTF) | ~240 ans par page NVS |
La NVS de l'ESP-IDF effectue en plus une répartition de l'usure sur les pages NVS disponibles (la partition par défaut en a 4), ce qui multiplie le TTF par ~4×. En pratique : l'usure de la NVS sur un cycle de sauvegarde de 5 minutes n'est pas un facteur limitant — le matériel deviendra obsolète avant.
Quand il vaut la peine de réduire la fréquence : si un utilisateur force SAVE_INTERVAL_MS en dessous de la valeur par défaut (par exemple 30 s) via son propre code, recalculez le TTF avec la même formule. Une borne inférieure sûre pour 10 ans de fonctionnement est ~30 s.
Discipline NACK
Les cartes ESP32 utilisant le pilote ESP-IDF v5 i2c_master (qu'utilisent ESPHome, arduino-esp32 v3.x et MicroPython sur ESP32) provoquent périodiquement des NACK sur les lectures du module à 100 kHz — dans environ 20 % des transactions. Le même module, mais avec un autre maître (par exemple un autre MCU 32 bits ou un Raspberry Pi), ne donne aucun NACK (0 %). Le problème vient donc du côté maître, et non du module. Les détails figurent dans la référence API, sous « I²C electrical discipline ».
Il y a une seconde complication : lorsque i2c_master_transmit_receive() renvoie ESP_FAIL à cause d'un NACK, le pilote IDF v5 ne remet pas à zéro le tampon utilisateur. Les données de la transaction précédente subsistent. Certains de ces motifs périmés ressemblent à des flottants plausibles (par exemple 0x3C 0x2F 0xFB 0x3F → 1.962 V) et passent un contrôle naïf isfinite().
Le composant met en œuvre trois couches d'atténuation :
| Couche | Implémentation | Effet |
|---|---|---|
| Bus 50 kHz par défaut | frequency: 50kHz dans le bloc YAML i2c: |
Réduit le taux de NACK d'environ 5× empiriquement |
| Relance par octet | 3 tentatives, pause de 5 ms, sur chaque octet de chaque float32 | Élimine un NACK transitoire avant utilisation des données |
| Filtre de cohérence souple | std::isfinite() sans bornes physiques strictes |
Capte les NaN/Inf/dénormaux issus du tampon périmé ; laisse passer les valeurs limites valides (chute de tension, déconnexion) |
Avec les trois couches actives, le composant atteint plus de 99 % de lectures valides sur banc à la fréquence recommandée de 50 kHz. Les firmwares v1.1 et v1.3 ont renforcé la fenêtre de récupération I²C du module, mais 50 kHz reste le réglage recommandé sur les maîtres basés sur l'ESP-IDF, car l'interaction de temporisation du pilote persiste à 100 kHz.
La famille de bibliothèques rbAmp
Ce composant fait partie de la famille multiplateforme des bibliothèques clientes rbAmp. Toutes implémentent le même protocole filaire (référence API).
| Plateforme | Dépôt |
|---|---|
| ESPHome (ce composant) | rb-amp/rbamp-esphome |
| Arduino / arduino-esp32 | rb-amp/rbamp-arduino |
| ESP-IDF | rb-amp/rbamp-esp-idf |
| Python (CPython + MicroPython) | rb-amp/rbamp-python |
Toutes les bibliothèques utilisent les mêmes conventions de fil — écritures octet par octet avec lecture en rafale facultative, la même machine d'état d'instantané de mesure par période, la même détection de variante SKU au démarrage, et les mêmes codes REG_ERROR. Le code de l'une de ces plateformes se porte vers une autre par une simple traduction syntaxique mécanique — la logique du protocole est identique. Voir 09 · Référence API pour la carte de registres canonique.
Références prises en charge
| Variante | Canal de tension | Canaux de courant | Puissance | Emplacements ESPHome disponibles |
|---|---|---|---|---|
| UI1 | oui | 1 | oui | voltage, current, power, energy, frequency, power_factor, reactive_power, apparent_power |
| UI2 | oui | 2 | oui | + current_1, power_1, energy_1, power_factor_1, reactive_power_1 |
| UI3 | oui | 3 | oui | + current_2, power_2, energy_2, power_factor_2, reactive_power_2 |
| I1 | non | 1 | non | current, frequency |
| I2 | non | 2 | non | + current_1 |
| I3 | non | 3 | non | + current_2 |
Les modules avec plusieurs entrées de tension utilisent à la place les emplacements phasés (voltage_a/b/c, current_a/b/c, ...) — voir 09 §2.2 ; les deux groupes ne peuvent pas être mélangés dans un même bloc sensor:.
Sur les variantes I seules, les emplacements power, energy et power_factor exigent un emplacement voltage déclaré (contrôlé par le validateur de schéma) — ne les déclarez que sur les références UI*.
Suite
- 02_tiers.md — les lignes de modules BASIC / STANDARD (STD) et les clés YAML disponibles sur chacune
- 03_sensor_selection.md — choix de la pince CT et comportement des clés
ct_model:/ct_models: - 04_hardware.md — brochage GPIO, tirages, le bus multi-modules
Source et signalements : rb-amp/rbamp-esphome · cette page dans le dépôt : docs/01_overview.md (v1.9.1)