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

01 · Vue d'ensemble

Chaîne de signal depuis la pince de courant, à travers le module rbAmp et I²C, jusqu'au maître puis vers le cloud ou Home Assistant.

Qu'est-ce que rbAmp

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 dispose d'un frontal analogique isolé intégré et d'un étalonnage d'usine stocké en flash.

Du point de vue d'un intégrateur, le module se comporte comme un esclave I²C standard : branchez l'alimentation, lisez les registres, et vous obtenez des valeurs prêtes à l'emploi en unités physiques. Aucun traitement du signal côté maître n'est nécessaire.

La vocation principale de la bibliothèque — surveiller plusieurs charges

La bibliothèque Arduino RbAmp est conçue pour travailler avec un groupe de modules simultanément sur un seul bus I²C, et non pour piloter un seul appareil. Le scénario canonique est un module principal sur l'arrivée secteur plus N modules sur des charges individuelles, le tout sur un bus, piloté par un seul Arduino/ESP32. La bibliothèque fournit la classe RbAmpFleet — un objet unique par lequel vous scannez le bus, interrogez chaque module par un seul appel, obtenez la puissance consommée totale et le bilan « arrivée − Σ(charges) », détectez les erreurs sur chaque module et, si besoin, synchronisez les instantanés de période par une commande de diffusion.

Les modules multi-canaux sont également pris en charge — les I2 / I3 à courant seul (deux ou trois TC) et les UI2 / UI3 / UI5 / UI7 équipés de tension (2 / 3 / 5 / 7 canaux de courant, avec puissance, FP et Wh par canal). Chaque canal a son propre modèle de capteur. C'est typique d'un sous-tableau, où un seul point d'installation surveille plusieurs départs.

Travailler avec un seul module est le cas minimal de cette même bibliothèque : la classe RbAmp est le bloc de base sur lequel RbAmpFleet est superposé. Si vous n'avez qu'un module sur le bus, vous utilisez directement ce même handle — l'API de flotte n'est pas nécessaire.

Le scénario des 80 % — arrivée principale + N sous-charges

Un module sur l'arrivée principale et un module par sous-charge, tous sur un bus I²C partagé lu par un seul maître.

  • 1 module sur l'alimentation secteur — consommation globale et qualité du réseau.
  • N modules sur des charges individuelles — comptage par canal.
  • Les modules multi-canaux conviennent aussi à ce cas : 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 fleet.pollAll() interroge tout ; le bilan mains − Σ(sub_loads) révèle « le reste » (consommation de fond, charges non comptées, fuites).

  • Une seule horodatage maître commun → comptage Wh correct sans dérive entre modules (voir 02_tiers.md et la section sur l'horloge murale du maître dans 09_api_reference.md).

Sécurité

Détail d'architecture important. Les variantes I (I1/I2/I3) ne mesurent que le courant — 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 ont une entrée de tension). Dans le déploiement de référence, le rôle de « compteur secteur » (comptage tarifaire / par période) est tenu par un seul UI1 sur l'arrivée secteur ; le rôle de sous-compteur (détail de courant par charge) est tenu par des I2/I3 (ou par des UI2 / UI3 / UI5 / UI7 lorsque la puissance et les Wh sont nécessaires par charge).

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 float32, V 0…300 V
Tension de crête U_peak float32, V 0…450 V
Courant efficace RMS I_rms float32, A selon le capteur choisi — voir 03_sensor_selection.md
Courant crête I_peak float32, A dépend du capteur sélectionné
Puissance active P (signée en RT) float32, W dépend du capteur sélectionné
Facteur de puissance PF float32 −1…+1
Fréquence du réseau uint8, Hz 50 / 60 Hz (détecté)
P moyenne sur la période float32, W comme pour P
Remarque

La valeur RT de la puissance active P est toujours signée, quel que soit le niveau du module (négatif signifie export vers le réseau). Le comportement de la valeur moyennée sur la période (PERIOD_AVG_P_W) dépend du niveau du module — voir la section « Niveaux de modules » ci-dessous et 02_tiers.md.

Raccordement

Le module se connecte au maître par quatre fils côté basse tension ; tout ce qui touche au secteur reste à l'intérieur du boîtier.

Wire Objet
VCC +5 V (4.5..5.5 V), courant ~15 mA, pointe ~25 mA. Régulateur embarqué et filtrage
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 à BAS pendant environ 10 µs toutes les 100 ms

L'adresse par défaut est 0x50 (7 bits, plage de changement 0x08..0x77), à 100 kHz (UNO / Mega / STM32 / RP2040) ou 50 kHz (ESP32 / ESP8266) ; n'utilisez pas 400 kHz. Le démarrage à froid jusqu'à la première mesure valide est d'environ 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 selon les différents hôtes) figurent au chapitre 04 · Raccordement.

