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
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
E_Wh = avg_P_W × master_dt_seconds / 3600
Where:
avg_P_W— la valeur dePERIOD_AVG_P_W, lue aprèsCMD_LATCH_PERIOD.master_dt_seconds— les secondes écoulées entre deux instantanés successifs, mesurées par le maître.
Période atomique — concept
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()) :
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 »).
— 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 |
Cycle d'interrogation continu (recommandé)
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.
— 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 |
: 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 |
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)
#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
- Le premier instantané est une amorce — son résultat est écarté.
PERIOD_VALIDdoit être lu AVANT d'utiliser l'instantané — sinon des données périmées peuvent passer en cas de course.- 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. t_prevprend 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.
— 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
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).
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.
// 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 :
- Intégration côté maître — lire le
P_realtemps 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.
— 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_VALIDreste à 1 (l'instantané est valide, simplement nul).PERIOD_MAX_P_Wvaut 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 :
// 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 ? »)
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 :
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_Sa diminué depuis votre instantané précédent, ouUPTIME_Sest 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.
— 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 :
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.
// 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 :
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é).
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 |
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_Psignale l'événement. - Contrôle de cohérence : si
max_Pdépasse largementavg_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. UtilisezPERIOD_AVG_P_W. - ❌ Ne déduisez pas le sens de
I_rms— le RMS est toujours ≥ 0. Le sens réside dans le signe deP_real. - ❌ N'utilisez pas
PERIOD_LATCH_MSpour les Wh — ce registre est de diagnostic et peut dériver avec l'horloge de la puce.master_dtfait 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 :
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
- troubleshooting.md — que faire lorsque les valeurs semblent fausses
- arduino-examples.md — exemple 5 (bidirectionnel côté maître sur le firmware BASIC)