02 · Initialisierung und Inbetriebnahme
rbAmp beginnt sofort nach dem Einschalten zu messen. Der Master muss nur:
- I²C-Bus initialisieren (Standard-
Wire/ HAL-Initialisierung). - ~250 ms warten oder
DATA_VALID = 1am Register0xCEabfragen. - Optional die Firmwareversion von
0x03als Plausibilitätsprüfung lesen. - Messdaten — bereit.
Kein Startbefehl und keine Konfiguration auf Registerebene am Chip erforderlich. Die Werkskalibrierung wird beim Booten automatisch geladen, sodass das Modul ab dem ersten Messwert korrekte physikalische Werte ausgibt.
Wichtig für BASIC-SCT-Serie-Module mit SCT-013-Sensoren: Schreiben Sie nach der ersten Installation das Sensormodell in das Modellregister. Das Modul braucht das Modell, um den richtigen mV-pro-Ampere-Koeffizienten anzuwenden. Der Modell-Code wird im Flash gespeichert und übersteht Neustarts. Bei Firmware vor 1.4.20 (CAPABILITY Bit 12 gelöscht) fällt die angewendete Skalierung nach einem Modulneustart auf die Werkseinstellung zurück — ein Master, der ein nicht werkseitiges Modell gewählt hat, muss es nach jedem erkannten Modulneustart erneut committen (siehe Was einen Neustart übersteht und die Regel zur Neustarterkennung in period-metering.md); ab Firmware 1.4.20 übersteht der Modellwechsel einen Neustart. Bei Images vor 1.4.20 ist die Energie nach jedem Modulneustart falsch, sofern CT_MODEL nicht erneut committet wird. Die Client-Bibliotheken behandeln beide Fälle für Sie. Details finden Sie im Abschnitt Sensorklasse und CT-Modell setzen unten.
BASIC-CT-Module werden paarweise mit ihren Sensoren geliefert, werkseitig für diesen Sensor voreingestellt und kalibriert; sie starten ohne Initialisierung.
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 |
Hilfsfunktionen (plattformneutrales C)
Alle folgenden Beispiele verwenden drei kleine Hilfsfunktionen, die auf jeder Plattform leicht umzusetzen sind:
// Read one byte from a slave register.
uint8_t rb_read_u8(uint8_t addr, uint8_t reg);
// Read a little-endian float32 (4 bytes from reg, reg+1, reg+2, reg+3).
// rbAmp supports READ auto-increment — both per-byte access and a single
// 4-byte burst-read are valid. The helpers below show per-byte for clarity;
// production code often uses burst-read for atomicity guarantees (see ch 11).
float rb_read_float_le(uint8_t addr, uint8_t reg);
// Write one byte to a slave register.
void rb_write_u8(uint8_t addr, uint8_t reg, uint8_t val);
Inbetriebnahme auf Arduino (Wire.h)
Hilfsfunktionen
#include
uint8_t rb_read_u8(uint8_t addr, uint8_t reg) {
Wire.beginTransmission(addr);
Wire.write(reg);
Wire.endTransmission(false); // repeated start, do not release bus
Wire.requestFrom(addr, (uint8_t)1);
return Wire.read();
}
float rb_read_float_le(uint8_t addr, uint8_t reg) {
uint8_t buf[4];
for (int i = 0; i < 4; i++) {
buf[i] = rb_read_u8(addr, reg + i);
}
float f;
memcpy(&f, buf, 4); // little-endian host (AVR, ESP32, ARM)
return f;
}
void rb_write_u8(uint8_t addr, uint8_t reg, uint8_t val) {
Wire.beginTransmission(addr);
Wire.write(reg);
Wire.write(val);
Wire.endTransmission();
}
Funktionstest (einzelnes Modul)
#include
#define RB_ADDR 0x50
void setup() {
Serial.begin(115200);
Wire.begin();
Wire.setClock(50000);
delay(300); // wait for module boot
// Wait DATA_VALID bit
while ((rb_read_u8(RB_ADDR, 0xCE) & 0x01) == 0) {
Serial.println("waiting for DATA_VALID...");
delay(50);
}
uint8_t ver = rb_read_u8(RB_ADDR, 0x03);
Serial.printf("rbAmp ready, version 0x%02X\n", ver);
}
void loop() {
float u_rms = rb_read_float_le(RB_ADDR, 0x86);
float i_rms = rb_read_float_le(RB_ADDR, 0x8E);
float p = rb_read_float_le(RB_ADDR, 0xA6);
float pf = rb_read_float_le(RB_ADDR, 0xB2);
Serial.printf("U=%.1f V I=%.3f A P=%.1f W PF=%.3f\n",
u_rms, i_rms, p, pf);
delay(1000);
}
Verwenden Sie eine Last von mindestens ~1 % der Sensornennlast — darunter werden die Messwerte verrauscht und die Klasse wird nicht eingehalten (eine 60-W-Lampe ist nur 0.9 % einer 30-A-Zange; siehe die Tabelle der Kenndaten). Bei einer 30-A-Zange ist ein 2-kW-Wasserkocher eine gute Last für den Funktionstest. Bei BASIC-SCT-Modulen mit SCT-013-Sensor müssen Sensorklasse und CT-Modell vor dem Funktionstest gesetzt werden (siehe Sensorklasse und CT-Modell setzen) — ohne das Modell sind die Stromwerte bedeutungslos.
Erwartete Ausgabe (ein 2-kW-Wasserkocher an 230 V, 30-A-Zange):
rbAmp ready, version 0x04
U=229.8 V I=8.72 A P=2004 W PF=0.999
U=230.1 V I=8.73 A P=2008 W PF=0.999
...
Inbetriebnahme auf STM32 HAL (C)
#include "stm32f1xx_hal.h"
extern I2C_HandleTypeDef hi2c1;
#define RB_ADDR_8BIT (0x50 << 1) // HAL expects 8-bit address format
uint8_t rb_read_u8(uint8_t reg) {
uint8_t v;
HAL_I2C_Mem_Read(&hi2c1, RB_ADDR_8BIT, reg, I2C_MEMADD_SIZE_8BIT, &v, 1, 100);
return v;
}
float rb_read_float_le(uint8_t reg) {
uint8_t buf[4];
for (int i = 0; i < 4; i++) {
HAL_I2C_Mem_Read(&hi2c1, RB_ADDR_8BIT, reg + i, I2C_MEMADD_SIZE_8BIT,
&buf[i], 1, 100);
}
float f;
memcpy(&f, buf, 4);
return f;
}
void main_app(void) {
while ((rb_read_u8(0xCE) & 0x01) == 0) HAL_Delay(50);
uint8_t ver = rb_read_u8(0x03);
printf("rbAmp version: 0x%02X\n", ver);
while (1) {
float u = rb_read_float_le(0x86);
float i = rb_read_float_le(0x8E);
float p = rb_read_float_le(0xA6);
printf("U=%.1f V I=%.3f A P=%.1f W\n", u, i, p);
HAL_Delay(1000);
}
}
CT-Serienmodule: Start ohne Konfiguration
Ein CT-Serie-Modul wird mit jedem Stromkanal bereits konfiguriert geliefert: Sensorklasse, Nennwert und Kalibrierung sind im Werk für die mit dem Kanal gelieferte Zange geschrieben. Es sind keine Initialisierungsschreibvorgänge nötig — der Host liest nur.
⚠ Schreiben Sie die Sensorklasse oder das Sensormodell auf einem CT-Serie-Modul nicht. - Das Schreiben des Modells auf einen Kanal ersetzt dessen Werkskalibrierung durch eine generische Voreinstellung: Der aktuelle Fehler wird −2…+3 %, und die Schwelle für kleine Ströme ist falsch. - Das Schreiben der Klasse löscht das Modell aller Kanäle.
Ab Firmware 1.4.22 lehnt ein CT-Serienmodul Klassen- und Modellschreibvorgänge im Normalbetrieb mit ERR_PARAM (0xFE) ab; die Client-Bibliotheken verweigern sie bei allen Firmwareständen.
Kanal und seine Zange bilden ein Paar. Jede Zange ist mit dem Kanal beschriftet, zu dem sie gehört. Versetzen Sie keine Zange auf einen anderen Kanal und schließen Sie keine andere Zange an einen Kanal an: Die Kalibrierung gilt nur für die Werkspaarung. Die Nennwerte sind fest; es gibt keinen Nennwert zu wählen.
Startsequenz
- Stromzangen anschließen (Pfeil zur Last — siehe hardware-connection.md) und das Modul einschalten.
- Die Klasse lesen (
SENSOR_CLASS,0x25):2= Serie der CT-Zangen. - Lesen Sie das angewendete Modell jedes Kanals (
0x51..0x53, ein Register je Kanal; UI5/UI7-Kanäle 3 und höher: über das Kanal-Zugriffsfenster, FeldCT_MODEL) und ordnen Sie es dem Nennwert zu:
| Modellcode | 0x06 |
0x07 |
0x08 |
0x09 |
0x0A |
0x0B |
0x0D |
|---|---|---|---|---|---|---|---|
| Nennwert | 1 A | 5 A | 10 A | 20 A | 30 A | 50 A | 100 A |
Verwenden Sie den Nennwert, um Anzeigebereiche zu skalieren und Messwerte zu prüfen; das Modul meldet bereits Ampere.
- Pollen Sie wie bei jedem BASIC-Modul — Messfenster von 100 ms, Data-Ready-Pin oder periodisches Lesen (siehe realtime-polling.md); Periodenzählung wie in period-metering.md.
Weitere Schritte sind nicht nötig: Es gibt keine Sensorauswahl, keine Verstärkungsstufe und keinen Speicherbefehl. Das Modul behält seine Konfiguration über Neustarts hinweg.
Austausch einer CT-Zange oder eines Moduls
Die Kalibrierung gehört zum Paar. Eine Zange oder ein Kanal kann im Feld nicht ausgetauscht werden: Ein Modul, das eine neue Zange braucht, geht zur Neupaarung an den Werksservice.
Sensorklasse und CT-Modell setzen
Erforderlich nur für BASIC-SCT-Serie-Module mit SCT-013-Sensoren. BASIC-CT-Serie-Module werden paarweise mit ihren Sensoren geliefert: Alles ist werkseitig für genau diesen Sensor voreingestellt und kalibriert, und sie starten ohne Initialisierung — diesen Abschnitt überspringen.
Zwei Register beschreiben den externen Sensor: SENSOR_CLASS (die Familie — SCT-013-Klemmzangen, die Serie verdrahteter CT-Zangen, integrierter CT) und CT_MODEL (der konkrete Modellcode innerhalb dieser Familie). Bei v1.3 wird das Modell nach einem reinen Staging-Verfahren geschrieben — das Schreiben von CT_MODEL wendet es nicht allein an; ein eigener Befehl pro Kanal committet den gestagten Wert.
Register
| Name | Adresse | Typ | Hinweise |
|---|---|---|---|
SENSOR_CLASS |
0x25 |
u8 RW | 0 = nicht gesetzt, 1 = SCT_013, 2 = WIRED_CT (die Serie der CT-Zangen), 3 = BUILTIN_CT (integrierter Sensor, Werkskalibrierung je Gerät — kein Modellcode). Ein Wechsel der Klasse setzt CT_MODEL auf 0 zurück. |
CT_MODEL |
0x05 |
u8 RW | CT-Modell-Code — nur Vorbereitungsregister. Ein reiner Schreibvorgang wird nicht übernommen. |
Auswahl eines Sensors
Kaufen Sie eines der in der Tabelle unten aufgeführten Modelle der SCT-013-Reihe mit Spannungsausgang (3.5-mm-Stecker) — nicht eine Variante mit Stromausgang. Wählen Sie die kleinste Zange, deren Nennwert über Ihrem größten erwarteten Strom liegt; für die angegebene Klasse sollte die Last nicht unter etwa 1 % des Nennwerts liegen (siehe die Genauigkeitstabelle).
CT-Modellcodes — SCT-013-Familie (SENSOR_CLASS = 1)
| Code | Sensor | Nennstrom | Beginn der Effektivwert-Begrenzung (RMS-Clip) | Spitzenbegrenzung |
|---|---|---|---|---|
0x00 |
nicht gesetzt (Standard bei werkseitig neuen BASIC-SCT-Serie-Modulen) | — | — | — |
0x01 |
SCT-013-005 | 5 A | 5.8 A | 8.2 A |
0x02 |
SCT-013-010 | 10 A | 11.6 A | 16.4 A |
0x03 |
SCT-013-030 | 30 A | 34.8 A | 49.2 A |
0x04 |
SCT-013-050 | 50 A | 58 A | 82 A |
0x05 |
SCT-013-100 | 100 A | 116 A | 164 A |
0x06 |
SCT-013-020 | 20 A | 23.2 A | 32.8 A |
0x07 |
SCT-013-060 | 60 A | 69.6 A | 98.4 A |
Die Codes 0x06 und 0x07 sind nach Nennwert nicht monoton — sie wurden nach dem ursprünglichen Satz 0x01..0x05 ergänzt. Wählen Sie stets nach dem benötigten Nennwert, nicht nach der Codereihenfolge.
Grenzwert-Semantik: Nennstrom und Beginn der Effektivwert-Begrenzung setzen eine sinusförmige Last voraus; der gemessene Clipping-Beginn liegt bei ≈ 1.16 × dem Nennwert. Die Spitzenbegrenzung (≈ 1.64 × Nennwert) ist die eigentliche Obergrenze — eine verzerrte Last (hoher Crestfaktor) beginnt bei Spitze / Crestfaktor zu clippen, also unterhalb der Effektivwertangaben. Bleiben Sie für die angegebene Genauigkeit bei oder unter dem Nennwert: Die Messwerte begrenzen bei etwa 115–120 % des Nennwerts.
Die Nennwerte je Bereich (erkennbare und ablesbare Untergrenze, Klasse, Sensortoleranz, Clipping-Punkt) stehen in der Genauigkeitstabelle in overview.md. Den Sensortyp zu ändern heißt, den Modellcode auf das Modul zu schreiben — mehr ist nicht nötig; es gibt keinen Kalibrierschritt.
CT-Modellcodes — Serie verdrahteter CT-Zangen (SENSOR_CLASS = 2)
Module der CT-Serie werden als werkskalibriertes Set mit eigener Zange geliefert: Klasse und Modell sind bereits gesetzt und Teil der Kalibrierung — siehe CT-Serie-Module: Inbetriebnahme ohne Konfiguration. Schreiben Sie sie nicht. Die Tabelle unten dient als Referenz zum Lesen des angewendeten Modells; bei einem Modul der CT-Serie wählt der Anwender nichts.
| Code | Zange | Nennstrom | Fenster |
|---|---|---|---|
0x01..0x05 |
veraltete Voreinstellungen für verdrahtete CT | — | — |
0x06 |
CT-Zange, 1 A | 1 A | 6 mm |
0x07 |
CT-Zange, 5 A | 5 A | 6 mm |
0x08 |
CT-Zange, 10 A | 10 A | 6 mm |
0x09 |
CT-Zange, 20 A | 20 A | 10 mm |
0x0A |
CT-Zange, 30 A | 30 A | 10 mm |
0x0B |
CT-Zange, 50 A | 50 A | 10 mm |
0x0D |
CT-Zange, 100 A | 100 A | 16 mm |
Die Fenstergröße richtet sich nach dem Nennstrom (6 mm für 1–10 A, 10 mm für 20–50 A, 16 mm für 100 A) und beeinflusst die Kalibrierung nicht.
Befehle
| Name | Opcode | Wirkung | Warten |
|---|---|---|---|
CMD_SET_CT_MODEL_CH0 |
0x28 |
Vorbereitetes CT_MODEL auf Kanal 0 zuordnen |
~5 ms |
CMD_SET_CT_MODEL_CH1 |
0x29 |
An Kanal 1 binden (UI2/UI3/I2/I3) | ~5 ms |
CMD_SET_CT_MODEL_CH2 |
0x2A |
An Kanal 2 binden (UI3/I3) | ~5 ms |
CMD_SAVE_USER_CONFIG |
0x32 |
Benutzerkonfigurationsblock (Sensorklasse, CT-Modell, Adresse, Bezeichnung) im Flash speichern | ~700 ms |
Vorgehen
- CT-Zange(n) in die Buchse(n) des Moduls stecken (Pfeil zur Last — siehe hardware-connection.md).
-
Sensorklasse setzen(einmalig, falls noch nicht gesetzt):
C++rb_write_u8(0x50, 0x25, 0x01); // SCT_013 -
Für jeden Kanal stellt das Modul bereit:
- CT-Modellcode vorbereiten auf
CT_MODEL:C++rb_write_u8(0x50, 0x05, 0x03); // example: SCT-013-030 - Ordnen Sie es dem Kanal mit der entsprechenden
CMD_SET_CT_MODEL_CHn:C++rb_write_u8(0x50, 0x01, 0x28); // CMD_SET_CT_MODEL_CH0 delay(5); - Für Kanal 1 / Kanal 2 wiederholen, sofern die Variante sie hat (Kanäle sind unabhängig — Modellcodes können je Kanal gemischt werden).
-
Speichernin den Flash mit
CMD_SAVE_USER_CONFIG:C++rb_write_u8(0x50, 0x01, 0x32); delay(700); // flash erase/write -
Fertig — mit einem Vorbehalt bei Firmware vor 1.4.20 (
CAPABILITYBit 12 gelöscht): Dort überdauert der gespeicherte Modell-Code Neustarts, die übernommene Skalierung jedoch nicht (siehe unten Was einen Neustart übersteht) — haben Sie ein nicht werkseitiges Modell gewählt, wiederholen Sie Schritt 3 (vorbereiten + festschreiben) nach jedem erkannten Neustart des Moduls;CMD_SAVE_USER_CONFIGmuss nicht wiederholt werden. Ab Firmware 1.4.20 übersteht der Modellwechsel Neustarts.
: Bei v1.3 können Sie CMD_SET_CT_MODEL_CH0/1/2 in beliebiger Reihenfolge aufrufen. Eine Umgehung mit absteigender Reihenfolge ist nicht nötig (das war ein internes Artefakt früherer Firmware).
Verhalten mit den aktuellen Client-Bibliotheken
Die rbAmp-Client-Bibliotheken (Arduino, ESP-IDF, ESPHome, Python) kapseln diesen Ablauf und ergänzen:
-
Erneutes Schreiben desselben Werts wird übersprungen. Das Setzen der Sensorklasse oder des CT-Modells auf den Wert, den das Modul bereits hat, löst keinen Buszugriff und keinen Flash-Zyklus aus — der Aufruf des Setters bei jedem Start ist unbedenklich.
-
Werkspaarte Module lehnen Klassen- und Modelländerungen ab. Bei SKUs, die als werkskalibriertes Set mit eigenem Stromsensor ausgeliefert werden (CT-Serie), sind Sensorklasse und -modell Teil der Kalibrierung: Das Modul (Firmware 1.4.22 und neuer) weist den Schreibvorgang im Normalbetrieb mit
ERR_PARAM (0xFE)zurück, und die Bibliotheken lehnen ihn bei allen Firmware-Versionen vor dem Senden ab. Das Neu-Paaren eines Ersatzsensors ist ein Werksservice. -
Grenzwerte je Modell. Für jedes CT-Modell stellen die Bibliotheken seinen Nennstrom, den Effektivwert, bei dem das Clipping einsetzt, und die Spitzenbegrenzung bereit — verwenden Sie diese, um Messwerte gegen den angeschlossenen Sensor zu prüfen.
Verifikation
Nach dem Binden wird das angewendete CT-Modell jedes Kanals bei 0x51..0x53 gespiegelt (schreibgeschützte Prüfspiegel). Dies sind NICHT das Staging-Register 0x05:
uint8_t ch0 = rb_read_u8(0x50, 0x51); // applied on ch0
uint8_t ch1 = rb_read_u8(0x50, 0x52); // applied on ch1
uint8_t ch2 = rb_read_u8(0x50, 0x53); // applied on ch2
Serial.printf("Applied: ch0=0x%02X ch1=0x%02X ch2=0x%02X\n", ch0, ch1, ch2);
⚠ Rücklesen ≠ Speicherung. Ein erfolgreiches Lesen von 0x51..0x53 bestätigt, dass der Wert live im RAM steht, nicht dass er den Flash überstanden hat. Zur Prüfung der Speicherung CMD_RESET ausführen (oder das Netz aus- und einschalten) und nach dem Startfenster erneut lesen. Das vollständige Muster steht in period-metering.md.
Wenn Sie ein neues Modul in Betrieb nehmen, führen Sie eine Plausibilitätsprüfung mit einer bekannten ohmschen Last durch (zum Beispiel eine 100-W-Glühlampe): I_rms ≈ 100 W / U_rms ≈ 0.43 A und P_real ≈ 100 W. Wenn die Messwerte um einen großen Faktor abweichen, ist der Modellcode wahrscheinlich falsch.
Was einen Neustart übersteht
CMD_SAVE_USER_CONFIG speichert den Benutzerkonfigurationsblock im Flash, aber nicht alles, was ein Master setzt, wird beim nächsten Start wieder angewendet. Bei Firmware vor 1.4.20 (CAPABILITY Bit 12 gelöscht):
| Position | Übersteht einen Neustart? |
|---|---|
| I²C-Adresse | ja |
| Modul-Bezeichnung | ja |
| Sensorklasse + CT-Modellcode (zurücklesbar) | ja |
| Übernommene Skalierung je Modell | vor Firmware 1.4.20: nein — fällt auf die Werkseinstellung zurück; ab 1.4.20 (CAPABILITY Bit 12 gesetzt): ja |
FLEET_CONFIG (GC-Aktivierung) + GROUP_ID |
ja (über CMD_SAVE_USER_CONFIG; wirkt nach Reset) |
| Konfiguration nur im RAM (Ereignisschwellen, Digest-Konfiguration) | nein |
Die Folge auf diesen Images: Ein Modul, das auf ein anderes Modell umgestellt wurde, als es das Werk verlassen hat, liefert nach einem Neustart das gespeicherte Modellkennzeichen zurück, misst aber bis zum erneuten Commit des Modells mit der Werksskalierung. Die Regel für jeden Master (und für einen Hub, der eine Flotte nach Modul-UID verwaltet):
-
Neustart erkennen —
UPTIME_S/ EreignisbitRESET_OCCURRED, siehe period-metering.md → Neustart eines Moduls erkennen. -
CT-Modell auf jedem Kanal neu vorbereiten und festschreiben (
CT_MODEL+CMD_SET_CT_MODEL_CHn), danach jede nur im RAM gehaltene Konfiguration erneut anwenden.
Die Client-Bibliotheken setzen genau dies in ihrem Resume-Pfad um. Ab fw 1.4.20 (CAPABILITY Bit 12, SCT_RATING_SELF) behält der Modellwechsel die Gerätekalibrierung bei und übersteht Neustarts — Schritt 2 entfällt dann für das CT-Modell; reine RAM-Konfiguration muss weiterhin neu initialisiert werden. Module, die mit ihrem Werksmodell laufen (einschließlich aller werkseitig gepaarten CT-Serie-Module), sind auf jedem Image nicht betroffen — die Werksskalierung ist die richtige.
— 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 |
Ablauf mit einem einzelnen Modul
- Verdrahten Sie das Modul gemäß hardware-connection.md.
- Bei BASIC-SCT-Modulen das Sensormodell einmal schreiben (vorheriger Abschnitt).
- Den Master mit der Funktionstest-Skizze flashen.
- Serieller Monitor öffnen — Sie sollten jede Sekunde U/I/P sehen.
- Wenn die Messwerte falsch aussehen, siehe troubleshooting.md.
Aufbau mit mehreren Modulen
Szenario: drei rbAmp-Module an einem Bus, um verschiedene Bereiche eines Hauses zu überwachen (Hauptzuleitung, Warmwasserbereiter, Klimaanlage).
Schritt 1 — Adressen
Ab Werk tragen alle drei Module die Adresse 0x50. Sie müssen einzeln neu adressiert werden. Verbinden Sie nur ein Modul mit dem Bus, bis die Neuadressierung abgeschlossen ist.
Schritt 2 — Funktionstest mit einem Modul
Verwenden Sie den obigen Abschnitt. Bestätigen Sie, dass ein Modul korrekt arbeitet.
Schritt 3 — Neu adressieren (und bei Bedarf das CT-Modell setzen)
Verwenden Sie den unten beschriebenen Adressänderungsablauf. Wenn die Module verschiedene SCT-013-Sensoren nutzen, stellen Sie das CT-Modell an jedem Modul ein, bevor Sie die Adressen ändern.
Schritt 4 — Abfrageschleife für mehrere Module
#include
const uint8_t modules[] = {0x50, 0x51, 0x52}; // main, boiler, AC
const char* labels[] = {"MAIN", "BOIL", "AC "};
const int N = sizeof(modules) / sizeof(modules[0]);
void setup() {
Serial.begin(115200);
Wire.begin();
Wire.setClock(50000);
delay(300);
for (int i = 0; i < N; i++) {
Wire.beginTransmission(modules[i]);
uint8_t rc = Wire.endTransmission();
Serial.printf("Module %s (0x%02X): %s\n",
labels[i], modules[i], rc == 0 ? "OK" : "MISSING");
}
}
void loop() {
for (int i = 0; i < N; i++) {
float u = rb_read_float_le(modules[i], 0x86);
float p = rb_read_float_le(modules[i], 0xA6);
Serial.printf("[%s] U=%.1f P=%.1f W\n", labels[i], u, p);
}
Serial.println();
delay(1000);
}
Erwartete Ausgabe:
Module MAIN (0x50): OK
Module BOIL (0x51): OK
Module AC (0x52): OK
[MAIN] U=229.8 P=850.3 W
[BOIL] U=229.7 P=1850.0 W
[AC ] U=229.9 P=0.0 W
...
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmpFleet::scan(match_product, added) / RbAmpFleet::pollAll(snaps, status, capacity, n_ok) |
die Module am Bus erkennen; alle in einem Durchgang lesen |
| ESP-IDF | rbamp_fleet_scan() / rbamp_fleet_poll_all() |
die Module am Bus erkennen; alle in einem Durchgang lesen |
| Python | fleet.scan(match_product=True) / fleet.poll_all() |
die Module am Bus erkennen; alle in einem Durchgang lesen |
| ESPHome | rbamp: (list) |
ein rbamp:-Block je Modul, jeweils mit eigener id und address |
Adressänderung
Die Werksadresse 0x50 ist im Benutzerkonfigurationsblock im Flash gespeichert. v1.3 verwendet einen Zwei-Phasen-Commit, damit versehentliche Adressänderungen schwer fallen: Eine Kandidatenadresse geht zuerst in ein RAM-Staging-Register, muss mit einem Magic-Byte scharf geschaltet werden und wird erst dann durch einen expliziten Befehl ins Flash committet. Ein Reset zählt das Modul unter der neuen Adresse neu auf.
Register und Befehle
| Name | Adresse / Opcode | Typ | Zweck |
|---|---|---|---|
REG_I2C_ADDRESS |
0x30 |
u8 RW | Vorbereitung für die Kandidatenadresse (0x08..0x77). Eine Regel: Vor dem Reset gibt 0x30 den vorbereiteten Kandidaten zurück; nach dem Start liest es die aktive Adresse. |
ADDR_COMMIT_MAGIC |
0x31 |
u8 W | Commit mit 0xA5 scharf schalten. Wird beim Commit-Versuch verbraucht (gelöscht). |
CMD_COMMIT_ADDR |
Opcode 0x30 in REG_COMMAND (0x01) geschrieben |
Befehl | Prüft die gestagte Adresse gegen das Magic und speichert sie im Flash. |
CMD_RESET |
Opcode 0x01, geschrieben in REG_COMMAND (0x01) |
Befehl | Weicher Reset. Das Modul meldet sich nach ~300 ms unter der neuen Adresse neu an. |
Vorgehen
- Nur ein Modul (noch auf
0x50) an den Bus anschließen. -
Neue Adresse vorbereiten:
C++rb_write_u8(0x50, 0x30, 0x51); // candidate address → RAM staging -
Commit scharf schalten:
C++rb_write_u8(0x50, 0x31, 0xA5); // ADDR_COMMIT_MAGIC -
Problem
CMD_COMMIT_ADDR(opcode0x30):C++rb_write_u8(0x50, 0x01, 0x30); -
Warten≥ 700 msfür das Löschen/Schreiben des Flash:
C++delay(700); -
Problem
CMD_RESET(opcode0x01) —CMD_COMMIT_ADDRtutnicht auto-reset:C++rb_write_u8(0x50, 0x01, 0x01); -
~300 ms für das Startfenster warten. Während dieses Fensters keine Befehle senden.
-
Prüfen Sie, ob das Modul unter der neuen Adresse mit ACK antwortet:
C++uint8_t ver = rb_read_u8(0x51, 0x03); // VERSION should be 0x04 on v1.3 if (ver == 0x04) Serial.println("Address change OK"); -
Markieren Sie die Platine mit der neuen Adresse per Wachsstift oder Etikett, damit Sie das Modul physisch identifizieren können.
Wichtige Hinweise
- Beide Stufen sind zwingend. Das Schreiben des Kandidaten allein nach
0x30bewirkt nichts Dauerhaftes — er landet nur im RAM und geht beim nächsten Reset verloren. Erst das Magic-und-Commit-Paar schreibt tatsächlich den Flash neu. - Die vorbereitete Adresse muss im Bereich
0x08..0x77liegen (gültige 7-Bit-I²C-Adresse). Außerhalb liegende Schreibvorgänge werden mitERR_PARAMabgelehnt; das Modul behält seine aktuelle Adresse. - Reservierte I²C-Adressen:
0x00(Allgemeiner Aufruf, siehe unten),0x01..0x07(CBus reserviert),0x78..0x7F(10-Bit reserviert). Diese nicht verwenden. - Eine Rücklesregel: Vor dem Reset gibt
0x30den vorbereiteten Kandidaten zurück; nach dem Start liest es die aktive Adresse. - Das scharfgeschaltete Magic verfällt nach 5 s ohne Commit (Kapitel 11 §6.1) — scharf schalten Sie erneut, wenn Sie zu lange gewartet haben.
- Hinweis zu den Adressräumen — derselbe Bytewert kann eine Adresse und ein Opcode sein:
| Byte | Als Registeradresse | Als Opcode (geschrieben in 0x01) |
|---|---|---|
0x27 |
FLEET_CONFIG |
CMD_LATCH_PERIOD |
0x28 |
GROUP_ID |
CMD_SET_CT_MODEL_CH0 |
0x30 |
REG_I2C_ADDRESS |
CMD_COMMIT_ADDR |
Vollständiges Beispiel zur Adressänderung
#include
bool change_address(uint8_t old_addr, uint8_t new_addr) {
if (new_addr < 0x08 || new_addr > 0x77) {
Serial.println("ERROR: invalid address");
return false;
}
Serial.printf("Changing 0x%02X -> 0x%02X\n", old_addr, new_addr);
rb_write_u8(old_addr, 0x30, new_addr); // 1. stage candidate
rb_write_u8(old_addr, 0x31, 0xA5); // 2. arm magic
rb_write_u8(old_addr, 0x01, 0x30); // 3. CMD_COMMIT_ADDR
delay(700); // 4. flash erase/write
rb_write_u8(old_addr, 0x01, 0x01); // 5. CMD_RESET (mandatory)
delay(300); // 6. boot window
Wire.beginTransmission(new_addr);
if (Wire.endTransmission() == 0) {
Serial.printf("OK, module now at 0x%02X\n", new_addr);
return true;
}
Serial.printf("FAIL: module not found at 0x%02X\n", new_addr);
return false;
}
void setup() {
Serial.begin(115200);
Wire.begin();
delay(300);
change_address(0x50, 0x51);
}
— 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 |
Allgemeiner Aufruf (Broadcast an Adresse 0x00)
Das I²C-Protokoll reserviert die Adresse 0x00 (Allgemeiner Aufruf) — Rahmen an diese Adresse werden von allen Slaves am Bus gleichzeitig empfangen. rbAmp kann seinen Periodenschnappschuss per Allgemeinem-Aufruf-Rahmen nehmen, aber nur, nachdem diese Funktion am Modul ausdrücklich aktiviert wurde.
Aktivierung auf Wunsch (Standard AUS)
Der GC-Schnappschussempfang ist standardmäßig deaktiviert — ein neues Modul wird den Allgemeinen-Aufruf-Rahmen mit NACK beantworten; der Master erkennt dies als harten Fehler und wechselt automatisch auf einen Einzelschnappschuss je Modul. So aktivieren Sie GC auf einem Modul:
- Bit 0 setzen von
FLEET_CONFIG:C++rb_write_u8(0x50, 0x27, 0x01); // bit0 = GC_ENABLE
Hinweis zum Wert 0x27: Dies ist die Registeradresse von FLEET_CONFIG. Derselbe Bytewert 0x27 ist zufällig auch der Befehls-Opcode für CMD_LATCH_PERIOD (ein eigener Adressraum — Opcodes gehen in REG_COMMAND bei 0x01). Die Überschneidung ist rein äußerlich; Adresse und Opcode werden auf Protokollebene nie verwechselt.
-
(optional) setzen
GROUP_IDzur Aufteilung der Flotte —0x00akzeptiert All-Call:C++rb_write_u8(0x50, 0x28, 0x00); // all-call -
Persist:
C++rb_write_u8(0x50, 0x01, 0x32); // CMD_SAVE_USER_CONFIG delay(700); -
Zurücksetzen und prüfen, dass das Bit übernommen wurde:
C++rb_write_u8(0x50, 0x01, 0x01); // CMD_RESET delay(300); uint8_t cfg = rb_read_u8(0x50, 0x27); if (cfg & 0x01) Serial.println("GC enabled");
GC-Frame-Format
GC-Schnappschuss-Rahmen haben ein festes Magic- und Opcode-Layout:
addr 0x00 | A5 27
A5— Rahmenkennung (der Slave weist jedes andere Byte zurück).27— Opcode (CMD_LATCH_PERIOD).— Zielgruppe (0x00= alle; andernfalls muss sie mit demGROUP_IDdes Moduls übereinstimmen).— 16-Bit-Tick-Zähler auf Master-Seite, gespiegelt in das RegisterGC_TICK (0x59)jedes Moduls zur Erkennung verpasster Rahmen.
Per Konstruktion tragen GC-Frames nur den Snapshot-Befehl — zerstörerische Opcodes (SAVE_*, COMMIT_ADDR, FACTORY_RESET) werden über General Call nicht ausgeführt.
Beispiel für einen Broadcast-Snapshot (nach der Aktivierung)
// All modules with GC enabled take their snapshots at once.
Wire.beginTransmission(0x00);
Wire.write(0xA5); // frame magic
Wire.write(0x27); // CMD_LATCH_PERIOD opcode
Wire.write(0x00); // group_id = all-call
Wire.write(tick & 0xFF); // tick_lo
Wire.write((tick >> 8) & 0xFF); // tick_hi
uint8_t rc = Wire.endTransmission();
if (rc != 0) {
// NACK at GC level → no module on the bus has GC enabled.
// Fall back to per-module sequential snapshot.
}
Nach dem Broadcast aktualisiert jedes Modul seinen Schnappschuss unabhängig. Der Master liest dann jedes Modul über seine einzelne Adresse. Zeugenprüfung (empfohlen): Nach ~50 ms Einschwingzeit V03_PERIOD_VALID (0x07) an jedem erwarteten Modul lesen — 1 bestätigt, dass der Schnappschuss übernommen wurde; 0 fällt nur bei diesem Modul auf den Einzelschnappschuss zurück.
Anwendung: präzise Periodensynchronisation für den Lastausgleich mehrerer Module (z. B. mains_input − solar_output), bei dem der Schnappschusszeitpunkt in allen Modulen identisch sein muss.
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::enableGc(enable) / RbAmpFleet::gcLatch(group, tick, settle_ms) |
Allgemeinen Aufruf am Modul aktivieren; den Schnappschuss-Rahmen an die Flotte senden |
| ESP-IDF | rbamp_enable_gc() / rbamp_fleet_gclatch() |
Allgemeinen Aufruf am Modul aktivieren; den Schnappschuss-Rahmen an die Flotte senden |
| Python | dev.enable_gc(enable=True) / fleet.gc_latch(group, tick, settle_ms) |
Allgemeinen Aufruf am Modul aktivieren; den Schnappschuss-Rahmen an die Flotte senden |
| ESPHome | fleet_gc_enable: / group_id: |
YAML-Optionen für die Aktivierung des Allgemeinen Aufrufs und die Gruppen-ID |
Empfohlener Ablauf für die Bereitstellung mehrerer Module
Step 1: Unbox all modules — every module is on address 0x50.
Step 2: For each module, one at a time:
a) Connect only this module to the bus.
b) If it is a BASIC SCT-series module: set SENSOR_CLASS (0x25), stage CT_MODEL (0x05),
issue CMD_SET_CT_MODEL_CHn for each channel, then CMD_SAVE_USER_CONFIG.
c) On images before fw 1.4.20 (`CAPABILITY` bit 12 clear): after any later reset of this
module, re-stage and re-commit CT_MODEL on each channel (see the persistence table above).
d) Run change_address(0x50, ).
e) Verify the module responds at the new address.
f) Physically mark the module (label with 0x51, 0x52, ...).
g) Disconnect and move to the next module.
Step 3: After readdressing all modules, connect them in parallel.
With four or more modules (or a longer bus), cut the built-in
pull-up jumpers on all but one (see hardware-connection.md → I2C pull-ups).
Step 4: At master boot, run a scan loop and verify every readdressed
module responds at its expected address.
BASIC oder STD?
Die STD-Linie von rbAmp antwortet auf demselben Bus, verwendet aber eine andere Registerübersicht mit 16 Bit. Bevor Sie die unten beschriebene BASIC-Erkennung anwenden, können Sie unterscheiden: Senden Sie den 16-Bit-Zeiger 0x00 0x00 und lesen Sie 2 Byte — ein STD-Modul liefert das ASCII-Paar 'S','T' (0x53 0x54); ein BASIC-Modul nicht (es behandelt die Bytes als 8-Bit-Registerschreibvorgänge und liefert seine normalen Daten). STD-Module sind in ihrer eigenen Referenzdokumentation beschrieben.
Das müssen Sie nicht selbst tun, wenn Sie eine Client-Bibliothek verwenden. Die Bibliotheken (Arduino, ESP-IDF, Python, ESPHome) erkennen die Modulreihe bereits und behandeln die unterschiedlichen Registergrößen — Sie müssen nicht berücksichtigen, ob die Registerübersicht 8 oder 16 Bit hat.
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::line() / RbAmp::begin() |
Leitung in begin() erkannt; aus dem zwischengespeicherten Wert zurücklesen |
| ESP-IDF | rbamp_line() / rbamp_begin() |
Leitung in begin erkannt; aus dem Zwischenspeicher zurücklesen |
| Python | dev.is_std / dev.begin() |
Leitung in begin() erkannt; über die Property zurücklesen |
| ESPHome | — | nicht verfügbar — die Erkennung erfolgt automatisch, in YAML ist nichts einzustellen |
Automatische Erkennung der Modulvariante
⚠ Erkennen Sie die Variante nicht durch Abfragen eines NACK bei Registerlesezugriffen. Die Firmware quittiert Registerlesezugriffe nie mit NACK — nicht abgebildete Adressen liefern 0x00 (siehe Kapitel 11 §5.2). Eine NACK-basierte Prüfung meldet immer „Kanal vorhanden“.
Verwenden Sie das kanonische Paar HW_VARIANT (0x55) + CAPABILITY (0x57/0x58):
struct VariantInfo {
uint8_t hw_variant; // 1=UI1, 2=UI2, 3=UI3, 4=I1, 5=I2, 6=I3
uint8_t n_current; // 1..3
bool has_voltage; // true on UI*, false on I*
};
VariantInfo detect_variant(uint8_t addr) {
VariantInfo v = {0, 0, false};
uint8_t product = rb_read_u8(addr, 0x54); // PRODUCT_ID
if (product != 0x01) return v; // not an rbAmp sensor
v.hw_variant = rb_read_u8(addr, 0x55); // HW_VARIANT
uint8_t hw = v.hw_variant;
v.n_current = (hw == 1 || hw == 4) ? 1
: (hw == 2 || hw == 5) ? 2
: (hw == 3 || hw == 6) ? 3 : 0;
uint8_t cap_hi = rb_read_u8(addr, 0x58); // CAPABILITY high byte
v.has_voltage = (cap_hi & 0x01) != 0; // bit 8 of u16 = voltage-HW
return v;
}
HW_VARIANT 1..3 sind UI-Varianten (has_voltage == true); 4..6 sind Nur-Strom-Varianten (has_voltage == false). Eine Abweichung zwischen der HW_VARIANT-Familie und CAPABILITY.bit8 deutet auf ein defektes oder falsch geflashtes Modul hin.
AC_FREQ (0x20) funktioniert bei allen Varianten — das Nulldurchgangssignal stammt von einem eigenen Netz-ZC-Pin, unabhängig vom Spannungs-Frontend.
— dieselbe Aufgabe ohne Registerzugriff:
| Bibliothek | Aufruf | Was es tut |
|---|---|---|
| Arduino | RbAmp::readVariant() / RbAmp::readCapability(out) |
die Hardwarevariante und die Capability-Map lesen |
| ESP-IDF | rbamp_read_variant() / rbamp_read_capability() |
die Hardwarevariante und die Capability-Map lesen |
| Python | dev.read_variant() / dev.read_capability() |
die Hardwarevariante und die Capability-Map lesen |
| ESPHome | get_variant_str() / get_capability_hex() |
Variantentext und Capability-Bitmap aus der Identitätsoberfläche |
Weiter
- realtime-polling.md — Echtzeit-Abfrage im Detail (100-ms-Fenster, DRDY)
- period-metering.md — Aufsummierung der Tarifenergie