rbAmp
DE
Shop
Docs
Aktualisiert

02 · Initialisierung und Inbetriebnahme

rbAmp beginnt sofort nach dem Einschalten zu messen. Der Master muss nur:

  1. I²C-Bus initialisieren (Standard-Wire / HAL-Initialisierung).
  2. ~250 ms warten oder DATA_VALID = 1 am Register 0xCE abfragen.
  3. Optional die Firmwareversion von 0x03 als Plausibilitätsprüfung lesen.
  4. 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.

Der Ablauf vom Einschalten bis zum ersten gültigen Messwert.

Hinweis

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:

C
// 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

C++
#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)

C++
#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):

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

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.

Sicherheit

⚠ 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

  1. Stromzangen anschließen (Pfeil zur Last — siehe hardware-connection.md) und das Modul einschalten.
  2. Die Klasse lesen (SENSOR_CLASS, 0x25): 2 = Serie der CT-Zangen.
  3. 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, Feld CT_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.

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

Hinweis

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
Hinweis

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
Hinweis

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

  1. CT-Zange(n) in die Buchse(n) des Moduls stecken (Pfeil zur Last — siehe hardware-connection.md).
  2. Sensorklasse setzen(einmalig, falls noch nicht gesetzt):

    C++
    rb_write_u8(0x50, 0x25, 0x01);    // SCT_013
    

  3. Für jeden Kanal stellt das Modul bereit:

  4. CT-Modellcode vorbereiten aufCT_MODEL:
    C++
    rb_write_u8(0x50, 0x05, 0x03);    // example: SCT-013-030
    
  5. Ordnen Sie es dem Kanal mit der entsprechendenCMD_SET_CT_MODEL_CHn:
    C++
    rb_write_u8(0x50, 0x01, 0x28);    // CMD_SET_CT_MODEL_CH0
    delay(5);
    
  6. Für Kanal 1 / Kanal 2 wiederholen, sofern die Variante sie hat (Kanäle sind unabhängig — Modellcodes können je Kanal gemischt werden).
  7. Speichernin den Flash mitCMD_SAVE_USER_CONFIG:

    C++
    rb_write_u8(0x50, 0x01, 0x32);
    delay(700);                          // flash erase/write
    

  8. Fertig — mit einem Vorbehalt bei Firmware vor 1.4.20 (CAPABILITY Bit 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_CONFIG muss nicht wiederholt werden. Ab Firmware 1.4.20 übersteht der Modellwechsel Neustarts.

Unabhängigkeit der Kanalreihenfolge

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

C++
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);
Sicherheit

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

  1. Neustart erkennen — UPTIME_S / Ereignisbit RESET_OCCURRED, siehe period-metering.md → Neustart eines Moduls erkennen.

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

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

Ablauf mit einem einzelnen Modul

  1. Verdrahten Sie das Modul gemäß hardware-connection.md.
  2. Bei BASIC-SCT-Modulen das Sensormodell einmal schreiben (vorheriger Abschnitt).
  3. Den Master mit der Funktionstest-Skizze flashen.
  4. Serieller Monitor öffnen — Sie sollten jede Sekunde U/I/P sehen.
  5. 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

C++
#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:

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

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

Die zweiphasige Adressänderung: neue Adresse vorbereiten, scharf schalten, committen, dann zurücksetzen.

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

  1. Nur ein Modul (noch auf 0x50) an den Bus anschließen.
  2. Neue Adresse vorbereiten:

    C++
    rb_write_u8(0x50, 0x30, 0x51);    // candidate address → RAM staging
    

  3. Commit scharf schalten:

    C++
    rb_write_u8(0x50, 0x31, 0xA5);    // ADDR_COMMIT_MAGIC
    

  4. ProblemCMD_COMMIT_ADDR (opcode 0x30):

    C++
    rb_write_u8(0x50, 0x01, 0x30);
    

  5. Warten≥ 700 msfür das Löschen/Schreiben des Flash:

    C++
    delay(700);
    

  6. ProblemCMD_RESET (opcode 0x01) — CMD_COMMIT_ADDRtutnicht auto-reset:

    C++
    rb_write_u8(0x50, 0x01, 0x01);
    

  7. ~300 ms für das Startfenster warten. Während dieses Fensters keine Befehle senden.

  8. 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");
    

  9. 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 0x30 bewirkt 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..0x77 liegen (gültige 7-Bit-I²C-Adresse). Außerhalb liegende Schreibvorgänge werden mit ERR_PARAM abgelehnt; 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 0x30 den 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

C++
#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);
}
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

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:

  1. Bit 0 setzen vonFLEET_CONFIG:
    C++
    rb_write_u8(0x50, 0x27, 0x01);    // bit0 = GC_ENABLE
    
Hinweis

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.

  1. (optional) setzenGROUP_IDzur Aufteilung der Flotte —0x00akzeptiert All-Call:

    C++
    rb_write_u8(0x50, 0x28, 0x00);    // all-call
    

  2. Persist:

    C++
    rb_write_u8(0x50, 0x01, 0x32);    // CMD_SAVE_USER_CONFIG
    delay(700);
    

  3. 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:

Byte-Layout des General-Call-Snapshot-Frames.

Text
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 dem GROUP_ID des Moduls übereinstimmen).
  • — 16-Bit-Tick-Zähler auf Master-Seite, gespiegelt in das Register GC_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)

C++
// 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.

In den Client-Bibliotheken

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

Wie sich ein BASIC-Modul zur Laufzeit von einem STD-Modul unterscheidet.

In den Client-Bibliotheken

— 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

Sicherheit

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

C++
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.

In den Client-Bibliotheken

— 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