rbAmp
DE
Shop
Docs
Aktualisiert · Auf GitHub bearbeiten [Edit on GitHub]

06 · Beispiele

Dieses Kapitel beginnt mit den Vorzeigeszenarien — den realen Einsatzmustern, für die die Bibliothek entworfen wurde (Netz + N Teillasten an einem Bus, GC-synchronisierte Snapshots). Es folgen Einzelmodul-Szenarien — vom minimalen „Hallo Welt“ bis zum batteriebetriebenen Deep-Sleep-Logger.

Die meisten Szenarien liegen als sofort baubares IDF-Projekt in examples/, das Sie mit idf.py -C examples/ build flash monitor bauen können. Der Code in diesem Kapitel ist eine Destillation der Kernlogik, nicht das vollständige Projekt (bus_cfg / WiFi-Inbetriebnahme / Kconfig sind der Kürze halber weggelassen).

# Szenario Schwierigkeit Quelle
1 Netz + N Unterlasten — der 80-%-Kanon mittel examples/fleet_sync/
2 Bereitstellungsablauf (neu → Flotte) niedrig (composition)
3 Mehrkanal mit gemischten CTs (I3, verschiedene Modelle) mittel (composition)
4 Fleet-GC-Synchronisation — Synchronität der Tarifperioden mittel examples/fleet_sync/
5 Schnelllesung (einzelnes Modul) minimal examples/quick_read/
6 Wh-Zähler auf einem 16×2-LCD niedrig examples/lcd_period/
7 Überwachung von 3 Modulen (klassisch sequenziell) niedrig examples/multi_module/
8 MQTT pro Kanal mittel examples/mqtt_publisher/
9 Bidirektionale Messung auf der Masterseite mittel (composition)
10 Gesamte Energiebilanz im Haus (3 Module) hoch (composition)
11 Ereignisbasiertes Logging (EMA) mittel (composition)
12 Lokaler CSV-Logger auf SPIFFS mittel examples/spiffs_logger/
13 Batterie-Datenlogger mit Deep-Sleep mittel examples/deep_sleep_logger/
14 I3 mit unterschiedlicher CT je Kanal (Vertiefung zu gemischten Lasten) mittel (composition)
15 Unterzähler: 5×UI1 an einem gemeinsamen Bus hoch (composition)
16 GC-Broadcast-Snapshot für mehr als 8 Module hoch (composition)
17 GC-Gruppenfilterung (Mehrmandanten-Messung) hoch (composition)
18 STD-Modul: Blind- / Scheinleistung, THD, master-zeitgesteuerte Energie mittel examples/std_meter/
Hinweis

Szenario 18 zeigt die Modulreihe STD. Die Szenarien 1–4 sind die Leitszenarien, die um die kanonische Bereitstellung der Bibliothek herum aufgebaut sind. Ihr Code verwendet die Fleet-API und ist am Bench-Aufbau validiert (eine heterogene Flotte aus UI1+I2+I3). Die Szenarien 5–13 sind Einzelmodul- und Kombinationsmuster; 14–17 sind erweiterte Fleet-Szenarien (eine Vertiefung der in 1–4 eingeführten Funktionen). Szenario 7 ist der ältere sequenzielle Snapshot pro Modul ohne Fleet-API, behalten zum Vergleich und als Migrationspfad.

Alle Szenarien setzen voraus, dass Sensorklasse und CT-Modell bereits über rbamp_set_sensor_class() + rbamp_set_ct_model() konfiguriert sind (siehe 05 · Schnellstart, Schritt 3). Das geschieht einmal bei der Installation — die Einstellungen werden im Flash des Moduls gespeichert und überstehen einen Reset.

Zusätzliche REQUIRES für main/CMakeLists.txt

Die Basiskomponente zieht esp_driver_i2c, esp_timer und log mit. Einige Szenarien benötigen zusätzliche ESP-IDF-Komponenten — ergänzen Sie sie im REQUIRES Ihres main/:

Szenario Zusätzliche REQUIRES
1 — Netz + N Teillasten (Fleet) — (nur rbamp)
2 — Bereitstellungsablauf —
3 — Mehrkanal mit gemischter CT (I3) —
4 — Flotten-GC-Synchronisation —
5 — Schnelllesung —
6 — Wh-Zähler auf LCD rbamp (der LCD-Treiber ist eine separate Komponente Ihrer Wahl)
7 — Multi-Modul (klassisch sequenziell) —
8 — MQTT pro Kanal rbamp mqtt esp_wifi esp_event esp_netif nvs_flash
9 — Bidirektionale Messung —
10 — Energiebilanz —
11 — Ereignisbasiertes Logging —
12 — SPIFFS-Logger rbamp spiffs
13 — Deep-Sleep-Logger rbamp esp_sleep esp_wifi esp_event esp_netif nvs_flash mqtt (falls Sie veröffentlichen)
18 — STD-Zähler — (nur rbamp)

