04 · Periodenmessung und Tarifabrechnung
Für die Tarifenergieabrechnung (Wh pro 1 min / 15 min / 1 Stunde / Tag / Monat / Jahr) stellt rbAmp einen atomaren Periodenschnappschuss bereit: Ein einzelner I2C-Befehl friert die zeitgemittelte Leistung über eine Periode ein, und der Master multipliziert sie mit seiner eigenen Wanduhr-dt, um Wh zu erhalten.
Dies ist der produktionstaugliche Weg, Energiedaten zu gewinnen. Die Alternative — RT-P_real auf Master-Seite in jedem Messfenster (~100 ms, ab v1.2) aufsummieren — liefert bei BASIC nahezu dasselbe Ergebnis (etwas geringere Genauigkeit durch die Abtastdiskretisierung) und hält den Master dauerhaft aktiv.
BASIC- und STD-Perioden. BASIC führt einen Periodenschnappschuss je Kanal: Auf Befehl des Masters friert das Modul den Mittel- und Spitzenwert der Leistung sowie die Periodenlänge ein (neben dem laufenden 100-ms-Fenster, das keine Periode ist), und der Host integriert die Energie. STANDARD (STD) führt die Energie im Modul: kumulative Zähler (Bezug/Einspeisung, Wirk- und Blindenergie), die einen Stromausfall überstehen, sowie zeitgestempelte 15-Minuten- und Stundenwerte (der Master stellt die Uhr). STD-Module, bei denen das Bit 8 von CAPABILITIES gesetzt ist, haben außerdem 8 unabhängige Schnappschussbänke; ohne dieses Bit stammt die Intervallenergie aus Differenzen der Zähler. Dieses Kapitel beschreibt den BASIC-Periodenschnappschuss; STD wird in der STD-Technikreferenz beschrieben.
Warum ein Periodenschnappschuss nötig ist
Eine einzige Zeitbasis, im Besitz des Masters
In einem Mehrmodulsystem muss die Zeitbasis beim Master liegen. Der Chip integriert daher kein Wh intern. Stattdessen:
- Der Chip liefert eine zeitunabhängige Kennzahl — die mittlere P über die Periode.
- Der Master multipliziert es mit seinem eigenen Wanduhr-dt.
- Alle Module teilen dieselbe Zeitreferenz → im systemweiten Energiewert sammelt sich keine Drift an.
Die Formel
E_Wh = avg_P_W × master_dt_seconds / 3600
Where:
avg_P_W— der Wert vonPERIOD_AVG_P_W, gelesen nachCMD_LATCH_PERIOD.master_dt_seconds— die Sekunden zwischen zwei aufeinanderfolgenden Snapshots, gemessen vom Master.
Atomare Periode — Konzept
Was der Befehl bewirkt
Das Schreiben von 0x27 nach REG_COMMAND = 0x01 löst eine atomare Sequenz in der Firmware aus (ausgeführt unter __disable_irq()):
1. snapshot ← live (copy the live accumulator into the I2C-visible snapshot)
2. live ← 0 (reset the accumulator; start the next period)
3. period_start_ms = now
Diese drei Schritte sind unteilbar — kein Interrupt kann sich dazwischen schieben. Das garantiert:
- Atomarität: Jede Leistungsabtastung je Fenster gehört zu genau einem Schnappschuss — entweder dem vorherigen oder dem nächsten — nie doppelt, nie verloren.
- Keine Lücke: Die neue Periode beginnt im selben Moment, in dem die vorherige endete — es gibt kein blindes Intervall.
Wo der Schnappschuss liegt
Nach einem Snapshot geben die Periodenschnappschuss-Register (0xBE..0xCD, dazu 0xDC..0xDF für ch0 avg_p, dazu 0xE0..0xE3 für MAX_P, dazu 0xEC..0xEF für den Diagnosewert PERIOD_LATCH_MS) die soeben abgeschlossene Periode zurück. Beachten Sie, dass dieser Bereich nicht zusammenhängend ist — 0xD0..0xDB enthält den Q-Block (Live-RT, kein Periodenschnappschuss), und 0xE4..0xEB ist reserviert bzw. werkseitig. Das genaue Layout finden Sie in Kapitel 11 §4.11–4.13. Der Live-Akkumulator zählt bereits die nächste Periode mit; diese Snapshot-Register aktualisieren sich erst beim nächsten Snapshot.
Ein Schreibvorgang — schließt und öffnet
Dies ist die definierende Eigenschaft des rbAmp-Schnappschusses. Ein einziger Schnappschussbefehl bewirkt gleichzeitig:
- Schließt die gerade beendete Periode (ihre Daten → Schnappschuss)
- Öffnet die nächste Periode (live ← 0)
Der Master benötigt einen Schreibvorgang je Messung, nicht zwei (wie bei einer naiven Umsetzung „Start → Stopp → Lesen“).
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::latchPeriod() / RbAmp::isPeriodValid() |
den Schnappschussbefehl senden; das Gültigkeits-Flag prüfen |
| ESP-IDF | rbamp_latch_period() / rbamp_is_period_valid() |
den Schnappschussbefehl senden; das Gültigkeits-Flag prüfen |
| Python | dev.latch_period() / dev.is_period_valid() |
den Schnappschussbefehl senden; das Gültigkeits-Flag prüfen |
| ESPHome | update_interval: |
jedes Update schließt die Periode ab; Snapshot-Befehl und Einschwingen übernimmt die Komponente |
Fortlaufender Polling-Zyklus (empfohlen)
master chip
------ ----
accumulator running since boot...
write CMD_LATCH (0x27) ────► snapshot ← live (since-boot — DISCARD)
live ← 0, period_start = T0
t0 = master.clock() ◄──── first snapshot — primer (discard)
[wait 60 seconds]
write CMD_LATCH ────► snapshot ← live (over [T0..T1] — KEEP)
live ← 0, period_start = T1
t1 = master.clock()
read avg_p_W @ 0xDC ────► float32 LE
E1_Wh = avg_p × (t1 − t0) / 3600
[wait 60 seconds]
write CMD_LATCH ────► snapshot ← live (over [T1..T2] — KEEP)
live ← 0, period_start = T2
t2 = master.clock()
read avg_p_W
E2_Wh = avg_p × (t2 − t1) / 3600
...and so on. t1 is both the end of period 1 and the start of period 2.
Der erste Snapshot ist ein Vorlauf (verwerfen)
Der erste Snapshot nach dem Start erfasst, was der Akkumulator ab dem Einschalten bis zum ersten Aufruf des Masters gesammelt hat — ein Fenster unbestimmter Länge, das für die Messung ungeeignet ist. Verwerfen Sie sein Ergebnis. Ab dem zweiten Snapshot sind die Daten sauber und nutzbar.
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::readPeriodSnapshot(out, settle_ms, skip_latch) / RbAmp::begin() |
Schnappschuss, Einschwingen, Gültigkeitsprüfung und Lesen in einem Aufruf; begin() verwirft den ersten Schnappschuss |
| ESP-IDF | rbamp_read_period_snapshot() / rbamp_begin() |
Snapshot, Einschwingen, Gültigkeitsprüfung und Lesen in einem Aufruf; begin verwirft den ersten Snapshot |
| Python | dev.read_period_snapshot(settle_ms=50, skip_latch=False) / dev.begin() |
Schnappschuss, Einschwingen, Gültigkeitsprüfung und Lesen in einem Aufruf; begin() verwirft den ersten Schnappschuss |
| ESPHome | update_interval: / latch_interval: |
Aktualisierungsintervall des Schnappschusszyklus; optional eigenes Schnappschussintervall |
Periodenschnappschuss-Register
| Adresse | Name | Typ | Wann man liest | Beschreibung |
|---|---|---|---|---|
0x07 |
PERIOD_VALID |
u8 | zuerst lesen | Bit0 = 1, wenn der Snapshot frisch und gültig ist, 0 bei veraltet (Wettlauf oder zu früher Snapshot) |
0xDC..0xDF |
PERIOD_AVG_P_W[0] |
float32 LE | primär | PRODUKTION — mittlere P_real von Kanal I0 über die Periode (W) |
0xC2..0xC5 |
PERIOD_AVG_P_W[1] |
float32 LE | UI2/UI3 | Mittlere P_real von Kanal I1 |
0xC6..0xC9 |
PERIOD_AVG_P_W[2] |
float32 LE | UI3 | Mittlere P_real von Kanal I2 |
: Derselbe Schnappschuss friert auch die Kanalmittelwerte ein — lesen Sie 0xC2 (Kanal 1) / 0xC6 (Kanal 2) im selben Durchgang und multiplizieren Sie mit demselben dt: e1_wh = avg_p1 * dt_s / 3600. | 0xE0..0xE3 | PERIOD_MAX_P_W | float32 LE | optional | Spitzen-P_real während der Periode (für Spitzentarife) | | 0xEC..0xEF | PERIOD_LATCH_MS | u32 LE | nur Diagnose | Sicht des Chips auf dt zwischen den Schnappschüssen — kann unter Last zu niedrig anzeigen; für die Fensterlänge auf Modulseite PERIOD_COMMIT_COUNT × Commit-Länge verwenden | | 0xBE..0xC1 | PERIOD_COMMIT_COUNT | u32 LE | Fenstermessung | Anzahl der RT-Commits in der abgeschlossenen Periode. Ein Commit = 0.1 s ab v1.2; 0.2 s bei älteren Images — Anzahl × 0.1 s (oder × 0.2 s) ist die eigene Messung des Moduls für die Fensterlänge. Welcher Wert gilt, zeigt der Abschnitt zum Uhrendrift
Export-Akkumulatoren
| Adresse | Name | Typ | Beschreibung |
|---|---|---|---|
| — | — | Die BASIC-Übersicht hat keine Export-Zähler (negative Richtung); bei STD wird die Energie anders geführt — siehe die STD-Dokumentation |
Bei BASIC-Modulen gibt es keine Export-Register; Lesezugriffe auf nicht abgebildete Adressen liefern 0x00 (die Firmware quittiert Lesezugriffe nie mit NACK — siehe Kapitel 11 §5.2). Ein Master, der die Einspeisung auf BASIC erfassen muss, greift auf die RT-basierte Abrechnung zurück (siehe arduino-examples.md → Beispiel 5).
In den Client-Bibliotheken — dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::readPeriodAvgPower(ch) / RbAmp::readPeriodMaxPower() |
Mittel- und Spitzenwert der Leistung der abgeschlossenen Periode |
| ESP-IDF | rbamp_read_period_avg_power() / rbamp_read_period_max_power() |
Mittel- und Spitzenwert der Leistung der abgeschlossenen Periode |
| Python | dev.read_period_avg_power(ch=0) / dev.read_period_max_power() |
Mittel- und Spitzenwert der Leistung der abgeschlossenen Periode |
| ESPHome | update_interval: |
die Komponente liest die Periodenmittelwerte bei jedem Update |
Algorithmus auf Masterseite
Grundzyklus (ein Modul, 60-Sekunden-Periode)
#include
#define RB_ADDR 0x50
void setup() {
Serial.begin(115200);
Wire.begin();
delay(300);
// 1. Primer snapshot (discard result)
rb_write_u8(RB_ADDR, 0x01, 0x27);
}
void loop() {
static uint32_t t_prev = millis();
delay(60000); // wait 60 seconds
// 2. Final snapshot — closes [t_prev, now]
rb_write_u8(RB_ADDR, 0x01, 0x27);
uint32_t t_now = millis();
delay(50); // firmware finishes in ~5 ms; allow margin
// 3. Check PERIOD_VALID
uint8_t valid = rb_read_u8(RB_ADDR, 0x07);
if ((valid & 0x01) == 0) {
// Race or premature snapshot — retry
delay(250);
rb_write_u8(RB_ADDR, 0x01, 0x27);
t_now = millis();
delay(50);
valid = rb_read_u8(RB_ADDR, 0x07);
if ((valid & 0x01) == 0) {
Serial.println("WARN: two stale snapshots in a row");
t_prev = millis();
return;
}
}
// 4. Read the snapshot
float avg_p = rb_read_float_le(RB_ADDR, 0xDC);
float max_p = rb_read_float_le(RB_ADDR, 0xE0);
// 5. Compute energy on master clock
float dt_s = (t_now - t_prev) / 1000.0f;
float e_wh = avg_p * dt_s / 3600.0f;
Serial.printf("[+%5.1fs] E=%.3f Wh avg_P=%.1f W max_P=%.1f W\n",
dt_s, e_wh, avg_p, max_p);
t_prev = t_now;
}
Was in diesem Code wesentlich ist
- Der erste Snapshot ist ein Vorlauf — sein Ergebnis wird verworfen.
PERIOD_VALIDwird VOR der Verwendung des Snapshots gelesen — andernfalls kann bei einem Wettlauf veraltete Daten durchrutschen.- dt wird am Master gemessen, nicht aus
PERIOD_LATCH_MSabgeleitet — das Chip-Register dient nur der Driftdiagnose. t_prevwird auf den t_now eines erfolgreichen Schnappschusses gesetzt, nicht auf den ursprünglichen Periodenbeginn — so bleibt die Kette lückenlos.
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::energyWh(ch) / RbAmpEnergy::reset(ch) |
laufende Wh-Summe auf dem Host führen; Akkumulator auf null setzen |
| ESP-IDF | rbamp_energy_wh() / rbamp_energy_reset() |
laufende Wh-Summe auf dem Host führen; Akkumulator auf null setzen |
| Python | dev.energy.wh(ch) / dev.energy.reset(ch) |
laufende Wh-Summe auf dem Host führen; Akkumulator auf null setzen |
| ESPHome | energy |
Energiesensor, integriert durch die Komponente |
Bidirektionale Abrechnung
Bei einem BASIC-Modul sind die Register PERIOD_AVG_P_NEG_W nicht belegt (Lesewerte sind 0x00), und PERIOD_AVG_P_W ist immer ≥ 0 (negative Samples werden aus dem Akkumulator verworfen).
Was bidirektionale Abrechnung bedeutet
Der Chip integriert pro Periode zwei getrennte Akkumulatoren:
- Verbrauch: Integral von
max(P, 0) × dt— nur positive Leistung. - Einspeisung: Integral von
max(−P, 0) × dt— nur negative Leistung, dem Betrag nach.
Die Summe beider ergibt die Gesamtenergie, die absolut durch den Zähler geflossen ist; die Differenz ist der Nettoverbrauch (was ein mechanischer Scheibenzähler anzeigen würde).
Anwendungen
- Haushalte mit Solarmodulen: Verbrauch und Einspeisung werden nach unterschiedlichen Tarifen abgerechnet (Einspeisevergütung)
- Systeme mit Batteriespeicher: Erfassung der Lade-/Entladezyklen
- Windkraftanlagen, Rückspeiseverbraucher, V2G-EV-Lader
Wo die bidirektionale Zählung liegt
Bidirektionale Produkte (Bezug + Einspeisung) gehören zur rbAmp-STD-Linie, die eine andere 16-Bit-Registerübersicht mit vorzeichenbehafteten Energiezählern im Gerät verwendet — siehe die STD-Referenzdokumentation. Auf der 8-Bit-Übersicht von BASIC, die dieses Kapitel beschreibt, gibt es keine Export-Register.
// BASIC-map period accounting, 60-second period (consumption only)
void loop() {
static uint32_t t_prev = millis();
delay(60000);
rb_write_u8(RB_ADDR, 0x01, 0x27);
uint32_t t_now = millis();
delay(50);
if ((rb_read_u8(RB_ADDR, 0x07) & 0x01) == 0) {
t_prev = millis();
return;
}
float avg_p_consume = rb_read_float_le(RB_ADDR, 0xDC); // ≥ 0
float dt_s = (t_now - t_prev) / 1000.0f;
float e_consume_wh = avg_p_consume * dt_s / 3600.0f;
Serial.printf("[%.1fs] consume=%.3f Wh\n", dt_s, e_consume_wh);
t_prev = t_now;
}
Was bei BASIC nicht verfügbar ist
Wenn Sie ein Modul der BASIC-Stufe besitzen und eine bidirektionale Abrechnung benötigen, haben Sie zwei Möglichkeiten:
- Integration auf Masterseite — RT-
P_real(0xA6) in jedem Messfenster (~100 ms ab v1.2; davor 200 ms) lesen und positive und negative Samples getrennt auf der Masterseite integrieren. Siehe Beispiel 5 in arduino-examples.md. Die Genauigkeit ist etwas geringer (wegen der Abtast-Diskretisierung), funktioniert aber mit jeder Firmware.
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::stdReadEnergy(out) / RbAmp::readPower(ch) |
STD: Import-/Exportzähler im Gerät; BASIC: vorzeichenbehaftete Leistung, Aufteilung auf dem Host |
| ESP-IDF | rbamp_std_read_energy() / rbamp_read_power() (mit Vorzeichen) |
STD: Import-/Exportzähler im Gerät; BASIC: vorzeichenbehaftete Leistung, Aufteilung auf dem Host |
| Python | dev.read_std_energy() / dev.read_power(ch) |
STD: Import-/Exportzähler im Gerät; BASIC: vorzeichenbehaftete Leistung, Aufteilung auf dem Host |
| ESPHome | bidirectional: / energy_exported |
Einspeiseenergie aktivieren; Einspeisesensoren (BASIC meldet 0) |
Reine I-Varianten — Periodenzählung liefert null
Bei I1/I2/I3 (und höheren Varianten nur mit I*) ohne Spannungssensor:
PERIOD_AVG_P_W[*]ist immer 0.0f — ohne U gibt es nichts zu integrieren.PERIOD_VALIDmeldet weiterhin 1 (der Schnappschuss ist gültig, nur null).PERIOD_MAX_P_Wist ebenfalls 0.
Bei Nur-Strom-Varianten liefert die Periodenmessung auf dem Chip keinen Energiewert. Der Master muss entweder:
- Eigenen Spannungssensor verwenden und
I_rms × U_master × cos(φ)_masterintegrieren (aufwendiger; erfordert Phasensynchronisation), oder - Das Nur-Strom-Modul nur zur Überwachung der Stromanwesenheit verwenden und für Energie mit einem UI*-Modul oder einem externen Zähler kombinieren.
Ereignisgesteuertes vs. periodisches Polling
Periodisch (cron-artig)
Der Master liest alle N Sekunden per Timer:
// Once per hour
setInterval(60 * 60 * 1000, [](){
rb_write_u8(0x50, 0x01, 0x27);
// ... read snapshot, accumulate Wh
});
Geeignet für klassische Tarifmessung (1-min, 15-min, 1-Stunde).
Ereignisgesteuert
Der Master löst einen Schnappschuss aus, wenn ein externes Ereignis eintritt:
- Ein Impuls des elektronischen Zählers des Versorgers (Gegenprüfung)
- Ein Tarifwechsel (Spitze / Nebenzeit)
- Eine Benutzerabfrage („Wie viel habe ich bisher verbraucht?“)
void on_tariff_change() {
rb_write_u8(0x50, 0x01, 0x27); // close the period under the old tariff
delay(50);
if (rb_read_u8(0x50, 0x07) & 0x01) {
float avg_p = rb_read_float_le(0x50, 0xDC);
save_period_to_tariff_a_bucket(avg_p, current_dt_s);
}
// the next period accumulates into bucket B
}
Periode neu starten
Um den Live-Akkumulator zu verwerfen und neu zu starten, lösen Sie einen zusätzlichen Snapshot aus und ignorieren dessen Ergebnis:
void restart_period() {
rb_write_u8(0x50, 0x01, 0x27); // close current + start new
// do not read the snapshot — discard
}
Danach den normalen Snapshot-Zyklus von vorn wieder aufnehmen.
Neustart eines Moduls erkennen
Ein Neustart des Moduls (Spannungseinbruch, Watchdog) setzt den laufenden Akkumulator stillschweigend zurück, sodass der nächste Schnappschuss ein undefiniertes Fenster abdeckt — genau wie der erste Schnappschuss nach dem Start. Das Modul stellt bereit:
| Adresse | Name | Typ | Beschreibung |
|---|---|---|---|
0x46..0x49 |
UPTIME_S |
u32 LE | Eigener Betriebszeitzähler des Moduls (nominell Sekunden seit dem Start). Nur Neustart-Erkennung — bei Firmware bis 1.4.21 läuft er langsamer als die Wanduhr (gemessen 0.58–0.80×); niemals als Uhr oder für Zeitrechnungen verwenden |
0x4A |
RESET_CAUSE |
u8 | Reset-Ursachenflags: Bit0 externer Pin, Bit1 Power-on/Brown-out, Bit2 Software, Bit3/Bit4 Watchdogs. Nur zur Protokollierung |
Bei jedem Snapshot prüfen — das Modul wurde innerhalb der Periode neu gestartet, wenn eines der folgenden zutrifft:
UPTIME_Sist seit Ihrem vorherigen Schnappschuss gesunken, oderUPTIME_Sist kleiner als die seit Ihrem vorherigen Snapshot verstrichene Zeit (gemessen mit der Uhr des Masters).
Da der Zähler langsam laufen kann, kann die zweite Prüfung gelegentlich einen Neustart melden, der nicht stattgefunden hat (kurz nach einem echten Start) — das ist unschädlich: Sie verwerfen eine zusätzliche Periode als Vorlauf. Behandeln Sie UPTIME_S ausschließlich als Neustart-Erkennung, nicht als Zeitquelle.
Bei einem erkannten Neustart verwerfen Sie den Snapshot dieser Periode (behandeln Sie ihn als neuen Vorlauf), committen Sie das CT-Modell erneut, wenn Sie bei Firmware vor 1.4.20 ein nicht werkseitiges Modell verwenden (CAPABILITY Bit 12 gelöscht) (initialization.md → Was einen Neustart übersteht), und initialisieren Sie jede reine RAM-Konfiguration neu — siehe Kapitel 11 (Ereignisbit RESET_OCCURRED). RESET_CAUSE ändert die Behandlung nicht; protokollieren Sie es und fahren Sie fort.
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmpPeriodSnapshot::module_restarted |
Neustart-Flag im Periodenergebnis (STD-Zählerpfad) |
| ESP-IDF | rbamp_read_uptime_s() / module_restarted |
die Betriebszeit des Moduls lesen; Neustart-Flag im Periodenergebnis |
| Python | — | nicht verfügbar — kein eigener Aufruf zur Neustarterkennung bei BASIC |
| ESPHome | — | nicht verfügbar — keine Option zur Neustarterkennung in YAML |
Mehrere Module — gleichzeitiger Schnappschuss
Wenn der Master synchrone Schnappschüsse aller Module wünscht (für eine augenblickliche Energiebilanz des Hauses), gibt es zwei Ansätze.
Ansatz 1 — sequenzieller Schnappschuss (einfach)
Der Master erfasst jedes Modul der Reihe nach:
const uint8_t modules[] = {0x50, 0x51, 0x52};
uint32_t t_prev[] = {0, 0, 0};
void setup() {
Wire.begin();
// Primer
for (int i = 0; i < 3; i++) {
rb_write_u8(modules[i], 0x01, 0x27);
t_prev[i] = millis();
}
}
void loop() {
delay(60000);
for (int i = 0; i < 3; i++) {
rb_write_u8(modules[i], 0x01, 0x27);
uint32_t t_now = millis();
delay(50);
if (rb_read_u8(modules[i], 0x07) & 0x01) {
float avg_p = rb_read_float_le(modules[i], 0xDC);
float dt_s = (t_now - t_prev[i]) / 1000.0f;
float e_wh = avg_p * dt_s / 3600.0f;
Serial.printf("[0x%02X] E=%.3f Wh\n", modules[i], e_wh);
t_prev[i] = t_now;
}
}
}
Nachteil: Die Snapshot-Zeitpunkte weichen um wenige Millisekunden voneinander ab. Bei einer 60-Sekunden-Periode ergibt das < 0.1 % Fehler — vernachlässigbar.
Ansatz 2 — Broadcast-Snapshot über General Call (präzise, freiwillig)
Die I²C-General-Call-Adresse 0x00 ist ein Paket, das alle Slaves gleichzeitig empfangen. rbAmp akzeptiert auf der General-Call-Adresse einen kanonischen 5-Byte-Frame, der CMD_LATCH_PERIOD auf jedem Modul auslöst, das den GC-Empfang aktiviert hat. GC ist pro Modul freiwillig über FLEET_CONFIG.bit0 (Standard AUS) — Aktivierungsablauf und Frame-Format siehe initialization.md.
// Canonical 5-byte GC frame: A5 27 group tick_lo tick_hi.
// Returns true on ACK, false on bus-level NACK (no module has GC enabled).
bool broadcast_latch(uint16_t tick16, uint8_t group = 0) {
Wire.beginTransmission(0x00); // general call
Wire.write(0xA5); // frame magic
Wire.write(0x27); // CMD_LATCH_PERIOD opcode
Wire.write(group); // group_id (0 = all-call)
Wire.write((uint8_t)(tick16 & 0xFF)); // tick_lo
Wire.write((uint8_t)((tick16 >> 8) & 0xFF)); // tick_hi
return Wire.endTransmission() == 0;
}
Der Master führt einen 16-Bit-tick-Zähler, der bei jedem Broadcast erhöht wird. Jedes Modul spiegelt den zuletzt akzeptierten Tick in GC_TICK (0x59), sodass der Master einen verpassten Broadcast bei einem bestimmten Modul erkennen kann.
Nach dem Broadcast-Schnappschuss liest der Master den Schnappschuss jedes Moduls über dessen einzelne Adresse. Immer den Rückgabewert prüfen — bei NACK ist der GC-Rahmen nicht angekommen (kein Modul hat GC aktiviert), und der Master muss auf den Einzelschnappschuss je Modul zurückfallen:
const uint8_t modules[] = {0x50, 0x51, 0x52};
uint32_t t_prev;
uint16_t gc_tick = 0;
void setup() {
Wire.begin();
if (!broadcast_latch(gc_tick++)) {
// Fall back: per-module sequential snapshot.
for (uint8_t m : modules) rb_write_u8(m, 0x01, 0x27);
}
t_prev = millis();
}
void loop() {
delay(60000);
if (!broadcast_latch(gc_tick++)) {
for (uint8_t m : modules) rb_write_u8(m, 0x01, 0x27);
}
uint32_t t_now = millis();
delay(50);
float dt_s = (t_now - t_prev) / 1000.0f;
for (int i = 0; i < 3; i++) {
if (rb_read_u8(modules[i], 0x07) & 0x01) {
float avg_p = rb_read_float_le(modules[i], 0xDC);
float e_wh = avg_p * dt_s / 3600.0f;
Serial.printf("[0x%02X] E=%.3f Wh P_avg=%.1f W\n",
modules[i], e_wh, avg_p);
}
}
t_prev = t_now;
}
Vorteil: präzise Synchronisation — Snapshots werden auf allen GC-aktivierten Modulen im selben Moment genommen, innerhalb weniger Mikrosekunden.
Anwendungsfall: entscheidend für den augenblicklichen Ausgleich (z. B. Hausverbrauch − Solareinspeisung zu einem Zeitpunkt).
pro Modul über FLEET_CONFIG.bit0 (Standard AUS bei einem neuen Modul). Ist es AUS, quittiert der Slave den General-Call-Frame mit NACK, und der Master weicht automatisch auf den sequenziellen Snapshot pro Modul aus. Siehe initialization.md — General Call (Broadcast an Adresse 0x00) — für den Aktivierungsablauf und das Frame-Format.
Ein Akkumulator, zwei Auslöser. Der adressierte Schnappschuss (0x27 an der eigenen Adresse des Moduls) und der Broadcast-Schnappschuss setzen denselben Periodenakkumulator zurück — es gibt je Modul nur einen. Wählen Sie für den regulären Zyklus pro Modul eine Methode; ein zusätzlicher Schnappschuss über die andere Methode beendet die laufende Periode vorzeitig. Die obigen Ersatzmuster sind sicher, weil sie nur auslösen, wenn der Broadcast dieses Modul nicht erreicht hat.
In den Client-Bibliotheken — dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmpFleet::gcLatch(group, tick, settle_ms) / RbAmp::readPeriodSnapshot(out, settle_ms, skip_latch=true) |
Broadcast-Snapshot-Frame an die Flotte senden; danach jedes Modul nach einem externen Snapshot lesen |
| ESP-IDF | rbamp_fleet_gclatch() / rbamp_read_period_snapshot(..., skip_latch=true) |
Broadcast-Snapshot-Frame an die Flotte senden; danach jedes Modul nach einem externen Snapshot lesen |
| Python | fleet.gc_latch(group, tick, settle_ms) / dev.read_period_snapshot(skip_latch=True) |
Broadcast-Snapshot-Frame an die Flotte senden; danach jedes Modul nach einem externen Snapshot lesen |
| ESPHome | fleet_gc_enable: / group_id: |
YAML-Optionen für die Aktivierung des Allgemeinen Aufrufs und die Gruppen-ID |
Wahl der Periodenlänge
| Anwendung | Empfohlenes dt |
|---|---|
| Live-UI-Dashboard | 1 s (oder RT-P_real direkt lesen) |
| Trendkurve, Auflösung 1 Minute | 60 s |
| 15-Minuten-Spitzenlastmessung | 900 s |
| Stündliche Messung | 3600 s |
| Tagessummen | Stündliche Snapshots auf dem Master aufsummieren; eine einzelne Periode nicht länger als 1 Stunde werden lassen |
Perioden länger als 1 Stunde sind zulässig, und nichts läuft über — der Akkumulator mittelt, solange kein Schnappschuss eintrifft. Was bei einem sehr langen Fenster abnimmt, ist die Genauigkeit des Mittelwerts: im ungünstigsten Fall ≈ 0.2 % nach 1 Stunde, 1.3 % nach 6 Stunden, 5 % nach 24 Stunden. Halten Sie einzelne Perioden deshalb bei ≤ 1 Stunde und summieren Sie längere Gesamtwerte auf dem Master.
PERIOD_MAX_P_W — Spitzenlast
Register 0xE0 meldet die maximale Leistung, die in einem RT-Fenster innerhalb der Periode beobachtet wurde. Verwendung:
- Spitzenlasttarife: Versorger berechnen für Leistungsentgelte die höchste 15-Minuten-Last des Monats.
- Einschalterkennung: Motorstarts erzeugen einen 5–10-fachen Nennspitzenwert —
max_P >> avg_Pmarkiert das Ereignis. - Plausibilitätsprüfung: Wenn
max_Pavg_Pdeutlich übersteigt, ist die Last stoßartig — für viele Haushaltssituationen normal, bei erwartet konstanter Last aber prüfenswert.
Atomarität ist garantiert
CMD_LATCH_PERIOD läuft während der Snapshot-Kopie mit deaktivierten Interrupts (wenige Mikrosekunden). Der Master kann nie einen halb aktualisierten Snapshot lesen — selbst wenn er die Bytes unmittelbar nach dem Schreiben liest, schließt die Firmware den Block ab, bevor die nächste I2C-Transaktion endet (mindestens 10+ µs liegen zwischen Schreiben und Lesen).
Dieselbe Atomarität verknüpft das Zurücksetzen des Akkumulators mit der Kopie des Snapshots — jede P-Probe liegt in genau einem Snapshot (entweder in der vorherigen oder in der nächsten Periode), nie in beiden und nie in keinem.
Was der Master NICHT tun darf
- ❌ Berechnen Sie nicht
U_rms × I_rms × dt— das ist Scheinenergie (VAh), nicht Wh. Die Scheinleistung enthält den Blindanteil und überbewertet jede induktive Last. Verwenden SiePERIOD_AVG_P_W. - ❌ Richtung nicht aus
I_rmsableiten — der Effektivwert ist immer ≥ 0. Die Richtung steckt im Vorzeichen vonP_real. - ❌
PERIOD_LATCH_MSnicht für Wh verwenden — dieses Register dient der Diagnose und kann mit dem Chiptakt driften. Maßgeblich istmaster_dt. - ❌ Nicht schneller als der RT-Commit-Zyklus snappen. Der Chip braucht mindestens eine Netzperiode (~20 ms bei 50 Hz) Akkumulation plus Einschwingzeit — mindestens 50 ms zwischen
CMD_LATCH_PERIOD-Befehlen. Schnellere Snapshots liefern einen leeren Snapshot (PERIOD_VALID = 0). 200 ms sind eine sichere praktische Untergrenze für stationäres Polling; siehe Kapitel 11 §6.0 / §6.4.
Diagnose der Takt-Drift
PERIOD_LATCH_MS ist ein reines Diagnoseregister — der interne Zeitbezug des Moduls zeigt zu kurz an, wenn das Modul ausgelastet ist. Die Gegenprüfung sollte eine weite Toleranz verwenden:
uint32_t chip_dt = rb_read_u32(0x50, 0xEC);
uint32_t master_dt = t_now - t_prev;
float ratio = (float)chip_dt / (float)master_dt;
if (ratio < 0.70f || ratio > 1.05f) {
Serial.printf("WARN: chip drift outside ±30%% envelope, ratio=%.3f\n", ratio);
}
Akzeptanz: bis zu 30 % Unterzählung unter Last ist normal (Verhältnis bis hinab zu ~0.70). Das ist so vorgesehen — siehe troubleshooting.md §13. Verwenden Sie keine enge Schwelle von 3 %–5 %; sie verwirft gesunde Module in Massen.
Dieser Drift beeinflusst die Wh-Genauigkeit nicht (Wh nutzt den Master-Takt); PERIOD_LATCH_MS dient nur dazu, schwerwiegende Anomalien auf Chipseite anzuzeigen.
Wenn Sie die eigene Messung des Moduls für die Länge des abgeschlossenen Fensters möchten, verwenden Sie PERIOD_COMMIT_COUNT (Register 0xBE) multipliziert mit der Commit-Länge: Es zählt ganze RT-Commits und zeigt unter Last nicht zu niedrig an, wie PERIOD_LATCH_MS es kann. Ein Commit beträgt ab v1.2 0.1 s; ältere Images als v1.2 verwenden 0.2 s. Eine Versionstabelle ist zur Unterscheidung nicht nötig: Der Quotient PERIOD_LATCH_MS / PERIOD_COMMIT_COUNT liegt nahe bei 100 oder nahe bei 200.
Weiter
- troubleshooting.md — was zu tun ist, wenn Werte falsch aussehen
- arduino-examples.md — Beispiel 5 (Master-seitig bidirektional auf BASIC-Firmware)