09 · API-Referenz
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
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
02 · Initialisierung und Start (initialization) · BASIC oder STD? (initialization) · Dauerabfragezyklus (empfohlen) (period-metering)
Das Gerät abfragen, seine Produktlinie und Variante erkennen, die Momentaufnahme vorbereiten.
Sequence:
-
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. -
Lesen Sie
REG_VERSION(0x03). Hat das Gerät nicht bestätigt —falsemitRB_ERR_NACK. Hat es0x00/0xFFgeliefert —falsemitRB_ERR_VERSION. -
Topologie zwischenspeichern: das Varianten-Byte des Moduls auf Firmware, die es bereitstellt, sonst der Konstruktor-
hint. Danach lieferntopology()/channels()gültige Werte, ohne den Bus zu berühren. Die Kanalanzahl überschreitet nieRBAMP_MAX_CHANNELS(7); darüber liegende Kanäle werden nicht bereitgestellt, und ihre Adressierung liefertRB_ERR_PARAM. -
Lesen Sie
U_rms, um festzustellen, ob ein Spannungssensor vorhanden ist (Schwelle 1.0 V). -
Schreiben Sie
CMD_LATCH_PERIODals 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). -
millis()für die anschließende Energieintegration speichern. - 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
02 · Initialisierung und Start (Initialisierung) · 3. DATA_VALID (0xCE) wird nie 1 (Fehlersuche) · 4 · Registerkarte (Produktion v1.3) (API-Referenz)
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
Mehrkanal-Strom (UI2 / UI3 / UI5 / UI7) (Echtzeit-Abfrage) · 4.10 V03-Echtzeitblock (0x86..0xBD) (API-Referenz) · 4.14 Kanal-Zugriffsfenster (0x32 + 0x3C..0x3F) (API-Referenz)
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.
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)
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
Mehrkanaliger Strom (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.14 Kanalzugriffsfenster (0x32 + 0x3C..0x3F) (api-reference)
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
RT-Registerreferenz (realtime-polling) · Bilanzierung in beide Richtungen (period-metering)
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
RT-Registerreferenz (realtime-polling) · Abfrage — einzelnes Modul (realtime-polling) · 4.10 V03-Echtzeitblock (0x86..0xBD) (api-reference)
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 (überchannels()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
04 · Periodenmessung und Tarifabrechnung (Periodenmessung) · Kalibrierung und Genauigkeit (Fehlersuche) · 7.5 Erhaltung der Periode bei fehlgeschlagenem Snapshot (API-Referenz)
Liest das Bereitschaftsbit des Snapshots. true, wenn der letzte Snapshot aktuell und lesbar ist.
float readPeriodAvgPower(uint8_t ch = 0) noexcept
Register der Periodenmomentaufnahme (period-metering) · 4.11 V03-Periodenblock (0xBE..0xCF) (api-reference) · 4.12 V03 Q + Periode ch0 (0xD0..0xE3, Produktionsbuild) (api-reference)
Mittlere Wirkleistung auf einem Kanal über den abgeschlossenen Zeitraum. Muss nach latchPeriod() + 50 ms Einschwingzeit und Gültigkeitsprüfung aufgerufen werden.
float readPeriodMaxPower() noexcept
Register der Periodenmomentaufnahme (period-metering) · 4.12 V03 Q + Periode ch0 (0xD0..0xE3, Produktionsbuild) (api-reference)
Spitzen-Momentanleistung auf Kanal 0 über die abgeschlossene Periode.
uint32_t readPeriodLatchMs() noexcept
13. Takt-Drift mehrerer Module bei langen Tests (troubleshooting) · 4.13 Diagnose-dt auf Chipseite (0xEC) (api-reference)
Dauer der Periode aus Sicht des Geräts, in ms.
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
Fortlaufender Abfragezyklus (empfohlen) (Periodenmessung) · Mehrmodul — gleichzeitiger Snapshot (Periodenmessung) · Kalibrierung und Genauigkeit (Fehlersuche)
Der empfohlene Einstiegspunkt für die Periodenmessung. Die vollständige Abfolge im Hintergrund:
-
Bei
skip_latch == true— den Schreibzugriff auf den Momentaufnahmebefehl überspringen (gilt nachbroadcastLatch()oder einer manuellen Folge von Momentaufnahmebefehlen). -
Andernfalls —
CMD_LATCH_PERIODschreiben. - Erfassen Sie
millis(), ummaster_dt_mszu berechnen. -
delay(settle_ms)— standardmäßig 50 ms laut Protokollspezifikation. -
Prüfen Sie das Bereitschaftsflag des Snapshots. Bei 0 — setzen Sie
RB_ERR_STALEund halten Sie den Zeitstempel fest (damit der nächste Snapshot nicht umdtdoppelt zählt). -
Lesen Sie
avg_p[0..channels-1]+max_p+latch_ms. - 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
Algorithmus auf der Masterseite (Periodenmessung) · 7 · Semantik (API-Referenz)
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.
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
Sensorklasse und CT-Modell setzen (Initialisierung) · 4.3 System (0x20..0x25) (API-Referenz) · 6.2 CT-Modell-Zuordnung — reine Vorbereitung + CMD je Kanal (API-Referenz)
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. 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
Festlegen von Sensorklasse und CT-Modell (initialization) · 6.2 CT-Modell-Bindung — reine Vorbereitung + CMD je Kanal (api-reference)
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.
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:
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
4.7 CT-Modell-Verifikationsspiegel (0x51..0x53) (API-Referenz) · 8.10 Rücklesen des CT-Modell-Verifikationsspiegels (Plausibilität nach der Zuordnung) (API-Referenz)
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.
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.
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).
⚠ 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
Adressänderung (Initialisierung) · 4.5 Adresse (0x30..0x31) (API-Referenz) · 6.1 Adressänderung — zweiphasiger Commit (produktionstauglich) (API-Referenz)
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
Adressänderung (initialization) · 6.1 Adressänderung — zweiphasiger Commit (produktionstauglich) (api-reference) · 8.5 Adressänderung in 5 Schritten (api-reference)
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.
⚠ 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():
⚠ 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.
⚠ 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()an0x00wird auf Busebene mit NACK beantwortet → liefertfalse. Abhilfe: GC je Modul mitenableGc(true)aktivieren (schreibtFLEET_CONFIG.bit0+SAVE_USER_CONFIG+ Reset) oderRbAmpFleet::enableGcAll()verwenden. -
Alte Firmware ohne General-Call-Unterstützung — gibt
falsezurück, ohne den Bus anzufassen. Weichen Sie auf eine sequentielle Folge vonlatchPeriod()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:
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
Automatische Erkennung der Modulvariante (initialization) · rbAmp-Drahtprotokoll-Referenz (v1.3) (api-reference) · 3.6 Kanonischer Erkennungsalgorithmus (api-reference)
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) | — | — |
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
Automatische Erkennung der Modulvariante (Initialisierung) · 3.2 CAPABILITY (Register 0x57/0x58, u16 LE, nur lesbar) (API-Referenz) · 8 · Beispiele für Drahtprotokoll-Mitschnitte (API-Referenz)
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
3.5 PRODUCT_ID (0x54, u8, nur lesbar) (api-reference) · 4.8 Identität (0x54..0x6F) (api-reference)
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
8.3 Mehrbyte-SCHREIBZUGRIFF — LABEL Byte für Byte (api-reference)
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
8.3 Mehrbyte-SCHREIBZUGRIFF — LABEL Byte für Byte (api-reference)
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.
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
6.5 Provisionierung — frisches Flashen + SAVE (API-Referenz) · 8.6 Provisionierung nach frischem Flashen (API-Referenz)
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.
: 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:
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
}
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 Beispiel0xFE = 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-AnzeigeEVENT_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 nochfalse; nach 300 ms ist estrue. Danach bleibtbit3über beliebig viele Lesezugriffe hinweg bestehen.
⚠ 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
3. DATA_VALID (0xCE) wird nie 1 (troubleshooting) · Fehlercodes (REG_ERROR = 0x02) (troubleshooting) · 4 · Registerkarte (Produktion v1.3) (api-reference)
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).
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
Fehlercodes (REG_ERROR = 0x02) (troubleshooting) · 6.7 Wiederherstellung nach Fehlerzustand — Entscheidungsbaum (api-reference)
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. MitRbAmpSensorClass::Sct013werden die Modelle zugeordnet; eine Anfrage, Modelle unterWiredCT/BuiltinCTzuzuordnen, wird von vornherein abgelehnt (false,RB_ERR_MODE, nichts geschrieben). -
models— ein Array mitnCT-Modellcodes (generierteRBAMP_CT_*-Defines), je Kanal einer.0lässt das bestehende Modell des Kanals unverändert. -
n— die Länge des Arrays. Begrenzt aufchannels(): überzählige Array-Elemente werden ignoriert. Istnkleiner — die fehlenden Kanäle bleiben unverändert (sie behalten ihr bisheriges Modell).
Intern führt die Funktion aus:
setSensorClass(cls)einmal aufrufen.- Für jeden Kanal
k < min(n, channels):REG_CT_MODEL = models[k]vorbereiten +CMD_SET_CT_MODEL_CHk. - 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ültigesclsoder einmodels[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.
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
01 · Hardware-Anschluss (hardware-connection) · 03 · Echtzeit-Abfrage (realtime-polling)
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
01 · Hardware-Anschluss (hardware-connection) · 03 · Echtzeit-Abfrage (realtime-polling)
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
4.4 Fleet-Konfiguration (0x27..0x2F) (api-reference) · 8.8 Ablauf von Schwellwertereignissen — Schwellwert schreiben → auslösen → W1C-Löschen (api-reference)
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
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)
};
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), danachsetCTModel(code)— oderconfigureChannels(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 (siehesctRating()); 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 AufrufereadVoltage(phase)/readCurrent(ch)/readPower(ch)/readPeriodSnapshot(); die Kanalzahlen kommen vom Modul (dreiphasige Module sind einfach N > 1), und die STD-Zusatzfunktionen stehen alsreadReactivePower(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 AufrufereadPeriodSnapshot()/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/*_uvarhvonRbAmpStdEnergy(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_deginstdReadVoltage()) sowie die Phasenfolge (stdReadPhaseSequence()). Speichert Ihre SkizzeRbAmpStdEnergypersistent (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 mitRB_ERR_NOT_IMPLEMENTEDfehl. -
Die Verfügbarkeit der Funktionen richtet sich nach dem Image des Moduls: prüfen Sie
stdReadImageVersion()und die Flagsvalid/fineder 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 Siebegin(),readAll()undreadPeriodSnapshot()auf. -
Jeder Befehl wartet, bis das Modul den Abschluss meldet, und prüft danach sein Urteil. Ein abgelehnter Wert gibt
RB_ERR_PARAMzurü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.
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.
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).
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().
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).
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.
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).
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.
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.
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()).
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()).
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.
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.
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
RbAmpFleet(TwoWire& bus);
~RbAmpFleet(); // releases all adopted handles
Nach ~RbAmpFleet() sind alle über get(idx) erhaltenen Handle-Zeiger ungültig.
Erkennung — scan()
Einrichtung mehrerer Module (initialization) · Abfrage mehrerer Module — drei Strategien (realtime-polling) · Probleme mit mehreren Modulen (troubleshooting)
bool scan(bool match_product, size_t& added);
Fragt den Bus im Bereich 0x08..0x77 ab, und für jede antwortende Adresse:
-
Prüft die Identität (
PRODUCT_ID,HW_VARIANT,CAPABILITY). Istmatch_product = true, wird eine Übereinstimmung mit der rbAmp-PRODUCT_ID verlangt. -
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. -
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
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()
Einrichtung mehrerer Module (initialization) · Abfrage mehrerer Module — drei Strategien (realtime-polling)
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
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
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)
6.5 Provisionierung — frisches Flashen + SAVE (API-Referenz)
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:
- Prüft, ob eine Antwort unter
0x50vorliegt. - Prüft, dass niemand bislang unter
desired_addrantwortet. - Führt den zweiphasigen Adress-Commit durch.
-
Setzt das Modul zurück und wartet, bis es innerhalb des Startfensters unter
desired_addrerscheint. -
Erzeugt das Handle; ist
save_config = true, wirdsaveUserConfig()aufgerufen (Speicherung im Flash). -
Gibt das bereite Handle über
outzurück.
⚠ 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
General Call (Broadcast an Adresse 0x00) (initialization) · Mehrere Module — gleichzeitige Momentaufnahme (period-metering) · 6.3 GC-Broadcast-Momentaufnahme — optionale Flottensynchronisation (api-reference)
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.
-
enableGcAllsetztFLEET_CONFIG.bit0+GROUP_IDauf allen Flottenmodulen und sendetCMD_SAVE_USER_CONFIGan jedes (dauerhaft). Ein Neustart der Module ist nach dem Aktivieren zwingend — er erfolgt automatisch.ok_countist die Anzahl der Module, bei denen die Aktivierung gelang. -
gcLatchsendet den GC-RahmenA5 27 group tick_lo tick_hian die Adresse0x00— alle Module mit aktiviertem GC und passendergroupführen sofort den Momentaufnahmebefehl aus (LATCH_PERIOD).settle_msist die Pause nach dem Rahmen (typisch 50 ms) vor der Prüfung. -
checkSyncliestGC_TICK (0x59)auf jedem Modul inRbAmpFleetSync status[status_cap]. Das Ergebnis je Modul:
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
General Call (Broadcast an Adresse 0x00) (Initialisierung) · 4.4 Flottenkonfiguration (0x27..0x2F) (API-Referenz)
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
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.)
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.
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.
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.
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()
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:
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
doubleals 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.
#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.
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)
};
latch_ms ist ein diagnostischer Zeitgeber des Moduls; verwenden Sie ihn nicht für Energie — nutzen Sie die Masteruhr (master_dt_ms).
RbAmpTopology
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
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
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().
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:
#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:
#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:
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
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 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 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:
// 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:
addr=0x00 | A5 27
A5— Magic;27— OpcodeCMD_LATCH_PERIOD.—0x00= alle (All-Call), sonst muss er mitREG_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):
- GC-Adress-NACK (sofort auf Busebene): ist GC auf der gesamten Flotte deaktiviert, liefert
Wire.endTransmission()an0x00einen 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). - 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
- 05 · Schnellstart — Ihr erster funktionierender Sketch
- 06 · Beispiele — Arbeitsszenarien
-
10 · Fehlersuche — Entschlüsselung von Fehlern und Lösung häufiger Probleme
-
Quelldatei mit Doxygen-Kommentaren:
src/RbAmp.h
Quelle & Probleme: rb-amp/rbamp-arduino · diese Seite im Repo: docs/09_api_reference.md (v1.6.2)