rbAmp
DE
Shop
Docs
Aktualisiert · Auf GitHub bearbeiten [Edit on GitHub]

09 · API-Referenz

Registerkarte des Moduls: der Adressraum der Seite 0 von 0x00 bis 0xFF.

Atomarer Periodensnapshot: ein Schreibvorgang schließt die aktuelle Periode und öffnet die nächste.

Die öffentliche API der RbAmp-Bibliothek für Arduino ab v1.6.1. Eine Klasse bedient beide Modul-Produktlinien — BASIC und STANDARD (STD): begin() erkennt die Linie, und jeder Aufruf wird intern weitergeleitet. Aufrufe, die nur auf einer Linie existieren, sind gekennzeichnet; ein Aufruf ohne Gegenstück auf der erkannten Linie schlägt mit RB_ERR_NOT_IMPLEMENTED fehl. Maßgeblich sind die Headerdateien src/RbAmp.h, src/RbAmpSnapshot.h, src/RbAmpEnergy.h, src/RbAmpSensorModels.h, src/RbAmpRegisters.h (die letzten beiden werden automatisch erzeugt und dürfen nicht von Hand bearbeitet werden).

Dieses Kapitel ist ein Nachschlagewerk: Signaturen, Rückgabewerte, Nebenwirkungen, Grenzfälle. Arbeitsbeispiele finden Sie unter 06 · Beispiele; zum schnellen Einstieg 05 · Schnellstart.

Header-Dateien

Einbinden Was es mitbringt
Alle öffentlichen Typen (ziehen den Rest nach)
RbAmpSnapshot, RbAmpPeriodSnapshot, RbAmpTopology, RbAmpVariant, RbAmpLine, RbAmpSensorClass, RbAmpSctRating, RbAmpDrdyEvent und die RbAmpStd*-Strukturen der STD-Linie
RbAmpEnergy
Generiertes Sensormodell-Register — die Modellcodes RBAMP_CT_* und rbamp_sensor_model_lookup()
Automatisch erzeugte Protokollkonstanten — RB_OK, RB_ERR_*, SETTLE_MS_*

Ein Benutzer-Sketch braucht normalerweise nur #include — der Rest wird transitiv eingebunden.

Auf welcher Linie funktioniert ein Aufruf?

Gruppe BASIC STD
Lebenszyklus, Echtzeit-Lesezugriffe (readVoltage … readAll), Periodenmessung, energy() ja ja
readReactivePower(), readApparentPower() nein (RB_ERR_NOT_IMPLEMENTED) ja
Setter für Sensorklasse / CT-Modell, saveUserConfig(), Adressänderung, reset() ja ja (das CT-Modell ist auf STD eine Bezeichnung, siehe unten)
factoryReset(), General-Call-Helfer, Label-Helfer, readCapability(), readCommitSeq(), readPeriodLatchMs() ja nein (RB_ERR_NOT_IMPLEMENTED)
Data-Ready-Leitung und Ereignisse (setDrdyPin(), waitDataReady(), setEventMask() …) ja ja (abhängig vom Modul-Image, siehe unten)
std*-Aufrufe (STD-Linien-API) nein (RB_ERR_NOT_IMPLEMENTED) ja
SCT-013-Nennkorrektur (sctRating*()) ja (SCT-013-Klasse, ältere BASIC-Firmware) nie angewendet (Skalierung 1)

Einige STD-Funktionen hängen von der Version des Modul-Images ab: Mikro-Energiezähler, der Anlaufstrom für Energie, Spannungs-Phasenwinkel und die Phasenfolge benötigen ein Image von mindestens 0x0001007B (stdReadImageVersion()). Auf einem älteren Image meldet die Bibliothek sie als „nicht verfügbar“ (ein valid-Flag, das false ist, ein abgeleiteter Wert oder RB_ERR_NOT_IMPLEMENTED) — nie als falsche Zahl.

Klasse RbAmp

Der Hauptclient. Eine Instanz je Slave-Gerät auf dem I²C-Bus. Mehrere Instanzen können sich einen TwoWire-Bus teilen, um mehrere Module abzufragen.

Konstruktor

C++
explicit RbAmp(TwoWire& bus,
               uint8_t addr = 0x50,
               RbAmpTopology hint = RbAmpTopology::Single) noexcept;
Parameter Beschreibung
bus Referenz auf den TwoWire-Bus (meist Wire). Der Aufrufer muss bus.begin() VOR begin() aufrufen.
addr 7-Bit-Slave-Adresse. Bereich 0x08..0x77, Standard 0x50.
hint Topologie-Hinweis: die Anzahl der Stromkanäle (1/2/3). Auf Firmware vor v1.3 kann begin() die Variante nicht zuverlässig bestimmen, daher dient der Hinweis als Rückfall für Mehrkanal-SKUs. Standard ist Single — der sichere Standard, der keine falschen Lesevorgänge nicht vorhandener Kanäle auslöst. Für Mehrkanal-Module auf Firmware vor v1.3 übergeben Sie den passenden Hinweis ausdrücklich.

Der Konstruktor erzeugt keinen I²C-Verkehr.

Lebenszyklus-Methoden

bool begin() noexcept

Das Gerät abfragen, seine Produktlinie und Variante erkennen, die Momentaufnahme vorbereiten.

Sequence:

  1. STD-Identitätsprüfung zuerst. Meldet sich das Modul als STD-Modul, kommen die Kanalanzahlen vom Modul selbst, Snapshot-Bank 0 wird scharf geschaltet und vorbereitet, und begin() kehrt zurück — die BASIC-Schritte unten entfallen.

  2. Lesen Sie REG_VERSION (0x03). Hat das Gerät nicht bestätigt — false mit RB_ERR_NACK. Hat es 0x00 / 0xFF geliefert — false mit RB_ERR_VERSION.

  3. Topologie zwischenspeichern: das Varianten-Byte des Moduls auf Firmware, die es bereitstellt, sonst der Konstruktor-hint. Danach liefern topology() / channels() gültige Werte, ohne den Bus zu berühren. Die Kanalanzahl überschreitet nie RBAMP_MAX_CHANNELS (7); darüber liegende Kanäle werden nicht bereitgestellt, und ihre Adressierung liefert RB_ERR_PARAM.

  4. Lesen Sie U_rms, um festzustellen, ob ein Spannungssensor vorhanden ist (Schwelle 1.0 V).

  5. Schreiben Sie CMD_LATCH_PERIOD als Vorlauf + 50 ms warten. Die erste Momentaufnahme nach dem Einschalten wird verworfen (sie wird dem Anwendercode nicht übergeben — sie enthält Daten von vor dem Einschalten).

  6. millis() für die anschließende Energieintegration speichern.

  7. Bei einem BASIC-Modul mit der SCT-013-Klasse lesen Sie die kanalbezogene Nennkorrektur (siehe SCT-013-Nennkorrektur). Befindet sich das Modul in einem Zustand, der einen Neustart zur Übernahme der richtigen Verstärkung erfordert, startet begin() es einmal neu.

Idempotent: erneuter Aufruf ist unbedenklich.

Rückgabe: true bei Erfolg; andernfalls false — Details unter lastError().

bool probe() noexcept

Eine leichtgewichtige Lebendprüfung. Ein einzelnes Lesen von REG_VERSION ohne Nebenwirkungen.

Rückgabe: true, wenn der Slave bestätigt hat und eine unterstützte Version meldet (weder 0 noch 0xFF).

bool waitReady(uint32_t timeout_ms = 1000) noexcept

Fragt das Bereitschaftsflag des Moduls ab, bis Bit 0 gesetzt ist. Nützlich nach dem Einschalten — das Modul braucht unter Umständen bis zu einem Messfenster (100 ms), um die ersten Daten festzuschreiben.

Rückgabe: true, wenn das Bit vor Ablauf von timeout_ms gesehen wurde; andernfalls false mit RB_ERR_TIMEOUT.

uint8_t firmwareVersion() noexcept

Rückgabe: das Byte REG_VERSION (0x03). Bekannte BASIC-Werte: 0x01 = v1.0, 0x02 = v1.1, 0x03 = v1.2, 0x04 = v1.3. Neuere BASIC-Firmware meldet höhere Werte. 0 oder 0xFF zeigen einen I²C-Fehler an (siehe lastError()).

RbAmpLine line() const noexcept

Rückgabe: die von begin() erkannte Produktlinie — RbAmpLine::Basic (der Wert, bis begin() gelaufen ist) oder RbAmpLine::Std. Kein Buszugriff.

RbAmpTopology topology() const noexcept

Rückgabe: die zwischengespeicherte Topologie. Kein Buszugriff.

uint8_t channels() const noexcept

Rückgabe: die Anzahl der Stromkanäle, 1..RBAMP_MAX_CHANNELS (7). Bei der STD-Linie ist die Anzahl das, was das Modul meldet, begrenzt auf RBAMP_MAX_CHANNELS.

bool hasVoltageHw() const noexcept

Rückgabe: true, wenn bei begin() ein Spannungssensor erkannt wurde. Zwischengespeichert, kein Verkehr.

uint8_t address() const noexcept

Rückgabe: die aktuelle 7-Bit-I²C-Adresse. Wird nach einem erfolgreichen commitAddressChange() aktualisiert.

uint8_t rawTopology() noexcept

Ein direktes Lesen von REG_TOPOLOGY (0x24). Anders als topology() führt dies eine I²C-Transaktion aus.

Returns:

  • 1/2/3 — SINGLE/SPLIT_PHASE/THREE_PHASE.
  • 0xFF — I²C-Fehler.
Hinweis

Für die vollständige SKU-Erkennung verwenden Sie readVariant() (liest REG_HW_VARIANT 0x55) — siehe Identifikation und Provisionierung.

Echtzeit-Lesezugriffe (RT-Block, Aktualisierung alle 100 ms)

Zeitsteuerung des Echtzeitfensters: direkt aufeinanderfolgende 100-ms-Fenster, ein kurzer DRDY-Impuls je Fenster und der atomare Ergebnisblock wird in einem Burst gelesen.

Alle Methoden liefern float. Bei Fehlern liefern sie NAN und setzen lastError(). Im Hintergrund wird für die Robustheit gegen seltene Verbindungsstörungen auf ESP-IDF ein Wiederholungs- und Plausibilitätsfilter verwendet (siehe die Diagnosezähler unten). Das Modul veröffentlicht neue Werte einmal pro Messfenster — 100 ms (BASIC-Firmware vor v1.2 und STD-Images bis 0x7B: 200 ms).

float readVoltage(uint8_t phase = 0) noexcept

Momentaner Effektivwert der Spannung. phase ist 0 auf der BASIC-Linie; auf der STD-Linie ist sie 0 .. n_voltage-1 (siehe stdInfo()). Eine Phase außerhalb des Bereichs liefert NAN mit RB_ERR_PARAM.

float readVoltagePeak(uint8_t phase = 0) noexcept

Spitzenspannung über das RT-Fenster. Dieselbe phase-Regel gilt.

float readCurrent(uint8_t ch = 0) noexcept

Momentaner Effektivstrom an einem Kanal. ch muss < channels() sein — andernfalls NAN mit RB_ERR_PARAM. Dazu gehört jeder Kanal ab RBAMP_MAX_CHANNELS (7).

float readCurrentPeak(uint8_t ch = 0) noexcept

Spitzenstrom auf einem Kanal über das RT-Fenster.

float readPower(uint8_t ch = 0) noexcept

Momentane Wirkleistung an einem Kanal. Vorzeichenbehaftet — ein negativer Wert bedeutet Einspeisung (die Last speist Leistung ins Netz zurück, relevant für PV- / bidirektionale Anlagen).

float readPowerFactor(uint8_t ch = 0) noexcept

Leistungsfaktor an einem Kanal. Dimensionslos, Bereich −1..+1.

float readReactivePower(uint8_t ch = 0) noexcept — nur STD

Blindleistung auf einem Kanal, in var, mit Vorzeichen. Bei BASIC stellt diese Bibliothek keine Blindleistung bereit: Der Aufruf gibt NAN mit RB_ERR_NOT_IMPLEMENTED zurück.

float readApparentPower(uint8_t ch = 0) noexcept — nur STD

Scheinleistung an einem Kanal in VA. Auf einem BASIC-Modul liefert er NAN mit RB_ERR_NOT_IMPLEMENTED.

float readFrequency() noexcept

Netzfrequenz in Hz.

bool readAll(RbAmpSnapshot& out) noexcept

Der vollständige RT-Block in einem einzigen Aufruf in eine RbAmpSnapshot-Struktur. Entspricht sequenziell readVoltage() + readVoltagePeak()

  • readCurrent(0..N) + readCurrentPeak(0..N) + readPower(0..N) + readPowerFactor(0..N) + readFrequency(). Nicht genutzte Kanäle (über channels() hinaus) werden mit Nullen gefüllt.

Ein einzelnes Feld, das gelesen wird, aber den physikalischen Plausibilitätsfilter nicht besteht, wird auf NAN gesetzt und in out.implausible markiert (Bits RBAMP_FIELD_*); der Rest der Momentaufnahme bleibt verwendbar.

Rückgabe: true, solange kein Transportlesezugriff fehlgeschlagen ist — sonst false, und lastError() enthält den Code des ersten Fehlers.

Periodenmessung

Das große Bild finden Sie unter 01 · Überblick, eine minimale Vorlage in 05 · Schnellstart, Schritt 5.

bool latchPeriod() noexcept

Schreibt CMD_LATCH_PERIOD (0x27) in REG_COMMAND. Wartet nicht — der Aufrufer muss selbst die 50 ms Einschwingzeit abwarten und isPeriodValid() prüfen, bevor er liest.

Für die meisten Aufgaben verwenden Sie readPeriodSnapshot() — es kapselt die gesamte Abfolge.

Rückgabe: true bei einem erfolgreichen Schreibvorgang.

bool isPeriodValid() noexcept

Liest das Bereitschaftsbit des Snapshots. true, wenn der letzte Snapshot aktuell und lesbar ist.

float readPeriodAvgPower(uint8_t ch = 0) noexcept

Mittlere Wirkleistung auf einem Kanal über den abgeschlossenen Zeitraum. Muss nach latchPeriod() + 50 ms Einschwingzeit und Gültigkeitsprüfung aufgerufen werden.

float readPeriodMaxPower() noexcept

Spitzen-Momentanleistung auf Kanal 0 über die abgeschlossene Periode.

uint32_t readPeriodLatchMs() noexcept

Dauer der Periode aus Sicht des Geräts, in ms.

Diagnosewert.

latch_ms ist ein diagnostischer Zeitgeber des Moduls; verwenden Sie ihn nicht für Energie — nutzen Sie die Masteruhr (master_dt_ms aus RbAmpPeriodSnapshot).

bool readPeriodSnapshot(RbAmpPeriodSnapshot& out, uint16_t settle_ms = 50, bool skip_latch = false) noexcept

Der empfohlene Einstiegspunkt für die Periodenmessung. Die vollständige Abfolge im Hintergrund:

  1. Bei skip_latch == true — den Schreibzugriff auf den Momentaufnahmebefehl überspringen (gilt nach broadcastLatch() oder einer manuellen Folge von Momentaufnahmebefehlen).

  2. Andernfalls — CMD_LATCH_PERIOD schreiben.

  3. Erfassen Sie millis(), um master_dt_ms zu berechnen.
  4. delay(settle_ms) — standardmäßig 50 ms laut Protokollspezifikation.

  5. Prüfen Sie das Bereitschaftsflag des Snapshots. Bei 0 — setzen Sie RB_ERR_STALE und halten Sie den Zeitstempel fest (damit der nächste Snapshot nicht um dt doppelt zählt).

  6. Lesen Sie avg_p[0..channels-1] + max_p + latch_ms.

  7. Den Zeitstempel aktualisieren + energy().tick(out, channels_) aufrufen für die automatische Wh-Integration.
Parameter Beschreibung
out Ausgabestruktur.
settle_ms Wartezeit nach dem Snapshot-Befehl, standardmäßig 50.
skip_latch Bei true — den Snapshot-Befehl nicht senden, nur lesen (für eine synchronisierte Mehrboard-Szene).

Rückgabe: true, wenn out.valid == true; false, wenn der Lesezugriff fehlgeschlagen ist oder die Momentaufnahme veraltet ist.

Auf der STD-Linie wird das Einschwingen nach einem Snapshot auf mindestens 300 ms angehoben (das Modul bedient den Snapshot an der nächsten Messfenstergrenze), latch_ms ist 0, und master_dt_ms ist die Periode. Bei einem STD-Modul, das persistente Lebensdauer-Zähler statt Snapshot-Bänke führt, ist die Periode die Differenz zweier Zählerstände im Zeitplan des Masters; avg_p_total, wh_net und module_restarted des Snapshots werden dort befüllt.

