10 · Fehlersuche
Dieses Kapitel ist nach den beobachteten Symptomen gegliedert, nicht nach der internen Fehlerklassifikation. Sind Sie hier, funktioniert etwas nicht wie erwartet. Suchen Sie Ihr Symptom in der folgenden Liste, springen Sie zum passenden Abschnitt und arbeiten Sie das Diagnoseverfahren durch.
Die meisten Probleme am Arbeitsplatz fallen in drei Kategorien:
-
Busebene — das Modul antwortet nicht über I²C, Lesezugriffe liefern
NaNoderRB_ERR_NACK. -
Datenebene — das Modul antwortet, aber die Zahlen stimmen nicht: Nullen, seltsame Werte, falsches Vorzeichen.
-
Anwendungsebene — die Verbindung ist instabil, der Wh-Zähler weicht ab, der Sketch hängt.
Die Kurzfassung für Ungeduldige: Die Zähler dev.retryExhaustionCount() und dev.sanityRejectCount() müssen im Dauerbetrieb 0 sein. Sind sie es nicht, springen Sie direkt zum Abschnitt "Modul antwortet nicht über I²C" weiter unten.
Zuerst prüfen: U=0 → L/N nicht angeschlossen oder Sicherung aus; I=0 → CT-Buchse nicht vollständig eingesteckt (oder kein CT-Modell gesetzt, siehe unten).
Modul antwortet nicht über I²C
Was Sie beobachten: dev.begin() gibt false mit lastError() == RB_ERR_NACK zurück, oder Lesezugriffe zur Laufzeit "lecken" regelmäßig RB_ERR_NACK in den Anwendungscode.
Schritt 1 — Bus-Scan
Prüfen Sie zunächst, ob das Modul überhaupt am Bus vorhanden ist:
#include
void setup() {
Serial.begin(115200);
Wire.begin();
Serial.println(F("Scanning..."));
for (uint8_t addr = 0x08; addr <= 0x77; addr++) {
Wire.beginTransmission(addr);
if (Wire.endTransmission() == 0) {
Serial.print(F("Found 0x")); Serial.println(addr, HEX);
}
}
}
void loop() {}
Erwartete Ausgabe: Found 0x50 (oder eine andere Adresse, falls Sie sie geändert haben).
Wenn nichts gefunden wird — das Problem liegt in der Verdrahtung oder der Versorgung:
- SDA / SCL sind nicht vertauscht.
-
Beide Linien haben einen Pull-up gegen 3.3 V (die Modulplatine hat eingebaute 4.7-kΩ-Pull-ups — für ein einzelnes Modul sind keine externen nötig).
-
Der Stromversorgungs-Pin des Moduls führt tatsächlich 5 V (4.5–5.5 V) — ältere Board-Revisionen vertragen 3.3 V nicht.
-
Kein anderer Master (Debug-Probe, ein weiterer Arduino) hängt auf denselben Leitungen.
Wenn das Modul gefunden wird, aber unter einer unerwarteten Adresse — jemand hat es vorher auf der Werkbank umadressiert. Aktualisieren Sie das Konstruktorargument:
RbAmp dev(Wire, 0x52); // address from the bus scan
Schritt 2 — ESP32-Grundmuster für NACKs
Findet der Bus-Scan das Modul, liefert dev.readVoltage() aber periodisch NaN mit RB_ERR_NACK — und Sie verwenden einen ESP32 —, ist das ein dokumentiertes Grundmuster: Der ESP-IDF-v5-Treiber i2c_master hat Eigenheiten im Zusammenspiel mit rbAmp auf Firmware v1.0.
Die Minderung ist bereits in die Bibliothek eingebaut (standardmäßig RBAMP_NACK_RETRY_ATTEMPTS=3 auf dem ESP32), doch unter starker Last kann das Wiederholungsbudget aufgebraucht werden.
Was auf dem ESP32 zu tun ist:
- Senken Sie die Busgeschwindigkeit auf 50 kHz:
Wire.begin();
Wire.setClock(50000);
- Anzahl der Wiederholungsversuche bei hoher Last erhöhen:
#define RBAMP_NACK_RETRY_ATTEMPTS 5
#include
- Überwachen Sie den Zähler für ausgeschöpfte Wiederholungen — er sollte im Dauerbetrieb null bleiben:
if (dev.retryExhaustionCount() > 0) {
Serial.print(F("WARN: retry exhausted: "));
Serial.println(dev.retryExhaustionCount());
}
Schritt 3 — NACKs auf Nicht-ESP32-Plattformen
Auf AVR / STM32duino / ESP8266 / SAMD / RP2040 gibt es kein Grundmuster für NACKs — diese Plattformen zeigen mit rbAmp eine NACK-Rate von ~0 %. Die Bibliothek setzt dort standardmäßig RBAMP_NACK_RETRY_ATTEMPTS=1.
Falls hier NACKs auftreten, suchen Sie nach:
-
Hohe Buskapazität — lange Leitungen + viele Geräte. Senken Sie die Geschwindigkeit auf 100 kHz oder kürzen Sie das Kabel.
-
Masterkonflikt — die Bibliothek unterstützt keine Multi-Master-Konfiguration.
-
Ein schwebendes SCL zwischen Transaktionen — ein fehlender Pull-up.
Strom zeigt null bei einer arbeitenden Last
Was Sie beobachten: dev.readCurrent(0) liefert 0.000 (oder einen sehr kleinen Wert), obwohl ein echter Verbraucher eingeschaltet ist (ein Wasserkocher, eine Lampe, ein Bügeleisen). dev.readPowerFactor(0) zeigt eventuell einen seltsamen Wert (NaN / 0 / ±1) — das ist eine Folge; die Ursache liegt im Strom.
Diagnoseverfahren
- Prüfen Sie, ob Sensorklasse und CT-Modell konfiguriert sind:
if (!dev.setSensorClass(RbAmpSensorClass::Sct013)) {
Serial.println(F("class set failed"));
}
if (!dev.setCTModel(3)) { // or your model: see below
Serial.println(F("model set failed"));
}
Ohne diese beiden Aufrufe werden die Kalibrierkoeffizienten nicht geladen, und der Strom zeigt stets null. Dieser Schritt wird einmal bei der Erstinstallation ausgeführt — die Auswahl wird im Flash des Moduls gespeichert.
- Prüfen Sie, dass das CT-Modell zur Last passt. Eine große Stromzange (z. B. SCT-013-100, 100 A) an einer kleinen Last (eine 50-W-Lampe ≈ 0.2 A) erzeugt ein Signal genau am Rauschpegel, und die Messwerte bleiben null. Wählen Sie die kleinste Nennzange oberhalb Ihres größten erwarteten Stroms. Die vollständige Tabelle steht in 03 · Auswahl des Stromsensors.
Haben Sie ein Mehrkanal-Modul (UI2 / UI3 / UI5 / UI7) und möchten sowohl kleine Lasten als auch Spitzen sehen, erwägen Sie das Zwei-CT-Muster: eine kleine Zange (z. B. SCT-013-005) auf einem eigenen Kanal für den niedrigen Bereich und eine große (SCT-013-030/100) auf einem anderen Kanal für den hohen Bereich; der Master wählt den Wert über eine Schwelle. Das Muster wird unter 03 · Auswahl des Stromsensors, Abschnitt „Zwei-CT-Topologie“, behandelt.
- Prüfen Sie die Ausrichtung der Zange. Der Pfeil am Zangenkörper muss in Stromrichtung zum Verbraucher zeigen. Ist die Zange „verkehrt herum“, liefert
readCurrent()den korrekten Betrag,readPower()aber einen negativen Wert bei einem Verbraucher. Die Bestätigung:readPowerFactor()zeigt bei einer ohmschen Last genau −1.0 (statt +1.0). Abhilfe: bauen Sie die Zange physisch neu ein (Stromkreis abgeschaltet: abklemmen, Pfeil richtig herum drehen, wieder aufklemmen). Das Vorzeichen nicht in der Software umkehren.
Wenn alle drei Schritte bestanden werden und der Strom trotzdem null ist
Dann liegt das Signal am Modulenenngang tatsächlich unter dem Grundrauschen. Prüfen Sie:
-
Ob tatsächlich Strom fließt — messen Sie ihn mit einem Multimeter (Gleich- / Wechselstromzange) an derselben Leitung.
-
Ob die Zange intakt ist — am Zangenstecker sollte eine Wechselspannung proportional zum Strom anliegen (einige Millivolt bei Haushaltslasten).
-
Ob Sie den richtigen Draht klemmen — nur einen Leiter, die Leitung (L); niemals das ganze Kabel.
Messwerte springen oder kommen als NaN zurück
Was Sie beobachten: dev.readVoltage() oder dev.readCurrent() liefern periodisch NaN. dev.lastError() zeigt entweder RB_ERR_NACK oder RB_ERR_NON_PHYSICAL.
Wenn lastError() RB_ERR_NACK anzeigt
Siehe den Abschnitt "Modul antwortet nicht über I²C" oben — es ist dieselbe Problemklasse mit einem Unterschied: Die Verbindung arbeitet teilweise, aber das Wiederholungsbudget läuft gelegentlich aus.
Steps:
-
Auf dem ESP32 — die Geschwindigkeit auf 50 kHz senken und
RBAMP_NACK_RETRY_ATTEMPTS=5erhöhen. -
Auf anderen Plattformen — prüfen Sie die Buskapazität und die Pull-up-Widerstände.
- Beobachten Sie
dev.retryExhaustionCount(), um den Trend zu verfolgen.
Zeigt lastError() RB_ERR_NON_PHYSICAL
Der Plausibilitätsfilter der Bibliothek hat ausgelöst: vom Bus kam ein Fließkommawert, der entweder NaN, Inf oder |x| > 10000 ist — offensichtlich kein physikalischer Wert. Die Bibliothek verwirft diesen Wert und meldet RB_ERR_NON_PHYSICAL, statt Müll in die Anwendung durchzulassen.
Dies ist ein seltenes Artefakt. Der Dauerwert von dev.sanityRejectCount() ist 0. Ist er nicht null:
-
Prüfen Sie
dev.retryExhaustionCount(). Sind beide Zähler ungleich null, ist die Verbindung instabil und der Plausibilitätsfilter fängt nach fehlgeschlagenen Wiederholungen Müll ab. Erhöhen Sie das Wiederholungsbudget (siehe oben). -
Ist
retryExhaustionCount == 0, abersanityRejectCount > 0, ist ein Artefakt durch die Wiederholungsschicht gelangt. Das passiert bei sehr hoher Buslast. Erhöhen SieRBAMP_NACK_RETRY_ATTEMPTS=5und wiederholen Sie den Test.
Serial.print(F("retries exhausted: "));
Serial.print(dev.retryExhaustionCount());
Serial.print(F(" sanity rejects: "));
Serial.println(dev.sanityRejectCount());
Der Leistungsfaktor sieht seltsam aus
Was Sie beobachten: dev.readPowerFactor(0) liefert einen Wert, der nicht zur Lastart passt.
Erwartungen je Last:
| Last | Erwarteter PF |
|---|---|
| Wasserkocher, Bügeleisen, Glühlampe | +0.95 .. +1.0 (ohmsch) |
| Kühlschrank, Verdichtermotor | +0.6 .. +0.85 (induktiv) |
| LED-Lampe, TV (Schaltnetzteil) | +0.5 .. +0.95 (nichtlinear) |
| PV-Wechselrichter speist ein | negativer PF |
PF = NaN oder 0, wenn I = 0
PF ist definiert als P / (U × I). Bei null Strom I=0 ist die Rechnung nicht definiert. Der tatsächlich zurückgegebene Wert hängt von der Firmware ab (er kann NaN, 0 oder ein Platzhalter sein) — das ist normal, solange der Strom tatsächlich null ist. Sobald Strom fließt, liegt ein gültiger PF vor.
PF ist bei einer rein verbrauchenden Last genau −1.0
Die Zange ist "verkehrt herum" eingebaut — der Pfeil zeigt nicht in die Stromrichtung zur Last. Abhilfe: Bauen Sie die Zange richtig ein (physisch drehen; das Vorzeichen nicht in der Software umkehren).
Der Leistungsfaktor schwankt bei einer ohmschen Last zwischen +0.3 und +0.7
-
Mögliche Ursache: die CT-Zange hängt an einem Draht einer anderen Phase als der, an der der U-Eingang des Moduls angeschlossen ist. In einem Verteiler mit mehreren Phasen greift man leicht versehentlich die falsche Phase — eine Phasenverschiebung von 120° oder 180° zwischen U und I ergibt genau diese PF-Werte. Abhilfe: Installieren Sie das Modul so, dass der U-Eingang und die Zange an derselben Phase hängen.
-
Alternative: die Last ist wirklich nicht rein ohmsch. Wiederholen Sie den Test mit einer bekannten ohmschen Last (ein Wasserkocher bei voller Leistung).
Periodensnapshots sind immer stale
Was Sie beobachten: dev.readPeriodSnapshot(snap) gibt false mit lastError() == RB_ERR_STALE zurück. Das bedeutet, dass das Modul die vorherige Periode bis zum nächsten Lesezugriff nicht fertig integriert hat.
Die Bibliothek schützt vor Doppelzählung der Wh: Bei einem veralteten Lesewert speichert sie einen Master-Zeitstempel, und die nächste erfolgreiche Momentaufnahme deckt eine Periode ab, nicht zwei.
Akzeptabel: seltene veraltete Werte (1–2 pro Stunde bei einem Takt von 60 s). Nicht akzeptabel: aufeinanderfolgende veraltete Werte — das bedeutet, dass die Firmware nicht antwortet oder der Master zu oft abfragt.
Verfahren zur Prüfung des Takts
-
Prüfen Sie den Takt: 60 s zwischen den Snapshots ist komfortabel; 30 s ist grenzwertig; < 10 s garantiert veraltete Werte.
-
Prüfen Sie die Reaktionsfähigkeit des Moduls zwischen den Momentaufnahmen:
if (dev.probe()) {
Serial.println(F("alive"));
}
-
Direkte Flag-Prüfung —
dev.isPeriodValid()führt ein Einzelbyte-Lesen ohne Nebenwirkungen aus. -
Firmwareversion prüfen —
dev.firmwareVersion()sollte0x04(v1.3, aktuelle Produktion) melden; ältere Firmware (0x01v1.0 /0x02v1.1 /0x03v1.2) zeigt mehr Stales.
Die Wh-Bilanz weicht von einer Referenz ab
Was Sie beobachten: dev.energy().wh(0) weicht nach einigen Stunden / Tagen Betrieb vom Stand des Versorgungszählers oder eines Referenzzählers ab (Kill-A-Watt o. Ä.).
Schließen Sie zuerst das Triviale aus
-
Kalibrierung des Stromsensors: Stellen Sie sicher, dass
setSensorClass()undsetCTModel()mit dem richtigen CT-Modell aufgerufen wurden (siehe 03 · Auswahl des Stromsensors). Ohne das wird der Effektivstrom mit dem Standardgrundrauschen berechnet, und der Leistungswert ist systematisch verzerrt. -
Verworfene veraltete Snapshots: Liegt
dev.energy().wh()dauerhaft unter der Referenz, könnten Intervalle fehlen — ein Snapshot kam veraltet zurück, die Bibliothek schützte vor Doppelzählung, aber die Intervallmessung ging verloren. Prüfen Sie den Takt (siehe oben). -
Drift der Masteruhr:
millis()allein ist zuverlässig. Wechselt der Master aber in den Tiefschlaf ohne erhaltene RTC, geht das Intervall zwischen vorherigem und nächstem Snapshot verloren. Aktivieren Sie in solchen Szenarien die RTC.
Genauigkeit des Akkumulators je Plattform
| Plattform | Akkumulatortyp |
|---|---|
| ESP32 / ESP8266 / STM32duino / SAMD / RP2040 | 64-Bit-double |
| Arduino AVR (Uno, Mega, Nano) | 32-Bit-float (Toolchain) |
Die Integration auf Masterseite fügt über die Wirkleistungsgenauigkeit des Moduls hinaus keinen eigenen Fehler hinzu.
Für AVR bei langen Dauertest-Installationen setzen Sie den Akkumulator regelmäßig zurück und speichern die Langzeitsumme in Ihrem eigenen dauerhaften Speicher:
// Once a day in the MQTT-publish hook
mqtt.publish("rbamp/wh_daily", String(dev.energy().wh(0)));
dev.energy().reset(0);
snap.latch_ms weicht von der realen Periode ab
latch_ms ist ein diagnostischer Zeitgeber des Moduls; verwenden Sie ihn nicht für Energie — nutzen Sie die Masteruhr (master_dt_ms).
RB_ERR_STALE bei jedem Lesezugriff — der Master hält den Anker automatisch
Was Sie beobachten: dev.readPeriodSnapshot(snap) liefert periodisch false mit lastError() == RB_ERR_STALE. (Siehe auch den Abschnitt „Periodensnapshots sind immer veraltet“ oben.)
Kanonische dt-Behandlung: Bei einem veralteten Lesen setzt die Arduino-Bibliothek ihren internen Anker _last_latch_ms NICHT zurück. Das nächste gültige Lesen erhält ein master_dt, das dem vollständigen Intervall seit dem vorherigen erfolgreichen Snapshot entspricht — es umfasst also sowohl den „verlorenen“ veralteten Zeitraum als auch den aktuellen. Die Firmware bewahrt den Akkumulator avg_p über einen leeren Snapshot hinweg (firmwareseitige Persistenz): beim nächsten gültigen Snapshot ist dies bereits der über das gesamte Intervall gemittelte Wert. Die Wh-Integration bleibt genau — keine Doppelzählung, keine Unterzählung.
Im Code des Masters ist keine besondere Behandlung veralteter Werte nötig: Die Bibliothek erledigt alles korrekt und automatisch. RB_ERR_STALE können Sie ignorieren, wenn es selten vorkommt; tritt es häufig auf, prüfen Sie den Takt (Abschnitt oben).
ESP32-Sketch hängt sich nach einigen Minuten auf
Was Sie beobachten: Der Sketch auf dem ESP32 startet problemlos, geht dann aber nach 1–30 Minuten in einen Festhänger / eine Neustartschleife / einen WDT-Timeout.
Wire hängt sich auf einem grenzwertigen Bus auf — dreistufige Minderung
Was Sie konkret beobachten: ein Sketch auf dem ESP32 (Arduino-ESP32-Core) fragt rbAmp einige Minuten lang einwandfrei ab, dann „hängt“ er mitten in einem Aufruf von dev.readAll(...) / dev.readVoltage() / fleet.pollAll(). Ist der Task-WDT aktiv, fängt er den Hänger ab; andernfalls reagiert der Sketch einfach nicht mehr. Der dekodierte Backtrace endet in der Funktion i2c_ll_is_bus_busy (der IDF-i2c_master-Treiber, Datei i2c_master.c:526, Wartezeit „Bus belegt“ vor dem Senden).
Was passiert: der Arduino-ESP32-Wire umhüllt denselben IDF-i2c_master-Treiber wie native ESP-IDF-Projekte. Auf einem schwachen Bus (schwache Pull-ups, lange Leiterbahnen, EMI, Störungen durch Nulldurchgang) können SDA/SCL kurz in einem undefinierten Zustand „kleben“. Vor jeder Transaktion dreht der IDF-i2c_master in der Schleife i2c_ll_is_bus_busy, bis der Bus frei wird — dieses Warten ist NICHT durch den I²C-Timeout der Bibliothek begrenzt. Hält „Bus belegt“ länger, als das Warten ohne Abgabe an andere Tasks dauert, bekommt die FreeRTOS-IDLE-Task keine CPU, und der gesamte Sketch hängt.
Das ist kein „nur im Debugger auftretendes Artefakt“. Am Prüfstand validiert (derselbe Hardware-Aufbau und dieselbe Last):
| Buskonfiguration | Hänger-Rate |
|---|---|
| 2 schwache Modul-Pull-ups + angeschlossener Debugger-NRST | ~1 Hänger / 2.1 min |
| 1 schwacher Modul-Pull-up, kein Debugger | ~1 Hänger / 3.3 min (≈ 12 Hänger pro Stunde) |
| + externer 4.7-kΩ-Pull-up an DUT-SDA/SCL | 0 Festhänger (12-Minuten-Dauertest, 1300 Zyklen, 0 Neustarts, 0 WDT-Auslösungen) |
Der Zusammenhang ist eindeutig — die Behebung der Busintegrität beseitigt den Festhänger vollständig. Die Bibliothekslogik ist nicht beteiligt: RbAmpFleet::pollAll(), Einzelmodul-MISS sowie die Wiederholungs- und Plausibilitätszähler blieben bei jedem Lauf bis zum Festhänger selbst sauber.
Dreischichtige Minderung (wenden Sie alle drei Schichten an):
-
Externer Pull-up (ca. 4.7 kΩ) an SDA und SCL gegen 3.3 V an einem einzigen Punkt des Busses. Die internen Pull-ups des ESP32 (ca. 45 kΩ) sind für einen Mehrmodul-Bus realer Länge zu schwach, während die in die Module eingebauten 4.7-kΩ-Pull-ups parallel zu stark werden. Trennen Sie auf einem solchen Bus die eingebauten an allen Modulen bis auf eines (oder an allen — dann verlassen Sie sich nur auf die externen). Siehe 04 · Verdrahtung, Abschnitt „Mehrmodul-Bus — die primäre Topologie“.
-
Betreiben Sie keinen Produktionsbuild mit angeschlossenem Debugger-NRST. In einer Debug-Sitzung kann die Reset-Leitung SDA/SCL beim Trennen und Verbinden in einem undefinierten Zustand halten und beim nächsten Vorgang eine Bus-Blockade auslösen. In einem Feld-Build (ohne Debugger) entfällt dieser Faktor.
-
Anwendungsweiter Task-WDT auf dem Abfrage-Task — Verteidigung in der Tiefe. Falls die Pull-ups aus irgendeinem Grund grenzwertig blieben oder eine andere Ursache für einen Festhänger auftritt, startet der WDT den Sketch neu. Dauertest am Prüfstand, 12 Minuten: Der WDT fing alle 12 Festhänger in der Konfiguration ohne externen Pull-up ab und erholte sich davon. Richtige Bus-Pull-ups — Korrektur im Feld; App-WDT — Erholungsstrategie.
#include "esp_task_wdt.h"
void setup() {
// Layer 3 setup — defense-in-depth.
esp_task_wdt_config_t wdt_cfg = {
.timeout_ms = 8000, // 8 s with a large margin
.idle_core_mask = 0,
.trigger_panic = true, // on timeout — panic+reboot
};
esp_task_wdt_reconfigure(&wdt_cfg);
esp_task_wdt_add(NULL); // this task (loop) under WDT
// ... rest of the initialization ...
}
void loop() {
fleet.pollAll(snaps, status, RBAMP_FLEET_MAX_MODULES, n_ok);
// ... processing ...
esp_task_wdt_reset(); // "I'm alive" — every cycle
delay(200);
}
Was NICHT zu tun ist: Versuchen Sie nicht, das Problem mit einem größeren Parameter Wire.setTimeout() zu umgehen — er begrenzt das Vordrehen bei belegtem Bus nicht, das ein anderer Codepfad im IDF-Treiber ist. Die Lösung ist die Busintegrität (Ebene 1) + ein Supervisor (Ebene 3).
Watchdog-Timeout in wifi_connect()
Ursache: die unbegrenzte Schleife while (WiFi.status() != WL_CONNECTED) delay(500) löst nach ca. 5 s (Standard) den Task-WDT aus.
Abhilfe: ein begrenztes Warten mit Neustart als Rückfall:
uint32_t t0 = millis();
while (WiFi.status() != WL_CONNECTED) {
delay(500);
if (millis() - t0 > 30000) { ESP.restart(); }
}
Der MQTT-Broker trennt die Verbindung etwa alle 15 s
Ursache: PubSubClient verwendet als Standard Keepalive = 15 s, während mqtt.loop() nur im „langsamen“ Pfad aufgerufen wird (alle 60 s zusammen mit readPeriodSnapshot()).
Abhilfe: setzen Sie das Keepalive auf 60 s und rufen Sie bei jedem Durchlauf von loop() mqtt.loop() auf:
mqtt.setKeepAlive(60);
void loop() {
if (!mqtt.connected()) mqtt.connect("rbamp-id");
mqtt.loop(); // every iteration, not once every 60 s
// ...rest of the logic, slowed down via millis()...
}
Fehlgeschlagener TLS-Handshake (Cloud-Integrationen)
Ursache: Der Heap des ESP32 reicht für den TLS-Handshake nicht aus (ca. 30 kB benötigt). Oft kommt es mit WLAN + MQTT + Puffern zusammen — es bleiben weniger als 20 kB.
Fix:
setBufferSize()des MQTT-Clients auf das Minimum kürzen.- Verwenden Sie
WiFi.mode(WIFI_STA)(nichtWIFI_AP_STA). - BLE deaktivieren:
btStop()insetup().
Wenn ESP.getFreeHeap() vor client.connect() weniger als 25 kB anzeigt, schlägt der TLS-Handshake höchstwahrscheinlich fehl.
setSensorClass() / setCTModel() gibt RB_ERR_PARAM zurück
Was Sie beobachten: einer der Konfigurationsaufrufe gibt false zurück, lastError() == RB_ERR_PARAM.
Mögliche Ursachen:
-
setCTModel()vorsetSensorClass()aufgerufen. Zuerst die Sensorklasse, dann das Modell — siehe 03 · Auswahl des Stromsensors und 09 · API-Referenz § Sensorkonfiguration. -
Ungültiger Modellcode — für die Klasse
Sct013ist der gültige Satz{1, 2, 3, 4, 5, 6, 7}(die Codes 5 und 7 sind SCT-013-100 und SCT-013-060). Für andere Klassen siehe die Tabelle der akzeptierten Codes je Klasse in 03 · Auswahl des Stromsensors. Codes, die nicht zur Klasse passen, liefernRB_ERR_PARAM(bibliotheksseitige Wache vor dem Bus) oderDEV_ERR_PARAM(firmwareseitig, falls YAML durchrutscht). -
Ungültiger Kanalindex in der kanalweisen Form
setCTModel(channel, code)— er muss <dev.channels()sein. Ein Kanal bei oder überRBAMP_MAX_CHANNELS(7) wird nie bereitgestellt und gibt ebenfallsRB_ERR_PARAMzurück. -
Das Modul hat den Code abgelehnt — ein Code, der in der Registry steht, den das Modul aber nicht akzeptiert, wird vom Modul abgewiesen; der Kanal behält sein bisheriges Modell.
Gibt der Aufruf stattdessen false mit RB_ERR_MODE zurück, gehört das Modul einer werkseitig gepaarten Klasse an (WiredCT / BuiltinCT) — es wurde zusammen mit seinem Sensor ausgeliefert und kalibriert, und die Setter schreiben es nicht neu. Eine Neupaarung im Service erfolgt über setCTModelChForce().
Erwartetes Verhalten, kein Fehler:
-
Einen Wert setzen, den das Modul bereits hat, bleibt ohne Wirkung (
true, kein Schreibzugriff auf den Bus, kein Flash-Zyklus). -
Das Setzen eines CT-Modells startet das Modul neu bei BASIC-Firmware bis 1.4.19 mit der SCT-013-Klasse (etwa eine Sekunde, blockierend). Messwerte sind in dieser Zeit nicht verfügbar; die Bibliothek liest die Nennwertkorrektur danach neu.
-
Nach dem Wechsel eines SCT-013-Modells folgen Strom-, Leistungs- und Energiemesswerte automatisch der neuen Nennangabe (Leistungsfaktor und Spannung bleiben unberührt).
dev.sctRating(ch, r)zeigt den Status je Kanal; meldet erUnexpectedGainoderUnknown, wird keine Korrektur angewendet (Skalierung 1).
Hinweise zu STD- (STANDARD-) Modulen
Die STD-Linie verwendet dieselbe I²C-Verdrahtung wie BASIC (siehe 04 · Verdrahtung); dev.begin() erkennt sie, und dev.line() sagt Ihnen, welche Linie Sie haben. Spezifisch für STD:
-
RB_ERR_NOT_IMPLEMENTEDvon einem Aufrufstd*,readReactivePower()oderreadApparentPower()— das angeschlossene Modul ist BASIC (prüfen Siedev.line()). Umgekehrt liefern nur für BASIC gedachte Aufrufe (factoryReset(), General-Call, Label-Hilfsfunktionen,readCapability(),readCommitSeq()) diesen Fehler an einem STD-Modul. -
Eine Funktion meldet "nicht verfügbar" — Energie mit Mikroauflösung (
RbAmpStdEnergy::fine == false), der Anlaufstrom für Energie (RB_ERR_NOT_IMPLEMENTED), Spannungsphasenwinkel (angle_valid == false) und die Phasenfolge (NotAvailable) hängen von der Image-Version des Moduls ab: Sie brauchen ein Image von mindestens0x0001007B. Lesen Sie es mitdev.stdReadImageVersion(); bei einem älteren Image ist der Wert nicht verfügbar, nicht falsch. -
Spannungswinkel / Phasenfolge bleiben auf einem aktuellen Image "nicht verfügbar" — sie erfordern, dass alle Spannungseingänge unter Spannung stehen und messbar sind, und für die Phasenfolge ein Modul mit drei Spannungen.
-
Periodensnapshot-Lesungen kommen nach einem Modulneustart leer zurück (
RB_ERR_STALE) — erwartet: die Snapshot-Scharfschaltung liegt im RAM des Moduls. Die Bibliothek scharf schaltet die Bank neu und verwirft diese eine Periode; starten Sie Ihren eigenendt-Anker neu. Warten Sie mindestens 300 ms zwischenstdLatch()undstdReadLatch(). -
Keine Verlaufseinträge — das Modul zeichnet den Verlauf nur auf, solange seine Uhr gesetzt ist. Die Uhr geht bei jedem Neustart des Moduls verloren: Rufen Sie
dev.stdSetTime()nachbegin()auf und immer dann, wennstdReadHealth()time_valid == falsemeldet. -
Ein Befehl gibt
RB_ERR_PARAMzurück — bei STD wird das Urteil jedes Befehls zurückgelesen; das Modul hat den Wert abgelehnt und ist unverändert. -
Ein Speichervorgang liefert
RB_ERR_NOT_READY— das Modul begrenzt, wie oft es seinen Speicher schreibt; die Bibliothek wiederholt den Vorgang bereits einmal nach 5 s.
Fehlerbehandlung: letzter Schreibzugriff auf REG_ERROR + EVENT_FLAGS.bit3 dauerhaft (v1.3)
Verhalten in v1.3: REG_ERROR (0x02) ist das Ergebnis des letzten Schreibvorgangs und NICHT klebrig. Bei jedem Registerschreiben setzt die Firmware reg_error = ERR_OK; ein folgender, unabhängiger Schreibvorgang löscht den vorherigen Fehler.
Dauerhaftes Fehlersignal = EVENT_FLAGS (0x2A) bit3 — bleibt gesetzt (W1C) und wird sofort bei jedem abgewiesenen Schreibzugriff oder Befehl gesetzt.
Muster 1 — einmalige Erfassung nach einer Operation (wenn das Ergebnis genau dieser Operation zählt):
bool ok = dev.saveUserConfig();
uint8_t dev_err = dev.readReg(0x02); // IMMEDIATELY, before the next write
Muster 2 — dauerhafte Fehlerüberwachung (kanonisch):
uint8_t event_flags = dev.readReg(0x2A);
if (event_flags & (1 << 3)) {
uint8_t last_err = dev.readReg(0x02);
// handle
dev.writeReg(0x2A, (1 << 3)); // W1C clear bit3
// or dev.clearError();
}
⚠ REG_ERROR ist das Ergebnis des letzten Schreibzugriffs, nicht dauerhaft. Die Dauerhaftigkeit liefert EVENT bit3.
⚠ bit3 ist ein asynchroner Kanal, nicht für die synchrone Schreibprüfung gedacht: Bei einem abgewiesenen Schreibzugriff wird bit3 verzögert gesetzt, bezogen auf den Zeitpunkt, an dem die I²C-Transaktion zurückkehrt. Fragen Sie bit3 nicht unmittelbar nach einem Schreibzugriff ab, um dessen Ergebnis zu prüfen — für das Ergebnis Ihres eigenen Schreibzugriffs verwenden Sie Muster 1 (einmaliges Erfassen von lastError() direkt nach der Operation) oder den Rückgabecode des Setters. bit3 dient der langfristigen Überwachung asynchroner Fakten (Laufzeit, Befehlspfad), nicht der Prüfung einer soeben ausgeführten Operation.
lastError() vs. readLastError() — zwei verschiedene Kanäle, keine Synonyme
Zwei Funktionen mit ähnlichen Namen, aber völlig unterschiedlicher Semantik:
lastError() |
readLastError(out) |
|
|---|---|---|
| Was er zurückgibt | Von der Bibliothek zwischengespeicherter RB_ERR_*-Code des vorherigen Bibliotheksaufrufs |
Ein einzelner Lesezugriff auf das Register REG_ERROR (0x02) des Geräts |
| Eine I²C-Operation? | Nein — nur ein Speicherlesezugriff | Ja — eine einzige Lesetransaktion |
| Semantik | Ergebnis der Validierung in der Bibliothek (clientseitige Wache, Wiederholungszustand usw.) | Geräteseitiges Ergebnis des letzten Schreibvorgangs (Mnemonik DEV_ERR_*) |
| Wann aktualisiert | Nach jeder Bibliotheksmethode | Nach jedem vom Bus angenommenen Schreibzugriff auf dem Gerät |
| Beispielwert | RB_ERR_PARAM nach einer clientseitigen Prüfung |
0xFE (DEV_ERR_PARAM) nach einem abgelehnten Schreibvorgang auf dem Gerät |
| Beispiel für eine Abweichung | lastError() == RB_ERR_PARAM (der Setter hat es vor dem Bus blockiert) |
readLastError() → 0x00 (nichts hat das Gerät erreicht) |
Wann welche verwendet wird:
-
lastError()— für die Anwendungslogik, zum Auswerten der bibliotheksseitigen Ergebnisse (Wiederholung, Ausweichlösung, Fehlerklassifizierung), ohne I²C-Mehraufwand. -
readLastError()— wenn Sie den erweiterten Grundcode auf Geräteseite wollen (zum BeispielDEV_ERR_PARAM (0xFE)vs.DEV_ERR_NOT_READYvs.DEV_ERR_FLASH_PARAMS_BAD (0xFB)) in Kanal B (Ablehnung auf Seiten des DUT). Siehe den Abschnitt "v1.3-Fehlermodell — zwei unabhängige Kanäle" in 09 · API-Referenz.
Die Unterscheidung ist besonders wichtig bei der Fehlersuche für Kanal A (clientseitige Wache): der Setter liefert false + lastError() == RB_ERR_PARAM, aber readLastError() == 0x00 — weil die Bibliothek ihn vor dem Buszugriff blockiert hat und REG_ERROR auf dem Gerät unberührt blieb.
Vorbehalt: DEV_ERR_CLONE (0xF9) wird NICHT über CMD_CLEAR_ERROR gelöscht — es ist ein Anti-Klon-Wächter (nur durch einen Neustart oder einen Werksreset).
Ein frisch geflashtes Modul zeigt beim ersten Start 0xFB (NORMAL)
Was Sie beobachten: ein frisch geflashtes Modul zeigt beim ersten Booten REG_ERROR = 0xFB (DEV_ERR_FLASH_PARAMS_BAD) + EVENT bit3.
Ursache: die Parameterseite ist nicht initialisiert → Werkseinstellungen geladen. Das ist NORMAL bei einem neuen Modul, nicht fatal.
Abhilfe: konfigurieren Sie sensor_class + ct_model + (optional) Adresse und führen Sie dann dev.saveUserConfig() aus. Nach einem erfolgreichen SAVE → REG_ERROR = 0x00, bit3 gelöscht.
commitAddressChange() liefert RB_ERR_TIMEOUT
Was Sie beobachten: prepareAddressChange() ging durch, aber commitAddressChange() liefert false, lastError() == RB_ERR_TIMEOUT.
Ursache: Das Fenster des scharfen Zustands (5 s nach prepareAddressChange) ist abgelaufen. WLAN/MQTT oder jede blockierende E/A zwischen prepare und commit ist die Hauptursache dafür, dass das Fenster abläuft. dev.probe() hilft hier nicht (das Modul antwortet; das Problem liegt im Zustandsautomaten).
Was zu tun ist: rufen Sie prepareAddressChange() erneut und sofort auf und rufen Sie dann in derselben loop()-Iteration, ohne Netzwerkaufrufe dazwischen, commitAddressChange() auf.
✅ REG_I2C_ADDRESS (0x30) liest jetzt die AKTIVE Adresse beim Booten (v1.3). Nach einem Neustart nach dem Commit zeigt das Lesen von 0x30 die neue aktive Adresse. Für die zuverlässigste Prüfung eines zweiphasigen Adress-Commits lesen Sie an der neuen Adresse (sie sollte auf dem Bus ein ACK liefern). Nach einem Host-Schreibvorgang (Staging) gibt das Register den vorbereiteten Kandidaten zurück, bis CMD_COMMIT_ADDR + Reset erfolgen — das ist beabsichtigtes Verhalten.
Zum zweiphasigen Adress-Commit siehe 09 · API-Referenz und 04 · Verdrahtung.
Lesezugriffe scheitern beim Schalten von Relaislasten (EMV-Transienten)
Was Sie beobachten: dev.readVoltage() / dev.readCurrent() liefern periodisch NAN, lastError() == RB_ERR_NACK oder RB_ERR_IO — aber nur während aktiven Schaltens einer Relais- oder induktiven Last am selben Aufbau. Im stationären Betrieb sind die Lesezugriffe zuverlässig.
Ursache: Während des Relaisschaltens (eine Last von 5 A) scheitern durch EMV etwa 67 % der I²C-Transaktionen (ca. 8 von 12 in der Hardwaremessung). Der Bus erholt sich selbst, es kommt zu keinem Festhänger, kein Modul geht verloren — aber der aktuelle Lesezugriff schlägt fehl.
Abhilfe — Wiederholung auf Anwendungsebene:
float robust_read_voltage(RbAmp& dev) {
for (int attempt = 0; attempt < 5; attempt++) {
float v = dev.readVoltage();
if (!isnan(v)) return v;
delay(20); // a short pause before the retry
}
return NAN;
}
⚠ Die Busrettung auf Bibliotheksseite allein reicht nicht: Überlappt eine EMV-Störung das Wiederholungsfenster des Treibers, ist ein explizites Wiederholen auf Anwendungsebene mit einer Pause nötig.
Alternative: Sieht der Master die Ereignisse des Relaisschaltens, verzögern Sie die Lesezugriffe nach der Umschaltung um ca. 50–100 ms.
Übersichtstabelle der Fehlercodes
dev.lastError() liefert nach jedem öffentlichen API-Aufruf einen dieser Codes. RbAmp::errorString(code) liefert eine lesbare Zeichenkette.
| Code | String | Wann | Wo nachzuschlagen ist |
|---|---|---|---|
RB_OK (0) |
"OK" | Erfolg | — |
RB_ERR_IO (-1) |
"I2C-Übertragungsfehler" | der Bus-Treiber meldete etwas anderes als OK | Verkabelung, Stromversorgung, Pull-ups |
RB_ERR_NACK (-2) |
"NACK — Gerät fehlt oder ist beschäftigt" | Wiederholungsversuche erschöpft | Abschnitt „Modul antwortet nicht über I²C“ |
RB_ERR_TIMEOUT (-3) |
"Bus-Timeout" | das Zeitfenster von waitReady / waitDataReady / commitAddressChange ist abgelaufen |
Abschnitt "commitAddressChange() gibt RB_ERR_TIMEOUT zurück" |
RB_ERR_NOT_READY (-4) |
"Gerät nicht bereit" | das Modul ist nicht bereit / es gibt keinen solchen Verlaufseintrag / nichts ist scharf geschaltet / unter der neuen Adresse antwortet nichts | die obigen STD-Hinweise |
RB_ERR_STALE (-5) |
"Periodensnapshot veraltet" | das Flag Periode-bereit = 0 | Abschnitt "Periodenmomentaufnahmen sind immer veraltet" |
RB_ERR_PARAM (-6) |
"Ungültiger Parameter" | ungültiger Kanalindex / ungültiger Modellcode / ungültiger Adressbereich | Abschnitt "setSensorClass() / setCTModel() gibt RB_ERR_PARAM zurück" |
RB_ERR_MODE (-7) |
"Im aktuellen Modus des Moduls nicht erlaubt (Werksmodus / Serviceweg erforderlich)" | eine Operation nur im Werk oder ein CT-Setter an einem Modul der Klasse WiredCT / BuiltinCT |
rufen Sie auf Produktionsfirmware keine Werks-Operationen auf; verwenden Sie setCTModelChForce() nur für die Neuzuordnung im Service |
RB_ERR_CHECKSUM (-8) |
"Wertprüfung fehlgeschlagen — Prüfsumme / Signatur / Bereich" | die Wertprüfung des Moduls ist fehlgeschlagen (STD: abgelehntes Firmware-Image, Payload-CRC, Epoche außerhalb des Bereichs, leerer Verlaufspuffer) | Seite erneut senden / Image prüfen |
RB_ERR_VERSION (-9) |
"Nicht unterstützte Firmware-Version" | REG_VERSION = 0 / 0xFF |
prüfen Sie die Modulverbindung |
RB_ERR_NOT_IMPLEMENTED (-10) |
"Auf dieser Firmware nicht implementiert" | der Aufruf hat auf der erkannten Linie kein Gegenstück, oder das Modul-Image stellt die Funktion nicht bereit | dev.line(), dev.stdReadImageVersion() |
RB_ERR_NON_PHYSICAL (-11) |
"Nicht-physikalischer Wert (NaN/Inf/außerhalb der Grenzen)" | der Plausibilitätsfilter hat einen Float abgewiesen | Abschnitt „Messwerte springen oder kommen als NaN zurück“ |
Übersichtstabelle der Diagnosezähler
In einem gesunden Dauertestlauf (12 h, der Sketch SoakMonitor) bleiben alle null:
| Zähler | Dauerzustand | Reset |
|---|---|---|
dev.retryExhaustionCount() |
0 | dev.resetCounters() |
dev.sanityRejectCount() |
0 | dev.resetCounters() |
dev.lastError() nach einem Lesen |
RB_OK (0) |
beim nächsten Aufruf automatisch |
| veralteter Anteil in Periodensnapshots | < 1 % | (kumulativ — kein Reset) |
Sind eines dieser Felder im Dauerbetrieb ungleich null, gehen Sie zum entsprechenden Abschnitt oben zurück.
Fehlersuche auf Busebene mit einem Logikanalysator
Für tiefe Fehlersuche, wenn die Bibliothek Ihnen nicht mehr sagen kann, was auf dem Draht geschieht, erfassen Sie SDA + SCL mit einem Logikanalysator (Saleae, DSLogic Plus oder ein Sigrok-kompatibler):
- Abtastrate ≥ 1 MS/s bei 100 kHz I²C; ≥ 4 MS/s bei 400 kHz.
- Der I²C-Dekoder in Sigrok / Saleae zeigt ACK / NACK bei jedem Byte
- die Adressphase.
- Vergleichen Sie die Aufrufe Ihres Sketches (
dev.readVoltage()usw.) mit der erwarteten Byte-Folge — sie sollten exakt übereinstimmen. Burst-Lesezugriffe (mehrere Bytes in einer Transaktion über das automatische Inkrement der Adresse) werden unterstützt. Schreibzugriffe erfolgen NICHT mit automatischem Inkrement — jedes Byte ist eine eigene Transaktion.
Weicht das Verhalten der Bibliothek von der Aufnahme ab, eröffnen Sie ein Issue mit angehängter Aufnahmedatei (.sal / .dsl / .csv).
Wann Sie den Support kontaktieren sollten
Wenn Sie den betreffenden Abschnitt oben durchgearbeitet haben und das Problem weiterhin besteht, eröffnen Sie ein Issue:
github.com/rb-amp/rbamp-arduino/issues
Nehmen Sie in die Meldung auf:
-
Host-MCU + Version des Arduino-Cores (z. B. ESP32-S3 auf Arduino-ESP32 3.0.4).
-
Bibliotheksversion (
RbAmpaus dem Bibliotheksmanager). - Firmwareversion des Moduls —
dev.firmwareVersion(). - Minimaler Sketch, der das Problem reproduziert (ca. 30 Codezeilen).
-
dev.lastError()+dev.errorString(dev.lastError())+dev.retryExhaustionCount()+dev.sanityRejectCount()im Moment des Fehlers. -
(Falls verfügbar) eine Logikanalysator-Aufnahme aus dem Moment des Fehlers.
Links
- 05 · Schnellstart — Ihr erster funktionierender Sketch
-
09 · API-Referenz — die vollständige API und Warnungen zu den öffentlichen Methoden mit WARNING
-
03 · Auswahl des Stromsensors — die SCT-013-Modelltabelle, Zwei-CT-Topologie für einen großen Dynamikbereich, Ansätze zur Verbesserung der Empfindlichkeit bei kleinen Strömen
Quelle und Probleme: rb-amp/rbamp-arduino · diese Seite im Repository: docs/10_troubleshooting.md (v1.6.2)