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/ 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/ |
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/.
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:
-
Erkennen —
rbamp_fleet_scanfindet alle Module, prüft ihre Identität und schließt kollidierende Adressen aus. -
Konfigurieren —
rbamp_configure_channelssetzt die Sensorklasse + CT-Modelle pro Kanal + ein einziges abschließendesSAVE_USER_CONFIGin einem Aufruf pro Mehrkanal-Modul. -
GC-Scharfstellung —
rbamp_fleet_enable_gc_allaktiviert den Empfang von General-Call-Snapshots auf jedem Modul der Flotte. -
Schleife — bei jedem Takt führt der Master ein atomares
_gclatchaus (ein synchroner Snapshot über die gesamte Flotte), prüft mit_check_syncquer, liest_poll_all, integriert die Energie übermaster_dtund 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
#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)
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)
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) → einpoll_allliest die gesamte Flotte → Aggregation. Keine Drift zwischen den Modulen aus einer Kette sequenzieller Round-Trips. -
Verhalten von
total_powerin einer heterogenen Flotte. Die UI1 liefert Wirkleistung (sie hat Spannung → sie hatP); I2/I3 messen nur Strom, daher ist ihr Beitrag zutotal_powernull. Im Kanon entsprichttotal_powerdaher 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_totalwächst monoton (2.55 → 6.94 Wh im Messfenster am Bench). Die Komponente integriert jede Periode übermaster_dt_ms(esp_timer), nicht über das chipseitigelatch_ms(ein Modul-Diagnosetimer, der unter Last zu kurz gemeldet werden kann). Ein fehlerhafter Tick addiert0 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_alles mitstatus[i] != ESP_OKund 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 mitn_ok=2/3weiter abfragen, ohne Stillstand. Dasselbe gilt fürcheck_sync—missed_idxzeigt 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 mithas_voltage = true) von den Teil-Handles (allen übrigen). -
Stromwerte je Kanal → Lastaufteilung. Über
fleet_poll_allsieht 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 — Mittel112.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ündelterfleet_poll_allist 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.
#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):
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.
#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):
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.
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).
#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):
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 GCskew = 0nach 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.
#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.
#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).
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.
#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.
#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.
#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.
#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.
#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.
Benötigt eine eigene Partitionstabelle mit dem Eintrag storage,data,spiffs,,128K, in partitions.csv. Ein Beispiel liegt in examples/spiffs_logger/partitions.csv.
#include
#include
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_spiffs.h"
#include "esp_log.h"
#include "esp_timer.h"
#include "rbamp.h"
#define LOG_PATH "/storage/log.csv"
#define ROTATE_BYTES (64 * 1024)
static const char *TAG = "spiffs_logger";
static void rotate_if_full(void) {
struct stat st;
if (stat(LOG_PATH, &st) == 0 && st.st_size >= ROTATE_BYTES) {
rename(LOG_PATH, "/storage/log_prev.csv");
}
}
void app_main(void) {
esp_vfs_spiffs_conf_t spiffs_cfg = {
.base_path = "/storage",
.partition_label = "storage",
.max_files = 4,
.format_if_mount_failed = true,
};
ESP_ERROR_CHECK(esp_vfs_spiffs_register(&spiffs_cfg));
/* ...bus_cfg + rbamp_new + rbamp_begin... */
rbamp_handle_t dev = NULL;
while (1) {
vTaskDelay(pdMS_TO_TICKS(60000));
rbamp_period_snapshot_t snap;
if (rbamp_read_period_snapshot(dev, &snap, 50, false) != ESP_OK ||
!snap.valid) continue;
rotate_if_full();
FILE *f = fopen(LOG_PATH, "a");
if (!f) {
ESP_LOGE(TAG, "fopen failed");
continue;
}
fprintf(f, "%lld,%.3f,%.4f,%u\n",
(long long)(esp_timer_get_time() / 1000),
(double)snap.avg_p[0],
rbamp_energy_wh(dev, 0),
(unsigned)snap.master_dt_ms);
fclose(f);
}
}
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.
⚠ 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).
#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/.
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.
#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.
#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):
/* 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:
#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):
/* 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:
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/
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_msist 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_restartedmarkiert 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 PeriodeESP_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
-
07 · DIY-Integrationen — Home Assistant / Node-RED / OpenHAB auf Basis dieser Szenarien (einschließlich
examples/ha_discovery/) -
08 · Cloud-Integrationen — AWS IoT / Azure / GCP / InfluxDB Cloud
-
09 · API-Referenz — jede öffentliche Funktion dokumentiert
-
10 · Fehlerbehebung — wenn sich die Szenarien an Ihrem Aufbau anders verhalten
Quelle & Issues: rb-amp/rbamp-esp-idf · diese Seite im Repo: docs/06_examples.md (v1.7.3)