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

10 · Fehlersuche

Entscheidungsbaum zur Fehlerbehebung: Symptom → Schnellprüfung → Maßnahme

Dieses Kapitel ist nach dem beobachteten Symptom gegliedert, nicht nach der internen Fehlerklassifikation. Wenn Sie hier sind, funktioniert etwas nicht richtig. Suchen Sie Ihr Symptom in der Liste unten, gehen Sie zum passenden Abschnitt und arbeiten Sie das Diagnoseverfahren Schritt für Schritt durch.

Die meisten Probleme am Arbeitsplatz fallen in drei Kategorien:

  1. Busebene — das Modul antwortet nicht über I²C; Lesevorgänge lösen RbAmpIOError aus.

  2. Datenebene — das Modul antwortet, aber die Zahlen sind falsch: Nullen, ungewöhnliche Werte, falsches Vorzeichen.

  3. Anwendungsebene — die Verbindung ist instabil, der Wh-Zähler driftet, das Skript hängt oder bricht bei Timeout ab.

Kurzfassung für Ungeduldige: Im eingeschwungenen Zustand sollten die öffentlichen Methoden Werte liefern bzw. Snapshots erzeugen, ohne eine Ausnahme auszulösen. Wenn Sie häufig RbAmpIOError oder RbAmpStaleError in den Logs sehen, springen Sie direkt zu „Das Modul antwortet nicht über I²C“ unten.

Das Modul antwortet nicht über I²C

Was Sie sehen: dev.begin() (oder das Betreten des Kontextmanagers with RbAmp(bus, 0x50) as dev:) löst RbAmpIOError oder RbAmpVersionError aus, oder RT-Lesevorgänge lösen regelmäßig RbAmpIOError aus.

Schritt 1 — Bus-Scan

Stellen Sie zuerst fest, ob das Modul überhaupt am Bus vorhanden ist.

CPython (Linux-SBC)

Externes Tool:

Shell
i2cdetect -y 1     # bus 1 — the standard one on the RPi 40-pin header

Oder Python:

Python
from smbus2 import SMBus

with SMBus(1) as bus:
    print("Scanning...")
    for addr in range(0x08, 0x78):
        try:
            bus.write_quick(addr)
            print(f"Found 0x{addr:02X}")
        except OSError:
            pass

Erwartete Ausgabe: Found 0x50 (oder eine andere Adresse, falls Sie sie geändert haben).

MicroPython

Python
from machine import I2C, Pin

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
print("Found:", [hex(a) for a in i2c.scan()])

Erwartete Ausgabe: Found: ['0x50'] (oder Ihre Adresse).

Was zu tun ist, wenn nichts gefunden wird

Das Problem liegt in der Verdrahtung oder der Stromversorgung:

  • SDA / SCL sind nicht vertauscht (siehe 04 · Verdrahtung für die GPIO-Standards je Host).

  • Beide Leitungen haben einen Pull-up auf 3.3 V (die Modulplatine hat eingebaute 4.7-kΩ-Widerstände — für ein einzelnes Modul sind keine externen nötig).

  • Der Versorgungspin des Moduls liegt tatsächlich bei 5 V (4.5–5.5 V).

  • Kein anderer Master (Debug-Probe, zweiter Controller) hängt an denselben Leitungen.

  • Prüfen Sie unter MicroPython, dass freq=50_000 gesetzt ist (nicht 100k oder 400k — auf ESP32 mit v1-Firmware frisst das Grund-NACK-Muster das Wiederholungsbudget auf).

  • Prüfen Sie auf CPython, ob der I²C-Kerneltreiber aktiviert ist — auf dem RPi lsmod | grep i2c_bcm.

Was zu tun ist, wenn das Modul an einer unerwarteten Adresse erscheint

Jemand hat es zuvor am Testaufbau neu adressiert. Aktualisieren Sie das zweite Argument von RbAmp:

Python
dev = RbAmp(bus, 0x52)   # address from the bus scan

Schritt 2 — MicroPython + ESP32-Basis-NACK-Muster

Findet der Bus-Scan das Modul, aber dev.read_voltage() löst regelmäßig RbAmpIOError aus — und Sie verwenden MicroPython + ESP32 —, handelt es sich um ein dokumentiertes Basismuster: Der I²C-Stack des ESP32-Ports von MicroPython hat Eigenheiten des ESP-IDF-v5-Treibers übernommen, die bei der Kommunikation mit rbAmp auf der aktuellen Firmware bei 100 kHz häufige NACKs erzeugen.

Die Abhilfe ist bereits in MachineI2CBackend eingebaut (standardmäßig 3 Wiederholungen × 5 ms Pause), aber unter hoher Last kann das Wiederholungsbudget aufgebraucht sein.

Was auf dem ESP32 zu tun ist:

  1. Senken Sie die Busgeschwindigkeit auf 50 kHz:
Python
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
  1. Erhöhen Sie die Anzahl der Wiederholungsversuche bei hoher Last — dafür braucht es die erweiterte API mit explizitem Anlegen des Backends:
Python
from rbamp._io_micropython import MachineI2CBackend
from rbamp import RbAmp

backend = MachineI2CBackend(i2c, retry_attempts=5, retry_gap_ms=5)
dev = RbAmp(backend, 0x50)   # the address goes to RbAmp, not to the backend
  1. Überwachen Sie den Zähler für ausgeschöpfte Wiederholungen — er sollte im Dauerbetrieb null bleiben:
Python
if backend.retry_exhaustion_count > 0:
    print("WARN: retry exhausted:", backend.retry_exhaustion_count)

Schritt 3 — Plattformen ohne ESP32 (RP2040 / STM32 / CPython)

Auf RP2040 / STM32 / Pyboard (über MicroPython) gibt es kein Grund-NACK-Muster — diese Plattformen zeigen mit rbAmp eine NACK-Rate von etwa 0 %. MachineI2CBackend erkennt den Port automatisch und setzt den Wiederholungsstandard auf 1 Versuch.

