09 · Référence de l'API
L'API publique de la bibliothèque RbAmp pour Arduino à partir de la v1.6.1. Une seule classe couvre les deux lignes de produits de modules — BASIC et STANDARD (STD) : begin() détecte la ligne et chaque appel est routé en interne. Les appels propres à une seule ligne sont signalés ; un appel sans équivalent sur la ligne détectée échoue avec RB_ERR_NOT_IMPLEMENTED. Source de vérité — les fichiers d'en-tête src/RbAmp.h, src/RbAmpSnapshot.h, src/RbAmpEnergy.h, src/RbAmpSensorModels.h, src/RbAmpRegisters.h (les deux derniers sont générés automatiquement et ne doivent pas être modifiés à la main).
Ce chapitre est une référence : signatures, valeurs de retour, effets de bord, cas limites. Pour des exemples de travail, voir 06 · Exemples ; pour le démarrage rapide, voir 05 · Démarrage rapide.
Fichiers d'en-tête
| Inclure | Ce qu'elle apporte |
|---|---|
|
Tous les types publics (inclut tous les autres) |
|
RbAmpSnapshot, RbAmpPeriodSnapshot, RbAmpTopology, RbAmpVariant, RbAmpLine, RbAmpSensorClass, RbAmpSctRating, RbAmpDrdyEvent et les structures RbAmpStd* de la ligne STD |
|
RbAmpEnergy |
|
Registre généré des modèles de capteurs — les codes de modèle RBAMP_CT_* et rbamp_sensor_model_lookup() |
|
Constantes de protocole générées automatiquement — RB_OK, RB_ERR_*, SETTLE_MS_* |
Un croquis utilisateur n'a normalement besoin que de #include — le reste est tiré par dépendance transitive.
Sur quelle ligne un appel fonctionne-t-il ?
| Groupe | BASIC | STD |
|---|---|---|
Cycle de vie, lectures temps réel (readVoltage … readAll), comptage par période, energy() |
oui | oui |
readReactivePower(), readApparentPower() |
non (RB_ERR_NOT_IMPLEMENTED) |
oui |
Setters de classe de capteur / modèle de TC, saveUserConfig(), changement d'adresse, reset() |
oui | oui (le modèle de CT n'est qu'une étiquette sur STD, voir ci-dessous) |
factoryReset(), aides General-Call, aides d'étiquette, readCapability(), readCommitSeq(), readPeriodLatchMs() |
oui | non (RB_ERR_NOT_IMPLEMENTED) |
Ligne data-ready et événements (setDrdyPin(), waitDataReady(), setEventMask() …) |
oui | oui (selon l'image du module, voir ci-dessous) |
appels std* (API de la gamme STD) |
non (RB_ERR_NOT_IMPLEMENTED) |
oui |
Correction de calibre SCT-013 (sctRating*()) |
oui (classe SCT-013, anciens firmwares BASIC) | jamais appliquée (échelle 1) |
Certaines fonctionnalités STD dépendent de la version d'image du module : compteurs micro-énergie, courant de départ pour l'énergie, angles de phase de tension et séquence de phases nécessitent une image d'au moins 0x0001007B (stdReadImageVersion()). Sur une image plus ancienne, la bibliothèque les signale comme « non disponibles » (un drapeau valid à false, une valeur dérivée, ou RB_ERR_NOT_IMPLEMENTED) — jamais comme un mauvais nombre.
Classe RbAmp
Le client principal. Une instance par appareil esclave sur le bus I²C. Plusieurs instances peuvent partager un même bus TwoWire pour interroger plusieurs modules.
Constructeur
explicit RbAmp(TwoWire& bus,
uint8_t addr = 0x50,
RbAmpTopology hint = RbAmpTopology::Single) noexcept;
| Paramètre | Description |
|---|---|
bus |
Référence au bus TwoWire (en général Wire). L'appelant doit appeler bus.begin() AVANT begin(). |
addr |
Adresse esclave sur 7 bits. Plage 0x08..0x77, défaut 0x50. |
hint |
Indication de topologie : le nombre de canaux de courant (1/2/3). Sur un firmware antérieur à v1.3, begin() ne peut pas déterminer la variante de façon fiable, donc l'indication sert de repli pour les références multi-canaux. Par défaut Single — la valeur sûre, qui ne déclenche pas de lectures parasites des canaux absents. Pour les modules multi-canaux sur un firmware antérieur à v1.3, passez explicitement l'indication correspondante. |
Le constructeur ne génère aucun trafic I²C.
Méthodes de cycle de vie
bool begin() noexcept
02 · Initialisation et démarrage (initialization) · BASIC ou STD ? (initialization) · Cycle d'interrogation continu (recommandé) (period-metering)
Interroge l'appareil, détecte sa gamme de produit et sa variante, amorce l'instantané.
Sequence:
-
Sonde d'identité STD en premier. Si le module répond comme un module STD, le nombre de canaux vient du module lui-même, la banque d'instantanés 0 est armée et amorcée, et
begin()renvoie — les étapes BASIC ci-dessous sont sautées. -
Lisez
REG_VERSION(0x03). Si l'appareil n'a pas acquitté —falseavecRB_ERR_NACK. S'il a renvoyé0x00/0xFF—falseavecRB_ERR_VERSION. -
Mettez en cache la topologie : l'octet de variante du module sur les firmwares qui l'exposent, sinon l'indication
hintdu constructeur. Ensuite,topology()/channels()renvoient des valeurs valides sans toucher au bus. Le nombre de canaux ne dépasse jamaisRBAMP_MAX_CHANNELS(7) ; les canaux au-delà ne sont pas exposés et les adresser renvoieRB_ERR_PARAM. -
Lisez
U_rmspour déterminer si un capteur de tension est présent (seuil 1.0 V). -
Écrivez
CMD_LATCH_PERIODcomme amorce + attendez 50 ms. Le premier instantané après la mise sous tension est écarté (il n'est pas transmis au code utilisateur — il mêle des données antérieures à la mise sous tension). -
Mémorisez
millis()pour l'intégration ultérieure de l'énergie. - Sur un module BASIC de classe SCT-013, lisez la correction de calibre par canal (voir Correction de calibre SCT-013). Si le module est dans un état qui nécessite un redémarrage pour appliquer le bon gain,
begin()le redémarre une fois.
Idempotente : sûre à rappeler.
Renvoie : true en cas de succès ; false sinon — voir lastError() pour le détail.
bool probe() noexcept
Un contrôle de vie léger. Une seule lecture de REG_VERSION, sans effet de bord.
Renvoie : true si l'esclave a acquitté et signalé une version prise en charge (ni 0 ni 0xFF).
bool waitReady(uint32_t timeout_ms = 1000) noexcept
02 · Initialisation et démarrage (initialization) · 3. DATA_VALID (0xCE) ne passe jamais à 1 (troubleshooting) · 4 · Carte des registres (production v1.3) (api-reference)
Interroge le drapeau de disponibilité du module jusqu'à ce que le bit 0 soit positionné. Utile après la mise sous tension — le module peut avoir besoin d'une fenêtre de mesure (100 ms) pour valider ses premières données.
Renvoie : true si le bit a été vu avant l'expiration de timeout_ms ; sinon false avec RB_ERR_TIMEOUT.
uint8_t firmwareVersion() noexcept
Renvoie : l'octet REG_VERSION (0x03). Valeurs BASIC connues : 0x01 = v1.0, 0x02 = v1.1, 0x03 = v1.2, 0x04 = v1.3. Les firmwares BASIC plus récents renvoient des valeurs plus élevées. 0 ou 0xFF indiquent une erreur I²C (voir lastError()).
RbAmpLine line() const noexcept
Renvoie : la gamme de produit détectée par begin() — RbAmpLine::Basic (la valeur tant que begin() n'a pas été exécuté) ou RbAmpLine::Std. Aucun accès au bus.
RbAmpTopology topology() const noexcept
Renvoie : la topologie mise en cache. Aucun accès au bus.
uint8_t channels() const noexcept
Courant multi-canaux (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.10 Bloc temps réel V03 (0x86..0xBD) (api-reference) · 4.14 Fenêtre d'accès aux canaux (0x32 + 0x3C..0x3F) (api-reference)
Renvoie : le nombre de canaux de courant, 1..RBAMP_MAX_CHANNELS (7). Sur la gamme STD, le nombre est celui que signale le module, plafonné à RBAMP_MAX_CHANNELS.
bool hasVoltageHw() const noexcept
Renvoie : true si un capteur de tension a été détecté à begin(). Mis en cache, sans trafic.
uint8_t address() const noexcept
Retourne : l'adresse I²C active sur 7 bits. Mise à jour après un commitAddressChange() réussi.
uint8_t rawTopology() noexcept
Lecture directe de REG_TOPOLOGY (0x24). Contrairement à topology(), cette méthode effectue une transaction I²C.
Returns:
1/2/3—SINGLE/SPLIT_PHASE/THREE_PHASE.0xFF— erreur I²C.
Pour une détection complète de la référence utilisez readVariant() (lit REG_HW_VARIANT 0x55) — voir Identification et provisionnement.
Lectures temps réel (bloc RT, rafraîchissement de 100 ms)
Toutes les méthodes renvoient un float. En cas d'erreur, elles renvoient NAN et définissent lastError(). Sous le capot, une logique de nouvelle tentative et un filtre de cohérence assurent la robustesse face aux rares parasites du lien sur ESP-IDF (voir les compteurs de diagnostic ci-dessous). Le module publie de nouvelles valeurs une fois par fenêtre de mesure — 100 ms (firmware BASIC avant v1.2 et images STD jusqu'à 0x7B : 200 ms).
float readVoltage(uint8_t phase = 0) noexcept
Tension efficace instantanée. phase vaut 0 sur la gamme BASIC ; sur la gamme STD, elle vaut 0 .. n_voltage-1 (voir stdInfo()). Une phase hors plage renvoie NAN avec RB_ERR_PARAM.
float readVoltagePeak(uint8_t phase = 0) noexcept
Tension crête sur la fenêtre RT. Même règle phase.
float readCurrent(uint8_t ch = 0) noexcept
Courant multi-canaux (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.14 Fenêtre d'accès aux canaux (0x32 + 0x3C..0x3F) (api-reference)
Courant efficace instantané sur un canal. ch doit être < channels(), sinon NAN avec RB_ERR_PARAM. Cela inclut tout canal égal ou supérieur à RBAMP_MAX_CHANNELS (7).
float readCurrentPeak(uint8_t ch = 0) noexcept
Courant crête sur un canal, sur la fenêtre RT.
float readPower(uint8_t ch = 0) noexcept
Référence des registres RT (realtime-polling) · Comptabilité bidirectionnelle (period-metering)
Puissance active instantanée sur un canal. Signée — une valeur négative signifie export (la charge réinjecte de la puissance dans le réseau, pertinent pour les installations PV / bidirectionnelles).
float readPowerFactor(uint8_t ch = 0) noexcept
Facteur de puissance sur un canal. Sans dimension, plage −1..+1.
float readReactivePower(uint8_t ch = 0) noexcept — STD uniquement
Puissance réactive sur un canal, en var, signée. Sur BASIC, la puissance réactive n'est pas exposée par cette bibliothèque : l'appel renvoie NAN avec RB_ERR_NOT_IMPLEMENTED.
float readApparentPower(uint8_t ch = 0) noexcept — STD uniquement
Puissance apparente sur un canal, en VA. Sur un module BASIC, renvoie NAN avec RB_ERR_NOT_IMPLEMENTED.
float readFrequency() noexcept
Fréquence du réseau, en Hz.
bool readAll(RbAmpSnapshot& out) noexcept
Référence des registres RT (realtime-polling) · Interrogation — module unique (realtime-polling) · 4.10 Bloc temps réel V03 (0x86..0xBD) (api-reference)
Le bloc RT complet en un seul appel, dans une structure RbAmpSnapshot. Équivalent à des readVoltage() + readVoltagePeak() séquentiels.
readCurrent(0..N)+readCurrentPeak(0..N)+readPower(0..N)+readPowerFactor(0..N)+readFrequency(). Les canaux inutilisés (au-delà dechannels()) sont remplis de zéros.
Un champ unique qui est lu mais échoue au filtre physique de cohérence est mis à NAN et signalé dans out.implausible (bits RBAMP_FIELD_*) ; le reste de l'instantané reste utilisable.
Renvoie : true sauf si une lecture de transport a échoué — dans ce cas false, et lastError() contient le code de la première erreur.
Comptage par période
Voir 01 · Vue d'ensemble pour la vision globale et l'étape 5 de 05 · Démarrage rapide pour un modèle minimal.
bool latchPeriod() noexcept
Écrit CMD_LATCH_PERIOD (0x27) dans REG_COMMAND. N'attend pas : l'appelant doit lui-même observer le temps de stabilisation de 50 ms et vérifier isPeriodValid() avant la lecture.
Pour la plupart des tâches, utilisez readPeriodSnapshot() — il encapsule toute la séquence.
Retourne : true en cas d'écriture réussie.
bool isPeriodValid() noexcept
04 · Comptage par période et comptabilité tarifaire (period-metering) · Calibration et précision (troubleshooting) · 7.5 Préservation de la période après un instantané échoué (api-reference)
Lit le bit de disponibilité de l'instantané. true si le dernier instantané est frais et prêt à être lu.
float readPeriodAvgPower(uint8_t ch = 0) noexcept
Registres d'instantané de période (period-metering) · 4.11 Bloc de période V03 (0xBE..0xCF) (api-reference) · 4.12 V03 Q + période ch0 (0xD0..0xE3, build de production) (api-reference)
Puissance active moyenne sur un canal sur la période close. Doit être appelée après latchPeriod() + 50 ms de stabilisation + vérification de validité.
float readPeriodMaxPower() noexcept
Registres d'instantané de période (period-metering) · 4.12 V03 Q + période ch0 (0xD0..0xE3, build de production) (api-reference)
Puissance instantanée de crête sur le canal 0 sur la période close.
uint32_t readPeriodLatchMs() noexcept
13. Dérive d'horloge multi-modules dans les longs tests (troubleshooting) · 4.13 dt côté puce de diagnostic (0xEC) (api-reference)
Durée de la période du point de vue de l'appareil, en ms.
latch_ms est une minuterie de diagnostic du module ; ne l'utilisez pas pour l'énergie — utilisez l'horloge du maître (master_dt_ms issu de RbAmpPeriodSnapshot).
bool readPeriodSnapshot(RbAmpPeriodSnapshot& out, uint16_t settle_ms = 50, bool skip_latch = false) noexcept
Cycle d'interrogation continu (recommandé) (period-metering) · Multi-modules — instantané simultané (period-metering) · Calibration et précision (troubleshooting)
Le point d'entrée recommandé pour le comptage par période. La séquence complète en coulisse :
-
Si
skip_latch == true— ignore l'écriture de la commande d'instantané (s'applique aprèsbroadcastLatch()ou une série manuelle de commandes d'instantané). -
Sinon — écrivez
CMD_LATCH_PERIOD. - Capturez
millis()pour calculermaster_dt_ms. -
delay(settle_ms)— 50 ms par défaut selon la spécification du protocole. -
Vérifiez le bit de disponibilité de l'instantané. S'il vaut 0 — positionnez
RB_ERR_STALEet enregistrez l'horodatage (pour que le prochain instantané ne compte pas deux fois surdt). -
Lisez
avg_p[0..channels-1]+max_p+latch_ms. - Mettez à jour l'horodatage + appelez
energy().tick(out, channels_)pour l'intégration automatique des Wh.
| Paramètre | Description |
|---|---|
out |
Structure de sortie. |
settle_ms |
Attente après la commande d'instantané, 50 par défaut. |
skip_latch |
Si true — n'envoyez pas la commande d'instantané, lisez seulement (pour une scène multi-cartes synchronisée). |
Renvoie : true si out.valid == true ; false si la lecture a échoué ou si l'instantané est périmé.
Sur la ligne STD, la stabilisation après un instantané est portée à au moins 300 ms (le module traite l'instantané à la prochaine limite de fenêtre de mesure), latch_ms vaut 0 et master_dt_ms est la période. Sur un module STD qui conserve des compteurs d'énergie à vie persistés au lieu de banques d'instantanés, la période est la différence de deux lectures de compteurs selon la cadence du maître ; avg_p_total, wh_net et module_restarted de l'instantané y sont renseignés.
Comptage de l'énergie (accumulateur côté maître)
RbAmpEnergy& energy() noexcept
const RbAmpEnergy& energy() const noexcept
Accès à l'accumulateur Wh par canal détenu par cette instance RbAmp. L'accumulateur est mis à jour automatiquement à chaque readPeriodSnapshot() réussi. Pour les détails, voir la section « classe RbAmpEnergy » ci-dessous.
double energyWh(uint8_t ch = 0) const noexcept
Algorithme côté maître (period-metering) · 7 · Sémantique (api-reference)
Le total d'énergie courant d'un canal, comme energy().wh(ch) — sauf sur un module STD qui conserve des compteurs persistés mais ne publie aucune répartition par canal (plus d'un canal, ancienne carte de registres) : une demande par canal renvoie alors NaN au lieu d'un 0 qui se lirait comme « rien consommé ». Utilisez RBAMP_ENERGY_CH_TOTAL comme ch pour le total de tous les canaux.
Configuration du capteur
Une séquence en deux temps : d'abord la classe de capteur, puis le modèle. Les deux étapes sont obligatoires sur le firmware BASIC v1.2 et ultérieurs.
Pour un guide détaillé du choix de modèle, voir 03 · Sélection du capteur de courant.
Modèle de CT — un préréglage fonctionnel sur BASIC, une étiquette sur STD. Sur un module BASIC, écrire le modèle de CT applique immédiatement le préréglage correspondant — les lectures de courant changent. Changer la RbAmpSensorClass remet à 0 les modèles de CT des canaux sur le module. Sur un module STD, le modèle n'est qu'une référence (étiquette du capteur) : il ne règle aucun gain, car le module est calibré par canal.
Lecture avant écriture. Les setters lisent d'abord le module. Écrire une classe ou un modèle que le module détient déjà ne fait rien (true, aucune écriture sur le bus, aucun cycle flash) ; une configuration enregistrée peut donc être réappliquée à chaque démarrage sans toucher à l'étalonnage du module. Un module de classe WiredCT ou BuiltinCT (livré et calibré avec son capteur) n'est pas reconfiguré : le setter renvoie false avec RB_ERR_MODE et n'écrit rien. setCTModelChForce() est la voie de maintenance.
Définir un modèle de TC redémarre le module. Sur un firmware BASIC jusqu'à 1.4.19 avec la classe SCT-013, setCTModel() (les deux formes) et configureChannels() redémarrent le module après la sauvegarde pour que le nouveau modèle prenne effet (environ une seconde au total, bloquant), puis relisent la correction de calibre. Ne les appelez pas en boucle et n'attendez pas de lectures pendant ce temps.
bool setSensorClass(RbAmpSensorClass cls) noexcept
Définir la classe de capteur et le modèle de TC (initialization) · 4.3 Système (0x20..0x25) (api-reference) · 6.2 Liaison du modèle de TC — simple préparation + CMD par canal (api-reference)
Définir la classe du capteur de courant avec une sauvegarde en flash.
Séquence : lire la classe actuelle du module (lecture avant écriture) → écrire REG_SENSOR_CLASS (0x25) → CMD_SAVE_USER_CONFIG (0x32) → attendre 700 ms (effacement flash). Bloquant. Compatible production — SAVE_USER_CONFIG n'est pas soumis à verrouillage.
Doit être appelé avant setCTModel(). Sinon, setCTModel() renvoie false avec RB_ERR_PARAM. Il remet aussi les modèles de CT à 0 côté appareil ; réglez donc les modèles ensuite. Sur la gamme STD, la classe est une simple métadonnée, enregistrée avec la sauvegarde de configuration du module, et les mêmes règles de lecture avant écriture s'appliquent.
| Argument | Signification |
|---|---|
RbAmpSensorClass::Sct013 |
Pince de la série SCT-013 montée par l'utilisateur ; le modèle choisit le type de capteur |
RbAmpSensorClass::WiredCT |
TC câblé livré avec le module et calibré avec lui — non réécrit par les setters |
RbAmpSensorClass::BuiltinCT |
CT intégré, calibré avec le module — non réécrit par les setters |
Renvoie : true en cas de succès, ou lorsque le module détient déjà cls. false avec RB_ERR_MODE lorsque le module est de classe WiredCT / BuiltinCT.
bool readSensorClass(uint8_t& out) noexcept
Lit la classe de capteur de courant du module (une valeur RbAmpSensorClass ; 0 = non définie). Fonctionne sur les deux gammes.
Renvoie : true en cas de succès.
bool setCTModel(uint8_t code) noexcept
La forme à paramètre unique — règle le modèle de pince CT sur le canal 0 uniquement. Pratique pour les références à un seul canal (UI1/I1) ; sur les modèles multi-canaux, elle équivaut à setCTModel(0, code).
Séquence : écrire REG_CT_MODEL (0x05) → CMD_SET_CT_MODEL_CH0 (opcode 0x28) → 5 ms de stabilisation → CMD_SAVE_USER_CONFIG (opcode 0x32) → 700 ms. Compatible production — utilise le chemin de sauvegarde de la configuration utilisateur, sans verrouillage du mode usine.
Désignez le modèle avec le define RBAMP_CT_* généré (issu de RbAmpSensorModels.h), par exemple RBAMP_CT_SCT013_030 :
| Définir | code |
Modèle |
|---|---|---|
RBAMP_CT_SCT013_005 |
1 | SCT-013-005 |
RBAMP_CT_SCT013_010 |
2 | SCT-013-010 |
RBAMP_CT_SCT013_030 |
3 | SCT-013-030 |
RBAMP_CT_SCT013_050 |
4 | SCT-013-050 |
RBAMP_CT_SCT013_100 |
5 | SCT-013-100 |
RBAMP_CT_SCT013_020 |
6 | SCT-013-020 |
RBAMP_CT_SCT013_060 |
7 | SCT-013-060 |
Un code absent du registre pour la classe du module → false avec RB_ERR_PARAM et aucune écriture. Un code présent dans le registre mais que le module n'accepte pas est rejeté par le module avec RB_ERR_PARAM ; le canal conserve son modèle précédent. Pour l'ensemble d'acceptation complet par classe, voir 03 · Choix du capteur de courant.
Pour les modules multi-canaux, utilisez la forme par canal ci-dessous.
bool setCTModel(RbAmpCTModel model) noexcept
Surcharge à énumération typée pour les sept codes SCT-013 (RbAmpCTModel::Sct013_030 …). Équivalent à setCTModel(static_cast. Conservée pour la compatibilité ascendante ; le nouveau code transmet une constante RBAMP_CT_* générée à la forme uint8_t, qui est la seule façon de nommer un modèle de TC câblé.
bool setCTModel(uint8_t channel, uint8_t code) noexcept
Réglage de la classe de capteur et du modèle de CT (initialization) · 6.2 Liaison du modèle de CT — préparation pure + CMD par canal (api-reference)
La forme par canal. Définit le modèle de pince CT sur un canal précis, 0 .. channels()-1 (les canaux 3 et plus sont ceux de la référence haut de gamme ; ils nécessitent le firmware BASIC v1.4.18 ou ultérieur).
Sous le capot : écriture de REG_CT_MODEL (0x05) → commande CMD_SET_CT_MODEL_CH0/1/2 (opcode 0x28/0x29/0x2A) selon channel → 5 ms de stabilisation → CMD_SAVE_USER_CONFIG (opcode 0x32) → 700 ms. Compatible production — le chemin de sauvegarde de la configuration utilisateur est le canal de persistance en production pour ct_model / sensor_class / TC par canal. Les canaux 3 et au-delà sont liés via la fenêtre de canaux et relus ; un modèle rejeté par le module est signalé comme RB_ERR_PARAM. Sur un firmware antérieur à v1.2, l'appel renvoie RB_ERR_VERSION.
L'ordre des appels est indifférent en v1.3. Écrire REG_CT_MODEL (0x05) ne fait que préparer une valeur — elle n'est pas appliquée automatiquement au canal 0. L'application se fait exclusivement par le code de commande par canal CMD_SET_CT_MODEL_CHn (0x28 / 0x29 / 0x2A), qui recopie la valeur préparée dans son propre canal. Les canaux peuvent donc être configurés dans n'importe quel ordre — croissant, décroissant ou entrelacé — sans écrasement :
dev.setCTModel(0, RBAMP_CT_SCT013_005); // channel 0
dev.setCTModel(1, RBAMP_CT_SCT013_030); // channel 1
dev.setCTModel(2, RBAMP_CT_SCT013_020); // channel 2
Après une liaison multi-canaux, confirmez le résultat avec readCTModelCh(). Pour une configuration groupée à une seule sauvegarde de tous les canaux, préférez configureChannels().
Garde RB_ERR_PARAM sur la précondition de setSensorClass(), comme dans la forme à paramètre unique. Un canal égal ou supérieur à channels() (donc tout canal au-delà de RBAMP_MAX_CHANNELS) → RB_ERR_PARAM. La règle lire-avant-écrire et le refus RB_ERR_MODE s'appliquent comme décrit plus haut. Sur la gamme STD, le modèle est une étiquette écrite dans l'entrée du canal, relue et enregistrée avec la sauvegarde de configuration du module ; aucun effet de bord sur le canal 0.
Retourne : true en cas de succès, ou lorsque le canal détient déjà code.
bool setCTModel(uint8_t channel, RbAmpCTModel model) noexcept
Surcharge à énumération typée de la forme par canal (codes SCT-013 uniquement).
bool setCTModelChForce(uint8_t channel, uint8_t code) noexcept
Voie de service. Identique à setCTModel(channel, code), mais écrit quelle que soit la classe du module et le modèle que le canal détient actuellement. Elle remplace la calibration appariée de ce canal par le préréglage générique du modèle — à n'utiliser que pour réapparier un module avec un nouveau capteur en service, puis à faire suivre d'une calibration. Un code absent du registre est toujours rejeté (RB_ERR_PARAM, aucune écriture).
Renvoie : true en cas de succès.
bool readCTModelCh(uint8_t channel, uint8_t& out) noexcept
4.7 Miroirs de vérification du modèle de TC (0x51..0x53) (api-reference) · 8.10 Relecture du miroir de vérification du modèle de TC (contrôle après liaison) (api-reference)
Lit le modèle de CT réellement appliqué à un canal (le miroir de vérification du préréglage lié). Utilisez-la pour confirmer qu'une liaison a pris. out = 0 signifie non défini.
Renvoie : true en cas de succès.
Registre des capteurs — sensorModel() / sensorModelRatedA()
Simples recherches dans le registre généré (RbAmpSensorModels.h). Aucun trafic sur le bus. Une correspondance dans le registre ne signifie pas que le module connecté accepte le code — c'est le module qui en décide au moment de l'écriture.
static const rbamp_sensor_model_info_t* RbAmp::sensorModel(uint8_t cls, uint8_t code) noexcept;
static const rbamp_sensor_model_info_t* RbAmp::sensorModel(RbAmpSensorClass cls, uint8_t code) noexcept;
static float RbAmp::sensorModelRatedA(uint8_t cls, uint8_t code) noexcept;
static float RbAmp::sensorModelRatedA(RbAmpSensorClass cls, uint8_t code) noexcept;
sensorModel() renvoie l'entrée du registre ou nullptr si (class, code) ne figure pas dans le registre. L'entrée (rbamp_sensor_model_info_t) porte sensor_class, code, name, descriptor, status (caractérisé / réservé / ancien) et les limites actuelles nominal_a (courant efficace nominal), fs_a (courant efficace au début de l'écrêtage pour un sinus) et peak_a (plafond d'écrêtage instantané). 0 dans une limite = inconnu pour ce modèle.
sensorModelRatedA() renvoie le courant efficace nominal en ampères (0 = inconnu). Il couvre la famille SCT-013 et les modèles de pinces qui portent un calibre ; les codes anciens de tore / de charge renvoient 0.
float rated = RbAmp::sensorModelRatedA(RbAmpSensorClass::Sct013, RBAMP_CT_SCT013_030);
const rbamp_sensor_model_info_t* m = RbAmp::sensorModel(RbAmpSensorClass::Sct013, RBAMP_CT_SCT013_030);
if (m) Serial.println(m->descriptor);
Correction de calibre SCT-013
Sur le firmware BASIC jusqu'à 1.4.19, un module de classe SCT-013 est calibré sur le SCT-013-030 et, après un redémarrage, applique ce gain calibré quel que soit le modèle affiché par un canal. La bibliothèque compense : begin() lit le modèle et le gain appliqué de chaque canal et définit une échelle par canal. Cette échelle s'applique à readCurrent(), readCurrentPeak(), readPower(), readAll(), readPeriodAvgPower(), readPeriodMaxPower() et readPeriodSnapshot(), et donc à l'énergie qui en découle. Le facteur de puissance et la tension ne sont pas modifiés. Les bornes de vraisemblance et setEventThresholds() sont exprimées en ampères et en watts réels.
Ainsi, changer le calibre SCT-013 (par exemple de 030 à 050) corrige automatiquement le courant, la puissance et l'énergie ; cela ne modifie ni U ni PF. Le firmware 1.4.20 et plus corrige lui-même — l'échelle reste à 1 et une écriture de modèle ne nécessite aucun redémarrage. Les modules STD et les classes de pince câblée / intégrée ne sont jamais mis à l'échelle.
bool sctRatingRefresh() noexcept
Relit l'état de calibre de chaque canal depuis le module. La bibliothèque le fait déjà après que readEventFlags() signale EVENT_RESET_OCCURRED ; appelez-la vous-même après un redémarrage du module détecté autrement.
Renvoie : true lorsque le module a pu être lu.
bool sctRating(uint8_t channel, RbAmpSctRating& out) noexcept
État d'un canal : model, applied_gain, noise_floor, scale et status.
Retourne : true si channel est valide.
RbAmpSctRatingStatus |
Signification |
|---|---|
NotApplicable |
Ligne STD, une classe autre que SCT-013, firmware qui se corrige seul, ou aucun modèle défini — échelle 1 |
Native |
le canal affiche le modèle sur lequel le module a été calibré (030) — rien à corriger, échelle 1 |
Corrected |
autre modèle SCT-013 sur un firmware BASIC plus ancien — les lectures sont mises à l'échelle |
Uncalibrated |
le module applique un préréglage générique sans sa propre correction — correction nominale uniquement |
UnexpectedGain |
le gain appliqué n'est pas celui attendu par la correction — rien n'est supposé, échelle 1 |
Unknown |
l'état n'a pas pu être lu — échelle 1 |
float sctRatingScale(uint8_t channel) const noexcept
Le facteur appliqué aux lectures de courant / puissance de ce canal (1.0 lorsque rien n'est corrigé, et pour un indice de canal au-delà de RBAMP_MAX_CHANNELS).
static float sctPresetGain(uint8_t model) noexcept
Valeur de gain préréglé de la bibliothèque pour un code de modèle SCT-013 ; 0 si inconnu. Surtout utile pour le diagnostic.
bool configureChannels(RbAmpSensorClass cls, const uint8_t* models, uint8_t n) noexcept
Voir Configuration multi-canaux.
bool saveGains() noexcept — mode usine uniquement sur BASIC
Une écriture CMD_SAVE_GAINS (0x26) « nue » — le chemin de persistance d'usine pour les coefficients de calibration (gains / plancher de bruit / phase).
⚠ Réservé à l'usine sur BASIC. BLOQUÉ en production. Sur un module BASIC de production, CMD_SAVE_GAINS est rejetée par le firmware — l'appel renvoie false, REG_ERROR est positionné sur DEV_ERR_PARAM (0xFE), et le redémarrage suivant annule toute écriture seulement en RAM. Pour toute persistance destinée à l'utilisateur (classe de capteur, modèle de TC par canal, adresse, configuration de parc, étiquette), utilisez saveUserConfig() (CMD_SAVE_USER_CONFIG, opcode 0x32) — c'est le chemin de persistance compatible production. Le code utilisateur dans un contexte de déploiement ne doit pas appeler saveGains().
Ligne STD : saveGains() émet la sauvegarde de calibration du module, attend que le module signale la fin de la commande et vérifie son verdict. Le module écrit son stockage au plus une fois toutes les 5 s ; une sauvegarde dans cette fenêtre est relancée une fois après 5 s.
Renvoie : true en cas de commande réussie (production BASIC : toujours false avec RB_ERR_MODE).
bool prepareAddressChange(uint8_t new_addr) noexcept
Changement d'adresse (initialization) · 4.5 Adresse (0x30..0x31) (api-reference) · 6.1 Changement d'adresse — commit en deux phases (compatible production) (api-reference)
Étape 1 sur 2 pour changer l'adresse I²C du module. Adapté à la production sur le firmware actuel (validation en deux phases v1.3, sans verrouillage par mode usine pour l'adresse).
Séquence : valider la plage de new_addr (0x08..0x77, ≠ actuelle) → écrire le candidat dans REG_I2C_ADDRESS (0x30) en RAM → écrire le magic 0xA5 dans REG_ADDR_COMMIT_MAGIC (0x31) — armé. L'appelant doit appeler commitAddressChange() dans les 5 secondes, faute de quoi l'armement expire.
Retourne : true si l'armement a réussi.
bool commitAddressChange() noexcept
Changement d'adresse (initialization) · 6.1 Changement d'adresse — validation en deux phases (adapté à la production) (api-reference) · 8.5 Changement d'adresse en 5 étapes (api-reference)
Étape 2 sur 2. Doit être appelée dans les 5 secondes suivant prepareAddressChange().
Séquence : vérifier la fraîcheur de l'état armé par magic → CMD_COMMIT_ADDR (opcode 0x30) → enregistrer en flash → CMD_RESET (0x01) → ~300 ms de démarrage jusqu'à la réponse → mettre à jour le champ d'adresse interne. Ensuite, tous les appels sur cette instance visent la nouvelle adresse.
⚠ Réénumération après validation. Après une validation réussie, l'appareil redémarre et se réénumère à la NOUVELLE adresse. Les appels suivants sur cette instance RbAmp visent la nouvelle adresse de façon transparente — mais tout AUTRE maître du bus (un script Python, un composant ESP-IDF sur un autre MCU, une sonde de débogage) continuera de croire que l'appareil est à l'ancienne adresse tant que son état interne n'aura pas été mis à jour à la main.
⚠ Chemin de vérification (v1.3) : après redémarrage, REG_I2C_ADDRESS (0x30) lit l'adresse active. Un scan du bus à la nouvelle adresse permet aussi de confirmer la validation.
Le changement d'adresse est une opération de production (et non réservée à l'usine). L'adresse I²C — la voie documentée est la reconfiguration sur le banc d'usine (hors du périmètre de la bibliothèque).
Une note supplémentaire pour commitAddressChange() :
⚠ Redémarrage et réénumération après validation. Après une validation réussie, l'appareil redémarre et se réénumère à la NOUVELLE adresse. Les appels suivants sur cette instance RbAmp visent la nouvelle adresse de façon transparente — mais tout AUTRE maître du bus (un script Python, un composant ESP-IDF, une sonde de débogage) continuera de croire que l'appareil est à l'ancienne adresse tant que son état interne n'aura pas été mis à jour à la main.
Si la fenêtre d'armement a expiré, commitAddressChange() renvoie false avec RB_ERR_TIMEOUT et efface l'indicateur d'armement — un nouvel appel à prepareAddressChange() sera nécessaire.
Renvoie : true en cas de succès.
Ligne STD : le champ d'adresse est écrit et sauvegardé (l'appel attend la fin de la sauvegarde ; une adresse rejetée renvoie RB_ERR_PARAM et le module conserve son adresse), puis le module est réinitialisé. L'instance ne bascule vers la nouvelle adresse qu'une fois que le module y répond (jusqu'à 3 s). S'il revient sur l'ANCIENNE adresse, l'instance y reste et RB_ERR_NOT_READY est renvoyé.
bool factoryReset() noexcept
La commande CMD_FACTORY_RESET (0xAA) + attente de 1500 ms.
⚠ Opération destructive. Efface TOUS les paramètres en flash (modèle de TC, classe de capteur, coefficients de calibration, adresse I²C). Le module revient à ses valeurs d'usine — RbAmpSensorClass devient Unset, REG_CT_MODEL devient 0. Tout réglage précédemment appliqué via setSensorClass() / setCTModel() est perdu. Le prochain utilisateur DOIT réappliquer setSensorClass() et setCTModel() avant que le comptage ne fonctionne à nouveau. Ce n'est pas un « redémarrage léger » — pour un redémarrage léger, utilisez reset(). factoryReset() est réservé à la récupération d'un état connu comme défectueux ou au transfert du module à un autre utilisateur / une autre installation.
Retourne : true en cas d'écriture de commande réussie.
Ligne STD : il n'existe pas d'équivalent — l'appel renvoie false avec RB_ERR_NOT_IMPLEMENTED.
bool reset() noexcept
La commande CMD_RESET (0x01) + attente de 100 ms. Redémarrage à chaud de l'appareil, sans perte des paramètres en flash.
Retourne : true en cas d'écriture de commande réussie.
Ligne STD : attend d'abord toute commande en cours (un module n'est jamais réinitialisé en pleine sauvegarde), puis attend en silence (jusqu'à 3 s) que le module réponde à nouveau et réarme le chemin de période.
Bus multi-modules (statique)
static bool broadcastLatch(TwoWire& bus) noexcept
Envoie une diffusion d'instantané I²C General-Call (A5 27 00 tick_lo tick_hi à l'adresse 0x00) — tous les modules dont le GC est activé prennent simultanément l'instantané de période. Sur le firmware v1.3, le GC est pris en charge comme capacité sur option : activation par module via REG_FLEET_CONFIG.bit0 (désactivée par défaut) ; la carte de capacités du module indique s'il prend en charge l'instantané General-Call. Le General-Call est une fonction de la gamme BASIC (les aides General-Call et étiquettes renvoient RB_ERR_NOT_IMPLEMENTED sur une instance STD).
Sémantique du retour :
-
Firmware v1.3, GC activé sur au moins un module — renvoie
true; le parc prend son instantané de façon synchronisée (décalage < 1 ms entre les modules). -
Firmware v1.3, GC désactivé sur tous les modules —
Wire.endTransmission()vers0x00est NACKé au niveau du bus → renvoiefalse. Correctif : activez GC module par module viaenableGc(true)(écritFLEET_CONFIG.bit0+SAVE_USER_CONFIG+ réinitialisation), ou utilisezRbAmpFleet::enableGcAll(). -
Firmware ancien sans prise en charge du General-Call — renvoie
falsesans toucher au bus. Repliez-vous sur une série séquentielle delatchPeriod()sur chaque appareil — voir 06 · Exemples, la section bus multi-modules.
Diagnostic
int8_t lastError() const noexcept
Renvoie : le code de la dernière erreur — RB_OK (0) ou l'une des valeurs RB_ERR_* (négatives). Le tableau complet figure dans la section « Codes d'erreur » ci-dessous + 10 · Dépannage.
static const char* errorString(int8_t code) noexcept
Renvoie : une chaîne constante décrivant lisiblement le code d'erreur. Ne renvoie jamais NULL.
void setLogStream(Stream* stream) noexcept
Un puits de diagnostic facultatif. S'il est défini, la bibliothèque journalise brièvement les résultats de probe(), les instantanés périmés et les rejets de mode. Passez nullptr pour le désactiver. Désactivé par défaut.
Utilisation type :
dev.setLogStream(&Serial);
uint32_t retryExhaustionCount() const noexcept
Nombre de fois depuis la mise sous tension (ou le dernier resetCounters()) où la boucle de nouvelles tentatives a été épuisée lors d'une lecture d'un seul octet. La valeur en régime permanent est 0. Une valeur non nulle signale des problèmes de liaison (voir 10 · Dépannage).
uint32_t sanityRejectCount() const noexcept
Nombre de valeurs brutes en virgule flottante rejetées par le filtre de cohérence (!isfinite(x) || |x| > 10000). En régime permanent — 0. Une valeur non nulle après l'atténuation par nouvelles tentatives signale généralement un artefact rare de la pile I²C ESP-IDF qui a survécu à la couche de nouvelles tentatives.
void resetCounters() noexcept
Remet les deux compteurs à zéro. Utilisez-le au début d'un test d'endurance ou d'une fenêtre de régression pour ne mesurer que les événements de la fenêtre.
const char* errorString() const noexcept
Raccourci d'instance pour errorString(lastError()). Ne renvoie jamais NULL.
bool readCommitSeq(uint8_t& out) noexcept — BASIC uniquement
Lit l'octet de séquence de commit du module. Le module l'incrémente une fois par fenêtre de mesure publiée (100 ms sur le firmware v1.2+, 200 ms avant), en revenant de 255 à 0. Échantillonnez-le avant et après une lecture multi-registres pour détecter que les valeurs publiées ont avancé en cours de lecture. C'est uniquement un indicateur de changement — il n'y a pas de CRC. Sur une instance STD, l'appel échoue avec RB_ERR_NOT_IMPLEMENTED (utilisez readDataSeq()).
Renvoie : true en cas de succès.
Identification et provisionnement (v1.3)
Ces méthodes permettent au maître de comprendre exactement ce qui est connecté au bus (variante, carte de bits de capacité, UID, étiquette) et de préparer un module neuf ou fraîchement flashé à l'exploitation (provisionnement + sauvegarde de la configuration en flash).
RbAmpVariant readVariant() noexcept
Détection automatique de la variante du module (initialization) · Référence du protocole filaire rbAmp (v1.3) (api-reference) · 3.6 Algorithme canonique de détection (api-reference)
Lit le registre HW_VARIANT (0x55) du module et renvoie un RbAmpVariant :
| Valeur | SKU | Canaux I | Canal U |
|---|---|---|---|
UI1 (1) |
UI1 | 1 | oui |
UI2 (2) |
UI2 | 2 | oui |
UI3 (3) |
UI3 | 3 | oui |
I1 (4) |
I1 | 1 | non |
I2 (5) |
I2 | 2 | non |
I3 (6) |
I3 | 3 | non |
UI5 (7) |
UI5 (référence haut de gamme) | 5 | oui |
UI7 (8) |
UI7 (référence senior) | 7 | oui |
Unknown (0) |
non identifié (firmware v1.0/v1.1, défaillance I²C, ou ce n'est pas un rbAmp) | — | — |
La détection automatique de la variante via readVariant() est la voie recommandée. L'indication de topologie du constructeur reste un repli pour le firmware antérieur à v1.2 (où HW_VARIANT n'est pas disponible). Indication par défaut = RbAmpTopology::Single — sûre, elle ne déclenche pas de lectures parasites de canaux absents sur UI1/I1.
bool readCapability(uint16_t& out) noexcept — BASIC uniquement
Détection automatique de la variante du module (initialization) · 3.2 CAPABILITY (registres 0x57/0x58, u16 LE, lecture seule) (api-reference) · 8 · Exemples de traces filaires (api-reference)
Lit la carte de fonctions 16 bits du module. Branchez-vous sur les constantes de capacité nommées de RbAmpRegistersV2.h (espace de noms rbamp::v2), jamais sur des heuristiques de version de firmware. Entre autres, la carte indique si le module dispose d'une entrée de tension — sinon il ne calcule pas P / PF / énergie et ces valeurs valent 0 — et s'il prend en charge l'instantané par diffusion General-Call (voir broadcastLatch()). Sur une instance STD, l'appel renvoie false avec RB_ERR_NOT_IMPLEMENTED ; utilisez stdInfo() dans ce cas.
uint8_t readProductId() noexcept
3.5 PRODUCT_ID (0x54, u8, lecture seule) (api-reference) · 4.8 Identité (0x54..0x6F) (api-reference)
Lit PRODUCT_ID (0x54) — l'octet d'identification de la famille (capteur rbAmp = 0x01, rbDimmer = 0x02 ; 0 en cas d'échec). Utilisé par le scanner de flotte pour confirmer que l'appareil à une adresse est bien un rbAmp et non un autre esclave I²C qui aurait répondu à la même adresse. Une instance STD renvoie la famille de capteur.
bool readUid(uint8_t uid[12]) noexcept
Lit l'identifiant unique de 96 bits du MCU depuis UID (0x5C..0x67) en une seule rafale. L'UID est garanti unique pour chaque module et ne change pas au reflashage — pratique pour les journaux série, les contrôles anti-clonage côté maître et l'identification lorsqu'un module est remplacé dans une flotte déployée. Fonctionne sur les deux gammes.
bool readLabel(char out[9]) noexcept — BASIC uniquement
Lit l'étiquette utilisateur de 8 octets depuis LABEL (0x68..0x6F). ASCII, complété par des zéros ; le résultat est toujours terminé par un caractère nul (un tableau de 9 octets = 8 octets de données + le \0 terminal). Une étiquette vide = non définie.
bool writeLabel(const char* label) noexcept — BASIC uniquement
Écrit l'étiquette de 8 octets. Accepte une chaîne terminée par un octet nul — les octets en trop sont tronqués, les manquants sont complétés par des zéros. L'écriture se fait octet par octet pour les écritures multi-octets (le protocole filaire rbAmp incrémente automatiquement les lectures de registres en mode rafale, mais pas les écritures de registres — voir Détails du protocole filaire ci-dessous ; la bibliothèque effectue la boucle d'octets automatiquement). Après l'écriture, il faut dev.saveUserConfig() pour que l'étiquette survive à une réinitialisation.
Un module sorti d'usine peut signaler l'erreur 0xFB (DEV_ERR_FLASH_PARAMS_BAD) à son premier démarrage : le bloc de configuration utilisateur est encore vide. C'est normal (non fatal) ; saveUserConfig() l'efface. N'interrompez pas le provisionnement à la première apparition de 0xFB.
bool saveUserConfig() noexcept
6.5 Provisionnement — flashage neuf + SAVE (api-reference) · 8.6 Provisionnement après flashage neuf (api-reference)
Émet CMD_SAVE_USER_CONFIG (opcode 0x32) — enregistre le bloc de configuration utilisateur en flash : SENSOR_CLASS, CT_MODEL par canal, I2C_ADDRESS, FLEET_CONFIG, GROUP_ID, LABEL. Il n'enregistre pas les paramètres de calibration d'usine — ceux-ci relèvent d'un CMD_SAVE_GAINS distinct, verrouillé en mode production.
Bloque le fil pendant environ 700 ms (cycle d'effacement puis d'écriture de la flash). Pendant toute la durée de l'appel, n'essayez pas d'accéder au module depuis d'autres tâches.
Ligne STD : émet la sauvegarde de configuration du module (classe, référence du TC, niveau, adresse I²C ; l'étalonnage est préservé), attend que le module signale la fin de la commande (sans pause fixe) et vérifie son verdict — un champ invalide (par exemple une adresse hors plage) renvoie RB_ERR_PARAM. Une sauvegarde dans la limite de cadence de stockage de 5 s du module est relancée une fois après 5 s.
: confirmer qu'une valeur a été écrite en flash exige un redémarrage + une relecture. Voir la section « modèle d'erreur v1.3 » ci-dessous.
Modèle d'erreur v1.3 — deux canaux indépendants
Les erreurs ont deux canaux indépendants qui fonctionnent de façons différentes. Comprendre la différence est essentiel pour interpréter correctement l'état du module.
| Canal A — côté client, synchrone | Canal B — côté DUT, asynchrone durable | |
|---|---|---|
| Où il réside | Validation dans la bibliothèque (bibliothèque Arduino) | REG_ERROR (0x02) + EVENT_FLAGS.bit3 (0x2A) |
| Quand elle se déclenche | Avant la transaction I²C (la bibliothèque l'arrête) | Après que le firmware a accepté l'écriture puis l'a rejetée |
| Ce que voit le maître | le setter renvoie false + lastError() == RB_ERR_PARAM ; REG_ERROR sur l'appareil reste à 0x00 |
REG_ERROR = le code d'échec immédiatement ; bit3 se verrouille quelques centaines de millisecondes après la transaction |
| Collant | non (simple booléen renvoyé) | dernière écriture de REG_ERROR ; bit3 collant W1C |
| Chemin typique | Un argument hors des bornes autorisées (canal ∉ {0,1,2}, code ∉ l'ensemble caractérisé, sensor_class hors énumération) | Une écriture brute de registre que la bibliothèque ne valide pas à l'avance (usage bas niveau de writeReg() avec un masque invalide) |
Canal A — validation côté client (setters de la bibliothèque)
Tous les setters de la bibliothèque (setSensorClass, setCTModel, setCTModel(ch, code), configureChannels, etc.) vérifient d'abord les arguments par rapport aux valeurs autorisées. Si un argument est hors plage, le setter renvoie false et fixe lastError() == RB_ERR_PARAM, sans effectuer aucune transaction I²C. En conséquence, REG_ERROR sur l'appareil n'est pas touché :
if (!dev.setCTModel(/*ch=*/99, /*code=*/3)) { // client-side guard
Serial.print(F("rejected: "));
Serial.println(dev.lastError()); // RB_ERR_PARAM (lib cached)
uint8_t reg_err = dev.readLastError(); // device REG_ERROR byte
Serial.println(reg_err, HEX); // 0x00 — REG_ERROR untouched
}
lastError() vs readLastError() — deux canaux différents, pas des synonymes. lastError() renvoie le code mis en cache côté bibliothèque RB_ERR_* de l'appel précédent — sans aucune opération I²C. readLastError() effectue une lecture unique sur le fil du registre REG_ERROR (0x02) de l'appareil — le résultat de la dernière écriture côté firmware. Dans le canal A (ci-dessus), lastError() = RB_ERR_PARAM tandis que readLastError() = 0x00 (la bibliothèque n'a jamais atteint le fil — REG_ERROR non touché). Dans le canal B (ci-dessous), les deux affichent un code, mais différemment : lastError() — la dernière sémantique de la bibliothèque en cache ; readLastError() — la valeur exacte de l'octet REG_ERROR à cet instant.
Cela signifie : si vous voulez savoir exactement pourquoi un setter a refusé, la source fiable est le code de retour de la fonction + lastError(). REG_ERROR sur l'appareil ne vous dira rien dans ce scénario.
Canal B — rejet côté DUT (asynchrone durable)
Si l'écriture a transité par I²C (la bibliothèque ne l'a pas arrêtée, car l'argument semblait valide) mais que le firmware l'a rejetée, le second canal entre en jeu :
-
readLastError()contient immédiatement le code de raison (par exemple0xFE = DEV_ERR_PARAM). C'est le résultat de la dernière écriture : toute écriture réussie suivante l'écrasera. Vous devez le lire immédiatement après votre écriture, avant toute autre transaction. -
hasError(out)— l'indicateur collant W1CEVENT_FLAGS.bit3. Il ne se lève pas instantanément : au banc, un délai de quelques centaines de millisecondes a été mesuré entre la transaction en échec et la levée de bit3. Juste après l'écriture, bit3 vaut encorefalse; après 300 ms, il vauttrue. Ensuite,bit3reste stable quel que soit le nombre de lectures.
⚠ N'utilisez pas hasError() pour valider une écriture que vous venez de faire. Pour le résultat de cette écriture précise, seul readLastError() est fiable, lu immédiatement après l'écriture et avant toute autre transaction (ainsi que le code de retour du setter, s'il en a un). hasError() est un canal asynchrone pour une supervision par interrogation (« une panne est-elle survenue entre deux contrôles ? »), et non une validation synchrone.
Effacer une erreur durable — effacer les deux (REG_ERROR et bit3)
bit3 est repris par le firmware toutes les quelques centaines de millisecondes à partir de l'état actuel de REG_ERROR. Donc un simple clearEventFlags(1 << 3) ne fonctionnera pas — bit3 sera immédiatement réarmé depuis le REG_ERROR non encore effacé. Ordre correct : d'abord clearError() (efface REG_ERROR), puis clearEventFlags(1 << 3) (efface le verrou sticky). Si vous voulez l'atomicité — aucune écriture rejetée ne doit s'intercaler entre les deux.
uint8_t readLastError() noexcept
3. DATA_VALID (0xCE) ne passe jamais à 1 (troubleshooting) · Codes d'erreur (REG_ERROR = 0x02) (troubleshooting) · 4 · Carte des registres (production v1.3) (api-reference)
Lit directement le registre REG_ERROR (0x02) de l'appareil (une seule lecture sur le fil ; renvoie 0x00 pour OK, 0xFA..0xFF pour une classe d'erreur, et 0xFF si la lecture I²C elle-même a échoué) — le résultat de la dernière transaction acceptée par le bus (une écriture ou une commande). Non collant : toute écriture réussie suivante l'écrase avec son propre résultat. Utilisé dans le canal B (rejet côté DUT) pour le code de raison étendu. Sur la gamme STD, le verdict de commande est déjà traduit en lastError() (voir l'API de la gamme STD).
À ne pas confondre avec lastError() : il s'agit d'une méthode différente, qui renvoie le code RB_ERR_* mis en cache par la bibliothèque lors de l'appel précédent, sans opération I²C. Voir l'encadré du canal A ci-dessus.
bool hasError(bool& out) noexcept
Une aide pratique au-dessus de EVENT_FLAGS.bit3. Renvoie true dans out si bit3 est levé. Collant W1C ; non effacé tant qu'on ne le remet pas explicitement à zéro (avec une réserve — voir la section « Effacer une erreur durable » ci-dessus).
bool readEventFlags(uint8_t& out) noexcept / bool clearEventFlags(uint8_t mask) noexcept
8.8 Flux d'événements de seuil — écriture du seuil → déclenchement → effacement W1C (api-reference)
EVENT_FLAGS (0x2A) — un octet d'indicateurs collants ; les bits précis sont décrits dans la spécification (dont ERROR_OCCURRED bit3). L'effacement se fait par écriture-à-1-pour-effacer : écrivez un masque dont les bits à remettre à zéro sont à un à réinitialiser.
bool clearError() noexcept
Codes d'erreur (REG_ERROR = 0x02) (troubleshooting) · 6.7 Rétablissement après erreur — arbre de décision (api-reference)
Émet CMD_CLEAR_ERROR (opcode 0x31) — remet REG_ERROR à zéro. Nécessaire pour effacer une erreur durable, en complément de clearEventFlags(1 << 3) (voir ci-dessus). Sans clearError(), un simple clearEventFlags(1 << 3) laissera bit3 à true après quelques centaines de millisecondes, à cause du re-verrouillage.
Configuration multi-canaux (v1.3)
Sur les modules multi-canaux, chaque canal de courant a son propre modèle de capteur CT. L'outil atomique pour une configuration en bloc est configureChannels().
bool configureChannels(RbAmpSensorClass cls, const uint8_t* models, uint8_t n) noexcept
Parameters:
-
cls— la classe de capteur, appliquée en premier. AvecRbAmpSensorClass::Sct013, les modèles sont liés ; une demande de liaison de modèles sousWiredCT/BuiltinCTest refusée d'emblée (false,RB_ERR_MODE, rien n'est écrit). -
models— un tableau dencodes de modèle de TC (constantesRBAMP_CT_*générées), un par canal.0laisse le modèle existant de ce canal inchangé. -
n— la longueur du tableau. Bornée àchannels(): les éléments en trop sont ignorés. Sinest plus petit, les canaux manquants restent inchangés (ils gardent leur modèle précédent).
En interne, la fonction effectue :
setSensorClass(cls)une seule fois.- Pour chaque canal
k < min(n, channels): préparerREG_CT_MODEL = models[k]+CMD_SET_CT_MODEL_CHk. - Une sauvegarde terminale à la fin — un cycle d'effacement + écriture de la flash pour toute la configuration au lieu d'un par canal (environ 3 fois moins de cycles d'usure sur trois canaux).
La règle de lecture avant écriture s'applique : une classe ou un modèle déjà détenu par le module n'est pas réécrit, donc réappliquer la même configuration ne coûte que des lectures et aucun cycle de flash. Sur le firmware BASIC jusqu'à 1.4.19 avec la classe SCT-013, le module redémarre après la sauvegarde (voir Configuration du capteur).
Return:
true— la configuration a été appliquée et sauvegardée (ou était déjà en place).-
false+lastError() == RB_ERR_PARAM— unclsinvalide ou unmodels[k]absent du registre (validation côté client, voir « Modèle d'erreurs » ci-dessus) ; le lot est interrompu. -
false+RB_ERR_MODE— le module est d'une classe appariée en usine. false+ autres codes — erreur de bus, délai dépassé, etc.
Codes acceptés pour SCT_013 : {1, 2, 3, 4, 5, 6, 7} (SCT-013-005, -010, -030, -050, -100, -020, -060). Détails — 03 · Choix du capteur de courant.
bool readCTModelCh(uint8_t ch, uint8_t& out) noexcept
Lit le modèle de capteur CT appliqué (miroir de vérification) sur un canal donné. C'est une relecture depuis la RAM, et non une confirmation de persistance — pour confirmer une sauvegarde en flash, utilisez dev.reset() + une relecture du miroir.
Ligne data-ready et événements
Les deux lignes. La sortie DRDY du module est en drain ouvert, au repos à HIGH (rappel côté hôte), et émet une impulsion LOW à chaque publication d'un nouvel instantané complet — une fois par fenêtre de mesure (100 ms). Plusieurs modules peuvent partager une même ligne (OU câblé). Un module dont un événement masqué est en attente maintient la ligne LOW fixe (niveau d'alarme) jusqu'à ce que les drapeaux soient effacés. Sur la ligne STD, le bloc d'événements existe sur les modules dont l'image le fournit ; sur BASIC, à partir du firmware v1.3. Détails matériels — 04 · Câblage.
bool setDrdyPin(int pin) noexcept
01 · Raccordement matériel (hardware-connection) · 03 · Interrogation temps réel (realtime-polling)
Raccordez la ligne DRDY de ce module (ou détachez-la avec pin < 0). Configure la broche en entrée avec la résistance de rappel interne et une interruption sur front descendant ; l'ISR ne fait que compter et horodater le front — aucun trafic bus à cet endroit. Jusqu'à 4 lignes distinctes et 8 modules par ligne. Un module STD dont l'image ne prend pas en charge le contrat data-ready refuse avec RB_ERR_NOT_IMPLEMENTED ; waitDataReady() interroge alors la séquence. Sans ligne, waitDataReady() interroge aussi.
bool waitDataReady(uint32_t timeout_ms, RbAmpDrdyEvent* ev = nullptr) noexcept
01 · Raccordement matériel (hardware-connection) · 03 · Interrogation temps réel (realtime-polling)
Bloque jusqu'à ce que ce module publie un nouvel instantané (ou une alarme), au plus timeout_ms (0 = une vérification unique non bloquante).
Avec une ligne : attend le front, puis confirme qu'il provient de ce module grâce à son numéro de séquence d'instantané (une impulsion d'un autre module sur une ligne partagée est ignorée). Si la ligne reste à BAS peu après le front, un module de la ligne détient une alarme : les indicateurs de chaque module capable d'alarme sur la ligne sont lus et effacés ; ceux de ce module reviennent dans ev, les autres sont mis de côté sur leurs instances et signalés lors de leur prochaine attente. Sans ligne, il interroge la séquence toutes les RBAMP_DRDY_POLL_MS (par défaut 20 ms ; à définir avant d'inclure la bibliothèque pour la modifier).
Renvoie : true avec ev rempli ; false avec RB_ERR_TIMEOUT si rien n'est arrivé, RB_ERR_NOT_IMPLEMENTED sur un module STD dont l'image n'a pas de compteur de publication.
bool readAllReady(uint32_t timeout_ms, RbAmpSnapshot& out, RbAmpDrdyEvent* ev = nullptr) noexcept
waitDataReady() suivi de readAll(), de sorte que la lecture complète tombe dans une seule fenêtre de publication : l'instantané n'est jamais lu deux fois et ne chevauche jamais une publication.
bool readDataSeq(uint16_t& out) noexcept
La séquence d'instantanés du module — le compteur de publication sur STD, la séquence de commit sur BASIC. Uniquement pour la détection de changement.
uint8_t beginEventFlags() const noexcept
Les drapeaux d'événements tels que begin() les a trouvés, avant que la bibliothèque n'écrive quoi que ce soit. EVENT_RESET_OCCURRED signifie que le module a redémarré avant que cette instance ne le rencontre. Aucun accès au bus.
bool readEventMask(uint8_t& out) noexcept / bool setEventMask(uint8_t mask) noexcept
Lire / définir les bits d'événements qui maintiennent DRDY à LOW (bits rbamp::v2::EVENT_*). setEventMask() vérifie par relecture. Le masque réside dans la RAM du module : réappliquez-le après une réinitialisation du module (EVENT_RESET_OCCURRED vous en informe).
bool setEventThresholds(float i_amps, float p_watts) noexcept
4.4 Configuration de la flotte (0x27..0x2F) (api-reference) · 8.8 Flux d'événements de seuil — écriture du seuil → déclenchement → effacement W1C (api-reference)
Règle les seuils de courant / puissance derrière EVENT_THRESH_I / EVENT_THRESH_P ; une valeur <= 0 désactive ce seuil. En RAM du module.
-
BASIC compare le courant maximal des canaux et la somme signée des puissances des canaux — l'injection ne le déclenche jamais.
-
STD compare le courant de n'importe quel canal et la grandeur de la puissance globale — indépendant du sens.
Les événements de seuil sont verrouillés au niveau sur le module (réarmés à chaque fenêtre tant que la condition est vraie) : levez le seuil avant d'espérer une ligne calme.
readEventFlags() / clearEventFlags() / hasError() sont décrits sous Modèle d'erreur.
RbAmpDrdyEvent
struct RbAmpDrdyEvent {
bool fresh; // a new snapshot of THIS module is available
bool by_edge; // woken by the DRDY edge (false = found by polling)
uint16_t seq; // snapshot sequence now
uint16_t missed; // snapshots published since the previous call that were not read
bool alarm; // the line was held LOW (masked event pending on this module)
uint8_t event_flags; // event flags consumed from this module on an alarm, else 0
uint32_t latency_us; // edge to return, µs (0 when polling)
};
RbAmp dev(Wire, 0x50);
...
dev.setDrdyPin(15); // optional: omit to poll
dev.setEventThresholds(0, 3000); // power threshold, W
dev.setEventMask(rbamp::v2::EVENT_THRESH_P);
RbAmpSnapshot snap;
RbAmpDrdyEvent ev;
if (dev.readAllReady(500, snap, &ev)) {
if (ev.alarm) { /* ev.event_flags holds the cleared flags */ }
// use snap
}
Vue d'ensemble des fonctionnalités
Les résumés des fonctionnalités ci-dessous ont été déplacés ici depuis le README.
- Configuration du capteur de courant —
setSensorClass(class)choisit la famille (SCT-013 monté par vos soins ; les modules à pince câblée / intégrée sont livrés calibrés avec leur capteur et ne sont pas reconfigurés), puissetCTModel(code)— ouconfigureChannels(class, models[], n)pour un module multi-canaux en un seul appel. Les setters lisent avant d'écrire : une classe ou un modèle déjà détenu par le module ne coûte ni écriture sur le bus ni cycle de flash, donc réappliquer une configuration enregistrée à chaque démarrage est sans risque. Le jeu de codes SCT-013 accepté est{1=005A, 2=010A, 3=030A, 4=050A, 5=100A, 6=020A, 7=060A}. Les coefficients de calibration se chargent automatiquement depuis la table de préréglages d'usine. Les modules BASIC jusqu'au firmware 1.4.19 sont calibrés sur le SCT-013-030 : lorsque vous choisissez un autre modèle SCT-013, la bibliothèque redémarre le module après l'enregistrement et met ensuite à l'échelle les lectures de courant et de puissance par rapport au gain appliqué par le module (voirsctRating()) ; le facteur de puissance et la tension ne sont pas affectés, et un module qui signale le bit de capacité d'autocorrection (firmware 1.4.20+) n'en a pas besoin. - Gestionnaire
RbAmpFleet— pour plusieurs modules sur un bus :scan()découvre et adopte les modules (avec détection de collision),pollAll()les lit en un seul passage,totalPower()/totalEnergyWh()agrègent, et le chemin General-Call (enableGcAll()→gcLatch(tick)→checkSync()) prend simultanément l'instantané de période de chaque module avec détection des trames manquées par module.provision()/assignAddress()amènent sur le bus, à des adresses distinctes, des modules sortis d'usine. - Deux lignes de produits, une seule API —
begin()détecte si un module parle le modèle de registres BASIC (8 bits) ou STD (16 bits, virgule fixe) et route chaque appel en interne ;line()indique laquelle. Sur un module STD, les mêmes appelsreadVoltage(phase)/readCurrent(ch)/readPower(ch)/readPeriodSnapshot()fonctionnent, les nombres de canaux viennent du module (les modules triphasés sont simplement N > 1), et les extras réservés à STD sont exposés sous forme dereadReactivePower(ch)/readApparentPower(ch),stdReadChannel(ch)(une rafale : I / P / Q / S / PF / crête / énergie signée / harmoniques),stdReadVoltage(v),stdReadHealth(), et huit banques d'instantanés cadencées par le maître (stdArmBanks()→stdLatch(bank)→stdReadLatch(bank)→stdLatchWh()). Les modules qui conservent des compteurs d'énergie à vie persistés au lieu de banques d'instantanés sont servis par les mêmes appelsreadPeriodSnapshot()/energy()(une période est la différence de deux lectures de compteurs ;stdReadEnergy()donne les compteurs bruts), ainsi que l'horloge du module (stdSetTime()), l'historique et le journal d'événements (stdHistRead(),stdEventRead()), l'identité (stdIdentify(),RbAmp::stdProbe()), la mise en service par UID (RbAmp::stdSetAddressByUid()) et la mise à jour du firmware via I2C (stdOtaWritePreparedImage(), images préparées sur la machine de build du fabricant). Chaque commande attend que le module signale sa fin avant de lire le verdict, et les blocs multi-octets sont lus en une seule transaction afin que les compteurs ne se scindent jamais. Les modules qui publient des compteurs à micro-résolution remplissent les champs*_uwh/*_uvarhdeRbAmpStdEnergy(fine == true; sinon dérivés des compteurs grossiers, de sorte que les champs sont toujours utilisables), acceptent un courant de démarrage en dessous duquel un canal ne compte aucune énergie (stdSetEnergyStartCurrent()), et rapportent les angles de phase de tension (angle_degdansstdReadVoltage()) ainsi que la séquence de phases (stdReadPhaseSequence()). Si votre croquis persisteRbAmpStdEnergy(NVS, EEPROM, fichier), stockez les champs individuels dont vous avez besoin dans votre propre format fixe, et non la structure en blob brut — la structure gagne des champs d'une version de bibliothèque à l'autre, et un ancien blob ne correspondra plus à la nouvelle taille. - Ligne de données prêtes et événements —
setDrdyPin(pin)écoute la sortie DRDY du module ;waitDataReady()/readAllReady()reviennent dès que le module publie un nouvel instantané (plusieurs modules peuvent partager une ligne), et un module qui détient la ligne signale un événement masqué (setEventMask(),setEventThresholds()) que l'attente lit et efface pour vous. Sans ligne, les mêmes appels interrogent.
API de la gamme STD
La gamme STANDARD (STD) est détectée par begin() (dev.line() == RbAmpLine::Std). L'API scalaire ci-dessus (readVoltage(), readCurrent(), readPower(), readReactivePower(), readApparentPower(), readAll(), readPeriodSnapshot(), energy(), les setters de configuration, reset(), le changement d'adresse) fonctionne sur les deux gammes. Les appels std* ci-dessous ajoutent les lectures de blocs complets et les fonctions propres à la gamme STD.
- Chaque appel
std*échoue avecRB_ERR_NOT_IMPLEMENTEDsur une instance BASIC. -
La disponibilité des fonctionnalités suit l'image du module : vérifiez
stdReadImageVersion()et les drapeauxvalid/finedes structures renvoyées. Une fonctionnalité que le module n'a pas est signalée comme « non disponible » — elle ne renvoie jamais une valeur inventée. -
begin()effectue la détection de la ligne et la découverte des canaux. Les assistants internes correspondants ne font pas partie de l'API publique ; appelezbegin(),readAll()etreadPeriodSnapshot(). -
Chaque commande attend que le module signale sa fin, puis vérifie son verdict. Une valeur rejetée renvoie
RB_ERR_PARAMet laisse le module inchangé. -
Les primitives 8 bits refusent sur une instance STD, de sorte qu'un chemin réservé à BASIC ne peut jamais exécuter une transaction sur un mauvais registre d'un module STD.
if (dev.begin() && dev.line() == RbAmpLine::Std) {
RbAmpStdChannel c;
if (dev.stdReadChannel(0, c)) {
Serial.printf("P=%.1f W Q=%.1f var S=%.1f VA PF=%.2f\n", c.p, c.q, c.s, c.pf);
}
}
Source de l'énergie et version minimale de la bibliothèque
readPeriodSnapshot() et energy() tirent leur période de l'une de deux sources, choisie une fois par begin() d'après les bits de capacité du module et indiquée dans stdInfo().period_source :
| Le module signale | period_source |
La période / l'énergie provient de |
|---|---|---|
| compteurs d'énergie persistants (bit 13), avec ou sans banques | Counters |
les compteurs du module (une période est la différence de deux lectures) |
| banques d'instantanés uniquement (bit 8) | Latch |
banque 0 |
| aucun | None |
les appels refusent avec RB_ERR_NOT_IMPLEMENTED |
L'image STD série 0x7E signale les deux bits. Elle nécessite la bibliothèque 1.6.2 ou plus récente pour prendre son énergie depuis les compteurs du module. La bibliothèque 1.6.1 et antérieures lisent la période depuis la banque 0 sur cette image, c'est-à-dire une énergie intégrée sur l'hôte au lieu des compteurs propres du module ; mettez la bibliothèque à jour pour obtenir les valeurs issues des compteurs. Les banques restent disponibles sur 0x7E via les appels de Banques d'instantanés de période.
Identité
bool stdInfo(RbAmpStdInfo& out) noexcept
Identité mise en cache depuis begin() — aucun trafic bus. Échoue avec RB_ERR_NOT_IMPLEMENTED sur une instance BASIC ou avant begin().
struct RbAmpStdInfo {
uint8_t map_version; // register-map version
uint16_t capabilities; // feature bitmap of the module
uint8_t status; // status bits at begin() time (live: stdReadHealth())
uint8_t n_voltage; // populated voltage channels
uint8_t n_current; // populated current channels (the library exposes up to RBAMP_MAX_CHANNELS)
uint8_t variant; // raw variant byte (also mapped into readVariant())
uint32_t active_bank; // running firmware bank (firmware update), 0 if none
uint32_t ota_bank_size; // firmware bank size the module reports, 0 if none
RbAmpStdPeriodSource period_source; // which period / energy mechanism this module offers
};
RbAmpStdPeriodSource : Latch (le module dispose de banques d'instantanés ; la banque 0 sert readPeriodSnapshot()), Counters (pas de banques d'instantanés, mais des compteurs d'énergie à vie persistés — une période est la différence de deux lectures de compteurs ; les appels de banque sont refusés sans trafic sur le bus) ou None (les appels de période / d'énergie échouent avec RB_ERR_NOT_IMPLEMENTED).
bool stdIdentify(RbAmpStdIdentity& out) noexcept
Identité de ce module : les données begin() mises en cache, plus l'UID, la version de l'image en cours d'exécution et l'identifiant de carte (ces deux derniers lorsque le module les fournit ; sinon 0).
struct RbAmpStdIdentity {
uint8_t i2c_addr; // 7-bit address the module answered on
uint8_t map_version;
uint16_t capabilities;
uint8_t variant;
uint8_t n_voltage, n_current;
uint8_t uid[12]; // chip UID — the module's identity in a database
uint32_t fw_version; // running image version (0 if unknown)
uint32_t board_id; // board id (0 if unknown)
};
static int8_t stdProbe(TwoWire& bus, uint8_t addr, RbAmpStdIdentity& out) noexcept
Identifie tout ce qui répond à addr sans instance (scan du bus). Un essai par lecture, sans couche de reprise — un NACK est la réponse.
Renvoie : RB_OK ; RB_ERR_NACK si rien n'acquitte à cette adresse ; RB_ERR_VERSION si ce n'est pas un module STD ; RB_ERR_PARAM si l'adresse est hors de 0x08..0x77 ; RB_ERR_IO si une lecture ultérieure a échoué.
bool stdReadImageVersion(uint32_t& out) noexcept
La version de l'image en cours d'exécution (et non la version de la carte de registres) ; 0 si le module n'en signale aucune. Utilisez-la pour voir si une fonction qui exige une image récente est présente (micro-énergie, courant de démarrage, angles de tension et séquence de phases exigent une image d'au moins 0x0001007B).
bool stdReadBoardId(uint32_t& out) noexcept
Identifiant de carte de l'image en cours d'exécution.
Lectures par blocs
bool stdReadChannel(uint8_t ch, RbAmpStdChannel& out) noexcept
Un canal de courant (0 .. channels()-1) en une seule rafale : I, P, Q, S, PF, crête, accumulateurs d'énergie signée bruts et champs d'harmoniques.
bool stdReadTotals(uint8_t k, RbAmpStdChannel& out) noexcept
Un bloc agrégé : k = 0 total général (tous les canaux de courant), k = 1..3 totaux par phase A / B / C (sur un module monophasé, k = 1 égale le canal 0 et k = 2, 3 lisent 0). I / P / Q / S / PF / crête uniquement — sur les modules dotés de compteurs de durée de vie, les champs d'énergie valent 0 ici ; l'énergie provient de stdReadEnergy().
struct RbAmpStdChannel {
float i_rms, i_peak; // A
float p; // W, signed
float q; // var, signed
float s; // VA
float pf; // power factor, −1..+1
float thd_i; // current THD, % — 0 unless harmonics are enabled
float pf1; // displacement power factor — 0 unless harmonics are enabled
float q1; // fundamental reactive power, var — 0 unless harmonics are enabled
int64_t e_import_mws; // raw import energy accumulator (>= 0), see stdLatchWh()
int64_t e_export_mws; // raw export energy accumulator (<= 0)
uint8_t implausible; // RBAMP_FIELD_* bits of fields set to NaN by the sanity filter
};
Pour la supervision, intégrez p vous-même ou utilisez stdReadEnergy() ; les accumulateurs bruts existent pour le chemin des banques d'instantanés.
bool stdReadVoltage(uint8_t v, RbAmpStdVoltage& out) noexcept
Un canal de tension (0 .. n_voltage-1).
struct RbAmpStdVoltage {
float u_rms, u_peak; // V
float thd_u; // voltage THD, % — 0 unless harmonics are enabled
float angle_deg; // phase angle vs voltage 0, degrees; 0 when angle_valid is false
bool angle_valid; // false on older images, when the input is too low to measure, and on single-voltage modules for v > 0
uint8_t implausible;
};
bool stdReadPhaseSequence(RbAmpStdPhaseSeq& out) noexcept
Séquence de phases d'un module à trois tensions, déduite par le module des angles de tension. Renvoie true avec NotAvailable — et sans trafic sur le bus — sur une image qui ne la publie pas ; le module lui-même renvoie NotAvailable avec moins de trois entrées de tension, ou lorsqu'une entrée est trop faible pour être mesurée.
RbAmpStdPhaseSeq : NotAvailable, Forward (L1-L2-L3), Reverse (L1-L3-L2), Abnormal (aucun motif triphasé, par exemple deux entrées sur une même phase).
bool stdReadHealth(RbAmpStdHealth& out) noexcept
Santé du module en temps réel. Considérez les lectures comme valides lorsque status a le bit capteur OK et que frame_count augmente entre deux interrogations.
struct RbAmpStdHealth {
uint8_t status; // status bits: cal_ok / sensor_ok / mains_ok / time_valid / nvm_fault / maint
uint32_t frame_count; // sensor frame counter — must grow between polls (liveness)
uint32_t crc_errors; // sensor frame error counter
bool time_valid; // the module clock was set since its last restart — see stdSetTime()
bool nvm_fault; // energy store unusable
bool maint; // maintenance mode
uint8_t lta_status; // life-time energy store: 0 ok · 1 new · 2 fault · 3 corrupt (service)
uint8_t lta_src; // where the life-time counters were restored from
uint8_t cal_src; // 0 built-in defaults · 1 flash · 2 EEPROM · 3 stored calibration is for another firmware
uint8_t group_status; // per-channel energy store: 0 ok · 1 new · 2 fault · 3 restarted at 0
uint16_t legal_noen, ring_drop; // module diagnostics (ring_drop should stay 0)
uint32_t lost_frames; // should stay flat
uint32_t uptime_s; // seconds since the module's last restart
uint8_t reset_cause; // cause of this boot (image-dependent; 0 below)
uint16_t boot_count; // persisted boot counter, low 16 bits — a master that missed a restart sees it step
};
Les champs marqués « dépendant de l'image » ou documentés pour des cartes de registres plus récentes renvoient 0 / false sur les modules qui ne les fournissent pas. cal_ok peut valoir 0 sur une unité étalonnée avec une image plus ancienne, jusqu'à ce que saveGains() ait été exécuté une fois ; les lectures elles-mêmes ne sont pas affectées.
Banques d'instantanés de période
Un module STD qui signale des banques d'instantanés (bit de capacité 8) conserve huit périodes indépendantes, cadencées par le maître. Usage type : armez une fois les banques dont vous avez besoin ; puis, pour chaque banque, selon votre propre calendrier : stdLatch(bank) → attendre au moins 300 ms → stdReadLatch(bank, snap) → stdLatchWh(snap, dt, ...) avec le dt mesuré par le maître depuis l'instantané précédent de cette banque. Les banques sont un outil à part : elles sont disponibles quelle que soit la source d'énergie du module (voir Source d'énergie et version minimale de la bibliothèque). Sur un module sans banques, stdArmBanks(), stdLatch() et stdReadLatch() refusent avec RB_ERR_NOT_IMPLEMENTED et n'écrivent rien. La banque 0 sert readPeriodSnapshot() et energy() uniquement sur un module qui a des banques et pas de compteurs persistants.
bool stdArmBanks(uint8_t mask) noexcept
Définit le masque d'accumulation : bit b = la banque b accumule (les banques fraîchement armées démarrent propres ; les banques désarmées se figent et conservent leur dernier instantané). Gardez le bit 0 levé si vous utilisez readPeriodSnapshot(). Le masque réside dans la RAM du module et est perdu lors d'une réinitialisation du module ; la bibliothèque réarme une banque lorsqu'une lecture trouve un instantané vide sur une banque désarmée (voir stdReadLatch()).
bool stdLatch(uint8_t bank) noexcept
Demande un instantané et une remise à zéro de bank à la prochaine limite de fenêtre du module. N'attend pas ; lisez-le au moins 300 ms plus tard.
bool stdReadLatch(uint8_t bank, RbAmpStdLatch& out) noexcept
Lit le dernier instantané de bank en une seule rafale (totaux + énergie par canal de chaque canal renseigné).
Renvoie : false avec RB_ERR_STALE si le module n'a jamais pris d'instantané de cette banque (out.valid == false), ou si l'instantané est vide (win_count == 0) parce que la banque a perdu son armement après une réinitialisation du module. Dans ce dernier cas, la bibliothèque réarme et prend un instantané d'amorçage de la banque : écartez cette période et redémarrez votre propre ancre dt (l'intervalle de coupure ne contient aucune donnée).
struct RbAmpStdLatch {
float p_avg, q_avg, s_avg; // average W / var / VA over the period
float max_p, max_i; // peak power (W) and peak RMS current (A)
float max_u, min_u; // peak / minimum RMS voltage (V)
int64_t e_import_mws, e_export_mws; // raw energy accumulators over the period
uint32_t nsamp; // conversion divisor used by stdLatchWh()
uint32_t win_count; // measurement windows in the period (0 = not armed / nothing elapsed)
uint8_t channels, bank;
bool valid; // the bank has EVER been snapshotted (not a freshness signal)
float p_avg_ch[RBAMP_MAX_CHANNELS];
int64_t e_import_ch_mws[RBAMP_MAX_CHANNELS], e_export_ch_mws[RBAMP_MAX_CHANNELS];
};
static bool stdLatchWh(const RbAmpStdLatch& snap, uint32_t dt_ms, uint8_t ch, double& wh_import, double& wh_export) noexcept
Convertit les accumulateurs d'énergie bruts d'un instantané en Wh sur la période dt_ms mesurée par le maître (temps mural entre l'instantané précédent et celui-ci de la banque). ch est un indice de canal, ou RBAMP_STD_TOTAL pour les totaux de banque. wh_import est >= 0, wh_export est <= 0.
Retourne : false si ch est hors plage ou si rien n'a été accumulé.
Compteurs d'énergie à vie
Les modules qui conservent des compteurs d'énergie persistants les gardent en cas de coupure de courant ; ils sont monotones, avec une séparation signée importation / exportation.
bool stdReadEnergy(RbAmpStdEnergy& out) noexcept
Lisez les compteurs d'énergie à vie du module. Chaque bloc est lu en une seule transaction, de sorte qu'un compteur 64 bits ne peut pas se scinder à cheval sur une publication.
Renvoie : false avec RB_ERR_NOT_IMPLEMENTED lorsque le module ne conserve aucune énergie sur l'appareil ; RB_ERR_NOT_READY si le bloc n'est pas programmé.
struct RbAmpStdEnergy {
int64_t act_import_wh, act_export_wh, act_net_wh; // active energy, Wh (export is a magnitude)
int64_t rea_import_varh, rea_export_varh; // reactive energy, varh
uint32_t generation; // steps when the counters were reset or adopted — never take a delta across a change
uint32_t uptime_s; // module uptime at the reading (a drop = the module restarted)
int64_t act_import_mwh, act_export_mwh, act_net_mwh; // mWh (0 on modules without them)
uint8_t channels; // valid entries in the per-channel arrays (0 on modules without them)
uint8_t group_status; // per-channel store: 0 ok · 1 new · 2 fault · 3 restarted at 0
int64_t ch_import_mwh[RBAMP_MAX_CHANNELS], ch_export_mwh[RBAMP_MAX_CHANNELS];
bool fine; // true: the µWh / µvarh fields are the module's own micro-resolution counters
int64_t act_import_uwh, act_export_uwh, act_net_uwh; // µWh
int64_t rea_import_uvarh, rea_export_uvarh; // µvarh
int64_t ch_import_uwh[RBAMP_MAX_CHANNELS], ch_export_uwh[RBAMP_MAX_CHANNELS];
};
Les champs *_uwh / *_uvarh sont toujours renseignés, de sorte que vous pouvez les utiliser sur n'importe quel module : lorsque fine == true, ce sont les compteurs micro-résolution propres au module (image 0x0001007B ou ultérieure) ; sinon ils sont dérivés des compteurs plus grossiers et progressent dans leurs unités. Si votre croquis persiste RbAmpStdEnergy, stockez les champs individuels dont vous avez besoin dans votre propre format fixe plutôt que la structure en blob brut — la structure gagne des champs d'une version à l'autre.
static bool stdEnergyDelta(const RbAmpStdEnergy& prev, const RbAmpStdEnergy& now, RbAmpStdEnergy* delta, bool* module_restarted) noexcept
Énergie entre deux lectures : now − prev, chaque compteur étant ramené à 0 (un compteur peut repartir légèrement sous la dernière lecture après un redémarrage du module) ; le net est recalculé comme import − export des deltas ramenés. delta et module_restarted peuvent valoir nullptr ; delta->fine vaut true seulement si les deux lectures étaient fines ; *module_restarted vaut true quand la durée de fonctionnement de now est inférieure à celle de prev.
Renvoie : false lorsque generation a changé entre les relevés (réinitialisation ou reprise de la durée de vie) — ne comptabilisez pas cet intervalle.
bool stdSetEnergyStartCurrent(uint16_t ua) noexcept
Règle le courant de démarrage pour le comptage de l'énergie, en µA : en dessous de ce courant de canal, le module ne compte aucune énergie pour le canal (importation ou exportation, total et par canal). À vide, la puissance mesurée est du bruit de l'un ou l'autre signe et s'ajouterait sinon aux deux compteurs. Les lectures (I / P / Q) ne sont pas affectées. S'applique immédiatement, vérifié par relecture ; à conserver avec saveUserConfig(). 0 désactive ; sinon la valeur doit être un multiple de 10 µA dans la plage acceptée par le module — toute autre valeur renvoie RB_ERR_PARAM sans écriture sur le bus.
Renvoie : false avec RB_ERR_NOT_IMPLEMENTED lorsque le module ne dispose pas de courant de démarrage (pas d'énergie à micro-résolution, ou image plus ancienne).
bool stdReadEnergyStartCurrent(uint16_t& ua) noexcept
Le courant de démarrage actuel pour le comptage de l'énergie, en µA (0 = désactivé).
Configuration
bool stdReadConfig(RbAmpStdConfig& out) noexcept
Le bloc de configuration en une seule rafale.
struct RbAmpStdConfig {
uint8_t sensor_class; // RbAmpSensorClass value, 0 = unset. Persisted.
uint8_t ct_model; // CT model reference for channel 0 (label only, sets no gain). Persisted.
uint8_t tier; // module tier code. Persisted.
uint8_t i2c_addr; // persisted 7-bit address (applies on reset)
uint16_t rate_ms; // report-rate hint, ms (RAM only)
bool harmonics; // base-harmonics extraction enabled (RAM only)
};
bool stdSetHarmonics(bool enable) noexcept
Active / désactive l'extraction des harmoniques de base (THD, FP de déplacement, puissance réactive fondamentale). En RAM seulement (non persisté), relecture vérifiée. Nécessite la capacité THD du module — sinon RB_ERR_NOT_IMPLEMENTED.
bool stdCalThdFloor() noexcept
Capturez la THD brute sans charge comme plancher du capteur et conservez-la (environ 700 ms). Exécutez sur un secteur propre et sans charge ; ensuite, les lectures de THD sont corrigées du plancher du capteur. Nécessite la capacité THD.
Horloge
L'horloge du module est perdue à chaque redémarrage. Réglez-la après begin() et chaque fois que RbAmpStdHealth::time_valid vaut false ; sans elle, le module n'enregistre aucun historique.
bool stdSetTime(uint32_t unix_epoch) noexcept
Règle l'horloge du module (époque Unix, UTC). Renvoie false avec RB_ERR_PARAM si le module refuse l'époque (avant 2020), RB_ERR_NOT_READY s'il a accepté la valeur mais n'a pas signalé l'horloge valide dans les 300 ms.
bool stdReadTime(uint32_t& unix_epoch, bool& valid) noexcept
L'horloge du module, et l'indication qu'elle a été réglée depuis le dernier redémarrage du module.
Commandes et mise en service
bool stdCommand(uint8_t opcode, uint32_t settle_ms, uint32_t timeout_ms = 0) noexcept
Émet une commande de module et attend son verdict : attend que le module soit inactif (une commande écrite pendant l'occupation est perdue), écrit le code opération, interroge l'état de la commande jusqu'à ce que le module signale sa fin, puis lit le verdict. settle_ms ne borne que la première interrogation. timeout_ms = 0 signifie 1000 ms ; jamais moins de 1000.
Renvoie : false avec le verdict traduit en code d'erreur — PARAM, NOT_IMPLEMENTED (commande inconnue), CHECKSUM (contrôle de la valeur), MODE (clé / verrou), NOT_READY (limite de débit / reprise), TIMEOUT, IO (erreur de stockage du module).
bool stdWaitIdle(uint32_t timeout_ms = 0) noexcept
Attendre que le module indique qu'aucune commande n'est en cours (0 = 1000 ms).
bool stdLocate() noexcept
Faites clignoter les LED du module pendant environ 10 s — pour le repérer dans une armoire.
static int8_t stdSetAddressByUid(TwoWire& bus, uint8_t shared_addr, const uint8_t uid[12], uint8_t new_addr, uint32_t restart_ms = 0) noexcept
Donne à un module parmi plusieurs à une adresse partagée sa propre adresse, sélectionné par UID (mise en service). C'est une écriture seule sur l'adresse partagée (plusieurs modules peuvent répondre, donc rien n'est lu à cet endroit). Le module adressé enregistre la nouvelle adresse et redémarre ; l'appel sonde ensuite la nouvelle adresse et vérifie l'UID. Relancez begin() sur une instance liée à la nouvelle adresse. restart_ms = 0 signifie 1500 ms.
Renvoie : RB_OK ; RB_ERR_PARAM adresse hors plage ; RB_ERR_NACK aucun module n'a acquitté sur l'adresse partagée ; RB_ERR_NOT_READY rien ne répond ensuite à la nouvelle adresse ; RB_ERR_VERSION le module à cette adresse n'est pas celui visé (l'UID diffère).
Historique et journal d'événements
Les enregistrements n'existent que pour les périodes pendant lesquelles l'horloge du module était valide (voir stdSetTime()).
enum class RbAmpStdHistPeriod : uint8_t {
Min15 = 0, // 15-minute energy records — RAM only (the last record survives no restart)
Hour = 1, // hourly energy records — persistent ring (the one to backfill from)
Events = 2, // event log (read with stdEventRead())
};
bool stdHistInfo(RbAmpStdHistPeriod period, RbAmpStdHistInfo& out) noexcept
Résumé de l'anneau : count, capacity, record_size, oldest_ts, newest_ts (heure Unix). Les enregistrements sont récupérés du plus récent au plus ancien par un index back.
bool stdHistRead(RbAmpStdHistPeriod period, uint16_t back, RbAmpStdHistRecord& out) noexcept
Lit et décode un enregistrement de période énergétique (Min15 ou Hour ; back = 0 est le plus récent). Renvoie false avec RB_ERR_NOT_READY lorsqu'il n'existe pas d'enregistrement (anneau vide ou back au-delà) ; RB_ERR_PARAM pour l'anneau d'événements (utilisez stdEventRead()).
struct RbAmpStdHistRecord {
uint32_t ts; // Unix time at the end of the period
uint16_t flags; // partial / power-up / clock / life-time-jump bits
uint16_t n; // measurement windows in the period
bool from_ram; // served from RAM (not yet persisted)
float v_rms, i_total, p_avg, q_avg, s_avg, pf;
float p_min, p_max, i_min, i_max;
uint64_t e_import_wh, e_export_wh; // life-time ABSOLUTE counters at the end of the period
uint8_t phases; // valid entries in the per-phase arrays (0..3)
double ph_import_wh[3], ph_export_wh[3]; // THIS period's energy per phase
};
Ne prenez l'énergie d'une période à partir de deux enregistrements horaires consécutifs que si leurs horodatages diffèrent exactement d'une période et qu'aucun ne porte l'indicateur de saut de durée de vie.
bool stdHistReadRaw(RbAmpStdHistPeriod period, uint16_t back, uint8_t rec[rbamp_std::REG_HIST_REC_SIZE], uint8_t* flags) noexcept
Lit un enregistrement non décodé de n'importe quel anneau dans rec ; flags (facultatif) reçoit les indicateurs d'enregistrement du module.
bool stdEventRead(uint16_t back, RbAmpStdEvent& out) noexcept
Lit et décode un enregistrement du journal d'événements (back = 0 est le plus récent) ; RB_ERR_NOT_READY = aucun enregistrement de ce type.
struct RbAmpStdEvent {
uint32_t ts; // Unix time (0 if the clock was not set)
uint32_t uptime_s; // module uptime at the event
uint8_t type; // record type
uint8_t flags;
uint16_t boot; // boot counter at the event
uint32_t a_before, a_after; // event-specific values
uint64_t e_before_wh, e_after_wh; // life-time energy before / after, Wh
};
bool stdHistFlush() noexcept
Demande au module d'écrire maintenant ses accumulateurs d'énergie dans son stockage.
Mise à jour du firmware via I²C
Une mise à jour en deux phases : stdOtaBegin() → stdOtaWritePage() pour chaque page → stdOtaCommit() (vérifie l'image et arme le basculement ; sans redémarrage) → stdOtaActivate() (redémarre sur la nouvelle image quand vous le décidez). En pratique, utilisez stdOtaWritePreparedImage(), qui enchaîne begin + pages + commit en un appel, puis stdOtaActivate(). Les modules n'acceptent que les images préparées par le fabricant ; une mauvaise image est annulée par le module lui-même et la calibration est préservée. Chaque étape attend que le module signale la fin de la commande (aucune pause fixe). Tous les appels échouent avec RB_ERR_NOT_IMPLEMENTED sauf si le module signale la capacité de mise à jour.
typedef void (*RbAmpOtaProgress)(uint32_t done, uint32_t total, void* ctx);
| Appel | Description |
|---|---|
bool stdOtaStatus(uint8_t& out) |
L'état de mise à jour du module (rbamp_std::OTA_IDLE / READY / OK / ERR / DOWNGRADE). |
bool stdOtaBegin(uint32_t timeout_ms = 0) |
Efface la banque inactive et attend que le module signale qu'il est prêt. 0 = valeur par défaut (5 s). false avec RB_ERR_TIMEOUT si l'état n'est pas atteint. |
bool stdOtaWritePage(uint32_t page_idx, const uint8_t* page) |
Écrit une page de 256 octets à l'index page_idx. false avec RB_ERR_CHECKSUM si la charge utile est arrivée corrompue (renvoyer la même page), RB_ERR_IO si le module a rejeté la page, RB_ERR_NOT_READY si la session n'est plus ouverte — dans les deux derniers cas, repartez de stdOtaBegin() (voir stdOtaDiag()). |
bool stdOtaCommit(uint32_t timeout_ms = 0) |
Vérifie l'image écrite et arme le basculement de banque. 0 = valeur par défaut (3 s). RB_ERR_CHECKSUM image défectueuse, RB_ERR_VERSION image plus ancienne que celle en cours (rejetée), RB_ERR_TIMEOUT. |
bool stdOtaActivate() |
Redémarre dans l'image armée, attend le retour du module, le redécouvre, confirme que la banque en cours a changé et attend que la nouvelle image se confirme. Bloque pendant toute la séquence (environ 12 s). L'instance reste liée et stdInfo() reflète le nouveau firmware. false avec RB_ERR_NOT_READY si rien n'était armé, si le module est revenu sur la banque précédente ou n'a jamais confirmé la nouvelle image ; RB_ERR_VERSION si l'image qui tourne ensuite n'est pas celle qui était préparée (restaurée). |
static uint32_t stdCrc32(const uint8_t* data, size_t len) |
CRC-32 (compatible zlib) — la somme de contrôle par page que le module vérifie. |
bool stdOtaWritePreparedImage(const uint8_t* image, size_t len, RbAmpOtaProgress cb = nullptr, void* ctx = nullptr) |
Envoie une image de banque préparée (begin + pages + commit ; sans activate). len doit être égal à la taille de banque du module, sinon RB_ERR_PARAM. Les pages sont envoyées dans l'ordre croissant ; les pages vides sont ignorées ; une page que le module signale comme corrompue est renvoyée une fois. |
bool stdOtaWritePreparedImage(Stream& image, size_t len, RbAmpOtaProgress cb = nullptr, void* ctx = nullptr) |
Forme en flux — une page conservée en RAM. |
bool stdOtaWritePreparedImage(const uint8_t* bank_a, const uint8_t* bank_b, size_t len, RbAmpOtaProgress cb = nullptr, void* ctx = nullptr) |
Fournissez les deux images par banque ; la bibliothèque choisit celle de la banque qui ne tourne pas. RB_ERR_NOT_IMPLEMENTED si le module ne signale pas sa banque active. |
bool stdOtaActiveBank(uint8_t& out) |
Identifiant de la banque en cours : 0 = A, 1 = B. |
bool stdOtaStagedVersion(uint32_t& out) |
Version de l'image armée (validée, non encore activée) ; 0 lorsque rien n'est armé. |
bool stdOtaDiag(uint8_t& reason, uint8_t& hal_status) |
La raison de l'échec de la dernière mise à jour du module, ainsi qu'un octet d'état bas niveau. À lire après l'échec d'une validation ou d'une écriture de page. |
bool stdOtaAbort() |
Fermez la session de mise à jour / désarmez une image armée sans redémarrer. |
bool stdOtaBoardOk(uint32_t image_board_word) |
Refuse une image conçue pour une autre carte avant de l'envoyer : compare l'identifiant de carte du module au mot de carte de l'image (issu du manifeste de l'image). Une divergence renvoie RB_ERR_PARAM ; RB_ERR_NOT_IMPLEMENTED pour les modules qui ne signalent pas d'identifiant de carte. |
bool stdOtaWriteImage(const uint8_t* image, size_t len, uint32_t version, RbAmpOtaProgress cb = nullptr, void* ctx = nullptr) et la forme Stream& |
Conservé uniquement pour la compatibilité des sources : renvoie false avec RB_ERR_NOT_IMPLEMENTED sans toucher au module. Utilisez stdOtaWritePreparedImage(). |
RbAmpFleet — gérer plusieurs modules
La classe RbAmpFleet est la principale surface de haut niveau de la bibliothèque v1.3. Elle gère une collection de modules sur un bus I²C partagé : découverte, provisionnement, agrégation des interrogations, agrégation des erreurs, et instantanés synchrones via diffusion General-Call.
Une flotte est liée à un seul bus TwoWire (en général Wire) ; chaque module adopté est un handle RbAmp possédé. La limite souple du nombre de modules est RBAMP_FLEET_MAX_MODULES = 16.
Cycle de vie
RbAmpFleet(TwoWire& bus);
~RbAmpFleet(); // releases all adopted handles
Après ~RbAmpFleet(), tout pointeur de handle obtenu via get(idx) est invalide.
Découverte — scan()
Configuration multi-modules (initialization) · Interrogation multi-modules — trois stratégies (realtime-polling) · Problèmes multi-modules (troubleshooting)
bool scan(bool match_product, size_t& added);
Sonde le bus sur la plage 0x08..0x77, et pour chaque adresse qui répond par ACK :
-
Vérifie l'identité (
PRODUCT_ID,HW_VARIANT,CAPABILITY). Simatch_product = true, il exige une correspondance avec le PRODUCT_ID rbAmp. -
Lance un détecteur de conflit sur deux signaux indépendants (cohérence d'identité + valeur en direct). Les adresses suspectes sont placées dans la liste
excluded, et non dans le parc. -
Effectue un témoin de blocage de niveau 2 : il sonde une adresse où il n'y a manifestement personne. Si le témoin reçoit un ACK, renvoie
false— le bus est bloqué et le parc reste vide (voir les diagnostics au chapitre 10).
En cas de succès, added contient le nombre de modules ajoutés au parc. excludedCount() (voir ci-dessous) est disponible via un accesseur séparé.
Accès au module
size_t count() const noexcept;
RbAmp* get(size_t index) noexcept;
RbAmp* find(uint8_t address) noexcept;
bool add(RbAmp* dev) noexcept;
size_t excludedCount() const noexcept;
int excludedAddr(size_t i) const noexcept;
get renvoie nullptr si hors plage ; find renvoie nullptr si l'adresse n'est pas dans le parc (par exemple parce qu'elle a été exclue). add permet d'ajouter manuellement un descripteur créé séparément (par exemple après un provisionnement manuel).
Interrogation — pollAll()
Configuration multi-modules (initialization) · Interrogation multi-modules — trois stratégies (realtime-polling)
bool pollAll(RbAmpSnapshot* snaps,
RbAmpFleetPoll* status,
size_t capacity,
size_t& n_ok);
Interroge tous les modules de la flotte en un seul appel. Pour chaque module, il effectue une lecture RT complète (readAll()) et rattache le résultat à l'élément snaps[i] correspondant. En parallèle, status[i] reçoit le résultat par module (ok=true/false + addr + channels).
Au retour, n_ok est le nombre de modules pour lesquels un instantané valide a été obtenu.
Résilient aux MISS : un module silencieux n'annule pas l'interrogation des autres. C'est important pour un parc en production — perdre un module (fil cassé, panne) ne doit pas faire tomber toute la supervision.
Agrégation
bool totalPower(float& out_w) noexcept;
bool totalEnergyWh(double& out_wh) noexcept;
bool pollErrors(uint32_t& error_mask, size_t& n_errors) noexcept;
totalPower additionne la puissance active de tous les canaux de tous les modules. Sur les variantes I, il n'y a pas de puissance active → elles contribuent 0. Dans le déploiement de référence (UI1 secteur + sous-compteurs I2/I3), le résultat est la puissance active du module secteur.
totalEnergyWh additionne de la même façon les accumulateurs de Wh des handles. Il fonctionne aussi correctement : les variantes I donnent 0, UI1 donne l'énergie par charge.
pollErrors parcourt la flotte en appelant hasError() sur chaque module ; error_mask est un masque de bits des modules signalés par EVENT bit3, selon leur position (significatif pour les 32 premiers modules) ; n_errors est le nombre total de modules portant l'indicateur d'erreur au moment de l'interrogation.
Adressage et contrôle des conflits
bool assignAddress(RbAmp* dev, uint8_t new_addr);
bool checkConflict(uint8_t addr, bool& collision) noexcept;
assignAddress réaffecte un module existant du parc à une nouvelle adresse : en interne — un commit en deux phases + réinitialisation ; le descripteur dans le parc est mis à jour automatiquement (les appels suivants continuent de fonctionner).
checkConflict — une vérification en lecture seule, au mieux, pour une adresse précise : elle lit l'identité (PRODUCT_ID / HW_VARIANT / CAPABILITY) et la compare à l'état mis en cache de la flotte. Si une incohérence est détectée — collision = true. Pour parcourir toutes les adresses connues, itérez sur la flotte : for (size_t i = 0; i < fleet.count(); ++i) + checkConflict(fleet.get(i)->address(), col). Elle ne garantit pas de détecter des modules identiques — voir la discipline de provisionnement.
Provisionnement — provision() (statique)
static bool provision(TwoWire& bus,
uint8_t desired_addr,
bool save_config,
RbAmp*& out_dev);
Prend un TwoWire& (généralement Wire) et out_dev comme paramètre de sortie. En cas de succès, out_dev appartient à l'appelant — en général vous le passez directement à fleet.add(out_dev) :
Provisionne exactement un module vierge (en usine à 0x50) à l'adresse indiquée. En interne :
- Vérifie qu'il y a une réponse à
0x50. - Vérifie qu'il n'y a personne encore à
desired_addr. - Effectue le commit d'adresse en deux phases.
-
Réinitialise le module et attend qu'il apparaisse à
desired_addrdans la fenêtre de démarrage. -
Crée le descripteur ; si
save_config = true— appellesaveUserConfig()(persistance en flash). -
Renvoie le descripteur prêt via
out.
⚠ OBLIGATOIRE : exactement un module vierge sur le bus au moment de l'appel. Deux modules à 0x50 en même temps sont physiquement indiscernables sur I²C — ils ne peuvent pas être distingués, même avec un matériel spécial. La garantie repose sur l'opérateur, pas sur la bibliothèque. Pour la récupération, voir 10 · Dépannage, section « Parc : échec du provisionnement ».
Synchronisation GC de la flotte — instantanés synchrones sur toute la flotte
General Call (diffusion à l'adresse 0x00) (initialization) · Multi-modules — instantané simultané (period-metering) · 6.3 Instantané par diffusion GC — synchronisation de flotte sur option (api-reference)
bool enableGcAll(uint8_t group, size_t& ok_count);
bool gcLatch(uint8_t group, uint16_t tick, uint16_t settle_ms);
bool checkSync(uint16_t expected_tick,
RbAmpFleetSync* status,
size_t status_cap,
size_t& n_missed);
Pour une synchronisation fine des instantanés sur l'ensemble du parc, un instantané diffusé I²C General Call est utilisé.
-
enableGcAlldéfinitFLEET_CONFIG.bit0+GROUP_IDsur tous les modules du parc et émetCMD_SAVE_USER_CONFIGsur chacun (de façon persistante). Un redémarrage des modules est obligatoire après l'activation — il est effectué automatiquement.ok_countest le nombre de modules pour lesquels l'activation a réussi. -
gcLatchenvoie la trame GCA5 27 group tick_lo tick_hià l'adresse0x00— tous les modules dont le GC est activé et dont legroupcorrespond exécutent immédiatement la commande d'instantané (LATCH_PERIOD).settle_msest la pause après la trame (typiquement 50 ms) avant la vérification. -
checkSynclitGC_TICK (0x59)sur chaque module dansRbAmpFleetSync status[status_cap]. Le résultat par module :
struct RbAmpFleetSync {
uint8_t addr; // I²C address of the module
uint16_t gc_tick; // REG_GC_TICK; 0xFFFF = never received a GC
bool in_sync; // true if gc_tick == expected_tick
bool reachable; // false if the read NACKed / timed out
};
n_missed est le nombre de modules avec in_sync = false (ou tout simplement sans réponse). Si tous sont in_sync, alors n_missed == 0.
Configuration de parc par appareil (v1.3)
Ces méthodes travaillent avec un seul module directement (sans flotte) — pour les cas où vous configurez un module individuel avant de l'ajouter à une flotte, ou souhaitez un contrôle fin.
bool enableGc(bool enable) noexcept / bool readFleetConfig(uint8_t& out) noexcept
Appel général (diffusion à l'adresse 0x00) (initialization) · 4.4 Configuration de parc (0x27..0x2F) (api-reference)
enableGc(true) écrit 1 dans FLEET_CONFIG.bit0 (0x27) + enregistre en flash + réinitialise — le module commencera à accepter les instantanés GC après le démarrage. enableGc(false) efface le bit de façon symétrique. Bloque environ 1 seconde (stabilisation de SAVE_USER_CONFIG + stabilisation de la réinitialisation). readFleetConfig renvoie l'octet de configuration courant — utile pour une confirmation par relecture.
bool setGroupId(uint8_t group) noexcept / bool readGroupId(uint8_t& out) noexcept
GROUP_ID (0x28) — le filtre des trames GC : le module ne réagit qu'aux trames GC dont le group_id correspond. Par défaut = 0x00 (diffusion, réagit à toutes). Utile pour les bus multi-locataires — par exemple un groupe « phase A » et un groupe « phase B » sur un même bus partagé.
bool readGcTick(uint16_t& out) noexcept
Lit GC_TICK (0x59) — la dernière valeur de tick reçue d'une trame GC. Sert à détecter les trames manquées (si deux modules ont des ticks différents, quelqu'un a manqué une trame). 0xFFFF = le module n'a jamais reçu de trame GC depuis le démarrage.
static bool broadcastLatchGroup(TwoWire& bus, uint8_t group, uint16_t tick) noexcept
Un envoi bas niveau de la trame GC A5 27 group tick_lo tick_hi directement via bus (sans parc). Utile si le parc n'est pas encore créé, ou si vous voulez un contrôle manuel du compteur de ticks.
bool readActiveAddress(uint8_t& out) noexcept
Lit REG_I2C_ADDRESS (0x30) — l'adresse active (en fonctionnement) du module. Sur v1.3, au démarrage, il lit l'adresse active, et non un candidat en préparation. Sur la ligne STD, il renvoie le champ d'adresse persisté (appliqué à la réinitialisation). Utile pour la confirmation par relecture après commitAddressChange().
Classe RbAmpEnergy
Un accumulateur de Wh par canal. Détenu par RbAmp et accessible via dev.energy(). L'utilisateur ne le crée normalement pas directement.
Méthodes publiques
double wh(uint8_t ch = 0) const noexcept;
Le total Wh courant d'un canal, ou de tous les canaux avec RBAMP_ENERGY_CH_TOTAL. Signé — une valeur négative signifie export net. Si ch est hors plage, renvoie 0.0. (Sur un module STD sans compteurs par canal, utilisez RbAmp::energyWh() pour obtenir NaN au lieu d'un 0 trompeur.)
void addWh(uint8_t ch, double wh) noexcept;
Ajoute une énergie signée à un canal ou au total de tous les canaux. Utilisé par la bibliothèque sur le chemin de compteur STD ; également disponible pour le code utilisateur qui intègre lui-même l'énergie.
void reset(uint8_t ch = 0) noexcept;
void resetAll() noexcept;
Remettre à zéro un canal (ou le total avec RBAMP_ENERGY_CH_TOTAL) ou tous les canaux.
void disable() noexcept;
void enable() noexcept;
bool isEnabled() const noexcept;
Active / désactive l'intégration automatique. Tant que l'intégration est désactivée, readPeriodSnapshot() continue de fonctionner mais n'incrémente pas l'accumulateur — utile si le maître tient son propre stockage persistant des Wh.
uint32_t droppedDtCount() const noexcept;
void resetDroppedDtCount() noexcept;
Diagnostic : nombre d'impulsions d'intégration perdues parce que la période du maître dépassait la limite de cohérence d'une heure.
Le tick() interne
void tick(const RbAmpPeriodSnapshot& snap, uint8_t channels) noexcept;
Appelée automatiquement par RbAmp::readPeriodSnapshot() en cas de succès. Le code utilisateur ne l'appelle pas directement. Idempotente : les instantanés avec valid == false sont ignorés.
La formule d'intégration :
wh[ch] += snap.avg_p[ch] × snap.master_dt_ms / 1000 / 3600
[W] [milliseconds] → [Wh]
Précision
Dépend de la plateforme — détails dans 04 · Matériel :
-
ESP32 / ESP8266 / STM32duino / SAMD / RP2040 : un accumulateur
doublede 64 bits. -
Arduino AVR classique (Uno, Mega, Nano) : la chaîne d'outils définit
doublecomme unfloat32 bits. Pour les installations de longue durée, réinitialisez périodiquement l'accumulateur (par exemple une fois par jour).
Structures et énumérations POD
Les structures de la ligne STD (RbAmpStd*) sont décrites avec les appels qui les renvoient dans la référence de l'API de la ligne STD.
RbAmpSnapshot
Renvoyé par readAll(). Tous les champs en unités SI. Les canaux inutilisés (au-delà de channels) sont remplis de zéros.
#define RBAMP_MAX_CHANNELS 7 // override before including to shrink the arrays
struct RbAmpSnapshot {
float voltage; // V — RMS voltage
float voltage_peak; // V — peak voltage
float current[RBAMP_MAX_CHANNELS]; // A — RMS current per channel
float current_peak[RBAMP_MAX_CHANNELS]; // A — peak current per channel
float power[RBAMP_MAX_CHANNELS]; // W — active power per channel (signed)
float power_factor[RBAMP_MAX_CHANNELS]; // dimensionless, −1..+1
float frequency; // Hz — grid frequency
RbAmpTopology topology; // Single / SplitPhase / ThreePhase / Five / Seven
uint8_t channels; // 1..RBAMP_MAX_CHANNELS — number of valid channels
bool has_voltage_hw; // true if a voltage sensor is present
uint8_t implausible; // RBAMP_FIELD_* bits of fields set to NaN by the sanity filter
};
Bits implausible : RBAMP_FIELD_VOLTAGE, RBAMP_FIELD_CURRENT, RBAMP_FIELD_POWER, RBAMP_FIELD_PF, RBAMP_FIELD_FREQUENCY.
RbAmpPeriodSnapshot
Renvoyé par readPeriodSnapshot(). La primitive de comptage d'énergie.
struct RbAmpPeriodSnapshot {
float avg_p[RBAMP_MAX_CHANNELS]; // W — average active power over the period
float max_p; // W — peak instantaneous power on channel 0
uint32_t latch_ms; // ms — period duration (device's view, diagnostic; 0 on STD)
uint32_t master_dt_ms; // ms — master wall-clock dt since the last snapshot
bool valid; // true if the snapshot ready flag was set
float avg_p_total; // W — average active power over the period, all channels
double wh_net; // Wh — net energy of this period (import − export)
bool module_restarted; // the module restarted inside this period (STD counter path only)
};
latch_ms est une minuterie de diagnostic du module ; ne l'utilisez pas pour l'énergie — utilisez l'horloge du maître (master_dt_ms).
RbAmpTopology
enum class RbAmpTopology : uint8_t {
Single = 1, // 1 current channel (UI1 / I1)
SplitPhase = 2, // 2 current channels (UI2 / I2)
ThreePhase = 3, // 3 current channels (UI3 / I3)
Five = 5, // 5 current channels (UI5) — senior SKU
Seven = 7, // 7 current channels (UI7) — senior SKU
};
RbAmpLine
enum class RbAmpLine : uint8_t {
Basic = 0, // 8-bit register map (the default until begin() runs)
Std = 1, // STANDARD (STD) line: 16-bit register map
};
RbAmpVariant
Unknown, UI1, UI2, UI3, I1, I2, I3, UI5, UI7 — voir readVariant().
RbAmpSensorClass
enum class RbAmpSensorClass : uint8_t {
Unset = 0, // Factory default; setCTModel() will refuse
Sct013 = 1, // SCT-013 series clamp fitted by the user
WiredCT = 2, // Wired CT shipped with the module and calibrated together with it
BuiltinCT = 3, // Built-in CT, calibrated together with the module
};
WiredCT et BuiltinCT décrivent des modules livrés et calibrés avec leur capteur. Les setters ne réécrivent jamais ces modules (ils renvoient false avec RB_ERR_MODE) ; setCTModelChForce() est la voie de service.
RbAmpCTModel
Énumération figée de compatibilité ascendante pour les sept codes SCT-013 (Sct013_005 … Sct013_060). Le nouveau code passe un define RBAMP_CT_* généré aux surcharges uint8_t.
RbAmpSctRating et RbAmpSctRatingStatus
Voir Correction de calibre SCT-013.
RbAmpDrdyEvent
Voir Ligne de données prêtes et événements.
Codes d'erreur (espace de noms rbamp)
Défini dans RbAmpRegisters.h, renvoyé par lastError().
namespace rbamp {
constexpr int8_t RB_OK = 0;
constexpr int8_t RB_ERR_IO = -1; // I²C transport error
constexpr int8_t RB_ERR_NACK = -2; // retry exhausted, slave not responding
constexpr int8_t RB_ERR_TIMEOUT = -3; // timeout (waitReady / waitDataReady / commit-addr window expired)
constexpr int8_t RB_ERR_NOT_READY = -4; // module not ready / no such record / nothing armed
constexpr int8_t RB_ERR_STALE = -5; // period snapshot not ready
constexpr int8_t RB_ERR_PARAM = -6; // invalid channel / address / precondition; the module rejected a value
constexpr int8_t RB_ERR_MODE = -7; // not allowed in the module's current mode (factory-paired class, factory-only command)
constexpr int8_t RB_ERR_CHECKSUM = -8; // value check failed — checksum / signature / range
constexpr int8_t RB_ERR_VERSION = -9; // unsupported firmware / image version
constexpr int8_t RB_ERR_NOT_IMPLEMENTED = -10; // no counterpart on this line or on this module image
constexpr int8_t RB_ERR_NON_PHYSICAL = -11; // float rejected by the sanity filter
}
Recettes de diagnostic pour chaque code — 10 · Dépannage.
Recettes de diagnostic pour chaque code — 10 · Dépannage.
Configuration à la compilation
Définissez AVANT #include pour remplacer les valeurs par défaut :
#define RBAMP_NACK_RETRY_ATTEMPTS 5 // number of retry attempts per byte
#define RBAMP_NACK_RETRY_GAP_MS 5 // pause between attempts, ms
#include
Valeurs par défaut de la plateforme :
#if defined(ARDUINO_ARCH_ESP32) || defined(ESP_PLATFORM)
# define RBAMP_NACK_RETRY_ATTEMPTS 3
#else
# define RBAMP_NACK_RETRY_ATTEMPTS 1
#endif
#define RBAMP_NACK_RETRY_GAP_MS 5
Pour en savoir plus sur le sous-système de résilience — 10 · Dépannage.
Constantes de temps de stabilisation
Défini dans RbAmpRegisters.h. La bibliothèque les utilise en interne ; ils sont exportés pour les utilisateurs qui souhaitent respecter les mêmes temporisations lors d'un accès brut au bus :
constexpr uint16_t SETTLE_MS_LATCH_PERIOD = 50; // after CMD_LATCH_PERIOD
constexpr uint16_t SETTLE_MS_SAVE_GAINS = 700; // after CMD_SAVE_GAINS (flash write)
constexpr uint16_t SETTLE_MS_RESET = 300; // after CMD_RESET
constexpr uint16_t SETTLE_MS_FACTORY_RESET = 1500; // after CMD_FACTORY_RESET
Détails du protocole filaire
Cette section décrit le protocole de registres 8 bits de la gamme BASIC. La gamme STD utilise un pointeur de registre 16 bits avec des lectures par rafale à incrémentation automatique ; la bibliothèque s'en charge en interne (begin() détecte la gamme) et le câblage physique est le même bus I²C. Le code applicatif n'a jamais besoin des détails du câblage STD — utilisez les appels de l'API de la gamme STD.
Lectures de registres — incrémentation automatique
Une lecture en rafale renvoie N octets consécutifs à partir de addr. Les méthodes de la bibliothèque utilisent des rafales lorsque c'est possible (une transaction I²C = 4 octets de float).
Écritures de registres — octet par octet (PAS d'incrémentation automatique)
⚠ Les écritures n'incrémentent PAS automatiquement. Une écriture en rafale ne dépose que le premier octet — les octets 1..N sont perdus.
Un registre multi-octets s'écrit un octet à la fois — une transaction I²C distincte d'un seul octet pour chaque adresse :
// WRONG — data loss
uint8_t label[8] = "MyMeter1";
Wire.beginTransmission(addr);
Wire.write(0x68); // start of LABEL
Wire.write(label, 8); // burst — only 'M' lands
Wire.endTransmission();
// CORRECT — byte-at-a-time loop
for (int i = 0; i < 8; i++) {
Wire.beginTransmission(addr);
Wire.write(0x68 + i);
Wire.write(label[i]);
Wire.endTransmission();
}
Concerne les registres multi-octets inscriptibles : LABEL (0x68-0x6F), U_GAIN/I_GAIN (f32, réservés à l'usine), NF (u16), THRESH (u16). Lectures — rafale acceptée.
Exception : la trame de diffusion GC (5 octets A5 27 g tl th vers l'adresse 0x00) est un chemin de protocole filaire distinct (réception general-call, pas une écriture de registre), envoyée en une seule transaction. Voir le scénario 12 dans 06 · Exemples.
Lecture de registres non cartographiés
Toute lecture d'une adresse non mappée renvoie 0x00. Le firmware ne NACK jamais les lectures de registres. La détection de l'absence d'un appareil passe par l'ACK de la trame d'adresse I²C, et non par le sondage des registres.
Détection de variante
L'octet d'identification de référence faisant foi est REG_HW_VARIANT (0x55) (la méthode readVariant()) :
| valeur | SKU |
|---|---|
0x01 |
UI1 (1× I + U) |
0x02 |
UI2 (2× I + U) |
0x03 |
UI3 (3× I + U) |
0x04 |
I1 (1× I, sans U) |
0x05 |
I2 (2× I, sans U) |
0x06 |
I3 (3× I, sans U) |
0x07 |
UI5 (5× I + U, référence haut de gamme) |
0x08 |
UI7 (7× I + U, référence haut de gamme) |
REG_TOPOLOGY (0x24) est auxiliaire (seul le nombre de canaux, il ne distingue pas la présence de U). Sur la ligne STD, la bibliothèque lit l'identité depuis la carte 16 bits propre au module pendant begin() et fait correspondre la variante avec readVariant().
Instantané diffusé General-Call (synchronisation multi-modules)
Activation par module via REG_FLEET_CONFIG.bit0 — GC_ENABLE. Désactivé par défaut. Activé via CMD_SAVE_USER_CONFIG + CMD_RESET (logiciel ou matériel). Après la réinitialisation, le module écoute une trame de diffusion à l'adresse 0x00 :
addr=0x00 | A5 27
A5— magique ;27— opcodeCMD_LATCH_PERIOD.—0x00= appel général (all-call), sinon il doit correspondre àREG_GROUP_ID (0x28).— le compteur de période de synchronisation maître sur 16 bits.
La trame ne fait que prendre l'instantané ; les opcodes destructeurs ne sont pas transmis par GC.
Détection du mode de défaillance (deux niveaux) :
- NACK d'adresse GC (immédiatement au niveau du bus) : si GC est désactivé sur tout le parc —
Wire.endTransmission()vers0x00renvoie un code non nul (NACK). C'est une erreur franche, pas un rejet silencieux. La bibliothèque la traite comme « GC non activé » (nécessite les préconditions activation + réinitialisation). - Témoin par module (après stabilisation) : si aucun NACK ne s'est produit — lisez
REG_V03_PERIOD_VALID (0x07)sur chaque module attendu.1= instantané réussi ;0= GC désactivé sur ce module ou période vide ;!=1→ repli sur une latch par appareil.
Références
- 05 · Démarrage rapide — votre premier croquis fonctionnel
- 06 · Exemples — scénarios d'utilisation
-
10 · Dépannage — décodage des erreurs et résolution des problèmes courants
-
Fichier source avec commentaires Doxygen :
src/RbAmp.h
Sources et problèmes : rb-amp/rbamp-arduino · cette page dans le dépôt : docs/09_api_reference.md (v1.6.2)