rbAmp
DE
Shop
Docs
Aktualisiert · Auf GitHub bearbeiten

05 · Schnellstart

Ein fünfminütiges Hallo Welt: Komponente in ein IDF-Projekt aufnehmen, Modul verdrahten, Sensor wählen, Ihren ersten RT-Messwert und Ihren ersten Periodensnapshot (Wh) nehmen.

Die Details (Pinbelegung für einen bestimmten ESP32-Chip, Multi-Modul-Bus, Auswahl einer SCT-013 nach Bereich) stehen in den angrenzenden Kapiteln:

Ablaufdiagramm der Schritte von der Verdrahtung bis zum ersten Messwert und dem ersten Energiewert.

Was Sie benötigen

  • Ein rbAmp-Modul (jede Modullinie; der Einfachheit halber ein UI1 — ein Spannungseingang plus ein Stromkanal; andere Varianten stehen in 03)
  • Jeder Chip der ESP32-Familie (esp32, esp32s2, esp32s3, esp32c2, esp32c3, esp32c6, esp32h2)

  • ESP-IDF v5.2+ installiert (. ~/esp/esp-idf/export.sh bzw. unter Windows %IDF_PATH%\export.bat)

  • Eine SCT-013-Stromzange, bemessen für Ihren maximalen Strom (5 A / 10 A / 30 A / 50 A / 100 A)

  • Eine 5-V-Versorgung für das Modul (von einem USB-5V-DevKitC oder extern)
  • Ein zu messender Wechselstromkreis (eine Lampe, ein Wasserkocher, ein Haushaltsgerät)

Schritt 0 — Ziel festlegen

Ist dies ein frisches ESP-IDF-Projekt und wurde idf.py set-target noch nicht ausgeführt, tun Sie das vor dem ersten idf.py build — sonst scheitert der Build mit „no target specified“:

Shell
idf.py set-target esp32      # or esp32s3 / esp32c3 / esp32c6 / ...

Ohne diesen Schritt schlägt der Build fehl.

Schritt 1 — Komponente zum Projekt hinzufügen

In der Datei main/idf_component.yml Ihres Projekts (legen Sie die Datei an, falls sie nicht existiert). Der ESP-IDF Component Manager holt das getaggte Release:

YAML
dependencies:
  rbamp:
    git: https://github.com/rb-amp/rbamp-esp-idf.git
    version: v1.7.3

Die Komponente wird beim nächsten idf.py build (oder idf.py reconfigure) heruntergeladen.

Manuell (Git-Submodul / Klon)

Shell
mkdir -p components/
cd components/
git clone https://github.com/rb-amp/rbamp-esp-idf.git rbamp

Oder den Komponentenpfad in der CMakeLists.txt der Projektwurzel ergänzen:

CMake
list(APPEND EXTRA_COMPONENT_DIRS
     ${CMAKE_CURRENT_LIST_DIR}/components/rbamp)
# the directory must be named `rbamp`

Die Abhängigkeit in main/

CMake
# main/CMakeLists.txt
idf_component_register(
    SRCS "main.c"
    INCLUDE_DIRS "."
    REQUIRES rbamp
)

Die Komponente zieht esp_driver_i2c, esp_timer und log mit — mehr braucht das einfache Szenario aus Schritt 3 nicht. Die Netzwerk-, SPIFFS- und OLED-Szenarien benötigen zusätzliche REQUIRES — siehe 06 · Beispiele, die CMakeLists-Tabelle am Anfang des Kapitels.

Schritt 2 — Verdrahtung

Vier Leitungen + optional DRDY:

rbAmp-Pin ESP32 (Standard) ESP32-S3 (Standard) ESP32-C3 (Standard)
VCC +5 V (4.5 bis 5.5 V) gleich gleich
GND GND GND GND
SDA GPIO21 GPIO8 GPIO5
SCL GPIO22 GPIO9 GPIO6

Die Versorgung muss 5 V betragen. Die I²C-Leitungen laufen mit 3.3-V-Logik — direkt kompatibel mit den GPIOs des ESP32. Die Modulplatine hat bereits eingebaute 4.7-kΩ-Pull-up-Widerstände — für ein einzelnes Modul sind keine externen nötig.

Die vollständige Pinbelegungstabelle für jeden ESP32-Chip steht unter 04 · Verdrahtung.

Sicherheit

⚠ Netzspannung kann tödlich sein. Schalten Sie den Stromkreis ab und sichern Sie ihn gegen Wiedereinschalten, bevor Sie die L/N-Klemmen anschließen oder die Zange anbringen; lassen Sie Netzanschlussarbeiten und jede Arbeit im Verteilerkasten von einer Elektrofachkraft ausführen. Klemmen Sie NUR EINEN Leiter (L) ein — niemals das ganze Kabel. Sichern Sie die L-Abzweigung gemäß den örtlichen Vorschriften ab.

