10 · Fehlersuche
Dieses Kapitel ist nach den beobachteten Symptomen gegliedert, nicht nach interner Fehlerklassifikation. Wenn Sie hier sind, funktioniert etwas nicht richtig. Suchen Sie Ihr Symptom in der folgenden Liste, springen Sie zum passenden Abschnitt und folgen Sie dem Diagnoseverfahren.
Die meisten Probleme am Arbeitsplatz fallen in drei Kategorien:
-
Busebene — das Modul antwortet nicht über I²C, Lesevorgänge liefern
ESP_FAILoderESP_ERR_INVALID_RESPONSE. -
Datenebene — das Modul antwortet, aber die Zahlen stimmen nicht: Nullen, seltsame Werte, falsches Vorzeichen.
-
Anwendungsebene — die Verbindung ist instabil, der Wh-Zähler driftet, das Projekt hängt.
Kurzfassung für Ungeduldige: Im Normalbetrieb sollten die öffentlichen Funktionen rbamp_* ESP_OK liefern. Wenn Sie in den Logs häufig ESP_FAIL oder ESP_ERR_INVALID_RESPONSE sehen, springen Sie direkt zum Abschnitt „Module doesn't respond over I²C“ (Modul antwortet nicht über I²C) weiter unten.
Modul antwortet nicht über I²C
Was Sie sehen: rbamp_begin(dev) liefert ESP_FAIL oder ESP_ERR_INVALID_RESPONSE, oder RT-Lesevorgänge geben regelmäßig ESP_FAIL in Ihren Code weiter.
Schritt 1 — Bus-Scan
Prüfen Sie zuerst, ob das Modul am Bus überhaupt vorhanden ist. ESP-IDF v5.x stellt dafür i2c_master_probe() bereit:
#include "driver/i2c_master.h"
#include "esp_log.h"
static const char *TAG = "i2c_scan";
void bus_scan(i2c_master_bus_handle_t bus) {
ESP_LOGI(TAG, "Scanning...");
for (uint8_t addr = 0x08; addr <= 0x77; addr++) {
if (i2c_master_probe(bus, addr, /*xfer_timeout_ms=*/100) == ESP_OK) {
ESP_LOGI(TAG, "Found 0x%02X", addr);
}
}
}
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 (siehe 04 · Verdrahtung für die GPIO-Standards je Chip).
-
Beide Leitungen haben einen Pull-up auf 3.3 V (die Modulplatine hat eingebaute 4.7 kΩ — für ein einzelnes Modul sind externe nicht nötig).
-
Der Versorgungspin des Moduls führt tatsächlich 5 V (4.5–5.5 V).
-
Kein anderer Master (Debug-Sonde, zweiter ESP32) hängt an denselben Leitungen.
-
flags.enable_internal_pullup = truein Ihreri2c_master_bus_config_t(wenn keine externen Pull-ups vorhanden sind).
Wenn das Modul gefunden wird, aber unter einer unerwarteten Adresse — jemand hat es zuvor am Arbeitsplatz neu adressiert. Aktualisieren Sie das zweite Argument von rbamp_new:
rbamp_new(bus, 0x52, &dev); /* address from the bus scan */
Schritt 2 — ESP32-Grundmuster für NACKs
Findet der Bus-Scan das Modul, liefert rbamp_read_voltage(dev, 0, &v) aber periodisch ESP_FAIL — dies ist ein dokumentiertes Basismuster: Der I2C-Treiber i2c_master aus ESP-IDF v5 hat Eigenheiten beim Betrieb mit rbAmp auf der aktuellen Firmware (häufige NACKs bei 100 kHz).
Die Abhilfe ist bereits in die Komponente eingebaut (CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=3 standardmäßig, 50 kHz über CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000), aber bei starker Last kann das Retry-Budget erschöpft werden.
Was über idf.py menuconfig → Component config → rbAmp client zu tun ist:
- Den 50-kHz-Standard bestätigen:
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000
- Erhöhen Sie die Wiederholungsanzahl bei starker Last:
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=5
- Bei Bedarf — Timeout erhöhen:
CONFIG_RBAMP_I2C_TIMEOUT_MS=200
- DEBUG-Level für das Tag
rbampaktivieren für die Diagnose:
CONFIG_RBAMP_LOG_LEVEL_DEBUG=y
Das können Sie auch zur Laufzeit tun — esp_log_level_set("rbamp", ESP_LOG_DEBUG).
Zu den Retry-/Sanity-Zählern. Die Komponente stellt öffentliche Getter rbamp_retry_exhaustion_count(dev) und rbamp_sanity_reject_count(dev) bereit — sie entsprechen plattformübergreifend den Arduino-Aufrufen dev.retryExhaustionCount() / dev.sanityRejectCount(). Das kanonische Muster Snapshot + Differenz für die Produktionsüberwachung ist im Abschnitt „Monitoring the counters“ unten beschrieben.
Fleet: Ein Modul landete nach rbamp_fleet_scan in excluded
Was Sie sehen: rbamp_fleet_scan(fleet, ...) lief und lieferte ESP_OK, aber rbamp_fleet_count(fleet) ist kleiner als die Anzahl der tatsächlich angeschlossenen Module. rbamp_fleet_excluded_count(fleet)
0; über rbamp_fleet_excluded_addr(fleet, i) iterieren — jede ausgeschlossene Adresse bedeutet „ein Modul wurde erkannt, aber NICHT zur Fleet hinzugefügt — ein Konflikt wird vermutet“.
Ursache. Der Konflikt-Detektor arbeitet mit zwei unabhängigen Signalen:
- Identitätskonsistenz: HW_VARIANT ↔ CAPABILITY-Bitmap sind inkonsistent — ein Zeichen dafür, dass zwei verschiedene physische Module unter einer Adresse antworten (die Antwort verschmilzt teilweise).
- Live-Wert: An einer Adresse werden widersprüchliche „Live“-Messwerte beobachtet — etwa ein abweichendes
LABELoder eine wechselnde Variante.
Wenn mindestens eines der beiden Signale anspricht, wird die Adresse aus der Fleet ausgeschlossen, und die Bibliothek verlässt sich NICHT auf die Messwerte dieses Moduls. Sind beide Signale ruhig, die Module aber identisch konfiguriert (gleiche Variante, gleiches CT_MODEL, gleiches LABEL), kann der Detektor sie nicht unterscheiden — das ist ein physikalisch nicht erkennbarer Fall (siehe unten zur Disziplin).
⚠ Die Erkennung erfolgt nach bestem Bemühen. Es ist unmöglich zu garantieren, dass die Fleet zwei identische Module unter einer Adresse erwischt — genau deshalb gibt es die Disziplin bei der Bereitstellung (siehe den nächsten Abschnitt).
Was zu tun ist.
- Trennen Sie alle Module bis auf eines physisch.
-
Schließen Sie die übrigen einzeln an und rufen Sie nach jedem erneut
rbamp_fleet_scanauf. Das Modul, nach dessen Anschluss einexcludederscheint, kollidiert mit einem bereits angeschlossenen. -
Provisionieren Sie das kollidierende Modul über
rbamp_provision(bus, new_address, ...)auf eine freie Adresse neu (setzt voraus, dass es das einzige auf0x50ist — siehe Provisionierungsdisziplin unten). -
Nach der Neuadressierung
rbamp_fleet_scanerneut ausführen —excluded_countsollte0sein.
Fleet: rbamp_fleet_scan lieferte ESP_ERR_INVALID_STATE + leere Fleet
Was Sie sehen: rbamp_fleet_scan lieferte ESP_ERR_INVALID_STATE, rbamp_fleet_count(fleet) ist 0. Es wurden keine Module zur Fleet hinzugefügt, obwohl sie physisch angeschlossen sind.
Ursache. Tier-2-Wedge-Canary — die Bibliothek hat eine Busprüfung durchgeführt, ob an einer Adresse etwas antwortet, die nicht antworten darf (der Canary). Hat der Canary ein ACK erhalten, ist der Bus nicht im Normalzustand: entweder erzeugt elektrisches Rauschen falsche ACKs, oder alle Adressen sind infolge einer Blockade „festgefahren“, oder es liegt ein Topologiefehler vor (mehrere Module mit demselben Code gleichzeitig, plus SDA/SCL auf Low gezogen). In diesem Zustand können Sie keinem Scan-Ergebnis trauen — daher bleibt die Flotte leer; besser abbrechen, als bewusst falsch zu initialisieren.
Was zu tun ist.
-
Den gesamten Bus stromlos schalten (Module für einige Sekunden von der Versorgung trennen, ESP32 neu starten). Das löst die hängenden Zustände.
-
Verbinden Sie die Module strikt einzeln, führen Sie nach jedem
rbamp_fleet_scanaus (Inbetriebnahme eines einzelnen Moduls) und prüfen Sie den Rückgabewert: -
ESP_OK+count=1+excluded=0→ Bus ist sauber, Modul in Ordnung. -
ESP_ERR_INVALID_STATEbleibt bestehen → Pull-ups prüfen (siehe den Abschnitt zum I²C-Hänger oben — ein externer 4.7-kΩ-Widerstand an SDA/SCL ist zwingend). -
Sobald die Inbetriebnahme eines einzelnen Moduls für jedes einzelne Modul bestanden ist, fügen Sie alle gleichzeitig dem Bus hinzu und führen
rbamp_fleet_scanerneut aus. Erhalten Sie erneutINVALID_STATE, liegt das Problem in der Elektrik des Busses (Länge, Störungen, fehlender Pull-up), nicht in den einzelnen Modulen.
Flotte: rbamp_provision hat einen Fehler zurückgegeben
Was Sie sehen: Der Aufruf rbamp_provision(bus, desired_address, save_config, &out) wurde nicht mit ESP_OK abgeschlossen. Je nach zurückgegebenem Code:
esp_err_t |
Was passiert ist | Was zu tun ist |
|---|---|---|
ESP_ERR_NOT_FOUND |
Auf 0x50 (Werkseinstellung) antwortet nichts |
Prüfen Sie, dass das neue Modul physisch angeschlossen und versorgt ist (VCC); prüfen Sie die I²C-Verdrahtung (siehe „Module doesn't respond over I²C“). |
ESP_ERR_INVALID_STATE |
Ein Konflikt wurde auf 0x50 erkannt oder die gewünschte Adresse ist bereits belegt |
Am Bus befindet sich mehr als ein jungfräuliches Modul oder die gewünschte Adresse ist bereits von einem anderen Modul belegt. Trennen Sie alle „überzähligen“ Module (siehe unten). |
ESP_ERR_TIMEOUT |
Der Adress-Commit-Befehl wurde ausgeführt, aber das Modul erschien innerhalb des Boot-Fensters nicht an der neuen Adresse | Modul stromlos schalten und erneut versuchen. Tritt es erneut auf — wahrscheinlich ein unvollständiger Flash-Vorgang (Stromausfall während CMD_SAVE_USER_CONFIG oder CMD_COMMIT_ADDR, sodass der Flash-Block teilweise geschrieben sein kann). Beim nächsten Booten liefert das Modul REG_ERROR = 0xFB (ERR_FLASH_PARAMS_BAD), lädt die Werkseinstellungen und erscheint wieder auf 0x50. Provisionieren Sie neu von vorn; schlägt auch das fehl, senden Sie es zum Service ein. |
ESP_ERR_INVALID_ARG |
desired_addr liegt außerhalb des gültigen Bereichs 0x08..0x77 |
Verwenden Sie eine gültige Adresse. |
⚠ Disziplin bei der Bereitstellung — es darf immer nur EIN neues Modul angeschlossen sein.
Die häufigste Ursache für INVALID_STATE bei der Bereitstellung ist, dass mehr als ein Modul mit der Werksadresse 0x50 am Bus liegt. Sie über I²C zu unterscheiden ist physikalisch unmöglich (Open-Drain mit verdrahtetem UND — beide Module quittieren identisch, und die Rücklesedaten kommen „verschmolzen“ zurück).
Die Regel ist also streng (ein normatives MUSS, keine Empfehlung): Im Moment des Aufrufs von rbamp_provision muss genau ein Modul auf 0x50 liegen (neu oder über ein separates Werkzeug auf Werkseinstellungen zurückgesetzt). Kein „Ich bin sicher, dass diese beiden Module verschieden sind — ich trenne sie jetzt einfach“ — das funktioniert nicht; die Kollision zeigt sich später, wenn Sie bereits glauben, die Fleet sei sauber.
Wiederherstellungspfad bei vermuteter Verletzung der Disziplin: 1. Alle Module stromlos schalten. 2. Alle bis auf das eine „neue“ Modul physisch trennen (das, das Sie neu adressieren wollen). 3. rbamp_provision auf dem Ein-Modul-Bus aufrufen. 4. Die übrigen Module einzeln hinzufügen und jedes separat bereitstellen.
Strom zeigt null bei einer arbeitenden Last
Was Sie sehen: rbamp_read_current(dev, 0, &i) liefert ESP_OK, aber i = 0.000 (oder ein sehr kleiner Wert), obwohl ein echter Verbraucher eingeschaltet ist (Wasserkocher, Lampe, Bügeleisen). rbamp_read_power_factor(dev, 0, &pf) kann einen seltsamen Wert anzeigen (nan / 0 / ±1) — das ist eine Folge; die Ursache liegt im Strom.
Diagnoseverfahren
- Prüfen Sie, dass Sensorklasse und CT-Modell konfiguriert sind:
esp_err_t err = rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013);
if (err != ESP_OK) {
ESP_LOGE(TAG, "set_sensor_class: %s", rbamp_err_to_str(err));
}
err = rbamp_set_ct_model(dev, 3); /* or your model */
if (err != ESP_OK) {
ESP_LOGE(TAG, "set_ct_model: %s", rbamp_err_to_str(err));
}
Ohne diese beiden Aufrufe werden die Kalibrierkoeffizienten nicht geladen, und der Strom liest immer null. Dieser Schritt wird einmal bei der Erstinstallation ausgeführt — die Wahl wird im Flash des Moduls gespeichert.
Falle bei RBAMP_SENSOR_UNSET. Rufen Sie versehentlich rbamp_set_sensor_class(dev, RBAMP_SENSOR_UNSET) auf — die Funktion liefert ESP_OK, setzt die Klassenkonfiguration aber faktisch zurück. Ein nachfolgender Aufruf von rbamp_set_ct_model*() liefert dann ESP_ERR_INVALID_STATE. Abhilfe: rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013) erneut aufrufen, danach rbamp_set_ct_model() erneut aufrufen.
- Prüfen Sie, dass das CT-Modell zur Last passt. Eine große CT-Zange (z. B. SCT-013-100, 100 A) an einer kleinen Last (eine 50-W-Lampe ≈ 0.2 A) erzeugt ein Signal an der Grenze des Rauschpegels, und die Messwerte sind null. Wählen Sie das kleinste CT-Modell, das Ihren maximal erwarteten Strom abdeckt. Die vollständige Tabelle steht in 03 · Auswahl des Stromsensors.
Wenn Sie ein Mehrkanal-Modul (UI2 / UI3 / UI5 / UI7) haben und sowohl kleine Lasten als auch Lastspitzen sehen wollen, erwägen Sie das Dual-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 einen Schwellenwert. Das Muster wird in 03 · Auswahl des Stromsensors, Abschnitt „Dual-CT topology“, behandelt.
- Prüfen Sie die Ausrichtung der Zange. Der Pfeil am Zangenkörper muss in Stromflussrichtung zur Last hin zeigen. Ist die Zange „verkehrt herum“, liefert
rbamp_read_current()dem Betrag nach den richtigen Wert, aberrbamp_read_power()liefert bei einer Verbraucherlast einen negativen Wert. Bestätigung:rbamp_read_power_factor()zeigt bei einer ohmschen Last genau −1.0 (statt +1.0). Abhilfe: Entweder die Zange physisch neu anbringen (öffnen, den Pfeil in die richtige Richtung drehen, wieder schließen) oder das Vorzeichen auf der Master-Seite umkehren.
Wenn alle drei Schritte bestanden werden, der Strom aber weiter null ist
Dann liegt das Signal am Modulenenngang tatsächlich unter dem Grundrauschen. Prüfen Sie:
-
Fließt tatsächlich Strom — mit einem Multimeter (Gleich- / Wechselstrom-Zangenmessgerät) am selben Draht messen.
-
Ist die Zange intakt — an der Zangenbuchse sollte eine Wechselspannung anliegen, die proportional zum Strom ist (wenige Millivolt bei Verbraucherlasten).
-
Klemmen Sie den richtigen Draht? Den Außenleiter (Phase) und nur diesen einen Leiter (nie das ganze Kabel).
Messwerte springen oder liefern ESP_FAIL
Was Sie sehen: rbamp_read_voltage(dev, ...) oder rbamp_read_current(dev, ...) liefern periodisch ESP_FAIL. Der Wert in *out ist nach einem Fehler undefiniert.
ESP_FAIL aus der Komponente deckt zwei Problemklassen ab:
- NACK nach Ausschöpfen der Wiederholungen — die Verbindung ist instabil.
- Der Plausibilitätsfilter hat den Wert verworfen — ein Float
NaN/Inf/|x| > 10000kam über den Bus (ein eindeutig unphysikalischer Wert).
Die ESP-IDF-API unterscheidet sie nicht über eigene esp_err_t-Codes (anders als Arduinos RB_ERR_NACK / RB_ERR_NON_PHYSICAL) — beide liefern ESP_FAIL. Sie lassen sich über die Diagnosezähler unterscheiden (siehe den Abschnitt „Überwachung der Zähler“ unten). Beide Symptome werden gleich behandelt:
-
Den Standard von 50 kHz bestätigen und den Retry über Kconfig auf 5 erhöhen — siehe vorigen Abschnitt.
-
Die Lastdichte am Bus reduzieren — wenn Ihre Schleife viele Einzelbyte-Lesezugriffe macht, versuchen Sie
rbamp_read_all()(eine I²C-Transaktion statt ~13). -
Prüfen Sie
CONFIG_RBAMP_I2C_TIMEOUT_MS— antwortet das Gerät langsamer als üblich (lange Leitung, schlechter Kontakt), erhöhen Sie den Timeout. -
DEBUG-Protokollierung aktivieren über
CONFIG_RBAMP_LOG_LEVEL_DEBUG=yoderesp_log_level_set("rbamp", ESP_LOG_DEBUG)— die Komponente gibt Details des Retry-Zyklus und der Sanity-Ablehnungen unter dem Tag"rbamp"aus.
Überwachung der Zähler
Die Komponente stellt zwei öffentliche monotone Zähler für die Überwachung des Busses im Produktivbetrieb bereit:
uint32_t rbamp_retry_exhaustion_count(rbamp_handle_t dev);
uint32_t rbamp_sanity_reject_count(rbamp_handle_t dev);
retry_exhaustion_count wird erhöht, wenn eine einbyte-Transaktion das Budget von CONFIG_RBAMP_NACK_RETRY_ATTEMPTS ausgeschöpft und ESP_FAIL geliefert hat. sanity_reject_count wird erhöht, wenn der Plausibilitätsfilter einen Float verwirft (!isfinite(x) || |x| > 10000).
Der kanonische Ablauf ist ein Snapshot + Differenz alle 60 Sekunden, um eine „Ereignisrate pro Minute“ zu erhalten:
uint32_t prev_retry = rbamp_retry_exhaustion_count(dev);
uint32_t prev_sanity = rbamp_sanity_reject_count(dev);
/* ...60 s of normal operation (do N rbamp_read_* calls)... */
uint32_t now_retry = rbamp_retry_exhaustion_count(dev);
uint32_t now_sanity = rbamp_sanity_reject_count(dev);
uint32_t retry_delta = now_retry - prev_retry;
uint32_t sanity_delta = now_sanity - prev_sanity;
if (retry_delta > THRESHOLD || sanity_delta > THRESHOLD) {
ESP_LOGW(TAG, "bus health: retry+%u sanity+%u per minute",
retry_delta, sanity_delta);
}
Alarmschwellen hängen von der Last ab. Für ein dichtes Dauertest-Muster (wie der Arduino SoakMonitor — ~70 Byte pro Zyklus, einmal alle 5 Minuten):
retry_delta > 1/Stunde— harmloses Rauschen, kann ignoriert werden.-
retry_deltadauerhaft > 5/Stunde — untersuchenswert (schlechte Kontakte, Buskapazität, Temperaturdrift der Pull-ups). -
sanity_delta > 0im Dauerbetrieb — fast immer ein Zeichen für elektromagnetische Störungen am Bus oder einen Firmware-Rückschritt.
Die Zähler steigen nur (werden nie zurückgesetzt) — um sie zurückzusetzen, müssen Sie das Handle über rbamp_del(dev) + rbamp_new(...) neu erzeugen. Das ist Absicht, damit Sie keine Historie durch Wettläufe zwischen „Reset“ und „Lesen in den Logger“ verlieren.
Plattformübergreifend entsprechen diese Zähler der Semantik der Arduino-Aufrufe dev.retryExhaustionCount() / dev.sanityRejectCount() — dieselben Namen (snake_case statt camelCase), dieselben Schwellenwerte wirken gleich.
Leistungsfaktor wirkt falsch
Was Sie sehen: rbamp_read_power_factor(dev, 0, &pf) liefert ESP_OK, aber pf passt nicht zur Art der Last.
Erwartungen je Last:
| Last | Erwarteter PF |
|---|---|
| Wasserkocher, Bügeleisen, Glühlampe | +0.95 .. +1.0 (ohmsch) |
| Kühlschrank, Kompressormotor | +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 undefiniert. Der konkret gelieferte Wert hängt von der Firmware ab (er kann 0 oder ein Platzhalter nahe null sein) — das ist normal, solange der Strom tatsächlich null ist. Sobald Strom fließt, erscheint ein gültiger PF. Der Plausibilitätsfilter der Komponente verwirft diesen Wert nicht (daher erhöht sich das Äquivalent sanityRejectCount in IDF nicht) — er ist ein gültiges Maß für eine undefinierte Größe, kein Verbindungsfehler.
PF strikt −1.0 bei einer rein verbrauchenden Last
Die Zange ist „verkehrt herum“ angebracht — der Pfeil zeigt von der Stromflussrichtung weg, zur Last hin. Abhilfe: Entweder die Zange richtig neu anbringen oder das Vorzeichen auf der Master-Seite behandeln (p = -p; pf = -pf;, wenn Sie wissen, dass die Last kein PV-Wechselrichter sein kann).
Der Leistungsfaktor schwankt bei einer ohmschen Last zwischen +0.3 und +0.7
-
Mögliche Ursache: Die CT-Zange liegt auf einem Draht einer anderen Phase als der, an die der U-Eingang des Moduls angeschlossen ist. Bei einer Verteilung mit mehreren Phasen klemmt man leicht an der falschen Phase — eine Phasenverschiebung von 120° oder 180° zwischen U und I ergibt genau diese PF-Werte. Die Abhilfe: Modul so installieren, dass U-Eingang und CT auf derselben Phase liegen.
-
Alternative: Die Last ist tatsächlich nicht rein ohmsch. Wiederholen Sie den Test mit einer bekannten ohmschen Last (einem Wasserkocher bei voller Leistung).
Periodensnapshots sind immer stale
Was Sie sehen: rbamp_read_period_snapshot(dev, ...) liefert ESP_ERR_INVALID_RESPONSE oder *out.valid == false. Das bedeutet, dass das Modul die Integration der vorherigen Periode bis zum nächsten Lesevorgang nicht abgeschlossen hat.
Die Komponente verhindert doppelte Zählung von Wh: Bei einem veralteten Snapshot erfasst sie einen Master-Zeitstempel (esp_timer_get_time()), und der nächste erfolgreiche Snapshot 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.
Prüfablauf für die Taktung
-
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 (rbamp_probe(dev) == ESP_OK) {
ESP_LOGI(TAG, "alive");
}
- Das Flag direkt prüfen —
rbamp_is_period_valid()führt einen Einzelbyte-Lesevorgang ohne Nebenwirkungen aus:
bool valid;
if (rbamp_is_period_valid(dev, &valid) == ESP_OK && valid) {
/* avg_p[] can be read */
}
- Firmware-Version prüfen —
rbamp_firmware_version(dev) >= 0x02zeigt weniger Stales als 0x01. Aktuelle kanonische Firmware ist0x04(v1.3);0x01=v1.0,0x02=v1.1,0x03=v1.2.
Sonderfall — Aufwachen aus dem Deep-Sleep
Wenn Sie ein Deep-Sleep-Muster verwenden, ist der Standard-Aufruf rbamp_read_period_snapshot() direkt nach rbamp_begin() immer veraltet (oder liefert nahe-null-Werte) — begin() erstellt einen Näherungs-Snapshot, der den Akkumulator der Firmware zurücksetzt. Das kanonische Muster verwendet skip_latch=true + den eigenen, im RTC gespeicherten Zeitstempel des Masters — siehe 06 · Beispiele, Szenario 9.
Wh-Abrechnung weicht von einer Referenz ab
Was Sie sehen: rbamp_energy_wh(dev, 0) weicht nach mehreren Stunden / Tagen Betrieb vom Zählerstand des Energieversorgers oder einem Referenzzähler (Kill-A-Watt usw.) ab.
Schließen Sie zuerst das Triviale aus
-
Kalibrierung des Stromsensors: Bestätigen Sie, dass
rbamp_set_sensor_class()undrbamp_set_ct_model()mit dem richtigen CT-Modell aufgerufen wurden (siehe 03 · Auswahl des Stromsensors). Ohne das wird der Effektivstrom mit einem Standard-Grundwert berechnet, und der Leistungswert ist systematisch verzerrt. -
Verworfene veraltete Snapshots: Liegt
rbamp_energy_wh()dauerhaft unter der Referenz, könnten Intervalle fehlen — der Snapshot kam veraltet an, die Komponente verhinderte doppeltes Zählen, aber die Intervallmessung ging verloren. Prüfen Sie den Takt (siehe oben). -
Drift der Master-Uhr:
esp_timer_get_time()ist für sich genommen zuverlässig. Geht der Master jedoch in den Deep-Sleep, ohne die RTC zu sichern, geht das Intervall zwischen dem vorherigen und dem nächsten Snapshot verloren. Verwenden Sie für Deep-Sleep-Szenarien das Muster RTC_DATA_ATTR aus Szenario 9.
Genauigkeit des Akkumulators
Der Wh-Akkumulator im Handle wird als 64-Bit-double gespeichert.
Wenn Sie die Komponente mit CONFIG_RBAMP_DISABLE_ENERGY=y gebaut haben, werden Energiespeicher und API vollständig aus dem Binärcode entfernt. In diesem Fall müssen Sie einen eigenen Wh-Zähler im Anwendercode führen.
snap.latch_ms — diagnostisch, nicht für Energie
latch_ms ist ein Diagnose-Timer des Moduls; nicht für die Energie verwenden — nutzen Sie die Uhr des Masters.
ESP32-Projekt hängt nach einigen Minuten
Was Sie sehen: Ein ESP32-Projekt startet normal und geht dann nach 1–30 Minuten in einen Hänger / eine Neustartschleife / einen WDT-Timeout über.
IDF-i2c_master hängt bei einem grenzwertigen Bus — dreistufige Abschwächung
Was Sie konkret sehen: Ein ESP32-Projekt (klassisch v1.0, IDF v5.4.1, neuer i2c_master-Treiber) fragt rbAmp einige Minuten lang einwandfrei ab und hängt sich dann „tot“ mitten in einem Aufruf rbamp_*_read_* oder rbamp_fleet_poll_all auf. Der Task-WDT (falls aktiviert) fängt den Hänger ab; sonst reagiert das Projekt einfach nicht mehr. Der dekodierte Backtrace endet bei i2c_ll_is_bus_busy (Datei i2c_master.c:526, Warten auf freien Bus vor dem Senden).
Was passiert: Auf einem grenzwertigen Bus (schwache Pull-ups, lange Leiterbahnen, EMV, Störungen durch Nulldurchgangsflanken) können SDA/SCL kurzzeitig in einem unbestimmten Zustand „hängen bleiben“. Vor jeder Transaktion dreht der i2c_master des IDF in der Spin-Schleife i2c_ll_is_bus_busy und wartet, bis der Bus frei wird — diese Schleife ist NICHT durch den Parameter xfer_timeout_ms begrenzt. Dauert „Bus belegt“ länger, als die Schleife ohne Abgabe an andere Tasks laufen kann, bekommt der IDLE-Task der FreeRTOS keine CPU-Zeit, und die gesamte App hängt.
Das ist kein „nur für den Debugger sichtbares Artefakt“. Auf dem Prüfstand validiert: an derselben Hardware-Testanordnung und 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 Hänger (Läufe von 5 und 25 Minuten, 0 Neustarts) |
Der Zusammenhang ist eindeutig — eine Behebung der Busintegrität beseitigt den Hänger vollständig. Die Bibliothekslogik ist nicht schuld: Die Mechanik je Modul (fleet_poll_all, MISS/Desync, Lecküberprüfungen) blieb bei jedem Lauf bis zum Hänger sauber.
Dreischichtige Minderung (wenden Sie alle drei Schichten an):
-
Externer Pull-up (~4.7 kΩ) an SDA und SCL gegen 3.3 V an einem einzigen Punkt des Busses. Die im ESP32 integrierten Pull-ups (~45 kΩ) sind für einen mehrteiligen Bus realer Länge zu schwach, während die in die Module eingebauten 4.7-kΩ-Pull-ups parallel zu stark werden. Trennen Sie an einem solchen Bus die eingebauten bei allen Modulen bis auf eines (oder bei allen — dann verlassen Sie sich nur auf die externen). Siehe 04 · Verdrahtung, Abschnitt „Multi-module bus — primary topology“.
-
Betreiben Sie keinen Produktionsbuild mit angeschlossenem Debugger-NRST. Im Debug-Betrieb kann die Reset-Leitung SDA/SCL beim Trennen und Anschließen in einem unbestimmten Zustand halten und beim nächsten Zugriff eine Busblockade auslösen. Im Feld-Build (ohne Debugger) entfällt dieser Faktor.
-
App-weiter Task-WDT auf der Abfrage-Task — Verteidigung in der Tiefe. Falls die Pull-ups aus irgendeinem Grund grenzwertig bleiben oder eine andere Ursache für ein Blockieren auftritt, startet der WDT das Projekt neu, und wenn ein Supervisor vorhanden ist (z. B. ein rollierender Bootloader der App oder ein systemd-artiger Supervisor), läuft es wieder hoch. Bei einem Soak-Test am Bench über eine Stunde fing der WDT alle 12 Hänger in der Konfiguration ohne externen Pull-up ab und erholte sich davon.
#include "esp_task_wdt.h"
void app_main(void) {
/* Layer 3 setup — defense-in-depth. */
esp_task_wdt_config_t wdt_cfg = {
.timeout_ms = 10000, /* 10 s with plenty of margin */
.idle_core_mask = 0,
.trigger_panic = true, /* on timeout — panic+reboot */
};
ESP_ERROR_CHECK(esp_task_wdt_reconfigure(&wdt_cfg));
ESP_ERROR_CHECK(esp_task_wdt_add(NULL)); /* this task is under the WDT */
/* ... bus / fleet init ... */
while (1) {
rbamp_fleet_poll_all(fleet, snaps, status, RBAMP_FLEET_MAX_MODULES, &n_ok);
/* ... processing ... */
esp_task_wdt_reset(); /* "I'm alive" — every cycle */
vTaskDelay(pdMS_TO_TICKS(200));
}
}
Was NICHT zu tun ist: Versuchen Sie nicht, das Problem über ein größeres xfer_timeout_ms zu umgehen — es begrenzt das Warten auf einen belegten Bus nicht, das ist ein anderer Codepfad im Treiber. Die Lösung ist die Integrität des Busses (Schicht 1) + Supervisor (Schicht 3).
Watchdog-Timeout beim Verbinden mit dem WLAN
Ursache: Eine unbegrenzte WiFi-Verbindungswartschleife in einem Event-Handler löst nach ~5 s (Standard) den Task-WDT aus.
Abhilfe: Verwenden Sie ein ereignisgesteuertes Muster statt einer Busy-Wait-Schleife. Der WiFi-Treiber von ESP-IDF sendet die Ereignisse WIFI_EVENT_STA_DISCONNECTED und IP_EVENT_STA_GOT_IP — reagieren Sie darauf über esp_event_handler_register(), statt in einer Schleife abzufragen.
Minimales Muster:
static EventGroupHandle_t wifi_event_group;
#define WIFI_CONNECTED_BIT BIT0
#define WIFI_FAIL_BIT BIT1
static void wifi_event_handler(void *arg, esp_event_base_t event_base,
int32_t event_id, void *event_data) {
if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_DISCONNECTED) {
esp_wifi_connect(); /* auto-reconnect */
} else if (event_base == IP_EVENT && event_id == IP_EVENT_STA_GOT_IP) {
xEventGroupSetBits(wifi_event_group, WIFI_CONNECTED_BIT);
}
}
/* In app_main, wait for the event with a timeout: */
EventBits_t bits = xEventGroupWaitBits(
wifi_event_group, WIFI_CONNECTED_BIT | WIFI_FAIL_BIT,
pdFALSE, pdFALSE, pdMS_TO_TICKS(30000));
if (!(bits & WIFI_CONNECTED_BIT)) {
esp_restart();
}
MQTT-Broker trennt die Verbindung etwa alle 15 s
Ursache: In den meisten Fällen ist dies nicht das Keepalive. Das Standard-session.keepalive in esp_mqtt_client_config_t ist 120 s, und disable_keepalive ist standardmäßig false (d. h., das Keepalive ist an). Das Umschreiben dieser Felder mit denselben Werten ändert nichts — stirbt die Verbindung alle 15 s, liegt die echte Ursache im Netz (ein dazwischenliegendes NAT/Firewall, das inaktive TCP-Verbindungen verwirft) oder in einem WiFi-Abbruch.
Abhilfe: MQTT_EVENT_DISCONNECTED registrieren und explizit neu verbinden. esp_mqtt_client_start() startet intern eine eigene Task; Sie müssen keine separate mqtt.loop() antreiben — verbinden Sie einfach bei dem Ereignis neu.
static void mqtt_event_handler(void *arg, esp_event_base_t base,
int32_t event_id, void *event_data) {
if (event_id == MQTT_EVENT_DISCONNECTED) {
ESP_LOGW("mqtt", "disconnected — reconnecting on timeout");
/* esp-mqtt reconnects automatically with backoff;
* this handler is the place to clean up application state
* (retained flags, discovery payload caches). */
}
}
const esp_mqtt_client_config_t cfg = {
.broker.address.uri = "mqtt://192.168.1.10:1883",
/* leave keepalive at the default — 120 s;
* for aggressive NATs, lower it to 30 s: */
/* .session.keepalive = 30, */
};
esp_mqtt_client_handle_t client = esp_mqtt_client_init(&cfg);
esp_mqtt_client_register_event(client, ESP_EVENT_ANY_ID,
mqtt_event_handler, NULL);
esp_mqtt_client_start(client);
Wenn die Abbrüche zeitlich mit WLAN-Ausfällen zusammenfallen, liegt die eigentliche Ursache im WLAN (RSSI, ein überlasteter Kanal), nicht bei MQTT. Prüfen Sie die Nutzlast von MQTT_EVENT_ERROR und die WLAN-Logs, bevor Sie am Keepalive etwas ändern.
Fehlgeschlagener TLS-Handshake (Cloud-Integrationen)
Ursache: Der Heap des ESP32 reicht für den TLS-Handshake nicht aus (~30 kB nötig). Oft zusammen mit WLAN + MQTT + Puffern, sodass weniger als 20 kB frei bleiben.
Fix:
- Verwenden Sie
WiFi.mode(WIFI_MODE_STA)(nichtSTA+AP). -
Deaktivieren Sie BLE, falls Sie es nicht brauchen:
CONFIG_BT_ENABLED=nin sdkconfig. -
Verkleinern Sie die MQTT-Puffergrößen in
esp_mqtt_client_config_t. - Umstieg auf ESP32-S2 (kein Bluetooth — ~30 kB Heap gespart).
Zeigt esp_get_free_heap_size() vor esp_mqtt_client_start() oder esp_http_client_perform() weniger als 25 kB, wird der TLS-Handshake höchstwahrscheinlich scheitern.
Fehlerbehandlung: letzter Schreibzugriff auf REG_ERROR + EVENT_FLAGS.bit3 dauerhaft (v1.3)
v1.3-Kanon (HW-bestätigt): REG_ERROR (0x02) ist Ergebnis des letzten Schreibvorgangs, NICHT klebrig. Bei jedem Registerschreibvorgang setzt die Firmware reg_error = ERR_OK; ein folgender, nicht zusammenhängender 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 einem Vorgang (wenn das Ergebnis genau DIESES Vorgangs zählt):
esp_err_t err = rbamp_save_user_config(dev);
uint8_t dev_err;
rbamp_read_last_error(dev, &dev_err); /* IMMEDIATELY, before the next write */
Muster 2 — dauerhafte Fehlerüberwachung (kanonisch für Dauerbetrieb):
uint8_t event_flags;
rbamp_read_event_flags(dev, &event_flags);
if (event_flags & RBAMP_EVENT_ERROR) {
uint8_t last_err;
rbamp_read_last_error(dev, &last_err); /* what was the last rejected */
/* handle the error */
rbamp_clear_error(dev); /* clears REG_ERROR ... */
rbamp_clear_event_flags(dev, RBAMP_EVENT_ERROR); /* ... then the sticky bit */
}
⚠ UMKEHRUNG der früheren „sticky“-Dokumentation (Kanon v1.3 A3). REG_ERROR ist das Ergebnis des letzten Schreibens, nicht dauerhaft. Dauerhaftigkeit liefert EVENT bit3.
⚠ Bit 3 ist ein asynchroner Kanal, nicht für die synchrone Schreibvalidierung gedacht: Bei einem abgelehnten Schreibvorgang wird Bit 3 zeitversetzt gesetzt, bezogen auf den Zeitpunkt, zu dem die I²C-Transaktion zurückkehrt. Fragen Sie Bit 3 nicht unmittelbar nach einem Schreibvorgang ab, um dessen Ergebnis zu prüfen — für das Ergebnis Ihres eigenen Schreibvorgangs verwenden Sie Muster 1 (eine einmalige Erfassung von REG_ERROR direkt nach der Operation) oder den Rückgabewert des Setters. bit3 dient der langfristigen Überwachung asynchroner Zustände (Laufzeit, Befehlspfad), nicht der Validierung einer gerade ausgeführten Operation.
Vorsicht: DEV_ERR_CLONE (0xF9) wird NICHT über CMD_CLEAR_ERROR gelöscht — ein Anti-Klon-Sentinel (nur Neustart oder Werksreset).
Frisch geflashtes Modul zeigt beim ersten Start 0xFB (NORMAL)
Was Sie sehen: Ein frisch geflashtes Modul zeigt beim ersten Start REG_ERROR = 0xFB (DEV_ERR_FLASH_PARAMS_BAD) + EVENT bit3.
Ursache: Parameterseite nicht initialisiert → Werkseinstellungen geladen. Das ist NORMAL für ein neues Modul, nicht fatal.
Lösung: Sensorklasse + ct_model + (optional) Adresse konfigurieren, dann CMD_SAVE_USER_CONFIG. Nach erfolgreichem SAVE → REG_ERROR = 0x00, Bit 3 gelöscht.
rbamp_set_sensor_class / rbamp_set_ct_model* liefert ESP_ERR_INVALID_STATE
Was Sie sehen: einer der Konfigurationsaufrufe liefert ESP_ERR_INVALID_STATE.
ESP_ERR_INVALID_STATE aus dieser Funktionsgruppe ist ein Sammelcode für drei verschiedene Ursachen. Sie lassen sich über die Logzeile ESP_LOGW unterscheiden, die die Komponente unter dem Tag "rbamp" unmittelbar vor der Rückgabe ausgibt:
| Logzeile (ESP_LOGW, TAG="rbamp") | Ursache | Lösung |
|---|---|---|
set_ct_model_ch refused: sensor class is UNSET (call rbamp_set_sensor_class first) |
Vorbedingung: Die Sensorklasse muss gesetzt sein, bevor das CT-Modell geschrieben wird | Rufen Sie rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013) auf, bevor rbamp_set_ct_model*(). |
set_ct_model_ch refused: bind sequence error (call rbamp_set_sensor_class first to reset batch) |
Der interne Batch-Tracker der Komponente ist mit dem Staging-Zustand der Firmware nicht synchron | Bei Firmware v1.3 ist die Bindungsreihenfolge der Kanäle beliebig (reines Staging Fix-A — siehe 03 · Auswahl des Stromsensors). Rufen Sie rbamp_set_sensor_class() erneut auf, um den Batch-Tracker zurückzusetzen, und binden Sie dann Kanäle in beliebiger Reihenfolge. Die Formulierung „descending order required“ aus älteren Logmeldungen bezieht sich auf das Verhalten vor v1.3 und gilt nicht mehr. |
Es gibt auch den Fall eines Handles, das initialisiert ist, aber auf dem rbamp_begin() nie aufgerufen wurde — dies liefert ESP_ERR_INVALID_STATE ohne Zeile ESP_LOGW (das Handle ist noch „kalt“). Lösung: rbamp_begin(dev) nach rbamp_new() und vor jedem rbamp_set_* aufrufen.
Das Muster der Unterscheidung über das Log ist ein Standardidiom in ESP-IDF: Vergleichen Sie es mit esp_driver_i2c, das ESP_ERR_TIMEOUT sowohl für einen ACK-Timeout als auch für einen Bus-belegt-Timeout liefert und beide über das Log unterscheidet. Sehen Sie ESP_ERR_INVALID_STATE ohne klare Ursache, erhöhen Sie den Log-Level über esp_log_level_set("rbamp", ESP_LOG_WARN) (oder _DEBUG) und wiederholen Sie den Aufruf: Die Komponente sagt Ihnen, welcher der drei Fälle vorliegt. rbamp_err_to_str(ESP_ERR_INVALID_STATE) liefert eine allgemeine Beschreibung: „Wrong call sequence (check log: factory mode / sensor class UNSET / bind batch out of sync)“ (Falsche Aufrufreihenfolge — Log prüfen: Werksmodus / Sensorklasse UNSET / Bind-Batch nicht synchron).
rbamp_set_sensor_class / rbamp_set_ct_model* liefert ESP_ERR_INVALID_ARG
Was Sie sehen: Der Aufruf liefert ESP_ERR_INVALID_ARG.
Mögliche Ursachen:
-
Ungültiger Modellcode für die Klasse — die gültigen Codes hängen von der Sensorklasse ab:
SCT013akzeptiert{1, 2, 3, 4, 5, 6, 7}(siehe Tabelle in 03 · Auswahl des Stromsensors);WIRED_CTakzeptiert1–10und12. Ein Code, der für die Klasse unbekannt ist, liefertESP_ERR_INVALID_ARG. -
Ungültiger Kanalindex in der Form je Kanal
rbamp_set_ct_model_ch(dev, channel, code)— muss <rbamp_channels(dev)sein. -
Ein ungültiger Wert für
rbamp_sensor_class_t— eine Klasse über3liefertESP_ERR_INVALID_ARG. Module, die zusammen mit ihrem eigenen Sensor kalibriert geliefert werden (RBAMP_SENSOR_WIRED_CT,RBAMP_SENSOR_BUILTIN_CT), lehnen einen Klassen- oder Modellwechsel ab (ESP_ERR_INVALID_STATE); für eine aufklemmbare SCT-013-Stromzange verwenden SieRBAMP_SENSOR_SCT013. -
dev == NULLoderout == NULL— prüfen Sie, dassrbamp_new()erfolgreich war (ESP_OKzurückgegeben).
rbamp_commit_address_change liefert ESP_ERR_TIMEOUT
Wenn prepare erfolgreich war, commit aber ESP_ERR_TIMEOUT liefert, ist das „Scharfschalt“-Fenster abgelaufen (5 Sekunden nach prepare). rbamp_probe() hilft hier nicht (das Modul antwortet; das Problem liegt in der Zustandsmaschine). Die Abhilfe: rbamp_prepare_address_change() erneut und sofort aufrufen — in derselben app_main-Iteration, ohne Netzwerkaufrufe dazwischen — und dann rbamp_commit_address_change() aufrufen. WLAN / MQTT / jede blockierende E/A zwischen prepare und commit ist die Hauptursache für das Ablaufen des Fensters.
Zu den öffentlichen Methoden mit Warnung siehe 09 · API-Referenz, Abschnitt „Sensorkonfiguration“.
Lesezugriffe scheitern beim Schalten von Relaislasten (EMV-Transienten)
Was Sie sehen: rbamp_read_* liefert periodisch ESP_FAIL / ESP_ERR_INVALID_RESPONSE, aber nur, während auf demselben Aufbau eine Relais- oder induktive Last aktiv schaltet. Im Dauerbetrieb sind die Lesevorgänge zuverlässig.
Ursache (C.12 HW-bestätigt): Während des Relaisschaltens (eine 5-A-Last) scheitern ~67 % der I²C-Transaktionen durch EMV (~8/12 bei der Hardwaremessung). Der Bus erholt sich selbst, es entsteht keine Blockade, kein Modul geht verloren — aber der aktuelle Lesevorgang schlägt fehl.
Lösung — Wiederholung auf Anwendungsebene:
esp_err_t robust_read_voltage(rbamp_handle_t dev, float *v) {
for (int attempt = 0; attempt < 5; attempt++) {
esp_err_t err = rbamp_read_voltage(dev, 0, v);
if (err == ESP_OK) return ESP_OK;
vTaskDelay(pdMS_TO_TICKS(20)); // short pause before retry
}
return ESP_FAIL;
}
⚠ Ein master-seitiges bus_reset allein reicht nicht: Überlappt eine EMV-Störung das Retry-Fenster des Treibers, brauchen Sie einen expliziten Wiederholungsversuch auf Anwendungsebene mit einer Pause.
Alternative: Sieht der Master Ereignisse durch Relaisschaltungen — Lesevorgänge um ~50–100 ms nach dem Schalten verzögern.
Task-WDT-Neustart bei EMV-Störungen / hoher Last
Was Sie sehen: Der ESP32 startet unerwartet mit dem Grund TASK_WDT neu. Das geschieht meist bei EMV-Ereignissen (Relaisschaltungen, induktive Transienten).
Ursache: Bei durch EMV verlangsamten Lesevorgängen (NACK-Wiederholung + Bus-Reset-Zyklen) kann der I2C-Treiber i2c_master aus ESP-IDF eine Transaktion auf ~100 ms+ strecken. Läuft eine Task eine enge Massenlese-Schleife ohne Abgabe der Kontrolle — Task-WDT-Timeout.
Lösung — in der Massenlese-Schleife abgeben:
// WRONG — no yield, under EMI → WDT reboot
for (int i = 0; i < N_METERS; i++) {
rbamp_read_period_snapshot(meters[i], &snaps[i], 0, true);
}
// CORRECT — yield every N reads (or every iteration)
for (int i = 0; i < N_METERS; i++) {
rbamp_read_period_snapshot(meters[i], &snaps[i], 0, true);
vTaskDelay(1); // yield + WDT feed
}
Alternative: esp_task_wdt_reset() explizit aufrufen, wenn die Task vom WDT überwacht wird.
Übersichtstabelle der Fehlercodes
Die Funktionen rbamp_* liefern Standardwerte von esp_err_t. rbamp_err_to_str(err) liefert eine lesbare Zeichenkette.
| Code | Wann | Wo nachzuschlagen ist |
|---|---|---|
ESP_OK (0) |
Erfolg | — |
ESP_FAIL (-1) |
NACK nach Wiederholung; oder der Plausibilitätsfilter hat den Wert verworfen | Abschnitt „Modul antwortet nicht über I²C“ |
ESP_ERR_INVALID_ARG (0x102) |
dev == NULL, channel/phase außerhalb des Bereichs, ein unbekanntes cls, ein Wert, den das Modul ablehnt |
Die Aufrufargumente prüfen |
ESP_ERR_TIMEOUT (0x107) |
rbamp_wait_ready abgelaufen (Modul antwortet nicht) ODER das 5-s-Fenster zwischen prepare_address_change und commit_address_change ist abgelaufen |
für wait_ready — über rbamp_probe(); für commit — neu scharf schalten: prepare + commit unmittelbar hintereinander ohne blockierende E/A dazwischen |
ESP_ERR_INVALID_STATE (0x103) |
Vorbedingung: set_ct_model* vor set_sensor_class |
der Abschnitt set_* oben |
ESP_ERR_NOT_SUPPORTED (0x106) |
die Funktion ist auf der aktuellen SKU nicht verfügbar (z. B. die Spannungs-API auf einer I*-Variante) | prüfen Sie rbamp_line(dev) und rbamp_variant(dev) |
ESP_ERR_INVALID_RESPONSE (0x108) |
Periodensnapshot veraltet; oder REG_VERSION = 0/0xFF bei rbamp_begin |
Abschnitt „Period snapshots are always stale“ / „Module doesn't respond“ |
ESP_ERR_NO_MEM (0x101) |
Speicher für das Handle konnte nicht reserviert werden | das Heap-Budget prüfen (esp_get_free_heap_size()) |
Fehlersuche auf Busebene mit einem Logikanalysator
Wenn die Komponente nicht mehr sagen kann, was auf dem Draht geschieht, erfassen Sie SDA + SCL mit einem Logic-Analyzer (Saleae, DSLogic Plus, Sigrok-kompatibel) für eine tiefgehende Fehlersuche:
- Abtastrate ≥ 1 MS/s bei 100 kHz I²C; ≥ 4 MS/s bei 400 kHz.
-
Der I²C-Decoder in Sigrok / Saleae zeigt ACK / NACK für jedes Byte sowie die Adressphase.
-
Vergleichen Sie die Aufrufe Ihres Codes (
rbamp_read_voltage()usw.) mit der erwarteten Bytefolge — sie sollten exakt übereinstimmen. Burst-Lesen (mehrere Bytes in einer Transaktion über die automatische Adressinkrementierung) wird unterstützt.
Weicht das Verhalten der Komponente vom Mitschnitt ab, eröffnen Sie ein Issue mit der angehängten Mitschnittdatei (.sal / .dsl / .csv).
Wann Sie den Support kontaktieren sollten
Wenn Sie den einschlägigen Abschnitt oben durchgearbeitet haben und das Problem bleibt, eröffnen Sie ein Issue:
github.com/rb-amp/rbamp-esp-idf/issues
Nehmen Sie in die Meldung auf:
-
Ziel-SoC (ESP32 / S2 / S3 / C2 / C3 / C6 / H2) + ESP-IDF-Version (Ausgabe von
idf.py --version). -
Version der rbamp-Komponente (z. B. 1.1.0).
-
Modul-Firmwareversion —
rbamp_firmware_version(dev)in den Logs. -
Ein minimales IDF-Projekt, das das Problem reproduziert (~30 Zeilen Code in
main/main.c). -
Die
esp_err_t-Werte +rbamp_err_to_str(err)zum Zeitpunkt des Fehlers aus den Logs unter dem Tagrbamp. -
Relevante Kconfig:
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ,CONFIG_RBAMP_NACK_RETRY_ATTEMPTS,CONFIG_RBAMP_LOG_LEVEL_*. -
(Falls verfügbar) eine Logic-Analyzer-Aufzeichnung aus dem Moment des Fehlers.
Links
- 05 · Schnellstart — Ihr erstes funktionierendes Projekt
-
09 · API-Referenz — vollständige API mit Warnungen zu den öffentlichen Methoden mit WARNING und Kconfig-Abschnitt
-
03 · Auswahl des Stromsensors — Tabelle der SCT-013-Modelle, Dual-CT-Topologie für einen großen dynamischen Bereich, Ansätze zur Verbesserung der Empfindlichkeit bei kleinen Strömen
Quelle & Issues: rb-amp/rbamp-esp-idf · diese Seite im Repo: docs/10_troubleshooting.md (v1.7.3)