rbAmp
DE
Shop
Docs
Aktualisiert

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.

Zielgruppe

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

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

In den Client-Bibliotheken

— 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:

Text
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

Python
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
In den Client-Bibliotheken

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

In den Client-Bibliotheken

— 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

Python
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
In den Client-Bibliotheken

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

Überblick über die Registerübersicht von rbAmp und ihre Adressblöcke.

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..0x1A sind Produktionsdiagnose, siehe §4.2).
  • 0x36..0x3B, 0x40..0x45 — reservierte Adressen auf Seite 0 (0x32 + 0x3C..0x3F sind das Kanalzugriffsfenster, siehe §4.14).
  • 0x4F, 0x50 — reserviert (Vorabreservierung des Identitätsblocks).
  • 0xE4..0xEB, 0xF0..0xFF — Werkskalibrierung (NF, GAIN); nur werkseitig schreibbar.
Hinweis

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)
In den Client-Bibliotheken

— 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)
In den Client-Bibliotheken

— 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
In den Client-Bibliotheken

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

In den Client-Bibliotheken

— 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.
In den Client-Bibliotheken

— 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
In den Client-Bibliotheken

— 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)
In den Client-Bibliotheken

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

In den Client-Bibliotheken

— 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 –
In den Client-Bibliotheken

— 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.
In den Client-Bibliotheken

— 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
In den Client-Bibliotheken

— 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
In den Client-Bibliotheken

— 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

  1. ⛔ 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, und 0x9A setzt den Schritt fort — aber 0x9A ist V03_I0_PEAK, nicht V03_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.
  2. Vor jedem Lesen erneut auswählen. REG_CHANNEL_DATA ist ein Schnappschuss zum Zeitpunkt des Auswahlschreibvorgangs, keine Live-Ansicht. Wird 0x3C..0x3F in einer Schleife abgefragt, ohne 0x32 neu zu schreiben, liefert es für immer einen eingefrorenen Wert. Jeder neue Messwert erfordert einen neuen Schreibvorgang auf 0x32.
  3. 0x32-Registeradresse ≠ 0x32-Befehls-Opcode. CMD_SAVE_USER_CONFIG verwendet den Opcode 0x32, geschrieben in REG_COMMAND (0x01) — das ist ein anderer Adressraum als REG_CHANNEL_SELECT (das bei der Registeradresse 0x32 liegt). Nennen Sie 0x32 nie ohne Angabe des Adressraums.
  4. Für Kanäle 3+ kommen Periode/Energie nur aus Feld 13 (CHFIELD_PERIOD_AVG_P). Die Register V03_PERIOD_AVG_P* (0xC2/0xC6/0xDC) decken nur ch0/ch1/ch2 ab. Es gibt kein flaches V03_PERIOD_AVG_P_CH3 — lesen Sie stattdessen Feld 13 über das Fenster.

Beispiel auf Leitungsebene — Effektivstrom für Kanal 3 lesen

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

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

In den Client-Bibliotheken

— 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

Burst-Lesezugriffe zählen automatisch hoch, Mehrbyte-Schreibvorgänge erfolgen dagegen Byte für Byte.

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:

Text
# CORRECT: low byte first (LE)
write(addr=0x2C, value=0x34)   # LO byte
write(addr=0x2D, value=0x12)   # HI byte

FALSCHES / RICHTIGES Beispiel (Pseudocode)

Text
# 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 Firmware reg_error = ERR_OK; jeder nachfolgende, unabhängige Schreibvorgang löscht den vorherigen Fehler.
  • EVENT_FLAGS (0x2A) Bit 3 ist 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):

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

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

In den Client-Bibliotheken

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

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:

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

In den Client-Bibliotheken

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

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:

Text
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
In den Client-Bibliotheken

— 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):

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

: 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 über CMD_COMMIT_ADDR gespeichert.

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 0x30 bestätigen (spiegelt nun die neue aktive Adresse).

Fehlerbilder:

  • ADDR_COMMIT_MAGIC nicht 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 prepare muss wiederholt werden.
In den Client-Bibliotheken

— 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

Hinweis

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

Text
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), wenn CMD_SET_CT_MODEL_CHn ausgegeben wird → REG_ERROR = ERR_PARAM.
  • CT_MODEL außerhalb von 1..7 (SCT-013-005/-010/-030/-050/-100/-020/-060) bei CMD_SET → ERR_PARAM.
In den Client-Bibliotheken

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

Text
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

Text
I²C general-call address 0x00 | A5 27      (5-byte payload)
  • A5 — Frame-Magic.
  • 27 — Opcode CMD_LATCH_PERIOD.
  • — 0x00 = alle; andernfalls muss sie mit dem REG_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 über GC_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 0x00 oder 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:

Text
foreach module where witness == 0:
    write_cmd(module, CMD_LATCH_PERIOD)
sleep(50 ms)
foreach module: read period snapshot with skip_latch=true
In den Client-Bibliotheken

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

Text
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=1 bedeutet, 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 = 0 liefern, 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_PERIOD und 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.
In den Client-Bibliotheken

— 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.bit3 gesetzt.
  • 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:

Text
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
In den Client-Bibliotheken

— 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:

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

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

In den Client-Bibliotheken

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

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

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.

Sicherheit

⚠ 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
Sicherheit

⚠ 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:

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

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

In den Client-Bibliotheken

— 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_ms bleibt 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:

Text
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)
In den Client-Bibliotheken

— 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):

Text
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

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

In den Client-Bibliotheken

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

Text
# 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
In den Client-Bibliotheken

— 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

Text
# 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
In den Client-Bibliotheken

— 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

Text
# 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
In den Client-Bibliotheken

— 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

Text
# 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
In den Client-Bibliotheken

— 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

Text
# 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
In den Client-Bibliotheken

— 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

Text
# 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)
In den Client-Bibliotheken

— 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

Text
# 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
In den Client-Bibliotheken

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

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

Text
# 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)
In den Client-Bibliotheken

— 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 über CMD_SET_CT_MODEL_CHn (reihenfolgeunabhängig).
  • Adressen-Zwei-Phasen-Commit (produktionstauglich): I2C_ADDRESS wird über ADDR_COMMIT_MAGIC + CMD_COMMIT_ADDR gespeichert. REG_I2C_ADDRESS liefert beim Start die aktive Adresse.
  • REG_ERROR = Ergebnis des letzten Schreibvorgangs (nicht klebend). EVENT_FLAGS.bit3 ist 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 → über CMD_SAVE_USER_CONFIG gelö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.0 bedeutet „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).

Ende des Dokuments.