rbAmp
DE
Shop
Docs
Aktualisiert · Auf GitHub bearbeiten [Edit on GitHub]

05 · Schnellstart

Ein Fünf-Minuten-Hallo-Welt: installieren Sie die Bibliothek, verdrahten Sie das Modul, wählen Sie einen Sensor, nehmen Sie Ihre erste RT-Messung und Ihren ersten Periodensnapshot (Wh) auf.

Die Einzelheiten (Pinbelegung für einen bestimmten Host, Mehrmodul-Bus, Auswahl eines SCT-013 nach Bereich) stehen in den benachbarten Kapiteln:

Erste Messung in acht Schritten: verdrahten, einschalten, nach 0x50 scannen, begin(), optionale Sensoreinrichtung, U, I, P, PF lesen, Plausibilitätsprüfung, dann Energie.

Was Sie benötigen

  • Ein rbAmp-Modul (beliebige Stufe, der Einfachheit halber UI1)
  • Ein Arduino-kompatibler Host — UNO / Mega / ESP32 / ESP8266 / STM32duino / RP2040
  • Eine SCT-013-Zange mit einem Nennwert oberhalb Ihres größten erwarteten Stroms (5 A / 10 A / 30 A / 50 A / 100 A) — oder der Stromwandler, der an Ihrem Modul angeschlossen ist
  • Eine 5-V-Versorgung für das Modul (vom USB-5V des Hosts oder extern)
  • Ein zu messender Wechselstromkreis (eine Lampe, ein Wasserkocher, ein Haushaltsgerät)

Schritt 1 — Bibliothek installieren

Arduino IDE — Bibliotheksverwaltung

Sketch → Bibliothek einbinden → Bibliotheken verwalten… → nach RbAmp suchen → Installieren. Es gibt keine Abhängigkeiten. Nach der Installation erscheinen die Beispiele unter Datei → Beispiele → RbAmp [Sketch → Include Library → Manage Libraries; File → Examples].

Arduino CLI

Shell
arduino-cli lib install RbAmp

PlatformIO

INI
[env:esp32dev]
platform   = espressif32
framework  = arduino
lib_deps   = rbamp/RbAmp@^1.6.1

Schritt 2 — Verdrahtung

Sicherheit

⚠ Netzspannung kann tödlich sein. Trennen und sichern Sie den Stromkreis, bevor Sie die L/N-Klemmen anschließen oder die Zange anbringen; lassen Sie Netzverdrahtung und jede Arbeit im Verteilerkasten von einer Fachkraft ausführen. Umschließen Sie NUR EINEN Leiter (L) — niemals das ganze Kabel (L und N heben sich auf ca. 0 auf). Sichern Sie die L-Abzweigung gemäß den örtlichen Vorschriften ab.

Vier Niederspannungsleitungen plus optional DRDY, dann die Netzklemmen:

rbAmp-Pin Host
VCC +5 V (Bereich 4.5..5.5 V)
GND GND
SDA I²C SDA (UNO A4, ESP32 GPIO21, STM32duino PB7)
SCL I²C SCL (UNO A5, ESP32 GPIO22, STM32duino PB6)
DRDY (optional) für den ersten Sketch überspringen; siehe 04_hardware.md
Klemmen L, N derselbe Stromkreis, der die gemessene Last speist (Netzseite — siehe die Warnung oben)
CT-Buchse SCT-013-Stecker bis zum Anschlag eingesteckt

Die Versorgung muss 5 V betragen. Die I²C-Leitungen laufen mit 3.3-V-Logik, sind aber 5-V-tolerant — verbinden Sie sie direkt mit einem Arduino UNO ohne Pegelwandler. 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 Pin-Belegung für jeden Arduino-Host finden Sie unter 04 · Verkabelung.

Die SCT-013-Zange klemmt nur um den Außenleiter (L), wobei der Pfeil am Zangenkörper in Stromrichtung zum Verbraucher zeigt. Für mehr Details (Abschnitt „Stromsensor“) siehe Kapitel 04 · Verdrahtung.

Netzseitiger Anschluss: die CT-Zange nur am L-Leiter mit dem Pfeil zur Last, und der Abgriff der L/N-Spannungsreferenz.

Schritt 3 — Erster Sketch (RT-Messwerte)

Ein minimaler Sketch — prüfen Sie die Kommunikation, ohne den Sensor zu konfigurieren:

C++
#include 
#include 

RbAmp dev(Wire, 0x50);  // default address 0x50

void setup() {
    Serial.begin(115200);
    while (!Serial && millis() < 3000) { /* wait for USB-CDC */ }

    Wire.begin();
#if defined(ESP32) || defined(ESP_PLATFORM) || defined(ESP8266)
    Wire.setClock(50000);   // ESP32/ESP8266: 50 kHz — required for retry discipline
#endif

    while (!dev.begin()) {
        Serial.print(F("rbAmp begin failed: "));
        Serial.println(dev.errorString());
        delay(1000);
    }

    // v1.3: auto-detect the variant via REG_HW_VARIANT — more accurate than
    // the constructor topology hint (which is now a fallback for legacy fw).
    uint8_t variant = static_cast(dev.readVariant());
    Serial.print(F("Module ready, variant="));
    Serial.println(variant);   // 1=UI1, 4=I1, 5=I2, 6=I3
}

