02 · Modulstufen
rbAmp-Module gibt es in den Modulstufen BASIC und STANDARD (STD). Eine Modulstufe ist ein vollständiges Bündel aus Hardwarerevision und Firmware, kein Software-Flag. Der Wechsel zwischen den Stufen erfordert einen physischen SKU-Wechsel, kein Firmware-Update.
Was eine Modullinie ist
Aus Sicht der Komponente und des Anwendercodes gilt: ein Handle und eine rbamp_*-API bedienen beide ausgelieferten Modullinien. rbamp_begin() erkennt, ob das Modul hinter dem Handle ein BASIC- oder ein STD-Modul ist (rbamp_line()), und die Aufrufe, die nur auf einer der beiden existieren, liefern auf der anderen ESP_ERR_NOT_SUPPORTED. Die Unterschiede zeigen sich in den Werten, die das Modul liefert, in den zusätzlichen Größen, die das STD-Modul misst, und darin, wie die Firmware die Daten behandelt (insbesondere — die Einspeisung ins Netz).
Aktueller Status
BASIC- und STANDARD-(STD)-Module werden ausgeliefert und beide werden von dieser Komponente (Version 1.7.3) unterstützt.
| Modulstufe | Status in dieser Komponente |
|---|---|
| BASIC | ✅ im Einsatz — RBAMP_LINE_BASIC |
| STANDARD (STD) | ✅ im Einsatz — RBAMP_LINE_STD |
BASIC — Einstiegs-Modullinie für die Verbrauchsmessung
Hardware
Ein kostenoptimierter Analogpfad für typische Haushaltslasten. Das Modul enthält ein galvanisch getrenntes Analogfrontend, einen Onboard-Spannungsregler und eine im Flash gespeicherte Werkskalibrierung.
Verhalten der Firmware
Die Logik eines klassischen mechanischen Ferraris-Zählers — nur vorwärts gezählt, Einspeisung ins Netz wird nicht abgezogen.
Die drei "Ebenen" der Wirkleistungswerte verhalten sich unterschiedlich:
| Signal | Bedeutung | Verhalten bei BASIC |
|---|---|---|
rbamp_read_power(dev, ch, &p) |
momentane RT-Leistung, aktualisiert etwa alle 100 ms | vorzeichenbehaftet — ein negativer Wert ist in Echtzeit sichtbar (Einspeisung) |
snap.avg_p[ch] (innerhalb von rbamp_read_period_snapshot) |
Durchschnittsleistung über die Periode | jedes 100-ms-Fenster der mittleren P wird begrenzt auf max(P, 0), bevor es zum Periodenakkumulator addiert wird |
rbamp_energy_wh(dev, ch) |
Von der Komponente akkumulierte Wh | monoton — nur Verbrauch, Einspeisung wird nicht gezählt |
Mit anderen Worten: Der Anwender sieht die Einspeisung im RT-Messwert, aber der Wh-Zähler der Komponente auf BASIC enthält sie nicht.
Typische Anwendungen
-
Haushalte ohne eigene Erzeugung (keine Solarmodule, Windkraftanlagen, Batteriesysteme)
-
Unterzähler für rein verbrauchende Lasten (Warmwasserbereiter, Motoren, Haushaltsgeräte)
-
Verbrauchsüberwachung im Gebäude, wo bidirektionale Messung nicht nötig ist
Bidirektionale Messung auf BASIC (masterseitig)
rbamp_read_power(dev, 0, &p)ist vorzeichenbehaftet, daher:
#include "esp_timer.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
static double consume_wh = 0.0;
static double export_wh = 0.0;
void bidirectional_loop(rbamp_handle_t dev) {
int64_t t_prev_us = esp_timer_get_time();
while (1) {
/* Sample RT power at 10 Hz. Slower polling loses resolution
* on sharp load transitions; faster adds little for typical
* mixed loads with an inverter. */
vTaskDelay(pdMS_TO_TICKS(100));
int64_t t_now_us = esp_timer_get_time();
double dt_s = (double)(t_now_us - t_prev_us) / 1e6;
t_prev_us = t_now_us;
float p;
if (rbamp_read_power(dev, 0, &p) != ESP_OK) continue;
double dwh = (double)p * dt_s / 3600.0;
if (p >= 0.0f) consume_wh += dwh;
else export_wh += -dwh;
}
}
Ein vollständiges funktionierendes Beispiel für das Muster finden Sie in 06_examples.md, im Szenario „Bidirektionale Messung auf der Master-Seite“.
STANDARD (STD) — die Linie der Module mit erweiterter Messung
STD-Module werden von derselben rbamp_*-API unterstützt; rbamp_begin() erkennt sie. Zusätzlich zu dem, was BASIC bietet, liefert ein STD-Modul:
-
Vorzeichenbehaftete Energie. Bezug und Einspeisung sind getrennte Größen, und das Modul führt dauerhaft gespeicherte Lebensdauerzähler (Wh / varh, dazu feinere Auflösungen bei neueren Firmware-Versionen). Die Einspeisung wird nicht abgeschnitten: Die Energie einer Periode ist die Differenz zweier Zählerstände (
rbamp_std_read_energy()/rbamp_std_energy_delta()), undrbamp_energy_wh()liefert auf solchen Modulen einen vorzeichenbehafteten Nettowert. -
Weitere Größen: Blind- und Scheinleistung je Kanal (
rbamp_read_reactive_power(),rbamp_read_apparent_power(),rbamp_std_read_channel()), Summen je Phase und Gesamtsummen sowie — sobald die Oberschwingungsauswertung eingeschaltet ist — THD und Verschiebungs-Leistungsfaktor. Dreiphasenmodule melden außerdem die Spannungswinkel der Phasen und die Phasenfolge. -
Periodenmechanismen: Snapshot-Bänke (acht unabhängige, vom Master getaktete Perioden) auf Modulen, die sie besitzen, oder Zählerdifferenzen auf Modulen, die die Energie auf dem Gerät führen. Der Mechanismus wird bei
rbamp_begin()gewählt (rbamp_std_info_t.period_source). -
Das CT-Modell ist nur ein Etikett. Auf einem STD-Modul ist das CT-Modell nur ein Etikett und setzt keine Verstärkung.
- Modul-Uhr, Verlauf auf dem Gerät und ein Ereignisprotokoll, Zustand und Diagnose, Firmware-Update über I²C, ein Gerätezertifikat und Attestierung.
Alles dies ist in 09 · API-Referenz, Kapitel „STD line“, dokumentiert. Ein funktionierendes Beispiel ist examples/std_meter/ (siehe 06 · Beispiele, Szenario 18).
Verhalten, das sich von BASIC unterscheidet
| Thema | BASIC | STD |
|---|---|---|
Einspeisung in rbamp_energy_wh() |
nicht gezählt (monoton, nur Verbrauch) | vorzeichenbehaftet — Netto aus Bezug und Einspeisung |
| Blind- / Scheinleistung, THD | nicht verfügbar — bei BASIC stellt diese Bibliothek keine Blindleistung bereit (ESP_ERR_NOT_SUPPORTED) |
verfügbar |
| Periodenquelle | Snapshot des Periodenakkumulators | Snapshot-Bänke oder Zählerdifferenzen |
| Modul-Uhr | keine | Setzen Sie sie mit rbamp_std_set_time() nach jedem Modul-Reset |
rbamp_factory_reset() |
unterstützt | ESP_ERR_NOT_SUPPORTED |
Digest (rbamp_read_digest()) |
unterstützt auf Firmware mit der Fähigkeit | ESP_ERR_NOT_SUPPORTED |
| Periodenaufrufe auf einem Modul ohne Snapshot-Bänke und ohne Zähler | — | ESP_ERR_NOT_SUPPORTED |
Typische Anwendungen
- Haushalte mit Dachsolaranlage, Windkraftanlagen oder Batterien
- Generatorische Lasten, Ladung von Elektrofahrzeugen (V2G)
- Installationen, die neben der Wirkleistung auch Blindleistung, Leistungsfaktor und Oberschwingungen benötigen
Wie man die Modulstufe zur Laufzeit erkennt
rbamp_begin():
/* BASIC or STD — available after rbamp_begin() */
rbamp_line_t line = rbamp_line(dev); /* RBAMP_LINE_BASIC / RBAMP_LINE_STD */
/* Full SKU — cached by rbamp_begin(), no bus traffic */
rbamp_variant_t variant = rbamp_variant(dev); /* UI1 / UI2 / ... / I3 / UI5 / UI7 */
/* Voltage-sensing presence (UI* variants vs I*-only) */
bool voltage_hw = rbamp_has_voltage_hw(dev);
/* Number of current channels (1 / 2 / 3 / 5 / 7) */
uint8_t channels = rbamp_channels(dev);
/* Firmware: BASIC — REG_VERSION byte; STD — register-map version */
uint8_t fw = rbamp_firmware_version(dev);
/* STD only: identity, capabilities and the period mechanism */
rbamp_std_info_t info;
if (rbamp_line(dev) == RBAMP_LINE_STD && rbamp_std_info(dev, &info) == ESP_OK) {
/* info.capabilities, info.n_voltage, info.n_current, info.period_source */
}
: rbamp_line() unterscheidet BASIC von STD. Verwenden Sie die SKU-Bezeichnung auf dem Modulgehäuse als maßgebliche Quelle für das genaue Produkt.
Wo linienabhängige Details in der Dokumentation markiert sind
Im Komponententext und in der kanonischen Dokumentation sind linienabhängige Funktionen ausdrücklich markiert, zum Beispiel:
— diese Funktion ist auf dem Modul BASIC nicht verfügbar (ESP_ERR_NOT_SUPPORTED).
Oder umgekehrt, BASIC-spezifisches Verhalten:
: Der Zähler rbamp_energy_wh(dev, ch) ist monoton — Einspeisung ins Netz wird nicht gezählt. Für bidirektionale Messung siehe das Szenario „Bidirektionale Messung auf der Master-Seite“ in 06_examples.md, oder verwenden Sie ein STD-Modul.
Was als Nächstes kommt
-
03 · Auswahl des Stromsensors — welche SCT-013 für welche Aufgabe
-
04 · Verdrahtung — Hardware-Details
-
06 · Beispiele — Szenarien für BASIC, einschließlich der bidirektionalen Messung auf dem Master
-
09 · API-Referenz — die vollständige öffentliche API
Quelle & Issues: rb-amp/rbamp-esp-idf · diese Seite im Repo: docs/02_tiers.md (v1.7.3)