09 · API-Referenz
Die vollständige öffentliche API der Komponente rbamp für ESP-IDF. Die Quelle ist die Header-Datei include/rbamp.h mit Doxygen-Kommentaren; der Multi-Modul-Manager steht in include/rbamp_fleet.h, und der Wh-Akkumulator-Typ in include/rbamp_energy.h.
Dieses Kapitel ist ein Nachschlagewerk: Signaturen, Rückgabewerte, Nebenwirkungen, Randfälle. Funktionierende Beispiele finden Sie unter 06 · Beispiele; für einen schnellen Einstieg siehe 05 · Schnellstart.
Headerdatei
#include "rbamp.h" — der zentrale öffentliche Header. Er zieht transitiv esp_err.h für esp_err_t und driver/i2c_master.h für den Typ i2c_master_bus_handle_t nach. Weitere Includes sind nicht erforderlich.
Die API ist in einen extern "C"-Block eingebettet — kompatibel mit C- und C++-Aufrufern.
Allgemeine Muster
Die API folgt den üblichen ESP-IDF-Mustern:
-
Undurchsichtiges Handle:
rbamp_handle_t— ein typedef fürstruct rbamp_obj_t *; der Benutzer greift nicht auf seine Interna zu. Erzeugt mitrbamp_new(), freigegeben mitrbamp_del(). -
Rückgabewerte von
esp_err_t—ESP_OKbei Erfolg, einer der CodesESP_ERR_*bei Fehler. Verwenden SieESP_ERROR_CHECK()für die Fehlerbehandlung mit Abbruch oder prüfen Sie manuell. -
Ausgabe per Zeiger: Funktionen, die einen Wert zurückgeben, nehmen als letzten Parameter einen Zeiger auf einen Puffer. So kann ein einzelner Aufruf sowohl ein
esp_err_tals auch einen Wert liefern. -
Menschenlesbare Fehlerzeichenfolgen:
rbamp_err_to_str(err)liefert einen Zeiger auf eine statische Zeichenkette. Er liefert nieNULL. -
Ein Handle, zwei Modulstufen: Dasselbe Handle und dieselbe skalare API bedienen die BASIC- und die STD-Modulstufe;
rbamp_begin()erkennt die Stufe und leitet jeden Aufruf weiter. Funktionen, die nur auf einer Stufe existieren, liefern auf der anderenESP_ERR_NOT_SUPPORTED(sieherbamp_line_tund STD-Linie). -
Befehle werden nicht wiederholt. Ein Befehlsschreibvorgang (Snapshot, Reset, Speichern, ...) wird nach einem Transportfehler nie wiederholt — eine Wiederholung könnte den Opcode zweimal ausliefern. Lese- und Schreibvorgänge der Datenregister behalten die NACK-Wiederholung.
-
Fehlerzuordnung in der gesamten API:
ESP_ERR_NOT_SUPPORTED— die Funktion oder Eigenschaft existiert auf dieser Linie / Firmware / diesem Modul nicht;ESP_ERR_NOT_FOUND— das Modul oder der Datensatz ist nicht vorhanden (keine Bestätigung, kein solcher Historieneintrag, kein Zertifikat);ESP_ERR_INVALID_STATE— eine Vorbedingung oder Aufrufreihenfolge stimmt nicht, oder ein Modul mit eingepaartem Sensor ist geschützt (siehe Fehlercodes).
Typen
rbamp_handle_t
typedef struct rbamp_obj_t *rbamp_handle_t;
Ein undurchsichtiges Handle zu einem Slave-Gerät. Der Benutzer hat keinen Zugriff auf seine Felder. Erzeugt mit rbamp_new(), freigegeben mit rbamp_del().
rbamp_topology_t
typedef enum {
RBAMP_TOPOLOGY_SINGLE = 1, /* 1 current channel (UI1 / I1) */
RBAMP_TOPOLOGY_SPLIT_PHASE = 2, /* 2 current channels (UI2 / I2) */
RBAMP_TOPOLOGY_THREE_PHASE = 3, /* 3 current channels (UI3 / I3) */
RBAMP_TOPOLOGY_FIVE_CH = 5, /* 5 current channels (UI5) */
RBAMP_TOPOLOGY_SEVEN_CH = 7, /* 7 current channels (UI7) */
} rbamp_topology_t;
Der Wert ist die Kanalanzahl. rbamp_begin() übernimmt sie aus der Variante des Moduls; rbamp_new_with_topology() legt sie stattdessen fest. Die Aufzählung ist bewusst nicht lückenlos (es gibt keine 4 und keine 6): Die größeren SKUs springen 3 → 5 → 7.
Zwei Konstanten bestimmen die Größe Ihrer Arrays:
| Makro | Wert | Bedeutung |
|---|---|---|
RBAMP_MAX_CHANNELS |
7 | Die größte Kanalanzahl, die eine SKU bietet. Dimensionieren Sie Kanal-Arrays damit. |
RBAMP_SNAPSHOT_CHANNELS |
3 | Kanäle, die von rbamp_snapshot_t getragen werden (ch0–2). Kanäle 3 und höher lesen Sie mit rbamp_read_channel() / rbamp_read_all_channels(). |
rbamp_sensor_class_t
typedef enum {
RBAMP_SENSOR_UNSET = 0, /* Factory default */
RBAMP_SENSOR_SCT013 = 1, /* SCT-013 fitted by the user */
RBAMP_SENSOR_WIRED_CT = 2, /* Wired CT shipped with the module, calibrated as a pair */
RBAMP_SENSOR_BUILTIN_CT = 3, /* Built-in CT, calibrated as a pair */
} rbamp_sensor_class_t;
Klasse 1 ist ein Modul, auf das der Anwender eine SCT-013 seiner Wahl setzt — das CT-Modell wählt den Sensortyp. Die Klassen 2 und 3 sind Module, die mit ihrem Sensor ausgeliefert und mit ihm kalibriert werden. Die Bibliothek schreibt die Klasse oder das Modell eines solchen Moduls nicht um: rbamp_set_sensor_class() und rbamp_set_ct_model_ch() liefern ESP_ERR_INVALID_STATE. Eine Neupaarung im Service läuft über rbamp_set_ct_model_ch_force().
rbamp_variant_t
Die Hardware-Build-Variante, geliefert von rbamp_variant() und rbamp_read_variant():
| Wert | Enumeration | Kanäle | Spannung / Leistung |
|---|---|---|---|
| 0 | RBAMP_VARIANT_UNKNOWN |
— | noch nicht gelesen / nicht veröffentlicht |
| 1 | RBAMP_VARIANT_UI1 |
1 | ja |
| 2 | RBAMP_VARIANT_UI2 |
2 | ja |
| 3 | RBAMP_VARIANT_UI3 |
3 | ja |
| 4 | RBAMP_VARIANT_I1 |
1 | nein |
| 5 | RBAMP_VARIANT_I2 |
2 | nein |
| 6 | RBAMP_VARIANT_I3 |
3 | nein |
| 7 | RBAMP_VARIANT_UI5 |
5 | ja |
| 8 | RBAMP_VARIANT_UI7 |
7 | ja |
rbamp_line_t
typedef enum {
RBAMP_LINE_BASIC = 0, /* default until rbamp_begin() has run */
RBAMP_LINE_STD = 1,
} rbamp_line_t;
Ein Handle-Typ und eine API bedienen beide Modulstufen. rbamp_begin() ermittelt die Stufe aus dem Identitätsblock des Moduls, und jeder spätere Aufruf wird intern weitergeleitet. Abfragbar über rbamp_line(dev). Aufrufe, die auf der erkannten Stufe kein Gegenstück haben, liefern ESP_ERR_NOT_SUPPORTED — nie ein Lesen aus dem falschen Register. Was nur die STD-Linie bietet (Blind- / Scheinleistung, THD, vorzeichenbehaftete Energiezähler, Snapshot-Bänke, Verlauf) ist unter STD-Linie zusammengefasst.
rbamp_snapshot_t
Wird von rbamp_read_all() zurückgegeben. Alle Felder sind in SI-Einheiten. Unbenutzte Kanäle (über channels hinaus) sind mit Nullen gefüllt.
typedef struct {
float voltage; /* V — RMS voltage */
float voltage_peak; /* V — peak voltage */
float current[3]; /* A — RMS current, ch0–2 */
float current_peak[3]; /* A — peak current, ch0–2 */
float power[3]; /* W — active power, ch0–2 (signed) */
float power_factor[3]; /* dimensionless, −1..+1 */
float frequency; /* Hz — mains frequency */
rbamp_topology_t topology;
uint8_t channels; /* the module's channel count: 1, 2, 3, 5 or 7 */
bool has_voltage_hw; /* true if a voltage sensor is present */
uint8_t implausible; /* bitmask of RBAMP_FIELD_* classes set to NaN; 0 = all OK */
} rbamp_snapshot_t;
Die Arrays halten nur die Kanäle 0–2. Auf einem UI5/UI7 meldet channels die volle Anzahl (5 oder 7); Kanäle 3+ lesen Sie mit rbamp_read_channel() / rbamp_read_all_channels().
Unplausible Felder. Ein einzelnes Feld außerhalb seiner Grenze lässt nicht den gesamten Snapshot scheitern: Ein Feld, das seine größenspezifische Plausibilitätsgrenze verletzt, wird auf NaN gesetzt und sein Klassenbit in implausible angehoben, während der Rest nutzbar bleibt und rbamp_read_all() weiterhin ESP_OK liefert. Prüfen Sie implausible (oder isnan() je Feld), bevor Sie einen Wert verwenden.
| Bit | Bedeutung |
|---|---|
RBAMP_FIELD_VOLTAGE |
voltage / voltage_peak abgelehnt |
RBAMP_FIELD_CURRENT |
ein Strom- / Spitzenstrom-Wert abgelehnt |
RBAMP_FIELD_POWER |
eine Leistung abgelehnt |
RBAMP_FIELD_PF |
ein power_factor abgelehnt |
RBAMP_FIELD_FREQUENCY |
Frequenz abgelehnt |
Die Grenzen sind RBAMP_SANITY_LIMIT_V / _I / _P / _PF (500 V, 150 A, 30000 W, 1.5). Nur ein echter Transportfehler lässt rbamp_read_all() einen Wert ungleich OK zurückgeben.
rbamp_channel_reading_t
Von rbamp_read_channel() / rbamp_read_all_channels() zurückgegeben — ein Kanal, beliebiger Index.
typedef struct {
float i_rms; /* A */
float i_peak; /* A */
float p_real; /* W (signed) */
float pf; /* −1..+1 */
uint8_t implausible; /* RBAMP_FIELD_* bits; the flagged field is NaN */
} rbamp_channel_reading_t;
rbamp_period_snapshot_t
Von rbamp_read_period_snapshot() zurückgegeben. Die Grundfunktion der Energiebuchführung.
typedef struct {
float avg_p[3]; /* W — average active power over the period, ch0–2 */
float max_p; /* W — peak power on channel 0 during the period */
uint32_t latch_ms; /* ms — module-reported duration; DIAGNOSTIC, not for energy */
uint32_t master_dt_ms; /* ms — master wall-clock window since the previous consumed read (CANONICAL) */
bool valid; /* the period was ready at read time */
float avg_p_total; /* W — average active power summed over ALL channels (signed) */
double wh_net; /* Wh — net energy of this period as the library accounted it (signed) */
bool module_restarted; /* the module rebooted inside this period */
uint32_t module_window_ms; /* ms — the module's own length of the closed window (0 on STD) */
uint16_t module_commit_ms; /* ms — length of one module commit as inferred: 100 or 200 (0 on STD) */
uint32_t module_uptime_s; /* s — module uptime read with the snapshot (0 if not published) */
bool window_from_boot; /* the window started at the module's boot */
bool window_long; /* module_window_ms exceeds 6 h */
} rbamp_period_snapshot_t;
| Feld | Hinweise |
|---|---|
avg_p[3] |
Nur Kanäle 0–2. Auf einem UI5/UI7 nimmt das Modul seinen mittleren Leistungs-Snapshot für alle Kanäle atomar; Kanäle 3+ lesen Sie mit rbamp_read_period_avg_power() und ihre Wh mit rbamp_energy_wh() (der Akkumulator integriert jeden Kanal). |
max_p |
Ein globales Spitzenwert, gemessen auf Kanal 0. |
latch_ms |
Nur zur Diagnose; unter Last kann er zu kurz liegen. Das Energie-Integrationsfenster ist master_dt_ms oder module_window_ms. |
master_dt_ms |
Das Fenster, über das die Bibliothek die Energie integriert: die eigene esp_timer-Zeit des Masters zwischen zwei aufeinanderfolgenden verbrauchten Lesevorgängen. |
avg_p_total, wh_net |
Die über alle Kanäle summierte Periode. wh_net ist die Durchschnittsleistung × master_dt_ms oder — bei Modulen, die die Energie am Gerät führen — die Zählerdifferenz des Moduls selbst. |
module_window_ms, module_commit_ms |
Das Maß des Modulfensters: gezählte Commits auf der Messuhr des Moduls, je 100 ms auf aktueller Firmware und 200 ms auf Firmware älter als v1.2 — die Bibliothek schließt aus demselben Snapshot, welche gilt. Normalerweise gegen master_dt_ms gegengeprüft. Beide sind auf der Linie STD 0. |
module_restarted |
Das Modul hat innerhalb der Periode neu gestartet. Seine RAM-Einstellungen (Uhr, Ereignismaske, Schwellenwerte, Digest-Felder) müssen erneut eingespielt werden — die Bibliothek spielt die wieder ein, die ihr gehören. Auf einem BASIC-Modul wird es beim ersten Snapshot nach rbamp_begin_resume() gesetzt, wenn das Fenster beim Booten des Moduls begann. |
module_uptime_s, window_from_boot |
window_from_boot ist wahr, wenn das Snapshot-Fenster beim Booten des Moduls begann (ein Neustart oder der erste Snapshot seit dem Booten). Immer falsch, wenn die Firmware keine Laufzeit meldet (module_uptime_s = 0). |
window_long |
Das Fenster überschreitet 6 h: Der Mittelwert des Moduls verliert bei sehr langen Fenstern an Genauigkeit — nehmen Sie häufiger Snapshots. |
⚠ latch_ms ist diagnostisch, nicht für die Energie. Es ist die eigene Messung der Periode durch das Modul und kann unter Last zu kurz anzeigen. Nicht für die Energieintegration verwenden. Das kanonische dt für die Energie ist master_dt_ms (oder Ihr eigenes esp_timer_get_time()-Delta), oder module_window_ms für den ersten Snapshot nach rbamp_begin_resume().
Ereignisbits — rbamp_event_bit_t
Bits des klebrigen, Write-1-to-Clear-Bytes EVENT_FLAGS (siehe Ereignisse):
| Enumeration | Bedeutung |
|---|---|
RBAMP_EVENT_PERIOD_READY |
Ein Periodensnapshot wurde aufgenommen |
RBAMP_EVENT_THRESH_I |
Stromschwelle überschritten |
RBAMP_EVENT_THRESH_P |
Leistungsschwelle überschritten |
RBAMP_EVENT_ERROR |
Dauerhafter Fehleranzeiger (siehe Fehlermodell) |
RBAMP_EVENT_CONFIG_CHANGED |
Gespeicherte Konfiguration geändert |
RBAMP_EVENT_RESET_OCCURRED |
Der Modul-Reset seit dem letzten Löschen |
RBAMP_EVENT_NVM_FAULT |
Nur STD: Fehler im Energiespeicher |
rbamp_drdy_event_t
Befüllt durch rbamp_wait_data_ready() / rbamp_read_all_ready():
typedef struct {
bool fresh; /* a new snapshot of THIS module is available (true on ESP_OK) */
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: an unmasked event is pending on this module */
uint8_t event_flags; /* EVENT_FLAGS consumed on an alarm (RBAMP_EVENT_*), else 0 */
uint32_t latency_us; /* edge to return, µs (0 when polling) */
} rbamp_drdy_event_t;
Digest-Typen
typedef enum {
RBAMP_DIGEST_I = ..., /* RMS current per channel */
RBAMP_DIGEST_U = ..., /* RMS voltage (modules with voltage sensing only) */
RBAMP_DIGEST_P = ..., /* real power per channel, whole watts, signed */
RBAMP_DIGEST_PF = ..., /* |power factor| per channel */
} rbamp_digest_field_t;
typedef struct {
uint8_t status; /* STATUS mirror at the moment of the publish */
uint8_t seq; /* window sequence (one step per published window, wraps 255→0) */
uint8_t n_ch; /* channels in the digest: min(module channels, 3) */
uint8_t fields; /* which rbamp_digest_field_t bits were read */
float i_a[3]; /* A; 0 when the field is off */
float u_v; /* V; 0 when off or no voltage sensing */
int16_t p_w[3]; /* W, signed, truncated toward 0 (|P| < 1 W reads 0); 0 when off */
float pf[3]; /* |PF| 0..1; 0 when off */
} rbamp_digest_t;
Korrekturtypen für SCT-013
typedef enum {
RBAMP_SCT_NONE, /* no correction (scale 1) */
RBAMP_SCT_CORRECTED, /* scale applied to this channel */
RBAMP_SCT_UNCALIBRATED, /* after a reset the module applies the raw preset; scale 1, warning logged */
RBAMP_SCT_GAIN_UNEXPECTED,/* applied gain is not that of a 30 A-calibrated module; scale 1, warning logged */
RBAMP_SCT_UNKNOWN_MODEL, /* model code without a known preset; scale 1, warning logged */
RBAMP_SCT_PENDING, /* not evaluated yet (before rbamp_begin); scale 1 */
} rbamp_sct_status_t;
typedef struct {
rbamp_sct_status_t status;
uint8_t model; /* CT model the module reports for the channel */
float scale; /* factor applied to current, power, energy and digest (1.0 unless CORRECTED) */
float gain_applied; /* gain the module applies (0 when not read) */
} rbamp_sct_correction_t;
RBAMP_SCT_NONE wird auf der Linie STD gemeldet bei Sensorklasse 2/3, ohne gebundenes Modell, bei Modell 3 (der werkseitige 30-A-Sensor), bei einem Modul, das sich selbst korrigiert (siehe SCT-013-Nennwertkorrektur), und wenn CONFIG_RBAMP_SCT_RATING_CORRECTION ausgeschaltet ist.
Typen der STD-Linie (rbamp_std_info_t, rbamp_std_channel_t, ...) sind zusammen mit ihren Funktionen unter STD-Linie beschrieben.
Lebenszyklus
rbamp_new
esp_err_t rbamp_new(i2c_master_bus_handle_t bus,
uint8_t addr,
rbamp_handle_t *out);
Erzeugt ein undurchsichtiges Handle für ein Slave-Gerät. Intern wird über i2c_master_bus_add_device() ein i2c_master_dev_handle_t erzeugt.
Kanalanzahl und Vorhandensein der Spannung werden in rbamp_begin() vom Modul übernommen: Ein UI1 meldet 1 Kanal, ein UI3 meldet 3, ein UI7 meldet 7 usw., sodass rbamp_channels(dev) direkt nach begin stimmt und die kanalbezogene API (rbamp_set_ct_model_ch, ...) Kanäle absichert, die das Modul nicht hat. Nur wenn das Modul seine Variante nicht veröffentlicht (Firmware älter als v1.3), fällt das Handle auf RBAMP_TOPOLOGY_THREE_PHASE zurück; eine Überschätzung ist dort harmlos — unbenutzte Kanäle lesen 0.0 A. Mit rbamp_new_with_topology() legen Sie eine Anzahl fest, unabhängig davon, was das Modul meldet.
| Parameter | Beschreibung |
|---|---|
bus |
I²C-Bus-Handle, erzeugt über i2c_new_master_bus(). |
addr |
7-Bit-Slave-Adresse. Bereich 0x08..0x77, Standard 0x50. |
out |
Wo das neue Handle abgelegt wird. |
Rückgabewerte: ESP_OK bei Erfolg; ESP_ERR_NO_MEM, wenn kein Speicher reserviert werden konnte; ESP_ERR_INVALID_ARG, wenn bus == NULL oder out == NULL oder addr außerhalb des Bereichs liegt; das esp_err_t von i2c_master_bus_add_device() bei einem Fehler des Bus-Treibers.
rbamp_new_with_topology
esp_err_t rbamp_new_with_topology(i2c_master_bus_handle_t bus,
uint8_t addr,
rbamp_topology_t topology,
rbamp_handle_t *out);
Wie rbamp_new, aber mit einer expliziten Topologie. Sie fixiert die Kanalanzahl: rbamp_begin() behält sie, auch wenn das Modul eine andere meldet (es wird eine Warnung protokolliert). Variante und Spannungsvorhandensein folgen weiterhin dem Modul. Nur nötig für Firmware älter als v1.3, die ihre Variante nicht veröffentlicht, oder um bewusst weniger oder mehr Kanäle freizugeben, als das Modul hat.
rbamp_del
void rbamp_del(rbamp_handle_t dev);
Gibt das Handle frei und entfernt das zugehörige i2c_master_dev_handle_t vom Bus. Sicher mit NULL aufzurufen — es ist ein No-op.
rbamp_begin
02 · Initialisierung und Start (initialization) · BASIC oder STD? (initialization) · Dauerabfragezyklus (empfohlen) (period-metering)
esp_err_t rbamp_begin(rbamp_handle_t dev);
Prüft das Gerät, erkennt die Modullinie, übernimmt Kanalanzahl und Variante und stellt einen Snapshot bereit.
Sequence:
-
Lesen Sie
REG_VERSION(0x03). Hat das Gerät nicht mit ACK geantwortet —ESP_FAIL. Liefert es0x00/0xFF—ESP_ERR_INVALID_RESPONSE. -
Erkennt die Produktlinie (BASIC / STD) aus dem Identitätsblock des Moduls und speichert sie zwischen (
rbamp_line()). Auf der Linie STD wird die Identität ebenfalls zwischengespeichert (rbamp_std_info()), und der Periodenmechanismus wird gewählt. -
Übernimmt Kanalanzahl, Variante und Spannungsvorhandensein vom Modul (sofern nicht über
rbamp_new_with_topologyeine Topologie fixiert wurde). -
Die SCT-013-Nennwertkorrektur bewerten (siehe SCT-013-Nennwertkorrektur).
-
Schreiben Sie
CMD_LATCH_PERIODals Primer + 50 ms warten. Der erste Snapshot nach dem Einschalten wird verworfen. (rbamp_begin_resume()überspringt diesen Schritt.) -
Speichern Sie
esp_timer_get_time()für die spätere Energieintegration.
Idempotent, aber nicht kostenlos: Jeder Aufruf löst einen Primer-Snapshot aus.
Rückgabewerte: ESP_OK bei Erfolg; andernfalls die oben genannten Fehlercodes.
rbamp_begin_resume
esp_err_t rbamp_begin_resume(rbamp_handle_t dev);
rbamp_begin() ohne den Primer-Snapshot — es behält das Fenster, das das Modul gesammelt hat, während der Master abwesend war. Ein BASIC-Modul mittelt bis zum nächsten Snapshot weiter, daher hält das Modul nach einem Neustart oder Ausfall des Masters weiterhin das gesamte Fenster seit dem letzten verbrauchten Snapshot; rbamp_begin() würde einen Snapshot nehmen und verwerfen, dieser Aufruf nicht.
Der erste verbrauchte rbamp_read_period_snapshot() integriert nach dem eigenen Fenster des Moduls (module_window_ms): wh_net = avg_p_total × module_window_ms, master_dt_ms wird gleich module_window_ms gesetzt und module_restarted = window_from_boot. Alle späteren Snapshots verwenden wie üblich den Master-Takt. Ein veralteter erster Lesevorgang (Periode nicht gültig, leerer Akkumulator) wird wie jeder andere verworfen, und der nächste gültige Lesevorgang verwendet trotzdem das Modulfenster.
Bei Firmware, die die Laufzeit nicht veröffentlicht, bleiben window_from_boot und module_restarted false: Das wiederhergestellte Fenster kann dann einen Modul-Neustart enthalten, den die Bibliothek nicht sehen kann. Auf STD-Modulen ist der Aufruf identisch mit rbamp_begin() (ihre Energie liegt in Zählern am Modul).
rbamp_begin_event_flags
uint8_t rbamp_begin_event_flags(rbamp_handle_t dev);
Die EVENT_FLAGS, wie sie rbamp_begin() vorgefunden hat (beide Linien; 0, wenn nicht lesbar). RBAMP_EVENT_RESET_OCCURRED bedeutet hier, dass das Modul neu gestartet hatte, bevor die Bibliothek es antraf — spielen Sie seine RAM-Einstellungen erneut ein (Uhr, Ereignismaske, Schwellenwerte). Die Bibliothek löscht bei begin nichts. Kein Bus-Verkehr.
rbamp_probe
esp_err_t rbamp_probe(rbamp_handle_t dev);
Eine leichtgewichtige Lebendprüfung. Ein einzelnes Lesen von REG_VERSION ohne Nebenwirkungen.
Rückgabe: ESP_OK, wenn der Slave mit ACK geantwortet und eine unterstützte Version gemeldet hat (nicht 0 und nicht 0xFF); sonst ESP_FAIL.
rbamp_wait_ready
02 · Initialisierung und Start (Initialisierung) · 3. DATA_VALID (0xCE) wird nie 1 (Fehlersuche) · 4 · Registerkarte (Produktion v1.3) (API-Referenz)
esp_err_t rbamp_wait_ready(rbamp_handle_t dev, uint32_t timeout_ms);
Fragt das Ready-Flag des Moduls ab, bis Bit 0 gesetzt ist. Nützlich nach dem Einschalten — das Modul braucht bis zu 100 ms für das erste RT-Fenster.
Rückgabewerte: ESP_OK, wenn das Bit vor Ablauf von timeout_ms gesehen wird; andernfalls ESP_ERR_TIMEOUT.
Getter für den Handle-Zustand
BASIC oder STD? (initialization) · Mehrkanal-Strom (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.10 V03-Echtzeitblock (0x86..0xBD) (api-reference)
uint8_t rbamp_firmware_version(rbamp_handle_t dev);
rbamp_topology_t rbamp_topology (rbamp_handle_t dev);
uint8_t rbamp_channels (rbamp_handle_t dev);
rbamp_variant_t rbamp_variant (rbamp_handle_t dev);
bool rbamp_has_voltage_hw (rbamp_handle_t dev);
uint8_t rbamp_address (rbamp_handle_t dev);
rbamp_line_t rbamp_line (rbamp_handle_t dev);
Alle liefern zwischengespeicherte Werte, ohne den Bus zu berühren.
| Funktion | Rückgabewerte |
|---|---|
rbamp_firmware_version |
Das nach rbamp_begin() zwischengespeicherte Byte REG_VERSION — auf der Linie STD ist dies die Version der Registerabbildung, nicht die Firmware-Image-Version (siehe rbamp_std_read_image_version). 0 vor rbamp_begin() oder wenn es fehlschlug. |
rbamp_topology |
Die Aufzählung der Kanalanzahl — vom Modul nach rbamp_begin() oder wie durch rbamp_new_with_topology() festgelegt; THREE_PHASE vor begin / auf Firmware, die ihre Variante nicht veröffentlicht. |
rbamp_channels |
Anzahl gültiger Stromkanäle (1, 2, 3, 5 oder 7). |
rbamp_variant |
Die von rbamp_begin() zwischengespeicherte Variante; RBAMP_VARIANT_UNKNOWN vor begin oder wenn das Modul sie nicht veröffentlicht. rbamp_read_variant() liest das Register neu. |
rbamp_has_voltage_hw |
true, wenn die Spannungsmessung-Hardware erkannt wurde. |
rbamp_address |
Die aktuelle 7-Bit-Adresse (aktualisiert sich nach rbamp_commit_address_change()). |
rbamp_line |
RBAMP_LINE_BASIC, bis rbamp_begin() ausgeführt wurde, danach die erkannte Linie. |
rbamp_basic_fw_name
const char *rbamp_basic_fw_name(uint8_t version);
Eine reine Nachschlagefunktion (kein Bus-Verkehr): der lesbare Firmware-Name für das BASIC-Byte REG_VERSION, wie es rbamp_firmware_version() liefert — zum Beispiel 0x0D → "1.4.21", 0x0C → "1.4.20", 0x0B → "1.4.19", 0x0A → "1.4.18", 0x07 → "1.4.15-1.4.17", 0x05 → "1.4.4-1.4.14", 0x04 → "1.2-1.4.3", 0x00..0x03 → "<1.2". Jedes andere Byte → NULL (unbekannt oder kein BASIC-Modul).
Echtzeit-Lesevorgänge (RT-Block, Aktualisierung alle 100 ms)
Alle Funktionen liefern esp_err_t. Bei ESP_OK wird der Wert in den Zeiger out geschrieben; bei einem Fehler ist *out undefiniert. Im Hintergrund gibt es eine Disziplin aus Retry und Sanity zur Robustheit gegen seltene Verbindungsstörungen im I²C-Stack des ESP-IDF.
Lesevorgänge pro Kanal
RT-Registerreferenz (realtime-polling) · Bilanzierung in beide Richtungen (period-metering)
esp_err_t rbamp_read_voltage (rbamp_handle_t dev, uint8_t phase, float *out);
esp_err_t rbamp_read_voltage_peak (rbamp_handle_t dev, uint8_t phase, float *out);
esp_err_t rbamp_read_current (rbamp_handle_t dev, uint8_t ch, float *out);
esp_err_t rbamp_read_current_peak (rbamp_handle_t dev, uint8_t ch, float *out);
esp_err_t rbamp_read_power (rbamp_handle_t dev, uint8_t ch, float *out);
esp_err_t rbamp_read_power_factor (rbamp_handle_t dev, uint8_t ch, float *out);
esp_err_t rbamp_read_frequency (rbamp_handle_t dev, float *out);
| Funktion | Rückgabewert | Hinweise |
|---|---|---|
rbamp_read_voltage |
Effektivspannung, V | phase = 0 auf der BASIC-Linie |
rbamp_read_voltage_peak |
Scheitelspannung, V | Liefert auf STD-Modul-Map 0x34 und älter 0 — verwenden Sie max_u / min_u einer Snapshot-Bank |
rbamp_read_current |
Effektivstrom des Kanals, A | ch < rbamp_channels(dev); Kanäle 3+ (UI5 / UI7) werden transparent über das Kanalfenster geleitet |
rbamp_read_current_peak |
Spitzenstrom des Kanals, A | Liefert auf STD-Modul-Map 0x34 und älter 0 — verwenden Sie max_i einer Snapshot-Bank |
rbamp_read_power |
Wirkleistung, W (vorzeichenbehaftet) | Negativ = Einspeisung (PV / bidirektionale Anlagen) |
rbamp_read_power_factor |
Leistungsfaktor | Dimensionslos, −1..+1 |
rbamp_read_frequency |
Netzfrequenz, Hz | 50.0 oder 60.0 bei einem gesunden Netz. STD: ein Modulwert von 0 (kein Netz) liefert ESP_ERR_INVALID_RESPONSE mit *out = NaN |
Liegt ch oder phase außerhalb des Bereichs, liefert der Aufruf ESP_ERR_INVALID_ARG.
Einmaliges Lesen des gesamten RT-Blocks
RT-Registerreferenz (realtime-polling) · Abfrage — einzelnes Modul (realtime-polling) · 4.10 V03-Echtzeitblock (0x86..0xBD) (api-reference)
esp_err_t rbamp_read_all(rbamp_handle_t dev, rbamp_snapshot_t *out);
Entspricht sequenziellen Aufrufen von rbamp_read_voltage + rbamp_read_voltage_peak + rbamp_read_current(0..N) + rbamp_read_current_peak(0..N) + rbamp_read_power(0..N) + rbamp_read_power_factor(0..N) + rbamp_read_frequency. Ungenutzte Kanäle (jenseits von rbamp_channels(dev)) werden mit Nullen gefüllt.
Bei einem Modul mit mehr als drei Kanälen (UI5 / UI7) werden nur Kanäle 0–2 in die Struktur gelesen (RBAMP_SNAPSHOT_CHANNELS = 3); Kanäle 3+ werden nicht berührt — lesen Sie sie mit rbamp_read_channel() / rbamp_read_all_channels(). Auf der Linie STD werden der Spannungsblock und jeder Kanalblock vollständig gelesen (je eine Transaktion).
Ein Feld, das seine Plausibilitätsgrenze überschreitet, lässt den Aufruf nicht scheitern: Es wird auf NaN gesetzt und in snap.implausible markiert; der Aufruf liefert trotzdem ESP_OK (siehe rbamp_snapshot_t).
Rückgabewerte: ESP_OK bei Erfolg (prüfen Sie implausible); andernfalls der erste zugrunde liegende Transportfehler — in diesem Fall ist der Inhalt von out teilweise und darf nicht verwendet werden.
Blind- und Scheinleistung
esp_err_t rbamp_read_reactive_power(rbamp_handle_t dev, uint8_t ch, float *out);
esp_err_t rbamp_read_apparent_power(rbamp_handle_t dev, uint8_t ch, float *out);
Blindleistung von Kanal ch in var (vorzeichenbehaftet) und Scheinleistung in VA. Diese Größen gibt es nur auf der STD-Linie; bei BASIC stellt diese Bibliothek die Blindleistung nicht bereit, und auf einem BASIC-Handle liefern beide ESP_ERR_NOT_SUPPORTED.
Kanalzugriff (Kanäle 3 und höher)
Mehrkanaliger Strom (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.14 Kanalzugriffsfenster (0x32 + 0x3C..0x3F) (api-reference)
Kanäle 0–2 liegen im flachen RT-Block. Auf den größeren SKUs (UI5 / UI7) sind Kanäle 3+ nur über das Kanalfenster des Moduls erreichbar. Die Bibliothek übernimmt das transparent: rbamp_read_current(), rbamp_read_current_peak(), rbamp_read_power() und rbamp_read_power_factor() akzeptieren jedes ch in 0..rbamp_channels(dev)-1 und leiten Kanäle 3+ über das Fenster. Die Fensterauswahl ist eine gemeinsam genutzte Ressource im Modul, und Auswahl + Lesen bilden einen atomaren Abschnitt — teilen Sie ein Handle nicht zwischen Tasks ohne eigenen Mutex.
esp_err_t rbamp_read_channel (rbamp_handle_t dev, uint8_t ch,
rbamp_channel_reading_t *out);
esp_err_t rbamp_read_all_channels(rbamp_handle_t dev,
rbamp_channel_reading_t *out, uint8_t n);
-
rbamp_read_channelliest alle vier RT-Felder eines Kanals in einerbamp_channel_reading_t. Ein Feld, das seine Plausibilitätsgrenze verletzt, istNaNmit seinem BitRBAMP_FIELD_*inimplausible. -
rbamp_read_all_channelsfülltout[]mit jedem belegten Kanal;nist die Kapazität vonout(dimensionieren Sie es mitRBAMP_MAX_CHANNELS); der Aufruf fülltmin(n, rbamp_channels(dev))Einträge.
Rückgabe: ESP_OK (prüfen Sie implausible); ESP_ERR_INVALID_ARG bei einem ungültigen Kanal oder NULL; sonst der erste Transportfehler.
Das sind Live-, Momentanwerte. Ein Durchlauf über die Kanäle liest benachbarte Publikationsfenster und ist kein gleichzeitiger Snapshot — für Energie, die über Kanäle hinweg abgestimmt ist, verwenden Sie den Periodenpfad.
rbamp_read_all() auf einem UI5 / UI7 liefert die ersten drei Kanäle (RBAMP_SNAPSHOT_CHANNELS = 3) und lässt den Rest unberührt; snap.channels meldet weiterhin die tatsächliche Anzahl des Moduls.
rbamp_read_commit_seq
esp_err_t rbamp_read_commit_seq(rbamp_handle_t dev, uint8_t *out);
Liest das Sequenzbyte des Digests: ein uint8_t, das pro Messfenster erhöht wird (bei aktueller Firmware alle 100 ms, bei Images vor v1.2 alle 200 ms; läuft von 255 auf 0 über). Lesen Sie es vor und nach einem Sweep über mehrere Register — ein unveränderter Wert belegt, dass alle Lesevorgänge aus einem einzigen Commit stammen. Der Digest enthält keine CRC.
Datenbereit (DRDY)
01 · Hardware-Anschluss (hardware-connection) · 03 · Echtzeit-Abfrage (realtime-polling) · Abfrage — einzelnes Modul (realtime-polling)
DRDYAusgang: im Ruhezustand HIGH (Master-Pull-up), ein ~10-µs-LOW-Impuls jedes Mal, wenn ein vollständiger Messsnapshot veröffentlicht wird (alle 100 ms über die gesamte Familie; BASIC-Images vor v1.2 und STD-Images bis 0x7B: 200 ms). Mehrere Module können sich eine verdrahtete ODER-Leitung teilen. BASIC-Module halten die Leitung außerdem fest auf LOW, solange ein nicht maskiertes Ereignis ansteht (Alarm).
Die Bibliothek macht aus dem Impuls ein Aufwecksignal, sodass ein Leser denselben Snapshot nie zweimal liest, nie über eine Veröffentlichung hinweg liest und erfährt, wie viele Snapshots er verpasst hat. Bei STD-Modulen sagt der Veröffentlichungszähler, welches Modul auf einer gemeinsamen Leitung gepulst hat. Ohne DRDY-Leitung funktionieren dieselben Aufrufe per Polling des Zählers des Moduls alle CONFIG_RBAMP_DRDY_POLL_MS. STD-Module, die älter als Image 0x00010075 sind, steuern den Pin anders: Die Bibliothek behandelt sie als ohne DRDY-Leitung und fragt per Polling ab.
esp_err_t rbamp_set_drdy_gpio (rbamp_handle_t dev, int gpio);
esp_err_t rbamp_wait_data_ready(rbamp_handle_t dev, uint32_t timeout_ms,
rbamp_drdy_event_t *ev);
esp_err_t rbamp_read_all_ready (rbamp_handle_t dev, uint32_t timeout_ms,
rbamp_snapshot_t *out, rbamp_drdy_event_t *ev);
esp_err_t rbamp_read_data_seq (rbamp_handle_t dev, uint16_t *out);
| Funktion | Beschreibung |
|---|---|
rbamp_set_drdy_gpio(dev, gpio) |
Hängt die DRDY-Leitung dieses Moduls an, oder löst sie mit -1. Der GPIO wird als Eingang mit Pull-up und Interrupt auf der fallenden Flanke konfiguriert; beliebig viele Handles dürfen sich einen GPIO teilen. Rufen Sie es nach rbamp_begin() auf (der elektrische Vertrag der Leitung hängt vom erkannten Modul ab). Liefert ESP_ERR_NO_MEM, wenn mehr als 4 verschiedene Leitungen oder 8 Handles pro Leitung belegt sind. |
rbamp_wait_data_ready(dev, timeout_ms, ev) |
Blockiert, bis das Modul einen Snapshot veröffentlicht hat, der neuer ist als der letzte, den dieser Aufruf zurückgegeben hat (oder der letzte über rbamp_read_all_ready gelesene), höchstens timeout_ms. ev darf NULL sein. |
rbamp_read_all_ready(dev, timeout_ms, out, ev) |
rbamp_wait_data_ready(), gefolgt von rbamp_read_all(): ein kohärenter Lesevorgang je veröffentlichtem Snapshot, nie derselbe Snapshot zweimal. |
rbamp_read_data_seq(dev, &seq) |
Die aktuelle Snapshot-Folge ohne Warten. |
So funktioniert das Warten mit einer DRDY-Leitung. Es weckt auf der fallenden Flanke und prüft dann, ob die Sequenz des Moduls weitergelaufen ist (ein Impuls auf einer gemeinsamen Leitung kann zu einem anderen Modul gehören — der Aufruf wartet dann weiter). Liegt die Leitung 5 ms nach der Flanke immer noch auf LOW, steht auf einem Modul der Leitung ein nicht maskiertes Ereignis aus: Die Flags jedes an der Leitung hängenden Moduls werden gelesen und gelöscht (Write-1-to-Clear, was die Leitung freigibt — eine gehaltene Leitung würde die Impulse der anderen Module verdecken). Die Flags dieses Moduls kommen in ev mit gesetztem alarm zurück; die Flags der anderen Module gehen an deren eigene Handles und werden beim nächsten Warten dort gemeldet.
Rückgabewerte (rbamp_wait_data_ready): ESP_OK (frischer Snapshot); ESP_ERR_TIMEOUT; ESP_ERR_NOT_SUPPORTED auf STD-Modulen ohne Veröffentlichungszähler (Version der Registerabbildung unter 0x36).
rbamp_set_drdy_gpio(dev, GPIO_NUM_4);
while (1) {
rbamp_snapshot_t s;
rbamp_drdy_event_t ev;
if (rbamp_read_all_ready(dev, 500, &s, &ev) == ESP_OK) {
if (ev.missed) ESP_LOGW(TAG, "missed %u snapshot(s)", ev.missed);
/* use s — exactly one read per published snapshot */
}
}
BASIC-Digest
4.9 Digest-Fenster (0x70..0x85) (api-reference) · 8.7 DIGEST-Round-Trip — konfigurieren + lesen (api-reference)
Der Digest ist ein kompakter Block, den ein BASIC-Modul mit jedem Fenster veröffentlicht. Er erlaubt dem Master, das Ergebnis des Fensters in einer I²C-Transaktion zu lesen statt einer pro Feld.
esp_err_t rbamp_set_digest_fields(rbamp_handle_t dev, uint8_t fields);
esp_err_t rbamp_read_digest (rbamp_handle_t dev, rbamp_digest_t *out);
-
rbamp_set_digest_fields(dev, fields)wählt die Felder, die das Modul in den Digest packt: ein ODER ausRBAMP_DIGEST_I,_U,_P,_PF(nicht 0). Der Standard, wenn nie aufgerufen, sind Strom + Wirkleistung, plus Spannung auf Modulen mit Spannungsmessung. Die Wahl wird beim nächstenrbamp_read_digest()an das Modul geschrieben (oder sofort, wenn das Handle bereits auf einem BASIC-Modul mit Digest-Fähigkeit begonnen wurde). Das Modul hält sie nur im RAM, daher schreibt die Bibliothek sie nach einem erkannten Neustart des Moduls erneut. RückgabeESP_ERR_INVALID_ARGfür 0, für unbekannte Bits oder wenn das Modul ein Feld ablehnt, das es nicht hat (Spannung auf einem Modul nur mit Strom);ESP_ERR_NOT_SUPPORTEDauf der Linie STD oder auf Firmware ohne die Digest-Fähigkeit. -
rbamp_read_digest(dev, &d)liest Status, Fenstersequenz und die gewählten Felder für Kanäle 0–2 in einer einzigen Transaktion. Gedacht zum Lesen jedes veröffentlichten Fensters auf DRDY:rbamp_wait_data_ready()und danachrbamp_read_digest()liefert die vorzeichenbehaftete Wirkleistung jedes Fensters für wenige Bus-Bytes. Kanäle 3 und höher sind nicht im Digest enthalten (verwenden Sierbamp_read_channel()). Die Wirkleistung kommt in ganzen Watt — eine Last unter 1 W liest 0. RückgabeESP_OK;ESP_ERR_NOT_SUPPORTEDauf der Linie STD oder auf BASIC-Firmware ohne die Digest-Fähigkeit; Transportfehler.
Abrechnung je Periode
Den Überblick finden Sie in 01 · Überblick, für eine minimale Vorlage siehe 05 · Schnellstart, Schritt 5.
rbamp_latch_period
esp_err_t rbamp_latch_period(rbamp_handle_t dev);
Schreibt CMD_LATCH_PERIOD (0x27) in REG_COMMAND. Es wartet nicht — der Aufrufer muss 50 ms einschwingen lassen und rbamp_is_period_valid() prüfen, bevor er liest.
In den meisten Fällen verwenden Sie rbamp_read_period_snapshot() — es kapselt die gesamte Abfolge.
rbamp_is_period_valid
04 · Periodenmessung und Tarifabrechnung (Periodenmessung) · Kalibrierung und Genauigkeit (Fehlersuche) · 7.5 Erhaltung der Periode bei fehlgeschlagenem Snapshot (API-Referenz)
esp_err_t rbamp_is_period_valid(rbamp_handle_t dev, bool *out);
Liest das Bit „Snapshot bereit“. *out = true, wenn der letzte Snapshot frisch ist.
rbamp_read_period_avg_power
Register der Periodenmomentaufnahme (period-metering) · 4.11 V03-Periodenblock (0xBE..0xCF) (api-reference) · 4.12 V03 Q + Periode ch0 (0xD0..0xE3, Produktionsbuild) (api-reference)
esp_err_t rbamp_read_period_avg_power(rbamp_handle_t dev,
uint8_t ch, float *out);
Mittlere Wirkleistung auf dem Kanal über die Snapshot-Periode. Muss nach rbamp_latch_period() + 50 ms Abklingzeit + einer gültigen Prüfung aufgerufen werden.
rbamp_read_period_max_power
Register der Periodenmomentaufnahme (period-metering) · 4.12 V03 Q + Periode ch0 (0xD0..0xE3, Produktionsbuild) (api-reference)
esp_err_t rbamp_read_period_max_power(rbamp_handle_t dev, float *out);
Spitzen-Momentanleistung auf Kanal 0 über das Snapshot-Fenster. ch=0 nur auf Firmware v1.
rbamp_read_period_latch_ms
13. Takt-Drift mehrerer Module bei langen Tests (troubleshooting) · 4.13 Diagnose-dt auf Chipseite (0xEC) (api-reference)
esp_err_t rbamp_read_period_latch_ms(rbamp_handle_t dev, uint32_t *out);
Die Periodendauer, wie sie vom Gerät gesehen wird, in ms.
Die vom Modul gemeldete Dauer kann unter Last zu kurz erscheinen. Für die Energieintegration verwenden Sie master_dt_ms (oder module_window_ms) aus rbamp_period_snapshot_t, nicht dieses Feld.
rbamp_read_period_snapshot
Fortlaufender Abfragezyklus (empfohlen) (Periodenmessung) · Mehrmodul — gleichzeitiger Snapshot (Periodenmessung) · Kalibrierung und Genauigkeit (Fehlersuche)
esp_err_t rbamp_read_period_snapshot(rbamp_handle_t dev,
rbamp_period_snapshot_t *out,
uint16_t settle_ms,
bool skip_latch);
Der empfohlene Einstiegspunkt für die Abrechnung je Periode. Der vollständige Ablauf im Hintergrund:
-
Bei
skip_latch == true— den LATCH-Schreibvorgang überspringen (nach einer manuellen Folge von Snapshot-Befehlen oder einem Broadcast-Snapshot zur Synchronisation mehrerer Module verwendet). -
Andernfalls —
CMD_LATCH_PERIODschreiben. - Erfassen Sie
esp_timer_get_time(), ummaster_dt_mszu berechnen. vTaskDelay(pdMS_TO_TICKS(settle_ms))— standardmäßig 50 ms.-
Das Snapshot-bereit-Flag prüfen. Ist es 0 —
ESP_ERR_INVALID_RESPONSEsetzen und den Zeitstempel festhalten (damit der nächste Snapshotdtnicht doppelt zählt). -
Lesen Sie
avg_p[0..channels-1]+max_p+latch_ms. - Zeitstempel aktualisieren und den Energie-Integrator für alle Kanäle aufrufen (falls die Komponente nicht ohne
CONFIG_RBAMP_DISABLE_ENERGYgebaut ist).
| Parameter | Beschreibung |
|---|---|
out |
Ausgabestruktur. |
settle_ms |
Nach dem Snapshot warten (empfohlen 50). |
skip_latch |
Bei true — LATCH nicht schreiben, nur lesen (für das Mehrmodul-Muster). |
Rückgabe: ESP_OK, wenn out->valid == true; ESP_ERR_INVALID_RESPONSE, wenn der Snapshot veraltet ist (bei veraltet wird die Energie nicht integriert und der Anker gehalten); ESP_ERR_NOT_SUPPORTED bei einem STD-Modul ohne Snapshot-Bänke und ohne Zähler; sonst das esp_err_t aus den Busoperationen. Zum Verhalten auf der STD-Linie siehe Periodenaufrufe auf der STD-Linie.
Die Energie wird über master_dt_ms integriert — das eigene Fenster des Masters zwischen aufeinanderfolgenden verbrauchten Lesevorgängen. Nach rbamp_begin_resume() integriert der erste verbrauchte Snapshot stattdessen über das eigene Fenster des Moduls.
Zwischen den Snapshot-Aufrufen: 60 s sind bequem, 30 s sind grenzwertig, < 10 s garantieren veraltete Lesewerte. Die Firmware integriert den periodischen Akkumulator intern; ein häufigerer Aufruf von rbamp_read_period_snapshot(), als die Firmware die nächste Periode vorbereiten kann, liefert immer einen veralteten Snapshot (ESP_ERR_INVALID_RESPONSE). Für hochfrequente Telemetrie verwenden Sie die RT-Funktionen rbamp_read_power(ch) / rbamp_read_all() — sie aktualisieren mit ~10 Hz.
rbamp_read_uptime_s
Modul-Neustart erkennen (period-metering) · 4.6 Zustand / Diagnose (0x46..0x4F) (api-reference)
esp_err_t rbamp_read_uptime_s(rbamp_handle_t dev, uint32_t *out);
Sekunden seit dem Booten des Moduls. Ein kleiner werdender Wert zwischen zwei Lesevorgängen bedeutet, dass das Modul neu gestartet hat. Auf BASIC-Firmware, die die Laufzeit nicht veröffentlicht, liefert er 0.
Periodenaufrufe auf der Linie STD
Dieselbe Periodenschnittstelle bedient beide Linien, doch was darunter geschieht, hängt davon ab, was das STD-Modul bietet (rbamp_std_info_t.period_source, festgelegt durch rbamp_begin()):
period_source |
Verhalten von rbamp_read_period_snapshot() |
|---|---|
RBAMP_STD_PERIOD_LATCH |
Das Modul hat Snapshot-Bänke. Die Bibliothek verwendet Bank 0 (scharf gestellt durch rbamp_begin()): sie latcht, wartet mindestens 300 ms, unabhängig von einem kleineren settle_ms (das Modul nimmt den Snapshot an seiner nächsten Messfenstergrenze), liest die Bank und rechnet sie über master_dt_ms in Energie um. Mit skip_latch bestimmt der Aufrufer das Timing: latchen, ≥ 300 ms warten, dann lesen. Bit 0 in rbamp_std_arm_banks() gesetzt lassen. |
RBAMP_STD_PERIOD_COUNTERS |
Keine Snapshot-Bänke, aber dauerhaft gespeicherte Lebensdauerzähler. Es wird kein Latch gesendet, und settle_ms / skip_latch werden ignoriert: Der Aufruf liest die Zähler und meldet die Differenz seit dem vorherigen verbrauchten Lesevorgang in avg_p_total / wh_net. Beim Neustart des Moduls geht nichts verloren (module_restarted kennzeichnet das). |
RBAMP_STD_PERIOD_NONE |
Keines von beiden. Die Periodenaufrufe liefern ESP_ERR_NOT_SUPPORTED, statt stillschweigend eine ungültige Periode zu melden. |
Beim Zählerpfad hält avg_p[] die Periode für ein Ein-Kanal-Modul, die kanalweisen Zählerdifferenzen auf Modulen, die kanalweise Zähler veröffentlichen, und NaN auf Mehrkanal-Modulen, die dies nicht tun; max_p ist NaN. Bei Zählermodulen ohne feinkörnige Zähler wählen Sie eine Periode, die lang genug ist, dass ein Zählerschritt nur einen kleinen Bruchteil davon ausmacht (Minuten, nicht Sekunden). ESP_ERR_INVALID_RESPONSE verankert die Bibliothek neu (diese eine Periode wird verworfen), wenn sich die Generationszahl des Moduls geändert hat (seine Zähler wurden zurückgesetzt oder übernommen) oder ein Zähler rückwärts gelaufen ist.
Weitere STD-Hinweise: rbamp_latch_period() latcht Bank 0 (ein No-op, das bei Zählermodulen ESP_OK liefert); rbamp_is_period_valid() ist bei Zählermodulen wahr, sobald die Bibliothek einen Zähleranker hält (nach rbamp_begin() immer); rbamp_read_period_avg_power() liefert den Durchschnitt der zuletzt verbrauchten Periode für Ein-Kanal-Zählermodule und ESP_ERR_NOT_SUPPORTED bei Mehrkanal-Modulen; rbamp_read_period_max_power() liefert ESP_ERR_NOT_SUPPORTED bei Zählermodulen; rbamp_read_period_snapshot() liefert ESP_ERR_INVALID_RESPONSE, wenn Bank 0 kein abgelaufenes Fenster meldet — hat ein Modul-Reset die Arm-Maske der Bank gelöscht, scharf stellt die Bibliothek Bank 0 neu, nimmt einen Primer-Snapshot und startet den Zeitanker neu (dieses eine Fenster wird nicht integriert, das nächste ist wieder vollständig).
Inline-Hilfsfunktion
static inline esp_err_t
rbamp_read_period_snapshot_simple(rbamp_handle_t dev,
rbamp_period_snapshot_t *out);
Ein Komfort-Wrapper für die Standardargumente: settle_ms=50, skip_latch=false. Verwenden Sie ihn für gewöhnliches periodisches Abfragen.
Energiebuchführung (Akkumulator auf Masterseite)
Algorithmus auf der Masterseite (Periodenmessung) · 7 · Semantik (API-Referenz)
Wenn die Komponente ohne CONFIG_RBAMP_DISABLE_ENERGY=y gebaut wird, stehen Zugriffsfunktionen für den Wh-Akkumulator im Handle zur Verfügung:
double rbamp_energy_wh (rbamp_handle_t dev, uint8_t ch);
void rbamp_energy_reset (rbamp_handle_t dev, uint8_t ch);
void rbamp_energy_reset_all (rbamp_handle_t dev);
void rbamp_energy_disable (rbamp_handle_t dev);
void rbamp_energy_enable (rbamp_handle_t dev);
Der Akkumulator wird bei jedem erfolgreichen rbamp_read_period_snapshot() automatisch aktualisiert. Er ist vorzeichenbehaftet — ein negativer Wert bedeutet Nettoeinspeisung.
| Funktion | Beschreibung |
|---|---|
rbamp_energy_wh(dev, ch) |
Aktueller Wh-Gesamtwert des Kanals. Liegt ch außerhalb des Bereichs — 0.0. |
rbamp_energy_reset(dev, ch) |
Einen einzelnen Kanal auf null setzen. |
rbamp_energy_reset_all(dev) |
Alle Kanäle auf null setzen. |
rbamp_energy_disable(dev) |
Automatische Integration abschalten. Nützlich, wenn der Master seine eigene Wh-Speicherung führt (Deep-Sleep — siehe 06 · Beispiele, Szenario 9). |
rbamp_energy_enable(dev) |
Automatische Integration wieder aktivieren. |
rbamp_energy_wh() nimmt entweder einen Kanalindex (0..rbamp_channels(dev)-1, bis 6 auf einem UI7) oder den Selektor RBAMP_ENERGY_CH_TOTAL (0xFF) für die Gesamtsumme aller Kanäle. Der Wert ist vorzeichenbehaftet — negativ bedeutet Nettoeinspeisung — und 0, wenn ch außerhalb des Bereichs liegt oder die Energie deaktiviert ist.
STD-Module ohne Snapshot-Bänke (Zählerpfad): Die Summe ist die Summe der Zählerdifferenzen des Moduls selbst — exakt, auf dem Host wird nichts integriert. Werte pro Kanal stammen aus den Zählern des Moduls pro Kanal, sofern es diese veröffentlicht; sie sind NaN bei Mehrkanal-Modulen, die das nicht tun, und entsprechen bei Einkanal-Modulen der Summe.
Integrationsformel:
wh[ch] += snap.avg_p[ch] × master_dt_ms / 1000 / 3600
[W] [milliseconds] → [Wh]
Bei einem Build mit CONFIG_RBAMP_DISABLE_ENERGY=y werden beide Funktionen (Prototypen und Speicher) aus dem Binärcode entfernt über #if-Guards — ein Aufruf von rbamp_energy_wh() erzeugt einen Linker-Fehler „unresolved external“ (nicht aufgelöstes externes Symbol).
Der Akkumulatortyp (rbamp_energy.h)
Der Akkumulator hinter dem Handle liegt in einem eigenen Header, rbamp_energy.h. Der Header beschreibt ihn als interne API — die Anwendung verwendet normalerweise die oben genannten rbamp_energy_*-Wrapper und braucht diese nie. Er ist hier aufgeführt, weil die Symbole sichtbar sind:
typedef struct {
double wh[RBAMP_ENERGY_MAX_CH]; /* per-channel running total, Wh (signed) */
double wh_total; /* all-channel total, Wh (signed) */
bool enabled; /* false: tick() is a no-op */
} rbamp_energy_t;
void rbamp_energy_init (rbamp_energy_t *e);
void rbamp_energy_tick (rbamp_energy_t *e, const float avg_p[], uint8_t channels,
uint32_t period_ms, bool valid);
double rbamp_energy_wh_get (const rbamp_energy_t *e, uint8_t ch);
void rbamp_energy_add_wh (rbamp_energy_t *e, uint8_t ch, double wh);
void rbamp_energy_reset_ch (rbamp_energy_t *e, uint8_t ch);
void rbamp_energy_reset_all_ch(rbamp_energy_t *e);
static inline void rbamp_energy_set_enabled(rbamp_energy_t *e, bool en);
| Funktion | Beschreibung |
|---|---|
rbamp_energy_init |
Zähler auf null setzen; der Akkumulator startet aktiviert. |
rbamp_energy_tick |
Eine Periode integrieren: wh[ch] += avg_p[ch] × period_ms / 1000 / 3600 für bis zu RBAMP_ENERGY_MAX_CH (7) Kanäle. Wird stillschweigend übersprungen, wenn valid false ist, period_ms 0 ist oder der Akkumulator deaktiviert ist. period_ms muss das Fenster der Master-Wanduhr sein (master_dt_ms), nicht das latch_ms des Moduls. |
rbamp_energy_wh_get |
Laufende Summe eines Kanals; 0, wenn außerhalb des Bereichs. |
rbamp_energy_add_wh |
Fügt eine bereits gemessene Menge (Wh, vorzeichenbehaftet) einem Kanal oder, mit RBAMP_ENERGY_CH_TOTAL, der Gesamtsumme aller Kanäle hinzu. Wird verwendet, wenn das Modul Energiezähler selbst veröffentlicht. Ohne Wirkung, solange deaktiviert. |
rbamp_energy_reset_ch / rbamp_energy_reset_all_ch |
Einen Kanal / alle Kanäle auf null setzen. |
rbamp_energy_set_enabled |
Integration ein- oder ausschalten. Im ausgeschalteten Zustand tun tick() und add_wh() nichts, und Lesevorgänge liefern weiter den eingefrorenen Wert. |
Identifikation und Provisionierung
Diese Funktionen erlauben dem Master herauszufinden, was genau am Bus angeschlossen ist (Variante, Fähigkeits-Bitmap, UID), und ein neues oder frisch geflashtes Modul für den Betrieb vorzubereiten (Bereitstellung + Speichern der Konfiguration im Flash).
rbamp_read_variant
Automatische Erkennung der Modulvariante (initialization) · rbAmp-Drahtprotokoll-Referenz (v1.3) (api-reference) · 3.6 Kanonischer Erkennungsalgorithmus (api-reference)
esp_err_t rbamp_read_variant(rbamp_handle_t dev, rbamp_variant_t *out);
Liest das Variantenregister und bildet es auf die Enum rbamp_variant_t ab (RBAMP_VARIANT_UI1 / _I1 / _I2 / _I3, _UI5, _UI7, ...; jeder bekannte Code wird abgebildet). Für Kompatibilität mit älterem Code, der das „rohe“ Byte liest, können Sie es zurück in uint8_t casten. Der aus rbamp_begin() zwischengespeicherte Wert ist ohne Bus-Verkehr als rbamp_variant() verfügbar. Werte:
| Code | SKU | I-Kanäle | U-Kanal |
|---|---|---|---|
1 |
UI1 | 1 | ja |
2 |
UI2 | 2 | ja |
3 |
UI3 | 3 | ja |
4 |
I1 | 1 | nein |
5 |
I2 | 2 | nein |
6 |
I3 | 3 | nein |
7 |
UI5 | 5 | ja |
8 |
UI7 | 7 | ja |
Der Wert ist schreibgeschützt, im ROM gespeichert und ändert sich nur durch ein Neuflashen mit der Werkssoftware.
rbamp_read_capability
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)
esp_err_t rbamp_read_capability(rbamp_handle_t dev, uint16_t *out);
Liest die Fähigkeitskarte aus den Registern CAPABILITY (0x57/0x58), LE u16. Ein Flag zeigt das Vorhandensein eines Spannungsfrontends an: Ist es gelöscht, berechnet das Modul P / PF / Q nicht, und die Werte dieser Register sind 0.0f. Siehe den Abschnitt «CAPABILITY (0x57/0x58, u16 LE) — Karte zur Funktionserkennung» unten.
rbamp_has_voltage
bool rbamp_has_voltage(rbamp_handle_t dev);
Eine Komforthilfe über rbamp_read_capability — liefert true, wenn das Modul einen U-Kanal hat (also (cap >> 8) & 1). Beim ersten Aufruf wird es im Handle zwischengespeichert; spätere Aufrufe führen keine I²C-Operation aus.
rbamp_read_product_id
3.5 PRODUCT_ID (0x54, u8, nur lesbar) (api-reference) · 4.8 Identität (0x54..0x6F) (api-reference)
esp_err_t rbamp_read_product_id(rbamp_handle_t dev, uint8_t *out);
Liest PRODUCT_ID (0x54) — ein Byte-Kennzeichen der Familie (rbAmp = 0x01). Wird vom Flottenscanner verwendet, um zu bestätigen, dass das Gerät an einer Adresse wirklich ein rbAmp ist und nicht ein anderer I²C-Slave, der zufällig an derselben Adresse antwortet.
rbamp_read_uid
esp_err_t rbamp_read_uid(rbamp_handle_t dev, uint8_t uid[12]);
Liest die 96-Bit-eindeutige MCU-Kennung aus UID (0x5C..0x67) in einem einzigen Burst-Vorgang. Die UID ist je Modul eindeutig und ändert sich nicht beim Neuflashen — praktisch für serielle Logs, Anti-Klon-Prüfungen auf der Master-Seite und zur Identifikation beim Austausch eines Moduls in einer installierten Flotte.
rbamp_is_provisioned
esp_err_t rbamp_is_provisioned(rbamp_handle_t dev, bool *out);
Prüft, ob das Modul die anfängliche Provisionierung durchlaufen hat. Technisch wird REG_ERROR != 0xFB (ERR_FLASH_PARAMS_BAD) auf einem frisch gestarteten Modul geprüft — 0xFB setzt die Firmware, wenn der Benutzerkonfigurationsblock leer oder beschädigt ist. Ein frisch ab Werk gelieferte Modul liefert false — es braucht rbamp_save_user_config (oder die Provisionierung über die Flotte) nach der ersten Einrichtung von CT-Modell und Adresse.
Auf v1.3 ist dieser Code für ein jungfräuliches Modul normal (nicht fatal). Brechen Sie die Provisionierung beim ersten Auftreten von 0xFB nicht ab.
STD-Linie. Liefert true, wenn das Modul meldet, dass seine Kalibrierseite gültig ist. Ab Modul-Image-Version 0x00010079 zuverlässig; ältere Images setzen das Bit auch bei Werksverstärkungen, daher lässt sich „provisioniert“ von „unkalibriert“ über diesen Aufruf nicht unterscheiden (nutzen Sie stattdessen die Kalibrierquelle in rbamp_std_read_health()). Ab Modul-Image-Version 0x0001007A stammt das Bit von einer Marke, die das Modul beim Speichern der Kalibrierung schreibt: Ein unter älterer Firmware kalibriertes Gerät liefert nach dem Update false, bis einmal rbamp_save_gains() darauf ausgeführt wurde (seine Kalibrierung selbst ist intakt).
rbamp_save_user_config
6.5 Provisionierung — frisches Flashen + SAVE (API-Referenz) · 8.6 Provisionierung nach frischem Flashen (API-Referenz)
esp_err_t rbamp_save_user_config(rbamp_handle_t dev);
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 nicht die werkseitigen Kalibrierparameter (Verstärkung, NF, Phase) — dafür gibt es CMD_SAVE_GAINS, das im Produktionsmodus gesperrt ist.
Es blockiert den Thread für ~700 ms (Flash-Löschung und Schreibzyklus). Während des Aufrufs dürfen andere Tasks nicht auf das Modul zugreifen.
Returns:
ESP_OK— Konfiguration gespeichert, übersteht einen Stromausfall.-
ESP_ERR_TIMEOUT— das Modul hat nicht rechtzeitig geantwortet; die Versorgung ist während des Flash-Zyklus möglicherweise abgefallen. Erneut über Reset + Rücklesen prüfen. -
ESP_FAIL— das Modul hat nach dem BefehlREG_ERROR != OKzurückgegeben. Details überrbamp_read_last_errorprüfen.
: Dass ein Wert in den Flash geschrieben wurde, bestätigen Sie nur mit einem Neustart + erneutem Lesen. Siehe den Abschnitt Fehlermodell v1.3 unten und 03 · Auswahl des Stromsensors.
rbamp_read_active_address
esp_err_t rbamp_read_active_address(rbamp_handle_t dev, uint8_t *out);
Liest die aktive I²C-Adresse des Moduls. Beim Booten ist dieses Register zuverlässig — es liest die im Flash aktive Adresse (ein neu adressiertes Modul liest seine neue Adresse). Nach dem Vormerken eines Kandidaten mit rbamp_prepare_address_change() gibt es den Kandidaten zurück, bis Commit + Reset erfolgt. Nützlich, um einen zweiphasigen Adresswechsel nach dem Neustart nach dem Commit zu prüfen. Auf der STD-Linie liest es die gespeicherte Adresse (wirkt beim nächsten Reset).
Fehlermodell v1.3
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 | Prüfung innerhalb der Komponente (Bibliothek) | REG_ERROR (0x02) + EVENT_FLAGS.bit3 (0x2A) |
| Wann er auslöst | Vor der I²C-Transaktion (Bibliothek fängt ab) | Nachdem die Firmware einen Schreibvorgang angenommen und dann abgelehnt hat |
| Was der Master sieht | ESP_ERR_INVALID_ARG aus dem Setter; REG_ERROR bleibt 0x00 |
REG_ERROR = der unmittelbare Ablehnungscode; bit3 wird einige hundert Millisekunden nach der Transaktion gesetzt |
| Dauerhaft | nein (nur ein Rückgabecode) | REG_ERROR letzter Schreibvorgang; bit3 klebrig W1C |
| Typischer Weg | Argument außerhalb der zulässigen Grenzen (Kanal ≥ rbamp_channels(dev), unbekannte Klasse, …) |
Roher Registerschreibvorgang, den die Komponente nicht vorprüft (ein eigener Schreibzugriff auf niedriger Ebene); ein unbekanntes CT-Modell, das das Modul selbst ablehnt |
Kanal A — clientseitige Prüfung (Komponenten-Setter)
Alle Komponenten-Setter (rbamp_set_sensor_class, rbamp_set_ct_model_ch, rbamp_configure_channels usw.) prüfen zuerst die Argumente gegen die zulässigen Werte. Liegt ein Argument außerhalb des Bereichs, liefert der Setter ESP_ERR_INVALID_ARG ohne überhaupt eine I²C-Transaktion durchzuführen. Entsprechend wird REG_ERROR auf dem Gerät nicht berührt:
esp_err_t err = rbamp_set_ct_model_ch(dev, /*channel=*/99, /*code=*/3);
/* err == ESP_ERR_INVALID_ARG (lib client-side validation) */
uint8_t reg_err;
rbamp_read_last_error(dev, ®_err);
/* reg_err == 0x00 — REG_ERROR untouched, lib intercepted before I²C */
Das bedeutet: Wenn Sie genau wissen wollen, warum ein Setter etwas abgelehnt hat, ist die verlässliche Quelle der Rückgabewert der Funktion plus die Prüfung Ihres eigenen Arguments. REG_ERROR sagt in diesem Szenario nichts aus (die nächste erfolgreiche Transaktion setzt es).
Kanal B — Ablehnung auf Seiten des DUT (dauerhaft, asynchron)
Wenn ein Schreibvorgang über I²C ging (die Bibliothek ihn nicht abgefangen hat, weil das Argument gültig aussah), die Firmware ihn aber abgelehnt hat, greift der zweite Kanal:
-
REG_ERROR (0x02)enthält sofort den Grundcode (z. B.0xFE = ERR_PARAM). Das ist das Ergebnis des letzten Schreibvorgangs: Jeder spätere erfolgreiche Schreibvorgang überschreibt es. Sie müssen es unmittelbar nach Ihrem eigenen Schreibvorgang lesen, vor jeder anderen Transaktion. -
EVENT_FLAGS.bit3(rbamp_has_error) — klebriges W1C. Es rastet nicht sofort ein: Auf dem Prüfstand wurde zwischen der abgelehnten Transaktion und dem Setzen von bit3 eine Verzögerung von einigen hundert Millisekunden gemessen. Direkt nach dem Schreiben ist bit3 noch0; nach 300 ms ist es1. Danach bleibtbit3bei beliebig vielen Lesevorgängen erhalten.
Ausgabe am Bench (rohes Schreiben DIGEST_CONFIG = 0xFF):
raw write 0x29=0xFF → read_last_error → REG_ERROR=0xFE (immediate)
has_error(bit3): immediate=0, +300 ms poll#1=1, poll#2=1
⚠ Verwenden Sie has_error nicht, um einen gerade ausgeführten Schreibvorgang zu prüfen. Für das Ergebnis genau dieses Schreibvorgangs ist nur rbamp_read_last_error, unmittelbar nach dem Schreiben und vor jeder anderen Transaktion gelesen, zuverlässig (dazu der Rückgabecode des Setters, falls vorhanden). has_error ist ein asynchroner Kanal für Monitoring per Abfrage, um zu erkennen, ob zwischen zwei Prüfungen ein Fehler aufgetreten ist — nicht für eine synchrone Prüfung.
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 neu übernommen. Ein einfaches clear_event_flags(1<<3) funktioniert daher nicht — bit3 wird sofort wieder gesetzt, weil REG_ERROR noch nicht gelöscht ist:
state: REG_ERROR=0xFE, bit3=1
clear_event_flags(1<<3) → bit3=1 still (re-latched from REG_ERROR=0xFE)
clear_error + clear_event_flags(1<<3)
→ bit3=0 (cleared cleanly)
Die richtige Reihenfolge: zuerst rbamp_clear_error() (löscht REG_ERROR), dann rbamp_clear_event_flags(1<<3) (löscht das dauerhafte Latch). Soll es atomar sein, darf zwischen beiden kein abgelehnter Schreibvorgang liegen.
rbamp_read_last_error
3. DATA_VALID (0xCE) wird nie 1 (troubleshooting) · Fehlercodes (REG_ERROR = 0x02) (troubleshooting) · 4 · Registerkarte (Produktion v1.3) (api-reference)
esp_err_t rbamp_read_last_error(rbamp_handle_t dev, uint8_t *out);
Liest REG_ERROR (0x02) direkt — das Ergebnis der letzten vom Bus akzeptierten Transaktion (ein Schreibvorgang oder Befehl). Nicht dauerhaft: jeder nachfolgende erfolgreiche Schreibvorgang überschreibt es mit seinem eigenen Ergebnis.
Verwendet in Kanal B (Ablehnung auf Seiten des Prüflings) für den erweiterten Grundcode.
rbamp_has_error
esp_err_t rbamp_has_error(rbamp_handle_t dev, bool *out);
Ein Hilfsaufruf über EVENT_FLAGS.bit3 (ERROR_OCCURRED, Register 0x2A). Liefert true, wenn Bit 3 gesetzt ist. Dauerhaft (sticky), schreib-1-zum-Löschen; wird erst durch ein explizites Löschen zurückgesetzt (mit einem Vorbehalt — siehe den Abschnitt „Clearing a durable error“ oben).
Für Überwachung per Abfrage, ob „etwas fehlgeschlagen ist“ — etwa in langlaufenden Schleifen, in denen Zwischenschreibvorgänge REG_ERROR überschrieben haben könnten, bewahrt bit3 die Tatsache, dass mindestens einer davon abgelehnt wurde.
rbamp_read_event_flags / rbamp_clear_event_flags
esp_err_t rbamp_read_event_flags(rbamp_handle_t dev, uint8_t *out);
esp_err_t rbamp_clear_event_flags(rbamp_handle_t dev, uint8_t mask);
EVENT_FLAGS (0x2A) — ein Byte mit dauerhaften Flags (RBAMP_EVENT_*, siehe Ereignisbits, einschließlich RBAMP_EVENT_ERROR = Bit 3). Das Löschen erfolgt durch Schreiben-1-zum-Löschen: schreiben Sie eine Maske mit Einsen in den Bits, die Sie zurücksetzen wollen. Die Flags wirken auf beiden Linien; auf der Linie STD benötigen sie Version der Registerabbildung 0x36 oder neuer (unten ESP_ERR_NOT_SUPPORTED).
Es hilft, Ursachen zu trennen: Sie können zuerst alle Flags lesen und dann nur die behandelten zurücksetzen; die unbehandelten bleiben für den nächsten Abfragezyklus.
rbamp_clear_error
Fehlercodes (REG_ERROR = 0x02) (troubleshooting) · 6.7 Wiederherstellung nach Fehlerzustand — Entscheidungsbaum (api-reference)
esp_err_t rbamp_clear_error(rbamp_handle_t dev);
Gibt CMD_CLEAR_ERROR (Opcode 0x31) aus — setzt REG_ERROR auf null. Nötig, um einen dauerhaften Fehler zu löschen zusammen mit clear_event_flags(1<<3) (siehe oben). Ohne clear_error bleibt bit3 nach einigen hundert Millisekunden durch das erneute Latchen auf 1, wenn Sie nur clear_event_flags(1<<3) ausführen.
Ereignisse und die Alarmleitung
4.4 Fleet-Konfiguration (0x27..0x2F) (api-reference) · 8.8 Ablauf von Schwellwertereignissen — Schwellwert schreiben → auslösen → W1C-Löschen (api-reference)
Ereignisse bilden ein einheitliches Modell auf beiden Leitungen: dauerhafte Flags (RBAMP_EVENT_*), Schreiben-1-zum-Löschen. Flags, die auch in der Ereignismaske gesetzt sind, halten die Leitung DRDY auf LOW (ein Alarm), bis sie gelöscht oder aus der Maske genommen werden. Maske und Schwellenwerte liegen im RAM des Moduls — nach jedem Reset des Moduls neu scharf schalten (RBAMP_EVENT_RESET_OCCURRED zeigt es an; siehe auch rbamp_begin_event_flags()).
esp_err_t rbamp_read_event_mask (rbamp_handle_t dev, uint8_t *out);
esp_err_t rbamp_set_event_mask (rbamp_handle_t dev, uint8_t mask);
esp_err_t rbamp_set_event_thresholds(rbamp_handle_t dev, float i_amps, float p_watts);
| Funktion | Beschreibung |
|---|---|
rbamp_read_event_mask |
Welche Flags die DRDY-Leitung auf LOW halten (die Alarmklasse). |
rbamp_set_event_mask |
Setzen Sie die Maske (RAM des Moduls; 0 = die Leitung wird nie gehalten). Der Schreibvorgang wird zurückgelesen und geprüft. |
rbamp_set_event_thresholds |
Setzen Sie die Schwellwerte (RAM des Moduls): Der höchste Stromkanal oberhalb von i_amps setzt RBAMP_EVENT_THRESH_I, die Gesamtwirkleistung oberhalb von p_watts setzt RBAMP_EVENT_THRESH_P. Ein Wert <= 0 oder NaN deaktiviert den jeweiligen Schwellwert. Liefert ESP_ERR_NOT_SUPPORTED bei einem STD-Modul mit Registerkarte-Version unter 0x36. |
Der Vergleich unterscheidet sich je Linie. Die STD-Linie vergleicht die absolute Gesamtleistung (die Richtung spielt keine Rolle). Die BASIC-Linie vergleicht die vorzeichenbehaftete Summe der Kanalleistungen, sodass eine Einspeisung nie die Leistungsschwelle auslöst; Werte, die die BASIC-Kodierung nicht aufnehmen kann, gelten als „deaktiviert“. Auf STD benötigt rbamp_read_event_flags() die Registerkarten-Version 0x36 oder neuer (sonst ESP_ERR_NOT_SUPPORTED).
Konfiguration mehrerer Kanäle
Auf Mehrkanal-Modulen (I2, I3, UI2, UI3 sowie die größeren UI5 / UI7) hat jeder Stromkanal ein eigenes CT-Sensormodell. Das atomare Hilfsmittel für die Massenkonfiguration ist rbamp_configure_channels.
rbamp_configure_channels
esp_err_t rbamp_configure_channels(rbamp_handle_t dev,
rbamp_sensor_class_t cls,
const uint8_t *models,
uint8_t n);
Parameters:
cls— die Sensorklasse, zuerst überrbamp_set_sensor_class()angewendet.models— ein Array mitnCT-Modellcodes, einer je Kanal.n— die Länge des Arrays. Auf die Variante begrenzt: Istngrößer als die Kanalanzahl dieser Variante (zum Beispieln=3aufI2), begrenzt die Funktion auf die tatsächliche Kanalanzahl; überzählige Array-Elemente werden ignoriert. Istnkleiner als die Kanalanzahl, bleiben die fehlenden Kanäle unberührt (sie behalten ihr bisheriges Modell). Ein Eintrag0inmodelsüberspringt diesen Kanal. Der Aufruf umfasst alle Kanäle des Moduls, einschließlich Kanäle 3+ auf einem UI5 / UI7.
Intern führt die Funktion aus:
set_sensor_class(cls)einmal.-
Für jeden Kanal
k < min(n, n_channels):models[k]binden; jede Bindung wird synchron geprüft und per Rücklesen bestätigt. -
Ein abschließendes Speichern der Benutzerkonfiguration am Ende (plus das im
set_sensor_class) — also zwei Flash-Lösch- und Schreibzyklen für die gesamte Konfiguration, statt1 + n. Das ist die „flash-schonende“ Eigenschaft.
Erst lesen, dann schreiben. Der gesamte Auftrag wird vor dem ersten Schreibvorgang entschieden. Eine Klasse oder ein Modell, das das Modul bereits hält, wird nicht neu geschrieben, daher kostet das erneute Anwenden derselben Konfiguration nur Lesevorgänge und keinen Flash-Zyklus. Bei einem Modul der Klasse 2 oder 3 wird ein Auftrag, der die Klasse oder ein angefordertes Modell ändern würde, von vornherein mit ESP_ERR_INVALID_STATE abgelehnt, und es wird nichts geschrieben. Bei einem Klasse-1-Modul mit älterer Firmware (bis 1.4.19) endet ein Auftrag, der ein Modell ändert, mit einem Neustart des Moduls (siehe rbamp_set_ct_model_ch).
Returns:
ESP_OK— Konfiguration angewendet und gespeichert.-
ESP_ERR_INVALID_ARG— ungültigesclsodermodels[k](Prüfung beim Bindungsschritt, siehe den Abschnitt „Fehlermodell“ oben). -
ESP_ERR_INVALID_STATE— ein Kanal konnte nicht gebunden werden, oder das Modul ist mit seinem eingebauten Sensor kalibriert (Klasse 2 / 3). -
Andere ESP-IDF-Codes — Busfehler, Timeout usw.
rbamp_read_ct_model_ch
4.7 CT-Modell-Verifikationsspiegel (0x51..0x53) (API-Referenz) · 8.10 Rücklesen des CT-Modell-Verifikationsspiegels (Plausibilität nach der Zuordnung) (API-Referenz)
esp_err_t rbamp_read_ct_model_ch(rbamp_handle_t dev,
uint8_t channel,
uint8_t *out);
Liest das CT-Sensormodell, das tatsächlich angewendet wird, für einen bestimmten Kanal (0 = nicht gesetzt). Verwenden Sie es zur Bindungsprüfung nach rbamp_set_ct_model_ch(). Die Kanäle 0–2 lesen die flachen Spiegel (0x51 / 0x52 / 0x53); Kanäle 3+ (UI5 / UI7) lesen über das Kanalfenster zurück. Das ist ein Lesezugriff auf den RAM, keine Bestätigung der Persistenz — um eine Flash-Speicherung zu bestätigen, verwenden Sie einen Neustart + erneutes Lesen. Auf der STD-Linie liest es den Map-Eintrag des Kanals.
Flotten-Manager — mehrere Module verwalten
Die Fleet-API ist die primäre High-Level-Schnittstelle der Bibliothek. Sie verwaltet eine Sammlung von Modulen an einem gemeinsamen I²C-Bus: Erkennung, Bereitstellung, Aggregation von Abfragen, Aggregation von Fehlern, synchrone Snapshots.
Alle Flottenfunktionen sind über einen internen Mutex threadsicher; gleichzeitige Aufrufe aus verschiedenen Tasks werden serialisiert. Ein einziger Besitzer des fleet aus einer Task plus reiner Lesezugriff (z. B. _count, _get) aus anderen ist zulässig, komplexe mehrstufige Vorgänge sind jedoch ausdrücklich abzustimmen.
Lebenszyklus
esp_err_t rbamp_fleet_create(i2c_master_bus_handle_t bus,
rbamp_fleet_t *out);
void rbamp_fleet_destroy(rbamp_fleet_t fleet);
create nimmt einen Bus entgegen und liefert eine leere Flotte. destroy gibt alle verwalteten Handles und die Flotte selbst frei — danach sind alle über rbamp_fleet_get erhaltenen Handle-Zeiger ungültig.
Erkennung — rbamp_fleet_scan
Einrichtung mehrerer Module (initialization) · Abfrage mehrerer Module — drei Strategien (realtime-polling) · Probleme mit mehreren Modulen (troubleshooting)
esp_err_t rbamp_fleet_scan(rbamp_fleet_t fleet,
bool match_product,
size_t *added);
Sondiert den Bus im Bereich 0x08..0x77; für jede Adresse, die mit ACK antwortet:
-
Prüft die Identität (
PRODUCT_ID,HW_VARIANT,CAPABILITY). Istmatch_product = true, wird eine Übereinstimmung mit der rbAmp-PRODUCT_ID verlangt. -
Führt den Konflikt-Detektor aus (zwei unabhängige Signale; siehe 10 · Fehlerbehebung, Abschnitt „Fleet: a module ended up in excluded“). Verdächtige Adressen wandern in die Liste
excluded, nicht in die Fleet. -
Führt einen Tier-2-Wedge-Canary aus: Es sondiert eine Adresse, an der garantiert niemand sein sollte. Erhält der Canary ein ACK, liefert es
ESP_ERR_INVALID_STATE— der Bus ist blockiert, die Flotte bleibt leer (siehe die Diagnose in Kap. 10).
Nach Erfolg enthält *added die Anzahl der Module, die der Flotte hinzugefügt wurden. excluded_count (siehe unten) ist über einen eigenen Getter verfügbar.
Bench-Ausgabe (HW-validiert an einer heterogenen Flotte UI1+I2+I3 mit externen 4.7-kΩ-Pull-ups):
rbamp_fleet_scan() → 3 module(s), 0 excluded
module[0] @0x50 channels=1 voltage=yes (UI1 — mains)
module[1] @0x51 channels=2 voltage=no (I2 — sub-meter)
module[2] @0x52 channels=3 voltage=no (I3 — sub-meter)
rbamp_fleet_count() = 3
rbamp_fleet_excluded_count() = 0
In diesem Szenario würde ein Adresskonflikt in der Ausschlussliste landen (excluded_count > 0), und ein blockierter Bus würde in ESP_ERR_INVALID_STATE mit einer leeren Flotte enden (siehe 10 · Fehlerbehebung).
Modulzugriff
size_t rbamp_fleet_count(rbamp_fleet_t fleet);
rbamp_handle_t rbamp_fleet_get(rbamp_fleet_t fleet, size_t index);
rbamp_handle_t rbamp_fleet_find(rbamp_fleet_t fleet, uint8_t address);
esp_err_t rbamp_fleet_add(rbamp_fleet_t fleet, rbamp_handle_t dev);
size_t rbamp_fleet_excluded_count(rbamp_fleet_t fleet);
esp_err_t rbamp_fleet_excluded_addr(rbamp_fleet_t fleet,
size_t index,
uint8_t *out);
_get liefert NULL bei einem Wert außerhalb des Bereichs; _find liefert NULL, wenn die Adresse nicht in der Flotte ist (etwa weil sie in die Ausschlussliste geraten ist). _add fügt ein separat erstelltes Handle manuell hinzu (etwa nach einer manuellen Provisionierung).
Abfragen — rbamp_fleet_poll_all
Einrichtung mehrerer Module (initialization) · Abfrage mehrerer Module — drei Strategien (realtime-polling)
esp_err_t rbamp_fleet_poll_all(rbamp_fleet_t fleet,
rbamp_snapshot_t *snaps,
rbamp_fleet_poll_t *status,
size_t capacity,
size_t *n_ok);
Fragt alle Module der Fleet in einem einzigen Aufruf ab. Für jedes Modul wird ein vollständiger RT-Lesevorgang (rbamp_read_all) ausgeführt und das Ergebnis dem entsprechenden Element snaps[i] zugeordnet. Parallel erhält status[i] das Ergebnis je Modul: ESP_OK, ESP_ERR_TIMEOUT (Modul schweigt), ESP_FAIL (Sanity-Ablehnung) usw.
Nach der Rückgabe ist *n_ok die Anzahl der Module, für die ein gültiger Snapshot erhalten wurde (status[i] == ESP_OK).
MISS-resilient: Ein stummes Modul hebt die Abfrage der übrigen nicht auf. Das ist für eine Produktions-Fleet wichtig — der Verlust eines einzelnen Moduls (ein Verdrahtungsfehler, ein Ausfall) darf die gesamte Überwachung nicht lahmlegen.
Aggregation
esp_err_t rbamp_fleet_total_power(rbamp_fleet_t fleet, float *out_w);
esp_err_t rbamp_fleet_total_energy_wh(rbamp_fleet_t fleet, double *out_wh);
esp_err_t rbamp_fleet_poll_errors(rbamp_fleet_t fleet,
uint32_t *error_mask,
size_t *n_errors);
_total_power summiert die Wirkleistung über alle Kanäle aller Module. Auf I-Varianten gibt es keine Wirkleistung → sie tragen 0 bei. In der kanonischen Bereitstellung (UI1 am Netz + I2/I3-Unterzähler) ist das Ergebnis die Wirkleistung des Netzmoduls.
_total_energy_wh summiert ähnlich die Wh-Akkumulatoren der Handles. Auch das funktioniert korrekt: I-Varianten tragen 0 bei, UI1 trägt die Netzenergie bei.
_poll_errors durchläuft die Fleet und ruft rbamp_has_error für jedes Modul auf. *error_mask ist eine Bitmaske der Module mit dem Flag EVENT bit3, nach ihrer Position in der Fleet (aussagekräftig für die ersten 32 Module); *n_errors ist die Gesamtzahl der Module mit einem Fehlerflag zum Zeitpunkt der Abfrage. Beide Zeiger dürfen als NULL übergeben werden, falls nicht benötigt.
Adressierung und Konfliktprüfung
esp_err_t rbamp_fleet_assign_address(rbamp_fleet_t fleet,
rbamp_handle_t dev,
uint8_t new_addr);
esp_err_t rbamp_fleet_check_conflict(rbamp_fleet_t fleet,
uint8_t addr,
bool *collision);
_assign_address versieht ein bestehendes Fleet-Modul mit einer neuen Adresse: intern — zweiphasiger Commit + Reset; das Handle in der Fleet wird automatisch aktualisiert (nachfolgende Aufrufe funktionieren weiter).
_check_conflict — eine nach bestem Bemühen lesende, rein prüfende Kontrolle für eine bestimmte Adresse: einmal pro interessierender Adresse aufrufen. Sie liest die Identität (PRODUCT_ID / HW_VARIANT / CAPABILITY) und vergleicht sie mit dem zwischengespeicherten Zustand der Flotte. Wird eine Inkonsistenz erkannt (zwei Geräte antworten an derselben Adresse mit „verschmolzenen“ Bytes; Identität weicht vom zwischengespeicherten Zustand ab) — *collision = true. Um alle bekannten Adressen zu prüfen, durchlaufen Sie die Flotte selbst: for i in 0..count, check_conflict(fleet, addr, &col). Es garantiert nicht, identische Module zu erkennen — siehe die Provisionierungsdisziplin.
Provisionierung — rbamp_provision
6.5 Provisionierung — frisches Flashen + SAVE (API-Referenz)
esp_err_t rbamp_provision(i2c_master_bus_handle_t bus,
uint8_t desired_addr,
bool save_config,
rbamp_handle_t *out);
Stellt genau ein neues Modul (auf Werks-0x50) auf die angegebene Adresse ein. Intern:
-
Prüft, ob eine Antwort bei
0x50vorliegt (ESP_ERR_NOT_FOUND, wenn nicht). -
Prüft, dass niemand an
desired_addrantwortet (ESP_ERR_INVALID_STATE, wenn die Adresse belegt ist). -
Führt einen zweiphasigen Adress-Commit durch.
-
Setzt das Modul zurück und wartet, bis es im Bootfenster unter
desired_addrerscheint (ESP_ERR_TIMEOUT, wenn nicht). -
Erzeugt ein Handle; bei
save_config = truewirdrbamp_save_user_configaufgerufen (Persistierung im Flash). -
Liefert das fertige Handle über
*out.
⚠ MUSS: genau ein jungfräuliches Modul am Bus im Moment des Aufrufs. Zwei Module auf 0x50 gleichzeitig sind über I²C physisch nicht zu unterscheiden — auch mit Spezialhardware nicht. Die Garantie liegt beim Bediener, nicht bei der Bibliothek. Zur Wiederherstellung siehe 10 · Fehlerbehebung, Abschnitt „Flotte: rbamp_provision hat einen Fehler zurückgegeben“.
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)
esp_err_t rbamp_fleet_enable_gc_all(rbamp_fleet_t fleet,
uint8_t group,
size_t *ok_count);
esp_err_t rbamp_fleet_gclatch(rbamp_fleet_t fleet,
uint8_t group,
uint16_t tick,
uint32_t settle_ms);
esp_err_t rbamp_fleet_check_sync(rbamp_fleet_t fleet,
uint16_t expected_tick,
rbamp_fleet_sync_t *status,
size_t status_cap,
size_t *n_missed);
Für eine enge Snapshot-Synchronität (Schiefe < 1 ms über die gesamte Flotte) wird ein I²C-General-Call-Broadcast-Snapshot verwendet.
-
_enable_gc_allsetztFLEET_CONFIG.bit0+GROUP_IDauf allen Modulen der Flotte und sendetCMD_SAVE_USER_CONFIGan jedes (dauerhaft). Ein Neustart der Module ist nach der Aktivierung zwingend — dies geschieht automatisch. Ein einmaliger Aufruf bei der ersten Flotteneinrichtung genügt.*ok_count(optional) ist die Anzahl der Module, bei denen die Aktivierung erfolgreich war. -
_gclatchsendet den GC-RahmenA5 27 group tick_lo tick_hian die Adresse0x00— alle Module mit aktiviertem GC und passendemgroupnehmen sofort den Snapshot (LATCH_PERIOD).settle_msist die Pause nach dem Rahmen (typisch 50 ms) vor der Prüfung. -
_check_syncliestGC_TICK (0x59)jedes Moduls inrbamp_fleet_sync_t status[status_cap]. Das Ergebnis je Modul:
typedef struct {
uint8_t addr; /* module I²C address */
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 */
} rbamp_fleet_sync_t;
*n_missed ist die Anzahl der Module mit in_sync = false (oder die schlicht nicht antworten). Sind alle in_sync, gilt n_missed == 0.
Verwechseln Sie sie nicht: Das geräteweise rbamp_broadcast_latch (siehe Abschnitt „Multi-Modul-Bus“ unten) ist ein Rahmen über den gesamten Bus; die Flotten-GC-Synchronisation ist derselbe Rahmen, aber die Flotten-API bietet zusätzlich eine Zeugenprüfung (dass er bei allen erwarteten Modulen angekommen ist). Siehe auch 04 · Verdrahtung zu den GC-Voraussetzungen.
Fleet-Konfiguration je Gerät
Diese Funktionen arbeiten mit einem einzelnen Modul direkt (ohne Flotte) — für Fälle, in denen Sie ein einzelnes Modul konfigurieren, bevor Sie es einer Flotte hinzufügen, oder feinere Kontrolle wollen.
rbamp_enable_gc / rbamp_read_fleet_config
General Call (Broadcast an Adresse 0x00) (Initialisierung) · 4.4 Flottenkonfiguration (0x27..0x2F) (API-Referenz)
esp_err_t rbamp_enable_gc(rbamp_handle_t dev, bool enable);
esp_err_t rbamp_read_fleet_config(rbamp_handle_t dev, uint8_t *out);
enable_gc(dev, true) schreibt 1 in FLEET_CONFIG.bit0 (0x27) — das Modul akzeptiert GC-Snapshots nach dem nächsten CMD_SAVE_USER_CONFIG + Reset. enable_gc(dev, false) spiegelt das, indem es das Bit löscht (das Modul akzeptiert GC nach dem Reset nicht mehr). read_fleet_config liefert das aktuelle Konfigurationsbyte — nützlich zur Rücklesebestätigung.
rbamp_set_group_id / rbamp_read_group_id
esp_err_t rbamp_set_group_id(rbamp_handle_t dev, uint8_t group_id);
esp_err_t rbamp_read_group_id(rbamp_handle_t dev, uint8_t *out);
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.
rbamp_read_gc_tick
esp_err_t rbamp_read_gc_tick(rbamp_handle_t dev, uint16_t *out);
Liest GC_TICK (0x59) — den letzten Tick-Wert aus einem GC-Frame. Dient der Erkennung verpasster Frames (haben zwei Module unterschiedliche Ticks, hat jemand ein Frame verpasst).
rbamp_read_label / rbamp_write_label
8.3 Mehrbyte-SCHREIBZUGRIFF — LABEL Byte für Byte (api-reference)
esp_err_t rbamp_read_label(rbamp_handle_t dev, char out[9]);
esp_err_t rbamp_write_label(rbamp_handle_t dev, const char *label);
LABEL (0x68..0x6F) — eine benutzerdefinierte 8-Byte-Bezeichnung (ASCII, mit Nullen aufgefüllt). Sie hilft, Module in einer Flotte zu erkennen — etwa "MAINS", "BOILER", "AC1". read_label liefert immer ein 9-Byte-Array (8 Datenbytes + ein abschließendes \0). write_label erwartet eine nullterminierte Zeichenkette — überschüssige Bytes werden abgeschnitten.
Das Schreiben erfolgt Byte für Byte (keine automatische Inkrementierung beim Schreiben — siehe „Register writes“ unten). Nach dem Schreiben brauchen Sie rbamp_save_user_config, damit die Bezeichnung einen Reset übersteht.
rbamp_broadcast_latch_group
esp_err_t rbamp_broadcast_latch_group(i2c_master_bus_handle_t bus,
uint8_t group_id,
uint16_t tick);
Ein Low-Level-Sendevorgang des GC-Rahmens A5 27 group tick_lo tick_hi direkt über das Handle bus (ohne Flotte). Nützlich, wenn die Flotte noch nicht erstellt wurde, oder wenn Sie den Tick-Zähler manuell steuern wollen.
rbamp_reset_counters
esp_err_t rbamp_reset_counters(rbamp_handle_t dev);
Setzt die Diagnosezähler des Moduls zurück (Anzahl der I²C-Fehler, Anzahl der Neuinitialisierungen der Peripherie). Es betrifft weder die Benutzerkonfiguration noch die Kalibrierung. Verwendet für Bench-Tests und periodische Zählerrücksetzungen bei langen Produktionsdauertests.
Sensorkonfiguration
Ein zweistufiger Ablauf: zuerst die Sensorklasse, dann das Modell. Beide Schritte sind erforderlich bei einem Modul mit einem vom Anwender montierten Sensor (Klasse 1). Module, die mit ihrem Sensor ausgeliefert werden (Klasse 2 / 3), kommen bereits konfiguriert an und sind gegen versehentliches Überschreiben geschützt — siehe die Hinweise zum Lesen-vor-Schreiben weiter unten.
Einen ausführlichen Leitfaden zur Modellauswahl finden Sie in 03 · Auswahl des Stromsensors.
rbamp_set_sensor_class
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)
esp_err_t rbamp_set_sensor_class(rbamp_handle_t dev,
rbamp_sensor_class_t cls);
Setzt die Sensorklasse und speichert sie dauerhaft.
Erst lesen, dann schreiben. Die Funktion liest zuerst die Klasse, die das Modul hält. Den bereits gehaltenen Wert zu schreiben ist ein No-op ohne Busschreibvorgang (ESP_OK) — auf dem Modul löscht jeder Klassenschreibvorgang, auch ein unveränderter, das CT-Modell und die Kalibrierform jedes Kanals, daher würde ein unnötiger Schreibvorgang die Messwerte verschlechtern. Ein Modul, dessen Klasse 2 oder 3 ist (zusammen mit dem angepassten Sensor kalibriert), wird nicht neu geschrieben: ESP_ERR_INVALID_STATE.
Andernfalls schreibt sie die Klasse, prüft, ob das Modul sie angenommen hat, und speichert sie mit dem Speichern der Benutzerkonfiguration (~700 ms, blockierend). Das Setzen der Klasse löscht außerdem die CT-Modelle auf dem Modul, daher Modelle danach setzen.
Ab Firmware v1.2+ ist eine gesetzte Klasse Voraussetzung für rbamp_set_ct_model() und rbamp_set_ct_model_ch() — ein Aufruf eines der beiden, solange die Klasse noch RBAMP_SENSOR_UNSET ist, liefert ESP_ERR_INVALID_STATE. Siehe 10 · Fehlerbehebung, Abschnitt „Strom liest null“, zum Symptom „versehentlich UNSET geschrieben“.
Rückgabe: ESP_OK bei Erfolg oder wenn das Modul diese Klasse bereits hält; ESP_ERR_INVALID_ARG bei dev == NULL, einem nicht erkannten cls oder wenn das Modul den Schreibvorgang ablehnt; ESP_ERR_INVALID_STATE, wenn die aktuelle Klasse des Moduls 2 oder 3 ist; I²C-Fehlercodes bei einem Verbindungsausfall.
STD-Linie. Schreibt die Klasse als Metadatum (die STD-Linie hat keine Preset-Tabelle) und speichert sie; das Befehlsurteil des Moduls wird geprüft.
rbamp_set_ct_model
esp_err_t rbamp_set_ct_model(rbamp_handle_t dev, uint8_t code);
Die Einzelparameter-Form — setzt das CT-Modell nur auf Kanal 0 (entspricht rbamp_set_ct_model_ch(dev, 0, code); auf der STD-Linie ist es dieser Aufruf). Blockierend, ~700 ms beim Schreiben.
Der zulässige Modellsatz für die aktive Klasse ist die Laufzeitwahrheit der Firmware — die Bibliothek führt keine clientseitige Liste der Codes. Ein unbekanntes Paar (class, model) wird vom Modul abgelehnt und als ESP_ERR_INVALID_STATE gemeldet (oder als ESP_ERR_INVALID_ARG aus der synchronen Prüfung des Schreibvorgangs). Modellcodes und Namen stehen in der generierten rbamp_sensor_models.h (rbamp_sensor_model_lookup()); für Klasse 1:
code |
Modell |
|---|---|
| 1 | SCT-013-005 |
| 2 | SCT-013-010 |
| 3 | SCT-013-030 |
| 4 | SCT-013-050 |
| 5 | SCT-013-100 |
| 6 | SCT-013-020 |
| 7 | SCT-013-060 |
(Alle sieben SCT-013-Codes sind wählbar; der zulässige Satz ist {1, 2, 3, 4, 5, 6, 7}.)
rbamp_set_sensor_class() muss zuerst aufgerufen worden sein (sonst ESP_ERR_INVALID_STATE, kein Schreiben). Der Schutz durch Lesen-vor-Schreiben von rbamp_set_ct_model_ch() gilt ebenfalls.
Für Mehrkanal-Module verwenden Sie die kanalbezogene Form unten.
rbamp_set_ct_model_ch
Festlegen von Sensorklasse und CT-Modell (initialization) · 6.2 CT-Modell-Bindung — reine Vorbereitung + CMD je Kanal (api-reference)
esp_err_t rbamp_set_ct_model_ch(rbamp_handle_t dev,
uint8_t channel, uint8_t code);
Die Form je Kanal. Ein öffentlicher Aufruf für jeden Kanal; das Routing ist intern: Kanäle 0–2 stellen das Modell bereit und wenden es mit dem Befehl je Kanal an, Kanäle 3+ (UI5 / UI7, Firmware v1.4.18+) wenden es über das Kanalfenster an. In beiden Fällen wird das angewandte Modell per Rücklesen bestätigt und dann gespeichert (~700 ms). channel wird gegen die tatsächliche Kanalanzahl des Moduls geprüft.
Die Bindungsreihenfolge ist beliebig (v1.3-Kanon). Die CT-Bindung ist reines Staging: Jede kanalweise Anwendung bindet nur ihren eigenen Kanal, daher können Kanäle in beliebiger Reihenfolge konfiguriert werden — aufsteigend, absteigend oder verschachtelt — ohne sich gegenseitig zu überschreiben:
rbamp_set_ct_model_ch(dev, 0, 1); /* channel 0 = SCT-013-005 */
rbamp_set_ct_model_ch(dev, 1, 3); /* channel 1 = SCT-013-030 */
rbamp_set_ct_model_ch(dev, 2, 6); /* channel 2 = SCT-013-020 */
rbamp_set_ct_model_ch(dev, 4, 3); /* channel 4 (UI5 / UI7) */
Schutz durch Lesen-vor-Schreiben. Das Anwenden eines Modells ersetzt die Kalibrierung, die das Gerät für diesen Kanal trägt, durch die generische Voreinstellung des Modells — und das Modul tut das auch dann, wenn sich das Modell nicht ändert. Deshalb gilt:
-
das Modell, das der Kanal bereits hält (siehe
rbamp_read_ct_model_ch()), ist ein No-op ohne Busschreibvorgang — das erneute Anwenden einer gespeicherten Konfiguration bei jedem Wiederverbinden ist sicher und verursacht keinen unnötigen Modul-Neustart; -
ein Modul der Klasse 2 oder 3 liefert
ESP_ERR_INVALID_STATE;rbamp_set_ct_model_ch_force()ist der Service-Pfad.
Modul-Neustart bei älterer Klasse-1-Firmware. Auf einem BASIC-Modul der Klasse 1 ohne die Selbstkorrektur-Fähigkeit (Firmware bis 1.4.19) endet ein Aufruf, der das Modell tatsächlich ändert, mit einem Modul-Neustart (etwa eine Sekunde, dieselbe UID verifiziert): Das ist der einzige Weg, auf dem das Modul nach einem Modellschreibvorgang zu seiner kalibrierten Verstärkung zurückkehrt. Die Bibliothek wertet dann die Nennwertkorrektur (rbamp_sct_correction()) aus und skaliert die Messwerte aus der Verstärkung, die das Modul anwendet. Der RAM-Zustand des Moduls (Digest-Felder, Ereignismaske, Schwellwerte) wird von der Bibliothek dort neu angewendet, wo sie ihn verwaltet; die Periodenakkumulatoren starten neu, wie nach jedem Modul-Reset.
Rückgabewerte: ESP_OK; ESP_ERR_INVALID_ARG bei dev == NULL oder channel >= rbamp_channels(dev); ESP_ERR_NOT_SUPPORTED bei Firmware älter als v1.2 (Kanäle 0–2) oder auf einem STD-Modul, das kein CT-Modell je Kanal speichert; ESP_ERR_INVALID_STATE, wenn die Klasse UNSET ist, das Modul das Paar (class, model) ablehnt, das angewandte Modell die Rücklesebestätigung nicht besteht oder das Modul Klasse 2 / 3 ist; ESP_FAIL / ESP_ERR_TIMEOUT bei einem Transportfehler.
STD-Linie. Das CT-Modell ist nur ein Verweis (SKU-Metadaten): Es setzt keine Verstärkung — das Modul trägt seine eigene Kalibrierung je Kanal. Bei der aktuellen Firmware für Ein-Kanal-Module überlebt nach einem Reset nur das Modell von Kanal 0.
rbamp_set_ct_model_ch_force
esp_err_t rbamp_set_ct_model_ch_force(rbamp_handle_t dev,
uint8_t channel, uint8_t code);
Der Service-Pfad: wie rbamp_set_ct_model_ch(), schreibt aber unabhängig von der Klasse des Moduls und vom aktuell gehaltenen Modell. Er ersetzt die gepaarte Kalibrierung dieses Kanals durch das generische Preset des Modells — nur verwenden, wenn ein Modul im Service mit einem neuen Sensor neu gepaart wird, und danach eine Kalibrierung durchführen.
rbamp_read_sensor_class
esp_err_t rbamp_read_sensor_class(rbamp_handle_t dev, uint8_t *out);
Die aktuelle Sensorklasse des Moduls als rbamp_sensor_class_t-Wert (BASIC: das Klassenregister; STD: das Klassenfeld der Konfiguration).
Grenzwerte der Sensormodelle
bool rbamp_sensor_model_limits (uint8_t sensor_class, uint8_t code,
float *nominal_a, float *fs_a, float *peak_a);
float rbamp_sensor_model_rated_a(uint8_t sensor_class, uint8_t code);
Reine Nachschlagewerte in der generierten Modellregistrierung (rbamp_sensor_models.h) — kein Busverkehr.
-
rbamp_sensor_model_limitsfüllt (jede Ausgabe darfNULLsein):nominal_a— der Nennstrom-Effektivwert, A;fs_a— der Effektivstrom, bei dem eine Sinuswelle zu übersteuern beginnt, A;peak_a— die momentane Übersteuerungsgrenze, A (eine verzerrte Last übersteuert beipeak_ageteilt durch ihren Scheitelfaktor).0bedeutet unbekannt für dieses Modell (ältere Ringkern- / Burden-Codes). Lieferttrue, wenn das Paar(class, code)in der Registrierung steht, sonstfalse(die Ausgaben sind dann 0). -
rbamp_sensor_model_rated_aist die Kurzform fürnominal_a. Es ist die Nennleistung des Sensors, die von den Ampere im Modellnamen abweichen kann (die Zange „5 A“ ist für 4.6 A bemessen). Für den Modellnamen verwenden Sierbamp_sensor_model_lookup().
Ein Treffer in der Registry bedeutet nicht, dass das angeschlossene Modul den Code akzeptiert — das ist die Wahrheit zur Laufzeit.
Korrektur der SCT-013-Nennwerte
Ein BASIC-Modul der Sensorklasse 1 wird werksseitig mit dem 30-A-Sensor (Modell 3) kalibriert. Bei Firmware bis 1.4.19 bleibt nach einem Neustart nach einem Wechsel auf ein anderes Modell die 30-A-Kalibrierung aktiv, sodass ein größerer Sensor zu niedrig misst. Ein Modul, das die Fähigkeit zur Selbstkorrektur meldet (Firmware 1.4.20 und neuer), korrigiert sich selbst und braucht nichts davon.
Für die ältere Firmware liest die Bibliothek die Verstärkung, die das Modul tatsächlich anwendet — bei rbamp_begin(), nach einem Modellschreiben und nach jedem erkannten Neustart des Moduls — und skaliert Strom, Spitzenstrom, Wirkleistung, periodengemittelte Leistung, die integrierte Energie, den Digest und die Ereignisschwellen aus dieser Verstärkung und dem gewählten Modell. Spannung und Leistungsfaktor werden nicht skaliert. Das Ergebnis je Kanal ist rbamp_sct_status_t (siehe Typen). Eine Verstärkung, die noch dem rohen Voreinstellungswert entspricht (das Modell wurde in diesem Start gewechselt, ohne Neustart), löst einen Neustart des Moduls aus; eine unerwartete angewandte Verstärkung, ein unbekanntes Modell oder eine rohe Voreinstellung, die den Neustart überlebt, lassen die Messwerte unskaliert mit einer Warnung im Log. CONFIG_RBAMP_SCT_RATING_CORRECTION (Standard: an) schaltet den Mechanismus ab; dann liefert das Modul seine Rohwerte.
esp_err_t rbamp_sct_correction(rbamp_handle_t dev, uint8_t ch,
rbamp_sct_correction_t *out);
esp_err_t rbamp_sct_refresh (rbamp_handle_t dev);
| Funktion | Beschreibung |
|---|---|
rbamp_sct_correction(dev, ch, &c) |
Die zwischengespeicherte Korrektur von Kanal ch — kein Bus-Verkehr. Wird von rbamp_begin(), von rbamp_set_ct_model*() und nach einem erkannten Neustart des Moduls bewertet (ein gelöschtes RESET_OCCURRED, ein ausstehender RESET im Digest, eine sinkende Laufzeit). ESP_ERR_NOT_SUPPORTED auf der Linie STD. |
rbamp_sct_refresh(dev) |
Klasse, Modelle und angewandte Verstärkungen jetzt neu lesen und die Skalierung neu berechnen. Löst einen Modul-Neustart aus (und prüft das Modul erneut, UID verifiziert), wenn die angewandte Verstärkung eines Kanals noch die Rohvoreinstellung eines anderen Modells als des 30-A-Modells ist. Wird intern bei Bedarf aufgerufen; für einen Host bereitgestellt, der weiß, dass das Modul auf andere Weise neu gestartet wurde. Ein No-op, das ESP_OK liefert, auf der Modulreihe STD und auf einem selbstkorrigierenden Modul. |
rbamp_save_gains
esp_err_t rbamp_save_gains(rbamp_handle_t dev);
Ein „nacktes“ CMD_SAVE_GAINS-Schreiben ohne begleitende Registeränderungen.
⚠ Wird normalerweise innerhalb der Komponente aufgerufen. Ein nacktes rbamp_save_gains() ist NUR angemessen, wenn der Aufrufer manuell auf nicht öffentliche Kalibrierregister über direkten Buszugriff geschrieben hat — dies ist ein Vorgang außerhalb der Garantie, der die SKU-spezifische Preset-Tabelle umgeht. Falsche Werte erzeugen falsche Strom- und Leistungsmesswerte ohne ausdrückliche Warnung. Jeder Aufruf führt einen Flash-Lösch- und Schreibzyklus aus (~700 ms); die Flash-Lebensdauer ist begrenzt (~10000 Zyklen je Seite) — nicht in einer Schleife aufrufen.
Linie STD. Löst das Speichern der Kalibrierung aus (speichert den Kalibrierblock: Verstärkungen, Rausch- und THD-Grundwerte) und prüft das Ergebnis des Befehls.
rbamp_prepare_address_change / rbamp_commit_address_change
Adressänderung (Initialisierung) · 4.5 Adresse (0x30..0x31) (API-Referenz) · 6.1 Adressänderung — zweiphasiger Commit (produktionstauglich) (API-Referenz)
Die Änderung der I²C-Adresse des Moduls erfolgt im Produktionsmodus über einen zweiphasigen Commit. Die Firmware schließt die Adresse bewusst aus dem allgemeinen Ablauf CMD_SAVE_USER_CONFIG / CMD_SAVE_GAINS aus — eine Änderung erfordert eine eigene, durch Magic-Wert scharfgeschaltete Sequenz.
esp_err_t rbamp_prepare_address_change(rbamp_handle_t dev,
uint8_t new_addr);
esp_err_t rbamp_commit_address_change(rbamp_handle_t dev);
Drahtprotokoll im Hintergrund:
-
prepare: Bereich vonnew_addrprüfen (0x08..0x77, ≠ aktuell) →new_addrinREG_I2C_ADDRESS(0x30) schreiben — das landet im RAM. -
prepare: schreiben Sie0xA5nachREG_ADDR_COMMIT_MAGIC(0x31) — dies „scharf stellt“ den Commit. Das Fenster im scharfen Zustand dauert 5 Sekunden. -
commit: Scharfstellung auf Aktualität prüfen →CMD_COMMIT_ADDRsenden (Opcode 0x30) → im Flash speichern →CMD_RESET -
~400 ms Boot → internes Adressfeld des Handles aktualisieren.
Nach einem erfolgreichen commit richten sich alle Aufrufe auf dieser Handle-Instanz an die neue Adresse. Der Vorgang funktioniert im Produktionsmodus (nicht gesperrt), was den Austausch von Ersatzmodulen im Feld ermöglicht.
⚠ Wenn das scharf gestellte Fenster (5 s) abgelaufen ist — commit liefert ESP_ERR_TIMEOUT, das Scharfstell-Flag wird gelöscht, und Sie müssen mit prepare neu beginnen.
Linie STD. Die Adressänderung ist synchron, und das Handle wird erst umgeschaltet, wenn ein Modul unter der neuen Adresse antwortet — siehe rbamp_commit_address_change auf der Linie STD. Bei einem Fehlschlag behält das Handle die alte Adresse (ESP_ERR_NOT_FOUND).
⚠ Die Persistenz ist nur nach einem Reset bestätigt. Vor dem Reset kann rbamp_read_* die neuen Werte aus dem RAM liefern, doch der Flash-Schreibvorgang ist möglicherweise noch nicht abgeschlossen. Die Komponente führt beim commit selbst ein eingebautes CMD_RESET + Boot-Wartezeit aus, sodass nach erfolgreicher Rückgabe der Zustand garantiert gespeichert ist.
⚠ Neustart und erneute 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. Nachfolgende Aufrufe auf dieser Handle-Instanz richten sich transparent an die neue Adresse — aber jeder ANDERE Master am Bus (ein Python-Skript, eine ESP-IDF-Komponente auf einem anderen MCU, eine Debug-Sonde) hält das Gerät weiter für unter der alten Adresse, bis sein interner Zustand manuell aktualisiert wird.
rbamp_factory_reset
esp_err_t rbamp_factory_reset(rbamp_handle_t dev);
Der Befehl CMD_FACTORY_RESET (0xAA) + eine Wartezeit von 1500 ms.
⚠ Destruktive Operation. Sie löscht ALLE Flash-Parameter (CT-Modell, Sensorklasse, Kalibrierkoeffizienten, I²C-Adresse). Das Modul kehrt zu den Werkseinstellungen zurück — rbamp_sensor_class_t wird RBAMP_SENSOR_UNSET, REG_CT_MODEL wird 0. Jede zuvor über rbamp_set_sensor_class() / rbamp_set_ct_model*() gesetzte Einstellung verschwindet. Der nächste Benutzer MUSS sowohl rbamp_set_sensor_class() als auch rbamp_set_ct_model*() erneut anwenden, bevor die Abrechnung wieder betriebsbereit ist. Dies ist kein „Soft-Neustart“ — für einen Soft-Neustart verwenden Sie rbamp_reset(). rbamp_factory_reset() ist für die Wiederherstellung aus einem bekannt fehlerhaften Zustand oder für die Übergabe des Moduls an einen anderen Benutzer / eine andere Installation vorgesehen.
STD-Linie. Dort gibt es keinen Befehl zum Zurücksetzen auf Werkseinstellungen: rbamp_factory_reset() liefert ESP_ERR_NOT_SUPPORTED.
rbamp_reset
esp_err_t rbamp_reset(rbamp_handle_t dev);
Der Befehl CMD_RESET (0x01) + 100 ms Wartezeit. Ein Soft-Neustart des Geräts ohne Verlust der Flash-Parameter.
Mehrmodul-Bus
rbamp_broadcast_latch
esp_err_t rbamp_broadcast_latch(i2c_master_bus_handle_t bus,
uint32_t timeout_ms);
Auf Firmware v1.3 (REG_VERSION = 0x04) ist dies der kanonische Flotten-Sync-Pfad, sobald General-Call flottenweit über rbamp_fleet_enable_gc_all() aktiviert ist. Der 5-Byte-General-Call-Rahmen A5 27 lässt jedes Modul seinen Snapshot in der passenden Gruppe im selben Drahtmoment nehmen, was eine enge Synchronisation zwischen den Teilzählern ergibt. Die Funktion nutzt nur den Bus: Sie sendet den Rahmen (ESP_OK heißt, dass der Host-Treiber keinen Fehler meldete — General Call ist nur schreibend, kein Modul sendet ein ACK; ESP_ERR_INVALID_ARG bei einem NULL-Bus). Module ohne General-Call-Unterstützung oder mit deaktiviertem General Call ignorieren den Rahmen einfach — prüfen Sie dies mit der Zeugenprüfung je Modul (unten) und nutzen Sie den sequenziellen Rückfall, wenn sie den Snapshot nicht genommen haben. rbamp_broadcast_latch_group(bus, group, tick, timeout_ms) ist dasselbe mit explizitem Gruppenfilter und Flotten-Tick.
Sequenzieller Rückfall (Altfirmware oder wenn GC deaktiviert gelassen wurde): eine Reihe von rbamp_latch_period() auf jedem Gerät, ein gemeinsames 50-ms-Abklingen und ein Snapshot je Gerät rbamp_read_period_snapshot(skip_latch=true) — siehe 06 · Beispiele, Szenario „Monitoring multiple modules“.
STD-Linie
Die Modullinie STD spricht hinter demselben Handle ein anderes Registermodell. rbamp_begin() erkennt es; die skalare API der vorherigen Kapitel funktioniert auf beiden Linien unverändert (rbamp_read_current, _power, _voltage, rbamp_read_period_snapshot, rbamp_energy_wh, die Konfigurationsaufrufe, …). Die Funktionen in diesem Kapitel sind die reinen STD-Ergänzungen: ganze Kanäle in einem Burst, die Größen, die nur diese Linie misst (Blind- / Scheinleistung, THD, vorzeichenbehaftete Energiezähler), Snapshot-Bänke, die Modulzeit, Historie, Zustand, Firmware-Update. Jede Funktion rbamp_std_* liefert ESP_ERR_NOT_SUPPORTED auf einem BASIC-Handle.
Viele Funktionen benötigen eine minimale Version der Registerabbildung des Moduls (unten als „map 0x35+“ u. ä. angegeben). Die Funktionsfreigabe richtet sich nach den Fähigkeiten und der Map-Version, die das Modul meldet (rbamp_std_info()), nie nach Raten; ist ein Modul zu alt, liefert die Funktion ESP_ERR_NOT_SUPPORTED — meist ohne jeglichen Bus-Verkehr. Ein funktionierendes Beispiel ist examples/std_meter/.
Identität und Discovery
typedef struct {
uint8_t map_version;
uint16_t capabilities; /* RBAMP_STD_CAP_* bitmap */
uint8_t status; /* RBAMP_STD_ST_* bits at begin() time */
uint8_t n_voltage; /* populated voltage channels */
uint8_t n_current; /* populated current channels */
uint8_t variant; /* raw RBAMP_STD_VARIANT_* byte */
uint32_t active_bank; /* running firmware bank, 0 without OTA capability */
uint32_t ota_bank_size; /* flash bank size, 0 if none */
rbamp_std_period_source_t period_source;
} rbamp_std_info_t;
typedef struct {
uint8_t i2c_addr;
uint8_t map_version;
uint16_t capabilities;
uint8_t variant;
uint8_t n_voltage, n_current;
uint8_t uid[12]; /* chip UID — the identity; addresses can change */
uint32_t fw_version; /* running image version (map 0x35+; 0 if unknown) */
uint32_t board_id; /* map 0x36+; 0 below */
} rbamp_std_identity_t;
| Funktion | Beschreibung |
|---|---|
rbamp_std_info(dev, &info) |
Die von rbamp_begin() zwischengespeicherte Identität — kein Bus-Verkehr. Liefert ESP_ERR_NOT_SUPPORTED auf einem BASIC-Handle oder vor rbamp_begin(). Die Kanalsteuerung richtet sich nach n_voltage / n_current: Register von Kanälen jenseits dieser Anzahlen sind unbestimmt, und die Bibliothek verweigert ihr Lesen. |
rbamp_std_identify(dev, &id) |
Alles, was ein Master braucht, um das Modul hinter einem Handle zu erkennen (zwei bis vier kurze Lesezugriffe). |
rbamp_std_probe(bus, addr, &id) |
Sondiert eine Adresse auf einem Bus ohne Handle — der Baustein eines Scans. Schnell: keine Wiederholungen, ein NACK ist die Antwort. ESP_OK mit gefülltem id; ESP_ERR_NOT_FOUND, wenn nichts mit ACK antwortet; ESP_ERR_INVALID_RESPONSE, wenn etwas antwortet, das kein STD-Modul ist (ein BASIC-Modul, ein anderer Chip). |
rbamp_std_read_image_version(dev, &v) |
Die Version des laufenden Firmware-Images (u32, z. B. 0x00010072). Unterscheidet sich von rbamp_firmware_version(), das die Registerkarten-Version auf dieser Linie ist. 0, wenn das Modul es nicht angeben kann. |
rbamp_std_read_board_id(dev, &id) |
Board-ID des laufenden Images (Map 0x36+): ein Wort, das die Hardware kodiert, für die das Image gebaut wurde. Ein Firmware-Image wird nur akzeptiert, wenn sein Board-Wort passt (siehe rbamp_std_ota_board_ok). |
rbamp_std_locate(dev) |
Lassen Sie die LEDs des Moduls etwa 10 s blinken, damit eine Person es finden kann. |
rbamp_std_set_address_by_uid(bus, shared_addr, uid, new_addr, restart_ms) |
Geben Sie einem Modul auf einer gemeinsamen Adresse eine eigene Adresse, ausgewählt über die UID (Map 0x36+). Mehrere Module dürfen auf shared_addr sitzen (z. B. der Werksstandard); nur dasjenige, dessen UID passt, übernimmt new_addr, speichert sie und startet neu, die anderen ignorieren den Befehl. Benötigt kein Handle. Nach dem Neustart prüft die Bibliothek new_addr und kontrolliert dort die UID. restart_ms 0 = 1500 ms. ESP_ERR_NOT_FOUND, wenn unter new_addr niemand antwortet; ESP_ERR_INVALID_RESPONSE, wenn dort ein Modul antwortet, dessen UID aber abweicht. |
Wie ein STD-Modul Periodenenergie liefert
typedef enum {
RBAMP_STD_PERIOD_NONE = 0,
RBAMP_STD_PERIOD_LATCH = 1,
RBAMP_STD_PERIOD_COUNTERS = 2,
} rbamp_std_period_source_t;
Wird von rbamp_begin() anhand der Fähigkeiten des Moduls festgelegt und in rbamp_std_info_t.period_source angezeigt:
-
LATCH— das Modul hat Snapshot-Bänke. Eine Periode ist Snapshot-zu-Snapshot auf Bank 0; Mittelwerte und Energie je Kanal kommen aus der Bank. Siehe Snapshot-Bänke. -
COUNTERS— keine Snapshot-Bänke, aber dauerhaft gespeicherte Lebensdauerzähler. Eine Periode ist die Differenz zweier Zählerstände, nach dem Zeitplan des Masters genommen; es gibt keinen Snapshot-Befehl, nichts scharf zu stellen, und beim Neustart des Moduls geht nichts verloren. Siehe Lebensdauer-Energiezähler. -
NONE— keines von beiden: die Perioden- und Energieaufrufe liefernESP_ERR_NOT_SUPPORTED.
Echtzeit-Blöcke
typedef struct {
float i_rms; /* A */
float i_peak; /* A — reads 0 on module map 0x34 and earlier */
float p, q, s; /* W (signed), var (signed), VA */
float pf; /* −1..+1 */
float thd_i; /* % — 0 while harmonics are off */
float pf1; /* displacement power factor — 0 while harmonics are off */
float q1; /* fundamental reactive power, var — 0 while harmonics are off */
int64_t e_import_mws; /* raw signed import accumulator, mW·samples (>= 0) */
int64_t e_export_mws; /* raw signed export accumulator, mW·samples (<= 0) */
uint8_t implausible; /* RBAMP_FIELD_* bits set to NaN */
} rbamp_std_channel_t;
typedef struct {
float u_rms, u_peak, thd_u; /* V, V (0 on map 0x34 and earlier), % */
uint8_t implausible;
float angle_deg; /* phase angle against voltage input 0, (−180, 180]; input 0 reads 0 */
bool angle_valid; /* the module publishes the angle for this input */
} rbamp_std_voltage_t;
| Funktion | Beschreibung |
|---|---|
rbamp_std_read_channel(dev, ch, &c) |
Ein Stromkanalblock (I / P / Q / S / PF / Spitze / Energieakkumulatoren / Oberschwingungen) in einem einzigen Burst; ch ist 0..rbamp_channels(dev)-1. Die Felder sind so kohärent, wie das Modul sie veröffentlicht (je Veröffentlichungsfenster); für einen streng atomaren Mehrfeld-Snapshot verwenden Sie den Periodensnapshot. Ein Feld, das eine Plausibilitätsgrenze verletzt, ist NaN mit seinem Bit RBAMP_FIELD_* in implausible. |
rbamp_std_read_totals(dev, k, &c) |
Ein Sammelblock: k = 0 die Gesamtsumme (Summe aller Stromkanäle), k = 1..3 die Summen je Phase A/B/C (nur Mehrphasenmodule). Summen je Phase werden aus Map 0x36 veröffentlicht — auf einem einphasigen Modul ist k = 1 gleich Kanal 0, und k = 2/3 liefern 0; unterhalb 0x36 liefern sie ESP_ERR_NOT_SUPPORTED (k = 0 funktioniert immer). Die Energiefelder (e_import_mws / e_export_mws) sind bei Sammelblöcken nicht befüllt und liefern 0 — Energie kommt aus den persistenten Zählern (rbamp_std_read_energy). |
rbamp_std_read_voltage(dev, v, &u) |
Ein Spannungskanalblock (RMS / Spitze / THD / Phasenwinkel) in einem Burst; v ist 0..n_voltage-1. angle_deg / angle_valid werden von Dreiphasenmodulen mit Modul-Image-Version 0x0001007A oder neuer veröffentlicht; andernfalls ist angle_valid falsch, und der Rest des Blocks ist nicht betroffen. Bei einem Dreiphasenmodul mit Vorwärtsfolge liest Eingang 1 etwa −120° und Eingang 2 etwa +120°. |
rbamp_std_read_phase_seq(dev, &seq) |
Die Reihenfolge der Spannungseingänge, vom Modul aus den Winkeln abgeleitet: RBAMP_STD_PHASE_SEQ_NA (weniger als drei Eingänge oder ein Eingang zu schwach), _FORWARD (L1-L2-L3), _REVERSE (L1-L3-L2), _ABNORMAL (kein 120°-Muster, z. B. zwei Eingänge an derselben Phase verdrahtet). Liefert ESP_ERR_NOT_SUPPORTED (und *seq = NA) bei einer Modul-Image-Version älter als 0x0001007A, ohne Busverkehr. |
thd_i, pf1, q1 und thd_u liefern 0, sofern die Oberschwingungsauswertung nicht aktiviert ist — siehe Konfiguration. e_import_mws / e_export_mws sind die rohen Akkumulatoren des Moduls in mW·Abtastungen; das Modul hat keine Uhr, daher braucht die Umrechnung in Wh die Anzahl der Abtastungen und Ihre eigene Periodenzeitmessung (verwenden Sie den Snapshot-Pfad oder die Lebensdauerzähler). Für die Überwachung integrieren Sie p über Ihr Abfrageintervall.
rbamp_read_all() liest bei einem STD-Modul den Spannungsblock und jeden Kanalblock vollständig (jeweils eine Transaktion), statt Feld für Feld. rbamp_read_frequency() liefert bei einem STD-Modul ESP_ERR_INVALID_RESPONSE mit *out = NaN, wenn das Modul 0 meldet (kein Netz); rbamp_read_all() setzt dann RBAMP_FIELD_FREQUENCY. rbamp_read_voltage_peak() / rbamp_read_current_peak() liefern auf Modul-Map 0x34 und älter 0 — verwenden Sie für den Spitzenwert über eine Periode max_u / min_u / max_i einer Snapshot-Bank.
Zustand
typedef struct {
uint8_t status; /* RBAMP_STD_ST_* bits: cal_ok / sensor_ok / mains_ok / locked / time_valid */
uint32_t frame_count; /* sensor frame counter — must grow between polls */
uint32_t crc_errors; /* sensor frame CRC error counter */
bool time_valid; /* the module clock is set; false after every module reset */
bool nvm_fault; /* energy store fault or corrupt (details in lta_status) */
uint8_t lta_status; /* life-time energy store: 0 ok · 1 new · 2 fault · 3 corrupt (service) */
uint8_t lta_src; /* counters loaded from: 0 none · 1 NVM · 2 backup domain · 3 legacy · 4 rollback anchor */
uint8_t cal_src; /* calibration in use: 0 defaults · 1 flash · 2 EEPROM · 3 stored cal is for another range */
uint32_t lost_frames; /* sensor frames lost since boot — should stay flat */
uint16_t ring_drop; /* acquisition ring overruns since boot — should stay flat */
uint32_t uptime_s; /* seconds since the module booted */
bool maint; /* maintenance mode active */
uint8_t group_status; /* per-channel energy store: 0 ok · 1 new · 2 fault · 3 restarted at 0 */
uint16_t legal_noen; /* metering-relevant operations executed outside maintenance mode */
uint8_t reset_cause; /* image 0x76+: cause of THIS boot, RBAMP_STD_RST_* bits; 0 below */
uint16_t boot_count; /* image 0x76+: persisted boot counter (low 16 bits); 0 below */
} rbamp_std_health_t;
rbamp_std_read_health(dev, &h) liest den Live-Zustand. Betrachten Sie Messwerte als gültig, wenn status RBAMP_STD_ST_SENSOR_OK enthält und frame_count zwischen zwei Abfragen steigt. Die Felder nach crc_errors existieren auf Modulen mit Map 0x35+ und liefern auf älteren Null / false.
Alarm bei: nvm_fault oder lta_status >= 2 (Energiespeicher); cal_src == 3 (die gespeicherte Kalibrierung gilt für einen anderen Bereich, Standardwerte werden verwendet, cal_ok ist ebenfalls gelöscht); lost_frames / ring_drop steigen; time_valid false (Uhr stellen); uptime_s sinkt (das Modul hat neu gestartet). reset_cause trägt die Bits RBAMP_STD_RST_* (Pin, Strom, Software = Reset / Aktivierung / Adressänderung, Watchdogs, Energiesparmodus, Options-Byte); das Pin-Bit begleitet die meisten internen Resets, daher nach den übrigen Bits beurteilen.
Konfiguration
typedef struct {
uint8_t sensor_class; /* rbamp_sensor_class_t value; 0 = unset. Persisted. */
uint8_t ct_model; /* CT model reference for channel 0 (metadata, sets no gain). Persisted. */
uint8_t tier; /* 0 or 1. 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) */
uint16_t start_ua; /* starting current for energy, µA (0 = off); 0 when start_ua_supported is false */
bool start_ua_supported; /* the module has the starting-current setting */
} rbamp_std_config_t;
| Funktion | Beschreibung |
|---|---|
rbamp_std_read_config(dev, &cfg) |
Der Konfigurationsblock (ein Burst sowie das Register für den Anlaufstrom, sofern das Modul es hat). |
rbamp_std_set_harmonics(dev, enable) |
Schaltet die Extraktion der Grundharmonischen (THD, Verschiebungs-PF, Q1) ein oder aus. Standardmäßig aus auf der regulären Stufe (spart CPU des Moduls); die Felder der Harmonischen liefern 0, solange sie aus sind. Nur im RAM: fällt bei einem Reset des Moduls wieder auf aus zurück. Rücklesen und bestätigt. ESP_ERR_NOT_SUPPORTED ohne die THD-Fähigkeit. |
rbamp_std_cal_thd_floor(dev) |
Kalibriert den THD-Bodenwert der Sensorkette: erfasst den aktuell geglätteten rohen THD als Boden, speichert ihn und wendet ihn sofort an. Voraussetzung: sauberes Netz und KEINE Last an der CT — der erfasste Wert wird von jedem späteren THD-Messwert abgezogen. Blockiert für die Persistenz-Einschwingzeit; das Ergebnis kommt aus dem Fehlerregister des Moduls (Map 0x34+). ESP_ERR_NOT_SUPPORTED ohne die THD-Fähigkeit. |
rbamp_std_get_start_current(dev, &ua) |
Der Anlaufstrom für die Energie in µA (0 = aus). Unterhalb dieses Kanalstroms zählt das Modul keine Energie für diesen Kanal (Bezug oder Einspeisung, Gesamtsumme und je Kanal); die Messwerte selbst bleiben unberührt. ESP_ERR_NOT_SUPPORTED ohne Busverkehr auf einem Modul ohne diese Einstellung (Modul-Image-Version älter als 0x0001007B). |
rbamp_std_set_start_current(dev, ua) |
Setzen: 0 = aus, sonst ein Wert aus der Menge der Stufen, die das Modul akzeptiert. Wirkt sofort; rbamp_save_user_config() speichert ihn. Rückgelesen und bestätigt. ESP_ERR_INVALID_ARG für einen Wert außerhalb der akzeptierten Menge — nichts wird geschrieben; ESP_ERR_NOT_SUPPORTED wie oben; ESP_ERR_INVALID_STATE, wenn das Modul den Wert nicht übernommen hat. |
Die skalaren Konfigurationsaufrufe (rbamp_set_sensor_class, rbamp_set_ct_model_ch, rbamp_configure_channels, rbamp_save_user_config, rbamp_save_gains, rbamp_prepare_address_change / rbamp_commit_address_change, rbamp_reset) funktionieren auf beiden Linien; jeder hat im eigenen Abschnitt einen Hinweis „STD line“. Zwei Unterschiede sind erwähnenswert: rbamp_factory_reset() liefert ESP_ERR_NOT_SUPPORTED (auf dieser Linie gibt es keinen solchen Befehl), und rbamp_save_gains() speichert den Kalibrierblock.
rbamp_commit_address_change() ist auf der Linie STD synchron: Das Speichern der Konfiguration wartet auf das Modul und liest das Ergebnis (eine Adresse außerhalb des Bereichs → ESP_ERR_INVALID_ARG; die Schreibratenbegrenzung des Modul-Flash → ESP_ERR_NOT_FINISHED — erneut vorbereiten und nach etwa 5 s wiederholen; in beiden Fällen ändert sich nichts), startet danach das Modul neu und schaltet das Handle erst um, wenn ein Modul unter der neuen Adresse antwortet (innerhalb von etwa 3 s). Antwortet dort niemand, folgt ESP_ERR_NOT_FOUND, und das Handle behält die alte Adresse. rbamp_read_active_address() liest die gespeicherte Adresse.
Lebensdauer-Energiezähler
Für ein Modul, das Energiezähler dauerhaft auf dem Gerät speichert (RBAMP_STD_CAP_ONDEVICE_ENERGY).
typedef struct {
int64_t act_import_wh, act_export_wh, act_net_wh; /* Wh; net = import − export */
int64_t rea_import_varh, rea_export_varh; /* varh */
uint32_t generation; /* changes when the counters were reset or adopted */
uint32_t uptime_s; /* module uptime */
int64_t act_import_mwh, act_export_mwh, act_net_mwh;/* mWh (map 0x36+) */
uint8_t channels; /* valid entries in the per-channel arrays (map 0x36+) */
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, fine_reactive;
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];
} rbamp_std_energy_t;
Die Zähler sind ganzzahlige Einheiten, monoton und bleiben bei Stromausfall erhalten. Bezug und Einspeisung sind getrennte Größen. Die Energie einer Periode ist die Differenz zweier Messwerte.
-
generationändert sich, wenn die Zähler auf dem Modul zurückgesetzt oder übernommen wurden — nie eine Differenz darüber bilden. -
Ein sinkendes
uptime_sbedeutet, dass das Modul neu gestartet hat. Die Zähler sind gespeichert, daher ist die Differenz weiterhin gültig, aber die Uhr und die Einstellungen im RAM des Moduls sind verloren. -
Nach einem Stromausfall kann ein Zähler knapp unter Ihrem letzten Messwert wieder einsetzen (ein Bruchteil einer Sekunde Energie);
rbamp_std_energy_delta()begrenzt eine solche Differenz auf 0 und behält das Intervall bei. -
Die Felder
*_uwh/*_uvarhsind immer befüllt, sodass Sie sie bei jedem Modul verwenden können: ein Modul, das Zähler mit Mikro-Auflösung veröffentlicht (Modul-Image-Version0x0001007Aund neuer; Blindleistung ab0x0001007B), liefert sie aus demselben Snapshot, undfine/fine_reactivesind true; auf älteren Modulen sind es die groben, skalierten Zähler, undfineist false. -
channels > 0(Map 0x36+): Kanalcist Stromkanalc; bei einem Dreiphasenmodul Phasec.
rbamp_std_energy_t erhält über die Komponentenversionen hinweg neue Felder. Wenn Sie es speichern (NVS, Datei), legen Sie die einzelnen benötigten Felder in Ihrem eigenen festen Format ab — nicht die Struktur als rohen Blob.
| Funktion | Beschreibung |
|---|---|
rbamp_std_read_energy(dev, &e) |
Lesen Sie die Zähler. Jeder dekodierte Block ist eine Transaktion (das Modul liefert ihn aus einem kohärenten Snapshot). ESP_ERR_NOT_SUPPORTED, sofern das Modul die Fähigkeit zur Energieführung am Gerät nicht meldet; ESP_ERR_INVALID_RESPONSE, wenn der Block als nicht programmiert gelesen wird. |
rbamp_std_energy_delta(&prev, &now, &delta, &restarted) |
Energie zwischen zwei Messwerten mit den angewandten Kontinuitätsregeln. delta = jetzt − vorher je Zähler (Bezug/Einspeisung-Beträge, netto, Blind; generation und uptime_s werden aus jetzt übernommen); restarted ist true, wenn uptime_s gesunken ist. Jede der beiden Ausgaben darf NULL sein. Ein Zähler, der gesunken ist, wird auf eine Differenz von 0 begrenzt — auch pro Kanal und auf jeder Auflösung; jedes Netto-Feld ist die Bezugsdifferenz minus die Einspeisungsdifferenz. Kanalbezogene Differenzen entstehen, wenn beide Messwerte dieselbe Kanalanzahl tragen, andernfalls ist delta->channels 0. ESP_ERR_INVALID_STATE, wenn die Generation abweicht — dieses Intervall nicht verbuchen; neu beginnen mit jetzt. |
Schnappschuss-Bänke
Das Modul führt 8 unabhängige Bänke (nur auf Modulen mit der Fähigkeit für mehrere Snapshots, period_source == RBAMP_STD_PERIOD_LATCH). Eine Bank akkumuliert, solange ihr Bit in der Arm-Maske gesetzt ist; rbamp_std_latch() nimmt einen Snapshot und setzt zurück an der nächsten Messfenstergrenze des Moduls. Eine Periode ist daher das Intervall zwischen zwei Snapshots derselben Bank, gemessen mit der Uhr des Masters (das Modul hat keine). Bank 0 wird auch von rbamp_read_period_snapshot() und rbamp_energy_wh() verwendet. Die drei Bankaufrufe liefern ESP_ERR_NOT_SUPPORTED ohne Busverkehr auf jedem anderen Modul — dort rbamp_std_read_energy() / rbamp_std_energy_delta() verwenden.
Typische Anwendung: Bänke einmal scharf schalten, dann je Bank nach eigenem Zeitplan rbamp_std_latch(bank) → ≥ 300 ms warten (eine sichere obere Grenze für ein Messfenster auf jedem Image) → rbamp_std_read_latch() → rbamp_std_latch_wh() mit dem vom Master gemessenen dt seit dem vorherigen Snapshot.
typedef struct {
float p_avg, q_avg, s_avg; /* average P / Q / S over the period */
float max_p, max_i, max_u, min_u;/* peaks in the period */
int64_t e_import_mws, e_export_mws;/* energy, mW·samples */
uint32_t nsamp; /* sensor samples in the period */
uint32_t win_count; /* measurement windows in the period (0 = not armed / nothing elapsed) */
uint8_t channels; /* valid entries in the per-channel arrays */
uint8_t 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];
} rbamp_std_latch_t;
| Funktion | Beschreibung |
|---|---|
rbamp_std_arm_banks(dev, mask) |
Setzen Sie die Akkumulationsmaske: Bit b = Bank b akkumuliert (neu scharf gestellte Bänke beginnen sauber; deaktivierte Bänke frieren ein und behalten ihren letzten Snapshot). Bit 0 muss gesetzt bleiben, wenn Sie rbamp_read_period_snapshot() verwenden. Die Maske liegt im RAM des Moduls: Jeder Modul-Reset löscht sie, und das Snapshotten einer nicht scharf gestellten Bank liefert einen leeren Snapshot. Die Bibliothek stellt Bank 0 selbst neu scharf (in rbamp_begin(), nach ihren eigenen Resets und wenn ein Periodensnapshot leer zurückkommt). Für Ihre eigenen Bänke erkennt rbamp_std_read_latch() den verlorenen Scharfzustand, stellt neu scharf und nimmt einen Primer-Snapshot. |
rbamp_std_latch(dev, bank) |
Fordert einen Snapshot an und setzt bank an der nächsten Fenstergrenze zurück. Wartet nicht — lesen Sie ≥ 300 ms später. |
rbamp_std_read_latch(dev, bank, &l) |
Liest den letzten Snapshot von bank (ein Burst: Summen + Energie je Kanal für jeden belegten Kanal). ESP_ERR_INVALID_RESPONSE, wenn das Modul diese Bank nie gelatcht hat (andere Felder sind null). ESP_ERR_INVALID_STATE, wenn der Snapshot leer ist, weil die Bank durch einen Modul-Reset entschärft wurde — die Bibliothek hat sie neu scharf gestellt und primer-gelatcht: diese Periode verwerfen und Ihren dt-Anker neu starten. Lesen Sie eine Bank mindestens ein Messfenster nach dem Latchen; win_count == 0 heißt, dass sie nicht scharf war oder kein Fenster abgelaufen ist. |
rbamp_std_latch_wh(&l, dt_ms, ch, &wh_import, &wh_export) |
Rechnet die Energiebuckets eines Snapshots über die vom Master gemessene Periode dt_ms in Wh um (die Wanduhr des Masters zwischen dem vorherigen und diesem Snapshot der Bank). ch ist ein Kanalindex oder RBAMP_STD_TOTAL (0xFF) für die Bank-Summen. Wh = E[mW·Abtastungen] / 1000 / 3600 × (dt / nsamp): Die Abtastanzahl und das dt des Masters normieren das Ergebnis. Bezug ≥ 0, Einspeisung ≤ 0; beide Ausgaben dürfen NULL sein. ESP_ERR_INVALID_STATE, wenn nsamp 0 ist. |
Uhr, Befehle und Service
Das Modul führt seine Uhr im RAM: sie ist nach jedem Reset des Moduls ungültig. Ohne gültige Uhr zeichnet das Modul keine Historie auf.
| Funktion | Beschreibung |
|---|---|
rbamp_std_set_time(dev, unix_epoch) |
Stellt die Modulzeit (Unix-Sekunden) und wartet auf den Abschluss. Nach rbamp_begin() aufrufen und immer dann, wenn rbamp_std_health_t.time_valid false ist (oder eine Periode module_restarted meldet). Die erste Einstellung nach einem Reset schließt das laufende Historienintervall ab, ohne es zu übernehmen. ESP_ERR_INVALID_ARG, wenn das Modul die Epoche ablehnt (vor 2020); ESP_ERR_INVALID_STATE, wenn die Uhr nicht gültig wurde; ESP_ERR_NOT_SUPPORTED unterhalb von Map 0x35. |
rbamp_std_read_time(dev, &epoch, &valid) |
Liest die Uhr des Moduls und ob sie gültig ist. |
rbamp_std_command(dev, opcode, settle_ms, timeout_ms) |
Schreibt einen Befehls-Opcode und wartet auf seinen Abschluss: wartet zuerst, bis das Modul untätig ist (ein Befehl, der bei Belegung geschrieben wird, wird verworfen), schläft settle_ms, wartet, bis BUSY erlischt, und liest dann das Ergebnis. timeout_ms 0 = 1 s. Ergebnisse: ESP_ERR_INVALID_ARG (ungültiger Parameter), ESP_ERR_NOT_SUPPORTED (unbekannter Befehl), ESP_ERR_INVALID_CRC (Wertprüfung), ESP_ERR_NOT_FINISHED (Flash-Schreiben ratenbegrenzt — nach etwa 5 s wiederholen), ESP_ERR_NOT_ALLOWED (Schlüssel- oder Wartungssperre), ESP_ERR_TIMEOUT (weiterhin belegt). |
rbamp_std_wait_idle(dev, timeout_ms) |
Wartet, bis das Modul den Befehl abgeschlossen hat, den es gerade ausführt. Jeder Befehl, der über diese Bibliothek ausgegeben wird, wartet bereits; verwenden Sie dies nur rund um Befehle, die Sie selbst in das Befehlsregister schreiben — ein Befehl, der im Zustand BUSY geschrieben wird, geht verloren. Liefert sofort zurück auf Modulen ohne Befehlszustandsregister. |
rbamp_std_hist_flush(dev) |
Schreibt die Energie-Akkumulatoren jetzt in den Flash (ergibt sich auch aus Reset / Firmware-Commit). |
Ein Befehlsschreibvorgang wird bei einem Transportfehler nie wiederholt (eine Wiederholung könnte den Opcode zweimal ausliefern); Lese- und Schreibvorgänge der Datenregister behalten die Wiederholung.
Verlauf und Ereignisprotokoll
Das Modul hält den letzten 15-Minuten-Datensatz im RAM (geht bei einem Modul-Reset verloren — ein Live-Indikator, keine Historie) und einen stündlichen Ringpuffer im Flash, der Resets übersteht und aus dem nachgeladen werden sollte; beide werden nur geschrieben, während die Uhr des Moduls gültig ist. Ein nie gelöschtes Ereignisprotokoll zeichnet abrechnungsrelevante Änderungen auf. Jeder STUNDEN-Datensatz enthält die Lebensdauer-Zähler absolut zum Periodenende: Die Gesamtenergie einer Periode ist die Differenz zweier aufeinanderfolgender Datensätze (Resets und Lücken bleiben sichtbar). Nachladen nach einem Ausfall des Masters: Ab 0 (neuester) mit back rückwärts gehen, bis die Zeitstempel erreicht sind, die Sie bereits haben.
typedef enum {
RBAMP_STD_HIST_MIN15 = 0, /* 15-minute records (RAM, lost at module reset) */
RBAMP_STD_HIST_HOUR = 1, /* hourly records (flash ring) */
RBAMP_STD_HIST_EVENTS = 2, /* event log — read with rbamp_std_event_read */
} rbamp_std_hist_period_t;
typedef struct {
uint16_t count; /* records available (0 while the ring is being cleared) */
uint16_t capacity; /* ring depth */
uint16_t record_size; /* bytes per record */
uint32_t oldest_ts, newest_ts; /* unix */
} rbamp_std_hist_info_t;
typedef struct {
uint32_t ts; /* period start, unix */
uint16_t flags; /* RBAMP_STD_HF_* bits */
uint16_t n; /* samples (MIN15) or 15-minute children (HOUR: 4 = complete) */
bool from_ram; /* record came from the RAM ring (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 counters ABSOLUTE at period end */
uint8_t phases; /* valid entries in the per-phase arrays */
double ph_import_wh[3], ph_export_wh[3]; /* per-phase energy OF THIS PERIOD, Wh */
} rbamp_std_hist_record_t;
typedef struct {
uint32_t ts; /* unix time (0 = clock was not set) */
uint32_t uptime_s; /* module uptime at the event */
uint8_t type; /* RBAMP_STD_EV_* */
uint8_t flags; /* RBAMP_STD_EVF_* (maintenance mode was active) */
uint16_t boot; /* boot counter (low 16 bits) */
uint32_t a_before, a_after; /* type-specific values before / after the change */
uint64_t e_before_wh, e_after_wh; /* grand import counter before / after, Wh */
} rbamp_std_event_t;
| Funktion | Beschreibung |
|---|---|
rbamp_std_hist_info(dev, period, &info) |
Ringzustand einer Historienperiode (wählt sie zugleich auf dem Modul aus). |
rbamp_std_hist_read(dev, period, back, &rec) |
Ruft den Datensatz back (0 = neuester) von MIN15 oder HOUR ab und decodiert ihn. ESP_ERR_NOT_FOUND, wenn es keinen solchen Datensatz gibt. Die Energie einer Periode nur aus zwei aufeinanderfolgenden Datensätzen entnehmen, deren Zeitstempel sich genau um eine Periode unterscheiden und von denen keiner das Flag RBAMP_STD_HF_LTA_JUMP trägt. |
rbamp_std_hist_read_raw(dev, period, back, rec, &flags) |
Derselbe Datensatz unverarbeitet: rec (ein Puffer RBAMP_STD_REG_HIST_REC_SIZE; die aussagekräftige Länge ist record_size) empfängt die Datenbytes des Moduls, flags die Flags des Moduls. |
rbamp_std_event_read(dev, back, &ev) |
Ruft den Ereignisprotokolleintrag back ab und dekodiert ihn (0 = neuester). ESP_ERR_NOT_FOUND, wenn keiner vorhanden ist. Die Ereignistypen sind die generierten Konstanten RBAMP_STD_EV_* (Zurücksetzen / Übernahme des Lebensdauerzählers, Speichern der Kalibrierung, Firmware-Commit, Löschen der Historie, …). |
Authentizität
Ein provisioniertes Modul trägt ein Gerätezertifikat, das vom Herstellerschlüssel signiert ist, und beantwortet eine Challenge mit einer digitalen Signatur des im Zertifikat genannten Geräteschlüssels. Die Bibliothek ruft beides ab; die Prüfung ist Aufgabe der Anwendung (mit einer Signaturbibliothek Ihrer Wahl).
typedef struct {
uint8_t raw[RBAMP_STD_REG_SEC_CERT_SIZE]; /* certificate bytes as read */
uint8_t state; /* the module's own check: 0 none · 1 ok · 2 bad · 3 not checked yet (shortly after boot) */
uint8_t version, variant, hw_rev;
uint8_t uid[12]; /* chip UID the certificate was issued for (compare with rbamp_read_uid) */
uint32_t batch, issued; /* production batch; issue time, unix */
uint8_t device_pubkey[32];
uint32_t mfr_key_id;
} rbamp_std_certificate_t;
typedef struct {
uint8_t signature[64]; /* signature over the attested message */
uint8_t data[24]; /* attested data exactly as signed */
uint32_t fw_version, generation; /* from data */
int64_t e_import_wh, e_export_wh; /* from data: life-time import / export, Wh */
} rbamp_std_attestation_t;
| Funktion | Beschreibung |
|---|---|
rbamp_std_read_certificate(dev, &cert) |
Liest das Gerätezertifikat. ESP_ERR_NOT_FOUND, wenn das Modul keines hat (nicht provisioniert; state wird trotzdem gefüllt); ESP_ERR_NOT_SUPPORTED unterhalb von Map 0x35. |
rbamp_std_attest(dev, challenge, &att) |
Fordern Sie das Modul mit 32 Zufallsbytes Ihrer Wahl heraus (bewahren Sie Ihre Kopie auf — das Modul überschreibt den Challenge-Bereich mit der Signatur) und holen Sie die signierte Antwort (etwa 60 ms). Die bescheinigten Daten binden die Firmware-Version und die Lebensdauerzähler an den Gerätschlüssel. ESP_ERR_NOT_FOUND, wenn das Modul keinen Gerätschlüssel hat; ESP_ERR_INVALID_STATE, wenn das Modul die Attestierung nicht als erledigt meldete. |
Firmware-Update (OTA)
Ein zweiphasiges Update über I²C. Jede Funktion hier gibt ESP_ERR_NOT_SUPPORTED zurück, sofern das Modul die OTA-Fähigkeit meldet (Map 0x33 oder neuer). Jeder Befehl wird innerhalb der Bibliothek synchron abgeschlossen (sie wartet auf den Befehlszustand des Moduls, nicht auf eine feste Verzögerung).
Ablauf: rbamp_std_ota_begin → rbamp_std_ota_write_page × N (Seiten zu 256 Bytes; leere 0xFF-Seiten dürfen übersprungen werden) → rbamp_std_ota_commit (prüft und scharf schalten den Wechsel, ohne Neustart) → rbamp_std_ota_activate (startet bei Bereitschaft in das neue Image neu). Das Modul ist für einige Sekunden vom Bus getrennt und fährt danach etwa 10 s lang eine Testphase, bevor das Image bestätigt wird. Nach jeder Seite muss die Sitzung noch offen sein, sonst schlägt der Aufruf mit ESP_ERR_INVALID_STATE fehl (neu ab begin starten). Ein fehlerhaftes Image rollt das Modul selbst zurück; die Kalibrierung bleibt erhalten.
Nur herstellerseitig vorbereitete Images werden akzeptiert. Release-Images erzeugt die Tooling des Modulherstellers (signiert und, wo nötig, verschlüsselt); das Modul lehnt einen vom Host gebauten Header beim Commit ab. rbamp_std_ota_write_image() (vom Host gebautes, unsigniertes Image) liefert daher ESP_ERR_NOT_SUPPORTED, bevor es das Modul berührt, und wird nur aus Gründen der ABI-Kompatibilität beibehalten.
| Funktion | Beschreibung |
|---|---|
rbamp_std_ota_status(dev, &st) |
Der OTA-Zustand des Moduls (RBAMP_STD_OTA_IDLE / READY / OK / ERR / DOWNGRADE). |
rbamp_std_ota_begin(dev, timeout_ms) |
Die inaktive Bank löschen und warten, bis das Modul READY meldet. timeout_ms 0 = Standard (5 s). ESP_ERR_TIMEOUT, wenn READY nicht erreicht wurde. |
rbamp_std_ota_write_page(dev, page_idx, page) |
Schreibt eine 256-Byte-Seite am Index page_idx (Offset / 256 innerhalb der Bank). ESP_ERR_INVALID_STATE, wenn das Modul einen Schreibfehler meldet. |
rbamp_std_ota_commit(dev, timeout_ms) |
Prüft das geschriebene Image und scharf schaltet den Bank-Wechsel. timeout_ms 0 = Standard (3 s). ESP_OK scharf geschaltet · ESP_ERR_INVALID_CRC fehlerhaftes Image (CRC / Header) · ESP_ERR_INVALID_MAC Authentifizierung fehlgeschlagen · ESP_ERR_INVALID_VERSION Image älter als das laufende · ESP_ERR_TIMEOUT. |
rbamp_std_ota_diag(dev, &reason) |
Warum das Modul die letzte Seite oder den letzten Commit abgelehnt hat: das Grundbyte seiner OTA-Diagnose (0 = keiner). rbamp_std_ota_commit() ordnet den Grund bereits dem oben genannten Fehlercode zu und protokolliert seinen Namen; rufen Sie dies auf, wenn Sie den Code selbst benötigen. |
rbamp_std_ota_activate(dev) |
In das scharfgestellte Image neu starten, warten, bis das Modul wieder da ist (etwa 4 s), es neu erkennen und dann die Testphase durchhalten und bestätigen: Die aktive Bank hat gewechselt, das laufende Image ist die vorbereitete Version, der Tausch ist nicht mehr ausstehend. Blockiert insgesamt etwa 10 s — das Modul in diesem Zeitfenster nicht zurücksetzen oder stromlos machen (der Bootloader rollt ein unbestätigtes Image zurück). Das Handle bleibt gültig, und rbamp_std_info() spiegelt die neue Firmware wider. ESP_ERR_INVALID_STATE, wenn nichts scharf gestellt war, wenn das Modul mit dem vorherigen Image zurückkam (Rollback) oder wenn der Tausch nach der Testphase noch aussteht. |
rbamp_std_ota_staged_version(dev, &v) |
Version des scharf geschalteten (committeten, noch nicht aktivierten) Images; 0, wenn nichts scharf geschaltet ist (Map 0x35+). |
rbamp_std_ota_abort(dev) |
Eine Update-Sitzung schließen und ein scharf geschaltetes Image entschärfen; das Modul läuft weiter, was es ausführt (Map 0x35+). |
rbamp_std_ota_board_ok(dev, image_board_word) |
Vorprüfung vor dem Streamen eines vorbereiteten Images: Das Board-Wort des Images (vom Hersteller-Tooling neben der Image-Datei mitgeliefert) muss mit der Board-ID des Moduls übereinstimmen. ESP_OK, wenn es passt; ESP_ERR_INVALID_ARG, wenn nicht (protokolliert); ESP_ERR_NOT_SUPPORTED unterhalb von Map 0x36. |
rbamp_std_ota_write_prepared(dev, image, size, cb, ctx) |
Streamen Sie ein vorbereitetes Bank-Image unverändert: begin, Seiten in aufsteigender Reihenfolge (Seite 0 wird immer gesendet, andere Seiten, die komplett 0xFF sind, werden übersprungen), commit. Die Bibliothek ändert nichts. Aktiviert nicht. size muss der Banggröße entsprechen, die das Modul meldet (rbamp_std_info_t.ota_bank_size) — sonst ESP_ERR_INVALID_SIZE, und nichts wird geschrieben. cb(done, total, ctx) ist ein optionaler Fortschritts-Callback (rbamp_std_ota_progress_cb_t). |
rbamp_std_ota_write_prepared_pair(dev, bank_a, size_a, bank_b, size_b, cb, ctx) |
Wie oben, bei beiden Bank-Images: Die Bibliothek fragt das Modul, welche Bank läuft, und streamt die andere. ESP_ERR_NOT_SUPPORTED bei Modulen, die ihre laufende Bank nicht melden (Map unter 0x35) — verwenden Sie dann rbamp_std_ota_write_prepared() und wählen Sie selbst anhand von active_bank. |
rbamp_std_crc32(data, len) |
CRC-32 (zlib-kompatibel) — die Prüfsumme, die das Modul beim Commit verifiziert. |
rbamp_std_ota_make_header(out, version, len, crc32) |
Erzeugt den Little-Endian-Image-Header. Nur verfügbar, wenn der generierte Register-Header die Header-Konstanten definiert; aus Gründen der ABI beibehalten. |
Diagnose
rbamp_err_to_str
const char *rbamp_err_to_str(esp_err_t err);
Liefert einen Zeiger auf eine statische Zeichenkette mit einer lesbaren Beschreibung des Fehlercodes. Gibt nie NULL zurück. Für Systemcodes verwendet sie das Standard-esp_err_to_name() und erweitert die Beschreibungen um rbamp-spezifische Bedeutungen (etwa was ESP_ERR_INVALID_STATE im Kontext von set_ct_model_ch ohne set_sensor_class bedeutet).
Typische Verwendung:
esp_err_t err = rbamp_read_period_snapshot(dev, &snap, 50, false);
if (err != ESP_OK) {
ESP_LOGE(TAG, "snapshot failed: %s", rbamp_err_to_str(err));
}
rbamp_retry_exhaustion_count / rbamp_sanity_reject_count / rbamp_reset_counters
uint32_t rbamp_retry_exhaustion_count(rbamp_handle_t dev);
uint32_t rbamp_sanity_reject_count (rbamp_handle_t dev);
void rbamp_reset_counters (rbamp_handle_t dev);
Öffentliche Getter für zwei Diagnosezähler (beide liefern 0 bei einem NULL-Handle):
-
rbamp_retry_exhaustion_count(dev)— ein monotoner Zähler für Ereignisse „Retry-Budget erschöpft“. Jede Erhöhung = eine Einzelbyte-Transaktion, die nachCONFIG_RBAMP_NACK_RETRY_ATTEMPTSVersuchen nie ein ACK vom Gerät erhielt. -
rbamp_sanity_reject_count(dev)— ein monotoner Zähler der Ablehnungen durch den Plausibilitätsfilter bei Float-Lesevorgängen (NaN, Inf oder ein Absolutwert über der Grenze je Größe —RBAMP_SANITY_LIMIT_V/_I/_P/_PF). Jede Erhöhung = ein Float, der vom Bus kam, als nicht physikalisch beurteilt und verworfen wurde; der Lesevorgang liefertESP_ERR_INVALID_RESPONSE.
rbamp_reset_counters(dev) setzt beide Zähler auf diesem Handle auf null (No-op für NULL). Gedacht für Testszenarien, die eine saubere Ausgangsbasis brauchen. Für die Produktionsüberwachung bevorzugen Sie das kanonische Muster „Rate über ein Intervall“ — Snapshot + Differenz, das gegen verpasste Reset-Fenster robust ist:
uint32_t prev = rbamp_retry_exhaustion_count(dev);
/* ...60 s of normal operation... */
uint32_t delta = rbamp_retry_exhaustion_count(dev) - prev;
if (delta > THRESHOLD) { /* alert */ }
Diese Namen entsprechen der plattformübergreifenden Arduino-Bibliothek (dev.retryExhaustionCount() / dev.sanityRejectCount() — dieselbe Semantik, in snake_case). Für praktische Lasten und Alarmschwellen siehe 10 · Fehlerbehebung, Abschnitt „Zähler überwachen“.
Protokollierung über esp_log
Die Komponente schreibt Logs unter dem Tag "rbamp". Die Log-Stufe wird über Kconfig beim Kompilieren festgelegt — das Laufzeit-esp_log_level_set("rbamp", ...) funktioniert, ist aber nach oben durch die Stufe zur Compilezeit begrenzt.
esp_log_level_set("rbamp", ESP_LOG_DEBUG); /* for debugging */
Fehlercodes
Die Funktionen rbamp_* liefern Standardwerte von esp_err_t. Die spezifischen Codes und ihre Bedeutung im Kontext von rbamp:
| Code | Wann | Wo nachzuschlagen ist |
|---|---|---|
ESP_OK (0) |
Erfolg | — |
ESP_FAIL (-1) |
Die I²C-Transaktion ist nach Wiederholungen fehlgeschlagen | Verdrahtung, Versorgung, Busgeschwindigkeit — Abschnitt „The module does not respond over I²C“ in 10 · Fehlerbehebung |
ESP_ERR_INVALID_ARG (0x102) |
Ungültiges Argument: dev == NULL, channel oder phase außerhalb des Bereichs, ein nicht erkanntes cls, ein Wert, den das Modul ablehnt (unbekanntes CT-Modell, Anlaufstrom außerhalb des akzeptierten Satzes, eine Uhr vor 2020) |
Die Aufrufargumente prüfen |
ESP_ERR_TIMEOUT (0x107) |
rbamp_wait_ready / rbamp_wait_data_ready ist abgelaufen; das Fenster rbamp_commit_address_change (5 s) ist abgelaufen; ein STD-Befehl oder OTA-Zustand wurde nicht abgeschlossen |
Ansprechbarkeit prüfen über rbamp_probe() |
ESP_ERR_INVALID_STATE (0x103) |
Eine Vorbedingung oder Aufrufreihenfolge ist falsch: set_ct_model* vor set_sensor_class; das Modul ist Klasse 2 / 3 (mit seinem Sensor kalibriert — für den Service rbamp_set_ct_model_ch_force() verwenden); das Modul hat das Paar (class, model) abgelehnt; Adress-Commit nicht scharf gestellt; Snapshot-Bank der STD-Linie nach einem Modul-Reset erneut scharf gestellt (diese Periode verwerfen); Zählergeneration der STD-Linie hat sich geändert (rbamp_std_energy_delta); OTA-Sitzung nicht geöffnet |
Abschnitt „rbamp_set_* liefert ESP_ERR_INVALID_STATE“ in 10 · Fehlerbehebung |
ESP_ERR_NOT_SUPPORTED (0x106) |
Die Funktion oder Eigenschaft existiert auf dieser Linie / Firmware / diesem Modul nicht: jeder rbamp_std_*-Aufruf auf einem BASIC-Handle, Blind- / Scheinleistung auf BASIC, rbamp_read_digest auf STD oder ohne die Digest-Fähigkeit, Periodenaufrufe auf einem STD-Modul ohne Snapshot-Bänke und ohne Zähler, rbamp_factory_reset auf STD, eine zu alte Version der Registerabbildung, OTA ohne die Fähigkeit |
rbamp_line(dev), rbamp_std_info() und rbamp_variant(dev) prüfen |
ESP_ERR_NOT_FOUND |
Nichts vorhanden: rbamp_std_probe — an der Adresse bestätigt nichts; kein solcher Verlaufs- / Ereignisdatensatz; kein Zertifikat oder Geräteschlüssel; Adress-Commit — an der neuen Adresse antwortet nichts (das Handle behält die alte) |
Verdrahtung/Adresse prüfen; back nur bis rbamp_std_hist_info().count zurückgehen |
ESP_ERR_INVALID_RESPONSE (0x108) |
Periodensnapshot veraltet (Ready-Flag = 0) oder eine übersprungene Periode (STD-Zähler neu verankert, Bank neu scharf gestellt); REG_VERSION = 0/0xFF bei rbamp_begin; ein Float ist am Plausibilitätsfilter gescheitert; STD-Netzfrequenz 0 (kein Netz); rbamp_std_probe — etwas antwortet, das kein STD-Modul ist |
Abschnitt „Periodensnapshots sind immer veraltet“ / „rbamp_begin kann nicht verlassen werden“ in 10 · Fehlerbehebung |
ESP_ERR_NO_MEM (0x101) |
Speicher für das Handle konnte nicht reserviert werden; mehr als 4 DRDY-Leitungen / 8 Handles pro Leitung | das Heap-Budget prüfen |
ESP_ERR_NOT_FINISHED |
STD: Der Flash-Schreibvorgang des Moduls ist ratenbegrenzt | Wiederholung nach etwa 5 s |
ESP_ERR_INVALID_CRC, ESP_ERR_INVALID_MAC, ESP_ERR_INVALID_VERSION, ESP_ERR_INVALID_SIZE, ESP_ERR_NOT_ALLOWED |
STD-Befehl / OTA-Urteile: eine Wert- oder Image-Prüfung ist fehlgeschlagen, die Authentifizierung ist fehlgeschlagen, das Image ist älter als das laufende, das Image passt nicht in die Bank, das Modul hat den Vorgang abgelehnt (siehe rbamp_std_command, rbamp_std_ota_commit) |
rbamp_std_ota_diag() für den Grund |
Alle Rückgabecodes lassen sich über rbamp_err_to_str() lesbar ausgeben.
Konfiguration zur Kompilierzeit (Kconfig)
Die folgenden CONFIG_RBAMP_*-Symbole sind in idf.py menuconfig verfügbar → Komponentenkonfiguration → rbAmp-Client (Component config → rbAmp client):
| Symbol | Typ | Bereich / Auswahl | Standard | Zweck |
|---|---|---|---|---|
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ |
int | 50000–1000000 Hz | 50000 | SCL-Frequenz. 50 kHz ist die Vorgabe für die aktuelle Firmware auf dem ESP32. |
CONFIG_RBAMP_I2C_TIMEOUT_MS |
int | 10–1000 ms | 100 | Timeout von i2c_master_transmit/receive. Er muss lang genug sein, um die Vorlauflatenz des Moduls aufzufangen. |
CONFIG_RBAMP_I2C_SCL_WAIT_US |
int | 2000–60000 µs | 10000 | Toleranz für das Clock-Stretching bei SCL: wie lange der I²C-Peripheriebaustein es zulässt, dass das Modul SCL auf LOW hält, bevor er die Transaktion aufgibt. Der Treiberstandard ist 2 ms; ein Modul dehnt SCL länger, während es einen Flash-Sektor bei einem Firmware-Update löscht, und jede solche Dehnung würde in einer Logzeile „I2C hardware timeout“ und einem Retry enden. 10 ms deckt das Löschen eines Sektors ab. Der ursprüngliche ESP32 kann nicht länger als etwa 13 ms warten (20-Bit-Hardwarezähler); die Komponente begrenzt den Wert auf diesem Ziel entsprechend. |
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS |
int | 1–10 | 3 | Versuche je Einbyte-Lesevorgang. |
CONFIG_RBAMP_NACK_RETRY_GAP_MS |
int | 1–100 ms | 5 | Pause zwischen Wiederholungsversuchen. |
CONFIG_RBAMP_BUS_RESET_ON_RETRY_EXHAUSTION |
bool | n/y | n | Schlagen alle NACK-Wiederholungen einer Transaktion fehl, rufen Sie i2c_master_bus_reset() einmal vor dem letzten Versuch auf. Der IDF-Treiber setzt seine Zustandsmaschine nach jeder fehlgeschlagenen Transaktion ohnehin zurück, und der explizite Reset nimmt keine Bussperre: Bei mehreren Tasks, die sich den Bus teilen, kann er die Transaktion einer anderen Task unterbrechen (auf dem ESP32 erzeugt er ein STOP auf den Pins, das der Interrupt-Handler des Treibers für das Ende eines Lesevorgangs halten kann). Weglassen, außer der Master ist Single-Task und der Bus bleibt nach Treiberfehlern nachweislich blockiert. |
CONFIG_RBAMP_SCT_RATING_CORRECTION |
bool | n/y | y | Korrigiert SCT-013-Messwerte auf BASIC-Firmware bis 1.4.19, die die 30-A-Kalibrierung beibehält, nachdem der Benutzer den Kanal auf ein anderes Modell umstellt. Die Bibliothek skaliert Strom, Leistung, Periodenleistung, Energie und Digest auf das gewählte Modell (rbamp_sct_correction() meldet das Ergebnis pro Kanal). Ein Modul, das sich selbst korrigiert (Firmware 1.4.20 und neuer), ist nicht betroffen. Zum Ausschalten, um die Rohwerte des Moduls zu lesen. Siehe SCT-013-Nennwertkorrektur. |
CONFIG_RBAMP_DRDY_POLL_MS |
int | 5–50 ms | 20 | Hat ein Handle keinen DRDY-GPIO, fragt rbamp_wait_data_ready() den Publish-Zähler des Moduls (STD) bzw. die Commit-Sequenz (BASIC) in diesem Intervall ab. Das Modul veröffentlicht alle 100 ms (ältere Images: 200 ms). |
CONFIG_RBAMP_DISABLE_ENERGY |
bool | n/y | n | Entfernt den Wh-Akkumulator vollständig aus der Kompilierung (sowohl Speicher als auch API). |
CONFIG_RBAMP_LOG_LEVEL_* |
Wahl | NONE / ERROR / WARN / INFO / DEBUG | INFO | Compile-Zeit-LOG_LOCAL_LEVEL für das Tag rbamp. Bestimmt, ob die Log-Zeichenketten überhaupt in das Binary kompiliert werden; unabhängig von CONFIG_LOG_DEFAULT_LEVEL. |
Eine Beispiel-sdkconfig.defaults für ein typisches Produktionsszenario:
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=3
CONFIG_RBAMP_NACK_RETRY_GAP_MS=5
CONFIG_RBAMP_I2C_TIMEOUT_MS=100
CONFIG_RBAMP_LOG_LEVEL_INFO=y
# leave CONFIG_RBAMP_DISABLE_ENERGY disabled (default n)
Für einen Bench-Test unter starker Last:
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=5
CONFIG_RBAMP_I2C_TIMEOUT_MS=200
CONFIG_RBAMP_LOG_LEVEL_DEBUG=y
Einschwingzeitkonstanten
Die Komponente verwendet intern folgende Abklingzeiten, wenn sie Befehle ausführt (für Anwender, die über der Roh-API mit i2c_master_transmit_receive arbeiten und dieselben Zeiten einhalten wollen):
Die Bibliothek exportiert eine kleine Gruppe von Abklingzeit-Konstanten (ms) für Anwender der Roh-API, die Befehle direkt an das Gerät senden und warten müssen, bis das Gerät die Verarbeitung abgeschlossen hat, bevor sie die betroffenen Register lesen. Die Wrapper-Funktionen der Komponente (rbamp_save_gains, rbamp_factory_reset, rbamp_set_ct_model_ch usw.) halten intern die korrekte Verzögerung ein — diese Konstanten werden nur benötigt, wenn Sie die Wrapper umgehen.
| Makro | Zweck | ms |
|---|---|---|
RBAMP_SETTLE_MS_LATCH_PERIOD |
Nach CMD_LATCH_PERIOD |
50 |
RBAMP_SETTLE_MS_RESET |
Nach CMD_RESET |
100 |
RBAMP_SETTLE_MS_SAVE_GAINS |
Nach CMD_SAVE_GAINS (Flash-Löschung + Schreiben) |
700 |
RBAMP_SETTLE_MS_FACTORY_RESET |
Nach CMD_FACTORY_RESET |
1500 |
RBAMP_SETTLE_MS_SET_CT_MODEL_CH0 |
Nach CMD_SET_CT_MODEL_CH0 |
5 |
RBAMP_SETTLE_MS_SET_CT_MODEL_CH1 |
Nach CMD_SET_CT_MODEL_CH1 |
5 |
RBAMP_SETTLE_MS_SET_CT_MODEL_CH2 |
Nach CMD_SET_CT_MODEL_CH2 |
5 |
Die Quelle der Wahrheit ist der Block @defgroup rbamp_settle_ms in include/rbamp.h. Die Zahlen sind die Spezifikationsminima des rbAmp-Protokolls; kürzer geht es nicht, länger ist erlaubt.
Details zum Drahtprotokoll
Registerlesezugriffe — automatisches Inkrement
Ein Burst-Lesevorgang liefert N aufeinanderfolgende Bytes ab addr. Beispiel: eine einzelne Transaktion i2c_master_transmit_receive(slave, {0x86}, 1, buf, 16, ...) liest 16 Bytes ab 0x86 (U_RMS + U_PEAK + I_RMS + I_PEAK auf UI1).
Registerschreibvorgänge — Byte für Byte (NICHT automatisch erhöht)
landetnur das erste Byte— die Bytes 1..N werden verworfen.
Ein Mehrbyte-Register wird Byte für Byte geschrieben — eine eigene einbyte I²C-Transaktion pro Adresse:
/* WRONG — data loss */
uint8_t label[8] = "MyMeter1";
uint8_t buf[9] = { 0x68, 'M', 'y', 'M', 'e', 't', 'e', 'r', '1' };
i2c_master_transmit(slave, buf, 9, 100); /* only 'M' lands */
/* CORRECT — byte-at-a-time loop */
for (int i = 0; i < 8; i++) {
uint8_t tx[2] = { 0x68 + i, label[i] };
i2c_master_transmit(slave, tx, 2, 100);
}
Dies betrifft beschreibbare Mehrbyte-Register: LABEL (0x68-0x6F), U_GAIN / I_GAIN (f32, werkseitig gesperrt), NF (u16), THRESH (u16). Lesevorgänge sind als Burst zulässig (die automatische Adressinkrementierung funktioniert beim Lesen).
Lesen nicht zugeordneter Register
Jeder Lesezugriff auf eine nicht abgebildete Adresse liefert 0x00. Die Firmware quittiert Registerlesezugriffe nie mit NACK. Das Erkennen eines fehlenden Geräts muss über das ACK des I²C-Adressrahmens laufen, nicht über das Abfragen von Registern.
Variantenerkennung
Das maßgebliche SKU-Byte ist das Register 0x55 (zwischengespeichert als rbamp_variant()):
| 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) |
0x08 |
UI7 (7× I + U) |
rbamp_topology() ist ergänzend; es liefert nur die Kanalzahl (1/2/3/5/7) und unterscheidet das Vorhandensein von U nicht.
⚠ REG_SENSOR_CLASS (0x25) ist KEIN Varianten-Unterscheidungsmerkmal (es wird durch die Benutzerkonfiguration bereitgestellt). Die Varianten-Invariante = HW_VARIANT (0x55) + CAPABILITY (0x57/0x58) — beide nur lesbar.
CAPABILITY (0x57/0x58, u16 LE) — Feature-Erkennungskarte
Eine Karte der Fähigkeiten des Geräts (zum Beispiel: Spannungsfrontend vorhanden, General-Call-Snapshot unterstützt, Digest-Block, Ereignisflags, zweiphasiger Adresswechsel). Der kanonische Weg zur Funktionserkennung (statt eines numerischen Versionsvergleichs). Prüfen Sie einzelne Fähigkeitsflags über die Hilfsfunktionen; die Menge der Flags wächst mit der Modul-Firmware.
has_voltage (ohne HW_VARIANT zu lesen):
/* Option 1 — the cached helper (no bus traffic after rbamp_begin). */
bool has_voltage = rbamp_has_voltage(dev);
/* Option 2 — read the full 16-bit CAPABILITY (LE). */
uint16_t cap;
rbamp_read_capability(dev, ∩);
bool has_voltage_2 = (cap & RBAMP_CAP_ZC_PHASE_OFFSET) != 0; /* voltage front-end flag */
Beide Optionen sind gleichwertig.
HW_VARIANT ⟷ CAPABILITY-Kohärenz: HW_VARIANT 1..3 (UI) → Spannungs-Frontend-Flag gesetzt; HW_VARIANT 4..6 (I) → Flag gelöscht. Eine Inkonsistenz = eine Hardware-Anomalie.
Atomarität / Lese-Einfrierung (B1)
- V03-Float-RMS-Block (0x86+: U_RMS, U_PEAK, I_RMS, I_PEAK, P, PF, Frequenz) — Lese-Einfrieren vorhanden, der Burst-Lesevorgang ist atomar.
- Digest-Block (0x70-0x85) — Lese-Einfrieren vorhanden.
- GC_TICK (0x59) / Adressspiegel (0x30) / CT-Modellspiegel (0x51-0x53) — ohne Lese-Einfrieren; für einen verlässlichen Lesevorgang verwenden Sie das Muster Zweimal-lesen-und-übereinstimmen (zweimal lesen, den Wert nur gültig werten, wenn beide Lesevorgänge übereinstimmen).
NF-Zangen-Semantik
I_RMS = 0x00000000 bedeutet „Signal unter dem Grundrauschen“ (die Firmware berechnet rms_corr² = max(0, raw² − nf²)), NICHT „keine Daten“ / „Fehler“. Das ist eine gültige Messung für Szenarien ohne Last.
Nur-Spannungs-Register auf Varianten nur mit Strom
U_RMS, U_PEAK auf I1/I2/I3 liefern 0. Sie sind nur gültig, wenn das Flag des Spannungsfrontends in CAPABILITY gesetzt ist. REG_AC_FREQ stammt aus der Nulldurchgangserkennung (ZC) und ist auf allen Varianten verfügbar (auch I*).
General-Call-Broadcast-Snapshot (Synchronisierung mehrerer Module)
Pro Modul aktivierbar über bit0 des Registers REG_FLEET_CONFIG (0x27) — GC_ENABLE. Standard AUS. Aktiviert über CMD_SAVE_USER_CONFIG + CMD_RESET (weich oder hart). Nach einem Reset lauscht das Modul auf den Broadcast-Rahmen an der I²C-General-Call-Adresse 0x00:
addr=0x00 | A5 27
A5— Magic-Wert.27— der OpcodeCMD_LATCH_PERIOD.—0x00= All-Call, sonst muss es mitREG_GROUP_ID(0x28) übereinstimmen.— ein 16-Bit-Periodenzähler (Master-Synchronisation).
Der Rahmen löst nur den Periodensnapshot aus; er trägt niemals zerstörerische Opcodes.
Erkennung von Fehlermodi (zweistufig, C.10 HW-bestätigt):
- GC-Adress-NACK (sofort, auf Busebene): Wenn GC an der gesamten Fleet deaktiviert ist —
i2c_master_transmitan0x00liefertESP_FAIL/ESP_ERR_INVALID_STATE. Das ist ein harter Fehler, kein stiller Verwurf. Die Bibliothek wertet das NACK als „GC nicht aktiviert“ (sie verlangt die Vorbedingungen Aktivieren + Reset). - Pro-Modul-Zeugenprüfung (nach dem Einschwingen): Wenn kein NACK aufgetreten ist — der Master liest
REG_V03_PERIOD_VALID (0x07)auf jedem erwarteten Slave:1= Snapshot erfolgreich,0= GC auf diesem konkreten Modul deaktiviert oder die Periode leer.
Links
- 05 · Schnellstart — Ihr erstes funktionierendes Projekt
- 06 · Beispiele — funktionierende Szenarien
-
10 · Fehlerbehebung — Fehlercodes entschlüsseln und gängige Probleme lösen
-
Die Quelldatei des Headers mit Doxygen-Kommentaren:
include/rbamp.h
Anhang — Unter der Haube
Aus dem Überblickskapitel übernommen: Vergleich auf Registerebene, Architektur- und Interaktionsdiagramme.
Ohne die Komponente (direkter Zugriff über i2c_master_transmit_receive)
// Read U_RMS — a single 4-byte burst-read (the firmware supports
// address auto-increment on read).
i2c_master_dev_handle_t slave;
i2c_master_bus_add_device(bus, &(i2c_device_config_t){
.device_address = 0x50, .scl_speed_hz = 50000,
}, &slave);
uint8_t reg = 0x86, buf[4] = { 0 };
if (i2c_master_transmit_receive(slave, ®, 1, buf, 4,
/*xfer_timeout_ms=*/100) != ESP_OK) {
return; // handle the error
}
float u_rms;
memcpy(&u_rms, buf, sizeof(float));
Mit der Komponente
float u_rms;
ESP_ERROR_CHECK(rbamp_read_voltage(dev, 0, &u_rms));
Eine Periode lesen — ohne die Komponente
// Snapshot + 50 ms settle + ready-flag check + burst-read avg_p
uint8_t latch_cmd[2] = { 0x01, 0x27 }; // REG_COMMAND, CMD_LATCH_PERIOD
ESP_ERROR_CHECK(i2c_master_transmit(slave, latch_cmd, 2, /*xfer_timeout_ms=*/100));
int64_t t_latch_us = esp_timer_get_time();
vTaskDelay(pdMS_TO_TICKS(50)); // settle
uint8_t valid_reg = 0x07, valid_byte = 0;
i2c_master_transmit_receive(slave, &valid_reg, 1, &valid_byte, 1, /*xfer_timeout_ms=*/100);
if ((valid_byte & 0x01) == 0) {
// snapshot is stale — t_latch_us STILL must be recorded,
// otherwise the next snapshot will count Wh over two periods
return;
}
// burst-read 4 bytes of avg_p (auto-increment), then assemble the float
// and integrate Wh:
// double dt_s = (esp_timer_get_time() - t_prev_latch_us) / 1e6;
// E_Wh += avg_p * dt_s / 3600.0;
Eine Periode lesen — mit der Komponente
rbamp_period_snapshot_t snap;
if (rbamp_read_period_snapshot(dev, &snap, 50, false) == ESP_OK && snap.valid) {
// snap.avg_p[0] is populated,
// rbamp_energy_wh(dev, 0) has increased by avg_p × master_dt_ms/1000/3600,
// master_dt_ms = master wall-clock dt between snapshots (canonical for energy).
// snap.latch_ms (0xEC) — diagnostic module timer, NOT for energy.
}
Intern garantiert die Komponente:
-
Ein Einschwingen von 50 ms nach
CMD_LATCH_PERIOD(konfigurierbar über den Parametersettle_ms), korrektes Auslesen des Snapshots (atomarer Snapshot auf der Modulseite). -
Vor dem Lesen eine Prüfung des Flags
REG_V03_PERIOD_VALID(das Feldsnap.valid). -
Zeitpunkt nach der Wanduhr des Masters erfassen, auch bei einem veralteten Snapshot (schützt vor doppelter Wh-Zählung beim nächsten Intervall).
-
Kanalweise Wh-Akkumulation mit doppelter Genauigkeit (der Typ
doubleim Handle). -
Automatisches Laden der Kalibrierkoeffizienten, wenn der Stromsensor über
rbamp_set_sensor_class()+rbamp_set_ct_model()gewählt wird — der Benutzer muss die internen Kalibrierregister nicht kennen.
Wann die Komponente und wann der direkte Buszugriff zu verwenden ist
| Aufgabe | Komponente | Direkter Zugriff über i2c_master_* |
|---|---|---|
| Lesen von U / I / P / PF / Frequenz | ✅ | nur zum Debuggen mit einem Logikanalysator |
| Energieabrechnung je Periode | ✅ | nur wenn Wh außerhalb der Komponente gespeichert wird (z. B. in einer Datenbank auf der Master-Seite) |
| Mehrere Module an einem Bus | ✅ (sequenzieller Snapshot + gemeinsames Einschwingen, siehe 06_examples.md) | — |
| Bidirektionale Abrechnung auf BASIC | ✅ (über RT-Lesevorgänge — siehe 06_examples.md) | die Alternative ist Ihre eigene RT-Lese-Schleife mit manueller Integration |
| Portierung auf eine andere Plattform | n/a | ✅ — siehe 09 · API-Referenz für Details zum Wire-Protokoll |
| Harte RAM-Grenze | selten relevant (~85 Bytes je Handle) | ✅ wenn selbst diese ~85 Byte kritisch sind |
Für alle typischen Aufgaben in den ersten Zeilen ist die Komponente die richtige Wahl.
Architektur
Interaktionsdiagramme
Der Ablauf von rbamp_begin()
Der erste Snapshot ist ein Primer (das Modul liefert, was seit dem Einschalten angesammelt wurde, was für die Tarifabrechnung ungeeignet ist). Die Komponente selbst vermerkt, dass dieser Snapshot verworfen werden muss — der Anwendercode sieht ihn nie.
Der Ablauf rbamp_read_period_snapshot(dev, &snap, 50, false)
Der atomare Snapshot auf der Modulseite garantiert, dass jede Messung innerhalb einer Periode in genau einem Snapshot landet — keine Doppelzählung und kein Verlust an der Periodengrenze.
Zuordnung zur direkten Register-API
Eine Tabelle für alle, die von eigenem direktem Zugriffscode migrieren:
Direkte API (i2c_master_transmit_receive) |
Gleichwertig über die Komponente |
|---|---|
Manuelles Lesen von 4 Byte + memcpy |
rbamp_read_voltage(dev, 0, &v) / rbamp_read_power(dev, ch, &p) |
tx([0x01, 0x27]); vTaskDelay(50) |
rbamp_latch_period(dev); vTaskDelay(pdMS_TO_TICKS(50)) (oder direkt rbamp_read_period_snapshot()) |
Prüfung von read_u8(0x07) & 1 |
das Feld snap.valid nach rbamp_read_period_snapshot() |
Manuelle Formel E_Wh += avg_p * dt_s / 3600 |
rbamp_energy_wh(dev, 0) — wird automatisch aktualisiert |
| Manuelle Konfiguration des Stromsensors über die direkte Register-API | rbamp_set_sensor_class(dev, cls) + rbamp_set_ct_model(dev, code) — Werkseinstellungen werden automatisch geladen |
Quelle & Issues: rb-amp/rbamp-esp-idf · diese Seite im Repo: docs/09_api_reference.md (v1.7.3)