rbAmp
FR
Boutique
Docs
Mis à jour le

04 · Mesure de période et comptabilité tarifaire

Pour la comptabilité énergétique tarifaire (Wh par 1 min / 15 min / 1 heure / jour / mois / année), rbAmp fournit un mécanisme d'instantané de période atomique : une seule commande I²C fige la puissance moyenne sur la période, et le maître la multiplie par sa propre durée dt pour obtenir des Wh.

C'est la méthode de niveau production pour extraire les données d'énergie. L'alternative — intégrer côté maître le P_real RT à chaque fenêtre de mesure (~100 ms, v1.2 et ultérieures) — donne quasiment le même résultat sur BASIC (précision légèrement inférieure à cause de la discrétisation de l'échantillonnage) et garde le maître actif en continu.

Périodes BASIC et STD. BASIC conserve un instantané de période par canal : sur commande du maître, le module fige la moyenne et la puissance de crête ainsi que la longueur de période (à côté de la fenêtre live de 100 ms, qui n'est pas une période), et l'hôte intègre l'énergie. STANDARD (STD) conserve l'énergie dans le module : compteurs cumulés (import/export, actif et réactif) qui survivent à une coupure de courant, plus des enregistrements horodatés de 15 minutes et horaires (le maître règle l'horloge). Les modules STD dont le bit 8 de CAPABILITIES est à 1 disposent aussi de 8 banques d'instantanés indépendantes ; sinon l'énergie d'intervalle provient des différences des compteurs. Le reste de ce chapitre décrit l'instantané de période BASIC ; STD est décrit dans la référence technique STD.

Pourquoi un instantané de période est nécessaire

Pourquoi un instantané de période est utilisé en plus de la fenêtre de mesure.

Une seule base de temps, détenue par le maître

Dans un système multi-modules, la base de temps doit résider sur le maître. La puce n'intègre donc pas les Wh en interne. À la place :

  • La puce expose une statistique indépendante du temps — la moyenne de P sur la période.
  • Le maître le multiplie par son propre dt d'horloge murale.
  • Tous les modules partagent la même référence temporelle → aucune dérive ne s'accumule dans le total d'énergie à l'échelle du système.

La formule

Text
E_Wh = avg_P_W × master_dt_seconds / 3600

Where:

  • avg_P_W — la valeur de PERIOD_AVG_P_W, lue après CMD_LATCH_PERIOD.
  • master_dt_seconds — les secondes écoulées entre deux instantanés successifs, mesurées par le maître.

Période atomique — concept

Comment une commande d'instantané unique fige l'instantané de période et ouvre la période suivante.

Ce que fait la commande

Écrire 0x27 dans REG_COMMAND = 0x01 déclenche une séquence atomique dans le firmware (exécutée sous __disable_irq()) :

Text
1. snapshot ← live      (copy the live accumulator into the I2C-visible snapshot)
2. live     ← 0         (reset the accumulator; start the next period)
3. period_start_ms = now

Ces trois étapes sont indivisibles — aucune interruption ne peut s'intercaler entre elles. Cela garantit :

  • Atomicité : chaque échantillon P par fenêtre appartient à exactement un instantané — soit le précédent, soit le suivant — jamais dupliqué, jamais perdu.
  • Aucun écart : la nouvelle période commence au même instant que la précédente se termine — il n'y a pas d'intervalle aveugle.

Où vit l'instantané

Après un instantané, les registres d'instantané de période (0xBE..0xCD, plus 0xDC..0xDF pour avg_p du canal 0, plus 0xE0..0xE3 pour MAX_P, plus 0xEC..0xEF pour le PERIOD_LATCH_MS de diagnostic) renvoient la période qui vient de se clore. Notez que cette plage n'est pas contiguë : 0xD0..0xDB contient le bloc Q (temps réel en direct, pas un instantané de période) et 0xE4..0xEB est réservé/usine. Voir le chapitre 11 §4.11–4.13 pour la disposition exacte. L'accumulateur en direct commence déjà à compter la période suivante ; ces registres d'instantané ne se mettent à jour qu'au prochain instantané.

Une écriture — ferme et ouvre

C'est la propriété définissante de l'instantané rbAmp. Une seule commande d'instantané fait simultanément :

  • Clôt la période qui vient de se terminer (ses données → instantané)
  • Ouvre la période suivante (live ← 0)

Le maître n'a besoin que d'une écriture par mesure, et non deux (comme dans une implémentation naïve « démarrer → arrêter → lire »).

Dans les bibliothèques clientes

— la même tâche sans accès aux registres :

Bibliothèque Appel Ce qu'il fait
Arduino RbAmp::latchPeriod() / RbAmp::isPeriodValid() envoyer la commande d'instantané ; vérifier l'indicateur de validité
ESP-IDF rbamp_latch_period() / rbamp_is_period_valid() envoyer la commande d'instantané ; vérifier l'indicateur de validité
Python dev.latch_period() / dev.is_period_valid() envoyer la commande d'instantané ; vérifier l'indicateur de validité
ESPHome update_interval: chaque mise à jour clôt la période ; la commande d'instantané et la stabilisation sont gérées par le composant
Text
master                          chip
------                          ----
                                accumulator running since boot...

write CMD_LATCH (0x27)   ────►  snapshot ← live (since-boot — DISCARD)
                                live ← 0, period_start = T0
t0 = master.clock()      ◄──── first snapshot — primer (discard)

  [wait 60 seconds]

write CMD_LATCH          ────►  snapshot ← live (over [T0..T1] — KEEP)
                                live ← 0, period_start = T1
t1 = master.clock()
read avg_p_W @ 0xDC      ────►  float32 LE
E1_Wh = avg_p × (t1 − t0) / 3600

  [wait 60 seconds]

write CMD_LATCH          ────►  snapshot ← live (over [T1..T2] — KEEP)
                                live ← 0, period_start = T2
t2 = master.clock()
read avg_p_W
E2_Wh = avg_p × (t2 − t1) / 3600

...and so on. t1 is both the end of period 1 and the start of period 2.

Le premier instantané est une amorce (à jeter)

Le premier instantané après démarrage capture tout ce que l'accumulateur a collecté depuis la mise sous tension jusqu'au premier appel du maître — une fenêtre de durée indéfinie, impropre au comptage. Écartez son résultat. À partir du deuxième instantané, les données sont propres et exploitables.

Dans les bibliothèques clientes

— la même tâche sans accès aux registres :

Bibliothèque Appel Ce qu'il fait
Arduino RbAmp::readPeriodSnapshot(out, settle_ms, skip_latch) / RbAmp::begin() instantané, stabilisation, contrôle de validité et lecture en un seul appel ; begin() jette le premier instantané
ESP-IDF rbamp_read_period_snapshot() / rbamp_begin() instantané, stabilisation, contrôle de validité et lecture en un seul appel ; begin écarte le premier instantané
Python dev.read_period_snapshot(settle_ms=50, skip_latch=False) / dev.begin() instantané, stabilisation, contrôle de validité et lecture en un seul appel ; begin() jette le premier instantané
ESPHome update_interval: / latch_interval: cadence de mise à jour du cycle d'instantané ; cadence d'instantané séparée facultative

Registres d'instantané de période

Adresse Nom Type Quand lire Description
0x07 PERIOD_VALID u8 à lire en premier bit0 = 1 si l'instantané est récent et valide, 0 s'il est périmé (course ou instantané prématuré)
0xDC..0xDF PERIOD_AVG_P_W[0] float32 LE primaire PRODUCTION — P_real moyen du canal I0 sur la période (W)
0xC2..0xC5 PERIOD_AVG_P_W[1] float32 LE UI2/UI3 P_real moyen du canal I1
0xC6..0xC9 PERIOD_AVG_P_W[2] float32 LE UI3 P_real moyenne du canal I2
Énergie par canal (UI2/UI3)

: le même instantané fige aussi les moyennes par canal — relisez 0xC2 (ch1) / 0xC6 (ch2) dans le même passage et multipliez par le même dt : e1_wh = avg_p1 * dt_s / 3600. | 0xE0..0xE3 | PERIOD_MAX_P_W | float32 LE | optionnel | P_real crête pendant la période (pour les tarifs à la puissance) | | 0xEC..0xEF | PERIOD_LATCH_MS | u32 LE | diagnostic uniquement | Vue de la puce sur le dt entre instantanés — peut être court sous charge ; utilisez PERIOD_COMMIT_COUNT × la longueur de commit pour la longueur de fenêtre côté module | | 0xBE..0xC1 | PERIOD_COMMIT_COUNT | u32 LE | mesure de fenêtre | Nombre de commits RT dans la période close. Un commit = 0.1 s depuis la v1.2 ; 0.2 s sur les images plus anciennes — count × 0.1 s (ou × 0.2 s) est la mesure propre du module pour la longueur de fenêtre. Voir la section sur la dérive d'horloge pour savoir lequel s'applique

Accumulateurs d'export

Adresse Nom Type Description
— — La carte BASIC n'a pas de compteurs d'export (sens négatif) ; sur STD, l'énergie est gérée autrement — voir la documentation STD
Remarque

Sur les modules BASIC, il n'existe pas de registres d'injection ; les lectures d'une adresse non mappée renvoient 0x00 (le firmware ne renvoie jamais de NACK sur les lectures — voir chapitre 11 §5.2). Un maître qui a besoin du suivi de l'injection sur BASIC se rabat sur une comptabilité basée sur le temps réel (voir arduino-examples.md → Exemple 5).

Dans les bibliothèques clientes — la même tâche sans accès aux registres :

Bibliothèque Appel Ce qu'il fait
Arduino RbAmp::readPeriodAvgPower(ch) / RbAmp::readPeriodMaxPower() moyenne et puissance de crête de la période close
ESP-IDF rbamp_read_period_avg_power() / rbamp_read_period_max_power() moyenne et puissance de crête de la période close
Python dev.read_period_avg_power(ch=0) / dev.read_period_max_power() moyenne et puissance de crête de la période close
ESPHome update_interval: le composant lit les moyennes de période à chaque mise à jour

Algorithme côté maître

Cycle de base (un module, période de 60 secondes)

C++
#include 

#define RB_ADDR 0x50

void setup() {
  Serial.begin(115200);
  Wire.begin();
  delay(300);

  // 1. Primer snapshot (discard result)
  rb_write_u8(RB_ADDR, 0x01, 0x27);
}

void loop() {
  static uint32_t t_prev = millis();
  delay(60000);                                    // wait 60 seconds

  // 2. Final snapshot — closes [t_prev, now]
  rb_write_u8(RB_ADDR, 0x01, 0x27);
  uint32_t t_now = millis();
  delay(50);                                       // firmware finishes in ~5 ms; allow margin

  // 3. Check PERIOD_VALID
  uint8_t valid = rb_read_u8(RB_ADDR, 0x07);
  if ((valid & 0x01) == 0) {
    // Race or premature snapshot — retry
    delay(250);
    rb_write_u8(RB_ADDR, 0x01, 0x27);
    t_now = millis();
    delay(50);
    valid = rb_read_u8(RB_ADDR, 0x07);
    if ((valid & 0x01) == 0) {
      Serial.println("WARN: two stale snapshots in a row");
      t_prev = millis();
      return;
    }
  }

  // 4. Read the snapshot
  float avg_p = rb_read_float_le(RB_ADDR, 0xDC);
  float max_p = rb_read_float_le(RB_ADDR, 0xE0);

  // 5. Compute energy on master clock
  float dt_s = (t_now - t_prev) / 1000.0f;
  float e_wh = avg_p * dt_s / 3600.0f;

  Serial.printf("[+%5.1fs] E=%.3f Wh  avg_P=%.1f W  max_P=%.1f W\n",
                dt_s, e_wh, avg_p, max_p);

  t_prev = t_now;
}

Ce qui est essentiel dans ce code

  1. Le premier instantané est une amorce — son résultat est écarté.
  2. PERIOD_VALID doit être lu AVANT d'utiliser l'instantané — sinon des données périmées peuvent passer en cas de course.
  3. dt est mesuré sur le maître, et non déduit de PERIOD_LATCH_MS — le registre de la puce ne sert qu'aux diagnostics de dérive.
  4. t_prev prend la valeur t_now d'un instantané réussi, et non le début initial de la période — la chaîne reste continue, sans trou.
Dans les bibliothèques clientes

— la même tâche sans accès aux registres :

Bibliothèque Appel Ce qu'il fait
Arduino RbAmp::energyWh(ch) / RbAmpEnergy::reset(ch) total Wh courant conservé sur l'hôte ; remettre l'accumulateur à zéro
ESP-IDF rbamp_energy_wh() / rbamp_energy_reset() total Wh courant conservé sur l'hôte ; remettre l'accumulateur à zéro
Python dev.energy.wh(ch) / dev.energy.reset(ch) total Wh courant conservé sur l'hôte ; remettre l'accumulateur à zéro
ESPHome energy capteur d'énergie intégré par le composant

Comptabilité bidirectionnelle

Remarque

Sur un module BASIC, les registres PERIOD_AVG_P_NEG_W ne sont pas alloués (les lectures renvoient 0x00), et PERIOD_AVG_P_W est toujours ≥ 0 (les échantillons négatifs sont retirés de l'accumulateur).

Comment l'énergie est comptabilisée sur les modules BASIC et STANDARD (STD).

Ce que signifie la comptabilité bidirectionnelle

La puce intègre deux accumulateurs distincts par période :

  • Consommation : intégrale de max(P, 0) × dt — puissance positive uniquement.
  • Injection : intégrale de max(−P, 0) × dt — puissance négative uniquement, en valeur absolue.

La somme des deux donne l'énergie totale ayant traversé le compteur en valeur absolue ; la différence est la consommation nette (ce qu'afficherait un compteur mécanique à disque).

Applications

  • Foyers équipés de panneaux solaires : la consommation et l'injection sont facturées selon des tarifs différents (tarif de rachat)
  • Installations avec stockage par batterie : suivi des cycles de charge/décharge
  • Éoliennes, charges régénératives, bornes de recharge V2G pour véhicules électriques

Où vit la mesure bidirectionnelle

Les produits bidirectionnels (consommation + export) appartiennent à la ligne rbAmp STD, qui utilise une carte de registres différente, sur 16 bits, avec des compteurs d'énergie signés embarqués — voir la documentation de référence STD. Il n'y a aucun registre d'export sur la carte 8 bits BASIC décrite dans ce chapitre.

C++
// BASIC-map period accounting, 60-second period (consumption only)
void loop() {
  static uint32_t t_prev = millis();
  delay(60000);

  rb_write_u8(RB_ADDR, 0x01, 0x27);
  uint32_t t_now = millis();
  delay(50);

  if ((rb_read_u8(RB_ADDR, 0x07) & 0x01) == 0) {
    t_prev = millis();
    return;
  }

  float avg_p_consume = rb_read_float_le(RB_ADDR, 0xDC);                  // ≥ 0

  float dt_s = (t_now - t_prev) / 1000.0f;
  float e_consume_wh = avg_p_consume * dt_s / 3600.0f;

  Serial.printf("[%.1fs] consume=%.3f Wh\n", dt_s, e_consume_wh);

  t_prev = t_now;
}

Ce qui n'est pas disponible sur BASIC

Si vous possédez un module de niveau BASIC et avez besoin d'une comptabilité bidirectionnelle, vous avez deux options :

  1. Intégration côté maître — lire le P_real temps réel (0xA6) à chaque fenêtre de mesure (~100 ms à partir de la v1.2 ; 200 ms avant) et intégrer séparément les échantillons positifs et négatifs côté maître. Voir l'exemple 5 dans arduino-examples.md. La précision est légèrement plus faible (à cause de la discrétisation de l'échantillonnage), mais cela fonctionne sur tout firmware.
Dans les bibliothèques clientes

— la même tâche sans accès aux registres :

Bibliothèque Appel Ce qu'il fait
Arduino RbAmp::stdReadEnergy(out) / RbAmp::readPower(ch) STD : compteurs d'import/export embarqués ; BASIC : puissance signée, séparée sur l'hôte
ESP-IDF rbamp_std_read_energy() / rbamp_read_power() (signée) STD : compteurs d'import/export embarqués ; BASIC : puissance signée, séparée sur l'hôte
Python dev.read_std_energy() / dev.read_power(ch) STD : compteurs d'import/export embarqués ; BASIC : puissance signée, séparée sur l'hôte
ESPHome bidirectional: / energy_exported activer l'énergie injectée ; capteurs d'injection (BASIC publie 0)

Variantes I uniquement — le comptage de période renvoie zéro

Sur I1/I2/I3 (et les variantes I* supérieures uniquement) sans capteur de tension :

  • PERIOD_AVG_P_W[*] vaut toujours 0.0f — l'absence de U signifie qu'il n'y a rien à intégrer.
  • PERIOD_VALID reste à 1 (l'instantané est valide, simplement nul).
  • PERIOD_MAX_P_W vaut aussi 0.

Pour les variantes à courant seul, la mesure de période sur puce ne fournit pas de mesure d'énergie. Le maître doit soit :

  • Utilisez votre propre capteur de tension et intégrez I_rms × U_master × cos(φ)_master (plus complexe ; nécessite une synchronisation de phase), ou
  • N'utilisez le module à courant seul que pour la détection de présence de courant, et associez-le à un module UI* ou à un compteur externe pour l'énergie.

Interrogation pilotée par événements ou périodique

Périodique (type cron)

Le maître lit toutes les N secondes sur un minuteur :

C++
// Once per hour
setInterval(60 * 60 * 1000, [](){
  rb_write_u8(0x50, 0x01, 0x27);
  // ... read snapshot, accumulate Wh
});

Adapté au comptage tarifaire classique (1 min, 15 min, 1 heure).

Piloté par événement

Le maître émet un instantané lorsqu'un événement externe survient :

  • Une impulsion du compteur électronique du distributeur (contrôle croisé)
  • Un changement de tarif (heures pleines / creuses)
  • Une question utilisateur (« combien ai-je consommé jusqu'ici ? »)
C++
void on_tariff_change() {
  rb_write_u8(0x50, 0x01, 0x27);    // close the period under the old tariff
  delay(50);
  if (rb_read_u8(0x50, 0x07) & 0x01) {
    float avg_p = rb_read_float_le(0x50, 0xDC);
    save_period_to_tariff_a_bucket(avg_p, current_dt_s);
  }
  // the next period accumulates into bucket B
}

Redémarrage de la période

Pour écarter l'accumulateur en direct et repartir à zéro, émettez un instantané supplémentaire et ignorez son résultat :

C++
void restart_period() {
  rb_write_u8(0x50, 0x01, 0x27);    // close current + start new
  // do not read the snapshot — discard
}

Ensuite, reprendre un cycle d'instantané normal depuis le début.

Détecter un redémarrage du module

Un redémarrage du module (creux de tension, watchdog) remet silencieusement à zéro l'accumulateur en cours, si bien que l'instantané suivant couvre une fenêtre indéfinie — exactement comme le premier instantané après démarrage. Le module expose :

Adresse Nom Type Description
0x46..0x49 UPTIME_S u32 LE Compteur de temps de fonctionnement propre au module (en secondes depuis le démarrage, en principe). Détecteur de redémarrage uniquement — sur le firmware jusqu'à 1.4.21 il tourne plus lentement que l'horloge murale (mesuré 0.58–0.80×) ; ne jamais l'utiliser comme horloge ni pour des calculs de temps
0x4A RESET_CAUSE u8 Indicateurs de cause de réinitialisation : bit0 broche externe, bit1 mise sous tension / baisse de tension, bit2 logiciel, bit3/bit4 chiens de garde. Pour la journalisation uniquement

Vérifier à chaque instantané — le module a redémarré au cours de la période si l'une des conditions suivantes est vraie :

  • UPTIME_S a diminué depuis votre instantané précédent, ou
  • UPTIME_S est inférieur au temps écoulé depuis votre instantané précédent (selon l'horloge du maître).

Comme le compteur peut tourner lentement, le second contrôle peut parfois signaler un redémarrage qui n'a pas eu lieu (juste après un vrai démarrage) — c'est sans gravité : vous jetez une période de plus comme amorce. Ne traitez UPTIME_S que comme discriminant de redémarrage, jamais comme source de temps.

Lors d'un redémarrage détecté, écartez l'instantané de cette période (traitez l'instantané comme une nouvelle amorce), revalidez le modèle CT si vous utilisez un modèle non-usine sur un firmware antérieur à 1.4.20 (bit 12 de CAPABILITY à 0) (initialization.md → Ce qui persiste après un redémarrage), et réinitialisez toute configuration uniquement en RAM — voir le chapitre 11 (bit d'événement RESET_OCCURRED). RESET_CAUSE ne change pas le traitement ; journalisez-le et passez à la suite.

Dans les bibliothèques clientes

— la même tâche sans accès aux registres :

Bibliothèque Appel Ce qu'il fait
Arduino RbAmpPeriodSnapshot::module_restarted indicateur de redémarrage dans le résultat de période (chemin compteur STD)
ESP-IDF rbamp_read_uptime_s() / module_restarted lire le temps de fonctionnement du module ; indicateur de redémarrage dans le résultat de période
Python — non exposé — pas d'appel dédié à la détection de redémarrage sur BASIC
ESPHome — non exposé — pas d'option de détection de redémarrage en YAML

Multi-module — instantané simultané

Si le maître souhaite des instantanés synchrones de tous les modules (pour un bilan énergétique instantané de la maison), deux approches existent.

Approche 1 — instantané séquentiel (simple)

Le maître prend un instantané de chaque module à tour de rôle :

C++
const uint8_t modules[] = {0x50, 0x51, 0x52};
uint32_t t_prev[] = {0, 0, 0};

void setup() {
  Wire.begin();
  // Primer
  for (int i = 0; i < 3; i++) {
    rb_write_u8(modules[i], 0x01, 0x27);
    t_prev[i] = millis();
  }
}

void loop() {
  delay(60000);
  for (int i = 0; i < 3; i++) {
    rb_write_u8(modules[i], 0x01, 0x27);
    uint32_t t_now = millis();
    delay(50);
    if (rb_read_u8(modules[i], 0x07) & 0x01) {
      float avg_p = rb_read_float_le(modules[i], 0xDC);
      float dt_s = (t_now - t_prev[i]) / 1000.0f;
      float e_wh = avg_p * dt_s / 3600.0f;
      Serial.printf("[0x%02X] E=%.3f Wh\n", modules[i], e_wh);
      t_prev[i] = t_now;
    }
  }
}

Inconvénient : les instants d'instantané diffèrent de quelques millisecondes. Pour une période de 60 secondes, cela donne une erreur < 0.1 % — négligeable.

Approche 2 — instantané de diffusion par appel général (précis, sur option)

L'adresse d'appel général I²C 0x00 est un paquet que tous les esclaves reçoivent simultanément. rbAmp accepte une trame canonique de 5 octets sur l'adresse d'appel général qui déclenche CMD_LATCH_PERIOD sur chaque module ayant la réception GC activée. GC est activé module par module via FLEET_CONFIG.bit0 (par défaut DÉSACTIVÉ) — voir initialization.md pour la séquence d'activation et le format de trame.

Un instantané de diffusion atteignant tous les modules au même moment via l'adresse d'appel général.

C++
// Canonical 5-byte GC frame: A5 27 group tick_lo tick_hi.
// Returns true on ACK, false on bus-level NACK (no module has GC enabled).
bool broadcast_latch(uint16_t tick16, uint8_t group = 0) {
  Wire.beginTransmission(0x00);                // general call
  Wire.write(0xA5);                            // frame magic
  Wire.write(0x27);                            // CMD_LATCH_PERIOD opcode
  Wire.write(group);                           // group_id (0 = all-call)
  Wire.write((uint8_t)(tick16 & 0xFF));        // tick_lo
  Wire.write((uint8_t)((tick16 >> 8) & 0xFF)); // tick_hi
  return Wire.endTransmission() == 0;
}

Le maître tient un compteur tick de 16 bits qui s'incrémente à chaque diffusion. Chaque module reproduit le dernier tick accepté dans GC_TICK (0x59), afin que le maître détecte une diffusion manquée sur un module donné.

Après l'instantané en diffusion, le maître lit l'instantané de chaque module par son adresse propre. Vérifiez toujours la valeur de retour — sur NACK, la trame GC n'a pas été reçue (aucun module n'a GC activé), et le maître doit revenir à l'instantané séquentiel module par module :

C++
const uint8_t modules[] = {0x50, 0x51, 0x52};
uint32_t t_prev;
uint16_t gc_tick = 0;

void setup() {
  Wire.begin();
  if (!broadcast_latch(gc_tick++)) {
    // Fall back: per-module sequential snapshot.
    for (uint8_t m : modules) rb_write_u8(m, 0x01, 0x27);
  }
  t_prev = millis();
}

void loop() {
  delay(60000);
  if (!broadcast_latch(gc_tick++)) {
    for (uint8_t m : modules) rb_write_u8(m, 0x01, 0x27);
  }
  uint32_t t_now = millis();
  delay(50);

  float dt_s = (t_now - t_prev) / 1000.0f;
  for (int i = 0; i < 3; i++) {
    if (rb_read_u8(modules[i], 0x07) & 0x01) {
      float avg_p = rb_read_float_le(modules[i], 0xDC);
      float e_wh = avg_p * dt_s / 3600.0f;
      Serial.printf("[0x%02X] E=%.3f Wh  P_avg=%.1f W\n",
                    modules[i], e_wh, avg_p);
    }
  }
  t_prev = t_now;
}

Avantage : synchronisation précise — les instantanés sont pris au même instant sur tous les modules GC activés, à quelques microsecondes près.

Cas d'usage : critique pour l'équilibrage instantané (par exemple consommation_maison − injection_solaire à un instant donné).

L'instantané de diffusion est sur option

par module via FLEET_CONFIG.bit0 (par défaut DÉSACTIVÉ sur un module neuf). Lorsqu'il est désactivé, l'esclave renvoie NACK sur la trame d'appel général et le maître se rabat automatiquement sur un instantané séquentiel module par module. Voir initialization.md — Appel général (diffusion à l'adresse 0x00) — pour la séquence d'activation et le format de trame.

Un accumulateur, deux déclencheurs. L'instantané adressé (0x27 à l'adresse propre du module) et l'instantané en diffusion remettent à zéro le même accumulateur de période — il n'y en a qu'un par module. Choisissez une seule méthode par module pour le cycle régulier ; un instantané supplémentaire par l'autre méthode raccourcit la période en cours. Les schémas de repli ci-dessus sont sûrs, car ils ne se déclenchent que si la diffusion n'a pas atteint ce module.

Dans les bibliothèques clientes — la même tâche sans accès aux registres :

Bibliothèque Appel Ce qu'il fait
Arduino RbAmpFleet::gcLatch(group, tick, settle_ms) / RbAmp::readPeriodSnapshot(out, settle_ms, skip_latch=true) trame d'instantané de diffusion vers la flotte ; lire chaque module après un instantané externe
ESP-IDF rbamp_fleet_gclatch() / rbamp_read_period_snapshot(..., skip_latch=true) trame d'instantané de diffusion vers la flotte ; lire chaque module après un instantané externe
Python fleet.gc_latch(group, tick, settle_ms) / dev.read_period_snapshot(skip_latch=True) trame d'instantané de diffusion vers la flotte ; lire chaque module après un instantané externe
ESPHome fleet_gc_enable: / group_id: Options YAML pour l'adhésion General Call et l'identifiant de groupe

Choisir la durée de la période

Application dt recommandé
Tableau de bord UI en direct 1 s (ou lire directement P_real temps réel)
Courbe de tendance, résolution de 1 minute 60 s
Comptage de la pointe de demande sur 15 minutes 900 s
Comptage horaire 3600 s
Totaux journaliers Accumuler des instantanés horaires sur le maître ; ne laissez jamais une seule période dépasser 1 heure
Remarque

Des périodes de plus de 1 heure sont admises et rien ne déborde — l'accumulateur continue de moyenner tant qu'aucun instantané n'arrive. Ce qui se dégrade sur une très longue fenêtre, c'est la précision de la moyenne : au pire ≈ 0.2 % à 1 heure, 1.3 % à 6 heures, 5 % à 24 heures. Limitez donc les périodes uniques à ≤ 1 heure et cumulez les totaux plus longs côté maître.

PERIOD_MAX_P_W — pointe de demande

Le registre 0xE0 renvoie la puissance maximale observée dans une fenêtre RT quelconque de la période. Usages :

  • Tarifs à pointe de demande : les distributeurs facturent la demande maximale sur 15 minutes du mois pour les frais de puissance souscrite.
  • Détection d'appel de courant : le démarrage des moteurs produit un pic de 5 à 10× la valeur nominale — max_P >> avg_P signale l'événement.
  • Contrôle de cohérence : si max_P dépasse largement avg_P, la charge est irrégulière — normal pour de nombreux scénarios domestiques, mais à examiner si la charge est censée être stable.

L'atomicité est garantie

CMD_LATCH_PERIOD s'exécute avec les interruptions désactivées pendant la copie de l'instantané (quelques microsecondes). Le maître ne peut jamais lire un instantané à moitié mis à jour — même s'il lit les octets immédiatement après l'écriture, le firmware termine la mise à jour du bloc avant la fin de la transaction I²C suivante (au moins 10 µs+ s'écoulent entre l'écriture et la lecture).

La même atomicité lie la remise à zéro de l'accumulateur à la copie de l'instantané — chaque échantillon de P figure dans exactement un instantané (soit la période précédente, soit la suivante), jamais dans les deux, jamais dans aucun.

Ce que le maître NE DOIT PAS faire

  • ❌ Ne calculez pas U_rms × I_rms × dt — c'est l'énergie apparente (VAh), non des Wh. La puissance apparente inclut le contenu réactif et surestime toute charge inductive. Utilisez PERIOD_AVG_P_W.
  • ❌ Ne déduisez pas le sens de I_rms — le RMS est toujours ≥ 0. Le sens réside dans le signe de P_real.
  • ❌ N'utilisez pas PERIOD_LATCH_MS pour les Wh — ce registre est de diagnostic et peut dériver avec l'horloge de la puce. master_dt fait foi.
  • ❌ Ne prenez pas d'instantané plus vite que le cycle de validation temps réel. La puce a besoin d'au moins une période du secteur (~20 ms à 50 Hz) d'accumulation plus la stabilisation — minimum 50 ms entre deux envois de CMD_LATCH_PERIOD. Des instantanés plus rapprochés donnent un instantané vide (PERIOD_VALID = 0). 200 ms est un plancher pratique sûr pour l'interrogation en régime établi ; voir chapitre 11 §6.0 / §6.4.

Diagnostic de dérive d'horloge

PERIOD_LATCH_MS est un registre de diagnostic uniquement — la base de temps interne du module affiche une valeur trop courte lorsque le module est occupé. La vérification croisée doit utiliser une enveloppe large :

C++
uint32_t chip_dt = rb_read_u32(0x50, 0xEC);
uint32_t master_dt = t_now - t_prev;
float ratio = (float)chip_dt / (float)master_dt;
if (ratio < 0.70f || ratio > 1.05f) {
  Serial.printf("WARN: chip drift outside ±30%% envelope, ratio=%.3f\n", ratio);
}

Acceptation : une sous-estimation allant jusqu'à 30 % sous charge est normale (rapport descendant jusqu'à ~0.70). C'est volontaire — voir troubleshooting.md §13. N'utilisez pas un seuil serré de 3 %–5 % ; il rejettera en masse des modules sains.

Cette dérive n'affecte pas la précision des Wh (les Wh utilisent l'horloge maître) ; PERIOD_LATCH_MS ne sert qu'à signaler les anomalies graves côté puce.

Quand vous voulez la propre mesure du module de la longueur de fenêtre close, utilisez PERIOD_COMMIT_COUNT (registre 0xBE) multiplié par la longueur du commit : il compte les commits RT entiers et ne sous-estime pas sous charge comme peut le faire PERIOD_LATCH_MS. Un commit = 0.1 s depuis la v1.2 ; les images antérieures à la v1.2 utilisaient 0.2 s. Aucune table de versions n'est nécessaire pour les distinguer : le rapport PERIOD_LATCH_MS / PERIOD_COMMIT_COUNT donne une valeur proche de 100 ou proche de 200.

Suivant