void loop() {
    Serial.print(F("U=")); Serial.print(dev.readVoltage(), 1);
    Serial.print(F("V  I=")); Serial.print(dev.readCurrent(0), 3);
    Serial.print(F("A  P=")); Serial.print(dev.readPower(0), 1);
    Serial.print(F("W  PF=")); Serial.println(dev.readPowerFactor(0), 3);
    delay(1000);
}

Laden Sie den Sketch hoch und öffnen Sie den Serial Monitor mit 115200 Baud.

Erwartete Ausgabe (ohne Sensorkalibrierung):

Text
Module ready, variant=1
U=230.4V  I=0.000A  P=0.0W  PF=nan
U=230.4V  I=0.000A  P=0.0W  PF=nan

PF kann nan, 0.000 oder einen anderen Platzhalter ausgeben, solange der Strom null ist.

Sicherheit

U zeigt ungefähr die Netzspannung (220–240 V bei 230-V-Netzen) — das heißt, das Modul ist richtig angeschlossen. I=0.000 A bei eingeschalteter Last ist in diesem Schritt normal: das Modul kennt noch nicht die verwendete CT-Zange. Bei I=0 ist PF mathematisch nicht definiert (abhängig von der Firmware — es kann NaN, 0 oder ein Platzhalter sein) — die genaue Form des Werts spielt bei Strom null keine Rolle. Der nächste Schritt behebt das.

Schritt 4 — Konfiguration des Stromsensors

Haben Sie eine separate aufklemmbare SCT-013-Zange montiert, müssen Sie dem Modul die Sensorklasse und das Modell mitteilen. Ohne das werden die Kalibrierkoeffizienten nicht geladen, und die Stromwerte bleiben bei null. Ist Ihr Modul bereits mit seinem Stromwandler ausgeliefert, überspringen Sie diesen Schritt.

Lesen Sie das Modell vom Aufkleber der Zange ab (zum Beispiel SCT-013-030 → Code 3, siehe die Tabelle unten). Wählen Sie die kleinste Zange mit einem Nennwert oberhalb Ihres größten erwarteten Stroms. Eine zu klein dimensionierte Zange liefert bei Spitzen abgeschnittene, zu niedrige Messwerte; eine weit überdimensionierte liefert bei kleinen Strömen verrauschte, ungenaue Messwerte.

Fügen Sie dies nach dev.begin() in setup() ein. Die Funktion loop() bleibt gleich wie in Schritt 3 — nur setup() ändert sich:

C++
void setup() {
    Serial.begin(115200);
    while (!Serial && millis() < 3000) { /* wait for USB-CDC */ }
    Wire.begin();
#if defined(ESP32) || defined(ESP_PLATFORM) || defined(ESP8266)
    Wire.setClock(50000);   // ESP32/ESP8266: 50 kHz
#endif

    while (!dev.begin()) { delay(500); }

    // Step 1: sensor class. SCT-013 = the clip-on clamp you fitted.
    if (!dev.setSensorClass(RbAmpSensorClass::Sct013)) {
        Serial.print(F("setSensorClass failed: "));
        Serial.println(dev.errorString());
        while (true) { delay(1000); }
    }

    // Step 2: model. For example, SCT-013-030 for a household feed up to ~7 kW.
    if (!dev.setCTModel(RbAmpCTModel::Sct013_030)) {
        Serial.print(F("setCTModel failed: "));
        Serial.println(dev.errorString());
        while (true) { delay(1000); }
    }

    Serial.println(F("Ready."));
}

Modellcodes — die akzeptierte Menge ist {1, 2, 3, 4, 5, 6, 7}:

code Modell Bereich Status Typische Anwendung
1 SCT-013-005 0..5 A ✅ wählbar Kleine Lasten, eine einzelne Steckdose
2 SCT-013-010 0..10 A ✅ wählbar Kühlschrank, Waschmaschine
3 SCT-013-030 0..30 A ✅ wählbar Haushaltseinspeisung bis ca. 7 kW
4 SCT-013-050 0..50 A ✅ wählbar Ladestation für E-Autos, elektrische Heizung
5 SCT-013-100 0..100 A ✅ wählbar Hauptanschluss, große Einspeisungen
6 SCT-013-020 0..20 A ✅ wählbar Mittlere Einspeisung — 3-4 kW Geräte
7 SCT-013-060 0..60 A ✅ wählbar Industrieller Unterzähler

Mehr zur Auswahl finden Sie unter 03 · Auswahl des Stromsensors.

Hinweis

Diese beiden Aufrufe erfolgen einmal bei der Erstinstallation — die Wahl wird im Flash des Moduls gespeichert und übersteht einen Reset. Die Gesamtzeit beträgt etwa 1.4 Sekunden (zwei Flash-Schreibvorgänge × je ca. 700 ms). Die Bibliothek serialisiert beide Aufrufe intern — jeder blockiert, bis der Flash-Schreibvorgang abgeschlossen ist, daher brauchen Sie dazwischen kein delay() einzufügen: Der zweite Aufruf wartet selbst, bis der erste freigibt.