Auf CPython (über smbus2) gibt es überhaupt keine Wiederholungsschicht — der Linux-Kernel-I²C-Treiber ist vom NACK-Muster nicht betroffen; ein einzelnes OSError von smbus2 wird ohne Wiederholung in RbAmpIOError übersetzt.

Falls auf diesen Plattformen NACKs auftreten, achten Sie auf:

  • Hohe Buskapazität — lange Leitungen + viele Geräte. Senken Sie die Geschwindigkeit oder kürzen Sie das Kabel.

  • Master-Konkurrenz — das Paket unterstützt keinen Multi-Master-Betrieb.

  • Ein schwebendes SCL zwischen Transaktionen — ein fehlender Pull-up.
  • Auf dem RPi: prüfen Sie dtparam=i2c_arm_baudrate in /boot/config.txt — 100000 wird empfohlen.

PermissionError: [Errno 13] auf /dev/i2c-1 (Linux)

Was Sie sehen: SMBus(1) löst PermissionError aus, während sudo python funktioniert. Ihr Benutzer darf das I²C-Gerät nicht öffnen. Abhilfe:

Shell
sudo usermod -aG i2c $USER   # then log out and in again

Stellen Sie außerdem sicher, dass I²C aktiviert ist (sudo raspi-config → Schnittstellenoptionen [Interface Options] → I2C), und dass ls /dev/i2c-* den Bus auflistet; sudo apt install i2c-tools liefert i2cdetect -y 1.

Strommessung zeigt Null bei laufender Last

Was Sie sehen: dev.current[0] (oder dev.read_current(0)) liefert 0.000 (oder einen sehr kleinen Wert), obwohl ein echter Verbraucher eingeschaltet ist (ein Wasserkocher, eine Lampe, ein Bügeleisen). dev.power_factor[0] kann einen merkwürdigen Wert zeigen (nan / 0 / ±1) — das ist eine Folge; die Ursache liegt im Strom.

Diagnoseverfahren

  1. Prüfen Sie, ob Sensorklasse und CT-Modell konfiguriert sind:
Python
from rbamp import RbAmp, RbAmpError, RbAmpSensorClass, RbAmpModeError

try:
    dev.set_sensor_class(RbAmpSensorClass.SCT_013)
except RbAmpError as e:
    print("set_sensor_class failed:", e)

try:
    dev.set_ct_model(3)   # or your model — see the table in 03
except RbAmpModeError:
    print("Class must be set first!")
except ValueError:
    print("Code not in per-class accept-set (SCT_013: {1,2,3,4,5,6,7})")

Ohne diese beiden Aufrufe werden die Kalibrierkoeffizienten nicht geladen, und der Strom wird immer als null angezeigt. Dieser Schritt wird einmalig bei der Erstinstallation ausgeführt — die Auswahl wird im Flash des Moduls gespeichert.

  1. Prüfen Sie, ob das CT-Modell zur Last passt. Eine große CT-Zange (etwa SCT-013-100, 100 A) an einer kleinen Last (eine 50-W-Lampe ≈ 0.2 A) liefert ein Signal am Rand des Grundrauschens, und die Messwerte bleiben bei 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 Spitzen sehen wollen, erwägen Sie das Dual-CT-Muster: ein kleiner Wandler (SCT-013-005) auf einem separaten Kanal für den unteren Bereich und ein großer (SCT-013-030/100) auf einem anderen Kanal für den oberen Bereich; der Master wählt den Wert über eine Schwelle. Das Muster wird in 03 · Auswahl des Stromsensors, Abschnitt „Dual-CT-Topologie“, behandelt.

  1. Prüfen Sie die Ausrichtung der Zange. Der Pfeil am Zangenkörper muss in Stromflussrichtung zur Last zeigen. Ist die Zange „verkehrt herum“, liefert dev.read_current() dem Betrag nach den richtigen Wert, aber dev.read_power() liefert bei einer verbrauchenden Last einen negativen Wert. Bestätigung — dev.read_power_factor() zeigt bei einer ohmschen Last genau −1.0 (statt +1.0). Abhilfe: Entweder die Zange physisch neu montieren (abnehmen, Pfeil richtig herum drehen, wieder aufklipsen) oder das Vorzeichen anwendungsseitig umkehren (p = -p; pf = -pf;, wenn Sie wissen, dass die Last kein PV-Wechselrichter ist).

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 das mit einem Multimeter (einer DC- bzw. AC-Zange) am selben Draht.

  • Ob die Zange intakt ist — am Zangenstecker sollte eine Wechselspannung proportional zum Strom anliegen (einige Millivolt bei Haushaltslasten).

  • Ob Sie den richtigen Draht umschließen — nur einen Leiter, den stromführenden Draht (L), nicht das ganze Kabel (wenn Sie L und N umschließen, lesen Sie ~0).

Messwerte springen oder RbAmpIOError wird ausgelöst

Was Sie sehen: dev.voltage / dev.read_current(...) löst periodisch RbAmpIOError aus. Der Eigenschaftswert wurde nicht erhalten — Sie brauchen auf Anwendungsseite eine Wiederholung oder einen try/except-Schutz.

RbAmpIOError aus dem Paket 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| > 10000 (eindeutig kein physikalischer Wert) kam vom Bus.

Unterscheiden Sie sie anhand der Diagnosezähler (auf MicroPython verfügbar):

Python
from rbamp._io_micropython import MachineI2CBackend

# Build the backend yourself, then pass IT (not the raw I2C object) to RbAmp.
# This is where `backend` comes from; the address belongs to RbAmp.
backend = MachineI2CBackend(i2c, retry_attempts=5)
dev = RbAmp(backend, 0x50)

# After a period of operation:
print("retries succeeded:", backend.retry_count_total)
print("retries exhausted:", backend.retry_exhaustion_count)
print("sanity rejects:",    dev.sanity_reject_count)
Zähler Was es bedeutet
retry_count_total ↑, retry_exhaustion_count = 0, sanity_reject_count = 0 Der Bus ist in Ordnung; das Paket behebt die seltenen NACKs unauffällig. Normal.
retry_count_total ↑, retry_exhaustion_count ↑ NACK-Plateau — erhöhen Sie retry_attempts (siehe Schritt 2 oben).
retry_count_total niedrig, sanity_reject_count ↑ Der Plausibilitätsfilter fängt nach fehlgeschlagenen Wiederholungen Datenmüll ab. Erhöhen Sie retry_attempts=5+.

