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

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/ build flash monitor. 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/
Remarque

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

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 :

  1. Découvrir — rbamp_fleet_scan trouve tous les modules, vérifie leur identité et écarte les adresses en conflit.

  2. Configurer — rbamp_configure_channels règle la classe de capteur + les modèles de CT par canal + une seule sauvegarde terminale SAVE_USER_CONFIG en un appel par module multicanal.

  3. Armement GC — rbamp_fleet_enable_gc_all active la réception des instantanés General-Call sur chaque module de la flotte.

  4. Boucle — à chaque cycle, le maître exécute un _gclatch atomique (un instantané synchrone sur toute la flotte), contrôle _check_sync, lit _poll_all, intègre l'énergie sur master_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

C
#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)

Text
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)
Remarque

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 seul poll_all lit toute la flotte → agrégation. Aucune dérive entre modules due à une chaîne d'allers-retours séquentiels.

  • Comportement de total_power dans une flotte hétérogène. UI1 fournit la puissance active (il a une tension → il a P) ; les I2/I3 ne mesurent que le courant, donc leur contribution à total_power est 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_total croî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 par master_dt_ms (esp_timer), non par latch_ms côté puce (une minuterie de diagnostic du module qui peut lire court). Un tick parasite ajoute 0 Wh si 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_all le signale avec status[i] != ESP_OK et 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/3 sans blocage. Il en va de même pour check_sync — missed_idx pointe 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 a has_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 — moyenne 112.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). Un fleet_poll_all groupé 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.

C
#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) :

Text
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.

C
#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) :

Text
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.

Codes de modèle de CT valides.

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).

C
#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Ω) :

Text
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 donne skew = 0 d'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.

C
#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.

C
#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).

Remarque

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.

C
#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.

C
#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.

C
#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.

C
#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.

C
#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.

Remarque

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.

C
#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.

Sécurité

⚠ 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).

C
#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/.

Sécurité

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.

C
#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.

C
#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) :

C
/* 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 :

C
#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) :

C
/* 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 :

C
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/

C
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_ms est 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_restarted signale 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 renvoie ESP_ERR_INVALID_STATE pour 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


Source et problèmes : rb-amp/rbamp-esp-idf · cette page dans le dépôt : docs/06_examples.md (v1.7.3)