06 · Exemples
Ce chapitre s'ouvre sur les scénarios phares — les motifs de déploiement réels pour lesquels la bibliothèque a été conçue (secteur + N sous-charges sur un seul bus, instantanés synchronisés par GC). Ils sont suivis de scénarios à module unique — du « bonjour le monde » minimal jusqu'au journaliseur sur batterie en veille profonde.
La plupart des scénarios sont livrés sous forme de projets IDF prêts à compiler dans examples/, que vous pouvez compiler avec idf.py -C examples/. Le code de ce chapitre est une distillation de la logique clé, et non le projet complet (bus_cfg / mise en service WiFi / Kconfig sont omis par souci de concision).
| # | Scénario | Difficulté | Source |
|---|---|---|---|
| 1 | Secteur + N sous-charges : le canon des 80 % | moyen | examples/fleet_sync/ |
| 2 | Flux de provisionnement (vierge → parc) | faible | (composition) |
| 3 | CT mixtes multicanal (I3, modèles différents) | moyen | (composition) |
| 4 | Synchronisation GC de flotte — synchronicité des périodes tarifaires | moyen | examples/fleet_sync/ |
| 5 | Lecture rapide (module unique) | minimal | examples/quick_read/ |
| 6 | Compteur Wh sur écran LCD 16×2 | faible | examples/lcd_period/ |
| 7 | Surveillance de 3 modules (séquentiel historique) | faible | examples/multi_module/ |
| 8 | MQTT par canal | moyen | examples/mqtt_publisher/ |
| 9 | Comptage bidirectionnel côté maître | moyen | (composition) |
| 10 | Bilan énergétique de la maison entière (3 modules) | élevé | (composition) |
| 11 | Journalisation par événements (EMA) | moyen | (composition) |
| 12 | Journaliseur CSV local sur SPIFFS | moyen | examples/spiffs_logger/ |
| 13 | Enregistreur sur batterie avec deep-sleep | moyen | examples/deep_sleep_logger/ |
| 14 | I3 avec un CT différent par canal (analyse approfondie de charges mixtes) | moyen | (composition) |
| 15 | Sous-comptage : 5×UI1 sur un bus partagé | élevé | (composition) |
| 16 | Instantané de diffusion GC pour plus de 8 modules | élevé | (composition) |
| 17 | Filtrage par groupe GC (comptage multi-locataires) | élevé | (composition) |
| 18 | Module STD : puissances réactive / apparente, THD, énergie cadencée par le maître | moyen | examples/std_meter/ |
Le scénario 18 présente la gamme de modules STD. Les scénarios 1 à 4 sont les scénarios phares, construits autour du déploiement canonique de la bibliothèque. Leur code utilise l'API de flotte et est validé sur matériel de banc (une flotte hétérogène UI1+I2+I3). Les scénarios 5 à 13 concernent un seul module et des schémas composés ; les scénarios 14 à 17 sont des scénarios de flotte étendus (approfondissement des capacités introduites en 1 à 4). Le scénario 7 est l'ancien instantané séquentiel par module, sans API de flotte, conservé pour comparaison et comme chemin de migration.
Tous les scénarios supposent que la classe de capteur et le modèle de CT ont déjà été configurés via rbamp_set_sensor_class() + rbamp_set_ct_model() (voir 05 · Démarrage rapide, étape 3). Cela se fait une seule fois à l'installation — les réglages sont stockés dans la flash du module et survivent à une réinitialisation.
REQUIRES supplémentaires pour main/CMakeLists.txt
Le composant de base tire esp_driver_i2c, esp_timer, log. Certains scénarios utilisent des composants ESP-IDF supplémentaires — ajoutez-les au REQUIRES de votre main/ :
| Scénario | REQUIRES supplémentaires |
|---|---|
| 1 — Arrivée secteur + N charges secondaires (flotte) | — (rbamp uniquement) |
| 2 — Flux de provisionnement | — |
| 3 — Multi-canaux à CT mixtes (I3) | — |
| 4 — Synchronisation GC de flotte | — |
| 5 — Lecture rapide | — |
| 6 — Compteur Wh sur écran LCD | rbamp (le pilote LCD est un composant séparé de votre choix) |
| 7 — Multi-modules (séquentiel historique) | — |
| 8 — MQTT par canal | rbamp mqtt esp_wifi esp_event esp_netif nvs_flash |
| 9 — Comptage bidirectionnel | — |
| 10 — Bilan énergétique | — |
| 11 — Journalisation par événements | — |
| 12 — Journaliseur SPIFFS | rbamp spiffs |
| 13 — Enregistreur en deep-sleep | rbamp esp_sleep esp_wifi esp_event esp_netif nvs_flash mqtt (si vous publiez) |
| 18 — Compteur STD | — (rbamp uniquement) |
Les composants réseau exigent aussi nvs_flash_init() dans app_main et la mise en route du Wi-Fi. Par souci de concision, tout cela est omis dans les extraits ci-dessous ; le projet complet se trouve toujours dans examples/.
Remarque importante sur les extraits ci-dessous. Chaque extrait est une distillation de la logique clé, non un app_main complet. Dans un code fonctionnel, la ligne rbamp_handle_t dev est toujours précédée de i2c_master_bus_config_t bus_cfg = {...}; i2c_new_master_bus(&bus_cfg, &bus); rbamp_new(bus, 0x50, &dev); rbamp_begin(dev); (pour un module unique) ou de rbamp_fleet_create(bus, &fleet); rbamp_fleet_scan(fleet, true, &n); (pour la flotte). Une fois le travail terminé — rbamp_del(dev) / rbamp_fleet_destroy(fleet) (omis là où app_main entre dans une boucle infinie — le handle vit jusqu'au redémarrage de la puce).
Scénario 1 — Secteur + N sous-charges (le canon 80 %) : système de comptage intégré
Objectif : le déploiement canonique de la bibliothèque — un système de comptage cohérent sur une flotte hétérogène, bouclé en une seule boucle :
-
Découvrir —
rbamp_fleet_scantrouve tous les modules, vérifie leur identité et écarte les adresses en conflit. -
Configurer —
rbamp_configure_channelsrègle la classe de capteur + les modèles de CT par canal + une seule sauvegarde terminaleSAVE_USER_CONFIGen un appel par module multicanal. -
Armement GC —
rbamp_fleet_enable_gc_allactive la réception des instantanés General-Call sur chaque module de la flotte. -
Boucle — à chaque cycle, le maître exécute un
_gclatchatomique (un instantané synchrone sur toute la flotte), contrôle_check_sync, lit_poll_all, intègre l'énergie surmaster_dt, et calcule_total_power+_total_energy_wh.
C'est l'exemple principal du chapitre — il montre la bibliothèque entière en fonctionnement dans la configuration de référence. Chacun des autres scénarios (2-17) découpe ce flux en blocs élémentaires ou l'enrichit d'intégrations tierces (LCD, MQTT, SD).
Matériel (validé sur matériel) : une flotte hétérogène de 3 modules sur un bus unique, avec une résistance de rappel externe de 4.7 kΩ sur SDA/SCL (voir 04 · Câblage, section « Bus multi-modules — la topologie principale ») :
@0x50— UI1, compteur secteur à l'entrée de service (un canal de courant + tension).@0x51— I2, un sous-compteur de courant à deux canaux (sans tension).@0x52— I3, un sous-compteur de courant à trois canaux (sans tension).
La charge de référence sur la ligne est d'environ 0.57 A.
Code — boucle intégrée
#include "rbamp.h"
#include "rbamp_fleet.h"
#include "esp_timer.h"
static const char *TAG = "metering";
/* The per-module Wh accumulator lives in the handle (the component
* already integrates by master_dt in rbamp_read_period_snapshot —
* here we only read it). */
static void configure_one(rbamp_handle_t dev) {
if (!dev) return;
uint8_t n = rbamp_channels(dev);
if (n == 1) { /* UI1 mains */
rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013);
rbamp_set_ct_model(dev, /*example=*/3); /* SCT-013-030 */
rbamp_save_user_config(dev);
} else if (n == 2) { /* I2 sub-meter */
const uint8_t models[2] = { 1, 3 }; /* 5A, 30A */
rbamp_configure_channels(dev, RBAMP_SENSOR_SCT013, models, 2);
} else if (n == 3) { /* I3 sub-meter */
const uint8_t models[3] = { 1, 3, 6 }; /* 5A, 30A, 20A */
rbamp_configure_channels(dev, RBAMP_SENSOR_SCT013, models, 3);
}
}
void app_main(void) {
/* 1) bus + fleet_create — omitted for brevity */
rbamp_fleet_t fleet;
ESP_ERROR_CHECK(rbamp_fleet_create(bus, &fleet));
/* 2) discover */
size_t n_added = 0;
if (rbamp_fleet_scan(fleet, true, &n_added) == ESP_ERR_INVALID_STATE) {
ESP_LOGE(TAG, "bus wedged — see ch.10");
return;
}
ESP_LOGI(TAG, "fleet_scan: %u module(s), %u excluded",
(unsigned)n_added,
(unsigned)rbamp_fleet_excluded_count(fleet));
/* 3) configure per-module (mixed-CT on the sub-meters) */
for (size_t i = 0; i < rbamp_fleet_count(fleet); ++i) {
configure_one(rbamp_fleet_get(fleet, i));
}
/* 4) arm GC across the whole fleet */
size_t gc_ok = 0;
ESP_ERROR_CHECK(rbamp_fleet_enable_gc_all(fleet, /*group=*/0, &gc_ok));
ESP_LOGI(TAG, "enable_gc_all → %u/%u modules armed",
(unsigned)gc_ok, (unsigned)rbamp_fleet_count(fleet));
/* 5) loop: gclatch → check_sync → poll_all → energy + totals */
rbamp_snapshot_t snaps[RBAMP_FLEET_MAX_MODULES];
rbamp_fleet_poll_t status[RBAMP_FLEET_MAX_MODULES];
rbamp_fleet_sync_t sync_status[RBAMP_FLEET_MAX_MODULES];
uint16_t tick = 0;
while (1) {
rbamp_fleet_gclatch(fleet, /*group=*/0, tick, /*settle_ms=*/50);
size_t n_missed = SIZE_MAX;
rbamp_fleet_check_sync(fleet, tick, sync_status,
RBAMP_FLEET_MAX_MODULES, &n_missed);
size_t n_ok = 0;
rbamp_fleet_poll_all(fleet, snaps, status,
RBAMP_FLEET_MAX_MODULES, &n_ok);
/* Energy is accumulated per-handle by the component on each
* period-snapshot read. Here we read the fleet-wide aggregates. */
float p_total = 0.0f;
double e_total = 0.0;
rbamp_fleet_total_power(fleet, &p_total);
rbamp_fleet_total_energy_wh(fleet, &e_total);
size_t n_total = rbamp_fleet_count(fleet);
ESP_LOGI(TAG, "ITER %3u: GC %u/%u in_sync | poll n_ok=%u/%u | "
"P_total=%.1f W E_total=%.3f Wh",
(unsigned)tick,
(unsigned)(n_total - n_missed), (unsigned)n_total,
(unsigned)n_ok, (unsigned)n_total,
p_total, e_total);
tick++;
vTaskDelay(pdMS_TO_TICKS(1000)); /* 1 Hz for a compact summary */
}
}
Sortie de banc (validée sur matériel sur toute la flotte)
INTEGRATED METERING SYSTEM — fleet_scan: 3 module(s), 0 excluded
module[0] @0x50 channels=1 voltage=yes (mains meter: voltage + 1 current)
module[1] @0x51 channels=2 voltage=no (2-channel current sub-meter)
module[2] @0x52 channels=3 voltage=no (3-channel current sub-meter)
configure_channels(2ch) → mirrors [1 2 -]
configure_channels(3ch) → mirrors [1 2 3]
enable_gc_all → 3/3 modules armed
ITER 1..N: GC in_sync=3/3 skew=0 | poll n_ok=3/3 | P_total≈1260 W | E_total: 2.49 → 4.38 Wh (accumulating)
@0x50 V=226 I=[5.58] P=[1256] (mains)
@0x51 V= — I=[11.30, 3.75] P=[—] (current sub-meter)
@0x52 V= — I=[ 3.73, 1.87, 7.50] P=[—] (current sub-meter; the 3rd input
is unused on this rig,
pickup ≈ zero)
Les chiffres de banc illustrent la forme des données et leur cheminement dans le système — pas la précision de mesure.
Remarques pour le déploiement
-
Une seule boucle synchronisée suffit pour tout le système. À chaque cycle : un
gclatch(une seule transaction General-Call I²C) → tous les modules démarrent atomiquement leur instantané de période (check_sync= 3/3, décalage = 0) → un seulpoll_alllit toute la flotte → agrégation. Aucune dérive entre modules due à une chaîne d'allers-retours séquentiels. -
Comportement de
total_powerdans une flotte hétérogène. UI1 fournit la puissance active (il a une tension → il aP) ; les I2/I3 ne mesurent que le courant, donc leur contribution àtotal_powerest nulle. Par conséquent, dans le canon,total_power≈ la puissance du module secteur. Pour la puissance par charge sur un sous-compteur, calculez-la côté maître :P_subload[k] ≈ V_mains × I_sub[k](une approximation, juste lorsque les PF sont proches ; un sous-compteur en courant seul ne peut pas donner la puissance exacte par charge). -
Énergie (Wh) — horloge murale maître.
E_totalcroît de façon monotone (2.55 → 6.94 Wh sur la fenêtre de capture de banc) ; le composant intègre chaque période parmaster_dt_ms(esp_timer), non parlatch_mscôté puce (une minuterie de diagnostic du module qui peut lire court). Un tick parasite ajoute0 Whsi aucune nouvelle période ne s'est écoulée entre deux scrutations — c'est normal (snap.valid = 0 sur ce cycle). -
Scrutation résistante aux manques. Si l'un des modules quitte le bus (déconnexion, redémarrage),
poll_allle signale avecstatus[i] != ESP_OKet continue de scruter les autres — le maître ne se bloque pas. Vérifié sur banc : un module déconnecté en cours de route a laissé la flotte scrutée àn_ok=2/3sans blocage. Il en va de même pourcheck_sync—missed_idxpointe vers le premier module désynchronisé pendant que les autres continuent de prendre leurs instantanés. -
Analyse du bilan. Dans le canon 80 % :
balance = P_mains − Σ(V_mains × I_sub[k])— une estimation du « reste » (consommation de fond, charges non comptabilisées). Le code ciblé parcourt la flotte en séparant le handle du secteur (celui qui ahas_voltage = true) des sous-handles (tous les autres). -
Courants par canal → désagrégation des charges. Via
fleet_poll_all, le maître voit tous les canaux de courant d'un coup (1+2+3 = 6 sur notre flotte de banc), sans lecteurs séparés par module. -
CT mixtes sur un module à 3 canaux. Utilisez la version actuelle de la bibliothèque ; les miroirs [1 2 3] sur I3 se stabilisent comme configuré. L'ordre dans lequel les canaux sont liés n'a pas d'importance.
-
Latence de scrutation pour le dimensionnement en production (mesurée sur matériel). Sur banc à 50 kHz I²C : 2 modules — moyenne
89.4 ms(min 89.4 / max 89.6) ; 3 modules — moyenne112.1 ms(min 112.1 / max 112.3). Soit ≈ 22 à 23 ms par module supplémentaire, linéaire et avec une gigue très faible (min ≈ max). Unfleet_poll_allgroupé unique est déterministe sur un bus propre. Une flotte de 3 modules (~112 ms) tient dans un intervalle de scrutation de 200 ms — une cadence de scrutation de 5 Hz est donc réalisable (toutes les deux fenêtres de module de 100 ms) sans saturer le bus. Le budget complet du bus (lorsque la flotte dépasse l'intervalle de scrutation) figure dans le tableau de 04 · Câblage, section « Bus energy budget » (budget énergétique du bus).
Scénario 2 — Flux de provisionnement (vierge → flotte)
Objectif : déplacer un nouveau module de son adresse d'usine 0x50 vers une adresse de travail et l'ajouter à une flotte existante, en persistant sa configuration (modèles de CT, étiquette) en flash.
Matériel (validé sur matériel) : un module vierge à l'adresse d'usine 0x50 (HW_VARIANT 3 canaux). Le provisionnement le déplace à l'adresse 0x52 et enregistre la configuration en flash.
#include "rbamp_fleet.h"
#include "rbamp.h"
void provision_new_module(i2c_master_bus_handle_t bus,
rbamp_fleet_t fleet,
uint8_t desired_addr,
const char *label /* nullable */) {
/* PRECONDITION: exactly one virgin at 0x50 on the bus.
* MUST one-virgin-at-a-time — see ch.04 + ch.10. */
rbamp_handle_t dev = NULL;
esp_err_t err = rbamp_provision(bus, desired_addr,
/*save_config=*/true, &dev);
if (err == ESP_ERR_NOT_FOUND) {
ESP_LOGE("prov", "nobody answers at 0x50 — check VCC/I2C");
return;
}
if (err == ESP_ERR_INVALID_STATE) {
ESP_LOGE("prov", "0x50 or 0x%02X is already taken — "
"discipline violation? see ch.10",
desired_addr);
return;
}
if (err != ESP_OK) {
ESP_LOGE("prov", "provision fail: %s", esp_err_to_name(err));
return;
}
ESP_LOGI("prov", "provisioned virgin → 0x%02X (+saved)", desired_addr);
/* Label for fleet iterations (optional). */
if (label) rbamp_write_label(dev, label);
/* Bind the sensor class + CT model + one more SAVE_USER_CONFIG. */
rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013);
rbamp_set_ct_model(dev, /*example=*/3); /* SCT-013-030 */
rbamp_save_user_config(dev);
/* Add to the fleet — from here the module is polled the usual way. */
rbamp_fleet_add(fleet, dev);
ESP_LOGI("prov", "module @0x%02X added to the fleet", desired_addr);
}
Sortie de banc (chemin de réussite validé sur matériel) :
before: present(0x50)=yes present(0x52)=no
virgin @0x50: variant=3-channel, channels=3
rbamp_provision(→0x52, save_config=true) = ESP_OK
(lib log: "provisioned virgin → 0x52 (+saved)")
post: handle now answers @0x52, is_provisioned=true
after: present(0x50)=no present(0x52)=yes
is_provisioned renvoie true après un appel réussi. Sur un module sorti d'usine et que rien n'a encore touché, le is_provisioned précédent vaudra false — c'est l'état normal 0xFB (ERR_FLASH_PARAMS_BAD) décrit dans 10 · Dépannage, et il n'est pas fatal.
Chemins de défaillance
| Erreur | Condition | Récupération |
|---|---|---|
ESP_ERR_NOT_FOUND |
Personne ne répond à 0x50 |
Vérifiez que le module vierge est physiquement connecté et alimenté (VCC) ; contrôle du bus (10 · Dépannage). |
ESP_ERR_INVALID_STATE |
Un conflit a été détecté à 0x50 ou desired_addr ; des modules différents répondent de façon identique |
Violation de la discipline — plus d'un module vierge sur le bus. Coupez l'alimentation, déconnectez physiquement tous les modules sauf un, puis réessayez (voir la procédure de récupération dans 10 · Dépannage). |
ESP_ERR_TIMEOUT |
La validation en deux phases a abouti, mais le module n'est pas apparu à la nouvelle adresse dans la fenêtre de démarrage | Couper puis rallumer le module, réessayer. Si cela persiste — problème de cycles de flash. |
ESP_ERR_INVALID_ARG |
desired_addr hors de 0x08..0x77 |
Utilisez une adresse 7 bits valide. |
Un parcours détaillé des modes de défaillance : 10 · Dépannage, section « Flotte : rbamp_provision a renvoyé une erreur ».
Scénario 3 — CT mixtes multi-canaux (I3, modèles différents par canal)
Objectif : démontrer rbamp_configure_channels sur un I3 — trois canaux avec des modèles de CT différents (par ex. ch0=SCT-013-005 pour une petite charge, ch1=SCT-013-030 pour une charge moyenne, ch2=SCT-013-020 pour une grosse charge) avec un seul cycle flash terminal (ménagé pour la flash), et confirmer la persistance après un redémarrage.
#include "rbamp.h"
#include "esp_timer.h"
void configure_mixed_ct(rbamp_handle_t dev_i3) {
/* (a) Configure — three CT models in a single call. */
const uint8_t models[3] = { 1, 3, 6 };
/* 1=SCT-013-005 (5A), 3=SCT-013-030 (30A), 6=SCT-013-020 (20A) */
int64_t t0 = esp_timer_get_time();
esp_err_t err = rbamp_configure_channels(
dev_i3, RBAMP_SENSOR_SCT013, models, 3);
int64_t t1 = esp_timer_get_time();
if (err != ESP_OK) {
uint8_t reg_err;
rbamp_read_last_error(dev_i3, ®_err);
ESP_LOGE("3", "configure rejected: %s, REG_ERROR=0x%02X",
esp_err_to_name(err), reg_err);
return;
}
ESP_LOGI("3", "configure_channels latency = %lld ms",
(long long)((t1 - t0) / 1000));
/* (b) Verify the mirror via registers 0x51 / 0x52 / 0x53 (RAM). */
uint8_t m0, m1, m2;
rbamp_read_ct_model_ch(dev_i3, 0, &m0);
rbamp_read_ct_model_ch(dev_i3, 1, &m1);
rbamp_read_ct_model_ch(dev_i3, 2, &m2);
ESP_LOGI("3", "applied: [%u %u %u] (expected [1 3 6])", m0, m1, m2);
/* (c) Persist verify — reset + re-read the mirror after boot. */
rbamp_reset(dev_i3);
vTaskDelay(pdMS_TO_TICKS(300)); /* boot window */
rbamp_read_ct_model_ch(dev_i3, 0, &m0);
rbamp_read_ct_model_ch(dev_i3, 1, &m1);
rbamp_read_ct_model_ch(dev_i3, 2, &m2);
ESP_LOGI("3", "after reboot: [%u %u %u]", m0, m1, m2);
}
Sortie de banc (validée sur matériel sur un I3 reflashé à neuf) :
configure_channels(SCT013, {1, 3, 6}, 3) = ESP_OK
configure_channels latency = 1403 ms
applied: [1 3 6] (raw 0x01 0x03 0x06)
after reboot: [1 3 6] (persisted through CMD_RESET + boot)
La propriété « SAVE unique » — pourquoi elle compte
configure_channels effectue une seule CMD_SAVE_USER_CONFIG de terminaison à la fin. L'alternative — des appels set_ct_model_ch séparés pour chaque canal, chacun suivi de son propre save_user_config — donne trois cycles d'effacement et d'écriture de la flash.
Comparaison de latence sur banc (sur le même I3) :
| Approche | Latence | Cycles de flash |
|---|---|---|
configure_channels(...) — 1 SAUVEGARDE de terminal |
~1403 ms | 1 |
3× (set_ct_model_ch + save_user_config) |
~3492 ms | 3 |
3× plus lent — soit (~2.5×) × ~700 ms. Le point clé est la différence d'usure de 3× sur la même page de flash : avec les reconfigurations habituelles des modules sur le terrain, cela représente un coût d'usure notable. Utilisez toujours configure_channels lorsque vous devez régler la classe de capteur + les modèles de CT par canal.
Pour la famille SCT-013 : 1=SCT-013-005, 2=SCT-013-010, 3=SCT-013-030, 4=SCT-013-050, 5=SCT-013-100, 6=SCT-013-020, 7=SCT-013-060. Un code en dehors de {1, 2, 3, 4, 5, 6, 7} donne ESP_ERR_INVALID_ARG / REG_ERROR=0xFE (ERR_PARAM).
Scénario 4 — Synchronisation GC de flotte (synchronisation des périodes tarifaires)
Objectif : démontrer un instantané atomique sur toute la flotte avec une seule trame General-Call I²C. Contrairement au CMD_LATCH_PERIOD séquentiel module par module (où le décalage s'accumule à chaque aller-retour), GC synchronise tous les modules dans une seule transaction de bus.
Matériel : la même flotte hétérogène UI1+I2+I3 (@0x50/0x51/0x52).
#include "rbamp_fleet.h"
static const char *TAG = "gc_sync";
void app_main(void) {
/* bus init + fleet_create + fleet_scan ... as in Sc.1 */
/* Step 1: enable GC on all modules in the fleet. */
size_t gc_ok = 0;
ESP_ERROR_CHECK(rbamp_fleet_enable_gc_all(fleet, /*group=*/0, &gc_ok));
ESP_LOGI(TAG, "GC armed: %u/%u",
(unsigned)gc_ok, (unsigned)rbamp_fleet_count(fleet));
rbamp_fleet_sync_t sync_status[RBAMP_FLEET_MAX_MODULES];
uint16_t tick = 0;
for (int round = 0; round < 10; ++round) {
/* Step 2: a single broadcast snapshot — all modules atomically. */
ESP_ERROR_CHECK(rbamp_fleet_gclatch(fleet, /*group=*/0, tick,
/*settle_ms=*/50));
/* Step 3: in-sync check — all modules caught the same tick. */
size_t n_missed = 0;
rbamp_fleet_check_sync(fleet, tick, sync_status,
RBAMP_FLEET_MAX_MODULES, &n_missed);
size_t n_total = rbamp_fleet_count(fleet);
ESP_LOGI(TAG, "round %d tick=%u in_sync=%u/%u",
round, tick,
(unsigned)(n_total - n_missed), (unsigned)n_total);
tick++;
vTaskDelay(pdMS_TO_TICKS(100));
}
}
Sortie de banc (10 cycles sur la flotte UI1+I2+I3, résistance de rappel 4.7 kΩ) :
rbamp_fleet_enable_gc_all() → 3/3 modules armed
round 0 tick=0 in_sync=3/3 skew=0
round 1 tick=1 in_sync=3/3 skew=0
round 2 tick=2 in_sync=3/3 skew=0
round 3 tick=3 in_sync=3/3 skew=0
round 4 tick=4 in_sync=3/3 skew=0
round 5 tick=5 in_sync=3/3 skew=0
round 6 tick=6 in_sync=3/3 skew=0
round 7 tick=7 in_sync=3/3 skew=0
round 8 tick=8 in_sync=3/3 skew=0
round 9 tick=9 in_sync=3/3 skew=0
Quand utiliser la synchronisation GC :
-
Synchronisation serrée. Si l'écart d'instantané entre modules par minute ou par seconde compte pour le reporting (par exemple un bilan
arrivée − Σ(sous)intégré dans le temps — le décalage entre modules introduit une erreur systématique), le GC donneskew = 0d'après une mesure sur banc. Un instantané séquentiel module par module sur ces 3 modules accumule 100 à 300 µs par module × N, ce qui devient sensible sur une fenêtre de 60 minutes en analyse fine. -
Grande flotte. À mesure que le nombre de modules augmente, l'écart entre « N × aller-retour séquentiel » et « une seule trame GC » croît linéairement.
-
Alignement entre déploiements. Si vous avez plusieurs ESP32 sur des bus différents partageant une horloge maître, le tick GC peut être synchronisé via l'horloge murale côté maître — et alors les instantanés de bus différents sont alignés dans une seule fenêtre d'aller-retour réseau.
Témoin via check_sync : une vérification que tous les modules ont bien reçu la trame GC. Il peut en manquer un s'il était occupé à démarrer / dans un cycle de SAVE au moment de la trame — missed_idx pointe vers le premier désynchronisé. Lors de la validation sur banc, 10 tours d'affilée — 0 manque.
Précondition. Le GC doit être activé sur chaque module (rbamp_fleet_enable_gc_all ou, par appareil, rbamp_enable_gc + SAVE_USER_CONFIG + réinitialisation). Un module neuf aux réglages d'usine n'accepte pas le GC — c'est voulu, pour éviter les diffusions accidentelles sur un bus de mise en service.
Scénario 5 — Lecture rapide (module unique)
Objectif : afficher U / I / P / PF / fréquence dans le journal ESP-IDF une fois par seconde. Le même « bonjour le monde » que vous avez écrit dans 05 · Démarrage rapide, mais via rbamp_read_all() — une lecture unique de tout le bloc RT dans une seule structure.
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/i2c_master.h"
#include "esp_log.h"
#include "rbamp.h"
static const char *TAG = "quick_read";
void app_main(void) {
/* ...bus_cfg setup, rbamp_new + rbamp_begin as in the Quickstart... */
rbamp_handle_t dev = NULL;
while (1) {
rbamp_snapshot_t s;
if (rbamp_read_all(dev, &s) != ESP_OK) {
ESP_LOGE(TAG, "read fail");
vTaskDelay(pdMS_TO_TICKS(1000));
continue;
}
ESP_LOGI(TAG, "U=%.1f V f=%.1f Hz channels=%u",
(double)s.voltage, (double)s.frequency, s.channels);
for (uint8_t ch = 0; ch < s.channels; ++ch) {
ESP_LOGI(TAG, " I%u=%.2f A P%u=%.1f W PF%u=%.2f",
ch, (double)s.current[ch],
ch, (double)s.power[ch],
ch, (double)s.power_factor[ch]);
}
vTaskDelay(pdMS_TO_TICKS(1000));
}
}
Ce qui se passe sur le bus : rbamp_read_all() sur un UI3 effectue environ 53 transactions d'un seul octet (13 valeurs flottantes × 4 octets + 1 octet de fréquence). À 50 kHz avec marge de reprise — de l'ordre de 25 à 30 ms. Si vous n'avez pas besoin de toutes les valeurs, appelez les fonctions par propriété (rbamp_read_voltage(), rbamp_read_current(ch)) — moins d'octets sur le bus.
Scénario 6 — Compteur Wh sur un LCD 16×2
Objectif : un compteur Wh, rafraîchi une fois par minute, sur un LCD alphanumérique 16×2 avec un extenseur I²C PCF8574 (compatible HD44780). Le LCD se trouve sur le même bus I²C que le rbAmp. Le mécanisme clé du composant est rbamp_read_period_snapshot(), qui encapsule en un seul appel l'instantané + la stabilisation + la vérification de validité + la lecture + la mise à jour Wh.
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/i2c_master.h"
#include "esp_log.h"
#include "rbamp.h"
/* Minimal LCD shim — inline in the example, no third-party drivers.
* The full lcd_print/lcd_clear functions are in examples/lcd_period/main/main.c. */
void app_main(void) {
/* ...bus_cfg + rbamp + lcd init... */
rbamp_handle_t dev = NULL;
uint32_t ok_count = 0, bad_count = 0;
while (1) {
vTaskDelay(pdMS_TO_TICKS(60000));
rbamp_period_snapshot_t snap;
if (rbamp_read_period_snapshot(dev, &snap, 50, false) != ESP_OK
|| !snap.valid) {
bad_count++;
continue;
}
ok_count++;
char line1[17], line2[17];
snprintf(line1, sizeof(line1), "P=%6.1f W ", (double)snap.avg_p[0]);
snprintf(line2, sizeof(line2), "%8.4f Wh ok%lu", rbamp_energy_wh(dev, 0),
(unsigned long)ok_count);
lcd_clear();
lcd_print(0, 0, line1);
lcd_print(0, 1, line2);
}
}
Le projet IDF complet — examples/lcd_period/.
Traitement des instantanés périmés. rbamp_read_period_snapshot() renvoie ESP_ERR_INVALID_RESPONSE si le module n'a pas réussi à préparer un nouvel instantané à l'heure de la lecture. Le composant enregistre tout de même son horodatage (esp_timer_get_time()) en interne — ainsi, l'instantané réussi suivant n'est pas compté deux fois sur l'intervalle.
Scénario 7 — Surveillance de 3 modules (séquentiel, historique) sur un seul bus
Objectif : interroger 3 modules aux adresses 0x50 / 0x51 / 0x52 depuis un même maître. Chaque module doit avoir une adresse unique (les adresses sont attribuées lors de l'étape de provisionnement en usine / d'intégration — voir 09 · Référence API sur les méthodes de changement d'adresse avec leurs notes d'AVERTISSEMENT).
Le schéma canonique pour le firmware v1 est un rbamp_latch_period() séquentiel sur chaque appareil + une seule pause de stabilisation de 50 ms partagée + rbamp_read_period_snapshot(skip_latch=true) par appareil. Le décalage entre appareils à 100 kHz : ~1 ms par appareil — négligeable face à une période de 60 secondes.
Sur le firmware v1.3 (REG_VERSION = 0x04), rbamp_broadcast_latch() est entièrement pris en charge une fois GC activé à l'échelle de la flotte via rbamp_fleet_enable_gc_all() — le chemin canonique de synchronisation de flotte pour une synchronisation serrée entre sous-compteurs (voir la section de flotte Strategy 2 GC plus haut dans ce chapitre). Sur le firmware historique v1.0-v1.2 (sans prise en charge de l'instantané General-Call), l'appel renvoie ESP_ERR_NOT_SUPPORTED et la bibliothèque revient à l'instantané par appareil présenté ci-dessus. Voir 09 · Référence API pour les détails.
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/i2c_master.h"
#include "esp_timer.h"
#include "esp_log.h"
#include "rbamp.h"
#define N_MODULES 3
static const char *TAG = "multi_module";
static const uint8_t ADDRS[N_MODULES] = { 0x50, 0x51, 0x52 };
void app_main(void) {
/* ...bus_cfg setup as in the Quickstart... */
i2c_master_bus_handle_t bus = NULL;
rbamp_handle_t modules[N_MODULES] = { NULL };
/* Create a handle for each module */
for (int i = 0; i < N_MODULES; ++i) {
if (rbamp_new(bus, ADDRS[i], &modules[i]) != ESP_OK ||
rbamp_begin(modules[i]) != ESP_OK) {
ESP_LOGE(TAG, "module 0x%02X init failed", ADDRS[i]);
modules[i] = NULL;
}
}
while (1) {
vTaskDelay(pdMS_TO_TICKS(60000));
/* Phase 1: sequential snapshot on each device, measure the skew */
const int64_t sync_start_us = esp_timer_get_time();
for (int i = 0; i < N_MODULES; ++i) {
if (modules[i]) rbamp_latch_period(modules[i]);
}
const uint32_t sync_us = (uint32_t)(esp_timer_get_time() - sync_start_us);
/* Phase 2: a single shared settle for all 3 modules */
vTaskDelay(pdMS_TO_TICKS(50));
/* Phase 3: read the snapshots with skip_latch=true */
ESP_LOGI(TAG, "sync_us=%u", (unsigned)sync_us);
for (int i = 0; i < N_MODULES; ++i) {
if (!modules[i]) continue;
rbamp_period_snapshot_t snap;
if (rbamp_read_period_snapshot(modules[i], &snap, 0,
/*skip_latch=*/true) != ESP_OK) {
continue;
}
ESP_LOGI(TAG, "mod%d 0x%02X P=%.0f W Wh=%.3f",
i, ADDRS[i],
(double)snap.avg_p[0],
rbamp_energy_wh(modules[i], 0));
}
}
}
Le projet complet (avec sonde de bus et signalement d'erreurs) — examples/multi_module/.
Scénario 8 — MQTT par canal
Objectif : un module UI3 avec 3 pinces CT sur trois lignes indépendantes. Compteurs Wh par canal, publiés sur MQTT une fois par minute. Montre que rbamp_energy_wh(dev, ch) fonctionne sur chaque canal indépendamment — pas besoin d'un tableau total_wh[3] manuel côté maître.
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/i2c_master.h"
#include "esp_log.h"
#include "mqtt_client.h"
#include "rbamp.h"
static const char *TAG = "ui3_mqtt";
static const char *CH_NAMES[3] = { "main", "heatpump", "lights" };
static esp_mqtt_client_handle_t mqtt;
static void publish_channel(const char *name, float avg_p, double e_wh) {
char topic[64], payload[96];
snprintf(topic, sizeof(topic), "rbamp/%s/state", name);
snprintf(payload, sizeof(payload),
"{\"power\":%.1f,\"energy\":%.4f}", (double)avg_p, e_wh);
esp_mqtt_client_publish(mqtt, topic, payload, 0, /*qos*/1, /*retain*/1);
}
void app_main(void) {
/* ...wifi STA + mqtt_client init... */
/* ...bus_cfg + rbamp_new + rbamp_begin (50 kHz via Kconfig)... */
rbamp_handle_t dev = NULL;
while (1) {
vTaskDelay(pdMS_TO_TICKS(60000));
rbamp_period_snapshot_t snap;
if (rbamp_read_period_snapshot(dev, &snap, 50, false) != ESP_OK ||
!snap.valid) {
continue;
}
for (uint8_t ch = 0; ch < rbamp_channels(dev); ++ch) {
publish_channel(CH_NAMES[ch], snap.avg_p[ch],
rbamp_energy_wh(dev, ch));
}
}
}
Le projet complet — examples/mqtt_publisher/. Pour la découverte automatique MQTT de HA fondée sur ce motif — voir 07 · Intégrations maison + examples/ha_discovery/.
Scénario 9 — Comptage bidirectionnel côté maître
Objectif : séparer la puissance instantanée signée en consommation brute et export brut. Utilisez ce motif sur la gamme BASIC, où le firmware écrête les valeurs négatives dans snap.avg_p[ch] (puissance moyennée sur la période) — échantillonnez rbamp_read_power(dev, 0, &p) (puissance instantanée, signée sur toutes les gammes) à 10 Hz côté maître et répartissez-la vous-même.
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_timer.h"
#include "esp_log.h"
#include "rbamp.h"
static const char *TAG = "bidir";
void bidir_task(void *arg) {
rbamp_handle_t dev = arg;
double consume_wh = 0.0, export_wh = 0.0;
int64_t t_prev_us = esp_timer_get_time();
while (1) {
vTaskDelay(pdMS_TO_TICKS(100)); /* 10 Hz, matches the RT cadence */
const int64_t t_now_us = esp_timer_get_time();
const double dt_s = (double)(t_now_us - t_prev_us) / 1e6;
t_prev_us = t_now_us;
float p;
if (rbamp_read_power(dev, 0, &p) != ESP_OK) continue;
const double dwh = (double)p * dt_s / 3600.0;
if (p >= 0.0f) consume_wh += dwh;
else export_wh += -dwh;
/* Print once a second */
static int n = 0;
if (++n % 5 == 0) {
ESP_LOGI(TAG, "P=%.1f W cons=%.4f Wh exp=%.4f Wh net=%.4f Wh",
(double)p, consume_wh, export_wh,
consume_wh - export_wh);
}
}
}
Il s'agit d'un scénario composite sans projet IDF dédié. Sur un module STD, les compteurs d'énergie sont signés et rbamp_energy_wh(dev, 0) renvoie un bilan net (l'import et l'export sont tenus séparément dans rbamp_std_read_energy()) — cette répartition côté maître n'est nécessaire que sur les modules BASIC, ou pour un reporting séparé de consommation brute / export brut à partir de la puissance temps réel.
Scénario 10 — Bilan énergétique de la maison
Objectif : 3 modules — secteur (bidirectionnel), solaire (production seulement), charges (UI3 par appareil). Le tableau de bord combiné est publié une fois par minute.
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/i2c_master.h"
#include "esp_log.h"
#include "mqtt_client.h"
#include "rbamp.h"
static rbamp_handle_t mains_dev, solar_dev, loads_dev;
static esp_mqtt_client_handle_t mqtt;
void app_main(void) {
/* ...wifi STA + mqtt init... */
/* ...bus_cfg + per-module rbamp_new(bus, 0x50/0x51/0x52, ...) +
* rbamp_begin() on each... */
while (1) {
vTaskDelay(pdMS_TO_TICKS(60000));
/* Sequential snapshot + shared settle (the pattern from Scenario 3) */
rbamp_latch_period(mains_dev);
rbamp_latch_period(solar_dev);
rbamp_latch_period(loads_dev);
vTaskDelay(pdMS_TO_TICKS(50));
rbamp_period_snapshot_t sm, ss, sl;
if (rbamp_read_period_snapshot(mains_dev, &sm, 0, true) != ESP_OK || !sm.valid ||
rbamp_read_period_snapshot(solar_dev, &ss, 0, true) != ESP_OK || !ss.valid ||
rbamp_read_period_snapshot(loads_dev, &sl, 0, true) != ESP_OK || !sl.valid) {
continue;
}
char payload[256];
snprintf(payload, sizeof(payload),
"{\"mains\":%.3f,\"solar\":%.3f,"
"\"hp\":%.3f,\"ac\":%.3f,\"ev\":%.3f}",
rbamp_energy_wh(mains_dev, 0),
rbamp_energy_wh(solar_dev, 0),
rbamp_energy_wh(loads_dev, 0),
rbamp_energy_wh(loads_dev, 1),
rbamp_energy_wh(loads_dev, 2));
esp_mqtt_client_publish(mqtt, "home/energy/balance",
payload, 0, 1, 1);
}
}
Pour une séparation explicite consommation brute / export brut au niveau du secteur — combinez avec le schéma du scénario 5 (une tâche séparée à 10 Hz sur rbamp_read_power(mains_dev, 0, ...)).
C'est un scénario composite sans projet IDF dédié — assemblez-le à partir de examples/mqtt_publisher/ + examples/multi_module/.
Scénario 11 — Journalisation événementielle (EMA)
Objectif : sur chaque fenêtre RT de 100 ms, comparez la puissance instantanée à une moyenne mobile exponentielle. Consignez les écarts significatifs — des charges comme un micro-ondes, une bouilloire ou un sèche-cheveux « apparaissent » dans le journal comme un événement de mise en marche / arrêt.
#include /* fabsf */
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_log.h"
#include "esp_timer.h"
#include "rbamp.h"
#define EMA_ALPHA 0.05f
#define EVENT_THRESHOLD_W 200.0f
static const char *TAG = "event";
void event_task(void *arg) {
rbamp_handle_t dev = arg;
float p_ema = 0.0f;
/* seed the EMA so the first reading is not a false event */
if (rbamp_read_power(dev, 0, &p_ema) != ESP_OK) p_ema = 0.0f;
while (1) {
vTaskDelay(pdMS_TO_TICKS(200));
float p;
if (rbamp_read_power(dev, 0, &p) != ESP_OK) continue;
const float delta = p - p_ema;
p_ema = (1.0f - EMA_ALPHA) * p_ema + EMA_ALPHA * p;
if (fabsf(delta) > EVENT_THRESHOLD_W) {
ESP_LOGI(TAG, "%s delta=%.0f W P=%.0f W EMA=%.0f W",
(delta > 0) ? "TURN_ON" : "TURN_OFF",
(double)delta, (double)p, (double)p_ema);
}
}
}
Un scénario composite — pas de projet IDF dédié. Combinez-le avec la publication MQTT du scénario 4 pour les automatisations côté HA, ou écrivez les événements dans SPIFFS selon le motif du scénario 8 pour un journal hors ligne.
Scénario 12 — Enregistreur CSV local sur SPIFFS
Objectif : écrire un instantané de période dans un fichier CSV sur SPIFFS une fois par minute. Utile pour les déploiements autonomes sans Wi-Fi / MQTT, ou comme tampon avant une synchronisation cloud différée.
Nécessite une table de partitions personnalisée avec l'entrée storage,data,spiffs,,128K, dans partitions.csv. Un exemple se trouve dans examples/spiffs_logger/partitions.csv.
#include
#include
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_spiffs.h"
#include "esp_log.h"
#include "esp_timer.h"
#include "rbamp.h"
#define LOG_PATH "/storage/log.csv"
#define ROTATE_BYTES (64 * 1024)
static const char *TAG = "spiffs_logger";
static void rotate_if_full(void) {
struct stat st;
if (stat(LOG_PATH, &st) == 0 && st.st_size >= ROTATE_BYTES) {
rename(LOG_PATH, "/storage/log_prev.csv");
}
}
void app_main(void) {
esp_vfs_spiffs_conf_t spiffs_cfg = {
.base_path = "/storage",
.partition_label = "storage",
.max_files = 4,
.format_if_mount_failed = true,
};
ESP_ERROR_CHECK(esp_vfs_spiffs_register(&spiffs_cfg));
/* ...bus_cfg + rbamp_new + rbamp_begin... */
rbamp_handle_t dev = NULL;
while (1) {
vTaskDelay(pdMS_TO_TICKS(60000));
rbamp_period_snapshot_t snap;
if (rbamp_read_period_snapshot(dev, &snap, 50, false) != ESP_OK ||
!snap.valid) continue;
rotate_if_full();
FILE *f = fopen(LOG_PATH, "a");
if (!f) {
ESP_LOGE(TAG, "fopen failed");
continue;
}
fprintf(f, "%lld,%.3f,%.4f,%u\n",
(long long)(esp_timer_get_time() / 1000),
(double)snap.avg_p[0],
rbamp_energy_wh(dev, 0),
(unsigned)snap.master_dt_ms);
fclose(f);
}
}
Le projet complet — examples/spiffs_logger/. L'extrait ci-dessus est une simplification pédagogique avec une ligne CSV à 4 colonnes. L'exemple écrit lui-même une ligne CSV à 9 colonnes avec avg_p par canal et Wh pour les 3 canaux — plus utile pour les scénarios de production sur modules UI3.
Pour une synchronisation différée vers le cloud (journaliser localement, envoyer une fois par heure), voir la section « Hybride : stockage local + synchronisation » dans 08 · Intégrations cloud.
Scénario 13 — Enregistreur sur batterie avec deep-sleep
Objectif : un ESP32 se réveille une fois toutes les 10 minutes, prend un instantané de période unique, publie via WiFi+MQTT, puis retourne en veille profonde. L'énergie persiste dans la mémoire RTC entre les cycles de sommeil. L'accumulateur du composant est désactivé — c'est le maître qui gère lui-même la persistance des Wh.
⚠ Remarque importante sur la veille profonde. Sur le firmware actuel, rbamp_begin() émet toujours un amorçage CMD_LATCH_PERIOD, qui réinitialise l'accumulateur de période du firmware. Cela signifie qu'après un réveil de veille profonde, vous ne pouvez pas simplement appeler rbamp_read_period_snapshot() par défaut — cet appel prendrait un autre instantané et renverrait des données proches de zéro environ 50 ms après l'amorçage. Le bon motif ci-dessous utilise skip_latch=true pour lire les données accumulées pendant l'intervalle de sommeil, et le timer RTC propre au maître pour l'intervalle entre les réveils (le champ snap.master_dt_ms ne reflète que le temps à l'intérieur du cycle de réveil courant, et non d'un réveil à l'autre).
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/i2c_master.h"
#include "esp_log.h"
#include "esp_sleep.h"
#include "esp_timer.h"
#include "rbamp.h"
#define WAKE_INTERVAL_US (10ULL * 60ULL * 1000000ULL)
#define RTC_MAGIC 0xCAFEFEEDu
RTC_DATA_ATTR static uint32_t rtc_magic = 0;
RTC_DATA_ATTR static double rtc_total_wh = 0.0;
RTC_DATA_ATTR static bool rtc_primer_done = false;
RTC_DATA_ATTR static uint64_t rtc_last_wake_us = 0;
static const char *TAG = "deep_sleep";
void app_main(void) {
/* ...bus_cfg setup... */
i2c_master_bus_handle_t bus = NULL;
rbamp_handle_t dev = NULL;
if (rtc_magic != RTC_MAGIC) {
/* Cold start — initialize RTC-RAM */
rtc_magic = RTC_MAGIC;
rtc_total_wh = 0.0;
rtc_primer_done = false;
rtc_last_wake_us = 0;
}
ESP_ERROR_CHECK(rbamp_new(bus, 0x50, &dev));
ESP_ERROR_CHECK(rbamp_begin(dev)); /* issues the primer snapshot */
rbamp_energy_disable(dev); /* the master owns Wh itself */
if (!rtc_primer_done) {
/* First wake: the primer snapshot just captured the "dirty" data from
* before wake. Record the time and go straight back to sleep —
* the next wake in 10 min gets a full accumulator for the interval. */
rtc_last_wake_us = esp_timer_get_time();
rtc_primer_done = true;
esp_sleep_enable_timer_wakeup(WAKE_INTERVAL_US);
esp_deep_sleep_start();
}
/* skip_latch=true reads what the rbamp_begin() primer latched —
* that is, the accumulator for the elapsed 10-minute sleep interval. */
rbamp_period_snapshot_t snap;
esp_err_t snap_err = rbamp_read_period_snapshot(dev, &snap, /*settle_ms=*/0,
/*skip_latch=*/true);
if (snap_err != ESP_OK || !snap.valid) {
ESP_LOGW(TAG, "snapshot fail: %s (valid=%d)",
rbamp_err_to_str(snap_err), snap.valid);
esp_sleep_enable_timer_wakeup(WAKE_INTERVAL_US);
esp_deep_sleep_start();
}
/* `snap.master_dt_ms` here is the time within the current wake (after
* the primer); for energy integration we use `esp_timer_get_time()`
* against `rtc_last_wake_us`. On ESP-IDF v5.x, the value returned by
* `esp_timer_get_time()` **survives deep sleep** — the timer is
* re-derived from the RTC slow-clock on wake. So the delta gives the
* real wake-to-wake interval in microseconds. */
const uint64_t now_us = esp_timer_get_time();
const double dt_s = (double)(now_us - rtc_last_wake_us) / 1e6;
rtc_last_wake_us = now_us;
rtc_total_wh += (double)snap.avg_p[0] * dt_s / 3600.0;
ESP_LOGI(TAG, "wake: P=%.1f W Wh=%.4f dt_s=%.1f",
(double)snap.avg_p[0], rtc_total_wh, dt_s);
publish_via_wifi(snap.avg_p[0], rtc_total_wh, dt_s);
esp_sleep_enable_timer_wakeup(WAKE_INTERVAL_US);
esp_deep_sleep_start();
}
Le projet complet (avec configuration WiFi, publication MQTT, gardes de marqueur magique RTC) — examples/deep_sleep_logger/.
rbamp_begin_resume() (composant 1.7.0 et ultérieur) est la variante d'initialisation sans l'amorçage CMD_LATCH_PERIOD, si bien que rbamp_read_period_snapshot() fonctionne directement après un réveil de veille profonde. Le motif ci-dessus (skip_latch=true + le timer RTC du maître) reste valable sur les anciennes versions du composant.
Budget énergétique (ESP32-WROOM, intervalle de réveil de 10 minutes) :
- Durée d'un cycle actif : ~3 s (Wi-Fi + MQTT + I²C)
- Courant actif : ~80 mA en moyenne → ~0.07 mAh par réveil
- Courant de veille : ~10 µA (RTC + domaines conservés)
- ~10 mAh par jour → une cellule Li-ion de 2000 mAh dure ~6 mois
Scénario 14 — I3 avec un CT différent par canal (surveillance de charges mixtes)
Objectif : un seul module UI3 surveille trois lignes indépendantes sur une phase, avec des niveaux de charge différents :
- Canal 0 — une seule prise (SCT-013-005, ≤5 A) — TV / routeur / veille.
- Canal 1 — la ligne de la cuisine (SCT-013-030, ≤30 A) — bouilloire / micro-ondes.
- Canal 2 — une chaudière de chauffe-eau (SCT-013-020, ≤20 A) — charge de pointe.
Les trois canaux sont alimentés depuis une seule phase (en phase avec le canal U), donc P/PF/Q sont corrects pour les trois — voir la mise en garde sur la tension unique dans 03 · Choix du capteur de courant.
#include "driver/i2c_master.h"
#include "rbamp.h"
#include "esp_log.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
static const char *TAG = "ui3-mixed";
void mixed_load_task(void *arg) {
rbamp_handle_t dev = (rbamp_handle_t)arg;
/* Per-channel configuration — v1.3: order is arbitrary (pure staging) */
rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013);
rbamp_set_ct_model_ch(dev, 2, 6); /* ch2: SCT-013-020 (boiler) */
rbamp_set_ct_model_ch(dev, 1, 3); /* ch1: SCT-013-030 (kitchen) */
rbamp_set_ct_model_ch(dev, 0, 1); /* ch0: SCT-013-005 (outlet) */
while (1) {
float u, i0, i1, i2, p0, p1, p2;
rbamp_read_voltage(dev, 0, &u);
rbamp_read_current(dev, 0, &i0);
rbamp_read_current(dev, 1, &i1);
rbamp_read_current(dev, 2, &i2);
rbamp_read_power(dev, 0, &p0);
rbamp_read_power(dev, 1, &p1);
rbamp_read_power(dev, 2, &p2);
ESP_LOGI(TAG, "U=%.1f V", (double)u);
ESP_LOGI(TAG, " outlet: I=%.3f A P=%.1f W", (double)i0, (double)p0);
ESP_LOGI(TAG, " kitchen: I=%.2f A P=%.1f W", (double)i1, (double)p1);
ESP_LOGI(TAG, " boiler: I=%.2f A P=%.1f W", (double)i2, (double)p2);
ESP_LOGI(TAG, " total: P=%.1f W", (double)(p0 + p1 + p2));
vTaskDelay(pdMS_TO_TICKS(2000));
}
}
Quand l'utiliser : surveiller une seule phase avec trois groupes de charge d'intensités très différentes. L'avantage principal est la résolution — chaque pince correspond à sa plage (une SCT-013-005 donne des mesures précises sur une charge de veille de 50 W, alors qu'une SCT-013-020 ne sature pas sur un chauffe-eau d'environ 4 kW).
Scénario 15 — Sous-comptage : 5×UI1 sur un bus partagé
Objectif : surveiller 5 lignes indépendantes dans un appartement monophasé avec une synchronisation des périodes tarifaires. Un UI1 par ligne (5 modules au total).
C'est la stratégie 1 de synchronisation des périodes de 04 · Câblage : instantané séquentiel + stabilisation partagée.
#define N_METERS 5
static rbamp_handle_t meters[N_METERS]; /* initialized in app_main */
void sub_meter_task(void *arg) {
int64_t period_start_us = esp_timer_get_time();
const int64_t PERIOD_S = 60; /* 60-second metering period */
while (1) {
/* Wait until the end of the period */
int64_t now_us = esp_timer_get_time();
int64_t elapsed_s = (now_us - period_start_us) / 1000000;
if (elapsed_s < PERIOD_S) {
vTaskDelay(pdMS_TO_TICKS((PERIOD_S - elapsed_s) * 1000));
continue;
}
/* Phase 1: sequential snapshot (skew ~5 ms between modules at 50 kHz) */
for (int i = 0; i < N_METERS; i++) {
rbamp_latch_period(meters[i]);
}
/* Phase 2: shared settle */
vTaskDelay(pdMS_TO_TICKS(50));
/* Phase 3: read snapshots with skip_latch=true */
float total_wh_period = 0.0f;
for (int i = 0; i < N_METERS; i++) {
rbamp_period_snapshot_t snap;
if (rbamp_read_period_snapshot(meters[i], &snap, 0, /*skip_latch=*/true) == ESP_OK
&& snap.valid) {
float wh_this_period = snap.avg_p[0] * snap.period_ms / 3600000.0f;
ESP_LOGI("meter", "[%d] avg_p=%.1f W Wh_period=%.2f",
i, (double)snap.avg_p[0], (double)wh_this_period);
total_wh_period += wh_this_period;
}
}
ESP_LOGI("meter", "TOTAL for the period: %.2f Wh\n", (double)total_wh_period);
period_start_us = esp_timer_get_time();
}
}
Analyse du décalage : 5 modules × ~1 ms/instantané = ~5 ms. Par rapport à la période de 60 s = 0.008%. Négligeable.
Budget du bus : 5 modules × ~5 ms de bloc RT = 25 ms pour un tour complet ; cela tient aussi à une cadence d'interrogation de 5 Hz (25 ms ≪ 100 ms). La marge du bus est confortable jusqu'à ~15 modules UI1.
Scénario 16 — Instantané diffusé GC (synchronisation serrée pour plus de 8 modules)
Objectif : à partir de ≥ 8 modules, le décalage de la stratégie 1 (séquentielle) approche ~10 ms. Pour la synchronisation des périodes tarifaires — stratégie 2, diffusion General-Call.
Préconfiguration (une fois par module) :
/* Enable GC reception on each module: the call writes FLEET_CONFIG.bit0,
saves the configuration and restarts the module (~1 s) */
rbamp_enable_gc(dev, true);
Instantané de diffusion en cours d'exécution avec témoin :
#define N_METERS 12
esp_err_t synced_snapshot(i2c_master_bus_handle_t bus,
rbamp_handle_t meters[], int n,
uint16_t tick_counter) {
/* All-call broadcast snapshot (group 0x00): the library builds the
General-Call frame and sends it to address 0x00 on the bus */
esp_err_t err = rbamp_broadcast_latch_group(bus, 0x00, tick_counter, 100);
if (err != ESP_OK) return err;
/* Settle: snapshot + 1 commit-cycle for witness refresh */
vTaskDelay(pdMS_TO_TICKS(50));
/* Witness check: each module echoes the tick of the last GC frame it accepted */
int n_ok = 0;
for (int i = 0; i < n; i++) {
uint16_t tick;
if (rbamp_read_gc_tick(meters[i], &tick) == ESP_OK && tick == tick_counter) {
n_ok++;
} else {
ESP_LOGW("gc-snapshot", "module %d did not take its snapshot (witness mismatch)", i);
}
}
if (n_ok < n) {
ESP_LOGW("gc-snapshot", "fallback to sequential snapshot for %d modules",
n - n_ok);
/* Strategy 1 fallback on the remaining ones */
for (int i = 0; i < n; i++) {
uint16_t tick;
if (rbamp_read_gc_tick(meters[i], &tick) != ESP_OK || tick != tick_counter) {
rbamp_latch_period(meters[i]);
}
}
vTaskDelay(pdMS_TO_TICKS(50));
}
return ESP_OK;
}
Analyse du décalage : une trame GC dure ~1 ms à 50 kHz → les 12 modules prennent leur instantané simultanément au niveau du bus. Le décalage est pratiquement 0.
Quand l'utiliser : ≥ 8 modules et/ou synchronisation serrée.
Quand NE PAS l'utiliser : sur un bus mixte avec des appareils non rbAmp (le GC peut entrer en conflit).
Scénario 17 — Filtrage par groupe GC (comptage multi-locataires)
Objectif : 10 modules sur un seul bus, où vous devez prendre des instantanés de sous-ensembles indépendamment. Par exemple, 5 modules mesurent le tarif A (jour), 5 — le tarif B (nuit) ; ils sont armés et lus selon des calendriers différents.
Mise en place (une fois) :
/* Tariff A — modules 0..4 → group = 1 */
for (int i = 0; i < 5; i++) {
rbamp_set_group_id(meters[i], 1);
rbamp_save_user_config(meters[i]);
}
/* Tariff B — modules 5..9 → group = 2 */
for (int i = 5; i < 10; i++) {
rbamp_set_group_id(meters[i], 2);
rbamp_save_user_config(meters[i]);
}
Exécution — instantané indépendant par tarif :
void daytime_cycle(i2c_master_bus_handle_t bus, uint16_t tick) {
/* Snapshot tariff A only (group 1) */
rbamp_broadcast_latch_group(bus, 1, tick, 100);
vTaskDelay(pdMS_TO_TICKS(50));
/* read the 5 modules of tariff A */
}
void nighttime_cycle(i2c_master_bus_handle_t bus, uint16_t tick) {
/* Snapshot tariff B only (group 2) */
rbamp_broadcast_latch_group(bus, 2, tick, 100);
vTaskDelay(pdMS_TO_TICKS(50));
/* read the 5 modules of tariff B */
}
void all_modules_snapshot(i2c_master_bus_handle_t bus, uint16_t tick) {
/* group = 0x00 — all-call, all 10 take a snapshot */
rbamp_broadcast_latch_group(bus, 0, tick, 100);
}
Avantages : un cycle par tarif = séparation nette des intervalles de comptage. Sans groupes, il faudrait maintenir des boucles d'instantanés séquentielles parallèles avec résolution des conflits.
Scénario 18 — Module STD : puissance réactive, THD et énergie cadencée par le maître
Objectif : lire les grandeurs que seul un module STD mesure — puissance réactive et apparente, THD, facteur de puissance de déplacement — et comptabiliser l'énergie sur une période qui vous est propre. La même API rbamp_* sert les deux gammes de modules ; rbamp_begin() détecte la gamme. Sur un module BASIC, l'exemple affiche une note et revient au comportement quick_read — rien ne plante, les appels STD signalent simplement « non pris en charge ».
Source: examples/std_meter/
rbamp_new(bus, 0x50, &dev);
rbamp_begin(dev); /* detects BASIC / STD */
const bool std = (rbamp_line(dev) == RBAMP_LINE_STD);
if (std) {
rbamp_std_info_t info;
rbamp_std_info(dev, &info);
/* THD and displacement PF are off by default (RAM-only setting;
* reverts at a module reset). */
rbamp_std_set_harmonics(dev, true);
/* Period energy depends on what the module offers. */
if (info.period_source == RBAMP_STD_PERIOD_LATCH) {
/* Snapshot banks: keep bank 0 (the library's) armed, add our own. */
rbamp_std_arm_banks(dev, (1u << 0) | (1u << 1));
rbamp_std_latch(dev, 1); /* primer: the period starts now */
} /* COUNTERS: nothing to arm */
}
while (1) {
rbamp_std_voltage_t v;
rbamp_std_read_voltage(dev, 0, &v); /* U, THD, phase angle */
for (uint8_t ch = 0; ch < rbamp_channels(dev); ++ch) {
rbamp_std_channel_t c;
rbamp_std_read_channel(dev, ch, &c); /* I, P, Q, S, PF, PF1, THD in one burst */
}
rbamp_std_health_t h; /* the frame counter must keep growing */
rbamp_std_read_health(dev, &h);
/* Every PERIOD_MS: */
/* - LATCH module: rbamp_std_latch(dev, 1); wait >= 300 ms;
* rbamp_std_read_latch(dev, 1, <);
* rbamp_std_latch_wh(<, dt_ms, RBAMP_STD_TOTAL, &wh_in, &wh_out);
* - COUNTERS module: rbamp_read_period_snapshot(dev, &ps, 0, false);
* ps.wh_net / ps.avg_p_total / ps.module_restarted */
vTaskDelay(pdMS_TO_TICKS(1000));
}
Notes:
-
dt_msest l'horloge murale du maître entre deux instantanés de la banque — le module n'a pas d'horloge propre pour la période. -
Sur un module à compteurs, il n'y a pas de banque d'instantanés et rien à armer : l'instantané de période de la bibliothèque lit les compteurs persistants et rapporte la différence ;
module_restartedsignale un redémarrage à l'intérieur de la période (la différence reste valide). -
Le masque des banques d'instantanés est en RAM du module. Si une réinitialisation du module l'efface,
rbamp_std_read_latch()réarme la banque et renvoieESP_ERR_INVALID_STATEpour cette seule période — écartez-la et redémarrez votre ancre de dt. -
API complète : 09 · Référence de l'API, chapitre « STD line ».
Tableau récapitulatif des scénarios
| # | LOC | bus I²C | Période ? | DRDY? | MQTT? | Persistance |
|---|---|---|---|---|---|---|
| 1 | ~120 | partagé 3 modules (UI1+I2+I3) | oui (synchronisation GC) | non | oui | RAM (détenue par le maître) |
| 2 | ~50 | dédié (un seul vierge) | non | non | non | flash (save_config=true) |
| 3 | ~60 | dédié (I3) | non | non | non | flash (SAVE_USER_CONFIG) |
| 4 | ~50 | partagé par 3 modules | oui (GC) | non | non | RAM |
| 5 | ~40 | dédié | non | non | non | non |
| 6 | ~60 | partagé avec LCD | oui | non | non | RAM |
| 7 | ~80 | partagé par 3 modules | oui | non | non | RAM |
| 8 | ~70 | dédié | oui | non | oui | retained MQTT |
| 9 | ~50 | dédié | non (RT) | non | non | RAM (détenue par le maître) |
| 10 | ~80 | partagé par 3 modules | oui | non | oui | retained MQTT |
| 11 | ~80 | dédié | non (RT) | oui | non | RAM |
| 12 | ~70 | dédié | oui | non | non | SPIFFS |
| 13 | ~80 | dédié | oui | non | oui | Mémoire RTC + MQTT |
| 14 | ~60 | I3 dédié | non (RT) | non | non | RAM |
| 15 | ~80 | partagé 5×UI1 | oui | non | non | RAM |
| 16 | ~100 | partagé 12 modules | oui (synchronisation GC) | non | non | RAM |
| 17 | ~60 | partagé 10 modules multi-locataires | oui (groupes GC) | non | non | RAM |
| 18 | ~110 | dédié (module STD) | oui (banque d'instantanés ou compteurs) | non | non | RAM (les compteurs de durée de vie résident sur le module) |
Suite
-
07 · Intégrations DIY — Home Assistant / Node-RED / OpenHAB fondés sur ces scénarios (dont
examples/ha_discovery/) -
08 · Intégrations cloud — AWS IoT / Azure / GCP / InfluxDB Cloud
-
09 · Référence API — chaque fonction publique est documentée
-
10 · Dépannage — lorsque les scénarios se comportent différemment sur votre banc
Source et problèmes : rb-amp/rbamp-esp-idf · cette page dans le dépôt : docs/06_examples.md (v1.7.3)