Die Netzwerkkomponenten benötigen außerdem nvs_flash_init() in app_main und die WLAN-Einrichtung. Der Kürze halber ist all das in den folgenden Ausschnitten weggelassen; das vollständige Projekt liegt immer in examples//.

Hinweis

Wichtiger Hinweis zu den folgenden Ausschnitten. Jeder Ausschnitt ist eine Destillation der Kernlogik, kein vollständiges app_main. Im lauffähigen Code steht vor der Zeile rbamp_handle_t dev immer i2c_master_bus_config_t bus_cfg = {...}; i2c_new_master_bus(&bus_cfg, &bus); rbamp_new(bus, 0x50, &dev); rbamp_begin(dev); (für ein einzelnes Modul) oder rbamp_fleet_create(bus, &fleet); rbamp_fleet_scan(fleet, true, &n); (für die Fleet). Ist die Arbeit erledigt, folgen rbamp_del(dev) / rbamp_fleet_destroy(fleet) (weggelassen, wo app_main in eine Endlosschleife geht — das Handle lebt, bis der Chip neu startet).


Szenario 1 — Netz + N Teillasten (der 80-%-Kanon): integriertes Messsystem

Ziel: das kanonische Einsatzszenario der Bibliothek — ein kohärentes Messsystem über eine heterogene Flotte, in einer einzigen Schleife geschlossen:

  1. Erkennen — rbamp_fleet_scan findet alle Module, prüft ihre Identität und schließt kollidierende Adressen aus.

  2. Konfigurieren — rbamp_configure_channels setzt die Sensorklasse + CT-Modelle pro Kanal + ein einziges abschließendes SAVE_USER_CONFIG in einem Aufruf pro Mehrkanal-Modul.

  3. GC-Scharfstellung — rbamp_fleet_enable_gc_all aktiviert den Empfang von General-Call-Snapshots auf jedem Modul der Flotte.

  4. Schleife — bei jedem Takt führt der Master ein atomares _gclatch aus (ein synchroner Snapshot über die gesamte Flotte), prüft mit _check_sync quer, liest _poll_all, integriert die Energie über master_dt und berechnet _total_power + _total_energy_wh.

Dies ist das Hauptbeispiel des Kapitels — es zeigt die gesamte Bibliothek in Aktion in der kanonischen Konfiguration. Jedes andere Szenario (2–17) zerlegt diesen Ablauf in einzelne Bausteine oder ergänzt ihn um Drittanbieter-Integrationen (LCD, MQTT, SD).

Hardware (HW-validiert): eine heterogene Flotte aus 3 Modulen an einem einzigen Bus mit einem externen 4.7-kΩ-Pull-up an SDA/SCL (siehe 04 · Verdrahtung, Abschnitt „Multi-Modul-Bus — die primäre Topologie“):

  • @0x50 — UI1, Netzzähler am Hausanschluss (ein Stromkanal + Spannung).
  • @0x51 — I2, ein Zweikanal-Stromteilzähler (ohne Spannung).
  • @0x52 — I3, ein dreikanaliger Strom-Unterzähler (ohne Spannung).

Die Referenzlast auf der Leitung beträgt ~0.57 A.

Code — integrierte Schleife

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 */
    }
}

Bench-Ausgabe (an der gesamten Flotte hardwarevalidiert)

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

Die Messwerte vom Bench zeigen die Form der Daten und ihren Fluss durch das System — nicht die Messgenauigkeit.