Energiemessung (Akkumulator auf Masterseite)

RbAmpEnergy& energy() noexcept

const RbAmpEnergy& energy() const noexcept

Zugriff auf den Wh-Akkumulator je Kanal dieser RbAmp-Instanz. Der Akkumulator wird bei jedem erfolgreichen readPeriodSnapshot() automatisch aktualisiert. Details im Abschnitt „RbAmpEnergy-Klasse“ unten.

double energyWh(uint8_t ch = 0) const noexcept

Der laufende Energiesaldo eines Kanals, wie energy().wh(ch) — außer bei einem STD-Modul, das persistente Zähler führt, aber keine Aufteilung je Kanal veröffentlicht (mehr als ein Kanal, älteres Registerlayout): eine Anfrage je Kanal liefert dort NaN statt einer 0, die als „nichts verbraucht“ gelesen würde. Verwenden Sie RBAMP_ENERGY_CH_TOTAL als ch für die Gesamtsumme aller Kanäle.

Sensorkonfiguration

Eine zweistufige Abfolge: zuerst die Sensorklasse, dann das Modell. Beide Schritte sind Pflicht auf BASIC-Firmware v1.2 und später.

Eine ausführliche Anleitung zur Modellauswahl finden Sie unter 03 · Auswahl des Stromsensors.

Hinweis

CT-Modell — auf BASIC eine Funktionsvorgabe, auf STD nur eine Bezeichnung. Bei einem BASIC-Modul wendet das Schreiben des CT-Modells sofort die passende Vorgabe an — die Messwerte ändern sich. Ändern Sie die RbAmpSensorClass, werden die CT-Modelle der Kanäle auf dem Modul auf 0 zurückgesetzt. Bei einem STD-Modul ist das Modell nur eine Referenz (Sensorbezeichnung): Es setzt keine Verstärkung, weil das Modul je Kanal kalibriert ist.

Read-before-write. Die Setter lesen zuerst das Modul. Das Schreiben einer Klasse oder eines Modells, das das Modul bereits hält, ist ein No-op (true, kein Buszugriff, kein Flash-Zyklus). So kann eine gespeicherte Konfiguration bei jedem Booten erneut angewendet werden, ohne die Kalibrierung des Moduls zu berühren. Ein Modul der Klasse WiredCT oder BuiltinCT (ausgeliefert und zusammen mit seinem Sensor kalibriert) wird nicht neu konfiguriert: der Setter liefert false mit RB_ERR_MODE und schreibt nichts. setCTModelChForce() ist der Serviceweg.

Das Setzen eines CT-Modells startet das Modul neu. Auf BASIC-Firmware bis 1.4.19 mit der SCT-013-Klasse starten setCTModel() (beide Formen) und configureChannels() das Modul nach dem Speichern neu, damit das neue Modell wirksam wird (insgesamt etwa eine Sekunde, blockierend), und lesen danach die Nennkorrektur erneut. Rufen Sie sie nicht in einer Schleife auf und erwarten Sie in dieser Zeit keine Messwerte.

bool setSensorClass(RbAmpSensorClass cls) noexcept

Die Stromsensorklasse mit einem Speichern in den Flash setzen.

Ablauf: die aktuelle Klasse des Moduls lesen (read-before-write) → REG_SENSOR_CLASS (0x25) schreiben → CMD_SAVE_USER_CONFIG (0x32) → 700 ms warten (Flash-Löschung). Blockierend. Produktionstauglich — SAVE_USER_CONFIG ist nicht gesperrt.

Muss vor setCTModel() aufgerufen werden. Andernfalls gibt setCTModel() false mit RB_ERR_PARAM zurück. Außerdem setzt es die CT-Modelle auf Geräteseite auf 0 zurück, daher die Modelle anschließend setzen. Bei der STD-Linie ist die Klasse eine Metainformation, die mit dem Speichern der Modulkonfiguration gesichert wird, und dieselben Regeln "Lesen vor Schreiben" gelten.

Argument Bedeutung
RbAmpSensorClass::Sct013 Stromwandler-Zange der SCT-013-Serie, vom Anwender angeschlossen; das Modell wählt den Sensortyp
RbAmpSensorClass::WiredCT verdrahteter Stromwandler, der mit dem Modul ausgeliefert und zusammen mit ihm kalibriert wurde — wird von den Setzern nicht umgeschrieben
RbAmpSensorClass::BuiltinCT eingebauter CT, zusammen mit dem Modul kalibriert — wird von den Settern nicht neu geschrieben

Rückgabe: true bei Erfolg oder wenn das Modul bereits cls hat. false mit RB_ERR_MODE, wenn das Modul die Klasse WiredCT / BuiltinCT hat.

bool readSensorClass(uint8_t& out) noexcept

Liest die Sensorklasse des Stromsensors des Moduls (ein Wert RbAmpSensorClass; 0 = nicht gesetzt). Funktioniert auf beiden Linien.

Rückgabe: true bei Erfolg.

bool setCTModel(uint8_t code) noexcept

Die Einzelparameterform — setzt das CT-Zangenmodell nur auf Kanal 0. Praktisch für SKUs mit einem Kanal (UI1/I1); bei Mehrkanal-SKUs entspricht sie setCTModel(0, code).

Ablauf: REG_CT_MODEL (0x05) schreiben → CMD_SET_CT_MODEL_CH0 (Opcode 0x28) → 5 ms Einschwingzeit → CMD_SAVE_USER_CONFIG (Opcode 0x32) → 700 ms. Produktionstauglich — nutzt den Speicherpfad der Anwenderkonfiguration, ohne Werksmodus-Sperre.

Benennen Sie das Modell mit dem erzeugten Define RBAMP_CT_* (aus RbAmpSensorModels.h), zum Beispiel RBAMP_CT_SCT013_030:

Definieren code Modell
RBAMP_CT_SCT013_005 1 SCT-013-005
RBAMP_CT_SCT013_010 2 SCT-013-010
RBAMP_CT_SCT013_030 3 SCT-013-030
RBAMP_CT_SCT013_050 4 SCT-013-050
RBAMP_CT_SCT013_100 5 SCT-013-100
RBAMP_CT_SCT013_020 6 SCT-013-020
RBAMP_CT_SCT013_060 7 SCT-013-060

Ein code, der in der Registry für die Klasse des Moduls nicht vorkommt → false mit RB_ERR_PARAM und ohne Schreibzugriff. Ein Code, der in der Registry steht, den das Modul aber nicht akzeptiert, wird vom Modul mit RB_ERR_PARAM abgewiesen; der Kanal behält sein bisheriges Modell. Die vollständige Akzeptanzmenge je Klasse finden Sie unter 03 · Auswahl des Stromsensors.

Für Mehrkanal-Module verwenden Sie die kanalbezogene Form unten.

bool setCTModel(RbAmpCTModel model) noexcept

Überladung mit typisiertem Enum für die sieben SCT-013-Codes (RbAmpCTModel::Sct013_030 …). Entspricht setCTModel(static_cast(model)). Aus Gründen der Abwärtskompatibilität beibehalten; neuer Code übergibt ein generiertes RBAMP_CT_*-Define an die Form uint8_t, die die einzige Möglichkeit ist, ein verdrahtetes CT-Modell zu benennen.

bool setCTModel(uint8_t channel, uint8_t code) noexcept

Die kanalweise Form. Setzt das CT-Zangenmodell auf einem bestimmten Kanal, 0 .. channels()-1 (Kanäle 3 und höher sind die Kanäle der Top-SKU; sie benötigen BASIC-Firmware v1.4.18 oder neuer).

Unter der Haube: Schreiben von REG_CT_MODEL (0x05) → Befehl CMD_SET_CT_MODEL_CH0/1/2 (Opcode 0x28/0x29/0x2A) je nach channel → 5 ms Einschwingzeit → CMD_SAVE_USER_CONFIG (Opcode 0x32) → 700 ms. Produktionstauglich — der Speicherpfad der Anwenderkonfiguration ist der Produktionskanal für die Persistenz von ct_model / sensor_class / CT je Kanal. Die Kanäle 3 und höher werden über das Kanalfenster gebunden und zurückgelesen; ein vom Modul abgelehntes Modell wird als RB_ERR_PARAM gemeldet. Auf Firmware älter als v1.2 liefert der Aufruf RB_ERR_VERSION.

Hinweis

Die Reihenfolge der Aufrufe ist auf v1.3 beliebig. Ein Schreibzugriff auf REG_CT_MODEL (0x05) legt einen Wert nur vor — er wird nicht automatisch auf Kanal 0 angewendet. Die Anwendung erfolgt ausschließlich über den kanalweisen Opcode CMD_SET_CT_MODEL_CHn (0x28 / 0x29 / 0x2A), der den vorbereiteten Wert in seinen eigenen Kanal kopiert. Die Kanäle können daher in beliebiger Reihenfolge konfiguriert werden — aufsteigend, absteigend oder verschachtelt — ohne Überschreiben:

C++
dev.setCTModel(0, RBAMP_CT_SCT013_005);   // channel 0
dev.setCTModel(1, RBAMP_CT_SCT013_030);   // channel 1
dev.setCTModel(2, RBAMP_CT_SCT013_020);   // channel 2

Nach einer Mehrkanal-Zuordnung bestätigen Sie das Ergebnis mit readCTModelCh(). Für eine gebündelte Konfiguration aller Kanäle mit einem Speichervorgang verwenden Sie bevorzugt configureChannels().

Die RB_ERR_PARAM-Prüfung der Voraussetzung setSensorClass() gilt wie bei der Einzelparameterform. Ein Kanal bei oder über channels() (und damit jeder Kanal über RBAMP_MAX_CHANNELS) → RB_ERR_PARAM. Lesen-vor-Schreiben und die Ablehnung RB_ERR_MODE gelten wie oben beschrieben. Bei der STD-Linie ist das Modell eine Bezeichnung, die in den Eintrag des Kanals geschrieben, zurückgelesen und mit dem Speichern der Modulkonfiguration gesichert wird; keine Nebenwirkung auf Kanal 0.

Rückgabe: true bei Erfolg oder wenn der Kanal bereits code enthält.

bool setCTModel(uint8_t channel, RbAmpCTModel model) noexcept

Typisierte Aufzählungsüberladung der kanalweisen Form (nur SCT-013-Codes).

bool setCTModelChForce(uint8_t channel, uint8_t code) noexcept

Serviceweg. Wie setCTModel(channel, code), schreibt aber unabhängig von der Klasse des Moduls und vom Modell, das der Kanal gerade hält. Es ersetzt die werkseitige Paarungskalibrierung dieses Kanals durch die generische Vorgabe des Modells — verwenden Sie es nur bei der Neupaarung eines Moduls mit einem neuen Sensor im Service und lassen Sie eine Kalibrierung folgen. Ein Code, der nicht in der Registry steht, wird weiterhin abgelehnt (RB_ERR_PARAM, kein Schreibzugriff).

Rückgabe: true bei Erfolg.

bool readCTModelCh(uint8_t channel, uint8_t& out) noexcept

Liest das CT-Modell, das tatsächlich auf einen Kanal angewendet ist (das Prüf-Spiegelbild der gebundenen Vorgabe). Verwenden Sie es, um zu bestätigen, dass eine Bindung erfolgreich war. out = 0 bedeutet nicht gesetzt.

Rückgabe: true bei Erfolg.

Sensorregister — sensorModel() / sensorModelRatedA()

Reine Abfragen in der erzeugten Registry (RbAmpSensorModels.h). Kein Buszugriff. Ein Registry-Treffer bedeutet nicht, dass das angeschlossene Modul den Code akzeptiert — das entscheidet das Modul beim Schreiben.

C++
static const rbamp_sensor_model_info_t* RbAmp::sensorModel(uint8_t cls, uint8_t code) noexcept;
static const rbamp_sensor_model_info_t* RbAmp::sensorModel(RbAmpSensorClass cls, uint8_t code) noexcept;
static float RbAmp::sensorModelRatedA(uint8_t cls, uint8_t code) noexcept;
static float RbAmp::sensorModelRatedA(RbAmpSensorClass cls, uint8_t code) noexcept;

sensorModel() liefert den Registereintrag oder nullptr, wenn (class, code) nicht im Register steht. Der Eintrag (rbamp_sensor_model_info_t) enthält sensor_class, code, name, descriptor, status (charakterisiert / reserviert / veraltet) und die aktuellen Grenzwerte nominal_a (Nenn-Effektivstrom), fs_a (Effektivstrom bei Beginn der Übersteuerung für eine Sinuskurve) und peak_a (momentane Übersteuerungsgrenze). 0 bei einem Grenzwert = für dieses Modell nicht bekannt.

sensorModelRatedA() liefert den Nennstrom (Effektivwert) in Ampere (0 = nicht bekannt). Er gilt für die Familie SCT-013 und für die Zangenmodelle, die eine Nennangabe tragen; ältere Ringkern- bzw. Bürdencodes liefern 0.

C++
float rated = RbAmp::sensorModelRatedA(RbAmpSensorClass::Sct013, RBAMP_CT_SCT013_030);
const rbamp_sensor_model_info_t* m = RbAmp::sensorModel(RbAmpSensorClass::Sct013, RBAMP_CT_SCT013_030);
if (m) Serial.println(m->descriptor);

Korrektur der SCT-013-Nennwerte

Bei BASIC-Firmware bis 1.4.19 wird ein Modul der Klasse SCT-013 auf den SCT-013-030 kalibriert und übernimmt nach einem Neustart diesen kalibrierten Verstärkungswert, unabhängig davon, welches Modell ein Kanal anzeigt. Die Bibliothek gleicht das aus: begin() liest das Modell und den angewendeten Verstärkungswert jedes Kanals und setzt eine kanalbezogene Skalierung. Die Skalierung wirkt auf readCurrent(), readCurrentPeak(), readPower(), readAll(), readPeriodAvgPower(), readPeriodMaxPower() und readPeriodSnapshot() — und damit auf die daraus abgeleitete Energie. Leistungsfaktor und Spannung bleiben unverändert. Plausibilitätsgrenzen und setEventThresholds() beziehen sich auf die echten Ampere bzw. Watt.

Eine Änderung der SCT-013-Nennstärke (zum Beispiel von 030 auf 050) korrigiert daher Strom, Leistung und Energie automatisch; U und PF ändern sich nicht. Firmware 1.4.20 und neuer korrigiert sich selbst — die Skala bleibt 1, und ein Modellschreibzugriff braucht keinen Neustart. STD-Module und die Klassen der fest verdrahteten / eingebauten CT werden nie skaliert.

bool sctRatingRefresh() noexcept

Liest den Bewertungszustand jedes Kanals aus dem Modul neu. Die Bibliothek tut dies bereits, nachdem readEventFlags() EVENT_RESET_OCCURRED meldet; rufen Sie es selbst auf, nachdem Sie auf anderem Weg einen Neustart des Moduls erkannt haben.

Rückgabe: true, wenn das Modul gelesen werden konnte.

bool sctRating(uint8_t channel, RbAmpSctRating& out) noexcept

Zustand eines Kanals: model, applied_gain, noise_floor, scale und status.

Rückgabe: true, wenn channel gültig ist.

RbAmpSctRatingStatus Bedeutung
NotApplicable STD-Linie, eine andere Klasse als SCT-013, Firmware, die sich selbst korrigiert, oder kein Modell gesetzt — Skalierung 1
Native der Kanal zeigt das Modell, auf dem das Modul kalibriert wurde (030) — nichts zu korrigieren, Skala 1
Corrected ein anderes SCT-013-Modell auf älterer BASIC-Firmware — Messwerte werden skaliert
Uncalibrated das Modul wendet eine generische Voreinstellung ohne eigenen Abgleich an — nur nominale Korrektur
UnexpectedGain die angewandte Verstärkung entspricht nicht dem, was die Korrektur erwartet — nichts wird angenommen, Skala 1
Unknown der Zustand konnte nicht gelesen werden — Skalierung 1
float sctRatingScale(uint8_t channel) const noexcept

Der Faktor, der auf die Strom- / Leistungsmesswerte dieses Kanals angewendet wird (1.0, wenn nichts korrigiert wird, und für einen Kanalindex über RBAMP_MAX_CHANNELS hinaus).

static float sctPresetGain(uint8_t model) noexcept

Der Voreinstellungs-Verstärkungswert der Bibliothek für einen SCT-013-Modellcode; 0, wenn unbekannt. Vor allem für die Diagnose nützlich.

bool configureChannels(RbAmpSensorClass cls, const uint8_t* models, uint8_t n) noexcept

Siehe Mehrkanalkonfiguration.

bool saveGains() noexcept — bei BASIC nur im Werksmodus

