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:
-
04 · Verdrahtung — Hardware-Details und GPIO-Standards je Chip für alle unterstützten ESP32-Chips
-
03 · Auswahl des Stromsensors — welches SCT-013-Modell zu verwenden ist und warum
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.shbzw. 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“:
idf.py set-target esp32 # or esp32s3 / esp32c3 / esp32c6 / ...
Ohne diesen Schritt schlägt der Build fehl.
Schritt 1 — Komponente zum Projekt hinzufügen
Als Git-Abhängigkeit (empfohlen)
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:
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)
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:
list(APPEND EXTRA_COMPONENT_DIRS
${CMAKE_CURRENT_LIST_DIR}/components/rbamp)
# the directory must be named `rbamp`
Die Abhängigkeit in main/
# 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.
⚠ 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 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.
#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:
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):
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
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.
/* 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.
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():
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):
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);
}
}
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):
- Sendet dem Modul den Periodensnapshot-Befehl (
CMD_LATCH_PERIOD). - Wartet
settle_ms(standardmäßig 50 ms), während das Modul den Snapshot vorbereitet. - Prüft das Bereit-Flag; liest die Mittel- / Spitzenleistung.
- Aktualisiert den internen Wh-Zähler:
+= avg_p × master_dt_s / 3600(sofern die Komponente nicht ohneCONFIG_RBAMP_DISABLE_ENERGYgebaut wurde).
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:
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
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:
#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)