Die SCT-013-CT-Zange legt sich um den Außenleiter (L), wobei der Pfeil am Zangenkörper in Stromflussrichtung zur Last hin zeigt. Ein UI-Modul braucht zusätzlich seine L/N-Spannungsverbindung; die CT-Zange steckt in die 3.5-mm-CT-Buchse des Moduls (auf der Platine beschriftet I0, I1, …); die Netzseite hat die Klemmen L und N. Siehe 04 · Verdrahtung, „Netz- und CT-Anschluss“.

Schritt-für-Schritt-Anschluss des Netzabgriffs und der Zange.

Schritt 3 — Erstes Projekt (erster Messwert)

Eine minimale main/main.c: den Bus in Betrieb nehmen, dem Modul mitteilen, welche CT-Zange Sie angebracht haben, und einmal pro Sekunde U / I / P / PF ausgeben.

C
#include 
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/i2c_master.h"
#include "esp_log.h"
#include "rbamp.h"

static const char *TAG = "app";

void app_main(void) {
    const i2c_master_bus_config_t bus_cfg = {
        .i2c_port  = I2C_NUM_0,
        .sda_io_num = GPIO_NUM_21,            /* ESP32 — adjust for your chip */
        .scl_io_num = GPIO_NUM_22,
        .clk_source = I2C_CLK_SRC_DEFAULT,
        .glitch_ignore_cnt = 7,
        .flags.enable_internal_pullup = true, /* optional with the module's own pull-ups */
    };
    i2c_master_bus_handle_t bus;
    ESP_ERROR_CHECK(i2c_new_master_bus(&bus_cfg, &bus));

    rbamp_handle_t dev = NULL;
    ESP_ERROR_CHECK(rbamp_new(bus, 0x50, &dev));    /* default address 0x50 */

    /* rbamp_begin blocks while it tries to reach the slave;
     * it runs a primer-snapshot and a valid-check, ~250 ms. */
    while (rbamp_begin(dev) != ESP_OK) {
        ESP_LOGE(TAG, "rbAmp not responding — check wiring and power");
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
    ESP_LOGI(TAG, "Module ready.");

    /* Sensor configuration (see Step 4): class first, then model.
     * Code 3 = SCT-013-030; use the code of the clamp you fitted. */
    if (rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013) != ESP_OK ||
        rbamp_set_ct_model(dev, 3) != ESP_OK) {
        ESP_LOGE(TAG, "sensor configuration failed");
        return;
    }
    ESP_LOGI(TAG, "Sensor configured.");

    while (1) {
        float u = NAN, i = NAN, p = NAN, pf = NAN;
        if (rbamp_read_voltage(dev, 0, &u)        != ESP_OK) u  = NAN;
        if (rbamp_read_current(dev, 0, &i)        != ESP_OK) i  = NAN;
        if (rbamp_read_power(dev, 0, &p)          != ESP_OK) p  = NAN;
        if (rbamp_read_power_factor(dev, 0, &pf)  != ESP_OK) pf = NAN;

        ESP_LOGI(TAG, "U=%.1f V  I=%.3f A  P=%.1f W  PF=%.3f",
                 (double)u, (double)i, (double)p, (double)pf);
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

Bauen, flashen und den Monitor öffnen:

Shell
idf.py build
idf.py -p /dev/ttyUSB0 flash monitor

(Unter Windows — idf.py -p COM3 ....)

Erwartete Ausgabe bei eingeschalteter Last (die Werte hängen von Ihrer Last ab):

Text
I (1234) app: Module ready.
I (2634) app: Sensor configured.
I (3634) app: U=230.4 V  I=0.523 A  P=119.8 W  PF=0.987
Sicherheit

U zeigt ungefähr die Netzspannung (220–240 V bei 230-V-Netzen) — das bedeutet, dass das Modul richtig verdrahtet ist.

Wenn I bei einer Last auf 0.000 A bleibt: Das Modul kennt die verwendete CT-Zange nicht (der Schritt der Sensorkonfiguration wurde übersprungen oder schlug fehl) — ohne ihn bleiben die Stromwerte bei null. PF ist undefiniert, wenn I=0 ist, und kann nan, 0 oder einen Platzhalter zeigen; ignorieren Sie ihn, bis der Strom ungleich null ist. Siehe 10 · Fehlerbehebung, „Current reads zero on a working load“ (Strom liest bei arbeitender Last null).

Schritt 4 — Was die Sensorkonfiguration tut

Die beiden Aufrufe in Schritt 3 teilen dem Modul Klasse und Modell des Sensors mit. Ohne sie werden die Kalibrierkoeffizienten nicht geladen, und die Stromwerte bleiben bei null. Die Reihenfolge ist wichtig: zuerst die Klasse, dann das Modell.

C
/* Step A: sensor class. The current rbAmp SKU uses SCT-013 clamps. */
rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013);
/* Step B: model. For example, SCT-013-030 for a household feed up to ~7 kW. */
rbamp_set_ct_model(dev, 3);

Modellcodes:

code Modell Bereich Typische Anwendung
1 SCT-013-005 0..5 A Kleine Lasten, eine einzelne Steckdose
2 SCT-013-010 0..10 A Kühlschrank, Waschmaschine
3 SCT-013-030 0..30 A Haushaltseinspeisung bis ca. 7 kW
4 SCT-013-050 0..50 A Ladestation für E-Autos, elektrische Heizung
5 SCT-013-100 0..100 A Hauptanschluss eines Hauses oder eines kleinen Büros
6 SCT-013-020 0..20 A Warmwasserboiler, Heizkessel, große Haushaltsgeräte
7 SCT-013-060 0..60 A Industrieller Unterzähler

Mehr zur Auswahl (inklusive der übrigen unterstützten Codes) — 03 · Auswahl des Stromsensors.

Hinweis

Diese beiden Aufrufe erfolgen einmal bei der Erstinstallation — die Wahl wird im Flash des Moduls gespeichert und überlebt einen Reset. Die Gesamtzeit beträgt etwa 1.4 Sekunden (zwei Flash-Schreibvorgänge × ~700 ms je Vorgang).

Bei späteren Firmware-Läufen können Sie rbamp_set_sensor_class() und rbamp_set_ct_model() überspringen (das Modul merkt sich die Werte). Schadet aber auch nicht — ein erneuter Aufruf mit demselben Wert schreibt nichts.

Schritt 5 — Energieabrechnung (Wh)

Das Modul liefert nur Momentanwerte + die Durchschnittsleistung über eine Periode. Die Wh selbst berechnet die Komponente aus esp_timer_get_time():

Text
E_Wh += avg_P × master_dt_s / 3600
        [W]    [seconds]      →  [Wh]

wobei master_dt_s die Anzahl Sekunden zwischen zwei erfolgreichen Aufrufen von rbamp_read_period_snapshot() ist. Die Komponente hält den Zeitstempel des letzten Snapshots im Handle und berechnet die Differenz selbst.

Eine minimale Vorlage für periodische Abrechnung (einmal pro Minute):

C
void app_main(void) {
    /* ...bus + rbamp_new + rbamp_begin + set_sensor_class + set_ct_model (Step 3)... */

    while (1) {
        vTaskDelay(pdMS_TO_TICKS(60000));   /* 60-second period */

        rbamp_period_snapshot_t snap;
        esp_err_t err = rbamp_read_period_snapshot(dev, &snap, 50, false);
        if (err != ESP_OK || !snap.valid) {
            ESP_LOGW(TAG, "snapshot error: %s", rbamp_err_to_str(err));
            continue;
        }

        ESP_LOGI(TAG, "avg P over period: %.2f W   accumulated: %.4f Wh   dt=%u ms",
                 (double)snap.avg_p[0],
                 rbamp_energy_wh(dev, 0),
                 (unsigned)snap.master_dt_ms);
    }
}
Hinweis

Nach Schritt 3 wurden die Aufrufe rbamp_set_sensor_class() und rbamp_set_ct_model() bereits einmal ausgeführt und im Flash des Moduls gespeichert; in der obigen Vorlage stehen sie für einen erneuten Lauf der Firmware — das Modul ignoriert einen wiederholten Aufruf mit demselben Wert. Die Fehlerbehandlung ist der Kürze halber teilweise weggelassen — ergänzen Sie zusätzliche if (err != ESP_OK)-Prüfungen, wenn Sie beim Start die seltenen Kommunikationsstörungen abfangen wollen.

Was rbamp_read_period_snapshot() im Hintergrund tut (mit skip_latch=false):

  1. Sendet dem Modul den Periodensnapshot-Befehl (CMD_LATCH_PERIOD).
  2. Wartet settle_ms (standardmäßig 50 ms), während das Modul den Snapshot vorbereitet.
  3. Prüft das Bereit-Flag; liest die Mittel- / Spitzenleistung.
  4. Aktualisiert den internen Wh-Zähler: += avg_p × master_dt_s / 3600 (sofern die Komponente nicht ohne CONFIG_RBAMP_DISABLE_ENERGY gebaut wurde).
Der Wh-Zähler liegt im RAM.

rbamp_energy_wh() startet nach jedem Reset oder Stromausfall des ESP32 bei 0 neu; speichern Sie den Wert selbst, wenn er ihn überleben soll (siehe 06 · Beispiele, Szenario 13).

Der erste Aufruf nach rbamp_begin() ist ein Primer: Das Modul liefert, was es seit dem Einschalten angesammelt hat (ein Intervall, das für die Tarifabrechnung ungeeignet ist). Die Komponente weiß selbst, dass dieser Snapshot verworfen werden muss — Anwendercode sieht ihn nie.

Erwartete Ausgabe:

Text
I (61234) app: avg P over period: 120.18 W   accumulated: 2.0036 Wh   dt=60012 ms
I (121234) app: avg P over period: 120.21 W   accumulated: 4.0073 Wh   dt=60005 ms
...

Schritt 6 — Schnellstart für eine Flotte aus N Modulen

Dieser Schnellstart zeigt die Arbeit mit einem einzelnen Modul. Das eigentliche kanonische Szenario der Bibliothek sind mehrere Module an einem Bus unter einem einzigen Flotten-Handle (Netzanschluss + N Teillasten). Das vollständige Beispiel steht in 06 · Beispiele, Szenario 1. > Voraussetzungen für eine Flotte. Alle Module werden auf der Adresse 0x50 ausgeliefert, und

Sicherheit

rbamp_fleet_scan schließt Module aus, die dieselbe Adresse teilen. Geben Sie jedem Modul zuerst eine eigene Adresse, jeweils nur ein Modul am Bus (06 · Beispiele, Szenario 2, rbamp_provision), und stellen Sie auf jedem Modul die Sensorklasse und das CT-Modell ein (03). Andernfalls kommt die Fleet leer oder mit Ausschlüssen hoch, und Ströme liefern 0. Leistung und Wh brauchen eine UI-Variante: Eine Bilanz „Netz minus Summe der Lasten“ braucht ein UI-Modul an jeder Last.

Ein minimales Fleet-Grundgerüst:

C
#include "rbamp_fleet.h"

void app_main(void) {
    /* ... bus init as in Step 3 ... */

    rbamp_fleet_t fleet;
    ESP_ERROR_CHECK(rbamp_fleet_create(bus, &fleet));

    size_t added = 0;
    esp_err_t scan = rbamp_fleet_scan(fleet, /*match_product=*/true, &added);
    if (scan == ESP_ERR_INVALID_STATE) {
        ESP_LOGE("app", "bus wedged — see ch.10 \"Fleet: INVALID_STATE\"");
        return;
    }
    ESP_LOGI("app", "fleet: %u modules; excluded: %u",
             (unsigned)added,
             (unsigned)rbamp_fleet_excluded_count(fleet));

    rbamp_snapshot_t snaps[RBAMP_FLEET_MAX_MODULES];
    rbamp_fleet_poll_t status[RBAMP_FLEET_MAX_MODULES];

    while (1) {
        size_t n_ok = 0;
        rbamp_fleet_poll_all(fleet, snaps, status,
                             RBAMP_FLEET_MAX_MODULES, &n_ok);

        float p_total;
        rbamp_fleet_total_power(fleet, &p_total);
        ESP_LOGI("app", "fleet: %u/%u modules OK, total P = %.1f W",
                 (unsigned)n_ok, (unsigned)rbamp_fleet_count(fleet), p_total);

        vTaskDelay(pdMS_TO_TICKS(200));
    }
}

Im kanonischen 80-%-Szenario ist eines der Module eine UI1 am Netzanschluss (sie liefert total_power und total_energy_wh), die übrigen sind I2/I3-Teilzähler für den Strom (nur Strom — keine Leistung oder Wh; verwenden Sie UI-Module, wo Sie Leistung oder Energie je Last brauchen). Die Details und fortgeschrittenen Szenarien (Aufteilung Netz + Teillasten, GC-Synchronisation für enge Snapshots, der Provisionierungsablauf) stehen in Kapitel 06.

Was als Nächstes kommt

  • 01 · Überblick — was rbAmp ist und was die Komponente leistet
  • 02 · Modulstufen — welche Stufe für welche Aufgabe
  • 06 · Beispiele — funktionierende Szenarien: Netz + N Teillasten (der 80-%-Kanon), Provisionierungsablauf, Mehrkanal mit gemischter CT, Flotten-GC-Sync, MQTT, Deep-Sleep

  • 07 · DIY-Integrationen — Home Assistant / Node-RED / OpenHAB

  • 08 · Cloud-Integrationen — AWS IoT / Azure / GCP / InfluxDB Cloud

  • 09 · API-Referenz — die vollständige öffentliche API (einschließlich Fleet-Manager + Fleet-Konfiguration je Gerät + Mehrkanal-Konfiguration + Fehlermodell v1.3 + Identifikation und Bereitstellung)

  • 10 · Fehlerbehebung — wenn etwas nicht funktioniert (Abschwächung gegen I²C-Hänger in drei Stufen, Flotten-Konflikt / Blockade / Provisionierungsfehler)


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