Unter CPython (SMBusBackend) gibt es keine Wiederholungsschicht — RbAmpIOError wird beim allerersten Fehler ausgelöst. Die Symptome sind selten (der Linux-Kernel ist meist zuverlässig); treten sie aber auf, prüfen Sie Verdrahtung, Pull-ups und Busgeschwindigkeit.

Leistungsfaktor wirkt merkwürdig

Was Sie sehen: dev.power_factor[0] (oder dev.read_power_factor(0)) liefert einen Wert, der nicht zum Lasttyp passt.

Erwartungen je Last:

Last Erwarteter PF
Wasserkocher, Bügeleisen, Glühlampe +0.95 .. +1.0 (ohmsch)
Kühlschrank, Motorkompressor +0.6 .. +0.85 (induktiv)
LED-Lampe, Fernseher (Schaltnetzteil) +0.5 .. +0.95 (nichtlinear)
PV-Wechselrichter speist ein negativer PF

PF = nan oder 0 bei I = 0

PF ist definiert als P / (U × I). Bei null Strom I=0 ist die Rechnung nicht definiert. Der genaue Rückgabewert hängt von der Firmware ab (er kann nan, 0 oder ein Platzhalter sein) — das ist normal, solange der Strom wirklich null ist. Sobald Strom fließt, erscheint ein gültiger PF.

PF genau −1.0 bei einer rein verbrauchenden Last

Die Zange ist „verkehrt herum“ angebracht — der Pfeil zeigt nicht in Stromflussrichtung zur Last. Abhilfe: Entweder die Zange richtig neu montieren oder das Vorzeichen anwendungsseitig behandeln (p = -p; pf = -pf;, wenn Sie wissen, dass die Last kein PV-Wechselrichter sein kann).

PF schwankt bei einer ohmschen Last zwischen +0.3 und +0.7

  • Mögliche Ursache: Die CT-Zange sitzt auf einem Draht einer anderen Phase als derjenigen, an die der U-Eingang des Moduls angeschlossen ist. In einer mehrphasigen Verteilung ist es leicht, aus Versehen die falsche Phase zu umschließen — eine Phasenverschiebung von 120° oder 180° zwischen U und I ergibt genau diese PF-Werte. Die Abhilfe: Installieren Sie das Modul so, dass U-Eingang und CT auf derselben Phase liegen.

  • Alternative: Die Last ist tatsächlich nicht rein ohmsch. Wiederholen Sie den Test mit einer bekannt ohmschen Last (einem Wasserkocher bei voller Leistung).

Periodensnapshots sind immer RbAmpStaleError

Was Sie sehen: dev.read_period_snapshot() löst bei jedem Aufruf RbAmpStaleError aus. Das bedeutet, dass das Modul die Integration der vorherigen Periode bis zum nächsten Lesen nicht abgeschlossen hat.

Bei einem veralteten Lesewert behält das Paket den vorherigen Zeitstempel, sodass der nächste erfolgreiche Snapshot das volle Intervall seit dem letzten guten abdeckt und die Wh-Summe exakt bleibt (keine Doppelzählung, kein Verlust).

Akzeptabel: seltene veraltete Lesewerte (1–2 pro Stunde bei einem 60-s-Takt). Nicht akzeptabel: aufeinanderfolgende veraltete Lesewerte — das bedeutet, dass die Firmware nicht reagiert oder der Master zu oft abfragt.

Verfahren zur Prüfung des Takts

  1. Prüfen Sie den Takt: 60 s zwischen Snapshots sind komfortabel; 30 s sind grenzwertig; < 10 s führt garantiert zu veralteten Messwerten.

  2. Prüfen Sie die Reaktionsfähigkeit des Moduls zwischen den Momentaufnahmen:

Python
if dev.probe():
    print("alive")
  1. Das Flag direkt prüfen:
Python
if dev.is_period_valid():
    # avg_p[] can be read
    ...
  1. Prüfen Sie die Firmware-Version — dev.firmware_version >= 0x04 (v1.3) hat die wenigsten veralteten Lesewerte; 0x02/0x03 (v1.1/v1.2) werden weiterhin unterstützt, aber die Rate veralteter Lesewerte steigt; 0x01 (v1.0) ist am störanfälligsten.

Sonderfall — Aufwachen aus MicroPython-Deep-Sleep

Wenn Sie auf MicroPython ein Deep-Sleep-Muster verwenden, liefert das Standard-dev.read_period_snapshot() nach dem Betreten des Kontextmanagers immer ein veraltetes (oder nahezu nulliges) Ergebnis — __enter__ nimmt einen Snapshot (Befehl LATCH) als Priming, der den Firmware-Akkumulator zurücksetzt. Das kanonische Muster verwendet skip_latch=True + eine bekannte Schlafdauer (das Argument machine.deepsleep(SLEEP_MS)) — siehe 06 · Beispiele, Szenario 9.

Wh-Bilanz weicht von der Referenz ab

Was Sie sehen: dev.energy.wh(0) weicht nach mehreren Stunden / Tagen Betrieb vom Stand des Versorgerzählers oder eines Referenzzählers (Kill-A-Watt oder ähnlich) ab.

Schließen Sie zuerst das Triviale aus

  1. Kalibrierung des Stromsensors: Stellen Sie sicher, dass dev.set_sensor_class() und dev.set_ct_model() mit dem richtigen CT-Modell aufgerufen werden (siehe 03 · Auswahl des Stromsensors). Ohne das wird der Effektivstrom mit dem Standard-Grenzwert berechnet, und der Leistungswert ist systematisch verzerrt.

  2. Verworfene veraltete Snapshots: Liegt dev.energy.wh(0) durchgehend unter der Referenz, handelt es sich möglicherweise um verpasste Intervalle. Ein einzelner veralteter Snapshot verliert keine Energie (der nächste gute deckt das volle Intervall ab), wiederholte Ausfälle oder ein nicht laufendes Skript aber schon. Prüfen Sie den Takt (siehe oben).

  3. Drift der Master-Uhr: time.monotonic() (CPython) und time.ticks_ms() (MicroPython) sind im Normalbetrieb zuverlässig. Geht der Master aber in Deep Sleep, verwenden Sie das Muster mit RTC-Speicher und bekannter Schlafdauer aus Szenario 9.