Hinweise zum Einsatz

  • Eine synchronisierte Schleife ist das ganze System. Jeder Takt: ein gclatch (eine einzige I²C-General-Call-Transaktion) → alle Module starten atomar ihren Periodensnapshot (check_sync = 3/3, Schiefe = 0) → ein poll_all liest die gesamte Flotte → Aggregation. Keine Drift zwischen den Modulen aus einer Kette sequenzieller Round-Trips.

  • Verhalten von total_power in einer heterogenen Flotte. Die UI1 liefert Wirkleistung (sie hat Spannung → sie hat P); I2/I3 messen nur Strom, daher ist ihr Beitrag zu total_power null. Im Kanon entspricht total_power daher ungefähr der Leistung des Netzmoduls. Für die Leistung je Last an einem Teilzähler berechnen Sie sie auf der Master-Seite: P_subload[k] ≈ V_mains × I_sub[k] (eine Näherung, korrekt, wenn die Leistungsfaktoren nahe beieinanderliegen; ein reiner Stromteilzähler kann die Wirkleistung je Last nicht exakt angeben).

  • Energie (Wh) — Master-Wanduhr. E_total wächst monoton (2.55 → 6.94 Wh im Messfenster am Bench). Die Komponente integriert jede Periode über master_dt_ms (esp_timer), nicht über das chipseitige latch_ms (ein Modul-Diagnosetimer, der unter Last zu kurz gemeldet werden kann). Ein fehlerhafter Tick addiert 0 Wh, wenn zwischen zwei Abfragen keine neue Periode verstrichen ist — das ist normal (snap.valid = 0 in diesem Zyklus).

  • MISS-resilientes Polling. Fällt eines der Module vom Bus (Trennung, Neustart), markiert poll_all es mit status[i] != ESP_OK und fährt fort, die übrigen abzufragen — der Master hängt nicht. Am Bench geprüft: Ein Modul, das mitten im Lauf getrennt wurde, ließ die Fleet mit n_ok=2/3 weiter abfragen, ohne Stillstand. Dasselbe gilt für check_sync — missed_idx zeigt auf das erste nicht synchrone Modul, während die übrigen weiter Snapshots nehmen.

  • Bilanzanalyse. Im 80-%-Kanon: balance = P_mains − Σ(V_mains × I_sub[k]) — eine Schätzung von „dem Rest“ (Grundverbrauch, nicht erfasste Lasten). Der Zielcode durchläuft die Flotte und trennt das Netz-Handle (dasjenige mit has_voltage = true) von den Teil-Handles (allen übrigen).

  • Stromwerte je Kanal → Lastaufteilung. Über fleet_poll_all sieht der Master alle Stromkanäle auf einmal (1+2+3 = 6 an unserer Testflotte), ohne separate Leser pro Modul.

  • Gemischte CTs an einem 3-Kanal-Modul. Verwenden Sie die aktuelle Bibliotheksversion; Spiegel [1 2 3] auf I3 stellen sich wie konfiguriert ein. Die Reihenfolge, in der die Kanäle gebunden werden, spielt keine Rolle.

  • Abfragelatenz für die Produktionsdimensionierung (am Gerät gemessen). Am Bench bei 50 kHz I²C: 2 Module — Mittel 89.4 ms (min 89.4 / max 89.6); 3 Module — Mittel 112.1 ms (min 112.1 / max 112.3). Das sind ≈ 22–23 ms je zusätzlichem Modul, linear und mit sehr geringem Jitter (min ≈ max). Ein einzelner gebündelter fleet_poll_all ist auf einem sauberen Bus deterministisch. Eine 3-Modul-Fleet (~112 ms) passt in ein Abfrageintervall von 200 ms — das heißt, eine Abfragerate von 5 Hz ist erreichbar (jedes zweite 100-ms-Modulfenster), ohne den Bus zu sättigen. Das vollständige Bus-Budget (wenn die Fleet das Abfrageintervall übersteigt) steht in der Tabelle in 04 · Verdrahtung, Abschnitt „Bus energy budget“.


Szenario 2 — Provisionierungsablauf (jungfräulich → Flotte)

Ziel: ein neues Modul von seiner Werksadresse 0x50 auf eine Arbeitsadresse verlegen und einer bestehenden Flotte hinzufügen, wobei die Konfiguration (CT-Modelle, Label) im Flash gespeichert wird.

Hardware (HW-validiert): ein jungfräuliches Modul auf der Werksadresse 0x50 (HW_VARIANT 3-Kanal). Die Provisionierung verschiebt es auf die Adresse 0x52 und speichert die Konfiguration im 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);
}

Ausgabe am Bench (hardwarevalidierter Erfolgspfad):

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 liefert nach einem erfolgreichen Aufruf true. Bei einem frisch ab Werk gelieferten Modul (das noch nichts berührt hat) ist das vorherige is_provisioned false — dies ist der normale Zustand 0xFB (ERR_FLASH_PARAMS_BAD), beschrieben in 10 · Fehlerbehebung, und nicht fatal.

Fehlerpfade

