01 · Vue d'ensemble
rbAmp est un module matériel compact pour la mesure de précision des paramètres du secteur alternatif via l'interface I²C. Il est construit autour d'un microcontrôleur doté d'un front-end analogique isolé intégré et d'une calibration d'usine stockée en flash.
Qu'est-ce que rbAmp
La vocation principale de la bibliothèque — surveiller plusieurs charges
components/rbamp est conçu pour fonctionner avec un groupe de modules sur un même bus I²C à la fois, plutôt que pour piloter un seul appareil. Le scénario canonique est un module principal à l'arrivée secteur plus N modules sur des charges individuelles, tous sur un bus, pilotés par un seul ESP32. La bibliothèque fournit un handle de flotte : un objet unique par lequel vous parcourez le bus, interrogez tous les modules en un appel, obtenez la puissance totale consommée et le bilan « arrivée − Σ(charges) », captez les erreurs par module et, si nécessaire, synchronisez les instantanés de période par une commande diffusée.
Les modules multicanaux sont aussi pris en charge — le courant seul I2 / I3 (2 / 3 canaux de courant) et les variantes avec tension UI2 / UI3 / UI5 / UI7 (2 / 3 / 5 / 7 canaux de courant, avec puissance, PF et Wh par canal). Chaque canal a son propre modèle de capteur CT. C'est typique d'un sous-tableau où un même point d'installation surveille plusieurs départs : un module donne une répartition par canal sans un module séparé sur chacun.
Détail d'architecture important. La puissance et les Wh exigent une variante UI ; un « bilan secteur moins somme des charges » exige un module UI sur chaque charge. Les variantes I (I1/I2/I3) mesurent le courant seul — elles n'ont ni tension, ni puissance active, ni PF. L'énergie active (Wh) et la puissance ne sont calculées que sur les variantes UI (qui disposent d'un étage d'entrée en tension). Dans le déploiement canonique, le rôle de « compteur général » (énergie totale) est assuré par un seul UI1 à l'arrivée secteur, tandis que le rôle de sous-compteur (détail du courant par charge) est assuré par des modules I2/I3 (ou par UI2 / UI3 / UI5 / UI7 lorsque la puissance et les Wh sont nécessaires par charge).
Travailler avec un seul module est le cas minimal de cette même bibliothèque : rbamp_handle_t est le bloc de base sur lequel la flotte est construite. Si vous n'avez qu'un module sur le bus, vous utilisez directement ce même handle — aucune API de flotte n'est nécessaire.
Le scénario des 80 % — arrivée principale + N sous-charges
- 1 module à l'arrivée (secteur) — consommation totale et qualité du réseau.
- N modules sur des charges individuelles — comptabilisation par canal.
- Les modules multi-canaux conviennent aussi : un seul UI2 / UI3 / UI5 / UI7 (ou I2 / I3) peut mesurer plusieurs charges, chacune sur son propre canal — N modules ne signifient pas obligatoirement N charges.
-
Un seul appel de flotte
rbamp_fleet_poll_all()interroge tout ; le bilanmains − Σ(sub_loads)révèle le « reste » (consommation de fond, charges non comptabilisées, fuites). -
Une horloge maître partagée → comptabilisation Wh correcte sans dérive inter-modules (voir 02_tiers.md et la section sur l'horloge murale du maître dans 09_api_reference.md).
Pour le détail, voir le chapitre 06 · Exemples, scénario 1 (« Secteur + N charges secondaires — le canon des 80 % »). Pour l'API, voir le chapitre 09 · Référence API, la section « Gestionnaire de flotte ».
Ce que mesure rbAmp
| Grandeur | Type | Plage |
|---|---|---|
| Tension efficace RMS U_rms | float, V | 0…300 V |
| Tension de crête U_peak | float, V | 0…450 V |
| Courant efficace RMS I_rms | float, A | dépend du capteur sélectionné — voir 03_sensor_selection.md |
| Courant crête I_peak | float, A | dépend du capteur sélectionné |
| Puissance active P (signée en RT) | float, W | dépend du capteur sélectionné |
| Facteur de puissance PF | float | −1…+1 |
| Fréquence du secteur | uint8, Hz | 50 / 60 Hz (détecté) |
| P moyennée sur une période | float, W | identique à P |
La valeur RT de la puissance active P est toujours signée sur toute gamme de modules (négative = export vers le réseau). Le comportement de la valeur moyennée sur la période (avg_p[ch] dans rbamp_period_snapshot_t) dépend de la gamme de modules — voir la section « Module lines » ci-dessous et 02_tiers.md.
Câblage
Le module se connecte au maître par quatre fils côté BT. L'unique référence secteur (l'entrée de tension L/N sur les variantes UI*) se trouve derrière un diviseur isolé galvaniquement, et la pince CT se couple magnétiquement sans contact électrique ; voir 04 · Câblage, « Mains and CT connection » (une tension secteur peut tuer — lisez d'abord l'avertissement qui s'y trouve).
| Wire | Objet |
|---|---|
VCC |
+5 V (4.5..5.5 V), ~15 mA, crête ~25 mA. Régulateur et filtrage embarqués |
GND |
commun avec le maître (obligatoire) |
SDA, SCL |
I²C, logique 3.3 V, tolérant 5 V. Résistances de rappel intégrées de 4.7 kΩ vers 3.3 V |
DRDY |
facultatif, drain ouvert à l'état BAS ~10 µs toutes les ~100 ms |
L'adresse par défaut est 0x50 (7 bits, plage réglable 0x08..0x77), la vitesse recommandée est 50 kHz sur ESP32 (voir la section sur la discipline nouvelle tentative + cohérence ci-dessous). Démarrage à froid jusqu'à la première mesure valide : ~250 ms.
Les règles complètes (longueur du bus, recommandations de résistances de rappel sur un bus multi-modules, schémas de câblage pour les différentes cibles ESP32) figurent au chapitre 04 · Câblage.
Gammes de modules (aide-mémoire)
BASIC et STANDARD (STD) modules sont livrés. BASIC suit la logique d'un compteur mécanique classique — comptabilisation unidirectionnelle (consommation seule) ; STD conserve des compteurs d'énergie signés :
| Niveau | Puissance RT P |
Accumulateur par période avg_p[ch] |
Compteur Wh du composant |
|---|---|---|---|
| BASIC | signée (négative = injection vers le réseau, visible en temps réel) | chaque fenêtre de 100 ms de la puissance moyenne P est ramenée à max(P, 0) avant d'être ajoutée à l'accumulateur de période |
monotonic — comptabilisation de la consommation seulement |
| STANDARD (STD) | signé ; également puissances réactive et apparente | banques d'instantanés, ou différences de compteurs — l'export est conservé (import et export comptés séparément) | Valeur nette signée (négative = export net) |
Pour les détails, voir le chapitre 02 · Gammes de modules. Au niveau du composant, le même handle rbamp_handle_t est utilisé quelle que soit la gamme — rbamp_begin() détecte la gamme du module (rbamp_line()) ; les différences apparaissent dans les valeurs renvoyées par le module et dans les appels rbamp_std_* supplémentaires qu'offre un module STD.
Comptabilité bidirectionnelle sur BASIC : rbamp_energy_wh(dev, ch) sur la gamme BASIC ne donne que la consommation. Si vous devez comptabiliser l'export séparément, échantillonnez la puissance RT rbamp_read_power(dev, 0, &p) à ~10 Hz et répartissez vous-même les échantillons positifs et négatifs dans deux variables d'accumulation. Voir l'exemple dans 06_examples.md (Scénario 9, « Comptage bidirectionnel côté maître »).
Ce que fait ce composant
esp_timer_get_time().
Le composant gère aussi la comptabilité de période : il prend un instantané, attend la stabilisation du module, vérifie que l'instantané est valide, et intègre les Wh par rapport à l'horloge du maître (rbamp_read_period_snapshot() et rbamp_energy_wh(), voir 05 · Démarrage rapide, étape 5). La comparaison au niveau des registres (« sans le composant »), le schéma d'architecture, les schémas d'interaction et la table de correspondance se trouvent dans 09 · Référence de l'API, annexe « Under the hood ».
Journalisation et Kconfig
Contrairement à la bibliothèque Arduino, où le flux de journalisation est configuré à l'exécution (setLogStream(&Serial)), ici on utilise le motif standard d'ESP-IDF : le composant journalise sous le tag "rbamp" via esp_log. Le niveau de journalisation est compilé via le choix Kconfig CONFIG_RBAMP_LOG_LEVEL_* (NONE / ERROR / WARN / INFO / DEBUG, INFO par défaut). À NONE, les chaînes de journalisation sont entièrement retirées du binaire.
Le filtre à l'exécution fonctionne aussi (via esp_log_level_set("rbamp", ...)), mais il est plafonné par le niveau de compilation.
Six symboles CONFIG_RBAMP_* sont disponibles dans idf.py menuconfig → Component config → rbAmp client [Component config → rbAmp client] :
| Symbole | Objet | Par défaut |
|---|---|---|
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ |
Fréquence SCL pour le bus partagé | 50000 (50 kHz) |
CONFIG_RBAMP_I2C_TIMEOUT_MS |
délai d'émission / réception | 100 ms |
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS |
tentatives de nouvelle lecture par lecture d'un octet | 3 |
CONFIG_RBAMP_NACK_RETRY_GAP_MS |
intervalle entre les tentatives de reprise | 5 ms |
CONFIG_RBAMP_DISABLE_ENERGY |
retirer l'accumulateur Wh de la compilation | n |
CONFIG_RBAMP_LOG_LEVEL_* |
niveau de compilation des chaînes de journalisation | INFO |
Pour plus de détails, voir 09 · Référence de l'API, section « Compile-time configuration » (configuration à la compilation).
Suite
- 02 · Gammes de modules — quelle gamme pour quelle tâche
- 04 · Câblage — résistances de rappel, longueur du bus, brochage de la famille ESP32
- 05 · Démarrage rapide — votre premier projet fonctionnel
- 06 · Exemples — démonstrations guidées de projets IDF prêts à l'emploi
- 09 · Référence de l'API — toutes les fonctions publiques
- 10 · Dépannage — quand quelque chose ne fonctionne pas
Source et problèmes : rb-amp/rbamp-esp-idf · cette page dans le dépôt : docs/01_overview.md (v1.7.3)