Sicherheit

⚠ ticks_ms()-Überlauf auf MicroPython. time.ticks_ms() läuft bei 2**30 ms (~12.4 Tage) über — eine naive Subtraktion t1 - t0 über diese 12.4-Tage-Grenze ergibt eine negative oder riesige Zahl. Intern verwendet das Paket time.ticks_diff(t1, t0), das überlaufsicher ist. Wenn Sie master_dt_ms selbst im Anwendercode berechnen (außerhalb des Pakets), verwenden Sie ticks_diff statt einer direkten Subtraktion.

Genauigkeit des Akkumulators

Der Wh-Akkumulator im Handle:

Laufzeit Typ
CPython 64-Bit-float (Python-float)
MicroPython (Double-Precision-Build) 64-Bit-float
MicroPython auf Ports ohne Double-Float 32-Bit-float

Prüfung der Genauigkeit unter MicroPython (sys.float_info gibt es nur unter CPython; unter uPy verwenden wir eine empirische Prüfung):

Python
# On CPython:
import sys
print(sys.float_info.dig)   # 15 → double; 7 → single

# On MicroPython — empirically:
import sys
print(sys.implementation.name)   # 'micropython'
test = 1.0 + 1e-15
print("double" if test != 1.0 else "single")   # 1.0 + 1e-15 != 1.0 only on double

Bei Single-Float-MicroPython-Portierungen auf langlaufenden Dauertest-Installationen setzen Sie dev.energy.reset(0) periodisch zurück und speichern die Langzeitsumme in Ihrem eigenen persistenten Speicher (zum Beispiel über eine MQTT-Retain-Nachricht in HA).

Das Skript hängt / bricht bei Timeout ab

Was Sie sehen: Das Python-Skript startet normal, bleibt dann nach einigen Minuten hängen bzw. wirft einen RuntimeError.

MicroPython auf ESP32: Eine I²C-Operation hängt bei einem grenzwertigen Bus — dreistufige Abhilfe

Was Sie konkret sehen: Ein Skript auf dem ESP32 (MicroPython machine.I2C) fragt rbAmp mehrere Minuten lang fehlerfrei ab und hängt dann mitten in einem Aufruf von dev.read_period_snapshot() / fleet.poll_all() „tot“. Der WDT (falls aktiviert) fängt den Hänger auf; andernfalls reagiert das Skript einfach nicht mehr. Hat man eine REPL, hängt sie ebenfalls.

Was geschieht: Das MicroPython-machine.I2C auf dem ESP32 umhüllt denselben i2c_master-Treiber des ESP-IDF, den auch native ESP-IDF-Projekte verwenden. Bei einem grenzwertigen Bus (schwache Pull-ups, lange Leiterbahnen, EMV, ZC-Rauschen) können SDA/SCL kurzzeitig in einem undefinierten Zustand „hängen bleiben“. Vor der nächsten Transaktion dreht der i2c_master des IDF in einer Schleife i2c_ll_is_bus_busy und wartet auf die Freigabe des Busses — dieses Warten ist nicht durch das I²C-Timeout der Bibliothek begrenzt.

