rbAmp
FR
Boutique
Docs
Mis à jour le · Modifier sur GitHub [Edit on GitHub]

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

Vue d'ensemble de la façon dont l'application, la bibliothèque, le bus I²C et les modules rbAmp s'articulent.

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.

Sécurité

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

Un maître sur un bus I²C partagé, avec un module secteur à l'arrivée et des modules de sous-charges sur des dérivations individuelles, une pince par module.

  • 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 bilan mains − Σ(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
Remarque

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.

Remarque

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

Chronologie de fenêtres de mesure de 100 ms consécutives, des impulsions facultatives de disponibilité des données et d'un instantané de période déclenché par le maître.
Sa tâche principale est de masquer l'échange protocolaire et de dispenser l'application utilisateur de la gestion des registres, de l'ordre des octets et des temps de stabilisation après commande. De plus, le composantcalcule l'énergie (Wh)— le module ne renvoie que la puissance moyennée sur la période, et l'intégration est faite par le maître viaesp_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


Source et problèmes : rb-amp/rbamp-esp-idf · cette page dans le dépôt : docs/01_overview.md (v1.7.3)