Ein bloßer Schreibzugriff CMD_SAVE_GAINS (0x26) — der Werks-Speicherpfad für die Kalibrierkoeffizienten (Verstärkungen / Grundrauschen / Phase).

Sicherheit

⚠ Nur im Werkmodus auf BASIC. IN DER PRODUKTION GESPERRT. Auf einem Produktions-BASIC-Modul wird CMD_SAVE_GAINS von der Firmware abgelehnt — der Aufruf liefert false, REG_ERROR wird auf DEV_ERR_PARAM (0xFE) gesetzt, und der nächste Neustart setzt alle nur im RAM geschriebenen Werte zurück. Für jede anwenderseitige Persistenz (Sensorklasse, CT-Modell je Kanal, Adresse, Flottenkonfiguration, Label) verwenden Sie saveUserConfig() (CMD_SAVE_USER_CONFIG, Opcode 0x32) — das ist der produktionstaugliche Persistenzpfad. Anwendercode in einem Einsatzkontext sollte saveGains() nicht aufrufen.

STD-Linie: saveGains() löst das Speichern der Kalibrierung im Modul aus, wartet, bis das Modul den Befehl als beendet meldet, und prüft sein Ergebnis. Das Modul schreibt seinen Speicher höchstens einmal pro 5 s; ein Speichern innerhalb dieses Fensters wird nach 5 s einmal wiederholt.

Rückgabe: true bei einem erfolgreichen Befehl (BASIC-Produktion: immer false mit RB_ERR_MODE).

bool prepareAddressChange(uint8_t new_addr) noexcept

Schritt 1 von 2 zum Ändern der I²C-Adresse des Moduls. Produktionstauglich bei der aktuellen Firmware (v1.3 zweiphasiger Commit, keine Sperre im Werksmodus für die Adresse).

Ablauf: Prüfen Sie den Bereich der new_addr (0x08..0x77, ≠ aktuell) → schreiben Sie den Kandidaten in REG_I2C_ADDRESS (0x30) im RAM → schreiben Sie das Magic 0xA5 in REG_ADDR_COMMIT_MAGIC (0x31) — scharf geschaltet. Der Aufrufer muss commitAddressChange() innerhalb von 5 Sekunden aufrufen, sonst verfällt die Scharfschaltung.

Rückgabe: true, wenn erfolgreich scharf geschaltet.

bool commitAddressChange() noexcept

Schritt 2 von 2. Muss innerhalb von 5 Sekunden nach prepareAddressChange() aufgerufen werden.

Ablauf: Frische des magisch scharf geschalteten Zustands prüfen → CMD_COMMIT_ADDR (opcode 0x30) → im Flash speichern → CMD_RESET (0x01) → ca. 300 ms bis zur Betriebsbereitschaft nach dem Start → internes Adressfeld aktualisieren. Danach adressieren alle Aufrufe dieser Instanz die neue Adresse.

Sicherheit

⚠ Neue Aufzählung nach dem Commit. Nach einem erfolgreichen Commit setzt sich das Gerät zurück und wird unter der NEUEN Adresse neu aufgezählt. Folgeaufrufe an diese RbAmp-Instanz sprechen die neue Adresse transparent an — aber jeder ANDERE Master am Bus (ein Python-Skript, eine ESP-IDF-Komponente auf einem anderen MCU, ein Debug-Probe) hält das Gerät weiterhin für unter der alten Adresse erreichbar, bis dessen interner Zustand von Hand aktualisiert wird.

⚠ Prüfpfad (v1.3): Nach dem Neustart liest REG_I2C_ADDRESS (0x30) die aktive Adresse. Ein Bus-Scan unter der neuen Adresse bestätigt die Übernahme ebenfalls.

Die Adressänderung ist eine Produktionsoperation (nicht nur im Werk). Die dokumentierte I²C-Adresse wird über die Werksbank neu konfiguriert (außerhalb des Umfangs der Bibliothek).

Ein zusätzlicher Hinweis zu commitAddressChange():

Sicherheit

⚠ Neustart und Neuaufzählung nach dem Commit. Nach einem erfolgreichen Commit setzt sich das Gerät zurück und wird unter der NEUEN Adresse neu aufgezählt. Folgeaufrufe an diese RbAmp-Instanz sprechen die neue Adresse transparent an — aber jeder ANDERE Master am Bus (ein Python-Skript, eine ESP-IDF-Komponente, ein Debug-Probe) hält das Gerät weiterhin für unter der alten Adresse, bis dessen interner Zustand von Hand aktualisiert wird.

Ist das Scharfschaltfenster abgelaufen, gibt commitAddressChange() false mit RB_ERR_TIMEOUT zurück und löscht das Scharfschalt-Flag — ein neues prepareAddressChange() ist dann erforderlich.

Rückgabe: true bei Erfolg.

STD-Linie: das Adressfeld wird geschrieben und gespeichert (der Aufruf wartet auf das Ende des Speicherns; eine abgelehnte Adresse liefert RB_ERR_PARAM, und das Modul behält seine Adresse), danach wird das Modul zurückgesetzt. Die Instanz wechselt erst dann auf die neue Adresse, wenn das Modul dort antwortet (bis zu 3 s). Meldet es sich stattdessen auf der ALTEN Adresse, bleibt die Instanz dort und RB_ERR_NOT_READY wird zurückgegeben.

bool factoryReset() noexcept

Der Befehl CMD_FACTORY_RESET (0xAA) + Wartezeit 1500 ms.

Sicherheit

⚠ Destruktive Operation. Löscht ALLE Flash-Parameter (CT-Modell, Sensorklasse, Kalibrierkoeffizienten, I²C-Adresse). Das Modul kehrt zu den Werkseinstellungen zurück — RbAmpSensorClass wird Unset, REG_CT_MODEL wird 0. Jede zuvor über setSensorClass() / setCTModel() gesetzte Einstellung ist verloren. Der nächste Anwender MUSS sowohl setSensorClass() als auch setCTModel() erneut ausführen, bevor die Messung wieder funktioniert. Das ist kein „weicher Neustart“ — dafür verwenden Sie reset(). factoryReset() ist für die Wiederherstellung aus einem bekannt fehlerhaften Zustand oder die Übergabe des Moduls an einen anderen Anwender bzw. eine andere Installation reserviert.

Rückgabe: true bei erfolgreichem Schreiben des Befehls.

STD-Linie: es gibt kein Gegenstück — der Aufruf liefert false mit RB_ERR_NOT_IMPLEMENTED.

bool reset() noexcept

Der Befehl CMD_RESET (0x01) + 100 ms warten. Ein Softneustart des Geräts ohne Verlust der Flash-Parameter.

Rückgabe: true bei erfolgreichem Schreiben des Befehls.

STD-Linie: wartet zuerst auf einen laufenden Befehl (ein Modul wird nie mitten im Speichern zurückgesetzt), wartet dann ruhig (bis zu 3 s), bis das Modul wieder antwortet, und scharf schaltet den Periodenpfad neu.

Mehrmodul-Bus (statisch)

static bool broadcastLatch(TwoWire& bus) noexcept

Sendet eine I²C-General-Call-Rundsendung einer Momentaufnahme (A5 27 00 tick_lo tick_hi an Adresse 0x00) — alle Module mit aktiviertem GC übernehmen gleichzeitig die Periodenmomentaufnahme. Bei Firmware v1.3 wird GC als optionale Fähigkeit unterstützt: Aktivierung je Modul über REG_FLEET_CONFIG.bit0 (standardmäßig gelöscht); die Fähigkeitenkarte des Moduls zeigt, ob es die General-Call-Momentaufnahme unterstützt. General-Call ist eine Funktion der BASIC-Linie (die General-Call- und Label-Hilfsfunktionen liefern RB_ERR_NOT_IMPLEMENTED auf einer STD-Instanz).

Semantik der Rückgabe:

  • Firmware v1.3, GC auf mindestens einem Modul aktiviert — liefert true; die Flotte nimmt ihren Snapshot synchron (Versatz < 1 ms zwischen den Modulen).

  • v1.3-Firmware, GC auf allen Modulen deaktiviert — Wire.endTransmission() an 0x00 wird auf Busebene mit NACK beantwortet → liefert false. Abhilfe: GC je Modul mit enableGc(true) aktivieren (schreibt FLEET_CONFIG.bit0 + SAVE_USER_CONFIG + Reset) oder RbAmpFleet::enableGcAll() verwenden.

  • Alte Firmware ohne General-Call-Unterstützung — gibt false zurück, ohne den Bus anzufassen. Weichen Sie auf eine sequentielle Folge von latchPeriod() an jedem Gerät aus — siehe 06 · Beispiele, Abschnitt Mehrmodul-Bus.

Diagnose

int8_t lastError() const noexcept

Rückgabe: der Code des letzten Fehlers — RB_OK (0) oder einer der Werte RB_ERR_* (negativ). Die vollständige Tabelle steht im Abschnitt "Fehlercodes" unten + 10 · Fehlerbehebung.

static const char* errorString(int8_t code) noexcept

Rückgabe: eine konstante Zeichenkette mit einer lesbaren Beschreibung des Fehlercodes. Liefert nie NULL.

void setLogStream(Stream* stream) noexcept

Eine optionale Diagnosesenke. Ist sie gesetzt, protokolliert die Bibliothek kurz die Ergebnisse von probe(), veraltete Momentaufnahmen und Modusablehnungen. Übergeben Sie nullptr, um sie abzuschalten. Standardmäßig aus.

Typische Verwendung:

C++
dev.setLogStream(&Serial);

uint32_t retryExhaustionCount() const noexcept

Wie oft seit dem Einschalten (oder dem letzten resetCounters()) die Wiederholungsschleife bei einem Einzelbyte-Lesen ausgeschöpft wurde. Der Dauerwert ist 0. Ein Wert ungleich null deutet auf Verbindungsprobleme hin (siehe 10 · Fehlersuche).

uint32_t sanityRejectCount() const noexcept

Wie viele rohe Fließkommawerte vom Plausibilitätsfilter verworfen wurden (!isfinite(x) || |x| > 10000). Im Dauerbetrieb — 0. Ein Wert ungleich null nach der Wiederholungsminderung bedeutet meist ein seltenes Artefakt des ESP-IDF-I²C-Stacks, das die Wiederholungsschicht überstanden hat.

void resetCounters() noexcept

Setzt beide Zähler auf null. Verwenden Sie es zu Beginn eines Dauertests oder eines Regressionsfensters, um nur die Ereignisse innerhalb des Fensters zu messen.

const char* errorString() const noexcept

Instanzverkürzung für errorString(lastError()). Liefert nie NULL.

bool readCommitSeq(uint8_t& out) noexcept — nur BASIC

Liest das Commit-Folgebyte des Moduls. Das Modul erhöht es einmal pro veröffentlichtem Messfenster (100 ms ab Firmware v1.2, davor 200 ms), mit Überlauf 255→0. Vor und nach einem Mehrregister-Lesen abtasten, um zu erkennen, dass die veröffentlichten Werte sich mitten im Lesen geändert haben. Es ist nur ein Änderungsflag — es gibt keine CRC. Auf einer STD-Instanz scheitert der Aufruf mit RB_ERR_NOT_IMPLEMENTED (verwenden Sie stattdessen readDataSeq()).

Rückgabe: true bei Erfolg.

Identifikation und Provisionierung (v1.3)

Diese Methoden lassen den Master genau erkennen, was am Bus angeschlossen ist (Variante, Fähigkeits-Bitmap, UID, Label), und bereiten ein neues oder frisch geflashtes Modul für den Betrieb vor (Provisionierung + Speichern der Konfiguration im Flash).

RbAmpVariant readVariant() noexcept

Liest das Register HW_VARIANT (0x55) des Moduls und gibt eine RbAmpVariant zurück:

Wert SKU I-Kanäle U-Kanal
UI1 (1) UI1 1 ja
UI2 (2) UI2 2 ja
UI3 (3) UI3 3 ja
I1 (4) I1 1 nein
I2 (5) I2 2 nein
I3 (6) I3 3 nein
UI5 (7) UI5 (Top-SKU) 5 ja
UI7 (8) UI7 (Senior-SKU) 7 ja
Unknown (0) nicht identifiziert (Firmware v1.0/v1.1, ein I²C-Fehler oder kein rbAmp) — —
Sicherheit

Die automatische Erkennung der Variante über readVariant() ist der empfohlene Weg. Der Topologie-Hinweis im Konstruktor bleibt als Rückfall für Firmware vor v1.2 erhalten (dort ist HW_VARIANT nicht verfügbar). Standardhinweis = RbAmpTopology::Single — sicher, er löst keine falschen Lesevorgänge nicht vorhandener Kanäle auf UI1/I1 aus.

bool readCapability(uint16_t& out) noexcept — nur BASIC

Liest die 16-Bit-Funktionskarte des Moduls. Verzweigen Sie anhand der benannten Fähigkeitskonstanten aus RbAmpRegistersV2.h (Namensraum rbamp::v2), niemals anhand von Heuristiken zur Firmwareversion. Die Karte sagt unter anderem, ob das Modul einen Spannungseingang hat — wenn nicht, berechnet es P / PF / Energie nicht, und diese Werte liefern 0 — und ob es die General-Call-Broadcast-Momentaufnahme unterstützt (siehe broadcastLatch()). Bei einer STD-Instanz gibt der Aufruf false mit RB_ERR_NOT_IMPLEMENTED zurück; verwenden Sie dort stdInfo().

uint8_t readProductId() noexcept

Liest PRODUCT_ID (0x54) — die Byte-Kennung der Familie (rbAmp-Sensor = 0x01, rbDimmer = 0x02; 0 bei Fehler). Wird vom Fleet-Scanner verwendet, um zu bestätigen, dass das Gerät unter einer Adresse wirklich ein rbAmp ist und nicht ein anderer I²C-Slave, der zufällig unter derselben Adresse antwortet. Eine STD-Instanz meldet die Sensorfamilie.

bool readUid(uint8_t uid[12]) noexcept

Liest die 96-Bit-Eindeutigkeitskennung des MCU aus UID (0x5C..0x67) in einer einzigen Burst-Operation. Die UID ist für jedes Modul garantiert eindeutig und ändert sich bei erneutem Flashen nicht — praktisch für serielle Logs, Prüfungen auf Klone auf Masterseite und die Identifikation, wenn ein Modul in einer ausgerollten Flotte ersetzt wird. Funktioniert auf beiden Linien.

bool readLabel(char out[9]) noexcept — nur BASIC

Liest das 8-Byte-Anwenderlabel aus LABEL (0x68..0x6F). ASCII, mit Nullen aufgefüllt; das Ergebnis endet immer mit einem Nullzeichen (ein Array mit 9 Bytes = 8 Datenbytes + das abschließende \0). Ein leeres Label = nicht gesetzt.

bool writeLabel(const char* label) noexcept — nur BASIC

Schreibt das 8-Byte-Label. Akzeptiert eine nullterminierte Zeichenkette — überzählige Bytes werden abgeschnitten, fehlende mit Nullen aufgefüllt. Das Schreiben erfolgt Byte für Byte bei Mehrbyte-Schreibvorgängen (das rbAmp-Drahtprotokoll erhöht Lesevorgänge im Burst-Modus automatisch, Schreibvorgänge jedoch nicht — siehe Details zum Drahtprotokoll unten; die Bibliothek übernimmt die Byte-Schleife automatisch). Nach dem Schreiben brauchen Sie dev.saveUserConfig(), damit das Label einen Reset übersteht.

Hinweis

Ein frisch aus dem Werk kommendes Modul kann beim ersten Start den Fehler 0xFB (DEV_ERR_FLASH_PARAMS_BAD) melden: Der Block der Benutzerkonfiguration ist noch leer. Das ist normal (nicht fatal); saveUserConfig() löscht ihn. Brechen Sie die Bereitstellung beim ersten Auftreten von 0xFB nicht ab.

bool saveUserConfig() noexcept

Gibt CMD_SAVE_USER_CONFIG (opcode 0x32) aus — speichert den Benutzerkonfigurationsblock im Flash: SENSOR_CLASS, CT_MODEL je Kanal, I2C_ADDRESS, FLEET_CONFIG, GROUP_ID, LABEL. Es speichert keine Werkskalibrierparameter — dafür gibt es einen eigenen Befehl CMD_SAVE_GAINS, der im Produktionsmodus gesperrt ist.

Blockiert den Thread für ca. 700 ms (Löschen und Schreiben des Flash). Während des Aufrufs nicht aus anderen Tasks auf das Modul zugreifen.