Dies ist kein „nur im Debugger auftretendes Artefakt“. Am Testaufbau validiert (bibliotheksübergreifend, gleiches Hardware-Setup und gleiche 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 (12-Minuten-Dauertest, 0 Neustarts)

Der Zusammenhang ist eindeutig — eine Korrektur der Busintegrität beseitigt das Hängen vollständig. Die Bibliothekslogik ist nicht die Ursache.

Dreischichtige Minderung (wenden Sie alle drei Schichten an):

  1. Externer Pull-up (~4.7 kΩ) an SDA und SCL gegen 3.3 V an einer Stelle des Busses. Die internen Pull-ups des ESP32 (~45 kΩ) sind für einen Mehrmodul-Bus realer Länge zu schwach, während die in den Modulen eingebauten 4.7-kΩ-Pull-ups parallel zu stark werden. Trennen Sie auf einem solchen Bus die eingebauten an allen Modulen bis auf eines. Siehe 04 · Verdrahtung, Abschnitt „Mehrmodul-Bus — die primäre Topologie“.

  2. Betreiben Sie keinen Produktions-Build mit angeschlossenem Debugger-NRST. In einer Debug-Sitzung kann die Reset-Leitung SDA/SCL beim Trennen bzw. Verbinden in einem undefinierten Zustand halten und beim nächsten Zugriff einen Busstillstand auslösen.

  3. Eine App-seitige Task-WDT auf der Abfrage-Task — Verteidigung in der Tiefe. Saubere Bus-Pull-ups sind die Lösung im Feld; die Task-WDT ist eine Wiederherstellungsstrategie.

Python
# MicroPython-on-ESP32
from machine import WDT
import time

wdt = WDT(timeout=8000)   # 8 s

while True:
    snap = dev.read_period_snapshot()
    # ... processing ...
    wdt.feed()             # "I'm alive" — every cycle
    time.sleep_ms(200)

Was NICHT zu tun ist: Versuchen Sie nicht, das Problem mit einem größeren Parameter I2C(..., timeout=ms) zu umgehen — er begrenzt das Vorab-Warten auf den belegten Bus nicht; das ist ein anderer Codepfad im IDF-Treiber. Zu beheben ist die Busintegrität (Ebene 1) und die Überwachung (Ebene 3).

CPython auf Linux-SBC: Der I²C-Kernel ist von diesem Problem nicht betroffen

Die Linux-Kerneltreiber (i2c-bcm2835 auf dem Raspberry Pi, i2c-i801 auf x86 usw.) führen ihre Prüfung auf belegten Bus mit einem Timeout durch — auf einem blockierten Bus liefern sie IOError(Errno 110: ETIMEDOUT) oder EREMOTEIO, statt zu hängen. Die Bibliothek verpackt das in RbAmpIOError. Daher ist die dreistufige Abhilfe unter CPython nicht nötig — Linux erledigt das selbst. Ein externer Pull-up von etwa 4.7 kΩ ist für die Signalintegrität auf einem langen Bus trotzdem wünschenswert.

latch_ms passt nicht zur Wanduhr-Periode

latch_ms ist ein Diagnose-Timer des Moduls; nicht für die Energie verwenden — nutzen Sie die Uhr des Masters.

Die Bibliothek integriert die Energie über die Wanduhr des Masters: CPython — time.monotonic(); MicroPython — time.ticks_ms() + time.ticks_diff(). Die Integration auf Masterseite fügt über die Genauigkeit der Wirkleistung des Moduls hinaus keinen eigenen Fehler hinzu.

Wenn Ihr Code für Teilperioden-Berechnungen auf snap.latch_ms setzt, wechseln Sie auf Ihre eigene time.monotonic() / time.ticks_diff().

RbAmpStaleError bei jedem Lesevorgang — die Bibliothek hält den Anker automatisch

Was Sie sehen: dev.read_period_snapshot() löst periodisch RbAmpStaleError aus.

Kanonische dt-Behandlung: Bei einem veralteten Lesewert setzt die Python-Bibliothek nicht den internen Anker _last_latch_ms auf null. Der nächste gültige Lesewert erhält ein master_dt_ms, das dem vollen Intervall seit dem vorherigen erfolgreichen Snapshot entspricht — es deckt also sowohl den „verlorenen“ veralteten Zeitraum als auch den aktuellen ab. Die Firmware bewahrt den avg_p-Akkumulator über einen leeren Snapshot hinweg (firmwareseitige Persistenz): Beim nächsten gültigen Snapshot ist er bereits ein Mittelwert über das gesamte Intervall. Die Wh-Integration bleibt exakt — keine Doppel-, keine Unterzählung.

Muster für den Kaltstart (prime-until-valid, ein Wiederholungsbudget von etwa 25 ist in Ordnung):

Python
from rbamp import RbAmpStaleError

while True:
    try:
        snap = dev.read_period_snapshot()
        break
    except RbAmpStaleError:
        time.sleep(3.0)

Nach dem Priming ignorieren Sie RbAmpStaleError, wenn es selten vorkommt; tritt es häufig auf, diagnostizieren Sie den Takt (Abschnitt „Periodische Snapshots liefern immer RbAmpStaleError“ oben).

CPython: signal.SIGTERM / KeyboardInterrupt werden nicht behandelt

Ursache: ein langes time.sleep(60) blockiert den Signal-Handler. Bei einem Produktions-Deployment (systemd) wartet systemctl stop rbamp bis zu einem Timeout (Standard 90 s) auf die SIGTERM-Antwort und beendet den Prozess dann mit SIGKILL — Wh kann verloren gehen.

Abhilfe: eine signalbewusste Schleife:

Python
import signal, time
shutdown = False

def on_sig(sig, frame):
    global shutdown
    shutdown = True

signal.signal(signal.SIGTERM, on_sig)
signal.signal(signal.SIGINT,  on_sig)

while not shutdown:
    snap = dev.read_period_snapshot()
    # ... publish ...
    for _ in range(60):           # wake on signal every second
        if shutdown: break
        time.sleep(1)

Oder verwenden Sie asyncio mit einem signal_handler — siehe den Abschnitt unten.

MicroPython (ESP32): Watchdog-Timeout beim WLAN-Verbindungsaufbau

Ursache: eine unbegrenzte WiFi-Verbindungsschleife löst nach ~5 s den Task-WDT aus (der Standard).

Abhilfe: ein begrenztes Warten mit Neustart als Rückfall:

Python
import network, time, machine

wlan = network.WLAN(network.STA_IF)
wlan.active(True)
wlan.connect("ssid", "pass")

t0 = time.ticks_ms()
while not wlan.isconnected():
    time.sleep_ms(100)
    if time.ticks_diff(time.ticks_ms(), t0) > 30_000:
        machine.reset()

Der MQTT-Broker trennt die Verbindung

Unter CPython (paho-mqtt): Der Standard-Keepalive beträgt 60 s, aber mqtt.connect() blockiert, und mqtt.loop() muss in einer Ereignisschleife aufgerufen werden. Verwenden Sie mqtt.loop_start() (ein Hintergrund-Thread) oder die asyncio-Variante aiomqtt.

Auf MicroPython (umqtt.simple): synchron ohne Keepalive — Sie müssen mqtt.ping() etwa alle 30 s manuell aufrufen. Die Alternative ist das asynchrone Paket mqtt_as mit integriertem Keepalive.

TLS-Handshake-Fehler (CPython-Cloud + RPi mit wenig RAM)

Selten ein Problem auf einem Pi mit 1+ GB RAM, aber auf einem Pi Zero / Zero W (512 MB) kann ein TLS-Handshake mit großem Zertifikatsspeicher vom OOM-Killer beendet werden.

Fix:

  • Verwenden Sie eine bestimmte CA statt der System-ca-certificates — das spart Speicher.

  • Reduzieren Sie die MQTT-Puffer.

  • Für einen Produktions-Cloudbetrieb wechseln Sie auf einen Pi 3/4/5.

set_sensor_class() / set_ct_model() löst RbAmpModeError aus

Was Sie sehen: Einer der Konfigurationsaufrufe löst RbAmpModeError mit folgender Meldung aus:

Text
REG_SENSOR_CLASS is UNSET;
call dev.set_sensor_class(RbAmpSensorClass.SCT_013) first

Ursache: set_ct_model[_ch] erfordert, dass vorher set_sensor_class() aufgerufen wurde. Das ist eine beabsichtigte Sperre.

Vorgehen:

Python
from rbamp import RbAmpSensorClass

# Class first — MANDATORY
dev.set_sensor_class(RbAmpSensorClass.SCT_013)

# Then the model
dev.set_ct_model(3)   # or per-channel dev.set_ct_model_ch(ch, code)

Mehr dazu — 03 · Auswahl des Stromsensors und 09 · API-Referenz, Abschnitt „Sensorkonfiguration“.

Seit 1.6.0 sind diese Setter mit einem Schutz „erst lesen, dann schreiben“ versehen:

  • Die Klasse oder das Modell, das das Modul bereits hält, erneut zu setzen ist ein stiller No-Op (erneutes Anwenden würde die Kanalkalibrierung löschen).

  • Bei einem werkseitig gepaarten Modul (Klasse WIRED_CT / BUILTIN_CT) wird eine andere Klasse oder ein anderes Modell abgelehnt mit RbAmpModeError. Im Servicekontext verwenden Sie dev.set_ct_model_ch_force(ch, code).

RbAmpModeError entsteht auch bei dev.factory_reset() und dev.save_gains() (Werksoperationen erfordern den Werksmodus). Eine Adressänderung auf v1.3 ist produktionstauglich und löst RbAmpModeError nicht aus.

set_sensor_class() / set_ct_model*() löst RbAmpParamError oder ValueError aus

Was Sie sehen: der Aufruf löst RbAmpParamError aus (auf CPython erbt er zusätzlich ValueError über Mehrfachbasis).

Mögliche Ursachen:

  1. Ungültiger Modellcode — für die Klasse SCT_013 ist die akzeptierte Menge {1, 2, 3, 4, 5, 6, 7} (Codes 5 und 7 sind SCT-013-100 und SCT-013-060). Für andere Klassen siehe die Tabelle der akzeptierten Mengen je Klasse in 03 · Auswahl des SCT-013-Modells. Werte außerhalb der akzeptierten Menge lösen RbAmpParamError(ValueError) aus.

  2. Ungültiger Kanalindex in der Form pro Kanal dev.set_ct_model_ch(channel, code) — er muss < dev.channels sein.

  3. Ein Sensorklassenwert außerhalb von 0..3. (WIRED_CT / BUILTIN_CT sind gültige Werte, aber ein werkseitig gepaartes Modul lässt keine Neukonfiguration zu — das löst RbAmpModeError aus, siehe unten.)

Fehlerbehandlung: letzter Schreibzugriff auf REG_ERROR + EVENT_FLAGS.bit3 dauerhaft (v1.3)

v1.3: REG_ERROR (0x02) ist das Ergebnis des letzten Schreibvorgangs, nicht klebrig. Bei jedem Registerschreibvorgang setzt die Firmware reg_error = ERR_OK; ein nachfolgender, unabhängiger Schreibvorgang löscht den vorherigen Fehler.

Das dauerhafte Fehlersignal = EVENT_FLAGS (0x2A) bit3 — klebrig (W1C), wird sofort bei jedem abgewiesenen Schreibvorgang/Befehl gesetzt.

Muster 1 — einmalige Erfassung nach einer Operation (das Ergebnis genau dieser Operation):

Python
dev.save_user_config()
dev_err = dev.read_reg(0x02)   # IMMEDIATELY, before the next write

Muster 2 — dauerhafte Überwachung (kanonisch für den Dauerbetrieb):

Python
event_flags = dev.read_reg(0x2A)
if event_flags & (1 << 3):
    last_err = dev.read_reg(0x02)
    # handle it
    dev.write_reg(0x2A, (1 << 3))   # W1C clear bit3
    # or dev.clear_error()
Sicherheit

⚠ UMKEHRUNG der frühen „klebrigen“ Dokumentation (v1.3). REG_ERROR ist das Ergebnis des letzten Schreibvorgangs, nicht klebrig. Die Dauerhaftigkeit liefert EVENT bit3.

⚠ bit3 ist ein asynchroner Kanal, nicht für die synchrone Prüfung von Schreibvorgängen: Bei einem abgelehnten Schreibvorgang wird bit3 verzögert gesetzt, bezogen auf den Zeitpunkt der Rückkehr der I²C-Transaktion (einige hundert Millisekunden). Fragen Sie bit3 nicht unmittelbar nach einem Schreibvorgang ab, um dessen Ergebnis zu prüfen — für das Ergebnis Ihres eigenen Schreibvorgangs verwenden Sie Muster 1 (einmalige Erfassung über read_last_error(), sofort) oder die RbAmpParamError, die der Setter auslöst. bit3 dient der langlaufenden Überwachung asynchroner Zustände (Laufzeit, Befehlspfad), nicht der Prüfung einer gerade ausgeführten Operation.

Vorbehalt: DEV_ERR_CLONE (0xF9) wird nicht durch CMD_CLEAR_ERROR gelöscht — es ist ein Anti-Klon-Sentinel.

Ein frisch geflashtes Modul zeigt beim ersten Booten 0xFB (NORMAL)

Was Sie sehen: Ein frisch geflashtes Modul zeigt beim ersten Start 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) die Adresse und führen Sie dann dev.save_user_config() aus. Nach erfolgreichem SAVE → REG_ERROR = 0x00, bit3 gelöscht.

