rbAmp-Wire-Protokoll-Referenz (v1.3)
rbAmp ist ein kompaktes Hardwaremodul zur Messung von Netzwechselgrößen über eine I²C-Schnittstelle. Das Modul verhält sich wie ein üblicher I²C-Slave mit einer festen Registerübersicht (Seite 0, 0x00..0xFF). Dieses Dokument beschreibt das Wire-Protokoll auf Registerebene sowie Befehle und Abläufe.
: Drittanbieter und fortgeschrittene Integratoren, die eigene I²C-Treiber für das rbAmp-Modul ohne Client-Bibliotheken schreiben (Arduino / ESP-IDF / Python / ESPHome).
Umfang: kanonisches Drahtprotokoll des rbAmp-Moduls in Version v1.3 — Registerabbildung, Protokollabläufe, Verhaltensgarantien. Dies ist die vollständige Referenzdokumentation auf Ebene des Drahtvertrags.
Version: „v1.3“ ist die Drahtprotokoll-Version (Register VERSION 0x03 liefert 0x04), nicht die Version dieses Dokuments. Es ist das Protokoll der gesamten aktuellen BASIC-Modul-Firmware (1.4.x); STANDARD-(STD)-Module verwenden eine andere Registerabbildung — siehe die technische STD-Referenz.
NICHT im Umfang: Integration mit einer bestimmten Bibliothek / einem bestimmten Betriebssystem / Framework — lesen Sie dazu die Dokumentation der jeweiligen Bibliothek.
1 · Einführung
1.1 Übersicht der Artikelnummern
Die Modulvarianten (SCT-UI1 … SCT-I3 mit ihren Spannungs- und Stromkanälen) sind in overview.md → Modulvarianten aufgeführt.
I-Varianten (I1/I2/I3) haben keine Spannungshardware — die Register U_RMS, U_PEAK und P liefern 0.0. Die Frequenz (AC_FREQ) ist bei allen Varianten verfügbar (aus dem ZC gewonnen).
Kalibrierung erfolgt im Werk. Der Kunden-Master konfiguriert NICHT Grundrauschen (NF), Verstärkung, Phasenkompensation oder andere Werksparameter — all das ist Werkskalibrierung, die im Modul hinterlegt ist (siehe §4.0 reservierte Bereiche). Bei BASIC-SCT-Modulen (mit SCT-013-Sensoren) schreibt der Kunde nur SENSOR_CLASS + CT_MODEL (siehe §6.2) — das Modul wendet alles andere automatisch aus der Voreinstellungstabelle an. BASIC-CT-Serie und STANDARD-(STD-)Module werden paarweise mit ihren Sensoren geliefert, werkseitig voreingestellt und kalibriert: Es wird nichts geschrieben.
1.2 Versionierung
| Feld | Wert |
|---|---|
protocol_version |
1.3 |
schema_version |
2 |
Register VERSION (0x03) |
0x04 für v1.3 |
| Vertrag der Seite 0 | eingefroren bei der Veröffentlichung von v1.3 |
2 · Grundlagen des Busprotokolls
2.0 Leistung und Versorgung
| Parameter | Wert |
|---|---|
VCC Nennwert |
+5 V |
VCC-Bereich |
4.5..5.5 V |
| Typische Stromaufnahme | ~15 mA |
| Spitzenstromaufnahme (Snapshot + Flash-Schreibvorgang) | ~25 mA |
| Einschaltstrom | ≤ 50 mA bei 5 ms |
| Reihenfolge | VCC darf gleichzeitig mit I²C angelegt werden; Pull-ups (3.3 V) sind zulässig, bevor VCC anliegt |
| Isolation | das Modul ist vollständig Niederspannung: Die Zange koppelt magnetisch, und der UI-Spannungsabgriff ist galvanisch getrennt |
Auf der Niederspannungsseite sind vier Leitungen zwingend: VCC, GND, SDA, SCL. DRDY (Open-Drain) ist optional. Zu Pull-ups und Mehrmodulbetrieb siehe §2.3.
2.1 I²C-Parameter
- Standardadresse:
0x50(7 Bit). - Zulässiger Adressbereich:
0x08..0x77(übliche I²C-Reservegrenzen). - Logikpegel: 3.3 V (5-V-tolerant bei Pull-ups auf 3.3 V).
- Eingebaute Pull-ups: 4.7 kΩ an SDA/SCL nach 3.3 V (Modul).
- Clock-Stretching: Das Modul verwendet SCL-Clock-Stretching NICHT als routinemäßigen Flusssteuerungsmechanismus. Zwischen Transaktionen muss der Master eine Pause zwischen Transaktionen von ≥ 100 µs (
tBUF) einhalten. Direkt aufeinanderfolgende Transaktionen ohne Pause (Back-to-back-START ohnetBUF) sind zulässig, aber nicht empfohlen — manche Host-Stacks (ESP-IDF i2c_master) zeigen eine erhöhte NACK-Rate. Siehe separat §5 Akzeptanz / EMI.
2.2 Busgeschwindigkeit
| Geschwindigkeit | Anwendbarkeit | Hinweis |
|---|---|---|
| 50 kHz | empfohlen auf ESP32- und ESP8266-Hosts | Der ESP-IDF-I²C-Treiber zeigt bei 100 kHz eine NACK-Rate von ~20 % — eine Einschränkung des Host-Treibers, nicht des Moduls; 50 kHz + 3× Wiederholung ergibt eine Fehlerrate < 0.8 %. |
| 100 kHz | empfohlen auf anderen Hosts | auch auf ESP32/ESP8266 mit Wiederholung auf Anwendungsebene (3×) machbar. |
| 400 kHz | nicht empfohlen | die Geschwindigkeit ist die Wahl des Anwenders. |
2.3 Mehrmodul-Bus
Mehrere rbAmp-Module können sich einen Bus teilen:
- Bis zu ca. 16 Module (begrenzt durch die gesamte Buskapazität ≤ 400 pF bei 100 kHz).
- Pull-ups: Bei 2–3 Modulen an einem Bus bis 15 cm die eingebauten Pull-ups unverändert lassen; bei vier oder mehr Modulen oder einem längeren Bus überlasten die parallelen 4.7-kΩ-Pull-ups die Senke. Die eingebauten Pull-ups trennen auf jedem Modul außer einem (oder einen PCA9515/9615-I²C-Puffer verwenden).
- Länge: bis 0.15 m einfach → 100 kHz; 0.15–1 m verdrillte Doppelader (SDA+GND und SCL+GND in getrennten Paaren) → 100 kHz; > 1 m — I²C-Puffer; > 3 m — differenzieller Bus (PCA9615 / LTC4332).
2.4 Budget für das Bus-Polling
Bei 50 kHz benötigt ein einzelner Registerlesezugriff ≈ 200–400 µs. Der vollständige RT-Block eines Kanals (U + I + P + PF, 4 Gleitkommazahlen = 16 Byte Burst) benötigt ≈ 5–8 ms je Kanal.
| Konfiguration | Busbelegung je Zyklus | Maximale Abfragerate |
|---|---|---|
| 1× UI1, RT-Block | ~5 ms | 100+ Hz (das Modul aktualisiert aber mit 10 Hz) |
| 5× UI1, RT-Block | ca. 25 ms | 10 Hz |
| 16× I3, RT + Periode | ca. 400 ms | kommt nicht mit — liest etwa alle 4 Fenster à 100 ms |
Faustregel: Bei 50 kHz liegen die komfortablen Grenzen bei 8–10× I3 oder 15–16× UI1, wenn jedes zweite Fenster abgefragt wird (5 Hz); halbieren Sie die Modulanzahl, um jedes Fenster abzufragen (10 Hz).
3 · Variantenmodell
3.1 HW_VARIANT (Register 0x55, u8, nur lesbar)
Verbindliches Artikel-Byte:
| Wert | SKU | N_I | Spannungs-HW |
|---|---|---|---|
0x01 |
UI1 | 1 | ja |
0x02 |
UI2 | 2 | ja |
0x03 |
UI3 | 3 | ja |
0x04 |
I1 | 1 | nein |
0x05 |
I2 | 2 | nein |
0x06 |
I3 | 3 | nein |
0x07 |
UI5 | 5 | ja |
0x08 |
UI7 | 7 | ja |
Jeder andere Wert → das Gerät wird nicht als rbAmp erkannt.
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::readVariant() |
Hardwarevariante (Artikelnummer) lesen |
| ESP-IDF | rbamp_read_variant() |
Hardwarevariante (Artikelnummer) lesen |
| Python | dev.read_variant() |
Hardwarevariante (Artikelnummer) lesen |
| ESPHome | get_variant_str() |
Hardwarevariante (Artikelnummer) lesen |
3.2 CAPABILITY (Register 0x57/0x58, u16 LE, nur lesbar)
Bitmap der Funktionserkennung. Dies ist der kanonische Weg, unterstützte Funktionen zu erkennen — ohne numerischen Versionsvergleich.
| Bit | Flag | Bedeutung |
|---|---|---|
| 0 | EXT_ADDRESSING | erweiterte 16-Bit-Adressierung (0xFF-Präfix) |
| 1 | GC_LATCH | Allgemeiner-Aufruf-Schnappschuss wird unterstützt |
| 2 | GC_GROUP_FILTER | Der GROUP_ID-Filter ist aktiv |
| 3 | DIGEST | Digest-Block (0x70..0x85) ist verfügbar |
| 4 | EVENTS | EVENT_FLAGS wird unterstützt |
| 5 | UID_ARBITRATION | UID-basierte Adressvergabe (keine öffentlichen Befehle) |
| 6 | SEAL | reserviert — nicht implementiert |
| 7 | TWO_PHASE_ADDR | Adressänderung mit Zwei-Phasen-Commit |
| 8 | ZC_PHASE_OFFSET = Spannungs-HW | das Modul hat einen U-Kanal |
| 9 | SAVE_USER_CONFIG | CMD_SAVE_USER_CONFIG ist verfügbar |
| 10 | CLEAR_ERROR | CMD_CLEAR_ERROR ist verfügbar |
| 11 | IAP | Programmierung im Betrieb (nur F4-Stufen) |
| 12 | SCT_RATING_SELF | Firmware 1.4.20+: Ein Wechsel des SCT-Modells behält die Gerätekalibrierung und übersteht einen Neustart; die Bibliotheken überspringen ihre eigene Nennkorrektur |
3.2.1 Funktionen erkennen
Jede Funktion über ihr einzelnes Bit erkennen — niemals das gesamte Register mit einem erwarteten Festwert vergleichen: Die Bitmap wächst mit der Firmware (z. B. erschien Bit 12 in Firmware 1.4.20), daher bricht ein Vergleich des Gesamtwerts bei neueren Modulen.
3.2.2 Byte-Layout von CAPABILITY u16 LE
CAPABILITY ist 2 Byte an den Adressen 0x57 (niederwertiges Byte) und 0x58 (höherwertiges Byte), Little-Endian:
register layout (byte-addressed):
0x57 0x58
┌──────┬──────┐
│ LO │ HI │
└──────┴──────┘
bits bits
0-7 8-15
full u16 = (read_u8(0x58) << 8) | read_u8(0x57)
Bitzuordnung:
- Byte
0x57(LO) enthält Bits 0..7: EXT_ADDRESSING, GC_LATCH, GC_GROUP_FILTER, DIGEST, EVENTS, UID_ARBITRATION, SEAL, TWO_PHASE_ADDR. - Byte
0x58(HI) enthält Bits 8..15: ZC_PHASE_OFFSET (= Spannungs-HW), SAVE_USER_CONFIG, CLEAR_ERROR, IAP, SCT_RATING_SELF (Bit 12, Firmware 1.4.20+), Bits 13–15 reserviert.
3.2.3 Kanonisches Rezept für has_voltage
cap_hi = read_u8(0x58) # high byte holds bits 8..15
has_voltage = bool(cap_hi & 0x01) # bit 8 of the u16 = bit 0 of byte 0x58
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::readCapability(out) / RbAmp::hasVoltageHw() |
16-Bit-Funktionsmaske lesen; auf einen Spannungskanal prüfen |
| ESP-IDF | rbamp_read_capability() / rbamp_has_voltage() |
16-Bit-Funktionsmaske lesen; auf einen Spannungskanal prüfen |
| Python | dev.read_capability() / dev.has_voltage() |
16-Bit-Funktionsmaske lesen; auf einen Spannungskanal prüfen |
| ESPHome | get_capability_hex() |
Capability-Bitmap lesen |
3.3 Varianten-Profiltabelle — unveränderlich
| SKU | HW_VARIANT (0x55) | N_I | Spannungs-HW | CAPABILITY Bit 8 (Spannungs-HW) |
|---|---|---|---|---|
| UI1 | 1 | 1 | ja | Bit 8 gesetzt |
| UI2 | 2 | 2 | ja | Bit 8 gesetzt |
| UI3 | 3 | 3 | ja | Bit 8 gesetzt |
| I1 | 4 | 1 | nein | Bit 8 gelöscht |
| I2 | 5 | 2 | nein | Bit 8 gelöscht |
| I3 | 6 | 3 | nein | Bit 8 gelöscht |
| UI5 | 7 | 5 | ja | Bit 8 gesetzt |
| UI7 | 8 | 7 | ja | Bit 8 gesetzt |
HW_VARIANT ⟷ CAPABILITY-Kohärenz: HW_VARIANT 1..3 und 7..8 (UI) → Bit 8 gesetzt; HW_VARIANT 4..6 (I) → Bit 8 gelöscht. Eine Abweichung weist auf eine Hardware- oder Firmware-Anomalie hin (defektes Gerät oder fehlerhaftes Flashen).
3.4 SENSOR_CLASS ≠ Varianten-Unterscheidungsmerkmal
⚠ SENSOR_CLASS (0x25) ist KEIN Varianten-Unterscheidungsmerkmal. Es ist ein vom Benutzer konfiguriertes Register (Auswahl der CT-Sensorklasse: Unset/Sct013/WiredCT/BuiltinCT) und spiegelt die Hardwarevariante nicht wider. Zur Varianterkennung ausschließlich HW_VARIANT (0x55) + CAPABILITY (0x57/0x58) verwenden.
3.5 PRODUCT_ID (0x54, u8, nur lesbar)
Unterscheidungsmerkmal der Produktfamilie:
| Wert | Familie |
|---|---|
0x01 |
rbAmp-Sensor (dieses Dokument) |
0x02 |
rbDimmer (eigene Registerabbildung; nicht in diesem Dokument behandelt) |
Der Master MUSS PRODUCT_ID lesen, bevor er ein familienspezifisches Register auswertet.
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::readProductId() |
Familien-ID-Byte lesen |
| ESP-IDF | rbamp_read_product_id() |
Familien-ID-Byte lesen |
| Python | dev.read_product_id() |
Familien-ID-Byte lesen |
| ESPHome | — | nicht verfügbar |
3.6 Kanonischer Erkennungsalgorithmus
if not i2c_addr_acks(addr):
return NO_DEVICE
product = read_u8(addr, 0x54)
if product != 0x01:
return NOT_RBAMP_SENSOR
hw = read_u8(addr, 0x55)
if 1 <= hw <= 8:
cap_hi = read_u8(addr, 0x58)
has_voltage = bool(cap_hi & 0x01)
return {sku: SKU[hw], N_I: N_I_TABLE[hw], has_voltage: has_voltage}
return UNKNOWN_DEVICE
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::begin() / RbAmp::readVariant() |
das Modul abfragen und seine Leitung erkennen; die Variante lesen |
| ESP-IDF | rbamp_begin() / rbamp_read_variant() |
das Modul abfragen und seine Leitung erkennen; die Variante lesen |
| Python | dev.begin() / dev.read_variant() |
das Modul abfragen und seine Leitung erkennen; die Variante lesen |
| ESPHome | rbamp: address: / get_variant_str() |
Modul-Adresse in YAML gesetzt; die Variante als Text |
4 · Registerabbildung (Produktion v1.3)
Angewandter Filter: build: production(Kalibrierregister der Kalibrierungsbuilds ausgenommen). Werkskalibrierungsregister (NF, GAIN, PHASE) sindnicht dokumentiert— sie gehören ins Werkslabor, nicht an die Verbraucher-Oberfläche.
4.0 Reservierte Bereiche (intern)
Die folgenden Bereiche sind für interne bzw. Werksnutzung reserviert und werden in diesem Dokument nicht beschrieben. Lesevorgänge liefern entweder Daten, die für die Verbraucherlogik nicht relevant sind, oder 0x00 für nicht vorhandene Adressen (siehe §5.2). Schreibvorgänge auf diese Adressen werden entweder stillschweigend verworfen oder mit ERR_PARAM beantwortet:
0x04— interne Betriebsanzeige (werkseitig gesteuert, vom Kunden nicht einstellbar).0x06,0x26— interne Kalibrierparameter (Werkslabor).0x08..0x0F— LUT-Debug-Ansicht (werkseitige Diagnose).0x1B..0x1F— reservierte Seite 0 (0x18..0x1Asind Produktionsdiagnose, siehe §4.2).0x36..0x3B,0x40..0x45— reservierte Adressen auf Seite 0 (0x32+0x3C..0x3Fsind das Kanalzugriffsfenster, siehe §4.14).0x4F,0x50— reserviert (Vorabreservierung des Identitätsblocks).0xE4..0xEB,0xF0..0xFF— Werkskalibrierung (NF, GAIN); nur werkseitig schreibbar.
Hinweis zu 0xD0..0xE3: Im Produktionsbuild ist dieser Bereich vom V03 Q-Block belegt (siehe §4.12). Im separaten Kalibrier-Firmwarestand (nicht an Endkunden ausgeliefert) wird derselbe Bereich vom Kalibrierungsblock überlagert (build:cal). Der Kundenmaster sieht nur die Produktionsüberlagerung — den Q-Block.
3rd-party-Integratoren müssen diese Bereiche ignorieren.
4.1 Steuerblock (0x00..0x07)
| Adr | Name | Größe | Typ | Zugriff | Persistenz | Hinweise |
|---|---|---|---|---|---|---|
0x00 |
STATUS |
1 | u8 | r | ram | Bit0=BEREIT, Bit1=FEHLER (Spiegel von REG_ERROR != 0), Bit2=EREIGNISSE_AUSSTEHEND (Spiegel von EVENT_FLAGS != 0) |
0x01 |
COMMAND |
1 | u8 | w | ram | Einen CMD_*-Opcode schreiben (siehe §5.2) |
0x02 |
ERROR |
1 | u8 | r | ram | Ergebnis des letzten Schreibvorgangs; 0x00 = OK; 0xFA..0xFF Fehlerklassen. Löschen über CMD_CLEAR_ERROR. Siehe §5.3 |
0x03 |
VERSION |
1 | u8 | r | von | Protokollversion. 0x04 = v1.3 |
0x05 |
CT_MODEL |
1 | u8 | rw | user_config | SCT-013-Artikelcode (reine Vorbereitung in v1.3 — siehe §6.2) |
0x07 |
V03_PERIOD_VALID |
1 | u8 | r | ram | Gesetzt durch CMD_LATCH_PERIOD: 1 = frisch, 0 = leer/veraltet. NICHT beim Lesen gelöscht. Siehe §6.3.3 (Zeugen) + §7.5 (Erhalt der Periode bei fehlgeschlagenem Schnappschuss) |
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::waitReady(timeout_ms) / RbAmp::readLastError() |
auf das Bereit-Flag warten; den Gerätefehlercode lesen |
| ESP-IDF | rbamp_wait_ready() / rbamp_read_last_error() |
auf das Bereit-Flag warten; den Gerätefehlercode lesen |
| Python | dev.wait_ready(timeout_ms=1000) / dev.read_last_error() |
auf das Bereit-Flag warten (bei Zeitüberschreitung Fehler); den Gerätefehlercode lesen |
| ESPHome | update()-Bereitschaftsprüfung / get_last_error_str() |
Messwerte werden veröffentlicht, sobald das Modul Bereitschaft meldet; der Fehlercode als Text |
4.2 Diagnose — rohe Eingangsmittelwerte und Erfassungsfenster (0x10..0x1C)
| Adr | Name | Größe | Typ | Zugriff | Persistenz | Hinweise |
|---|---|---|---|---|---|---|
0x10 |
ADC_MEAN_U |
2 | u16 LE | r | ram | Rohsignal-Mittelwert, U-Kanal (~2048 zentriert) |
0x12 |
ADC_MEAN_I0 |
2 | u16 LE | r | ram | Roh-Eingangsmittelwert, I0 |
0x14 |
ADC_MEAN_I1 |
2 | u16 LE | r | ram | Rohmittelwert des Eingangs, I1 (UI2/I2/I3/UI3) |
0x16 |
ADC_MEAN_I2 |
2 | u16 LE | r | ram | Rohsignal-Mittelwert, I2 (UI3/I3) |
0x18 |
CAPTURE_STATUS |
1 | u8 | r | ram | Rohsample-Erfassung: Bit0=bereit |
0x19 |
CAPTURE_PAGE |
1 | u8 | rw | ram | Seite 0..15 → 16 rohe I0-Abtastwerte in CAPTURE_WINDOW |
0x1A |
CAPTURE_WINDOW |
32 | Byte | r | ram | 16×u16 LE Roh-I0-Codes vor der LUT. Mit einem Burst 32 Byte lesen. |
4.3 System (0x20..0x25)
| Adr | Name | Größe | Typ | Zugriff | Persistenz | Hinweise |
|---|---|---|---|---|---|---|
0x20 |
AC_FREQ |
1 | u8 | r | ram | Aus dem Nulldurchgang (ZC) gewonnen. 50 oder 60 Hz, ganzzahlig. ZC ist bei allen Varianten aktiv (einschließlich I*) |
0x21 |
AC_PERIOD |
2 | u16 LE | r | ram | Netz-Halbperiode, µs |
0x23 |
CALIBRATION |
1 | u8 | r | ram | Altes Kalibrierstatus-Byte |
0x24 |
TOPOLOGY |
1 | u8 | r | von | Anzahl der Stromkanäle (= V03_N_I): 1, 2 oder 3; 5 = UI5, 7 = UI7 |
0x25 |
SENSOR_CLASS |
1 | u8 | rw | user_config | 0 = UNSET, 1 = SCT_013, 2 = WIRED_CT (CT-Zangen-Serie, Modelle 1..13: 1..5 Altbestand; werkseitig gepaart bei CT-Artikeln — ab Firmware 1.4.22 lehnt das Modul Klassen- und Modellschreibvorgänge im Normalbetrieb mit ERR_PARAM (0xFE) ab; die Client-Bibliotheken verweigern sie bei allen Firmwareständen), 3 = BUILTIN_CT (Kalibrierung je Gerät ab Werk, Modellcode ungenutzt). Ein Klassenwechsel setzt CT_MODEL = 0. Kein Varianten-Unterscheidungsmerkmal (siehe §3.4) |
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::setSensorClass(cls) / RbAmp::readSensorClass(out) |
Sensorklasse setzen; zurücklesen |
| ESP-IDF | rbamp_set_sensor_class() / rbamp_read_sensor_class() |
Sensorklasse setzen; zurücklesen |
| Python | dev.set_sensor_class(cls) / dev.read_sensor_class() |
Sensorklasse setzen; zurücklesen |
| ESPHome | sensor_class: |
YAML-Option, die die Sensorklasse festlegt |
4.4 Flottenkonfiguration (0x27..0x2F)
| Adr | Name | Größe | Typ | Zugriff | Persistenz | Hinweise |
|---|---|---|---|---|---|---|
0x27 |
FLEET_CONFIG |
1 | u8 | rw | user_config | Bit 0 = GC_ENABLE (Empfang von GC-Schnappschüssen; wirkt nach Reset). Bits 1–7 reserviert |
0x28 |
GROUP_ID |
1 | u8 | rw | user_config | GC-Snapshot-Gruppenfilter. 0 = auf All-Call antworten. Das Gruppenbyte des GC-Frames muss übereinstimmen oder 0x00 sein |
0x29 |
DIGEST_CONFIG |
1 | u8 | rw | ram | Bitmaske der Digest-Fensterzusammensetzung (siehe §4.9); das Schreiben eines nicht unterstützten Bits → ERR_PARAM. Nach dem Reset Standard 0x00 (Digest deaktiviert); bei jeder Initialisierung neu schreiben |
0x2A |
EVENT_FLAGS |
1 | u8 | w1c | ram | Sticky-Ereignisbits (siehe §5.3 Fehlermodell). Standard 0x00 nach dem Reset (aber Bit5 RESET_OCCURRED ist beim Booten gesetzt) |
0x2B |
EVENT_MASK |
1 | u8 | rw | ram | Welche EVENT_FLAGS-Bits DRDY dauerhaft auf LOW ziehen |
0x2C |
THRESH_I_HI |
2 | u16 LE | rw | ram | Stromschwelle → EVENT_FLAGS.THRESH_I. Einheit: 0.01 A. 0xFFFF = deaktiviert |
0x2E |
THRESH_P_HI |
2 | u16 LE | rw | ram | Leistungsschwelle → EVENT_FLAGS.THRESH_P. Einheit: W. 0xFFFF = deaktiviert |
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::enableGc(enable) / RbAmp::setEventThresholds(i_amps, p_watts) |
GC am Modul aktivieren; die Strom- und Leistungsschwellen setzen |
| ESP-IDF | rbamp_enable_gc() / rbamp_set_event_thresholds() |
GC am Modul aktivieren; die Strom- und Leistungsschwellen setzen |
| Python | dev.enable_gc(enable=True) / dev.read_event_flags() |
General Call auf einem Modul aktivieren; Ereignisflags lesen (kein Schwellwert-Setter am Gerät) |
| ESPHome | fleet_gc_enable: / group_id: |
YAML-Optionen für die Aktivierung des Allgemeinen Aufrufs und die Gruppen-ID |
4.5 Adresse (0x30..0x31)
| Adr | Name | Größe | Typ | Zugriff | Persistenz | Hinweise |
|---|---|---|---|---|---|---|
0x30 |
I2C_ADDRESS |
1 | u8 | rw | user_config | Zwei-Phasen-Commit: Kandidaten-0x08..0x77 in die RAM-Vorbereitung schreiben; ADDR_COMMIT_MAGIC scharf schalten; dann CMD_COMMIT_ADDR; wirkt nach dem Reset. Beim Start wird die aktive Adresse zurückgelesen (v1.3 Korrektur 4) |
0x31 |
ADDR_COMMIT_MAGIC |
1 | u8 | w | ram | Schreiben Sie 0xA5, um CMD_COMMIT_ADDR scharf zu schalten. Wird beim Commit-Versuch verbraucht (gelöscht). Lesezugriffe liefern 0x00 |
Die Reihenfolge finden Sie in §6.1.
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::prepareAddressChange(new_addr) / RbAmp::readActiveAddress(out) |
Neue Adresse vorbereiten und scharf schalten; die aktive Adresse lesen |
| ESP-IDF | rbamp_prepare_address_change() / rbamp_read_active_address() |
Neue Adresse vorbereiten und scharf schalten; die aktive Adresse lesen |
| Python | dev.prepare_address_change(new_addr) / dev.commit_address_change() |
neue Adresse vorbereiten und scharf schalten, dann committen |
| ESPHome | new_address: |
einmalige Adressänderung beim Start; danach die Option entfernen |
4.6 Gesundheit / Diagnose (0x46..0x4F)
| Adr | Name | Größe | Typ | Zugriff | Persistenz | Hinweise |
|---|---|---|---|---|---|---|
0x46 |
UPTIME_S |
4 | u32 LE | r | ram | Eigener Betriebszeitzähler des Moduls (nominell Sekunden seit dem Start) — nur Neustarterkennung: Bei Firmware bis 1.4.21 läuft er langsamer als die Wanduhr (gemessen 0.58–0.80×), daher nie als Uhr verwenden. Neustarterkennung für einen Master: Der Wert ist gesunken oder kleiner als die seit dem vorherigen Snapshot des Masters verstrichene Zeit |
0x4A |
RESET_CAUSE |
1 | u8 | r | ram | Reset-Ursachenflags (Bit0=PIN, Bit1=POR/BOR, Bit2=SW, Bit3=IWDG, Bit4=WWDG, Bit5=LPWR). Nur zur Protokollierung — die Neustartbehandlung ist unabhängig von der Ursache gleich |
0x4B |
I2C_ERR_COUNT |
2 | u16 LE | r | ram | Bus-Fehler (BERR+OVR) seit dem Start, begrenzt (sättigend) |
0x4D |
I2C_REINIT_COUNT |
1 | u8 | r | ram | Anzahl der Wiederherstellungen der I²C-Peripherie nach BUSY-Zuständen, begrenzt (sättigend) |
0x4E |
ZC_OFFSET |
2 | u16 LE | r | ram | µs von der letzten STOP-Flanke des GC-Snapshots bis zum nächsten Nulldurchgang der Spannung — dient der U/I-Phasenkompensation bei der Leistungsberechnung. Bei reinen I-Varianten auf 0xFFFF festgelegt (kein Spannungs-Frontend → kein Spannungs-ZC). Dies ist nicht die Quelle des Netzfrequenz-ZC — AC_FREQ (0x20) stammt von einem eigenen Netz-ZC-Pin und ist bei allen Varianten verfügbar. |
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | — | BASIC-Gesundheitsregister nicht verfügbar (nur STD-Linie) |
| ESP-IDF | rbamp_read_uptime_s() |
die Betriebszeit des Moduls in Sekunden lesen |
| Python | — | BASIC-Gesundheitsregister nicht verfügbar (nur STD-Linie) |
| ESPHome | — | keine Betriebszeit- oder Gesundheitsentität |
4.7 Prüfspiegel des CT-Modells (0x51..0x53)
Nur-Lese-Spiegel der übernommenen CT-Modellvoreinstellung je Kanal. Das Schreib-Protokoll bleibt unverändert (siehe §6.2) — dies ist ausschließlich ein Rücklesewert zur Prüfung.
| Adr | Name | Größe | Typ | Zugriff | Persistenz | Hinweise |
|---|---|---|---|---|---|---|
0x51 |
CT_MODEL_CH0 |
1 | u8 | r | user_config | Übernommene CT-Modell-Voreinstellung auf Kanal 0 (Prüfspiegel) |
0x52 |
CT_MODEL_CH1 |
1 | u8 | r | user_config | Übernommene CT-Modellvoreinstellung auf Kanal 1 |
0x53 |
CT_MODEL_CH2 |
1 | u8 | r | user_config | Angewendete CT-Modell-Voreinstellung auf ch2 |
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::readCTModelCh(channel, out) |
das tatsächlich auf einem Kanal angewendete CT-Modell lesen |
| ESP-IDF | rbamp_read_ct_model_ch() |
das tatsächlich auf einem Kanal angewendete CT-Modell lesen |
| Python | dev.read_ct_model_ch(ch) |
das tatsächlich auf einem Kanal angewendete CT-Modell lesen |
| ESPHome | Boot-Protokoll ct_model[0]: matches |
Protokollzeilen, die bestätigen, dass Sensorklasse und Modell übernommen wurden |
4.8 Identität (0x54..0x6F)
| Adr | Name | Größe | Typ | Zugriff | Persistenz | Hinweise |
|---|---|---|---|---|---|---|
0x54 |
PRODUCT_ID |
1 | u8 | r | von | Familie: 0x01 = rbAmp-Sensor. Der Master liest dies vor jedem familienspezifischen Register |
0x55 |
HW_VARIANT |
1 | u8 | r | von | Siehe §3.1 |
0x56 |
FW_TIER |
1 | u8 | r | von | Bit 0–1: 0=BASIC, 1=STANDARD (2 = nicht implementiert); Bit 2=bidirektional; Bit 3=LUT-kalibriert |
0x57 |
CAPABILITY |
2 | u16 LE | r | von | Siehe §3.2 |
0x59 |
GC_TICK |
2 | u16 LE | r | ram | Master-Tick des letzten akzeptierten GC-Frames; 0xFFFF = nie empfangen |
0x5C |
UID |
12 | Byte | r | von | 96-Bit-Chip-UID. Ein Burst-Lesezugriff. |
0x68 |
LABEL |
8 | Byte | rw | user_config | Benutzerdefinierte Standortbezeichnung (ASCII, mit Nullen aufgefüllt). Leer = nicht gesetzt. Byte für Byte schreiben (siehe §5.1) |
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::readProductId() / RbAmp::readUid(uid) |
Familien-ID lesen; die 96-Bit-UID lesen |
| ESP-IDF | rbamp_read_product_id() / rbamp_read_uid() |
Familien-ID lesen; die 96-Bit-UID lesen |
| Python | dev.read_product_id() / dev.read_uid() |
Familien-ID lesen; die 96-Bit-UID lesen |
| ESPHome | get_uid_hex() / get_variant_str() |
die UID als Hex; die Variante als Text |
4.9 Digest-Fenster (0x70..0x85)
DIGEST ist ein kompaktes Polling-Fenster, bedient durch einen einzelnen Burst-Lesezugriff. Seine Zusammensetzung wird über DIGEST_CONFIG (0x29) gewählt; ein Schreibvorgang, der ein nicht unterstütztes Bit setzt, wird mit ERR_PARAM abgelehnt:
Bit von DIGEST_CONFIG |
Inhalt | Format |
|---|---|---|
| Bit 0 | I_RMS[N] |
u16 je Kanal, 0.01 A |
| Bit 1 | U_RMS |
u16, 0.1 V (nur Spannungs-HW) |
| Bit 2 | P_REAL[N] |
i16 je Kanal, 1 W (nur has_power) |
| Bit 3 | PF[N] |
u8 je Kanal, 0..100 (nur has_power) |
| Adr | Name | Größe | Typ | Zugriff | Persistenz | Hinweise |
|---|---|---|---|---|---|---|
0x70 |
DIGEST |
22 | Byte | r | ram | Aufbau: [STATUS_MIRROR u8][SEQ u8] + maskengesteuerte Felder. Die maximale Nutzlast (UI3 volle Maske) beträgt 19 B + 2 B Kopf = 21 B belegt; 1 B Ende ungenutzt (liefert 0x00). SEQ wird je RT-Commit erhöht und läuft von 255 auf 0 zurück. Atomar durch Lese-Einfrieren (siehe §5.4). |
Das Layout ist dynamisch je DIGEST_CONFIG — jedes aktivierte Bit hängt seine Felder in fester Reihenfolge an: I_RMS[N] → U_RMS → P[N] → PF[N]. Deaktivierte Bits lassen kein Auffüllen — die Felder rücken nach. Der Master muss mit derselben Maske parsen, die er in DIGEST_CONFIG geschrieben hat. Ein Burst-Lesen von 22 Byte ist sicher (der Rest ist 0x00, solange die Gesamtnutzlast < 22 Byte beträgt). Das einzelne Rest-Byte ist immer 0x00 (reserviert).
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | — | Digest-Fenster nicht verfügbar |
| ESP-IDF | rbamp_set_digest_fields() / rbamp_read_digest() |
die Digest-Felder wählen; sie in einer Transaktion lesen (BASIC) |
| Python | — | Digest-Fenster nicht verfügbar |
| ESPHome | — | Digest-Fenster nicht verfügbar |
4.10 V03-Echtzeitblock (0x86..0xBD)
Alles float32 LE (IEEE 754 Single Precision, übliche Little-Endian-Byte-Reihenfolge). Das Byte-Layout ist ab v1.2 festgeschrieben. Jedes Register hat den Zugriff r, die Speicherung ram und die Gruppe v03_rt. Atomar durch Read-Freeze (siehe §5.4): Ein 56-Byte-Burst-Lesezugriff (0x86..0xBD) ist garantiert zusammenhängend (kein zerrissener Snapshot).
| Adr | Name | Größe | Typ | Zugriff | Persistenz | Einheiten | Hinweise |
|---|---|---|---|---|---|---|---|
0x86 |
V03_U_RMS |
4 | float32 LE | r | ram | V | 0.0 bei I-Varianten |
0x8A |
V03_U_PEAK |
4 | float32 LE | r | ram | V | |
0x8E |
V03_I0_RMS |
4 | float32 LE | r | ram | A | |
0x92 |
V03_I1_RMS |
4 | float32 LE | r | ram | A | 0.0, wenn die Variante keinen Kanal 1 hat |
0x96 |
V03_I2_RMS |
4 | float32 LE | r | ram | A | 0.0, wenn die Variante keinen Kanal 2 hat |
| ⛔ | STOP — der flache RMS-Wert je Kanal endet bei Kanal 2. | Die nächste Zeile (0x9A) ist V03_I0_PEAK, NICHT V03_I3_RMS. Das Schema aus Schritt 4 NICHT über Kanal 2 hinaus fortschreiben — Sie erhalten plausible, aber stillschweigend falsche Werte (Spitzenwert statt Effektivwert; Kanal 0 statt Kanal 3). Die Kanäle 3+ (UI5/UI7) werden nur über das Kanalzugriffsfenster angesprochen — siehe §4.14. |
|||||
0x9A |
V03_I0_PEAK |
4 | float32 LE | r | ram | A | |
0x9E |
V03_I1_PEAK |
4 | float32 LE | r | ram | A | |
0xA2 |
V03_I2_PEAK |
4 | float32 LE | r | ram | A | |
0xA6 |
V03_P0_REAL |
4 | float32 LE | r | ram | W | 0.0 bei I-Varianten (keine Leistungsberechnung) |
0xAA |
V03_P1_REAL |
4 | float32 LE | r | ram | W | |
0xAE |
V03_P2_REAL |
4 | float32 LE | r | ram | W | |
0xB2 |
V03_PF0 |
4 | float32 LE | r | ram | – | Bereich −1..+1 |
0xB6 |
V03_PF1 |
4 | float32 LE | r | ram | – | |
0xBA |
V03_PF2 |
4 | float32 LE | r | ram | – |
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::readAll(snapshot) / RbAmp::channels() |
den gesamten Echtzeitblock lesen; Anzahl der Stromkanäle |
| ESP-IDF | rbamp_read_all() / rbamp_channels() |
den gesamten Echtzeitblock lesen; Anzahl der Stromkanäle |
| Python | dev.read_all() / dev.channels |
den gesamten Echtzeitblock lesen; Anzahl der Stromkanäle |
| ESPHome | voltage / power |
YAML-Sensoren für die Echtzeitwerte |
4.11 V03-Periodenblock (0xBE..0xCF)
Ein Periodenschnappschuss, aufgenommen bei CMD_LATCH_PERIOD. Uneinheitliches Layout (historisches Erbe aus v1.2, bei v1.3 eingefroren): avg_p für Kanal 1/2 steht hier, während avg_p für Kanal 0 in §4.12 an der Adresse 0xDC liegt (die alte Energiegrundgröße wurde nicht verlegt, um bestehende Integratoren nicht zu brechen). Logisch gehören diese drei Werte zur selben Gruppe.
| Adr | Name | Größe | Typ | Zugriff | Persistenz | Einheiten | Hinweise |
|---|---|---|---|---|---|---|---|
0xBE |
V03_PERIOD_COMMIT_CNT |
4 | u32 LE | r | ram | – | RT-Commits in der abgeschlossenen Periode. Ein Commit = 0.1 s ab v1.2 (zuvor 0.2 s) — Anzahl × Commit-Länge ist die eigene Messung des Moduls für die Fensterlänge (siehe §7.4) |
0xC2 |
V03_PERIOD_AVG_P_CH1 |
4 | float32 LE | r | ram | W | Schnappschuss Mittelwert P, Kanal 1 (UI2, UI3) |
0xC6 |
V03_PERIOD_AVG_P_CH2 |
4 | float32 LE | r | ram | W | Schnappschuss Mittelwert P, Kanal 2 (UI3) |
0xCA |
V03_PERIOD_MS |
4 | u32 LE | r | ram | ms | Dauer der aktuellen Periode |
0xCE |
V03_STATUS |
1 | u8 | r | ram | – | Bit 0 = gültig (Ergebnis des RT-Commits). NICHT beim Lesen gelöscht. Der Master fragt STATUS (0x00) ab, um auf die Bereitschaft zu warten. Der Alias DATA_VALID wird in Tutorial-Kapiteln manchmal für dieses Register verwendet — gleiche Adresse, gleiche Semantik. |
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::readPeriodAvgPower(ch) / RbAmp::readPeriodSnapshot() |
die mittlere Periodenleistung lesen; einen vollständigen Periodenschnappschuss auslösen und lesen |
| ESP-IDF | rbamp_read_period_avg_power() / rbamp_read_period_snapshot() |
die mittlere Periodenleistung lesen; einen vollständigen Periodenschnappschuss auslösen und lesen |
| Python | dev.read_period_avg_power(ch) / dev.read_period_snapshot() |
die mittlere Periodenleistung lesen; einen vollständigen Periodenschnappschuss auslösen und lesen |
| ESPHome | update_interval: / latch_interval: |
YAML-Optionen für Periode und Schnappschussintervall |
4.12 V03 Q + Periode ch0 (0xD0..0xE3, Produktionsbuild)
| Adr | Name | Größe | Typ | Zugriff | Persistenz | Einheiten | Hinweise |
|---|---|---|---|---|---|---|---|
0xD0 |
V03_Q0_REAC |
4 | float32 LE | r | ram | VAr | Blindleistung Kanal 0 = √(S² − P²), S = U_rms × I_rms — ohne Vorzeichen (≥ 0), enthält die Verzerrungsleistung; 0 bei reinen I-Varianten; bei PF ≈ 1 verrauscht. Genauigkeit nicht spezifiziert |
0xD4 |
V03_Q1_REAC |
4 | float32 LE | r | ram | VAr | |
0xD8 |
V03_Q2_REAC |
4 | float32 LE | r | ram | VAr | |
0xDC |
V03_PERIOD_AVG_P |
4 | float32 LE | r | ram | W | PRODUKTIONS-Energiegrundgröße: Snapshot des mittleren P ch0, ≥ 0 (BASIC-einseitige Zange). Logisch gruppiert mit V03_PERIOD_AVG_P_CH1/CH2 (§4.11); das alte Layout bleibt aus Kompatibilitätsgründen erhalten |
0xE0 |
V03_PERIOD_MAX_P |
4 | float32 LE | r | ram | W | Snapshot-Maximum P ch0 in dieser Periode |
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::readPeriodAvgPower(ch) / RbAmp::readPeriodMaxPower() |
den Mittel- und Spitzenwert der Leistung der Periode lesen |
| ESP-IDF | rbamp_read_period_avg_power() / rbamp_read_period_max_power() |
den Mittel- und Spitzenwert der Leistung der Periode lesen |
| Python | dev.read_period_avg_power(ch) / dev.read_period_max_power() |
den Mittel- und Spitzenwert der Leistung der Periode lesen |
| ESPHome | reactive_power / update_interval: |
Blindleistungssensor; jede Aktualisierung schließt die Periode ab und liest die Mittelwerte |
4.13 Diagnose-dt auf Chipseite (0xEC)
| Adr | Name | Größe | Typ | Zugriff | Persistenz | Einheiten | Hinweise |
|---|---|---|---|---|---|---|---|
0xEC |
V03_PERIOD_LATCH_MS |
4 | u32 LE | r | ram | ms | dt auf Chipseite zwischen den beiden letzten Schnappschüssen. Diagnosetimer des Moduls — er kann unter Last zu niedrig anzeigen; für Energie den Master-Takt verwenden. Siehe §7.4 |
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::readPeriodLatchMs() |
Periodenlänge auf Modulseite lesen (nur Diagnose) |
| ESP-IDF | rbamp_read_period_latch_ms() |
Periodenlänge auf Modulseite lesen (nur Diagnose) |
| Python | dev.read_period_latch_ms() |
Periodenlänge auf Modulseite lesen (nur Diagnose) |
| ESPHome | — | nicht verfügbar |
4.14 Kanal-Zugriffsfenster (0x32 + 0x3C..0x3F)
Gilt für UI5 (5-Kanal) und UI7 (7-Kanal) Module. Bei UI1/UI2/UI3 und I1/I2/I3 ebenfalls verfügbar — ein einheitlicher Weg, falls Sie ihn den flachen Registern aus §4.10 vorziehen.
Die Kanäle 3..6 haben keine flachen Kanalregister (im 8-Bit-Adressraum wäre Platz für 8 Byte gewesen, ein flaches Layout hätte aber rund 88 benötigt). Stattdessen wird ein Auswahl-und-Lese-Fenster bereitgestellt:
| Adr | Name | Größe | Typ | Zugriff | Persistenz | Hinweise |
|---|---|---|---|---|---|---|
0x32 |
REG_CHANNEL_SELECT |
1 | u8 | rw | ram | Dies ist eine Registeradresse, NICHT der Befehls-Opcode CMD_SAVE_USER_CONFIG — sie stimmen zahlenmäßig überein. Nennen Sie 0x32 immer zusammen mit dem gemeinten Adressraum (Register oder Befehl). Kodiert als (field << 4) \| channel. Der Bereich des Kanal-Nibbles channel ist 0..15 (reserviert für bis zu 16 Kanäle); das physische Maximum je Artikel ist channels() (7 bei UI7). Ein Auswahlwert, dessen Kanalindex >= channels() ist, wird ohne ERR_PARAM akzeptiert; das Datenfenster liefert dann 0, und Schreibvorgänge darauf werden ignoriert. field gemäß nachstehender Tabelle. Das Schreiben des Auswahlwerts übernimmt den gewünschten Wert in REG_CHANNEL_DATA. |
0x3C..0x3F |
REG_CHANNEL_DATA |
4 | float32 LE | r | ram | Datenpuffer für die Auswahl. float32 LE für alle öffentlichen Felder. |
Feldcodes (oberes Nibble in 0x32):
| Code | Feld | Typ | Zugriff | Bedeutung |
|---|---|---|---|---|
0 |
CHFIELD_I_RMS |
float32 LE | r | Live-Effektivstrom für den gewählten Kanal (Einheit A) |
1 |
CHFIELD_I_PEAK |
float32 LE | r | Live-Spitzenstrom (Einheit A) |
2 |
CHFIELD_P_REAL |
float32 LE | r | Live-Wirkleistung (Einheit W) |
3 |
CHFIELD_PF |
float32 LE | r | Live-Leistungsfaktor (−1..+1) |
4..12 |
(reserved) | – | – | Nicht für Anwendercode dokumentiert; Werte oder Codes nicht darauf stützen. |
13 |
CHFIELD_PERIOD_AVG_P |
float32 LE | r | Mittlere Wirkleistung im Snapshot (W). Für Kanäle 3+ ist dies das EINZIGE Periodenfeld — die flachen V03_PERIOD_AVG_P* (§4.11/§4.12) decken nur ch0..ch2 ab. |
14 |
(reserved) | – | – | Für künftige Firmware reserviert; nicht darauf verlassen. |
15 |
CHFIELD_CT_MODEL |
u8 in 0x3C (Bytes 0x3D..0x3F werden als Null-Auffüllung gelesen) |
rw | Firmware ≥ 1.4.18. CT-Modell-Code je Kanal für den gewählten Kanal (0..N-1). Lesen liefert das übernommene Modell des Kanals. Schreiben wirkt nur im RAM und sofort: Die Skalierung des Kanals wird im selben Vorgang auf die Voreinstellung des gewählten Modells umgeschaltet; kein separater Commit-Befehl, kein CMD_SET_CT_MODEL_CH* nötig. Schreibvorgänge erfolgen Byte für Byte gemäß der Protokollregel für Schreibzugriffe (§5.1). Ein unbekanntes Paar (SENSOR_CLASS, code) liefert ERR_PARAM (0xFE), und der Kanal behält sein bisheriges Modell — kein Teilzustand. Senior-Kanäle (ch3+) übernehmen das globale Modell NICHT mehr — jeder Kanal muss explizit über Feld 15 konfiguriert werden. Speicherung: CMD_SAVE_USER_CONFIG (Opcode 0x32 in REG_COMMAND, ohne Schutzsperre) speichert die Modelle aller Kanäle in einem Befehl auf die Benutzerkonfigurationsseite im Flash. Ein Schreibvorgang ohne anschließendes CMD_SAVE_USER_CONFIG wird beim Neustart zurückgesetzt. Die akzeptierten Paare (class, code) sind in der Modelltabelle Ihrer Firmwareversion definiert; das Modul bestätigt einen Code verbindlich — schreiben, zurücklesen und REG_ERROR prüfen. Auf Modulen mit Firmware v1.4.0 liefert das Schreiben dieses Feldes ERR_PARAM; verwenden Sie stattdessen Befehle je Kanal und das flache Vorbereitungsregister REG_CT_MODEL. |
Die vier Fallen — vor dem Schreiben von Code lesen
- ⛔ Flacher Effektivwert je Kanal endet bei Kanal 2. Die Zeilen
V03_I0_RMS(0x8E) →V03_I1_RMS(0x92) →V03_I2_RMS(0x96) haben Schrittweite 4, und0x9Asetzt den Schritt fort — aber0x9AistV03_I0_PEAK, nichtV03_I3_RMS. Wer das Muster fortschreibt, erhält stillschweigend den Scheitelwert von ch0 statt des Effektivwerts von ch3. Die Firmware kann den Fehler nicht erkennen; der Wert wirkt plausibel. Kanäle 3+ sind nur im Kanal-Zugriffsfenster verfügbar. - Vor jedem Lesen erneut auswählen.
REG_CHANNEL_DATAist ein Schnappschuss zum Zeitpunkt des Auswahlschreibvorgangs, keine Live-Ansicht. Wird0x3C..0x3Fin einer Schleife abgefragt, ohne0x32neu zu schreiben, liefert es für immer einen eingefrorenen Wert. Jeder neue Messwert erfordert einen neuen Schreibvorgang auf0x32. 0x32-Registeradresse ≠0x32-Befehls-Opcode.CMD_SAVE_USER_CONFIGverwendet den Opcode0x32, geschrieben inREG_COMMAND(0x01) — das ist ein anderer Adressraum alsREG_CHANNEL_SELECT(das bei der Registeradresse0x32liegt). Nennen Sie0x32nie ohne Angabe des Adressraums.- Für Kanäle 3+ kommen Periode/Energie nur aus Feld
13(CHFIELD_PERIOD_AVG_P). Die RegisterV03_PERIOD_AVG_P*(0xC2/0xC6/0xDC) decken nur ch0/ch1/ch2 ab. Es gibt kein flachesV03_PERIOD_AVG_P_CH3— lesen Sie stattdessen Feld 13 über das Fenster.
Beispiel auf Leitungsebene — Effektivstrom für Kanal 3 lesen
# select field=0 (I_RMS), channel=3 → (0 << 4) | 3 = 0x03
write_u8(REG_CHANNEL_SELECT=0x32, 0x03)
# read 4 bytes at REG_CHANNEL_DATA — float32 LE
bytes = read(0x3C, 4)
i3_rms = unpack_float32_le(bytes) # amperes
Für den Scheitelstrom von Kanal 4: Selektor = (1 << 4) | 4 = 0x14, dann 0x3C..0x3F lesen. Für die Periodenmittelleistung von Kanal 5: Selektor = (13 << 4) | 5 = 0xD5, dann 0x3C..0x3F lesen.
Beispiel auf Leitungsebene — effektiven Strom auf ALLEN Kanälen eines UI7-Moduls lesen
Kombiniert beide Wege in einer Schleife: flacher RT-Block für Kanal 0..2, Kanalzugriffsfenster für Kanal 3..6.
# --- Discover physical channel count -----------------------------
N = read_u8(TOPOLOGY=0x24) # 5 on UI5, 7 on UI7
# --- ch 0..2 via flat block (single 12-byte burst) ---------------
bytes = read(V03_I0_RMS=0x8E, 12)
i0 = unpack_float32_le(bytes[0:4])
i1 = unpack_float32_le(bytes[4:8])
i2 = unpack_float32_le(bytes[8:12])
# --- ch 3..N-1 via channel access window (re-select per read) ----
i_rms = [i0, i1, i2]
for ch in range(3, N):
write_u8(REG_CHANNEL_SELECT=0x32, (0 << 4) | ch) # field 0 = I_RMS
i_rms.append(unpack_float32_le(read(REG_CHANNEL_DATA=0x3C, 4)))
# i_rms is now length-N: RMS current for every physical channel of the module.
Dasselbe Schema gilt für I_PEAK (Feld 1), P_REAL (Feld 2), PF (Feld 3) und den Periodenschnappschuss PERIOD_AVG_P (Feld 13) — flacher Block für Kanal 0..2, Fenster für Kanal 3+. Feld 13 ist die EINZIGE Quelle für Periode/Energie bei Kanal 3+ — der flache Block hat kein V03_PERIOD_AVG_P_CH3..6.
Für die Konfiguration des CT-Modells pro Kanal auf jedem Kanal (0..N-1) verwenden Sie das Fensterfeld 15 (CHFIELD_CT_MODEL): Schreiben Sie (15 << 4) | ch nach 0x32 und danach den Modellcode als ein Byte nach 0x3C. Speichern Sie die Modelle aller Kanäle mit einem einzigen CMD_SAVE_USER_CONFIG (Opcode 0x32 auf REG_COMMAND (0x01) — ungeschützt).
Empfehlung für neue Integrationen
Das Fenster umfasst die Kanäle 0..6 — Sie können es als einheitlichen Einzelweg für alle Kanäle verwenden, statt zwischen flachen Registern (Kanal 0..2) und dem Fenster (Kanal 3..6) zu verzweigen. Bei Flotten mit gemischten Einsteiger- (UI1/UI2/UI3) und Premium-Artikeln (UI5/UI7) entfällt damit eine Codeaufteilung. Die Latenz beträgt je Messwert einen zusätzlichen kleinen Schreibvorgang (verglichen mit einem direkten Burst-Lesen des flachen Blocks).
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::readCurrent(ch) / RbAmp::channels() |
einen beliebigen Kanal über seinen Index lesen; Anzahl der Kanäle |
| ESP-IDF | rbamp_read_channel() / rbamp_read_all_channels() |
einen Kanal über seinen Index lesen, einschließlich Kanal 3 und höher; alle Kanäle lesen |
| Python | dev.current[ch] / dev.channels |
Index über die gültigen Kanäle; Anzahl der Kanäle |
| ESPHome | current_N: |
Sensor-Slots je Kanal für bis zu sieben Stromkanäle |
5 · Leitungsprotokoll
5.1 Asymmetrie LESEN / SCHREIBEN
Kanonisches, konstruktionsbedingtes Verhalten:
| Richtung | Auto-Inkrement | Muster |
|---|---|---|
| LESEN (Burst-Lesen von N Byte) | ✅ JA | read(addr, N) liefert N aufeinanderfolgende Bytes ab addr. |
| SCHREIBEN (Mehrbyte-Register) | ❌ NEIN | Ein Mehrbyte-Register wird Byte für Byte geschrieben — eine eigene Einzelbyte-Transaktion pro Adresse. Ein Burst-Schreibvorgang verwirft die Bytes 1..N-1 und akzeptiert nur das erste. |
Betroffene beschreibbare Mehrbyte-Register (Byte für Byte schreiben)
LABEL(0x68-0x6F, 8 Byte)THRESH_I_HI(0x2C, 2 Byte u16 LE)THRESH_P_HI(0x2E, 2 Byte u16 LE)
Byte-Reihenfolge bei Mehrbyte-SCHREIBEN: Das Byte an der niedrigeren Adresse ist das niederwertige Byte (LE). Um beispielsweise THRESH_I_HI = 0x1234 (dezimal 4660) zu schreiben:
# CORRECT: low byte first (LE)
write(addr=0x2C, value=0x34) # LO byte
write(addr=0x2D, value=0x12) # HI byte
FALSCHES / RICHTIGES Beispiel (Pseudocode)
# WRONG — only 'M' (first byte) is accepted, the rest are dropped
write(addr=0x50, reg=0x68, data=b"MyMeter1") # 8-byte burst
# CORRECT — byte-at-a-time loop
label = b"MyMeter1"
for i, byte in enumerate(label):
write(addr=0x50, reg=0x68 + i, data=byte)
Ausnahme — GC-Broadcast-Frame
Der GC-Broadcast-Rahmen (0x00-Allgemeiner-Aufruf-Adresse + 5-Byte-Nutzlast) ist ein eigener Protokollpfad, kein Registerschreibvorgang. Die Lese-/Schreib-Asymmetrie aus §5.1 gilt nicht für GC. Siehe §6.3.
5.2 Verhalten nicht abgebildeter Register
Jeder Lesezugriff auf eine nicht abgebildete Adresse liefert 0x00. Die Firmware quittiert Registerlesezugriffe nie mit NACK. Das ist Absicht (Wedge-Fix).
Folgerung für die Erkennung: Das Erkennen eines fehlenden Geräts muss über das ACK des I²C-Adressrahmens erfolgen, nicht über Registerabfragen.
5.3 Fehlermodell
v1.3 kanonisch:
REG_ERROR (0x02)ist das Ergebnis des letzten Schreibvorgangs, NICHT haftend. Bei jedem Registerschreiben setzt die Firmwarereg_error = ERR_OK; jeder nachfolgende, unabhängige Schreibvorgang löscht den vorherigen Fehler.EVENT_FLAGS (0x2A) Bit 3ist das dauerhafte Signal (haftend, W1C), gesetzt bei jedem abgelehnten Schreib- oder Befehlsvorgang.
Fehlercodes
| Code | Name | Schweregrad |
|---|---|---|
0x00 |
OK | – |
0xF9 |
CLONE |
reserviert — wird nicht ausgelöst |
0xFA |
LUT_BAD |
Fehler |
0xFB |
FLASH_PARAMS_BAD |
Fehler (siehe §6.5 Erstflash) |
0xFC |
NOT_READY |
Fehler |
0xFD |
SENSOR_OVERFLOW |
Fehler |
0xFE |
PARAM |
Fehler (abgelehnter Schreibvorgang — ungültiges Argument / unbekannter Opcode / Wert außerhalb der Aufzählung; setzt EVENT.bit3. Sehr frühe Images, 1.2–1.4.3, ignorierten unbekannte Opcodes stillschweigend) |
0xFF |
UNHANDLED |
Fehler |
Aufbau von EVENT_FLAGS (0x2A) (klebend, W1C)
| Bit | Name | Hinweise |
|---|---|---|
| 0 | PERIOD_READY |
Periodenschnappschuss verfügbar |
| 1 | THRESH_I |
I_rms hat THRESH_I_HI überschritten |
| 2 | THRESH_P |
Die P-Summe hat THRESH_P_HI überschritten |
| 3 | ERROR |
REG_ERROR != 0 (dauerhaftes Fehlersignal) |
| 4 | CONFIG_CHANGED |
Klasse/Modell/Adresse/Bezeichnung geändert |
| 5 | RESET_OCCURRED |
Modul neu gestartet (bei Start gesetzt, bis W1C). Der Master muss die RAM-Konfiguration neu initialisieren. |
Kanonische Fehlermuster
Muster 1 — einmalige Erfassung nach dem Vorgang (Ergebnis genau dieses Vorgangs):
write target_reg(...)
err = read_u8(0x02) # IMMEDIATELY after the operation, before the next write
Muster 2 — dauerhafte Überwachung (kanonisch für einen langlaufenden Master):
event_flags = read_u8(0x2A)
if event_flags & (1 << 3): # ERROR bit
last_err = read_u8(0x02)
# handle
write_u8(0x2A, 1 << 3) # W1C clear bit 3
# or CMD_CLEAR_ERROR
⚠ Vorbehalt zu Bit 3 (asynchron)
Eine Schreibablehnung setzt EVENT_FLAGS.bit3 asynchron, innerhalb eines Messfensters (~100 ms ab v1.2; 200 ms bei Images vor v1.2) nach dem Vorgang, nicht sofort. Bit 3 nicht unmittelbar nach einem Schreibvorgang abfragen — entweder ≥ 200 ms warten (deckt alle Images ab) oder für das Ergebnis eines bestimmten Vorgangs Muster 1 (sofortige Erfassung von REG_ERROR) verwenden und das Abfragen von Bit 3 für langlaufende Überwachung reservieren.
Anti-Klon-Wächter
DEV_ERR_CLONE (0xF9) ist reserviert — er wird nie ausgelöst. Der Code wird aus Gründen der Vorwärtskompatibilität beibehalten.
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::readLastError() / RbAmp::hasError(out) |
den Fehlercode des letzten Schreibvorgangs lesen; das dauerhafte Fehler-Flag lesen |
| ESP-IDF | rbamp_read_last_error() / rbamp_has_error() |
den Fehlercode des letzten Schreibvorgangs lesen; das dauerhafte Fehler-Flag lesen |
| Python | dev.read_last_error() / dev.has_error() |
den Fehlercode des letzten Schreibvorgangs lesen; das dauerhafte Fehler-Flag lesen |
| ESPHome | get_last_error_str() / get_event_flags() |
den Fehlercode als Text; die Ereignisflags |
5.4 Atomarität / Read-Freeze-Semantik
5.4.1 Read-Freeze vorhanden (atomar — NICHT zerrissen)
Diese Blöcke sind durch das firmwareseitige Lese-Einfrieren geschützt. Ein Burst-Lesen ist gegenüber dem RT-Commit atomar:
- V03-RMS-/P-/PF-Block (0x86..0xBD) — der vollständige Gleitkommablock.
- Digest-Block (0x70..0x85).
Burst-Lesezugriffe auf diese Bereiche sind sicher — zwischen zwei aufeinanderfolgenden Commits gibt es kein geteiltes Sample.
5.4.2 Kein Lese-Einfrieren — zweimal-lesen-übereinstimmend empfohlen
Diese Register werden asynchron aktualisiert, ohne Lese-Einfrieren innerhalb des Lesens. Einzelbyte-Lesezugriffe sind tolerant, der Wert kann sich aber zwischen den Transaktionen ändern:
GC_TICK (0x59)— GC-Tick-Zähler.I2C_ADDRESS (0x30)— Spiegel der RAM-Vorbereitung.CT_MODEL_CH0/1/2 (0x51..0x53)— Gegenprüfungsspiegel.
Muster für zuverlässige Lesevorgänge:
val1 = read_u8(addr)
val2 = read_u8(addr)
if val1 == val2:
return val1 # stable
else:
retry # value changed between reads
5.4.3 Semantik der NF-Zange
I_RMS = 0x00000000 bedeutet „Signal unter der Rauschgrenze“ (die Firmware berechnet rms_corr² = max(0, raw² − nf²)), NICHT „keine Daten“ / „Fehler“. Es ist eine gültige Messung für Leerlauf- bzw. Kleinstlastsituationen.
Der Master-Code darf I_RMS = 0.0 nicht als Fehler oder fehlende Daten werten.
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::readAll(snapshot) |
den gesamten Echtzeitblock in einem Aufruf lesen |
| ESP-IDF | rbamp_read_all() |
den gesamten Echtzeitblock in einem Aufruf lesen |
| Python | dev.read_all() |
den gesamten Echtzeitblock in einem Aufruf lesen |
| ESPHome | Burst-Lesen des Momentanwert-Blocks | die Komponente liest den Momentanwert-Block pro Update in einem Burst |
6 · Protokollabläufe
6.0 Kaltstart-Zeitablauf
Nach POR (Einschalt-Reset) oder hartem Reset durchläuft das Modul folgende Phasen:
| Zeit ab POR | Zustand |
|---|---|
| 0 ms | POR — alle Register im Rücksetzzustand, SCL/SDA hochohmig |
| ~10 ms | Busantwortend (das Modul bestätigt seine Adresse mit ACK) |
| ~50 ms | Erster RT-Commit (der RT-Block ab 0x86 enthält gültige Daten; STATUS.bit0 = 1) |
| ~60–80 ms | Erstes gültiges V03_STATUS.bit0 (die RT-Pipeline hat eine volle Netzperiode durchlaufen) |
| ca. 100 ms | Der erste CMD_LATCH_PERIOD kann V03_PERIOD_VALID = 1 zurückgeben (ein Snapshot erfordert mindestens 1 Netzperiode Akkumulation; ~200 ms bei Images vor v1.2) |
| ~250 ms | Alle Messwerte stabil (typisch) |
Gesamter Kaltstart bis zur ersten gültigen Messung ≈ 250 ms (typisch). Nach einem weichen CMD_RESET ist der Zeitablauf identisch (die vollständige Reset-Zustandsmaschine läuft).
Master-Initialisierungsablauf:
1. wait ~50 ms after VCC stable
2. probe slave address (read PRODUCT_ID = 0x54); retry up to 300 ms on NACK
3. read identity (HW_VARIANT 0x55, CAPABILITY 0x57/0x58); validate
4. check REG_ERROR (0x02):
- 0x00 — normal boot
- 0xFB — fresh flash, provisioning required (§6.5)
- other — see §6.7 error-state recovery
5. configure (SENSOR_CLASS, CT_MODEL, FLEET_CONFIG, etc.)
6. poll STATUS (0x00) until bit0 = 1 (READY) — usually immediate after step 5
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::begin() / RbAmp::waitReady(timeout_ms) |
das Modul abfragen, dann auf das Bereit-Flag warten |
| ESP-IDF | rbamp_begin() / rbamp_wait_ready() |
das Modul abfragen, dann auf das Bereit-Flag warten |
| Python | dev.begin() / dev.wait_ready(timeout_ms=1000) |
das Modul abfragen, dann auf das Bereit-Flag warten |
| ESPHome | rbamp: address: |
Modul-Adresse im YAML gesetzt; die Komponente prüft das Modul beim Setup |
6.1 Adressänderung — Zwei-Phasen-Commit (produktionstauglich)
Wire-Protokoll (kanonisch v1.3):
1. write candidate_addr (1 byte) → REG_I2C_ADDRESS (0x30) # RAM staging, not persisted
2. write 0xA5 → REG_ADDR_COMMIT_MAGIC (0x31) # arm commit
3. issue CMD_COMMIT_ADDR (opcode 0x30 in REG_COMMAND) # persists into flash
4. wait ~700 ms (flash write completion; see §6.6 settle)
5. issue CMD_RESET (opcode 0x01) # module resets
6. wait ~300 ms boot-to-responsive
7. verify: bus-probe the new address (ACK = success)
: CMD_COMMIT_ADDR startet das Modul NICHT automatisch neu — in Schritt 5 ist ein ausdrücklicher CMD_RESET nötig. Überspringt der Master den ausdrücklichen Reset, bleibt die neue Adresse im Flash gespeichert, doch die alte Adresse bleibt bis zum nächsten externen Reset aktiv (Netz aus/ein, Hardware-Reset-Pin, IWDG).
Guarantees:
- Die Adressänderung funktioniert im Produktionsmodus (nicht werkseitig gesperrt).
REG_I2C_ADDRESS (0x30)liefert beim Booten die aktive Adresse (v1.3 kanonisch). Bis zum Neustart nach dem Staging spiegelt es den Kandidaten zurück.- Die Adresse ist ausgenommen vom Namensraum
CMD_SAVE_GAINS/CMD_SAVE_USER_CONFIG— sie wird nur überCMD_COMMIT_ADDRgespeichert.
Zeitfenster nach dem Start für die Prüfung:
- Mindestens 300 ms vom Booten bis zur Reaktionsfähigkeit.
- Wiederholungsfenster auf der neuen Adresse: insgesamt ~1 s (wenn ein NACK nach 1–2 Wiederholungen bestehen bleibt, kann eine zusätzliche Bootverzögerung nötig sein).
- Sobald die neue Adresse antwortet, optional durch Lesen von
0x30bestätigen (spiegelt nun die neue aktive Adresse).
Fehlerbilder:
ADDR_COMMIT_MAGICnicht scharf →CMD_COMMIT_ADDR→REG_ERROR = ERR_PARAM (0xFE).- Kandidat außerhalb des Bereichs (< 0x08 oder > 0x77) →
ERR_PARAM. - 5 s Timeout ohne Commit → Magic wird gelöscht; der Schritt
preparemuss wiederholt werden.
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::prepareAddressChange(new_addr) / RbAmp::commitAddressChange() |
neue Adresse vorbereiten und scharf schalten, dann committen |
| ESP-IDF | rbamp_prepare_address_change() / rbamp_commit_address_change() |
neue Adresse vorbereiten und scharf schalten, dann committen |
| Python | dev.prepare_address_change(new_addr) / dev.commit_address_change() |
neue Adresse vorbereiten und scharf schalten, dann committen |
| ESPHome | new_address: |
einmalige Adressänderung beim Start; danach die Option entfernen |
6.2 CT-Modell-Zuordnung — reine Vorbereitung + CMD je Kanal
Bei Images vor Firmware 1.4.20 (CAPABILITY Bit 12 gelöscht) fällt die übernommene Skalierung je Modell nach einem Neustart des Moduls auf die Werkseinstellung zurück — bringen Sie CT_MODEL je Kanal nach jedem erkannten Neustart erneut in die Vorbereitung und festschreiben, sonst ist die Energie falsch.
v1.3 reines Staging, kanonisch: Das Schreiben von REG_CT_MODEL (0x05) wendet die Voreinstellung auf ch0 nicht mehr automatisch an. Die Zuordnung erfolgt nur über CMD_SET_CT_MODEL_CHn.
Kanonisches Protokoll je Kanal (reihenfolgeunabhängig in v1.3):
1. write REG_SENSOR_CLASS (0x25) = sct013 # if not already set
2. write REG_CT_MODEL (0x05) = model_code # stages, applies nothing
3. issue CMD_SET_CT_MODEL_CHn (opcode 0x28/0x29/0x2A for ch0/1/2)
# VALIDATES (class, model) + binds to channel n
4. wait 5 ms settle
5. (optional) issue CMD_SAVE_USER_CONFIG (opcode 0x32) for persistence
Reihenfolgeunabhängig: Bei v1.3 dürfen Kanäle in beliebiger Reihenfolge konfiguriert werden — ch0 zuerst, zuletzt oder wie es gerade passt. Die Umgehung „ch0 zuletzt binden“ aus v1.2 ist nicht mehr nötig.
Rücklesekontrolle: Nach der Zuordnung CT_MODEL_CH0/1/2 (0x51..0x53) auslesen — diese Register spiegeln den übernommenen Zustand je Kanal wider.
Fehlerfälle (Prüfung von (Klasse, Modell) erfolgt beim Schritt CMD_SET_CT_MODEL_CHn-Bind, nicht beim reinen Staging-Schreiben nach 0x05):
SENSOR_CLASS = 0(NICHT GESETZT), wennCMD_SET_CT_MODEL_CHnausgegeben wird →REG_ERROR = ERR_PARAM.CT_MODELaußerhalb von 1..7 (SCT-013-005/-010/-030/-050/-100/-020/-060) beiCMD_SET→ERR_PARAM.
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::setSensorClass(cls) / RbAmp::setCTModel(channel, code) |
Sensorklasse und CT-Modell je Kanal setzen |
| ESP-IDF | rbamp_set_sensor_class() / rbamp_set_ct_model_ch() |
Sensorklasse und CT-Modell je Kanal setzen |
| Python | dev.set_sensor_class(cls) / dev.set_ct_model_ch(channel, code) |
Sensorklasse und CT-Modell je Kanal setzen |
| ESPHome | sensor_class: / ct_model: |
YAML-Optionen für Sensorklasse und CT-Modell |
6.3 GC-Broadcast-Schnappschuss — optionale Flottensynchronisation
Pro Modul aktivierbar über REG_FLEET_CONFIG.bit0 (GC_ENABLE). Standardmäßig AUS. Die Änderung wirkt nach einem Reset (weicher CMD_RESET oder harter Reset).
6.3.1 Aktivierungsablauf (einmal je Modul)
1. write REG_FLEET_CONFIG (0x27) = 0x01 # bit0 = GC_ENABLE
2. issue CMD_SAVE_USER_CONFIG (opcode 0x32, ungated)
3. issue CMD_RESET (opcode 0x01)
4. wait ~300 ms boot
5. verify: read REG_FLEET_CONFIG → bit 0 should be 1
6.3.2 GC-Frame-Format
I²C general-call address 0x00 | A5 27 (5-byte payload)
A5— Frame-Magic.27— OpcodeCMD_LATCH_PERIOD.—0x00= alle; andernfalls muss sie mit demREG_GROUP_ID (0x28)des Geräts übereinstimmen.— 16-Bit-Tick-Zähler auf Master-Seite (für die geräteübergreifende Fensternummerierung und die Erkennung verpasster Rahmen je Modul überGC_TICK (0x59)).
Nur Schnappschuss: GC-Rahmen tragen keine zerstörerischen Opcodes (SAVE_*, COMMIT_ADDR, FACTORY_RESET usw.) — konstruktionsbedingt.
6.3.3 Erkennung von Fehlerzuständen — 2-stufig
Stufe 1 — NACK auf GC-Adresse (sofort, auf Busebene):
- Wenn GC in der gesamten Flotte deaktiviert ist → der Master erhält einen harten Fehler (NACK auf Adresse
0x00oder das treiberseitige Äquivalent). - Dies ist ein harter Fehler, KEIN stiller Verlust — der Master kann ihn erkennen und reagieren.
- Auslösung: NACK auf GC = „GC ist auf keinem Gerät der Flotte aktiviert.“
Stufe 2 — Zeuge pro Modul (nach dem Einschwingen):
- Wenn kein NACK erfolgt (mindestens ein Modul hört zu), liest der Master
REG_V03_PERIOD_VALID (0x07)von jedem erwarteten Slave. 1= der Snapshot war an diesem Modul erfolgreich.0= GC ist auf diesem Modul deaktiviert, oder die aktuelle Periode ist leer.
Auf Gerätesnapshot ausweichen, wenn der Zeuge 0 meldet:
foreach module where witness == 0:
write_cmd(module, CMD_LATCH_PERIOD)
sleep(50 ms)
foreach module: read period snapshot with skip_latch=true
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmpFleet::gcLatch(group, tick, settle_ms) / RbAmpFleet::checkSync() |
den General-Call-Snapshot-Frame senden; jedes Modul prüfen |
| ESP-IDF | rbamp_fleet_gclatch() / rbamp_fleet_check_sync() |
den General-Call-Snapshot-Frame senden; jedes Modul prüfen |
| Python | fleet.gc_latch(group, tick, settle_ms) / fleet.check_sync(expected_tick) |
den General-Call-Snapshot-Frame senden; jedes Modul prüfen |
| ESPHome | fleet_gc_enable: / Protokoll der Synchronprüfung |
optionaler General-Call-Snapshot; Protokollzeile, die die Synchronität der Module bestätigt |
6.4 Periodensynchronisation — zwei Strategien
Strategie 1 — sequenzieller Schnappschuss + gemeinsames Einschwingen (jede Firmware)
for module in modules:
write_cmd(module, CMD_LATCH_PERIOD)
sleep(50 ms)
for module in modules:
read_period_snapshot(module) # skip_latch=true
Versatz zwischen Modulen: ca. 1 ms pro Modul bei 50 kHz. Bei 16 Modulen bezogen auf eine 60-Sekunden-Periode sind das 0.027 %. Vernachlässigbar für die Tarifabrechnung.
Einschwingzeit nach CMD_LATCH_PERIOD:
- Mindestens 50 ms warten, bevor Sie
V03_PERIOD_VALID (0x07)oder den Periodenschnappschuss lesen — das deckt die ungünstigste Snapshot-Latenz ab (1 Netzperiode bei 50 Hz = 20 ms + RT-Commit + Einschwingen des I²C-Peripheriegeräts). - Optional kann der Master
STATUS.bit0 (READY)abfragen, statt einen festen Sleep zu verwenden:READY=1bedeutet, dass der RT-Block konsistent ist, sodass der Periodenschnappschuss sicher im Burst gelesen werden kann. - Bei einem brandneuen Modul (< ~100 ms nach dem Booten ab v1.2; < 200 ms davor) kann ein Snapshot
V03_PERIOD_VALID = 0liefern, weil weniger als 1 Netzperiode akkumuliert wurde — siehe §6.0 Kaltstart-Zeitablauf.
Strategie 2 — General-Call-Broadcast-Snapshot (Aktivierung nötig)
Versatz = 0 (atomar auf Busebene). Siehe §6.3.
Wann was zu verwenden ist:
- < 8 Module: Strategie 1 (einfacher, keine Freigabe nötig).
- ≥ 8 Module oder enge Synchronisation: Strategie 2.
- Eine Methode je Modul: der adressierte
CMD_LATCH_PERIODund der GC-Broadcast-Schnappschuss setzen denselben einzigen Akkumulator zurück — werden beide an einem Modul gemischt, endet die laufende Periode vorzeitig. Der Ersatzweg je Modul (§6.3.3) ist sicher, da er nur bei einem Modul auslöst, das der Broadcast nicht erreicht hat.
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::readPeriodSnapshot(..., skip_latch=true) / RbAmpFleet::gcLatch() |
sequenzielles Lesen nach einem gemeinsamen Schnappschuss; Rahmen für den Allgemeinen-Aufruf-Schnappschuss |
| ESP-IDF | rbamp_read_period_snapshot(..., skip_latch=true) / rbamp_fleet_gclatch() |
sequenzielles Lesen nach einem gemeinsamen Schnappschuss; Rahmen für den Allgemeinen-Aufruf-Schnappschuss |
| Python | sequenzieller Schnappschuss, skip_latch=True / fleet.gc_latch() |
sequenzielles Lesen nach einem gemeinsamen Schnappschuss; Rahmen für den Allgemeinen-Aufruf-Schnappschuss |
| ESPHome | latch_interval: / fleet_gc_enable: |
eigener Snapshot-Takt; freiwilliger General-Call-Snapshot |
6.5 Provisionierung — Erstflash + SAVE
Verhalten eines frisch geflashten Moduls:
- Beim ersten Booten nach dem Firmware-Flash:
REG_ERROR = 0xFB (FLASH_PARAMS_BAD)+EVENT_FLAGS.bit3gesetzt. - Die Parameterseite ist nicht initialisiert → Werkseinstellungen werden geladen.
Das ist für ein unberührtes Modul NORMAL und nicht fatal. Brechen Sie die Provisionierung bei einem 0xFB beim ersten Start nicht ab.
Recovery:
1. configure SENSOR_CLASS + CT_MODEL (per §6.2)
2. (optional) configure FLEET_CONFIG + GROUP_ID + LABEL
3. issue CMD_SAVE_USER_CONFIG (opcode 0x32, ungated)
4. wait ~700 ms (flash write)
5. verify: REG_ERROR = 0x00, EVENT_FLAGS.bit3 cleared
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmpFleet::provision() / RbAmp::saveUserConfig() |
ein neues Modul auf seine Adresse setzen; Benutzerkonfiguration speichern |
| ESP-IDF | rbamp_provision() / rbamp_save_user_config() |
ein neues Modul auf seine Adresse setzen; Benutzerkonfiguration speichern |
| Python | Flotteneinrichtung / dev.save_user_config() |
ein unberührtes Modul provisionieren, dann in die Flotte aufnehmen; Benutzerkonfiguration speichern |
| ESPHome | Einrichtungsablauf / new_address: |
Schritt-für-Schritt-YAML für ein unberührtes Modul; einmalige Adressänderung |
6.7 Wiederherstellung nach Fehlerzustand — Entscheidungsbaum
Wenn beim Booten oder zur Laufzeit STATUS.bit1 (ERROR) = 1 ist oder das dauerhafte Signal EVENT_FLAGS.bit3 (ERROR) gesetzt ist, liest der Master REG_ERROR (0x02) und entscheidet anhand des Codes:
read REG_ERROR (0x02):
0x00 → no error (false signal — clear stale EVENT bit3 via W1C)
action: write 1<<3 → EVENT_FLAGS (W1C clear)
0xF9 → CLONE (reserved)
action: not raised. If ever observed, treat as
vendor-reserved and contact the supplier.
0xFA → LUT_BAD (calibration LUT corrupted)
action: device unusable for measurement. Factory recovery required.
0xFB → FLASH_PARAMS_BAD (params page uninitialized — virgin module)
action: NORMAL for a freshly flashed module. Provision per §6.5
(configure SENSOR_CLASS/CT_MODEL/...; issue CMD_SAVE_USER_CONFIG).
Cleared after a successful SAVE.
0xFC → NOT_READY (transient; module still booting)
action: wait 50 ms, retry. If persistent > 300 ms — power cycle.
0xFD → SENSOR_OVERFLOW (transient; signal saturated)
action: physical overload detected. The chosen CT clamp has
insufficient range for the measured current, or a real overload.
Issue CMD_CLEAR_ERROR (0x31) after the cause is removed.
0xFE → PARAM (last operation rejected — invalid argument / unknown opcode;
EVENT bit3 set. Very early images, 1.2–1.4.3, ignored unknown
opcodes silently)
action: master-side bug — review the last write. Issue CMD_CLEAR_ERROR
after fixing the master logic.
0xFF → UNHANDLED (firmware-side anomaly)
action: open an issue with the vendor; CMD_CLEAR_ERROR attempts to clear.
If persistent after CMD_RESET — the device is suspect.
Allgemeiner Wiederherstellungsablauf bei transienten Fehlern (0xFC/0xFD/0xFE):
1. capture context (what was the last write? master state?)
2. issue CMD_CLEAR_ERROR (opcode 0x31)
3. wait 5 ms
4. re-read STATUS / REG_ERROR — verify cleared
Bei dauerhaften Fehlern — CMD_RESET ausgeben und den Kaltstart-Zeitablauf durchgehen (§6.0). Bleibt der Fehler nach dem Reset bestehen und ist er nicht 0xFB (Erstflash) — wenden Sie sich an den Herstellersupport.
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::readLastError() / RbAmp::clearError() |
den Fehlercode lesen; ihn löschen |
| ESP-IDF | rbamp_read_last_error() / rbamp_clear_error() |
den Fehlercode lesen; ihn löschen |
| Python | dev.read_last_error() / dev.clear_error() |
den Fehlercode lesen; ihn löschen |
| ESPHome | write_clear_error() / write_reset() |
Fehler löschen; weicher Reset des Moduls |
6.6 Befehlsreferenz
Kern-Opcodes (Schreiben in REG_COMMAND (0x01))
| Opcode | Name | Einschwingen | Gesperrt | Hinweise |
|---|---|---|---|---|
0x01 |
RESET |
~300 ms | – | Weicher Reset (HAL_NVIC_SystemReset) |
0x27 |
LATCH_PERIOD |
50 ms | – | RT-Zähler in den Periodenschnappschuss übernehmen |
0x28 |
SET_CT_MODEL_CH0 |
5 ms | – | Vorbereitetes REG_CT_MODEL auf Kanal 0 zuordnen |
0x29 |
SET_CT_MODEL_CH1 |
5 ms | – | Vorbereitetes REG_CT_MODEL auf Kanal 1 zuordnen |
0x2A |
SET_CT_MODEL_CH2 |
5 ms | – | Vorbereitetes REG_CT_MODEL auf Kanal 2 zuordnen |
0x30 |
COMMIT_ADDR |
700 ms | – | I2C_ADDRESS persistieren (siehe §6.1) |
0x31 |
CLEAR_ERROR |
0 | – | REG_ERROR löschen (nur transiente Klassen; CLONE (0xF9) ist reserviert, wird nicht ausgelöst) |
0x32 |
SAVE_USER_CONFIG |
700 ms | – | Gruppe user_config speichern (produktionstauglich) |
Opcodes außerhalb des öffentlichen Bereichs (Werksnutzung) sind in dieser Referenz nicht dokumentiert. Ein Verbrauchs-Master sendet sie im Normalbetrieb nicht; ein nicht unterstützter Opcode → REG_ERROR = ERR_PARAM (0xFE).
7 · Bedeutung
7.0 Flash-Lebensdauer und Rücksetzverhalten
Hinweis: Vor Firmware 1.4.20 setzt ein Reset auch die übernommene CT-Modell-Skalierung auf die Werkseinstellung zurück (CAPABILITY Bit 12 gelöscht) — siehe §6.2.
Flash-Lebensdauer: ~10000 Zyklen pro Seite (typisch, Herstellerangabe). Jedes CMD_SAVE_USER_CONFIG oder CMD_COMMIT_ADDR ist ein Lösch- und Schreibzyklus auf der Parameterseite.
⚠ SAVE/COMMIT nicht in einer Laufzeitschleife wiederholen. Bei 1 SAVE/s brennt ein Modul in etwa 3 Stunden durch. Die Einrichtung erfolgt einmal bei der Installation; im Betrieb sind keine Einstellungsaktualisierungen nötig (ein Kunden-Master ändert sie selten).
Haltbarkeit: typischerweise 10+ Jahre bei üblicher Betriebstemperatur.
Vergleich des Rücksetzverhaltens:
| Reset-Typ | Erhalten | Gelöscht |
|---|---|---|
CMD_RESET (0x01) |
Flash (Konfiguration, Adresse, Label, Verstärkungen, NF) | RAM (UPTIME, ZC_OFFSET, EVENT_FLAGS — außer RESET_OCCURRED-Bit 5, das beim Booten gesetzt wird; THRESH_*; DIGEST_CONFIG) |
| Netzteil aus / Hard-Reset-Pin | Flash | wie CMD_RESET, zusätzlich alle externen RAM-Bereiche auf Host-Seite |
CMD_FACTORY_RESET (0xAA) (nur im Werksmodus) |
nichts | alles — der gesamte Parameterblock einschließlich der werkseitigen Kanalkalibrierung |
⚠ CMD_FACTORY_RESET ist kein Benutzerbefehl „Standardwerte wiederherstellen“. Er überschreibt den gesamten Parameterblock einschließlich der werkseitigen Kanalkalibrierung und wird vom Modul nur im Werksmodus akzeptiert — ein Fertigungsvorgang, kein Servicebefehl. Ein BASIC-Modul hat keinen Benutzer-Reset-Befehl. Um ein Modul in einen bekannten Zustand zurückzuführen, verwenden Sie CMD_RESET (0x01) (weicher Reset: nichts im Flash wird verändert) und stellen Sie die Benutzereinstellungen mit CMD_SAVE_USER_CONFIG (0x32) erneut ein.
Bitmuster von RESET_OCCURRED (kanonisch):
- Nach einem Reset, beim Booten:
EVENT_FLAGS.bit5 = 1. - Der Master sieht Bit 5 → weiß, dass das Modul neu gestartet hat → muss die RAM-only-Felder neu initialisieren (DIGEST_CONFIG, THRESH_*, EVENT_MASK).
- Der Master löscht Bit 5 per W1C:
write 1<<5 → EVENT_FLAGS.
7.1 Speichermodell
| Befehl | Produktion | Speichert dauerhaft |
|---|---|---|
CMD_SAVE_USER_CONFIG (0x32) |
✅ OK | i2c_address (über Zwei-Phasen-Commit), ct_model, sensor_class, fleet_config, group_id, label |
CMD_COMMIT_ADDR (0x30) |
✅ OK (magisch scharf geschaltet) | i2c_address |
CMD_RESET (0x01) |
✅ OK | — (weicher Reset) |
CMD_LATCH_PERIOD (0x27) |
✅ OK | — (übernimmt den Periodenschnappschuss) |
CMD_CLEAR_ERROR (0x31) |
✅ OK | — (löscht REG_ERROR) |
CMD_SAVE_GAINS (0x26) |
❌ GESPERRT in der Produktion (abgelehnt: REG_ERROR = 0xFE; Neustart setzt zurück) |
Werkskalibrierung |
CMD_FACTORY_RESET (0xAA) |
❌ GESPERRT in der Produktion | — |
7.2 Read-back ≠ Persistenz
⚠ Die Produktionsschutzschaltung nimmt den Schreibvorgang in den RAM an (ein anschließendes Lesen liefert den geschriebenen Wert), die Speicherung im Flash kann jedoch abgelehnt werden. Nach dem Neustart wird der Wert auf den Zustand vor dem Schreiben zurückgesetzt.
Der einzig gültige Weg, die Speicherung zu bestätigen, ist CMD_RESET + Startwartezeit + erneutes Lesen:
1. write target_reg(...)
2. issue CMD_RESET (0x01)
3. wait ~300 ms boot
4. re-read target_reg
5. assert read == written # only now is persistence confirmed
Die Adresse ist eine Ausnahme (v1.3 kanonisch): REG_I2C_ADDRESS (0x30) liefert beim Booten die aktive Adresse. Nach dem Staging wird der Kandidat zurückgespiegelt; nach dem Neustart zeigt es den tatsächlich gespeicherten Wert.
7.3 Vorbehalt zur einzelnen Spannungsreferenz
Das Modul verwendet einen U-Kanal, um P für alle I-Kanäle zu berechnen. Hängt eine CT-Zange an einem Leiter einer anderen Phase (Mehrphasen-Verteilung) — sind die P-Werte dieses Kanals falsch (beliebiger U/I-Phasenversatz). I_RMS bleibt korrekt.
Mehrphasenmessung (L1/L2/L3 gleichzeitig) ist eine eigenständige SKU mit eigener Spezifikation.
7.4 Energieintegration am Master — Kanon der Wanduhr
⚠ V03_PERIOD_LATCH_MS (0xEC) ist ein Diagnosetimer des Moduls; er kann unter Last zu niedrig anzeigen — für Energie den Master-Takt verwenden.
Kanonische Energieintegration am Master:
# CORRECT — master wall-clock
t_now = master_clock()
dt_s = (t_now - t_prev_latch) / time_unit
energy_wh[ch] += avg_p[ch] * dt_s / 3600
t_prev_latch = t_now
# WRONG — the module diagnostic timer may read short under load
dt_chip_s = read_u32(0xEC) / 1000.0
energy_wh[ch] += avg_p[ch] * dt_chip_s / 3600 # systematically under-reported
Die modulseitige Messung des abgeschlossenen Fensters ist V03_PERIOD_COMMIT_CNT (0xBE) multipliziert mit der Commit-Länge — sie zählt ganze RT-Commits und wird nicht von der Timer-Unterversorgung beeinflusst, die V03_PERIOD_LATCH_MS zu kurz anzeigen lässt. Ein Commit = 0.1 s ab v1.2; ältere Images verwendeten 0.2 s. Um ohne Versionstabelle zu erkennen, welcher Wert gilt: Das Verhältnis V03_PERIOD_LATCH_MS / V03_PERIOD_COMMIT_CNT liegt nahe 100 oder nahe 200. Verwenden Sie es für Gegenprüfungen; die Wanduhr des Masters bleibt für die Tarifabrechnung maßgeblich.
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::energyWh(ch) |
laufende Wh-Summe eines Kanals |
| ESP-IDF | rbamp_energy_wh() |
laufende Wh-Summe eines Kanals |
| Python | dev.energy.wh(ch) |
laufende Wh-Summe eines Kanals |
| ESPHome | energy |
Wh-Zähler je Kanal |
7.5 Erhalt der Periode bei fehlgeschlagenem Schnappschuss
Die Firmware BEWAHRT den Periodenakkumulator bei einem leeren Schnappschuss. Wenn g_period_count == 0 (ein Schnappschuss ohne lesbare Periode):
REG_V03_PERIOD_VALID = 0(Signal veraltet).period_start_msbleibt erhalten → der nächste erfolgreiche Snapshot deckt das vollständige, vom Master vorgesehene Intervall ab.
Folgerung: Der Master verliert bei einem veralteten Schnappschuss keine Daten. Muster für die Master-Integration:
issue snapshot
if PERIOD_VALID == 1:
integrate(avg_p, master_dt)
reset_master_clock
# else: skip integration (FW will automatically recover on the next success)
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::readPeriodSnapshot() / RbAmp::isPeriodValid() |
einen Periodenschnappschuss nehmen und nur bei Gültigkeit integrieren; das Bereit-Bit prüfen |
| ESP-IDF | rbamp_read_period_snapshot() / rbamp_is_period_valid() |
einen Periodenschnappschuss nehmen und nur bei Gültigkeit integrieren; das Bereit-Bit prüfen |
| Python | dev.read_period_snapshot() / RbAmpStaleError |
einen Periodenschnappschuss nehmen; ausgelöst, wenn der Snapshot nicht bereit ist — der nächste deckt das volle Intervall ab |
| ESPHome | Periodenschnappschuss nicht gültig | protokolliert, wenn das Gültigkeitsflag 0 ist; der erste Snapshot nach dem Start wird verworfen |
7.6 Toleranz gegenüber Takt-Drift
Kanonisch: Die interne Zeitbasis des Moduls kann unter Last um bis zu 30 % zu niedrig anzeigen — das ist normal und eine konstruktionsbedingte Eigenschaft der Zeitbasis. Unter Produktionslast gemessen.
Abnahme: Der Chip ist in Ordnung bei einem Drift ≤ 30 %.
⚠ Die alte 3-%-Schwelle ist FALSCH. Diese Schwelle würde gesunde Chips massenhaft ablehnen.
7.7 EMI- und Schalttransienten-Robustheit
Lesevorgänge während aktiven Relaisschaltens (5-A-EMI) scheitern in ~67 % der Fälle (hardwareseitig gemessen). Im stationären Betrieb sind Lesevorgänge zuverlässig. Der Bus erholt sich selbst, es tritt kein Blockieren ein, und keine Module gehen verloren.
Master-Muster — Wiederholung auf Anwendungsebene (zwingend beim Schalten induktiver Lasten):
for attempt in range(5):
result = read_register(...)
if result is OK:
return result
sleep(20 ms)
raise IOError("read failed after retries")
Ein Bus-Reset auf der Master-Seite allein reicht nicht, wenn ein EMV-Störimpuls mit dem Wiederholungsfenster des Treibers zusammenfällt.
7.8 Zusammenfassung bekannter Einschränkungen
Zusammengefasste Liste bekannter Eigenschaften, die der Master berücksichtigen muss:
| Thema | Verhalten | Siehe |
|---|---|---|
| Drift des Chip-Timers | Kann unter Last um bis zu 30 % zu kurz anzeigen (Akzeptanzbereich) | §7.4, §7.6 |
| EMI durch Relaisschaltvorgänge | ~67 % Lesefehlerrate während der Kommutierung; der Bus erholt sich selbst | §7.7 |
EVENT.bit3 asynchrone Latenz |
bis zu einem Fenster (~100 ms; 200 ms vor v1.2) von der Schreibablehnung bis zum Setzen von Bit 3 | §5.3 |
V03_PERIOD_LATCH_MS (0xEC) |
Diagnosetimer des Moduls; kann unter Last zu niedrig anzeigen — der Master nutzt seine eigene Wanduhr | §4.13, §7.4 |
Bedeutung von REG_ERROR (0x02) |
Ergebnis des letzten Schreibvorgangs (nicht klebend); EVENT Bit 3 = dauerhaftes Signal | §5.3 |
I_RMS = 0.0 |
Unter der Rauschgrenze (gültige Messung), NICHT „keine Daten“ | §5.4.3 |
U_RMS/U_PEAK/P bei I-Varianten |
Als 0.0 lesen (nur gültig, wenn CAPABILITY Bit 8 = 1) |
§4.10, §7.3 |
| Mehrbyte-SCHREIBEN | Kein Auto-Inkrement; Schleife Byte für Byte erforderlich | §5.1 |
| Verifikation der Adressänderung | Über einen Buscan unter der neuen Adresse; 0x30 ist auch nach einem Neustart zutreffend |
§6.1 |
| Start nach frischem Flash | REG_ERROR = 0xFB ist normal; SAVE löscht es |
§6.5 |
| GC-Standard | AUS (freiwillig pro Modul); NACK auf GC = „nicht aktiviert“ | §6.3 |
| Flash-Lebensdauer | ~10000 Zyklen je Seite; SAVE nicht in einer Schleife ausführen | §7.0 |
8 · Beispiele für Protokollmitschnitte
8.1 Erkennung — PRODUCT_ID + HW_VARIANT + CAPABILITY lesen
# I²C operations on default slave addr 0x50
S 0xA0 W 0x54 Sr 0xA1 R [PRODUCT_ID] P # read 0x54
S 0xA0 W 0x55 Sr 0xA1 R [HW_VARIANT] P # read 0x55
S 0xA0 W 0x57 Sr 0xA1 R [CAP_lo][CAP_hi] P # burst-read 0x57..0x58 (auto-increment)
Dabei bedeuten S=Start, Sr=wiederholter Start, P=Stopp, W=Schreibbit, R=Lesebit, 0xA0=Slave-Adresse 0x50 << 1.
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::readVariant() / RbAmp::readCapability(out) |
die Hardwarevariante lesen; die Capability-Map lesen |
| ESP-IDF | rbamp_read_variant() / rbamp_read_capability() |
die Hardwarevariante lesen; die Capability-Map lesen |
| Python | dev.read_variant() / dev.read_capability() |
die Hardwarevariante lesen; die Capability-Map lesen |
| ESPHome | get_variant_str() / get_capability_hex() |
die Variante als Text; die Capability-Bitmap als Hex |
8.2 Burst-Lesen des RT-Blocks (UI-Variante, alle Kanäle)
# Read all of V03 RMS + P + PF (0x86..0xBD) — 56 bytes, atomic via read-freeze
S 0xA0 W 0x86 Sr 0xA1 R [56 bytes] P
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::readAll(snapshot) |
den gesamten Echtzeitblock in einem Aufruf lesen |
| ESP-IDF | rbamp_read_all() |
den gesamten Echtzeitblock in einem Aufruf lesen |
| Python | dev.read_all() |
den gesamten Echtzeitblock in einem Aufruf lesen |
| ESPHome | Burst-Lesen des Momentanwert-Blocks | die Komponente liest den Momentanwert-Block pro Update in einem Burst |
8.3 Mehrbyte-SCHREIBEN — LABEL Byte für Byte
# WRONG: burst-write — only 'M' is accepted
S 0xA0 W 0x68 'M' 'y' 'M' 'e' 't' 'e' 'r' '1' P
# CORRECT: byte-at-a-time loop
S 0xA0 W 0x68 'M' P
S 0xA0 W 0x69 'y' P
S 0xA0 W 0x6A 'M' P
S 0xA0 W 0x6B 'e' P
S 0xA0 W 0x6C 't' P
S 0xA0 W 0x6D 'e' P
S 0xA0 W 0x6E 'r' P
S 0xA0 W 0x6F '1' P
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::writeLabel(label) / RbAmp::readLabel(out) |
das 8-Byte-Label schreiben (nur BASIC); zurücklesen |
| ESP-IDF | rbamp_write_label() / rbamp_read_label() |
das 8-Zeichen-Etikett schreiben; zurücklesen |
| Python | dev.set_label(label) / dev.read_label() |
das 8-Byte-Label schreiben; zurücklesen |
| ESPHome | — | Label-Option nicht dokumentiert |
8.4 GC-Broadcast-Snapshot + Zeugen-Fallback
# Send GC frame: A5 27
S 0x00 W 0xA5 0x27 0x00 0x2A 0x00 P
# Wait 50 ms settle
# Witness check for every expected module
foreach module in [0x50, 0x51, 0x52]:
S (module<<1)|W 0x07 Sr (module<<1)|R [VALID] P
if VALID != 1:
# Fall back to per-device snapshot
S (module<<1)|W 0x01 0x27 P # CMD_LATCH_PERIOD
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmpFleet::gcLatch(group, tick, settle_ms) / RbAmpFleet::checkSync() |
den General-Call-Snapshot-Frame senden; jedes Modul prüfen |
| ESP-IDF | rbamp_fleet_gclatch() / rbamp_fleet_check_sync() |
den General-Call-Snapshot-Frame senden; jedes Modul prüfen |
| Python | fleet.gc_latch(group, tick, settle_ms) / fleet.check_sync(expected_tick) |
den General-Call-Snapshot-Frame senden; jedes Modul prüfen |
| ESPHome | fleet_gc_enable: / Protokoll der Synchronprüfung |
optionaler General-Call-Snapshot; Protokollzeile, die die Synchronität der Module bestätigt |
8.5 Adressänderung in 5 Schritten
# 1. Stage candidate addr (0x51) → REG_I2C_ADDRESS
S 0xA0 W 0x30 0x51 P
# 2. Arm magic → ADDR_COMMIT_MAGIC
S 0xA0 W 0x31 0xA5 P
# 3. Issue CMD_COMMIT_ADDR (opcode 0x30) → REG_COMMAND
S 0xA0 W 0x01 0x30 P
# 4. Wait 700 ms flash write
# 5. Issue CMD_RESET (opcode 0x01) → REG_COMMAND
S 0xA0 W 0x01 0x01 P
# Wait ~300 ms boot
# Verify: probe the new addr
S 0xA2 W 0x55 Sr 0xA3 R [HW_VARIANT] P # 0xA2 = 0x51 << 1
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::prepareAddressChange(new_addr) / RbAmp::commitAddressChange() |
neue Adresse vorbereiten und scharf schalten, dann committen |
| ESP-IDF | rbamp_prepare_address_change() / rbamp_commit_address_change() |
neue Adresse vorbereiten und scharf schalten, dann committen |
| Python | dev.prepare_address_change(new_addr) / dev.commit_address_change() |
neue Adresse vorbereiten und scharf schalten, dann committen |
| ESPHome | new_address: |
einmalige Adressänderung beim Start; danach die Option entfernen |
8.6 Provisionierung nach dem Erstflash
# 1. Check fresh-flash state
S 0xA0 W 0x02 Sr 0xA1 R [0xFB] P # ERR_FLASH_PARAMS_BAD — normal
# 2. Configure sensor_class
S 0xA0 W 0x25 0x01 P # SCT_013
# 3. Stage CT model + bind ch0
S 0xA0 W 0x05 0x03 P # SCT-013-030
S 0xA0 W 0x01 0x28 P # CMD_SET_CT_MODEL_CH0
# Wait 5 ms
# 4. Save user_config
S 0xA0 W 0x01 0x32 P # CMD_SAVE_USER_CONFIG
# Wait 700 ms
# 5. Verify: REG_ERROR should be 0x00 (read IMMEDIATELY before the next write)
S 0xA0 W 0x02 Sr 0xA1 R [0x00] P
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::configureChannels(cls, models, n) / RbAmp::saveUserConfig() |
Klasse und alle Kanalmodelle setzen; Benutzerkonfiguration speichern |
| ESP-IDF | rbamp_configure_channels() / rbamp_save_user_config() |
Klasse und alle Kanalmodelle setzen; Benutzerkonfiguration speichern |
| Python | dev.configure_channels(cls, models) / dev.save_user_config() |
Klasse und alle Kanalmodelle setzen; Benutzerkonfiguration speichern |
| ESPHome | sensor_class: / ct_model: |
YAML-Optionen für Sensorklasse und CT-Modell |
8.7 DIGEST-Rundlauf — konfigurieren + lesen
# 1. Configure digest mask: I_RMS + U_RMS + P_REAL (bits 0+1+2 = 0x07)
S 0xA0 W 0x29 0x07 P
# 2. Wait one RT-commit cycle (~100 ms from v1.2; waiting 200 ms covers all images; or poll STATUS.bit0)
# 3. Burst-read the digest window (22 bytes)
S 0xA0 W 0x70 Sr 0xA1 R [22 bytes] P
# Parse the layout per DIGEST_CONFIG = 0x07 on UI1 (N_I = 1):
# byte[0] = STATUS_MIRROR
# byte[1] = SEQ
# byte[2..3] = I_RMS[0] u16 (0.01 A units)
# byte[4..5] = U_RMS u16 (0.1 V units)
# byte[6..7] = P[0] i16 (1 W units)
# byte[8..21] = unused (0x00)
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | — | Digest-Fenster nicht verfügbar |
| ESP-IDF | rbamp_set_digest_fields() / rbamp_read_digest() |
die Digest-Felder wählen; sie in einer Transaktion lesen (BASIC) |
| Python | — | Digest-Fenster nicht verfügbar |
| ESPHome | — | Digest-Fenster nicht verfügbar |
8.8 Ablauf von Schwellenereignissen — Schwelle schreiben → auslösen → W1C löschen
# 1. Write current threshold = 30 A (0x0BB8 in 0.01 A units → 2 bytes LE)
S 0xA0 W 0x2C 0xB8 P # LO byte
S 0xA0 W 0x2D 0x0B P # HI byte
# 2. Unmask THRESH_I event (bit 1) → DRDY solid-LOW on trip
S 0xA0 W 0x2B 0x02 P # EVENT_MASK = bit 1 only
# 3. (runtime) The master polls EVENT_FLAGS
S 0xA0 W 0x2A Sr 0xA1 R [event_flags] P
# event_flags == 0x02 → threshold tripped
# 4. (optional) Read context — REG_ERROR, RT block, etc.
# 5. Clear EVENT_FLAGS.bit1 via W1C
S 0xA0 W 0x2A 0x02 P
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::setEventThresholds(i_amps, p_watts) / RbAmp::readEventFlags(out) |
Strom- und Leistungsschwellen setzen; Ereignisflags lesen und löschen |
| ESP-IDF | rbamp_set_event_thresholds() / rbamp_read_event_flags() |
Strom- und Leistungsschwellen setzen; Ereignisflags lesen und löschen |
| Python | dev.read_event_flags() |
Ereignis-Flags lesen und löschen (kein Schwellwert-Setter am Gerät) |
| ESPHome | Schwellenalarme in YAML / get_event_flags() |
Schwellwert-Automatisierungen über Sensorwerte; die Ereignis-Flags |
8.9 Rohsample-Diagnoseburst (CAPTURE_*)
CMD_CAPTURE_RAW (0x38) und die Register CAPTURE_* sind eine Diagnoseeinrichtung — im Normalbetrieb nicht nötig; nur verwenden, wenn der Lieferant ausdrücklich die Aufnahme von Rohsamples verlangt.
# 1. Arm raw-capture
S 0xA0 W 0x01 0x38 P # CMD_CAPTURE_RAW (opcode 0x38)
# Wait ~80 ms (3 DMA-TC cycles)
# 2. Check ready
S 0xA0 W 0x18 Sr 0xA1 R [status & 0x01] P # bit 0 = ready
# 3. Select page 0 (16 raw I0 samples → CAPTURE_WINDOW)
S 0xA0 W 0x19 0x00 P
# 4. Burst-read CAPTURE_WINDOW (32 bytes = 16×u16 LE samples)
S 0xA0 W 0x1A Sr 0xA1 R [32 bytes] P
# Repeat steps 3-4 for pages 1..15 (256 samples total ≈ 1.3 mains periods)
8.10 Prüfspiegel-Rücklesen des CT-Modells (Plausibilitätsprüfung nach der Zuordnung)
# After the §6.2 sequence — verify the applied state per channel via 0x51..0x53 (burst):
S 0xA0 W 0x51 Sr 0xA1 R [model_ch0][model_ch1][model_ch2] P
# Expected on UI2 mixed-CT (e.g. ch0=SCT-013-005, ch1=SCT-013-030):
# byte[0] = 0x01 # SCT-013-005 applied on ch0
# byte[1] = 0x03 # SCT-013-030 applied on ch1
# byte[2] = 0x00 # unused (UI2 N_I=2)
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::readCTModelCh(channel, out) |
das tatsächlich auf einem Kanal angewendete CT-Modell lesen |
| ESP-IDF | rbamp_read_ct_model_ch() |
das tatsächlich auf einem Kanal angewendete CT-Modell lesen |
| Python | dev.read_ct_model_ch(ch) |
das tatsächlich auf einem Kanal angewendete CT-Modell lesen |
| ESPHome | Boot-Protokoll ct_model[0]: matches |
Protokollzeilen, die bestätigen, dass Sensorklasse und Modell übernommen wurden |
9 · Abnahme / Toleranz
| Parameter | Schwellwert | Quelle |
|---|---|---|
| Chip-Takt-Drift gegenüber der Wanduhr des Masters | ≤ 30 % | am Prüfstand validiert |
| Ausfallrate beim Lesen nach EMI-Schaltvorgängen | bis zu ~67 % bei Kommutierung | am Prüfstand validiert |
| Bus-NACK-Rate (Linux/ESP-I²C @ 100 kHz ohne Wiederholung) | bis zu ~20 % | hostseitige Eigenschaft |
| NACK-Rate am Bus bei 50 kHz + 3× Wiederholung | < 0.8 % | am Prüfstand validiert |
Wert von REG_ERROR bei Start nach frischem Flash |
0xFB (FLASH_PARAMS_BAD) |
NORMAL bei einem neuen Modul |
| Kaltstart bis zur ersten gültigen Messung | ~250 ms | typisch |
10 · Änderungsprotokoll
1.3.0 (2026-06-15) — Erste öffentliche Veröffentlichung.
Referenz-Firmware: protocol_version = 1.3, schema_version = 2. Der Vertrag der Seite 0 ist eingefroren.
Wichtige Änderungen in v1.3 gegenüber früheren internen Versionen
- CT_MODEL reine Vorbereitung:
REG_CT_MODEL (0x05)übernimmt beim Schreiben nicht mehr automatisch Kanal 0. Die Zuordnung erfolgt nur überCMD_SET_CT_MODEL_CHn(reihenfolgeunabhängig). - Adressen-Zwei-Phasen-Commit (produktionstauglich):
I2C_ADDRESSwird überADDR_COMMIT_MAGIC+CMD_COMMIT_ADDRgespeichert.REG_I2C_ADDRESSliefert beim Start die aktive Adresse. - REG_ERROR = Ergebnis des letzten Schreibvorgangs (nicht klebend).
EVENT_FLAGS.bit3ist das dauerhafte Signal (klebendes W1C; wird innerhalb eines Fensters, ~100 ms, nach der Schreibablehnung gesetzt). - Unbekannte Opcodes / Werte außerhalb der Aufzählung → abgelehnt:
REG_ERROR = ERR_PARAM (0xFE)+EVENT.bit3. Sehr frühe Images (1.2–1.4.3) ignorierten unbekannte Opcodes stillschweigend. - Erstes Einrichten nach frischem Flash:
ERR_FLASH_PARAMS_BAD (0xFB)auf einem neuen Modul → überCMD_SAVE_USER_CONFIGgelöscht. - GC-Broadcast-Schnappschuss — pro Modul aktivierbar über
FLEET_CONFIG.bit0(Standard AUS; wirkt nach Reset). NACK bei deaktiviertem Modul = harter Fehler, nicht stillschweigend. - Lese-/Schreib-Asymmetrie by design: LESEN mit Auto-Inkrement ✅; SCHREIBEN Byte für Byte erforderlich ❌ (hardwareseitig bestätigt).
- CAPABILITY-Register (0x57/0x58 u16 LE): Funktionsbitmap — Funktionen über einzelne Bits erkennen (§3.2), niemals durch Vergleich des Gesamtwerts; Bit 12 = SCT_RATING_SELF (Firmware 1.4.20+).
- Atomarität: V03-RMS-Block + Digest haben einen Read-Freeze (atomarer Burst-Lesezugriff); die Spiegel GC_TICK / I2C_ADDRESS / CT_MODEL_CHn werden zweimal gelesen und müssen übereinstimmen.
- NF-Zange-Semantik:
I_RMS = 0.0bedeutet „unter der Rauschgrenze“, eine gültige Messung. - AC_FREQ aus dem ZC gewonnen bei allen Varianten (auch bei reinen I-Varianten).
- Die Energieintegration am Master muss die eigene Wanduhr verwenden, nicht
V03_PERIOD_LATCH_MS (0xEC)(Diagnose-Timer des Moduls — kann unter Last zu kurz anzeigen).