STD-Linie: löst das Speichern der Modulkonfiguration aus (Klasse, CT-Referenz, Stufe, I²C-Adresse; die Kalibrierung bleibt erhalten), wartet, bis das Modul den Befehl als beendet meldet (ohne feste Wartezeit), und prüft sein Ergebnis — ein ungültiges Feld (z. B. eine Adresse außerhalb des Bereichs) liefert RB_ERR_PARAM. Ein Speichern innerhalb der Speicherratenbegrenzung des Moduls von 5 s wird nach 5 s einmal wiederholt.

Rücklesen ≠ Persistenz

: Dass ein Wert in den Flash geschrieben wurde, bestätigen Sie nur durch einen Neustart + erneutes Lesen. Siehe den Abschnitt "v1.3-Fehlermodell" unten.

v1.3-Fehlermodell — zwei unabhängige Kanäle

Fehler haben zwei unabhängige Kanäle, die auf unterschiedliche Weise arbeiten. Der Unterschied ist entscheidend, um den Zustand des Moduls richtig zu deuten.

Kanal A — clientseitig, synchron Kanal B — DUT-seitig, dauerhaft asynchron
Wo es sitzt Validierung innerhalb der Bibliothek (Arduino-Bibliothek) REG_ERROR (0x02) + EVENT_FLAGS.bit3 (0x2A)
Wann er auslöst Vor der I²C-Transaktion (die Bibliothek stoppt sie) Nachdem die Firmware den Schreibzugriff angenommen und dann abgelehnt hat
Was der Master sieht der Setter gibt false + lastError() == RB_ERR_PARAM zurück; REG_ERROR im Gerät bleibt 0x00 REG_ERROR = der Fehlercode sofort; bit3 rastet einige hundert Millisekunden nach der Transaktion ein
Dauerhaft nein (nur ein bool-Rückgabewert) REG_ERROR letzter Schreibvorgang; bit3 klebrig W1C
Typischer Weg ein Argument außerhalb der zulässigen Grenzen (Kanal ∉ {0,1,2}, Code ∉ der charakterisierten Menge, sensor_class außerhalb der Aufzählung) Ein rohes Registerschreiben, das die Bibliothek nicht vorab prüft (Low-Level-Verwendung von writeReg() mit einer ungültigen Maske)

Kanal A — clientseitige Validierung (Setter der Bibliothek)

Alle Setter der Bibliothek (setSensorClass, setCTModel, setCTModel(ch, code), configureChannels usw.) prüfen zuerst die Argumente gegen die zulässigen Werte. Liegt ein Argument außerhalb des Bereichs, gibt der Setter false zurück und setzt lastError() == RB_ERR_PARAM, ohne überhaupt eine I²C-Transaktion auszuführen. Entsprechend wird REG_ERROR im Gerät nicht berührt:

C++
if (!dev.setCTModel(/*ch=*/99, /*code=*/3)) {       // client-side guard
    Serial.print(F("rejected: "));
    Serial.println(dev.lastError());                 // RB_ERR_PARAM (lib cached)
    uint8_t reg_err = dev.readLastError();           // device REG_ERROR byte
    Serial.println(reg_err, HEX);                    // 0x00 — REG_ERROR untouched
}
Hinweis

lastError() vs. readLastError() — zwei verschiedene Kanäle, keine Synonyme. lastError() liefert den bibliotheksseitig zwischengespeicherten RB_ERR_*-Code des vorherigen Aufrufs — ohne jede I²C-Operation. readLastError() führt ein einzelnes Lesen über den Bus des Geräteregisters REG_ERROR (0x02) aus — das Ergebnis des letzten Schreibvorgangs aus Sicht der Firmware. Bei Kanal A (oben) ist lastError() = RB_ERR_PARAM, während readLastError() = 0x00 ist (die Bibliothek hat den Bus nie erreicht — REG_ERROR blieb unberührt). Bei Kanal B (unten) zeigen beide einen Code, aber unterschiedlich: lastError() — die zuletzt zwischengespeicherte Bibliothekssemantik; readLastError() — der genaue Wert des REG_ERROR-Bytes genau jetzt.

Wenn Sie also genau wissen wollen, warum ein Setter abgelehnt hat, ist die verlässliche Quelle der Rückgabecode der Funktion + lastError(). REG_ERROR im Gerät sagt Ihnen in diesem Szenario nichts.

Kanal B — Ablehnung auf Seiten des DUT (dauerhaft, asynchron)

Wenn der Schreibvorgang über I²C erfolgreich war (die Bibliothek hat ihn nicht gestoppt, weil das Argument gültig aussah), die Firmware ihn aber abgelehnt hat, greift der zweite Kanal:

  • readLastError() liefert sofort den Grundcode (zum Beispiel 0xFE = DEV_ERR_PARAM). Dies ist das Ergebnis des letzten Schreibzugriffs: Jeder nächste erfolgreiche Schreibzugriff überschreibt es. Sie müssen es sofort nach Ihrem Schreibzugriff lesen, vor jeder anderen Transaktion.

  • hasError(out) — die dauerhafte W1C-Anzeige EVENT_FLAGS.bit3. Sie rastet nicht sofort ein: Am Prüfstand wurde zwischen der fehlgeschlagenen Transaktion und dem Setzen von bit3 eine Verzögerung von einigen hundert Millisekunden gemessen. Direkt nach dem Schreibzugriff ist bit3 noch false; nach 300 ms ist es true. Danach bleibt bit3 über beliebig viele Lesezugriffe hinweg bestehen.

Sicherheit

⚠ Verwenden Sie hasError() nicht, um einen soeben ausgeführten Schreibvorgang zu prüfen. Für das Ergebnis genau dieses Schreibvorgangs ist nur readLastError() verlässlich; lesen Sie es sofort nach dem Schreiben, vor jeder anderen Transaktion (plus der Rückgabe des Setters, falls vorhanden). hasError() ist ein asynchroner Kanal für eine Überwachung nach Art des Pollings („ist zwischen zwei Prüfungen etwas ausgefallen“), keine synchrone Validierung.

Einen dauerhaften Fehler löschen — beides löschen (REG_ERROR und bit3)

bit3 wird von der Firmware alle paar hundert Millisekunden aus dem aktuellen Zustand von REG_ERROR übernommen. Ein einfaches clearEventFlags(1 << 3) funktioniert daher nicht — bit3 wird sofort wieder gesetzt aus dem noch nicht gelöschten REG_ERROR. Die richtige Reihenfolge: zuerst clearError() (löscht REG_ERROR), dann clearEventFlags(1 << 3) (löscht den klebrigen Speicher). Wollen Sie Atomarität — dazwischen darf kein abgelehnter Schreibvorgang liegen.

uint8_t readLastError() noexcept

Liest das Register REG_ERROR (0x02) des Geräts direkt aus (ein einzelner Leselesezugriff; liefert 0x00 für OK, 0xFA..0xFF für eine Fehlerklasse und 0xFF, wenn der I²C-Lesezugriff selbst fehlschlug) — das Ergebnis der letzten vom Bus erfolgreich angenommenen Transaktion (ein Schreibzugriff oder ein Befehl). Nicht dauerhaft: Jeder nächste erfolgreiche Schreibzugriff überschreibt es mit seinem eigenen Ergebnis. Wird in Kanal B (Ablehnung auf Seiten des DUT) für den erweiterten Grundcode verwendet. Bei der STD-Linie ist das Befehlsurteil bereits auf lastError() abgebildet (siehe die STD-Linien-API).

Hinweis

Nicht zu verwechseln mit lastError(): Das ist eine andere Methode, die den von der Bibliothek zwischengespeicherten RB_ERR_* des vorherigen Bibliotheksaufrufs liefert, ohne I²C-Operation. Siehe den Hinweis zu Kanal A oben.

bool hasError(bool& out) noexcept

Eine Komfortfunktion über EVENT_FLAGS.bit3. Gibt true in out zurück, wenn bit3 gesetzt ist. Dauerhaft W1C; wird erst durch ein ausdrückliches Löschen zurückgesetzt (mit einem Vorbehalt — siehe den Abschnitt "Dauerhaften Fehler löschen" oben).

bool readEventFlags(uint8_t& out) noexcept / bool clearEventFlags(uint8_t mask) noexcept

EVENT_FLAGS (0x2A) — ein Byte mit dauerhaften Flags; die einzelnen Bits sind in der Spezifikation beschrieben (einschließlich ERROR_OCCURRED, Bit 3). Das Löschen ist write-1-to-clear: Schreiben Sie eine Maske mit Einsen in die Bits, die Sie zurücksetzen wollen.

bool clearError() noexcept

CMD_CLEAR_ERROR (opcode 0x31) setzt REG_ERROR auf null. Erforderlich, um einen dauerhaften Fehler zu löschen, zusammen mit clearEventFlags(1 << 3) (siehe oben). Ohne clearError() bleibt bit3 nach einigen hundert Millisekunden durch erneutes Einrasten true — ein einfaches clearEventFlags(1 << 3) reicht daher nicht.

Mehrkanalkonfiguration (v1.3)

Bei Mehrkanalmodulen hat jeder Stromkanal sein eigenes CT-Sensormodell. Das atomare Hilfsmittel für die Massenkonfiguration ist configureChannels().

bool configureChannels(RbAmpSensorClass cls, const uint8_t* models, uint8_t n) noexcept

Parameters:

  • cls — die Sensorklasse, zuerst angewendet. Mit RbAmpSensorClass::Sct013 werden die Modelle zugeordnet; eine Anfrage, Modelle unter WiredCT / BuiltinCT zuzuordnen, wird von vornherein abgelehnt (false, RB_ERR_MODE, nichts geschrieben).

  • models — ein Array mit n CT-Modellcodes (generierte RBAMP_CT_*-Defines), je Kanal einer. 0 lässt das bestehende Modell des Kanals unverändert.

  • n — die Länge des Arrays. Begrenzt auf channels(): überzählige Array-Elemente werden ignoriert. Ist n kleiner — die fehlenden Kanäle bleiben unverändert (sie behalten ihr bisheriges Modell).

Intern führt die Funktion aus:

  1. setSensorClass(cls) einmal aufrufen.
  2. Für jeden Kanal k < min(n, channels): REG_CT_MODEL = models[k] vorbereiten + CMD_SET_CT_MODEL_CHk.
  3. Ein Speichervorgang der Klemmen am Ende — ein Flash-Lösch- und Schreibzyklus für die gesamte Konfiguration statt einem je Kanal (etwa 3× weniger Verschleißzyklen bei drei Kanälen).

Lesen-vor-Schreiben gilt: Eine Klasse oder ein Modell, das das Modul bereits hat, wird nicht neu geschrieben; das erneute Anwenden derselben Konfiguration kostet daher nur Lesezugriffe und keinen Flash-Zyklus. Bei BASIC-Firmware bis 1.4.19 mit der SCT-013-Klasse wird das Modul nach dem Speichern neu gestartet (siehe Sensorkonfiguration).

Return:

  • true — die Konfiguration wurde angewendet und gespeichert (oder war bereits vorhanden).
  • false + lastError() == RB_ERR_PARAM — ein ungültiges cls oder ein models[k], das nicht im Register steht (clientseitige Validierung, siehe „Fehlermodell“ oben); der Stapel wird abgebrochen.

  • false + RB_ERR_MODE — das Modul gehört einer werkseitig gepaarten Klasse an.

  • false + andere Codes — Busfehler, Timeout usw.
Hinweis

Zulässige Codes für SCT_013: {1, 2, 3, 4, 5, 6, 7} (SCT-013-005, -010, -030, -050, -100, -020, -060). Details — 03 · Auswahl des Stromsensors.

bool readCTModelCh(uint8_t ch, uint8_t& out) noexcept

Liest das angewendete (Verifikationsspiegel-)CT-Sensormodell auf einem bestimmten Kanal. Das ist ein Rücklesen aus dem RAM, keine Bestätigung der Persistenz — zur Bestätigung eines Flash-Speicherns verwenden Sie dev.reset() + ein erneutes Lesen des Spiegels.

Data-Ready-Leitung und Ereignisse

Beide Leitungen. Der Ausgang DRDY des Moduls ist Open-Drain, im Ruhezustand HIGH (Host-Pull-up), und zieht bei jedem neu veröffentlichten vollständigen Snapshot kurz auf LOW — einmal pro Messfenster (100 ms). Mehrere Module können eine Leitung teilen (Wired-OR). Ein Modul mit anstehendem maskiertem Ereignis hält die Leitung dauerhaft LOW (Alarmpegel), bis die Flags gelöscht sind. Auf der STD-Linie existiert der Ereignisblock bei Modulen, deren Image ihn bereitstellt; bei BASIC ab Firmware v1.3. Hardwaredetails — 04 · Verdrahtung.

bool setDrdyPin(int pin) noexcept

Schließen Sie die DRDY-Leitung dieses Moduls an (oder trennen Sie sie mit pin < 0). Konfiguriert den Pin als Eingang mit internem Pull-up und einem Interrupt auf der fallenden Flanke; die ISR zählt und stempelt die Flanke nur ab — kein Buszugriff dort. Bis zu 4 verschiedene Leitungen und 8 Module je Leitung. Ein STD-Modul, dessen Image den Data-Ready-Vertrag nicht unterstützt, lehnt mit RB_ERR_NOT_IMPLEMENTED ab; waitDataReady() fragt dann die Folge ab. Ohne Leitung fragt waitDataReady() ebenfalls ab.

bool waitDataReady(uint32_t timeout_ms, RbAmpDrdyEvent* ev = nullptr) noexcept

Blockiert, bis dieses Modul einen neuen Snapshot (oder einen Alarm) veröffentlicht, höchstens timeout_ms lang (0 = eine nicht blockierende Prüfung).

Mit einer Leitung: wartet auf die Flanke und bestätigt dann anhand ihrer Momentaufnahme-Sequenz, dass es die dieses Moduls war (ein Impuls eines anderen Moduls auf einer gemeinsamen Leitung wird ignoriert). Bleibt die Leitung kurz nach der Flanke LOW, hält ein Modul auf ihr einen Alarm: Die Flags jedes alarmfähigen Moduls auf der Leitung werden gelesen und gelöscht; die Flags dieses Moduls kommen in ev zurück, die der anderen werden an deren Instanzen geparkt und beim nächsten Warten gemeldet. Ohne Leitung wird die Sequenz alle RBAMP_DRDY_POLL_MS abgefragt (Standard 20 ms; vor dem Einbinden der Bibliothek definieren, um dies zu überschreiben).

Rückgabe: true mit gefülltem ev; false mit RB_ERR_TIMEOUT, wenn nichts eintraf; RB_ERR_NOT_IMPLEMENTED bei einem STD-Modul, dessen Image keinen Veröffentlichungszähler hat.

bool readAllReady(uint32_t timeout_ms, RbAmpSnapshot& out, RbAmpDrdyEvent* ev = nullptr) noexcept

waitDataReady() gefolgt von readAll(), sodass das gesamte Lesen in ein einziges Veröffentlichungsfenster fällt: der Snapshot wird nie zweimal gelesen und überschreitet nie eine Veröffentlichung.

bool readDataSeq(uint16_t& out) noexcept

Die Snapshot-Folge des Moduls — der Veröffentlichungszähler bei STD, die Commit-Folge bei BASIC. Dient nur der Änderungserkennung.

uint8_t beginEventFlags() const noexcept

Die Ereignisflags, wie begin() sie vorfand, bevor die Bibliothek etwas schrieb. EVENT_RESET_OCCURRED bedeutet hier, dass das Modul neu gestartet ist, bevor diese Instanz es traf. Kein Buszugriff.

bool readEventMask(uint8_t& out) noexcept / bool setEventMask(uint8_t mask) noexcept

Lesen / setzen, welche Ereignisbits DRDY auf LOW halten (Bits rbamp::v2::EVENT_*). setEventMask() prüft durch Rücklesen. Die Maske liegt im RAM des Moduls: nach einem Modul-Reset erneut anwenden (EVENT_RESET_OCCURRED zeigt es an).

bool setEventThresholds(float i_amps, float p_watts) noexcept

Setzen Sie die Strom- / Leistungsschwellen hinter EVENT_THRESH_I / EVENT_THRESH_P; ein Wert <= 0 schaltet die Schwelle ab. RAM des Moduls.

  • BASIC vergleicht den maximalen Kanalstrom und die vorzeichenbehaftete Summe der Kanalleistungen — Einspeisung löst sie nie aus.

  • STD vergleicht den Strom jedes Kanals und den Betrag der Gesamtleistung — richtungsunabhängig.

Schwellenereignisse werden auf dem Modul pegelgehalten (in jedem Fenster neu gesetzt, solange die Bedingung gilt): Heben Sie die Schwelle an, bevor Sie eine ruhige Leitung erwarten.

readEventFlags() / clearEventFlags() / hasError() werden unter Fehlermodell beschrieben.

RbAmpDrdyEvent