Lesezugriffe scheitern beim Schalten von Relaislasten (EMV-Transienten)

Was Sie sehen: dev.voltage / dev.current() lösen periodisch RbAmpIOError / OSError aus — aber nur während aktiven Schaltens eines Relais oder einer induktiven Last am selben Aufbau. Lesevorgänge im stationären Zustand sind zuverlässig.

Ursache (C.12 hardwarebestätigt): Während des Schaltens eines Relais (5-A-Last) scheitern etwa 67 % der I²C-Transaktionen durch EMV. Der Bus erholt sich selbst, es entsteht kein Hänger, und kein Modul geht verloren.

Abhilfe — Wiederholung auf Anwendungsebene:

Python
def robust_read_voltage(dev, attempts=5, gap_s=0.020):
    for _ in range(attempts):
        try:
            return dev.voltage
        except (RbAmpIOError, OSError):
            time.sleep(gap_s)
    raise RbAmpIOError("read failed after retries")
Sicherheit

⚠ Die Wiederholung im Backend allein reicht nicht: Dauert eine EMV-Störung länger als das Wiederholungsfenster des Backends, benötigen Sie eine explizite Wiederholung auf Anwendungsebene mit einer Pause.

commit_address_change() löst nach einem Busreset RbAmpIOError aus

Was Sie sehen: prepare_address_change() war erfolgreich, aber nach dem Commit + Reset antwortet das Modul nicht an der neuen Adresse.