Fehler Bedingung Wiederherstellung
ESP_ERR_NOT_FOUND Niemand antwortet auf 0x50 Prüfen, dass das neue Modul physisch angeschlossen und versorgt ist (VCC); Bus-Scan (10 · Fehlerbehebung).
ESP_ERR_INVALID_STATE Ein Konflikt wurde bei 0x50 oder desired_addr erkannt; verschiedene Module antworten identisch Verstoß gegen die Disziplin — mehr als ein jungfräuliches Modul am Bus. Stromlos schalten + alle außer einem physisch trennen + erneut versuchen (siehe den Wiederherstellungspfad in 10 · Fehlerbehebung).
ESP_ERR_TIMEOUT Der zweiphasige Commit ist durchgelaufen, aber das Modul erschien innerhalb des Bootfensters nicht unter der neuen Adresse Das Modul stromlos schalten, erneut versuchen. Bleibt es bestehen — Flash-Zyklus-Problem.
ESP_ERR_INVALID_ARG desired_addr außerhalb von 0x08..0x77 Verwenden Sie eine gültige 7-Bit-Adresse.

Eine ausführliche Tour durch die Fehlermodi: 10 · Fehlerbehebung, Abschnitt „Flotte: rbamp_provision hat einen Fehler zurückgegeben“.


Szenario 3 — Mehrkanal mit gemischter CT (I3, unterschiedliche Modelle je Kanal)

Ziel: rbamp_configure_channels auf einem I3 vorführen — drei Kanäle mit unterschiedlichen CT-Modellen (z. B. ch0=SCT-013-005 für eine kleine Last, ch1=SCT-013-030 für eine mittlere, ch2=SCT-013-020 für eine große) mit einem einzigen abschließenden Flash-Zyklus (flash-schonend) und Bestätigung der Persistenz über einen Neustart.

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);
}

Bench-Ausgabe (hardwarevalidiert an einem sauber neu geflashten I3):

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)

Die Eigenschaft „einmaliges Speichern“ — warum sie zählt

configure_channels führt am Ende einen Schreibvorgang CMD_SAVE_USER_CONFIG aus. Die Alternative — separate set_ct_model_ch-Aufrufe für jeden Kanal, jeweils mit eigenem save_user_config danach — verursacht drei Flash-Lösch- und Schreibzyklen.

Latenzvergleich am Prüfstand (am selben I3):

Vorgehen Latenz Flash-Zyklen
configure_channels(...) — 1 Schreibvorgang im Endlager SAVE ~1403 ms 1
3× (set_ct_model_ch + save_user_config) ~3492 ms 3

3× langsamer — das ist (~2.5×) × ~700 ms. Entscheidend ist der 3× höhere Verschleiß auf derselben Flash-Seite: Bei der typischen Neukonfiguration von Modulen im Feld entsteht daraus ein spürbarer Verschleißaufwand. Verwenden Sie für die Sensorklasse und die CT-Modelle pro Kanal immer configure_channels.

Gültige CT-Modellcodes.

Für die SCT-013-Familie: 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. Ein Code außerhalb von {1, 2, 3, 4, 5, 6, 7} ergibt ESP_ERR_INVALID_ARG / REG_ERROR=0xFE (ERR_PARAM).


Szenario 4 — Flotten-GC-Sync (synchrone Tarifperioden)

Ziel: einen atomaren Snapshot über die gesamte Flotte mit einem einzigen I²C-General-Call-Rahmen demonstrieren. Anders als beim sequenziellen CMD_LATCH_PERIOD je Modul (wo sich die Schiefe bei jedem Round-Trip aufsummiert) synchronisiert GC alle Module in einer einzigen Bustransaktion.

Hardware: dieselbe heterogene Fleet aus 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));
    }
}

Bench-Ausgabe (10 Runden an der Flotte UI1+I2+I3, 4.7-kΩ-Pull-up):

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

Wann GC-Synchronisation zu verwenden ist:

  • Enge Synchronisation. Wenn der Unterschied der Snapshots je Minute oder Sekunde zwischen den Modulen für die Berichterstattung zählt (etwa eine Bilanz Netz − Σ(Teil), über die Zeit integriert — ein Versatz der Module erzeugt einen systematischen Fehler), liefert GC skew = 0 nach Bench-Messung. Ein sequenzieller Snapshot je Modul an denselben 3 Modulen summiert 100–300 µs je Modul × N, was über ein 60-Minuten-Fenster bei punktgenauen Analysen spürbar wird.

  • Große Flotte. Mit wachsender Anzahl der Module wächst der Unterschied zwischen „sequenziell N × Round-Trip“ und „einem einzigen GC-Rahmen“ linear.

  • Synchronisation über Installationen hinweg. Wenn Sie mehrere ESP32 an verschiedenen Bussen mit einer gemeinsamen Master-Uhr haben, lässt sich der GC-Tick über die Wanduhr des Masters synchronisieren — dann werden Snapshots von verschiedenen Bussen innerhalb eines einzigen Round-Trip-Fensters im Netz aufeinander ausgerichtet.