C++
struct RbAmpDrdyEvent {
    bool     fresh;        // a new snapshot of THIS module is available
    bool     by_edge;      // woken by the DRDY edge (false = found by polling)
    uint16_t seq;          // snapshot sequence now
    uint16_t missed;       // snapshots published since the previous call that were not read
    bool     alarm;        // the line was held LOW (masked event pending on this module)
    uint8_t  event_flags;  // event flags consumed from this module on an alarm, else 0
    uint32_t latency_us;   // edge to return, µs (0 when polling)
};
C++
RbAmp dev(Wire, 0x50);
...
dev.setDrdyPin(15);                       // optional: omit to poll
dev.setEventThresholds(0, 3000);          // power threshold, W
dev.setEventMask(rbamp::v2::EVENT_THRESH_P);

RbAmpSnapshot snap;
RbAmpDrdyEvent ev;
if (dev.readAllReady(500, snap, &ev)) {
    if (ev.alarm) { /* ev.event_flags holds the cleared flags */ }
    // use snap
}

Funktionsübersicht

Die Funktionsübersichten unten wurden aus der README hierher verschoben.

  • Konfiguration des Stromsensors — setSensorClass(class) wählt die Familie (SCT-013, von Ihnen angeschlossen; fest verdrahtete / eingebaute CT-Module werden mit ihrem Sensor kalibriert ausgeliefert und nicht neu konfiguriert), danach setCTModel(code) — oder configureChannels(class, models[], n) für ein Mehrkanalmodul in einem Aufruf. Die Setter lesen, bevor sie schreiben: Eine Klasse oder ein Modell, das das Modul bereits hat, kostet keinen Schreibzugriff auf den Bus und keinen Flash-Zyklus, daher ist das erneute Anwenden einer gespeicherten Konfiguration bei jedem Start unbedenklich. Der akzeptierte Code-Satz für SCT-013 ist {1=005A, 2=010A, 3=030A, 4=050A, 5=100A, 6=020A, 7=060A}. Die Kalibrierkoeffizienten werden automatisch aus der Werksvoreinstellungstabelle geladen. BASIC-Module bis Firmware 1.4.19 sind auf den SCT-013-030 kalibriert: Wählen Sie ein anderes SCT-013-Modell, startet die Bibliothek das Modul nach dem Speichern neu und skaliert von da an Strom- und Leistungsmesswerte relativ zur Verstärkung, die das Modul anwendet (siehe sctRating()); Leistungsfaktor und Spannung bleiben unberührt, und ein Modul, das das Bit der Selbstkorrekturfähigkeit meldet (Firmware 1.4.20+), braucht keine Korrektur.
  • RbAmpFleet-Manager — für mehrere Module auf einem Bus: scan() erkennt und übernimmt sie (mit Kollisionserkennung), pollAll() liest sie in einem Durchlauf, totalPower() / totalEnergyWh() aggregieren, und der General-Call-Pfad (enableGcAll() → gcLatch(tick) → checkSync()) nimmt die Periodenmomentaufnahme aller Module gleichzeitig mit einer Erkennung verpasster Rahmen je Modul. provision() / assignAddress() bringen werkseitig neue Module unter eindeutigen Adressen auf den Bus.
  • Beide Produktlinien, eine API — begin() erkennt, ob ein Modul das BASIC-Registermodell (8 Bit) oder das STD-Registermodell (16 Bit, Festkomma) spricht, und leitet jeden Aufruf intern weiter; line() sagt Ihnen, welche. Auf einem STD-Modul funktionieren dieselben Aufrufe readVoltage(phase) / readCurrent(ch) / readPower(ch) / readPeriodSnapshot(); die Kanalzahlen kommen vom Modul (dreiphasige Module sind einfach N > 1), und die STD-Zusatzfunktionen stehen als readReactivePower(ch) / readApparentPower(ch), stdReadChannel(ch) (ein Burst: I / P / Q / S / PF / Spitze / vorzeichenbehaftete Energie / Oberschwingungen), stdReadVoltage(v), stdReadHealth() sowie acht vom Master getaktete Snapshot-Bänke (stdArmBanks() → stdLatch(bank) → stdReadLatch(bank) → stdLatchWh()) zur Verfügung. Module, die persistente Lebensdauer-Zähler statt Snapshot-Bänken führen, werden über dieselben Aufrufe readPeriodSnapshot() / energy() bedient (eine Periode ist die Differenz zweier Zählerstände; stdReadEnergy() liefert die Rohzähler), dazu die Modulzeit (stdSetTime()), der Verlauf und das Ereignisprotokoll (stdHistRead(), stdEventRead()), die Identität (stdIdentify(), RbAmp::stdProbe()), die Inbetriebnahme per UID (RbAmp::stdSetAddressByUid()) und das Firmware-Update über I2C (stdOtaWritePreparedImage(), Images, die auf dem Build-Host des Herstellers vorbereitet werden). Jeder Befehl wartet, bis das Modul die Fertigmeldung sendet, bevor das Ergebnis gelesen wird; Mehrbyte-Blöcke werden in einer Transaktion gelesen, damit Zähler nie zerreißen. Module, die Mikroauflösungs-Zähler veröffentlichen, füllen die Felder *_uwh / *_uvarh von RbAmpStdEnergy (fine == true; sonst aus den groben Zählern abgeleitet, sodass die Felder immer nutzbar sind), akzeptieren einen Anlaufstrom, unterhalb dessen ein Kanal keine Energie zählt (stdSetEnergyStartCurrent()), und melden Spannungs-Phasenwinkel (angle_deg in stdReadVoltage()) sowie die Phasenfolge (stdReadPhaseSequence()). Speichert Ihre Skizze RbAmpStdEnergy persistent (NVS, EEPROM, Datei), legen Sie die einzelnen benötigten Felder in Ihrem eigenen festen Format ab, nicht die Struktur als Rohblock — die Struktur erhält über Bibliotheksversionen hinweg neue Felder, und ein alter Block passt dann nicht mehr zur neuen Größe.
  • Data-ready-Leitung und Ereignisse — setDrdyPin(pin) überwacht den DRDY-Ausgang des Moduls; waitDataReady() / readAllReady() kehren sofort zurück, nachdem das Modul eine neue Momentaufnahme veröffentlicht hat (mehrere Module können sich eine Leitung teilen), und ein Modul, das die Leitung hält, meldet ein maskiertes Ereignis (setEventMask(), setEventThresholds()), das das Warten für Sie liest und löscht. Ohne Leitung fragen dieselben Aufrufe ab.

API der STD-Linie

Die Modullinie STANDARD (STD) wird von begin() erkannt (dev.line() == RbAmpLine::Std). Die skalare API oben (readVoltage(), readCurrent(), readPower(), readReactivePower(), readApparentPower(), readAll(), readPeriodSnapshot(), energy(), die Konfigurations-Setter, reset(), die Adressänderung) funktioniert auf beiden Linien. Die std*-Aufrufe unten ergänzen Blocklesezugriffe und die Funktionen, die nur die STD-Linie hat.

  • Jeder std*-Aufruf schlägt bei einer BASIC-Instanz mit RB_ERR_NOT_IMPLEMENTED fehl.
  • Die Verfügbarkeit der Funktionen richtet sich nach dem Image des Moduls: prüfen Sie stdReadImageVersion() und die Flags valid / fine der zurückgegebenen Strukturen. Eine Funktion, die das Modul nicht hat, wird als „nicht verfügbar“ gemeldet — nie als erfundener Wert.

  • begin() erledigt die Linienerkennung und die Kanalermittlung. Die entsprechenden internen Helfer sind nicht Teil der öffentlichen API; rufen Sie begin(), readAll() und readPeriodSnapshot() auf.

  • Jeder Befehl wartet, bis das Modul den Abschluss meldet, und prüft danach sein Urteil. Ein abgelehnter Wert gibt RB_ERR_PARAM zurück und lässt das Modul unverändert.

  • Die 8-Bit-Primitive lehnen auf einer STD-Instanz ab, sodass ein reiner BASIC-Pfad nie eine falsche Registertransaktion auf einem STD-Modul ausführen kann.

C++
if (dev.begin() && dev.line() == RbAmpLine::Std) {
    RbAmpStdChannel c;
    if (dev.stdReadChannel(0, c)) {
        Serial.printf("P=%.1f W  Q=%.1f var  S=%.1f VA  PF=%.2f\n", c.p, c.q, c.s, c.pf);
    }
}

Energiequelle und minimale Bibliotheksversion

readPeriodSnapshot() und energy() beziehen ihre Periode aus einer von zwei Quellen, die begin() einmalig anhand der Fähigkeitsbits des Moduls wählt und in stdInfo().period_source meldet:

Modul meldet period_source Periode / Energie stammt aus
gespeicherte Energiezähler (Bit 13), mit oder ohne Bänke Counters die Zähler des Moduls (eine Periode ist die Differenz zweier Ablesungen)
nur Momentaufnahmebänke (Bit 8) Latch Bank 0
keine von beiden None die Aufrufe lehnen mit RB_ERR_NOT_IMPLEMENTED ab

Das serielle STD-Image 0x7E meldet beide Bits. Es benötigt Bibliothek 1.6.2 oder neuer, um seine Energie aus den Zählern des Moduls zu beziehen. Bibliothek 1.6.1 und älter lesen auf diesem Image die Periode aus Bank 0, also Energie, die auf dem Host integriert wird statt aus den eigenen Zählern des Moduls; aktualisieren Sie die Bibliothek, um die zählerbasierten Werte zu erhalten. Die Bänke bleiben auf 0x7E über die Aufrufe in Periodensnapshot-Bänke verfügbar.

Identität

bool stdInfo(RbAmpStdInfo& out) noexcept

Zwischengespeicherte Identität aus begin() — kein Buszugriff. Schlägt mit RB_ERR_NOT_IMPLEMENTED auf einer BASIC-Instanz oder vor begin() fehl.

C++
struct RbAmpStdInfo {
    uint8_t  map_version;   // register-map version
    uint16_t capabilities;  // feature bitmap of the module
    uint8_t  status;        // status bits at begin() time (live: stdReadHealth())
    uint8_t  n_voltage;     // populated voltage channels
    uint8_t  n_current;     // populated current channels (the library exposes up to RBAMP_MAX_CHANNELS)
    uint8_t  variant;       // raw variant byte (also mapped into readVariant())
    uint32_t active_bank;   // running firmware bank (firmware update), 0 if none
    uint32_t ota_bank_size; // firmware bank size the module reports, 0 if none
    RbAmpStdPeriodSource period_source; // which period / energy mechanism this module offers
};

RbAmpStdPeriodSource: Latch (das Modul hat Snapshot-Bänke; Bank 0 bedient readPeriodSnapshot()), Counters (keine Snapshot-Bänke, aber persistente Lebensdauer-Energiezähler — eine Periode ist die Differenz zweier Zählerstände; die Bank-Aufrufe werden ohne Buszugriff abgelehnt) oder None (die Perioden-/Energieaufrufe schlagen mit RB_ERR_NOT_IMPLEMENTED fehl).

bool stdIdentify(RbAmpStdIdentity& out) noexcept

Identität dieses Moduls: die zwischengespeicherten Daten von begin() plus UID, laufende Image-Version und Board-ID (die beiden letzten, sofern das Modul sie meldet; sonst 0).

C++
struct RbAmpStdIdentity {
    uint8_t  i2c_addr;      // 7-bit address the module answered on
    uint8_t  map_version;
    uint16_t capabilities;
    uint8_t  variant;
    uint8_t  n_voltage, n_current;
    uint8_t  uid[12];       // chip UID — the module's identity in a database
    uint32_t fw_version;    // running image version (0 if unknown)
    uint32_t board_id;      // board id (0 if unknown)
};

static int8_t stdProbe(TwoWire& bus, uint8_t addr, RbAmpStdIdentity& out) noexcept

Ermittelt, was unter addr antwortet, ohne Instanz (Bus-Scan). Ein Versuch je Lesezugriff, keine Wiederholungsschicht — ein NACK ist die Antwort.

Rückgabe: RB_OK; RB_ERR_NACK, dort bestätigt nichts; RB_ERR_VERSION, etwas, das kein STD-Modul ist; RB_ERR_PARAM, Adresse außerhalb von 0x08..0x77; RB_ERR_IO, ein späterer Lesezugriff ist fehlgeschlagen.

bool stdReadImageVersion(uint32_t& out) noexcept

Die laufende Image-Version (nicht die Registerkartenversion); 0, wenn das Modul keine meldet. Damit sehen Sie, ob eine Funktion vorhanden ist, die ein aktuelles Image braucht (Mikroenergie, Anlaufstrom, Spannungswinkel und Phasenfolge benötigen ein Image von mindestens 0x0001007B).

bool stdReadBoardId(uint32_t& out) noexcept

Board-ID des laufenden Images.

Blocklesezugriffe

bool stdReadChannel(uint8_t ch, RbAmpStdChannel& out) noexcept

Ein Stromkanal (0 .. channels()-1) in einem einzigen Burst: I, P, Q, S, PF, Spitze, rohe vorzeichenbehaftete Energie-Akkumulatoren und Oberschwingungsfelder.

bool stdReadTotals(uint8_t k, RbAmpStdChannel& out) noexcept

Ein Sammelblock: k = 0 Gesamtsumme (alle Stromkanäle), k = 1..3 Summen je Phase A / B / C (bei einem Einphasenmodul entspricht k = 1 Kanal 0, und k = 2, 3 liefern 0). Nur I / P / Q / S / PF / Spitze — bei Modulen mit Lebensdauerzählern liefern die Energiefelder hier 0; die Energie kommt aus stdReadEnergy().

C++
struct RbAmpStdChannel {
    float   i_rms, i_peak;   // A
    float   p;               // W, signed
    float   q;               // var, signed
    float   s;               // VA
    float   pf;              // power factor, −1..+1
    float   thd_i;           // current THD, % — 0 unless harmonics are enabled
    float   pf1;             // displacement power factor — 0 unless harmonics are enabled
    float   q1;              // fundamental reactive power, var — 0 unless harmonics are enabled
    int64_t e_import_mws;    // raw import energy accumulator (>= 0), see stdLatchWh()
    int64_t e_export_mws;    // raw export energy accumulator (<= 0)
    uint8_t implausible;     // RBAMP_FIELD_* bits of fields set to NaN by the sanity filter
};

Zur Überwachung integrieren Sie p selbst oder verwenden stdReadEnergy(); die Rohakkumulatoren existieren für den Snapshot-Bank-Pfad.

bool stdReadVoltage(uint8_t v, RbAmpStdVoltage& out) noexcept

Ein Spannungskanal (0 .. n_voltage-1).

C++
struct RbAmpStdVoltage {
    float   u_rms, u_peak;   // V
    float   thd_u;           // voltage THD, % — 0 unless harmonics are enabled
    float   angle_deg;       // phase angle vs voltage 0, degrees; 0 when angle_valid is false
    bool    angle_valid;     // false on older images, when the input is too low to measure, and on single-voltage modules for v > 0
    uint8_t implausible;
};

bool stdReadPhaseSequence(RbAmpStdPhaseSeq& out) noexcept

Phasenfolge eines Moduls mit drei Spannungen, vom Modul aus den Spannungswinkeln abgeleitet. Gibt true mit NotAvailable zurück — und ohne Buszugriff — bei einem Image, das sie nicht veröffentlicht; das Modul selbst meldet NotAvailable bei weniger als drei Spannungseingängen oder wenn ein Eingang zu niedrig zum Messen ist.

RbAmpStdPhaseSeq: NotAvailable, Forward (L1-L2-L3), Reverse (L1-L3-L2), Abnormal (kein Dreiphasen-Muster, z. B. zwei Eingänge auf einer Phase).

bool stdReadHealth(RbAmpStdHealth& out) noexcept

Live-Zustand des Moduls. Behandeln Sie die Messwerte als gültig, wenn status das Sensor-OK-Bit trägt und frame_count zwischen zwei Abfragen wächst.

C++
struct RbAmpStdHealth {
    uint8_t  status;       // status bits: cal_ok / sensor_ok / mains_ok / time_valid / nvm_fault / maint
    uint32_t frame_count;  // sensor frame counter — must grow between polls (liveness)
    uint32_t crc_errors;   // sensor frame error counter
    bool     time_valid;   // the module clock was set since its last restart — see stdSetTime()
    bool     nvm_fault;    // energy store unusable
    bool     maint;        // maintenance mode
    uint8_t  lta_status;   // life-time energy store: 0 ok · 1 new · 2 fault · 3 corrupt (service)
    uint8_t  lta_src;      // where the life-time counters were restored from
    uint8_t  cal_src;      // 0 built-in defaults · 1 flash · 2 EEPROM · 3 stored calibration is for another firmware
    uint8_t  group_status; // per-channel energy store: 0 ok · 1 new · 2 fault · 3 restarted at 0
    uint16_t legal_noen, ring_drop;  // module diagnostics (ring_drop should stay 0)
    uint32_t lost_frames;  // should stay flat
    uint32_t uptime_s;     // seconds since the module's last restart
    uint8_t  reset_cause;  // cause of this boot (image-dependent; 0 below)
    uint16_t boot_count;   // persisted boot counter, low 16 bits — a master that missed a restart sees it step
};