Hinweis

✅ v1.3: REG_I2C_ADDRESS (0x30) liest beim Booten die aktive Adresse. Nach dem Reboot nach dem Commit zeigt ein Lesen von 0x30 unter der neuen Adresse dieselbe Adresse — das bestätigt, dass das Commit übernommen wurde. Antwortet das Modul unter der neuen Adresse nicht, führen Sie einen Bus-Scan über _io_smbus aus (er zeigt, unter welcher Adresse das Modul tatsächlich ist).

Mehr zum Zwei-Phasen-Commit — siehe 09 · API-Referenz und 04 · Verdrahtung.

commit_address_change() löst RbAmpTimeoutError aus

Wenn prepare erfolgreich war, commit aber RbAmpTimeoutError auslöst, ist das „Scharfschalt“-Fenster abgelaufen (5 Sekunden nach prepare). dev.probe() hilft hier nicht (das Modul antwortet; das Problem liegt im Zustandsautomaten des Moduls). Die Abhilfe: dev.prepare_address_change(new_addr) erneut aufrufen und dann sofort, in derselben Funktion bzw. Iteration und ohne Netzwerkaufrufe dazwischen, dev.commit_address_change() aufrufen. Jede blockierende E/A zwischen prepare und commit (WiFi, MQTT, HTTP) ist die Hauptursache für das Ablaufen des Fensters.

wait_ready() löst RbAmpTimeoutError aus

Das Bereitschaftsbit des Moduls wurde nicht innerhalb von timeout_ms gesetzt. Mögliche Ursachen:

  • Das Modul hat seinen Kaltstart (~250 ms) noch nicht abgeschlossen — erhöhen Sie timeout_ms oder wiederholen Sie den Aufruf.

  • Das Modul antwortet nicht über I²C — siehe den Abschnitt „Das Modul antwortet nicht über I²C“ oben.

  • Die Versorgungsspannung ist unter 4.5 V gefallen — prüfen Sie VCC mit einem Multimeter.

Mehr zu den öffentlichen, aber mit Warnung versehenen Methoden — siehe 09 · API-Referenz, Abschnitt „Sensorkonfiguration“ (der Unterabschnitt zur Adressänderung steht dort zusammen mit save_gains und factory_reset).

RbAmpNotSupportedError (STD-Aufrufe)

Was Sie sehen: ein Aufruf wie dev.read_std_energy(), dev.read_voltage_angle(), dev.read_phase_sequence(), dev.get_start_current() oder dev.set_time() löst RbAmpNotSupportedError aus.

Ursachen und Abhilfe:

  1. Das Modul ist ein BASIC-Modul. Nur für STD vorgesehene Aufrufe sind auf BASIC nicht verfügbar. Prüfen Sie dev.is_std; verwenden Sie auf BASIC die gemeinsamen Leser (voltage, current, power, power_factor, frequency) und stattdessen die Periodenschnittstelle.

  2. Das Modul-Image ist für dieses Merkmal zu alt. Mikro-Einheiten-Energiezähler, Spannungswinkel und Anlaufstrom brauchen ein hinreichend aktuelles Modul-Image; auf einem älteren meldet der Aufruf „nicht verfügbar“. Die gängigen Leser funktionieren weiter.

  3. dev.is_std ist bei einem STD-Modul False. Die Bibliothek erkennt die Reihe mit einer 16-Bit-Busübertragung; ein Bus-Objekt oder Adapter, der das nicht kann, wird als BASIC behandelt. Verwenden Sie smbus2 unter CPython (validiert), und siehe 04 · Hardware.

Dieselbe I²C-Verdrahtung gilt für beide Modulreihen. Beachten Sie, dass Energie auf dem Gerät, Winkel und Anlaufstrom auf CPython validiert sind; der 16-Bit-Pfad für MicroPython ist noch nicht an Hardware validiert.

Übersichtstabelle der Ausnahmen

RbAmpError (eine Unterklasse von OSError) ist die Basisklasse. Ein bestehender Handler except OSError: auf Anwendungsseite fängt rbAmp-Fehler weiterhin ohne Änderungen ab — die übliche Python-Konvention für Hardware-E/A-Treiber.

Ausnahme Wann Wo nachzuschlagen ist
RbAmpIOError NACK nach Wiederholung; Ablehnung durch Plausibilitätsprüfung; Fehler auf Busebene der Abschnitt „Das Modul antwortet nicht über I²C“
RbAmpTimeoutError wait_ready() ist abgelaufen; das Zeitfenster von commit_address_change (5 s) ist abgelaufen der Abschnitt „commit_address_change gibt RbAmpTimeoutError zurück“ unten
RbAmpNotReadyError (reserviert; wird von der Bibliothek nicht ausgelöst, aus Gründen der Vorwärtskompatibilität exportiert) wenn Sie diesen Typ abfangen — reproduzieren Sie ihn in einem Issue
RbAmpStaleError Periodensnapshot veraltet der Abschnitt „Periodensnapshots sind immer RbAmpStaleError“
RbAmpParamError (auf CPython zusätzlich ValueError) Ungültiges Argument: dev=None, ch außerhalb des Bereichs, code nicht in der Akzeptanzmenge der Klasse (für SCT_013 — {1, 2, 3, 4, 5, 6, 7}), eine reservierte cls. Außerdem eine Verletzung der Voraussetzung: set_ct_model*() ohne vorheriges set_sensor_class() prüfen Sie die Aufrufargumente und ob set_sensor_class() aufgerufen wurde
RbAmpModeError Betrieb nur werkseitig (Fabrikmodus nicht gesetzt; eine Adressänderung auf v1.3 ist für die Produktion zulässig); Sensorklasse nicht gesetzt; ein werkseitig gepaartes Modul verweigert einen Wechsel von Klasse/Modell den Modusflag prüfen; zuerst set_sensor_class(); für den Servicebetrieb set_ct_model_ch_force()
RbAmpNotSupportedError Nur für STD vorgesehener Aufruf auf einem BASIC-Modul oder ein STD-Merkmal, das das Modulabbild nicht bereitstellt der Abschnitt „RbAmpNotSupportedError“ weiter unten
RbAmpVersionError REG_VERSION = 0/0xFF bei begin() (das Modul antwortet nicht oder die Firmware ist beschädigt). Kanalweises set_ct_model_ch kann auf v1.0/v1.1 mit NACK beantwortet werden (den Opcode gibt es nicht) und löst RbAmpIOError aus, nicht RbAmpVersionError — die Versionsprüfung ist clientseitig NICHT implementiert; prüfen Sie vor dem Aufruf dev.firmware_version ≥ 0x03. dev.firmware_version prüfen