Nachweis über check_sync: eine Prüfung, dass alle Module den GC-Frame tatsächlich erhalten haben. Sie kann ein Modul übersehen, wenn es im Moment des Frames noch startete oder in einem SAVE-Zyklus war — missed_idx zeigt auf das erste nicht synchrone. Bei der Bench-Validierung: 10 Runden hintereinander — 0 Fehlzugriffe.

Vorbedingung. GC muss auf jedem Modul aktiviert sein (rbamp_fleet_enable_gc_all oder pro Gerät rbamp_enable_gc + SAVE_USER_CONFIG + Reset). Ein neues Modul mit Werkseinstellungen akzeptiert GC nicht — das ist Absicht, als Schutz vor versehentlichen Broadcasts an einem Inbetriebnahme-Bus.


Szenario 5 — Schnelllesung (einzelnes Modul)

Ziel: U / I / P / PF / Frequenz einmal pro Sekunde in das ESP-IDF-Log ausgeben. Das gleiche „Hallo Welt“ wie in 05 · Schnellstart, aber über rbamp_read_all() — ein einmaliges Lesen des gesamten RT-Blocks in eine Struktur.

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));
    }
}

Was auf dem Bus passiert: rbamp_read_all() auf einem UI3 führt ~53 Einzelbyte-Transaktionen aus (13 Float-Werte × 4 Bytes + 1 Frequenzbyte). Bei 50 kHz mit Retry-Reserve — in der Größenordnung von 25–30 ms. Wenn Sie nicht alle Werte brauchen, rufen Sie die Eigenschaftsfunktionen auf (rbamp_read_voltage(), rbamp_read_current(ch)) — weniger Bytes auf dem Bus.


Szenario 6 — Wh-Zähler auf einem 16×2-LCD

Ziel: ein Wh-Zähler, einmal pro Minute aktualisiert, auf einem 16×2-Zeichen-LCD mit einem PCF8574-I²C-Expander (HD44780-kompatibel). Das LCD hängt am selben I²C-Bus wie das rbAmp. Der zentrale Mechanismus der Komponente ist rbamp_read_period_snapshot(), der Snapshot + Einschwingen + Gültigkeitsprüfung + Lesen + Wh-Takt in einem einzigen Aufruf kapselt.

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);
    }
}

Das vollständige IDF-Projekt — examples/lcd_period/.

Umgang mit veralteten Snapshots. rbamp_read_period_snapshot() liefert ESP_ERR_INVALID_RESPONSE, wenn das Modul bis zum Lesezeitpunkt keinen neuen Snapshot vorbereiten konnte. Die Komponente erfasst trotzdem intern ihren Zeitstempel (esp_timer_get_time()) — damit wird der nächste erfolgreiche Snapshot im Intervall nicht doppelt gezählt.


Szenario 7 — Überwachung von 3 Modulen (älter, sequenziell) an einem Bus

Ziel: 3 Module auf den Adressen 0x50 / 0x51 / 0x52 von einem Master aus abfragen. Jedes Modul braucht eine eindeutige Adresse (Adressen werden beim Werks- bzw. Integratoreinbau vergeben — siehe 09 · API-Referenz zu den Methoden zur Adressänderung mit ihren WARNING-Hinweisen).

Hinweis

Das kanonische Muster für Firmware v1 ist ein sequenzielles rbamp_latch_period() an jedem Gerät + ein gemeinsames 50-ms-Abklingen + je Gerät rbamp_read_period_snapshot(skip_latch=true). Der Versatz zwischen Geräten bei 100 kHz: ~1 ms je Gerät — vernachlässigbar gegenüber einer 60-Sekunden-Periode.

Auf Firmware v1.3 (REG_VERSION = 0x04) wird rbamp_broadcast_latch() vollständig unterstützt, sobald GC flottenweit über rbamp_fleet_enable_gc_all() aktiviert ist — der kanonische Flotten-Sync-Pfad für enge Synchronisation zwischen den Teilzählern (siehe den Abschnitt zur GC-Flotte mit Strategie 2 weiter oben in diesem Kapitel). Auf älterer Firmware v1.0–v1.2 (ohne General-Call-Snapshot-Unterstützung) liefert der Aufruf ESP_ERR_NOT_SUPPORTED, und die Bibliothek fällt auf den oben gezeigten Snapshot je Gerät zurück. Siehe 09 · API-Referenz für Details.

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));
        }
    }
}

Das vollständige Projekt (mit Bus-Scan-Probe und Fehlermeldung) — examples/multi_module/.


Szenario 8 — MQTT je Kanal