Niveaux de modules (aide-mémoire)

Le niveau BASIC réalise un comptage unidirectionnel (consommation seule), selon la logique d'un compteur mécanique classique ; la ligne STANDARD (STD) est une seconde ligne de modules commercialisée avec une énergie signée (import / export) :

Niveau Puissance RT P Accumulateur de période PERIOD_AVG_P_W Compteur Wh de la bibliothèque
BASIC signée (négative = injection vers le réseau, visible en temps réel) chaque fenêtre de 100 ms de P moyenne est ramenée à max(P, 0) avant d'être ajoutée à l'accumulateur de période monotone — ne comptabilise que la consommation
STANDARD (STD) signé importation et exportation comptabilisées séparément (banques d'instantanés, ou compteurs de durée de vie persistants du module) énergie nette = import − export (wh_net, stdReadEnergy())

Les détails figurent au chapitre 02 · Niveaux de modules. Au niveau de la bibliothèque, la même classe RbAmp est utilisée quel que soit le niveau ; les différences apparaissent dans les valeurs renvoyées par le module.

Remarque

Comptage bidirectionnel sur BASIC : dev.energy().wh(ch) de la bibliothèque, sur le niveau BASIC, ne donne que la consommation. Si vous devez comptabiliser séparément l'export, échantillonnez la puissance RT dev.readPower(0) à environ 10 Hz et répartissez vous-même les échantillons positifs et négatifs dans deux variables d'accumulation. Un exemple se trouve dans 06_examples.md (le scénario BidirectionalEnergy).

Ce que fait cette bibliothèque

La tâche principale est de masquer l'échange de protocole et de décharger le croquis de l'utilisateur de la manipulation des registres, de l'ordre des octets et des temps de stabilisation après les commandes. De plus, la bibliothèque calcule l'énergie (Wh) — le module ne renvoie que la puissance moyenne sur la période, et l'intégration est faite par le maître selon sa propre horloge.

Remarque

Vous construisez pour ESPHome ? Utilisez plutôt le composant externe plutôt que cette bibliothèque directement — il intègre nativement le protocole rbAmp dans la chaîne YAML d'ESPHome.

Sans la bibliothèque (accès direct aux registres)

C++
// Reading U_RMS — in four transactions.
Wire.beginTransmission(0x50);
Wire.write(0x86);
Wire.endTransmission(false);
Wire.requestFrom((uint8_t)0x50, (uint8_t)1);
uint8_t b0 = Wire.read();
// ...repeat for b1, b2, b3...
float u_rms;
uint8_t buf[4] = {b0, b1, b2, b3};
memcpy(&u_rms, buf, 4);

Avec la bibliothèque

C++
float u_rms = dev.readVoltage();

Lire la période — sans la bibliothèque

C++
Wire.beginTransmission(0x50);
Wire.write(0x01); Wire.write(0x27);   // CMD_LATCH_PERIOD
Wire.endTransmission();
uint32_t t_latch_ms = millis();
delay(50);                            // settling time after the command

Wire.beginTransmission(0x50);
Wire.write(0x07);
Wire.endTransmission(false);
Wire.requestFrom((uint8_t)0x50, (uint8_t)1);
if ((Wire.read() & 0x01) == 0) {
    // snapshot is stale — t_latch_ms must STILL be recorded,
    // otherwise the next snapshot will count Wh over two periods
    t_prev_latch_ms = t_latch_ms;   // <-- this line is easy to forget
    return;
}
// ...read 4 bytes of avg_p, assemble the float, integrate Wh:
//   float dt_s = (millis() - t_prev_latch_ms) / 1000.0f;
//   E_Wh += avg_p × dt_s / 3600.0f;

Lecture de la période — avec la bibliothèque

C++
RbAmpPeriodSnapshot snap;
if (dev.readPeriodSnapshot(snap)) {
    // snap.avg_p[0] is filled,
    // dev.energy().wh(0) was incremented by avg_p × master_dt_s / 3600,
    // master_dt_ms is accounted for and saved for the next cycle.
}

En interne, la bibliothèque garantit :

  • Un temps de stabilisation de 50 ms après CMD_LATCH_PERIOD, et une lecture correcte de l'instantané (instantané atomique côté module).

  • Une vérification du drapeau PERIOD_VALID avant la lecture.

  • Enregistrer l'heure selon l'horloge du maître même sur un instantané périmé (protège contre le double comptage des Wh à la période suivante).

  • Accumulation de Wh par canal en double précision.

  • Chargement automatique des coefficients de calibration lorsqu'un capteur de courant est choisi via setSensorClass(class) + setCTModel(code) — l'utilisateur n'a pas besoin de connaître les registres NF/GAIN.

Quand utiliser la bibliothèque, quand utiliser l'accès direct aux registres

Tâche Bibliothèque Accès direct aux registres
Lecture de U / I / P / FP / fréquence ✅ seulement pour le débogage à l'analyseur logique
Comptage d'énergie par période ✅ seulement si les Wh sont stockés en dehors de la bibliothèque (par ex. dans une base de données côté maître)
Plusieurs modules sur un bus ✅ —
Comptage bidirectionnel sur BASIC ✅ (via les lectures RT — voir 06_examples.md) alternative — votre propre boucle de lectures RT et intégration manuelle
Portage vers une plateforme non Arduino n/a ✅ — voir 09 · Référence API, la section « Détails du protocole filaire »
Limite de RAM stricte (Arduino Uno AVR) ~42 o par instance RbAmp + 63 o par instantané ; faisable, mais serré sur un multi-modules (3 modules × ~42 o + 3 × 63 o ≈ 315 o occupent déjà une part notable du budget RAM de l'application) ✅ si l'instance de la bibliothèque ne tient pas

Pour toutes les tâches courantes des premières lignes, la bibliothèque convient parfaitement.

Architecture

Où se situe votre croquis : croquis, bibliothèque RbAmp, Wire (I²C) et le module rbAmp à l'adresse par défaut 0x50.

Diagrammes d'interaction

Le déroulement de begin()

Déroulement de begin() : lecture de la version, détection de la gamme, instantané d'amorce (écarté), puis prêt.

Le premier instantané est une amorce (le module renvoie ce qu'il a accumulé depuis la mise sous tension, ce qui ne convient pas au comptage tarifaire). La bibliothèque enregistre d'elle-même que cet instantané doit être écarté — le code utilisateur ne le voit jamais.

Le déroulement de readPeriodSnapshot(snap)

Séquence de readPeriodSnapshot() : la bibliothèque clôt la période sur le module, lit l'instantané, intègre l'énergie sur l'horloge du maître et renvoie le résultat au croquis.

L'instantané atomique côté module garantit que chaque mesure de la période tombe dans exactement un instantané — pas de doublon, pas de perte à la limite de la période.

Correspondance avec l'API de registres directe

Un tableau pour ceux qui migrent depuis leur propre code basé sur l'accès direct :

API directe Équivalent via la bibliothèque
Lecture manuelle de 4 octets + memcpy dev.readVoltage() / dev.readPower(ch)
Wire.write(0x01); Wire.write(0x27); delay(50) dev.latchPeriod(); delay(50) (ou simplement dev.readPeriodSnapshot())
Vérification de Wire.read(0x07) & 1 dev.isPeriodValid()
La formule manuelle E_Wh += avg_p × dt_s / 3600 dev.energy().wh(0) — mis à jour automatiquement
Configuration manuelle du capteur de courant via l'API de registres directe dev.setSensorClass(class) + dev.setCTModel(code) — les préréglages d'usine sont chargés automatiquement

Suite


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