Felder, die als „image-abhängig“ gekennzeichnet sind oder für neuere Registerkarten dokumentiert sind, liefern 0 / false bei Modulen, die sie nicht bereitstellen. cal_ok kann bei einem auf einem älteren Image kalibrierten Gerät 0 liefern, bis saveGains() einmal gelaufen ist; die Messwerte selbst sind davon nicht betroffen.

Momentaufnahmebänke der Periode

Ein STD-Modul, das Momentaufnahmebänke meldet (Fähigkeitsbit 8), hält acht unabhängige, vom Master getaktete Perioden. Typische Verwendung: Die benötigten Bänke einmal scharf schalten; dann je Bank nach Ihrem eigenen Zeitplan: stdLatch(bank) → mindestens 300 ms warten → stdReadLatch(bank, snap) → stdLatchWh(snap, dt, ...) mit dem vom Master gemessenen dt seit der vorherigen Momentaufnahme dieser Bank. Die Bänke sind ein eigenes Werkzeug: Sie sind unabhängig von der Energiequelle des Moduls verfügbar (siehe Energiequelle und minimale Bibliotheksversion). Bei einem Modul ohne Bänke lehnen stdArmBanks(), stdLatch() und stdReadLatch() mit RB_ERR_NOT_IMPLEMENTED ab und schreiben nichts. Bank 0 bedient readPeriodSnapshot() und energy() nur bei einem Modul, das Bänke und keine gespeicherten Zähler hat.

bool stdArmBanks(uint8_t mask) noexcept

Setzt die Akkumulationsmaske: Bit b = Bank b akkumuliert (neu scharf geschaltete Bänke starten sauber; unscharfe Bänke frieren ein und behalten ihre letzte Momentaufnahme). Lassen Sie Bit 0 gesetzt, wenn Sie readPeriodSnapshot() verwenden. Die Maske liegt im RAM des Moduls und geht bei einem Modul-Reset verloren; die Bibliothek scharf schaltet eine Bank erneut, wenn ein Lesezugriff eine leere Momentaufnahme auf einer unscharfen Bank findet (siehe stdReadLatch()).

bool stdLatch(uint8_t bank) noexcept

Fordern Sie einen Snapshot an und setzen Sie bank an der nächsten Fenstergrenze des Moduls zurück. Wartet nicht; lesen Sie frühestens 300 ms später.

bool stdReadLatch(uint8_t bank, RbAmpStdLatch& out) noexcept

Liest die letzte Momentaufnahme von bank in einem Burst (Summen + Energie je Kanal aller belegten Kanäle).

Rückgabe: false mit RB_ERR_STALE, wenn das Modul für diese Bank nie eine Momentaufnahme genommen hat (out.valid == false), oder wenn die Momentaufnahme leer ist (win_count == 0), weil die Bank nach einem Modul-Reset ihre Scharfschaltung verloren hat. Im letzteren Fall scharf schaltet die Bibliothek neu und nimmt eine Vorlauf-Momentaufnahme der Bank: Verwerfen Sie diese Periode und starten Sie Ihren eigenen dt-Anker neu (das Intervall des Ausfalls enthält keine Daten).

C++
struct RbAmpStdLatch {
    float    p_avg, q_avg, s_avg;    // average W / var / VA over the period
    float    max_p, max_i;           // peak power (W) and peak RMS current (A)
    float    max_u, min_u;           // peak / minimum RMS voltage (V)
    int64_t  e_import_mws, e_export_mws;   // raw energy accumulators over the period
    uint32_t nsamp;                  // conversion divisor used by stdLatchWh()
    uint32_t win_count;              // measurement windows in the period (0 = not armed / nothing elapsed)
    uint8_t  channels, bank;
    bool     valid;                  // the bank has EVER been snapshotted (not a freshness signal)
    float    p_avg_ch[RBAMP_MAX_CHANNELS];
    int64_t  e_import_ch_mws[RBAMP_MAX_CHANNELS], e_export_ch_mws[RBAMP_MAX_CHANNELS];
};

static bool stdLatchWh(const RbAmpStdLatch& snap, uint32_t dt_ms, uint8_t ch, double& wh_import, double& wh_export) noexcept

Wandelt die rohen Energieakkumulatoren eines Snapshots über die vom Master gemessene Periode dt_ms in Wh um (Wanduhrzeit zwischen dem vorherigen und diesem Snapshot der Bank). ch ist ein Kanalindex bzw. RBAMP_STD_TOTAL für die Bank-Summen. wh_import ist >= 0, wh_export ist <= 0.

Rückgabe: false, wenn ch außerhalb des Bereichs liegt oder nichts aufsummiert wurde.

Lebensdauer-Energiezähler

Module, die gespeicherte Energiezähler führen, behalten diese bei Stromausfall; sie sind monoton mit getrennter Bezugs- / Einspeisesumme mit Vorzeichen.

bool stdReadEnergy(RbAmpStdEnergy& out) noexcept

Lesen Sie die Lebensdauer-Zähler des Moduls. Jeder Block wird in einer Transaktion gelesen, sodass ein 64-Bit-Zähler über eine Veröffentlichung hinweg nicht zerrissen werden kann.

Rückgabe: false mit RB_ERR_NOT_IMPLEMENTED, wenn das Modul keine Energie auf dem Gerät speichert; RB_ERR_NOT_READY, wenn der Block nicht programmiert ist.

C++
struct RbAmpStdEnergy {
    int64_t  act_import_wh, act_export_wh, act_net_wh;     // active energy, Wh (export is a magnitude)
    int64_t  rea_import_varh, rea_export_varh;             // reactive energy, varh
    uint32_t generation;       // steps when the counters were reset or adopted — never take a delta across a change
    uint32_t uptime_s;         // module uptime at the reading (a drop = the module restarted)
    int64_t  act_import_mwh, act_export_mwh, act_net_mwh;  // mWh (0 on modules without them)
    uint8_t  channels;         // valid entries in the per-channel arrays (0 on modules without them)
    uint8_t  group_status;     // per-channel store: 0 ok · 1 new · 2 fault · 3 restarted at 0
    int64_t  ch_import_mwh[RBAMP_MAX_CHANNELS], ch_export_mwh[RBAMP_MAX_CHANNELS];
    bool     fine;             // true: the µWh / µvarh fields are the module's own micro-resolution counters
    int64_t  act_import_uwh, act_export_uwh, act_net_uwh;  // µWh
    int64_t  rea_import_uvarh, rea_export_uvarh;           // µvarh
    int64_t  ch_import_uwh[RBAMP_MAX_CHANNELS], ch_export_uwh[RBAMP_MAX_CHANNELS];
};

Die Felder *_uwh / *_uvarh sind immer befüllt, sodass Sie sie bei jedem Modul verwenden können: ist fine == true, sind sie die eigenen Mikroauflösungszähler des Moduls (Image 0x0001007B oder neuer); andernfalls werden sie aus den gröberen Zählern abgeleitet und treten in deren Einheiten auf. Speichert Ihr Sketch RbAmpStdEnergy, legen Sie die einzelnen benötigten Felder in Ihrem eigenen festen Format ab statt der Struktur als Rohblock — die Struktur erhält über Bibliotheksversionen hinweg neue Felder.

static bool stdEnergyDelta(const RbAmpStdEnergy& prev, const RbAmpStdEnergy& now, RbAmpStdEnergy* delta, bool* module_restarted) noexcept

Energie zwischen zwei Messwerten: jetzt − vorher, wobei jeder Zähler auf 0 begrenzt wird (ein Zähler kann nach einem Modulneustart knapp unter dem letzten Messwert wieder einsetzen); der Saldo wird aus Import minus Export der begrenzten Differenzen neu berechnet. delta und module_restarted dürfen nullptr sein; delta->fine ist nur dann true, wenn beide Messwerte fein waren; *module_restarted ist true, wenn die Laufzeit von now unter der von prev liegt.

Rückgabe: false, wenn sich generation zwischen den Messwerten geändert hat (Zurücksetzen oder Übernahme des Lebensdauerzählers) — dieses Intervall nicht verbuchen.

bool stdSetEnergyStartCurrent(uint16_t ua) noexcept

Setzt den Anlaufstrom für die Energiezählung in µA: Unterhalb dieses Kanalstroms zählt das Modul für den Kanal keine Energie (Bezug oder Einspeisung, gesamt und je Kanal). Ohne Last ist die gemessene Leistung Rauschen beliebigen Vorzeichens und würde sonst in beide Zähler einlaufen. Messwerte (I / P / Q) sind nicht betroffen. Wirkt sofort, Rücklesung wird geprüft; dauerhaft speichern mit saveUserConfig(). 0 schaltet ihn ab; andernfalls muss der Wert ein Vielfaches von 10 µA im Bereich sein, den das Modul akzeptiert — alles andere gibt RB_ERR_PARAM ohne Schreibzugriff auf den Bus zurück.

Rückgabe: false mit RB_ERR_NOT_IMPLEMENTED, wenn das Modul keinen Anlaufstrom hat (keine Energie mit Mikroauflösung oder ein älteres Image).

bool stdReadEnergyStartCurrent(uint16_t& ua) noexcept

Der aktuelle Anlaufstrom für die Energiezählung in µA (0 = aus).

Konfiguration

bool stdReadConfig(RbAmpStdConfig& out) noexcept

Der Konfigurationsblock in einem Burst.

C++
struct RbAmpStdConfig {
    uint8_t  sensor_class; // RbAmpSensorClass value, 0 = unset. Persisted.
    uint8_t  ct_model;     // CT model reference for channel 0 (label only, sets no gain). Persisted.
    uint8_t  tier;         // module tier code. Persisted.
    uint8_t  i2c_addr;     // persisted 7-bit address (applies on reset)
    uint16_t rate_ms;      // report-rate hint, ms (RAM only)
    bool     harmonics;    // base-harmonics extraction enabled (RAM only)
};

bool stdSetHarmonics(bool enable) noexcept

Grundschwingungs-Extraktion (THD, Verschiebungs-Leistungsfaktor, Grundblindleistung) aktivieren / deaktivieren. Nur im RAM (nicht persistiert), mit Rücklese-Prüfung. Setzt die THD-Fähigkeit des Moduls voraus — sonst RB_ERR_NOT_IMPLEMENTED.

bool stdCalThdFloor() noexcept

Erfassen Sie den Roh-THD ohne Last als Sensorgrundrauschen und speichern Sie ihn (ca. 700 ms). Mit sauberem Netz und ohne Last ausführen; danach werden THD-Messwerte um das Sensorgrundrauschen korrigiert. Erfordert die THD-Fähigkeit.

Uhr

Die Modulzeit geht bei jedem Modulneustart verloren. Setzen Sie sie nach begin() und immer dann, wenn RbAmpStdHealth::time_valid false ist; ohne sie zeichnet das Modul keinen Verlauf auf.

bool stdSetTime(uint32_t unix_epoch) noexcept

Setzt die Uhr des Moduls (Unix-Epoche, UTC). Rückgabe false mit RB_ERR_PARAM, wenn das Modul die Epoche ablehnt (vor 2020), RB_ERR_NOT_READY, wenn es den Wert akzeptiert, aber die Uhr innerhalb von 300 ms nicht als gültig meldet.

bool stdReadTime(uint32_t& unix_epoch, bool& valid) noexcept

Der Modultakt und ob er seit dem letzten Neustart des Moduls gesetzt wurde.

Befehle und Inbetriebnahme

bool stdCommand(uint8_t opcode, uint32_t settle_ms, uint32_t timeout_ms = 0) noexcept

Führen Sie einen Modulbefehl aus und warten Sie auf sein Ergebnis: wartet, bis das Modul im Leerlauf ist (ein während Beschäftigung geschriebener Befehl geht verloren), schreibt den Opcode, fragt den Befehlszustand ab, bis das Modul die Fertigmeldung sendet, und liest dann das Ergebnis. settle_ms begrenzt nur die erste Abfrage. timeout_ms = 0 bedeutet 1000 ms; nie weniger als 1000.

Rückgabe: false mit dem auf einen Fehlercode abgebildeten Urteil — PARAM, NOT_IMPLEMENTED (unbekannter Befehl), CHECKSUM (Wertprüfung), MODE (Schlüssel / Freigabe), NOT_READY (Ratenbegrenzung / Wiederholung), TIMEOUT, IO (Speicherfehler des Moduls).

bool stdWaitIdle(uint32_t timeout_ms = 0) noexcept

Warten, bis das Modul meldet, dass kein Befehl läuft (0 = 1000 ms).

bool stdLocate() noexcept

Lassen Sie die LEDs des Moduls etwa 10 s blinken — um es im Schaltschrank zu finden.

static int8_t stdSetAddressByUid(TwoWire& bus, uint8_t shared_addr, const uint8_t uid[12], uint8_t new_addr, uint32_t restart_ms = 0) noexcept

Gibt einem von mehreren Modulen mit gemeinsamer Adresse eine eigene Adresse, ausgewählt über die UID (Inbetriebnahme). Auf der gemeinsamen Adresse ist es nur schreibbar (mehrere Module könnten antworten, daher wird dort nichts gelesen). Das adressierte Modul speichert die neue Adresse und startet neu; der Aufruf prüft dann die neue Adresse und die UID. Führen Sie begin() auf einer Instanz erneut aus, die an die neue Adresse gebunden ist. restart_ms = 0 bedeutet 1500 ms.

Rückgabe: RB_OK; RB_ERR_PARAM, Adresse außerhalb des Bereichs; RB_ERR_NACK, kein Modul hat an der gemeinsamen Adresse bestätigt; RB_ERR_NOT_READY, danach antwortet unter der neuen Adresse nichts; RB_ERR_VERSION, das Modul dort ist nicht das angesprochene (UID weicht ab).

Verlauf und Ereignisprotokoll

Einträge existieren nur für Perioden, in denen die Modulzeit gültig war (siehe stdSetTime()).

C++
enum class RbAmpStdHistPeriod : uint8_t {
    Min15  = 0,  // 15-minute energy records — RAM only (the last record survives no restart)
    Hour   = 1,  // hourly energy records — persistent ring (the one to backfill from)
    Events = 2,  // event log (read with stdEventRead())
};

bool stdHistInfo(RbAmpStdHistPeriod period, RbAmpStdHistInfo& out) noexcept

Ringübersicht: count, capacity, record_size, oldest_ts, newest_ts (Unixzeit). Einträge werden über einen back-Index vom neuesten zum ältesten abgerufen.

bool stdHistRead(RbAmpStdHistPeriod period, uint16_t back, RbAmpStdHistRecord& out) noexcept

Holt einen Energieperioden-Datensatz (Min15 oder Hour) und dekodiert ihn; back = 0 ist der neueste. Rückgabe false mit RB_ERR_NOT_READY, wenn es keinen solchen Datensatz gibt (leerer Ring oder back darüber hinaus); RB_ERR_PARAM für den Ereignisring (verwenden Sie dafür stdEventRead()).

C++
struct RbAmpStdHistRecord {
    uint32_t ts;           // Unix time at the end of the period
    uint16_t flags;        // partial / power-up / clock / life-time-jump bits
    uint16_t n;            // measurement windows in the period
    bool     from_ram;     // served from RAM (not yet persisted)
    float    v_rms, i_total, p_avg, q_avg, s_avg, pf;
    float    p_min, p_max, i_min, i_max;
    uint64_t e_import_wh, e_export_wh;   // life-time ABSOLUTE counters at the end of the period
    uint8_t  phases;                     // valid entries in the per-phase arrays (0..3)
    double   ph_import_wh[3], ph_export_wh[3];  // THIS period's energy per phase
};

Die Energie einer Periode nur aus zwei aufeinanderfolgenden Stundendatensätzen übernehmen, wenn sich deren Zeitstempel genau um eine Periode unterscheiden und keiner das Flag für einen Sprung des Lebensdauerzählers trägt.

bool stdHistReadRaw(RbAmpStdHistPeriod period, uint16_t back, uint8_t rec[rbamp_std::REG_HIST_REC_SIZE], uint8_t* flags) noexcept

Holt einen nicht dekodierten Datensatz eines beliebigen Rings in rec; flags (optional) erhält die Datensatz-Flags des Moduls.

bool stdEventRead(uint16_t back, RbAmpStdEvent& out) noexcept