Ziel: ein UI3-Modul mit 3 CT-Zangen auf drei unabhängigen Leitungen. Wh-Zähler je Kanal, einmal pro Minute über MQTT veröffentlicht. Zeigt, dass rbamp_energy_wh(dev, ch) auf jedem Kanal unabhängig funktioniert — kein manuelles Array total_wh[3] auf der Masterseite nötig.

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));
        }
    }
}

Das vollständige Projekt — examples/mqtt_publisher/. Für HA MQTT Auto-Discovery auf Basis dieses Musters — siehe 07 · DIY-Integrationen + examples/ha_discovery/.


Szenario 9 — Bidirektionale Messung auf der Masterseite

Ziel: die vorzeichenbehaftete Momentanleistung in Bezugsleistung und Einspeiseleistung aufteilen. Verwenden Sie dieses Muster auf der BASIC-Stufe, wo die Firmware negative Werte in snap.avg_p[ch] (periodengemittelte Leistung) abschneidet — fragen Sie rbamp_read_power(dev, 0, &p) (Momentanleistung, auf allen Stufen vorzeichenbehaftet) mit 10 Hz auf der Master-Seite ab und sortieren Sie die Werte selbst in Klassen ein.

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);
        }
    }
}

Dies ist ein zusammengesetztes Szenario ohne eigenes IDF-Projekt. Bei einem STD-Modul sind die Energiezähler vorzeichenbehaftet, und rbamp_energy_wh(dev, 0) liefert eine Nettobilanz (Bezug und Einspeisung werden getrennt in rbamp_std_read_energy() geführt) — diese Aufteilung auf dem Master ist nur bei BASIC-Modulen nötig oder für getrennte Berichte über Gesamtbezug / Gesamteinspeisung aus der Echtzeitleistung.


Szenario 10 — Gesamte Energiebilanz im Haus

Ziel: 3 Module — Netz (bidirektional), Solar (nur Erzeugung), Lasten (UI3 für Geräte einzeln). Das kombinierte Dashboard wird einmal pro Minute veröffentlicht.

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);
    }
}

Für eine explizite Aufteilung von Gesamtbezug / Gesamteinspeisung am Netz — kombinieren Sie das Muster aus Szenario 5 (eine separate 10-Hz-Task auf rbamp_read_power(mains_dev, 0, ...)).

Dies ist ein zusammengesetztes Szenario ohne eigenes IDF-Projekt — stellen Sie es aus examples/mqtt_publisher/ + examples/multi_module/ zusammen.


Szenario 11 — Ereignisbasierte Protokollierung (EMA)

Ziel: Bei jedem 100-ms-Echtzeitfenster die Momentanleistung mit einem exponentiellen gleitenden Mittelwert vergleichen. Signifikante Abweichungen protokollieren — Lasten wie eine Mikrowelle, ein Wasserkocher oder ein Haartrockner erscheinen im Log als Ein- / Ausschaltereignis.

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);
        }
    }
}

Ein zusammengesetztes Szenario — kein eigenes IDF-Projekt. Kombinieren Sie es mit dem MQTT-Publizieren aus Szenario 4 für Automatisierungen auf Seiten von HA, oder schreiben Sie die Ereignisse mit dem Muster aus Szenario 8 in SPIFFS für ein Offline-Protokoll.


Szenario 12 — Lokaler CSV-Logger auf SPIFFS

Ziel: einmal pro Minute einen Periodensnapshot als CSV-Datei auf SPIFFS schreiben. Nützlich für eigenständige Installationen ohne WLAN / MQTT oder als Puffer für eine verzögerte Cloud-Synchronisation.

Hinweis

Benötigt eine eigene Partitionstabelle mit dem Eintrag storage,data,spiffs,,128K, in partitions.csv. Ein Beispiel liegt in 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);
    }
}

Das vollständige Projekt — examples/spiffs_logger/. Der obige Ausschnitt ist eine didaktische Vereinfachung mit einer CSV-Zeile mit 4 Spalten. Das Beispiel selbst schreibt eine CSV-Zeile mit 9 Spalten mit avg_p und Wh je Kanal für alle 3 Kanäle — nützlicher für Produktionsszenarien auf UI3-Modulen.

Für verzögerte Cloud-Synchronisation (lokal protokollieren, einmal pro Stunde senden) — siehe den Abschnitt „Hybrid: lokale Speicherung + Synchronisation“ in 08 · Cloud-Integrationen.


Szenario 13 — Batterie-Datenlogger mit Deep-Sleep

Ziel: ein ESP32 wacht alle 10 Minuten auf, nimmt einen einzelnen Periodensnapshot, veröffentlicht per WiFi+MQTT und geht zurück in den Deep-Sleep. Die Energie bleibt über den RTC-Speicher zwischen den Schlafzyklen erhalten. Der Akkumulator der Komponente ist deaktiviert — die Wh-Speicherung übernimmt der Master selbst.

