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

02 · Niveaux de modules

Les lignes de modules BASIC et STANDARD (STD) côte à côte : énergie sur le maître pour BASIC, sur le module pour STD.

Ce qu'est une ligne de modules

Vérifiez l'étiquette de votre module ; dev.line() affiche la ligne après begin().

rbAmp se décline en gammes de modules : BASIC et STANDARD (STD). Une gamme de module est un appariement complet de révision matérielle et firmware, pas un simple indicateur logiciel. Passer d'une gamme à l'autre exige un changement physique de référence, pas une mise à jour du firmware.

Du point de vue de la bibliothèque et de votre code : une seule classe RbAmp couvre les deux lignes produites. begin() détecte si un module est BASIC ou STANDARD (STD) et route chaque appel en interne ; les méthodes communes (readVoltage(), readCurrent(), readPower(), readPeriodSnapshot(), energy() …) fonctionnent sur les deux. La ligne STD ajoute ses propres appels — puissances réactive et apparente, lectures de blocs par canal, compteurs d'énergie à vie signés — voir 09 · Référence de l'API.

État actuel

Le niveau BASIC et la ligne STANDARD (STD) sont des lignes de modules commercialisées ; cette bibliothèque prend en charge les deux (STANDARD (STD) à partir de la bibliothèque 1.6.0, voir le README).

Niveau Expédition
BASIC ✅ oui
STANDARD (STD) ✅ oui (bibliothèque 1.6.0+)

BASIC — palier d'entrée pour le comptage grand public

Matériel

Un chemin analogique à faible coût adapté aux charges domestiques typiques. Le module comprend un frontal analogique isolé, un régulateur d'alimentation embarqué et un étalonnage d'usine stocké en flash.

Comportement du firmware

La logique d'un compteur mécanique à disque classique — le compte n'avance que dans un sens ; l'injection vers le réseau n'est pas soustraite.

Les trois « couches » des valeurs de puissance active se comportent différemment :

Signal Signification Comportement sur BASIC
dev.readPower(ch) puissance RT instantanée, mise à jour environ toutes les 100 ms signé — une valeur négative est visible en temps réel (export)
PERIOD_AVG_P_W (dans readPeriodSnapshot) puissance moyenne sur la période la puissance moyenne de chaque fenêtre de 100 ms est bornée à max(P, 0) avant d'être ajoutée à l'accumulateur de période
dev.energy().wh(ch) Wh accumulés par la bibliothèque monotone — consommation seulement ; l'injection n'est pas comptée

Autrement dit : l'utilisateur voit l'export dans la lecture RT, mais il est absent du compteur Wh de la bibliothèque sur BASIC.

Cas d'usage typiques

  • Foyers sans production sur place (ni panneaux solaires, ni éoliennes, ni systèmes de batteries)

  • Sous-compteurs pour les charges purement consommatrices (chauffe-eau, moteurs, appareils)

  • Surveillance de la consommation d'un bâtiment où le comptage bidirectionnel n'est pas nécessaire

Comptage bidirectionnel sur BASIC (côté maître)

Comptabilité de l'énergie sur BASIC (consommation sur le module, export intégré sur le maître) et sur STANDARD (STD) (compteurs d'import, d'export et net sur le module).

Si vous devez suivre séparément l'export vers le réseau sur un module BASIC, faites-le côté maître. La puissance RT dev.readPower(0) est signée, donc :

C++
double consume_wh = 0.0;
double export_wh  = 0.0;
uint32_t t_prev_ms = millis();

void loop() {
    // Sample RT power at 10 Hz — matches the firmware-commit cadence
    // (100 ms per channel). Faster gives empty repeat reads; slower
    // loses resolution on abrupt load transitions.
    //
    // delay() blocks the loop — incompatible with concurrent work
    // (LCD refresh, MQTT, networking). For sketches with other tasks,
    // replace it with a non-blocking millis() / scheduler pattern.
    delay(100);
    uint32_t t_now_ms = millis();
    float dt_s = (t_now_ms - t_prev_ms) / 1000.0f;
    t_prev_ms = t_now_ms;

    float p = dev.readPower(0);
    if (isnan(p)) return;

    double dwh = (double)p * dt_s / 3600.0;
    if (p >= 0) consume_wh += dwh;
    else        export_wh  += -dwh;
}