Einen Ereignisprotokoll-Eintrag abrufen und dekodieren (back = 0 ist der neueste); RB_ERR_NOT_READY = kein solcher Eintrag.

C++
struct RbAmpStdEvent {
    uint32_t ts;         // Unix time (0 if the clock was not set)
    uint32_t uptime_s;   // module uptime at the event
    uint8_t  type;       // record type
    uint8_t  flags;
    uint16_t boot;       // boot counter at the event
    uint32_t a_before, a_after;          // event-specific values
    uint64_t e_before_wh, e_after_wh;    // life-time energy before / after, Wh
};

bool stdHistFlush() noexcept

Veranlassen Sie das Modul, seine Energiezähler jetzt in seinen Speicher zu schreiben.

Firmware-Update über I²C

Ein zweiphasiges Update: stdOtaBegin() → stdOtaWritePage() für jede Seite → stdOtaCommit() (prüft das Image und scharf schaltet den Tausch; kein Neustart) → stdOtaActivate() (startet in das neue Image neu, wenn Sie bereit sind). In der Praxis verwenden Sie stdOtaWritePreparedImage(), das begin + Seiten + commit in einem Aufruf erledigt, und danach stdOtaActivate(). Module akzeptieren nur vom Hersteller vorbereitete Images; ein fehlerhaftes Image wird vom Modul selbst zurückgerollt, und die Kalibrierung bleibt erhalten. Jeder Schritt wartet, bis das Modul den Abschluss des Befehls meldet (keine festen Wartezeiten). Alle Aufrufe schlagen mit RB_ERR_NOT_IMPLEMENTED fehl, solange das Modul die Update-Fähigkeit nicht meldet.

C++
typedef void (*RbAmpOtaProgress)(uint32_t done, uint32_t total, void* ctx);
Aufruf Beschreibung
bool stdOtaStatus(uint8_t& out) Der Update-Zustand des Moduls (rbamp_std::OTA_IDLE / READY / OK / ERR / DOWNGRADE).
bool stdOtaBegin(uint32_t timeout_ms = 0) Die inaktive Bank löschen und warten, bis das Modul bereit meldet. 0 = Standard (5 s). false mit RB_ERR_TIMEOUT, wenn er nicht erreicht wird.
bool stdOtaWritePage(uint32_t page_idx, const uint8_t* page) Schreibt eine 256-Byte-Seite am Index page_idx. false mit RB_ERR_CHECKSUM, wenn die Nutzlast beschädigt ankam (dieselbe Seite erneut senden), RB_ERR_IO, wenn das Modul die Seite nicht übernommen hat, RB_ERR_NOT_READY, wenn die Sitzung nicht mehr offen ist — in den letzten beiden Fällen ab stdOtaBegin() neu starten (siehe stdOtaDiag()).
bool stdOtaCommit(uint32_t timeout_ms = 0) Prüft das geschriebene Image und scharf schaltet den Banktausch. 0 = Standard (3 s). RB_ERR_CHECKSUM, fehlerhaftes Image; RB_ERR_VERSION, Image älter als die laufende Version (abgelehnt); RB_ERR_TIMEOUT.
bool stdOtaActivate() Booten Sie in das scharf geschaltete Image, warten Sie, bis das Modul zurückkehrt, erkennen Sie es erneut, bestätigen Sie, dass die laufende Bank gewechselt hat, und warten Sie, bis sich das neue Image selbst bestätigt. Blockiert für die gesamte Sequenz (ca. 12 s). Die Instanz bleibt gebunden, und stdInfo() spiegelt die neue Firmware wider. false mit RB_ERR_NOT_READY, wenn nichts scharf geschaltet war, das Modul auf der vorherigen Bank zurückkam oder das neue Image nie bestätigt hat; RB_ERR_VERSION, wenn das danach laufende Image nicht das vorbereitete ist (zurückgerollt).
static uint32_t stdCrc32(const uint8_t* data, size_t len) CRC-32 (zlib-kompatibel) — die Prüfsumme je Seite, die das Modul verifiziert.
bool stdOtaWritePreparedImage(const uint8_t* image, size_t len, RbAmpOtaProgress cb = nullptr, void* ctx = nullptr) Überträgt ein vorbereitetes Bank-Image (begin + Seiten + commit; ohne activate). len muss der Bankgröße des Moduls entsprechen, sonst RB_ERR_PARAM. Seiten werden aufsteigend geschickt, leere Seiten werden übersprungen, eine Seite, die das Modul als beschädigt meldet, wird einmal erneut gesendet.
bool stdOtaWritePreparedImage(Stream& image, size_t len, RbAmpOtaProgress cb = nullptr, void* ctx = nullptr) Stream-Form — eine Seite im RAM gehalten.
bool stdOtaWritePreparedImage(const uint8_t* bank_a, const uint8_t* bank_b, size_t len, RbAmpOtaProgress cb = nullptr, void* ctx = nullptr) Geben Sie beide Images je Bank an; die Bibliothek wählt das Image für die Bank, die nicht läuft. RB_ERR_NOT_IMPLEMENTED, wenn das Modul seine laufende Bank nicht meldet.
bool stdOtaActiveBank(uint8_t& out) Kennung der laufenden Bank: 0 = A, 1 = B.
bool stdOtaStagedVersion(uint32_t& out) Version des scharf geschalteten (committeten, noch nicht aktivierten) Images; 0, wenn nichts scharf geschaltet ist.
bool stdOtaDiag(uint8_t& reason, uint8_t& hal_status) Der Grund des Moduls für den letzten fehlgeschlagenen Update-Versuch sowie ein Statusbyte auf niedriger Ebene. Lesen Sie es nach einem fehlgeschlagenen Commit oder Seitenschreibvorgang.
bool stdOtaAbort() Schließen Sie die Update-Sitzung bzw. heben Sie ein scharf geschaltetes Image auf, ohne neu zu starten.
bool stdOtaBoardOk(uint32_t image_board_word) Lehnt ein Image für ein anderes Board vor dem Senden ab: vergleicht die Board-ID des Moduls mit dem Board-Wort des Images (aus dem Image-Manifest). Eine Abweichung gibt RB_ERR_PARAM zurück; RB_ERR_NOT_IMPLEMENTED bei Modulen, die keine Board-ID melden.
bool stdOtaWriteImage(const uint8_t* image, size_t len, uint32_t version, RbAmpOtaProgress cb = nullptr, void* ctx = nullptr) und die Form mit Stream& Nur aus Gründen der Quellkompatibilität beibehalten: gibt false mit RB_ERR_NOT_IMPLEMENTED zurück, ohne das Modul anzufassen. Verwenden Sie stattdessen stdOtaWritePreparedImage().

RbAmpFleet — Verwaltung mehrerer Module

Die Klasse RbAmpFleet ist die wichtigste High-Level-Schnittstelle der Bibliothek v1.3. Sie verwaltet eine Sammlung von Modulen an einem gemeinsamen I²C-Bus: Erkennung, Provisionierung, Aggregation der Abfragen, Aggregation der Fehler und synchrone Snapshots per General-Call-Broadcast.

Eine Flotte ist an einen TwoWire-Bus gebunden (meist Wire); jedes übernommene Modul ist ein eigenes RbAmp-Handle. Die weiche Obergrenze für die Anzahl der Module ist RBAMP_FLEET_MAX_MODULES = 16.

Lebenszyklus

C++
RbAmpFleet(TwoWire& bus);
~RbAmpFleet();              // releases all adopted handles

Nach ~RbAmpFleet() sind alle über get(idx) erhaltenen Handle-Zeiger ungültig.

Erkennung — scan()

C++
bool scan(bool match_product, size_t& added);

Fragt den Bus im Bereich 0x08..0x77 ab, und für jede antwortende Adresse:

  1. Prüft die Identität (PRODUCT_ID, HW_VARIANT, CAPABILITY). Ist match_product = true, wird eine Übereinstimmung mit der rbAmp-PRODUCT_ID verlangt.

  2. Führt einen Konflikterkenner auf zwei unabhängigen Signalen aus (Identitätskonsistenz + Live-Wert). Verdächtige Adressen kommen auf die Liste excluded, nicht in die Flotte.

  3. Führt einen Tier-2-Canary für Bus-Blockaden aus: er fragt eine Adresse ab, an der nachweislich niemand sein kann. Erhält der Canary ein ACK, liefert er false — der Bus ist blockiert, und die Flotte bleibt leer (siehe die Diagnose in Kap. 10).

Nach Erfolg enthält added die Anzahl der zur Flotte hinzugefügten Module. excludedCount() (siehe unten) ist über einen separaten Getter verfügbar.

Modulzugriff

C++
size_t count() const noexcept;
RbAmp* get(size_t index) noexcept;
RbAmp* find(uint8_t address) noexcept;
bool add(RbAmp* dev) noexcept;

size_t excludedCount() const noexcept;
int excludedAddr(size_t i) const noexcept;

get liefert nullptr bei einem Wert außerhalb des Bereichs; find liefert nullptr, wenn die Adresse nicht in der Flotte ist (z. B. weil sie ausgeschlossen wurde). add erlaubt es, ein separat erzeugtes Handle manuell hinzuzufügen (z. B. nach manueller Provisionierung).

Abfrage — pollAll()

C++
bool pollAll(RbAmpSnapshot* snaps,
             RbAmpFleetPoll* status,
             size_t capacity,
             size_t& n_ok);

Fragt alle Module der Flotte in einem einzigen Aufruf ab. Für jedes Modul wird eine vollständige RT-Messung (readAll()) durchgeführt und das Ergebnis dem entsprechenden Element snaps[i] zugeordnet. Parallel erhält status[i] das Ergebnis je Modul (ok=true/false + addr + channels).

Nach der Rückkehr ist n_ok die Anzahl der Module, für die ein gültiger Snapshot erhalten wurde.

MISS-resistent: ein stummes Modul bricht die Abfrage der übrigen nicht ab. Das ist für eine Produktionsflotte wichtig — der Ausfall eines Moduls (eine defekte Leitung, ein Durchbrennen) darf nicht die gesamte Überwachung lahmlegen.

Aggregation

C++
bool totalPower(float& out_w) noexcept;
bool totalEnergyWh(double& out_wh) noexcept;
bool pollErrors(uint32_t& error_mask, size_t& n_errors) noexcept;

totalPower summiert die Wirkleistung über alle Kanäle aller Module. Bei I-Varianten gibt es keine Wirkleistung → sie tragen 0 bei. In der kanonischen Installation (UI1 Netz + I2/I3-Unterzähler) ist das Ergebnis die Wirkleistung des Netzmoduls.

totalEnergyWh summiert ebenso die Wh-Akkumulatoren der Handles. Auch das funktioniert korrekt: I-Varianten liefern 0, UI1 liefert Energie je Last.

pollErrors durchläuft die Flotte und ruft auf jedem Modul hasError() auf; error_mask ist eine Bitmaske der Module mit dem Flag EVENT bit3 nach ihrer Position (aussagekräftig für die ersten 32 Module); n_errors ist die Gesamtzahl der Module mit gesetztem Fehlerflag zum Zeitpunkt der Abfrage.

Adressierung und Konfliktprüfung

C++
bool assignAddress(RbAmp* dev, uint8_t new_addr);
bool checkConflict(uint8_t addr, bool& collision) noexcept;

assignAddress adressiert ein vorhandenes Modul der Flotte auf eine neue Adresse um: intern — ein zweiphasiger Commit + Reset; das Handle in der Flotte wird automatisch aktualisiert (nachfolgende Aufrufe funktionieren weiter).

checkConflict — eine nach bestem Bemühen nur lesende Prüfung für eine bestimmte Adresse: Sie liest die Identität (PRODUCT_ID / HW_VARIANT / CAPABILITY) und vergleicht sie mit dem zwischengespeicherten Zustand der Flotte. Wird eine Inkonsistenz erkannt — collision = true. Um alle bekannten Adressen zu durchlaufen, iterieren Sie über die Flotte: for (size_t i = 0; i < fleet.count(); ++i) + checkConflict(fleet.get(i)->address(), col). Sie garantiert nicht, identische Module zu erkennen — siehe Disziplin bei der Bereitstellung.

Bereitstellung — provision() (statisch)

C++
static bool provision(TwoWire& bus,
                      uint8_t desired_addr,
                      bool save_config,
                      RbAmp*& out_dev);

Nimmt ein TwoWire& (meist Wire) und out_dev als Ausgabeparameter. Bei Erfolg gehört out_dev dem Aufrufer — üblicherweise übergeben Sie es direkt an fleet.add(out_dev):

Versorgt genau ein neues, unberührtes Modul (ab Werk 0x50) mit der angegebenen Adresse. Intern:

  1. Prüft, ob eine Antwort unter 0x50 vorliegt.
  2. Prüft, dass niemand bislang unter desired_addr antwortet.
  3. Führt den zweiphasigen Adress-Commit durch.
  4. Setzt das Modul zurück und wartet, bis es innerhalb des Startfensters unter desired_addr erscheint.

  5. Erzeugt das Handle; ist save_config = true, wird saveUserConfig() aufgerufen (Speicherung im Flash).

  6. Gibt das bereite Handle über out zurück.

Sicherheit

⚠ PFLICHT: genau ein unkonfiguriertes Modul am Bus im Moment des Aufrufs. Zwei Module unter 0x50 gleichzeitig sind über I²C physisch nicht zu unterscheiden — sie lassen sich nicht einmal mit Spezialhardware trennen. Die Garantie beruht auf dem Bediener, nicht auf der Bibliothek. Zur Wiederherstellung siehe 10 · Fehlersuche, Abschnitt „Flotte: Provisionierung fehlgeschlagen“.

Fleet-GC-Synchronisation — synchrone Momentaufnahmen über die gesamte Flotte

C++
bool enableGcAll(uint8_t group, size_t& ok_count);
bool gcLatch(uint8_t group, uint16_t tick, uint16_t settle_ms);
bool checkSync(uint16_t expected_tick,
               RbAmpFleetSync* status,
               size_t status_cap,
               size_t& n_missed);

Für eine enge Snapshot-Synchronisierung über die gesamte Flotte wird ein I²C-General-Call-Broadcast-Snapshot verwendet.

  1. enableGcAll setzt FLEET_CONFIG.bit0 + GROUP_ID auf allen Flottenmodulen und sendet CMD_SAVE_USER_CONFIG an jedes (dauerhaft). Ein Neustart der Module ist nach dem Aktivieren zwingend — er erfolgt automatisch. ok_count ist die Anzahl der Module, bei denen die Aktivierung gelang.

  2. gcLatch sendet den GC-Rahmen A5 27 group tick_lo tick_hi an die Adresse 0x00 — alle Module mit aktiviertem GC und passender group führen sofort den Momentaufnahmebefehl aus (LATCH_PERIOD). settle_ms ist die Pause nach dem Rahmen (typisch 50 ms) vor der Prüfung.

  3. checkSync liest GC_TICK (0x59) auf jedem Modul in RbAmpFleetSync status[status_cap]. Das Ergebnis je Modul:

C++
struct RbAmpFleetSync {
    uint8_t  addr;        // I²C address of the module
    uint16_t gc_tick;     // REG_GC_TICK; 0xFFFF = never received a GC
    bool     in_sync;     // true if gc_tick == expected_tick
    bool     reachable;   // false if the read NACKed / timed out
};

n_missed ist die Anzahl der Module mit in_sync = false (oder schlicht ohne Antwort). Sind alle in_sync, gilt n_missed == 0.

Flottenkonfiguration je Gerät (v1.3)

Diese Methoden arbeiten direkt mit einem einzelnen Modul (ohne Fleet) — für Fälle, in denen Sie ein einzelnes Modul konfigurieren, bevor Sie es einer Fleet hinzufügen, oder eine feinkörnige Steuerung wünschen.

bool enableGc(bool enable) noexcept / bool readFleetConfig(uint8_t& out) noexcept

enableGc(true) schreibt 1 nach FLEET_CONFIG.bit0 (0x27) + speichert im Flash + Reset — das Modul akzeptiert nach dem Start General-Call-Momentaufnahmen. enableGc(false) löscht das Bit spiegelbildlich. Blockiert ca. 1 Sekunde (Einschwingen von SAVE_USER_CONFIG + Einschwingen des Resets). readFleetConfig liefert das aktuelle Konfigurationsbyte — nützlich zur Bestätigung durch Rücklesen.

bool setGroupId(uint8_t group) noexcept / bool readGroupId(uint8_t& out) noexcept

GROUP_ID (0x28) — der Filter für GC-Rahmen: Das Modul reagiert nur auf GC-Rahmen mit passender group_id. Standard = 0x00 (Broadcast, reagiert auf alle). Dient Mehrmandanten-Bussen — zum Beispiel eine Gruppe "Phase A" und eine Gruppe "Phase B" auf einem gemeinsamen Bus.