Sicherheit

⚠ Wichtiger Hinweis zum Deep-Sleep. Auf der aktuellen Firmware gibt rbamp_begin() immer einen CMD_LATCH_PERIOD-Primer aus, der den Periodenakkumulator der Firmware zurücksetzt. Das heißt: Nach dem Aufwachen aus dem Deep-Sleep können Sie rbamp_read_period_snapshot() nicht einfach standardmäßig aufrufen — dieser Aufruf würde einen weiteren Snapshot nehmen und ~50 ms nach dem Primer nahezu null-Daten liefern. Das korrekte Muster unten verwendet skip_latch=true, um die während des Schlafintervalls akkumulierten Daten zu lesen, und den eigenen RTC-Timer des Masters für das Intervall zwischen den Aufwachvorgängen (das Feld snap.master_dt_ms spiegelt nur die Zeit innerhalb des aktuellen Aufwachzyklus, nicht vom Aufwachen zum Aufwachen).

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();
}

Das vollständige Projekt (mit WiFi-Einrichtung, MQTT-Publikation, RTC-Magic-Marker-Schutz) — examples/deep_sleep_logger/.

Sicherheit

rbamp_begin_resume() (Komponente 1.7.0 und neuer) ist die Init-Variante ohne den CMD_LATCH_PERIOD-Primer, sodass rbamp_read_period_snapshot() direkt nach dem Aufwachen aus dem Deep-Sleep funktioniert. Das Muster oben (skip_latch=true + der RTC-Timer des Masters) bleibt auf älteren Komponentenversionen gültig.

Energiebudget (ESP32-WROOM, 10-Minuten-Aufwachintervall):

  • Dauer eines aktiven Zyklus: ~3 s (WiFi + MQTT + I²C)
  • Aktiver Strom: ~80 mA im Mittel → ~0.07 mAh pro Aufwachen
  • Ruhestrom: ca. 10 µA (RTC + erhaltene Domänen)
  • ~10 mAh pro Tag → eine 2000-mAh-Li-Ion hält ~6 Monate

Szenario 14 — I3 mit unterschiedlicher CT je Kanal (Überwachung gemischter Lasten)

Ziel: ein einzelnes UI3-Modul überwacht drei unabhängige Leitungen an einer Phase mit unterschiedlichen Lastniveaus:

  • Kanal 0 — eine einzelne Steckdose (SCT-013-005, ≤5 A) — TV / Router / Standby.
  • Kanal 1 — die Küchenleitung (SCT-013-030, ≤30 A) — Wasserkocher / Mikrowelle.
  • Kanal 2 — ein Warmwasserboiler (SCT-013-020, ≤20 A) — Spitzenlast.

Alle drei Kanäle werden aus einer einzigen Phase gespeist (in Phase mit dem U-Kanal), daher sind P/PF/Q für alle drei korrekt — siehe den Hinweis zur Einzelspannung in 03 · Auswahl des Stromsensors.

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));
    }
}

Wann verwenden: Überwachung einer einzelnen Phase mit drei Lastgruppen unterschiedlicher Stromstärke. Der Hauptvorteil ist die Auflösung — jede Zange passt zu ihrem Bereich (eine SCT-013-005 liefert genaue Werte bei einer 50-W-Standby-Last, während eine SCT-013-020 bei einem ~4-kW-Warmwasserboiler nicht übersteuert).


Szenario 15 — Unterzählung: 5×UI1 an einem gemeinsamen Bus

Ziel: 5 unabhängige Leitungen in einer einphasigen Wohnung mit synchronen Tarifperioden überwachen. Eine UI1 je Leitung (insgesamt 5 Module).

Dies ist Strategie 1 für die Periodensynchronisation aus 04 · Verdrahtung: sequenzieller Snapshot + gemeinsames Einschwingen.

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();
    }
}

Schiefe-Analyse: 5 Module × ~1 ms/Snapshot = ~5 ms. Im Verhältnis zur 60-s-Periode = 0.008 %. Vernachlässigbar.

Busbudget: 5 Module × ~5 ms RT-Block = 25 ms für eine vollständige Runde; das passt auch zu 5 Hz Abfrage (25 ms ≪ 100 ms). Der Busspielraum reicht bis etwa 15 UI1-Module komfortabel.


Szenario 16 — GC-Broadcast-Snapshot (enge Synchronisation für >8 Module)

Ziel: ab ≥ 8 Modulen nähert sich die Schiefe von Strategie 1 (sequenziell) ~10 ms. Für die Synchronität der Tarifperioden — Strategie 2, General-Call-Broadcast.