Un exemple complet fonctionnel se trouve dans 06_examples.md (le scénario BidirectionalEnergy) et dans examples/06_BidirectionalEnergy/.

STANDARD (STD) — ligne bidirectionnelle

Les modules STANDARD (STD) forment une ligne de modules commercialisée. La bibliothèque les détecte dans begin() (dev.line() == RbAmpLine::Std) et utilise le même câblage et la même API commune que BASIC (voir 04 · Câblage).

Ce qu'ajoute la ligne STD

Sur un module STD doté de compteurs persistants, l'API de période / d'instantanés et l'énergie proviennent des compteurs propres au module (les anciennes images STD utilisent les banques d'instantanés du module) ; sur le STD, le modèle de CT n'est qu'une étiquette et ne règle aucun gain.

  • Énergie signée : l'import et l'export sont comptabilisés séparément. Sur les modules qui conservent des compteurs d'énergie à vie persistés, dev.energy() et readPeriodSnapshot() prennent les chiffres propres du module (wh_net = import − export), et stdReadEnergy() donne les compteurs bruts (Wh, mWh et, sur les images qui les fournissent, µWh / µvarh).

  • Davantage de grandeurs (sur BASIC, la puissance réactive n'est pas exposée par cette bibliothèque) : readReactivePower(ch), readApparentPower(ch), stdReadChannel(ch) (I / P / Q / S / PF / crête en une seule rafale) et, lorsqu'elles sont activées, des valeurs issues des harmoniques (THD, facteur de puissance de déplacement).

  • Modules multi-canaux / multi-tensions : le nombre de canaux provient du module ; stdReadVoltage(v), totaux par phase avec stdReadTotals(k).

  • Diagnostic et maintenance : stdReadHealth(), horloge du module, historique et journal d'événements, identification par UID, mise à jour du firmware via I²C.

Tous ces appels sont listés un par un dans 09 · Référence API § API de la gamme STD.

Dépendance à l'image.

Certaines fonctions STD dépendent de la version de l'image du module : compteurs d'énergie à micro-résolution, courant de démarrage de l'énergie, angles de phase de tension et séquence de phases exigent une version d'image d'au moins 0x0001007B (dev.stdReadImageVersion()) ; sur une image plus ancienne, elles sont signalées comme « non disponibles ». Les appels réservés au STD sur un module BASIC renvoient RB_ERR_NOT_IMPLEMENTED.

Cas d'usage typiques

  • Foyers équipés de production solaire en toiture
  • Foyers avec éoliennes
  • Systèmes de stockage par batterie
  • Charges régénératives
  • Recharge VE vehicle-to-grid (V2G)

Comment détecter la ligne à l'exécution

Pour savoir quelle ligne de modules vous possédez : lisez l'étiquette ou appelez line() après begin().

C++
if (!dev.begin()) { /* see dev.errorString() */ }

// Product line, detected by begin(): BASIC or STANDARD (STD)
RbAmpLine line = dev.line();          // RbAmpLine::Basic / RbAmpLine::Std

// Firmware version — opaque byte
uint8_t fw = dev.firmwareVersion();

// Presence of a voltage sensor (UI* variants vs I*-only)
bool voltage_hw = dev.hasVoltageHw();

// Number of current channels
uint8_t channels = dev.channels();

// Full SKU — variant byte (REG_HW_VARIANT)
RbAmpVariant variant = dev.readVariant();   // UI1, UI2, UI3, I1, I2, I3, UI5, UI7 …
Remarque

: line() indique BASIC ou STANDARD (STD). Les autres indicateurs (version du firmware, nombre de canaux, capteur de tension, référence) décrivent le matériel. L'étiquette de référence sur le boîtier du module reste la source de vérité pour le produit.

Où les éléments dépendant du palier sont signalés dans la documentation

Dans tout le texte de la bibliothèque et la documentation canonique, les fonctionnalités dépendant du niveau sont signalées explicitement, par exemple :

STANDARD (STD) uniquement

— cela n'est pas disponible sur un module BASIC.

Ou, à l'inverse, un comportement propre à BASIC :

BASIC

: le compteur dev.energy().wh(ch) est monotone — l'export vers le réseau n'est pas compté. Pour le comptage bidirectionnel, voir l'exemple BidirectionalEnergy ou utilisez un module STANDARD (STD).

Suite


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