Alle Ausnahmen haben eine aussagekräftige __str__-Meldung — das Paket baut Fehlermeldungen sorgfältig mit Kontext auf.

Übersichtstabelle der Diagnosezähler

Bei einem gesunden Dauertest (dem 1-Stunden-Langzeit-Harness) bleiben alle null:

Zähler Dauerzustand Reset Verfügbarkeit
dev.sanity_reject_count 0 dev.reset_counters() beide Laufzeiten
MachineI2CBackend.retry_exhaustion_count 0 backend.reset_counters() nur MicroPython
MachineI2CBackend.retry_count_total niedrig (~5-20 pro Stunde ist normal) backend.reset_counters() nur MicroPython
veralteter Anteil in Periodensnapshots < 1 % (kumulativ — kein Reset) beide Laufzeiten

Wenn einer dieser Werte im eingeschwungenen Zustand ungleich null ist, gehen Sie zum entsprechenden Abschnitt oben zurück.

Fehlersuche auf Busebene mit einem Logikanalysator

Für tiefgehende Fehlersuche, wenn das Paket nicht mehr angeben kann, was auf dem Draht geschieht, erfassen Sie SDA und SCL mit einem Logikanalysator (Saleae, DSLogic Plus, beliebiges Sigrok-kompatibles Gerät):

  • 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 Skripts (dev.voltage usw.) mit der erwarteten Bytefolge — sie sollten genau übereinstimmen. Lesevorgänge sind als Burst zulässig (Auto-Increment). Schreibvorgänge sind NICHT auto-increment (Byte für Byte bei mehrbytigen Registern).

Weicht das Verhalten des Pakets von der Aufzeichnung ab, eröffnen Sie ein Issue und hängen die Aufzeichnungsdatei an (.sal / .dsl / .csv).

Wann Sie den Support kontaktieren sollten

Wenn Sie den passenden Abschnitt oben durchgearbeitet haben und das Problem weiterhin besteht, eröffnen Sie ein Issue:

github.com/rb-amp/rbamp-python/issues

Fügen Sie im Issue Folgendes bei:

  • Laufzeit + Version: python --version / mpremote eval 'import sys; print(sys.version, sys.implementation)'.

  • Host-Plattform: „RPi 4B Bookworm“, „ESP32-S3 N16R8 MicroPython 1.22“ usw.

  • Paketversion: rbamp --version (CPython) oder python -c "import rbamp; print(rbamp.__version__)".

  • Firmware-Version des Moduls — dev.firmware_version aus den Logs.

  • Ein minimales Skript (~30 Zeilen), das das Problem reproduziert.
  • Der Ausnahme-Traceback mit vollem Kontext.
  • Die Zähler im Augenblick des Fehlers: dev.sanity_reject_count, backend.retry_exhaustion_count (nur uPy).

  • Die ausführlichen Logs der Bibliothek — am einfachsten sammeln Sie sie mit dev.set_logger(print) vor dem fehlschlagenden Vorgang. Das Paket gibt seine internen Schritte aus (die Wiederholungsschleife, Timeouts beim Einschwingen, der Snapshot-Primer usw.) — hängen Sie die Standardausgabe an das Issue an.

  • (Falls verfügbar) die Aufzeichnungsdatei des Logikanalysators.

CLI — rbamp scan / rbamp read / rbamp address

Die CLI rbamp ist ein dünner Wrapper über RbAmp.* für Bench-Arbeiten (siehe 09 · API-Referenz, Abschnitt „CLI“). Da sie dieselbe Klasse RbAmp verwendet, gelten ALLE oben genannten Symptome. CLI-spezifische Fehler:

  • rbamp scan findet nichts — dasselbe wie in Schritt 1 des Abschnitts „Das Modul antwortet nicht über I²C“ oben. Prüfen Sie direkt mit i2cdetect -y 1. Findet es das Modul, liegt ein Problem in unserer Backend-Autodetection vor; eröffnen Sie ein Issue mit der Ausgabe von rbamp --verbose scan.

  • rbamp schlägt mit PermissionError: /dev/i2c-1 fehl — der Benutzer ist nicht in der Gruppe i2c. Siehe README § Installation für sudo usermod -aG i2c $USER + erneutes Anmelden.

  • rbamp: command not found nach pip install — der Konsoleneintrag [project.scripts] ist nicht aktiv. Prüfen Sie, ob pip show rbamp den Installationsort anzeigt; stellen Sie sicher, dass $HOME/.local/bin in $PATH liegt (für pip install --user).

  • 05 · Schnellstart — Ihr erstes funktionierendes Skript
  • 09 · API-Referenz — die vollständige API und Warnungen zu den öffentlichen Methoden mit WARNUNG

  • 03 · Auswahl des Stromsensors — die Tabelle der SCT-013-Modelle, die Doppel-CT-Topologie für einen großen Dynamikbereich, Ansätze zur Steigerung der Empfindlichkeit bei kleinen Strömen


Quelle & Probleme: rb-amp/rbamp-python · diese Seite im Repository: docs/10_troubleshooting.md (v1.6.1)