Vorkonfiguration (einmal pro Modul):

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

Laufzeit-Broadcast-Snapshot mit Zeugenprüfung:

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;
}

Schiefe-Analyse: Ein GC-Rahmen dauert ~1 ms bei 50 kHz → alle 12 Module nehmen ihren Snapshot gleichzeitig auf Busebene. Die Schiefe ist praktisch 0.

Wann zu verwenden: ≥ 8 Module und/oder enge Synchronisation.

Wann NICHT verwenden: an einem gemischten Bus mit Geräten, die nicht von rbAmp stammen (GC kann Konflikte verursachen).


Szenario 17 — GC-Gruppenfilterung (Mehrmieter-Abrechnung)

Ziel: 10 Module an einem einzigen Bus, bei denen Sie Snapshots von Teilmengen unabhängig voneinander nehmen müssen. Zum Beispiel messen 5 Module Tarif A (Tag), 5 — Tarif B (Nacht); sie werden nach unterschiedlichen Zeitplänen scharf geschaltet und gelesen.

Einrichtung (einmalig):

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]);
}

Laufzeit — unabhängiger Snapshot je 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);
}

Nutzen: ein Zyklus pro Tarif = saubere Trennung der Messintervalle. Ohne Gruppen müssten Sie parallele sequenzielle Snapshot-Schleifen mit Konfliktauflösung pflegen.


Szenario 18 — STD-Modul: Blindleistung, THD und master-zeitgesteuerte Energie

Ziel: die Größen lesen, die nur ein STD-Modul misst — Blind- und Scheinleistung, THD, Verschiebungs-Leistungsfaktor — und die Energie über einen eigenen Zeitraum abrechnen. Dieselbe rbamp_*-API bedient beide Modulstufen; rbamp_begin() erkennt die Stufe. Auf einem BASIC-Modul gibt das Beispiel einen Hinweis aus und fällt auf das Verhalten von quick_read zurück — nichts schlägt fehl, die STD-Aufrufe melden einfach „nicht unterstützt“.

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 ist die Master-Wanduhr zwischen zwei Snapshots der Bank — das Modul hat für die Periode keine eigene Uhr.

  • Bei einem Zählermodul gibt es keine Snapshot-Bank und nichts scharf zu schalten: Der Periodensnapshot der Bibliothek liest die gespeicherten Zähler und meldet die Differenz; module_restarted markiert einen Neustart innerhalb der Periode (die Differenz bleibt gültig).

  • Die Maske der Snapshot-Bank liegt im RAM des Moduls. Löscht ein Reset des Moduls sie, scharf schaltet rbamp_std_read_latch() die Bank neu und liefert für diese eine Periode ESP_ERR_INVALID_STATE — verwerfen Sie sie und starten Sie Ihren dt-Anker neu.

  • Vollständige API: 09 · API-Referenz, Kapitel „STD line“.


Übersichtstabelle der Szenarien

# LOC I²C-Bus Periode? DRDY? MQTT? Persistenz
1 ~120 gemeinsam 3 Module (UI1+I2+I3) ja (GC-Sync) nein ja RAM (vom Master verwaltet)
2 ~50 dediziert (ein neues Modul) nein nein nein Flash (save_config=true)
3 ~60 dediziert (I3) nein nein nein Flash (SAVE_USER_CONFIG)
4 ~50 gemeinsam 3 Module ja (GC) nein nein RAM
5 ~40 dediziert nein nein nein nein
6 ~60 gemeinsam mit LCD ja nein nein RAM
7 ~80 gemeinsam 3 Module ja nein nein RAM
8 ~70 dediziert ja nein ja retained MQTT
9 ~50 dediziert nein (RT) nein nein RAM (vom Master verwaltet)
10 ~80 gemeinsam 3 Module ja nein ja retained MQTT
11 ~80 dediziert nein (RT) ja nein RAM
12 ~70 dediziert ja nein nein SPIFFS
13 ~80 dediziert ja nein ja RTC-Speicher + MQTT
14 ~60 dediziert I3 nein (RT) nein nein RAM
15 ~80 geteilt 5×UI1 ja nein nein RAM
16 ~100 geteilt 12 Module ja (GC-Sync) nein nein RAM
17 ~60 geteilt 10 Module, Mehrmieter ja (GC-Gruppen) nein nein RAM
18 ~110 dediziert (STD-Modul) ja (Snapshot-Bank oder Zähler) nein nein RAM (Lebensdauerzähler liegen auf dem Modul)

Was als Nächstes kommt


Quelle & Issues: rb-amp/rbamp-esp-idf · diese Seite im Repo: docs/06_examples.md (v1.7.3)