bool readGcTick(uint16_t& out) noexcept

Liest GC_TICK (0x59) — den letzten Tick-Wert aus einem GC-Rahmen. Dient zur Erkennung verpasster Rahmen (haben zwei Module unterschiedliche Ticks, wurde ein Rahmen verpasst). 0xFFFF = das Modul hat seit dem Booten nie einen GC-Rahmen empfangen.

static bool broadcastLatchGroup(TwoWire& bus, uint8_t group, uint16_t tick) noexcept

Ein Low-Level-Versand des GC-Rahmens A5 27 group tick_lo tick_hi direkt über bus (ohne Flotte). Nützlich, wenn die Flotte noch nicht angelegt ist oder Sie die manuelle Kontrolle über den Tick-Zähler wünschen.

bool readActiveAddress(uint8_t& out) noexcept

Liest REG_I2C_ADDRESS (0x30) — die aktive (laufende) Adresse des Moduls. Auf v1.3 liest es beim Booten die aktive Adresse, nicht einen vorbereiteten Kandidaten. Auf der STD-Linie liefert es das persistierte Adressfeld (wirksam nach dem Reset). Nützlich zur Rücklesebestätigung nach commitAddressChange().

Klasse RbAmpEnergy

Ein Wh-Akkumulator je Kanal. Gehört RbAmp und wird über dev.energy() angesprochen. Der Anwender erstellt ihn normalerweise nicht direkt.

Öffentliche Methoden

C++
double wh(uint8_t ch = 0) const noexcept;

Der aktuelle Wh-Gesamtwert eines Kanals bzw. aller Kanäle mit RBAMP_ENERGY_CH_TOTAL. Vorzeichenbehaftet — ein negativer Wert bedeutet Nettoeinspeisung. Liegt ch außerhalb des Bereichs, liefert er 0.0. (Bei einem STD-Modul ohne Zähler je Kanal verwenden Sie RbAmp::energyWh(), um NaN statt einer irreführenden 0 zu erhalten.)

C++
void addWh(uint8_t ch, double wh) noexcept;

Fügt einem Kanal oder dem Gesamtsumme aller Kanäle eine vorzeichenbehaftete Energie hinzu. Wird von der Bibliothek auf dem STD-Zählerpfad verwendet; steht auch Anwendercode zur Verfügung, der Energie selbst integriert.

C++
void reset(uint8_t ch = 0) noexcept;
void resetAll() noexcept;

Einen Kanal nullen (oder die Summe mit RBAMP_ENERGY_CH_TOTAL) oder alle Kanäle.

C++
void disable() noexcept;
void enable() noexcept;
bool isEnabled() const noexcept;

Automatische Integration ein- und ausschalten. Solange die Integration aus ist, arbeitet readPeriodSnapshot() weiter, lässt den Akkumulator aber nicht fortschreiben — nützlich, wenn der Master seine eigene dauerhafte Wh-Speicherung führt.

C++
uint32_t droppedDtCount() const noexcept;
void resetDroppedDtCount() noexcept;

Diagnose: Wie viele Integrationstakte verworfen wurden, weil die Periode des Masters länger war als die Plausibilitätsgrenze von einer Stunde.

Das interne tick()

C++
void tick(const RbAmpPeriodSnapshot& snap, uint8_t channels) noexcept;

Wird bei Erfolg automatisch aus RbAmp::readPeriodSnapshot() aufgerufen. Anwendercode ruft es nicht direkt auf. Idempotent: Momentaufnahmen mit valid == false werden ignoriert.

Die Integrationsformel:

Text
wh[ch] += snap.avg_p[ch] × snap.master_dt_ms / 1000 / 3600
         [W]              [milliseconds]              → [Wh]

Genauigkeit

Plattformabhängig — Einzelheiten siehe 04 · Hardware:

  • ESP32 / ESP8266 / STM32duino / SAMD / RP2040: ein 64-Bit-double-Akkumulator.

  • Klassisches Arduino AVR (Uno, Mega, Nano): Die Toolchain definiert double als 32-Bit-float. Bei langlaufenden Dauertestinstallationen den Akkumulator regelmäßig zurücksetzen (zum Beispiel einmal täglich).

POD-Strukturen und Enums

Strukturen der STD-Linie (RbAmpStd*) werden zusammen mit den Aufrufen beschrieben, die sie zurückgeben, in der STD-Linien-API.

RbAmpSnapshot

Wird von readAll() zurückgegeben. Alle Felder in SI-Einheiten. Nicht genutzte Kanäle (über channels hinaus) werden mit Nullen gefüllt.

C++
#define RBAMP_MAX_CHANNELS 7                       // override before including to shrink the arrays

struct RbAmpSnapshot {
    float voltage;                                 // V — RMS voltage
    float voltage_peak;                            // V — peak voltage
    float current[RBAMP_MAX_CHANNELS];             // A — RMS current per channel
    float current_peak[RBAMP_MAX_CHANNELS];       // A — peak current per channel
    float power[RBAMP_MAX_CHANNELS];               // W — active power per channel (signed)
    float power_factor[RBAMP_MAX_CHANNELS];        // dimensionless, −1..+1
    float frequency;                               // Hz — grid frequency
    RbAmpTopology topology;                        // Single / SplitPhase / ThreePhase / Five / Seven
    uint8_t channels;                              // 1..RBAMP_MAX_CHANNELS — number of valid channels
    bool has_voltage_hw;                           // true if a voltage sensor is present
    uint8_t implausible;                           // RBAMP_FIELD_* bits of fields set to NaN by the sanity filter
};

implausible-Bits: RBAMP_FIELD_VOLTAGE, RBAMP_FIELD_CURRENT, RBAMP_FIELD_POWER, RBAMP_FIELD_PF, RBAMP_FIELD_FREQUENCY.

RbAmpPeriodSnapshot

Wird von readPeriodSnapshot() zurückgegeben. Das Grundelement der Energiemessung.

C++
struct RbAmpPeriodSnapshot {
    float avg_p[RBAMP_MAX_CHANNELS]; // W — average active power over the period
    float max_p;                     // W — peak instantaneous power on channel 0
    uint32_t latch_ms;               // ms — period duration (device's view, diagnostic; 0 on STD)
    uint32_t master_dt_ms;           // ms — master wall-clock dt since the last snapshot
    bool valid;                      // true if the snapshot ready flag was set
    float avg_p_total;               // W — average active power over the period, all channels
    double wh_net;                   // Wh — net energy of this period (import − export)
    bool module_restarted;           // the module restarted inside this period (STD counter path only)
};
Hinweis

latch_ms ist ein diagnostischer Zeitgeber des Moduls; verwenden Sie ihn nicht für Energie — nutzen Sie die Masteruhr (master_dt_ms).

RbAmpTopology

C++
enum class RbAmpTopology : uint8_t {
    Single      = 1,   // 1 current channel (UI1 / I1)
    SplitPhase  = 2,   // 2 current channels (UI2 / I2)
    ThreePhase  = 3,   // 3 current channels (UI3 / I3)
    Five        = 5,   // 5 current channels (UI5) — senior SKU
    Seven       = 7,   // 7 current channels (UI7) — senior SKU
};

RbAmpLine

C++
enum class RbAmpLine : uint8_t {
    Basic = 0,   // 8-bit register map (the default until begin() runs)
    Std   = 1,   // STANDARD (STD) line: 16-bit register map
};

RbAmpVariant

Unknown, UI1, UI2, UI3, I1, I2, I3, UI5, UI7 — siehe readVariant().

RbAmpSensorClass

C++
enum class RbAmpSensorClass : uint8_t {
    Unset     = 0,  // Factory default; setCTModel() will refuse
    Sct013    = 1,  // SCT-013 series clamp fitted by the user
    WiredCT   = 2,  // Wired CT shipped with the module and calibrated together with it
    BuiltinCT = 3,  // Built-in CT, calibrated together with the module
};

WiredCT und BuiltinCT beschreiben Module, die zusammen mit ihrem Sensor ausgeliefert und kalibriert werden. Die Setter schreiben ein solches Modul nie neu (sie geben false mit RB_ERR_MODE zurück); setCTModelChForce() ist der Serviceweg.

RbAmpCTModel

Ein eingefrorener Aufzählungstyp zur Abwärtskompatibilität für die sieben SCT-013-Codes (Sct013_005 … Sct013_060). Neuer Code übergibt ein erzeugtes RBAMP_CT_*-Define an die uint8_t-Überladungen.

RbAmpSctRating und RbAmpSctRatingStatus

Siehe Korrektur der SCT-013-Nennwerte.

RbAmpDrdyEvent

Siehe Data-ready-Leitung und Ereignisse.

Fehlercodes (Namensraum rbamp)

Definiert in RbAmpRegisters.h, zurückgegeben von lastError().

C++
namespace rbamp {
    constexpr int8_t RB_OK                  =  0;
    constexpr int8_t RB_ERR_IO              = -1;   // I²C transport error
    constexpr int8_t RB_ERR_NACK            = -2;   // retry exhausted, slave not responding
    constexpr int8_t RB_ERR_TIMEOUT         = -3;   // timeout (waitReady / waitDataReady / commit-addr window expired)
    constexpr int8_t RB_ERR_NOT_READY       = -4;   // module not ready / no such record / nothing armed
    constexpr int8_t RB_ERR_STALE           = -5;   // period snapshot not ready
    constexpr int8_t RB_ERR_PARAM           = -6;   // invalid channel / address / precondition; the module rejected a value
    constexpr int8_t RB_ERR_MODE            = -7;   // not allowed in the module's current mode (factory-paired class, factory-only command)
    constexpr int8_t RB_ERR_CHECKSUM        = -8;   // value check failed — checksum / signature / range
    constexpr int8_t RB_ERR_VERSION         = -9;   // unsupported firmware / image version
    constexpr int8_t RB_ERR_NOT_IMPLEMENTED = -10;  // no counterpart on this line or on this module image
    constexpr int8_t RB_ERR_NON_PHYSICAL    = -11;  // float rejected by the sanity filter
}

Diagnoserezepte für jeden Code — 10 · Fehlerbehebung.

Diagnoserezepte für jeden Code — 10 · Fehlerbehebung.

Konfiguration zur Kompilierzeit

Define VOR #include setzen, um die Standardwerte zu überschreiben:

C++
#define RBAMP_NACK_RETRY_ATTEMPTS 5    // number of retry attempts per byte
#define RBAMP_NACK_RETRY_GAP_MS 5      // pause between attempts, ms
#include 

Plattform-Standardwerte:

C++
#if defined(ARDUINO_ARCH_ESP32) || defined(ESP_PLATFORM)
#  define RBAMP_NACK_RETRY_ATTEMPTS 3
#else
#  define RBAMP_NACK_RETRY_ATTEMPTS 1
#endif
#define RBAMP_NACK_RETRY_GAP_MS 5

Mehr zum Resilienz-Subsystem — 10 · Fehlerbehebung.

Einschwingzeitkonstanten

Definiert in RbAmpRegisters.h. Die Bibliothek verwendet sie intern; sie sind für Anwender exportiert, die beim direkten Buszugriff dieselben Zeiten einhalten wollen:

C++
constexpr uint16_t SETTLE_MS_LATCH_PERIOD  =   50;  // after CMD_LATCH_PERIOD
constexpr uint16_t SETTLE_MS_SAVE_GAINS    =  700;  // after CMD_SAVE_GAINS (flash write)
constexpr uint16_t SETTLE_MS_RESET         =  300;  // after CMD_RESET
constexpr uint16_t SETTLE_MS_FACTORY_RESET = 1500;  // after CMD_FACTORY_RESET

Details zum Drahtprotokoll

Sicherheit

Dieser Abschnitt beschreibt das 8-Bit-Registerprotokoll der BASIC-Linie. Die STD-Linie verwendet einen 16-Bit-Registerzeiger mit Burst-Lesezugriffen und automatischem Inkrement; die Bibliothek erledigt das intern (begin() erkennt die Linie), und die physische Verdrahtung ist derselbe I²C-Bus. Anwendungscode braucht die Details der STD-Verdrahtung nie — verwenden Sie die Aufrufe der STD-Linien-API.

Registerlesezugriffe — automatisches Inkrement

Ein Burst-Lesezugriff + N bytes liefert N aufeinanderfolgende Bytes ab addr. Die Bibliotheksmethoden verwenden nach Möglichkeit Bursts (eine I²C-Transaktion = 4 Bytes Float).

Registerschreibvorgänge — Byte für Byte (NICHT automatisch erhöht)

⚠ Schreibvorgänge erhöhen NICHT automatisch. Ein Burst-SCHREIBEN + N Bytes landet nur das erste Byte — die Bytes 1..N gehen verloren.

Ein Mehrbyte-Register wird Byte für Byte geschrieben — eine eigene Einzelbyte-I²C-Transaktion für jede Adresse:

C++
// WRONG — data loss
uint8_t label[8] = "MyMeter1";
Wire.beginTransmission(addr);
Wire.write(0x68);                  // start of LABEL
Wire.write(label, 8);              // burst — only 'M' lands
Wire.endTransmission();

// CORRECT — byte-at-a-time loop
for (int i = 0; i < 8; i++) {
    Wire.beginTransmission(addr);
    Wire.write(0x68 + i);
    Wire.write(label[i]);
    Wire.endTransmission();
}

Betrifft beschreibbare Mehrbyte-Register: LABEL (0x68–0x6F), U_GAIN/I_GAIN (f32, werkseitig gesperrt), NF (u16), THRESH (u16). Lesen — Burst zulässig.

Ausnahme: der GC-Broadcast-Rahmen (5 Bytes A5 27 g tl th an Adresse 0x00) ist ein eigener Drahtprotokoll-Pfad (Empfang per General Call, kein Registerschreiben) und wird als einzelne Transaktion gesendet. Siehe Szenario 12 in 06 · Beispiele.

Lesen nicht zugeordneter Register

Jedes Lesen einer nicht zugeordneten Adresse liefert 0x00. Die Firmware sendet bei Registerlesungen nie ein NACK. Die Erkennung eines fehlenden Geräts erfolgt über den ACK des I²C-Adressrahmens, nicht durch Abfragen von Registern.

Variantenerkennung

Das maßgebliche SKU-Byte ist REG_HW_VARIANT (0x55) (die Methode readVariant()):

Wert SKU
0x01 UI1 (1× I + U)
0x02 UI2 (2× I + U)
0x03 UI3 (3× I + U)
0x04 I1 (1× I, kein U)
0x05 I2 (2× I, kein U)
0x06 I3 (3× I, kein U)
0x07 UI5 (5× I + U, Top-SKU)
0x08 UI7 (7× I + U, Top-Modell)

REG_TOPOLOGY (0x24) ist ergänzend (nur die Kanalanzahl, sie unterscheidet nicht das Vorhandensein von U). Auf der STD-Linie liest die Bibliothek die Identität aus der eigenen 16-Bit-Karte des Moduls während begin() und ordnet die Variante in readVariant() ein.

General-Call-Broadcast-Snapshot (Synchronisierung mehrerer Module)

Optional je Modul über REG_FLEET_CONFIG.bit0 — GC_ENABLE. Standard AUS. Aktiviert über CMD_SAVE_USER_CONFIG + CMD_RESET (weich oder hart). Nach dem Reset hört das Modul auf einen Broadcast-Rahmen an der Adresse 0x00:

Text
addr=0x00 | A5 27   
  • A5 — Magic; 27 — Opcode CMD_LATCH_PERIOD.
  • — 0x00 = alle (All-Call), sonst muss er mit REG_GROUP_ID (0x28) übereinstimmen.
  • — der 16-Bit-Zähler der Master-Synchronisationsperiode.

Der Rahmen erzeugt nur den Snapshot; zerstörerische Opcodes werden über GC nicht gesendet.

Erkennung von Fehlerzuständen (zweistufig):

  1. GC-Adress-NACK (sofort auf Busebene): ist GC auf der gesamten Flotte deaktiviert, liefert Wire.endTransmission() an 0x00 einen Code ungleich null (NACK). Das ist ein harter Fehler, kein stiller Verlust. Die Bibliothek wertet es als „GC nicht aktiviert“ (erfordert die Voraussetzungen Aktivieren + Reset).
  2. Nachweis je Modul (nach dem Einschwingen): gab es kein NACK, lesen Sie REG_V03_PERIOD_VALID (0x07) auf jedem erwarteten Modul. 1 = Snapshot erfolgreich; 0 = GC auf diesem Modul deaktiviert oder die Periode leer; !=1 → auf ein Latch je Gerät zurückfallen.

Referenzen


Quelle & Probleme: rb-amp/rbamp-arduino · diese Seite im Repo: docs/09_api_reference.md (v1.6.2)