rbAmp
DE
Shop
Docs
Aktualisiert · Auf GitHub bearbeiten

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

Die Modullinien BASIC und STANDARD (STD) im Vergleich.

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)

Wie Energie auf einem BASIC-Modul entsteht (auf dem Master integriert) und auf einem STANDARD-Modul (STD) (geräteinterne Zähler).
Wenn Sie die Einspeisung ins Netz auf einem BASIC-Modul getrennt erfassen müssen,auf der Masterseite tun. Die RT-Leistungrbamp_read_power(dev, 0, &p)ist vorzeichenbehaftet, daher:

C
#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()), und rbamp_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

Ablaufdiagramm, um herauszufinden, ob Sie ein BASIC- oder ein STANDARD-(STD)-Modul besitzen.
Die Produktlinie wird für Sie erkannt durchrbamp_begin():

C
/* 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 */
}
Hinweis

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

Nur STD

— diese Funktion ist auf dem Modul BASIC nicht verfügbar (ESP_ERR_NOT_SUPPORTED).

Oder umgekehrt, BASIC-spezifisches Verhalten:

BASIC

: 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


Quelle & Issues: rb-amp/rbamp-esp-idf · diese Seite im Repo: docs/02_tiers.md (v1.7.3)