Bei späteren Läufen des Sketches können Sie setSensorClass() und setCTModel() überspringen (das Modul merkt sich die Werte). Schaden richtet der Aufruf aber auch nicht an — ein Wiederholungsaufruf mit demselben Wert schreibt dasselbe Byte erneut.

Nach dem Neustart des Sketches sollte der korrekte Stromwert erscheinen:

Text
Ready.
U=230.4V  I=0.523A  P=119.8W  PF=+0.987

Schritt 5 — Energieabrechnung (Wh)

Das Modul liefert nur Momentanwerte plus die mittlere Leistung über eine Periode. Die Bibliothek berechnet die Wh selbst aus der Wanduhr des Masters:

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

wobei master_dt_s die Anzahl der Sekunden zwischen zwei erfolgreichen Aufrufen von readPeriodSnapshot() ist.

Eine minimale periodische Abrechnungsvorlage (einmal pro Minute):

C++
void setup() {
    Serial.begin(115200);
    while (!Serial && millis() < 3000) { /* wait for USB-CDC */ }
    Wire.begin();
#if defined(ESP32) || defined(ESP_PLATFORM) || defined(ESP8266)
    Wire.setClock(50000);   // ESP32/ESP8266: 50 kHz
#endif
    while (!dev.begin()) { delay(500); }
    dev.setSensorClass(RbAmpSensorClass::Sct013);
    dev.setCTModel(RbAmpCTModel::Sct013_030);
    Serial.println(F("Period meter started; the first line covers only the time since begin() — ignore it..."));
}

void loop() {
    RbAmpPeriodSnapshot snap;
    if (!dev.readPeriodSnapshot(snap)) {
        Serial.print(F("snapshot error: "));
        Serial.println(dev.errorString());
        delay(60000);
        return;
    }

    Serial.print(F("avg P for period: ")); Serial.print(snap.avg_p[0], 2);
    Serial.print(F(" W   accumulated: ")); Serial.print(dev.energy().wh(0), 4);
    Serial.print(F(" Wh   dt=")); Serial.print(snap.master_dt_ms);
    Serial.println(F(" ms"));

    delay(60000);  // the 60-second period sits at the END of loop — the first
                   // snapshot is taken right after setup() and covers only the
                   // seconds since begin(); full periods follow
}
Hinweis

Nach Schritt 4 wurden setSensorClass() und setCTModel() bereits einmal ausgeführt und im Flash des Moduls gespeichert; im obigen Muster stehen sie für erneute Durchläufe des Sketches — das Modul ignoriert einen Wiederholungsaufruf mit demselben Wert. Die Fehlerbehandlung ist der Kürze halber weggelassen — fügen Sie if (!...)-Abfragen hinzu, wenn Sie die seltenen Kommunikationsstörungen beim Start abfangen wollen.

Was readPeriodSnapshot() im Hintergrund tut:

  1. Sendet dem Modul einen Periodensnapshot-Befehl.
  2. Wartet 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.

begin() führt bereits eine erste Momentaufnahme durch, die die Bibliothek verwirft. Das erste readPeriodSnapshot() in Ihrem Sketch deckt daher nur die Zeit seit begin() ab (einige Sekunden, siehe dt= in der Ausgabe): Ignorieren Sie diese erste Zeile und warten Sie auf eine volle Periode. Ab dem zweiten Aufruf deckt jede Zeile eine volle Periode ab.

Erwartete Ausgabe:

Text
avg P for period: 119.90 W   accumulated: 0.1332 Wh   dt=4000 ms    <- short first period, ignore
avg P for period: 120.18 W   accumulated: 2.1368 Wh   dt=60012 ms
avg P for period: 120.21 W   accumulated: 4.1405 Wh   dt=60005 ms
...

Mehrere Module

Für mehrere Module an einem Bus (Einspeisung + Unterlasten) verwenden Sie RbAmpFleet. Das vollständige Beispiel steht in 06 · Beispiele, Szenario 1; die Verdrahtungsregeln für einen Mehrmodul-Bus stehen in 04 · Verdrahtung.

Wie es weitergeht

  • 01 · Überblick — was rbAmp ist und was die Bibliothek tut
  • 02 · Modulstufen — welche Stufe zu welcher Aufgabe passt
  • 06 · Beispiele — Arbeitsszenarien: Netz + N Teillasten (der 80-%-Kanon), Ablauf der Bereitstellung, Mehrkanal mit gemischten CTs, GC-Synchronisation der Flotte, MQTT, Tiefschlaf

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

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

  • 09 · API-Referenz — die vollständige öffentliche API (einschließlich RbAmpFleet + Mehrkanal + Fehlermodell v1.3 + Identität & Provisionierung)

  • 10 · Fehlersuche — wenn etwas nicht funktioniert (dreischichtige Minderung bei i2c-Hängern, Konflikte in der Flotte / Bus-Blockade / Fehlerbilder bei der Provisionierung)


Quelle & Probleme: rb-amp/rbamp-arduino · diese Seite im Repo: docs/05_quickstart.md (v1.6.2)