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

09 · API-Referenz

Registerkarte des Moduls: der Seite-0-Adressraum von 0x00 bis 0xFF

Atomarer Periodensnapshot: ein Schreibvorgang schließt die aktuelle Periode ab und öffnet die nächste

Die vollständige öffentliche API des Pakets rbamp. Quelle — __init__.py (Re-Exporte), _rbamp_core.py (die Hauptklasse RbAmp), _snapshot.py (POD-Strukturen + Ausnahmehierarchie), _energy.py (Wh-Akkumulator), _registers.py (automatisch erzeugte Konstanten).

Dieses Kapitel ist ein Nachschlagewerk: Signaturen, Rückgabewerte, Nebenwirkungen, Randfälle. Für Arbeitsbeispiele gehen Sie zu 06 · Beispiele; für einen schnellen Einstieg siehe 05 · Schnellstart.

Import-Anweisungen

Python
from rbamp import (
    RbAmp,                     # main class
    RbAmpEnergy,               # Wh accumulator (accessed via dev.energy)
    RbAmpSnapshot,             # RT-block dataclass-style
    RbAmpPeriodSnapshot,       # period snapshot dataclass-style
    RbAmpSensorClass,          # sensor-class enum
    TOPOLOGY_SINGLE, TOPOLOGY_SPLIT_PHASE, TOPOLOGY_THREE_PHASE,
    TOPOLOGY_FIVE_CH, TOPOLOGY_SEVEN_CH,
    topology_name,             # helper: int → topology name
    # STD module line (1.6.0)
    RbAmpStdEnergy, RbAmpStdVoltage, RbAmpStdChannel,
    RbAmpStdConfig, RbAmpStdHealth,   # value objects
    std_energy_delta,          # energy between two read_std_energy() snapshots
    phase_seq_name,            # helper: phase-sequence code → name
    PHASE_SEQ_NA, PHASE_SEQ_FORWARD, PHASE_SEQ_REVERSE, PHASE_SEQ_ABNORMAL,
    # Exception hierarchy
    RbAmpError,                # base class of all errors
    RbAmpIOError,
    RbAmpTimeoutError,
    RbAmpNotReadyError,
    RbAmpStaleError,
    RbAmpParamError,
    RbAmpModeError,
    RbAmpVersionError,
    RbAmpNotSupportedError,    # call not available on this module / firmware
    # Metadata
    __version__,               # "1.6.0"
    __protocol_version__,      # 0x04 (RBAMP_PROTOCOL_VERSION)
    REGISTERS, COMMANDS,       # raw protocol constants (advanced use)
)

Minimaler Import für eine typische Anwendung:

Python
from rbamp import RbAmp, RbAmpSensorClass, RbAmpError

Allgemeine Muster

Die API folgt den üblichen Python-Mustern:

  • Eine Klasse für jede Modulreihe: Dieselbe Klasse RbAmp bedient BASIC- und STANDARD-Module (STD). Die Reihe wird in begin() automatisch erkannt (siehe STD-Modulreihe); Sie wählen sie nie selbst.

  • Klassenbasiert: die Hauptklasse RbAmp verwaltet alles — Echtzeitwerte, Periode, Konfiguration, Diagnose. Das Handle hält intern das Backend und den Energieakkumulator.

  • Kontextmanager: with RbAmp(bus, addr) as dev: — das empfohlene Idiom. __enter__ ruft automatisch dev.begin() auf.

  • Eigenschaften für RT-Messwerte: dev.voltage, dev.frequency — eine Eigenschaft = eine I²C-Transaktion. Kanalindizierte laufen über _ChannelProxy: dev.current[ch], dev.power[ch], dev.power_factor[ch].

  • Methoden für kanalindizierte Lesevorgänge: dev.read_current(ch), dev.read_power(ch). Vollständig äquivalent zur Eigenschaftsform — verwenden Sie, was bequemer ist.

  • Ausnahmen für Fehler: jeder Fehler ist eine Unterklasse von RbAmpError. Das übliche Python-Muster try / except (nicht last_error() + ein Rückgabecode).

  • Asynchroner Generator für periodisches Streaming: async for snap in dev.stream_period(interval_s=...).

Typen

RbAmp

Python
class RbAmp:
    def __init__(self, bus, addr: int = 0x50): ...

Die Hauptklasse. Eine Instanz pro Slave-Gerät. Der Bus ist jedes Objekt mit einer der „bekannten“ API-Signaturen: smbus2.SMBus, machine.I2C oder ein eigenes Backend (siehe 04 · Hardware).

Das Backend wird beim ersten Buszugriff automatisch gewählt:

Methode des Bus-Objekts Backend
bus.readfrom_mem, bus.writeto_mem MachineI2CBackend (MicroPython)
bus.read_byte_data, bus.write_byte_data SMBusBackend (CPython + smbus2)
bus.read_byte, bus.register_acks, bus.now_ms bereits umhüllt (Testmocks, FTDI-Adapter)

Passt keine Signatur, wird RbAmpParamError mit einer Beschreibung ausgelöst.

Ausnahmehierarchie

Jeder Fehler aus dem Paket ist eine Unterklasse von RbAmpError, die selbst von OSError erbt (nicht von bloßem Exception). Das heißt: bestehender Code mit except OSError:-Handlern fängt rbAmp-Fehler weiterhin ab, ohne Umschreiben — die übliche Python-Konvention für Hardware-I/O-Treiber.

Ausnahmehierarchie des Pakets rbamp: jeder Fehler leitet sich von RbAmpError ab, das sich von OSError ableitet.

Hinweis

: RbAmpParamError erbt unter CPython von RbAmpError und ValueError (Mehrfachbasis). Unter MicroPython, wo Mehrfachvererbung nicht von allen Ports unterstützt wird, fällt die Klasse auf eine Einfachbasis zurück. Aus Anwendersicht funktioniert try / except RbAmpParamError gleich. Aber try / except ValueError fängt nur unter CPython — unter MicroPython wird dieser Handler verfehlt. Code, der sich auf plattformübergreifendes Verhalten stützt, muss RbAmpParamError explizit abfangen.

Standardverwendung:

Python
try:
    snap = dev.read_period_snapshot()
except RbAmpStaleError:
    # period not ready yet — the master timestamp was committed by the package
    continue
except RbAmpIOError as e:
    log.warning("bus failure: %s", e)
except RbAmpError as e:
    log.error("unexpected: %s", e)

RbAmpSensorClass

Python
class RbAmpSensorClass(IntEnum):
    UNSET       = 0   # factory value after reset
    SCT_013     = 1   # SCT-013 series (shipping default)
    WIRED_CT    = 2   # factory-fitted wired CT (module ships paired)
    BUILTIN_CT  = 3   # factory-fitted built-in CT (module ships paired)
Hinweis

: Unter CPython wird IntEnum aus dem Standardmodul enum verwendet. Auf MicroPython-Ports ohne Modul enum wird eine einfache Klassen-Ersatzlösung mit denselben Member-Werten verwendet. Aus Anwendersicht sind beide Formen identisch: dev.set_sensor_class(RbAmpSensorClass.SCT_013) oder dev.set_sensor_class(1) — beide funktionieren.

SCT_013 ist die Klasse, die Sie auf einem Modul mit nachträglich angebrachten SCT-013-Zangen wählen. WIRED_CT und BUILTIN_CT beschreiben Module, die werkseitig mit ihrem Sensor gepaart ausgeliefert werden: set_sensor_class() und set_ct_model*() verweigern die Änderung solcher Module (RbAmpModeError, siehe Schutz „erst lesen, dann schreiben“). Werte außerhalb von 0..3 lösen RbAmpParamError aus.

RbAmpSnapshot

Wird von dev.read_all() zurückgegeben. Eine einfache Python-Klasse (kein @dataclass, aus Kompatibilität mit MicroPython). Alle Felder in SI-Einheiten.

Python
class RbAmpSnapshot:
    voltage:        float       # V — RMS voltage
    voltage_peak:   float       # V — peak voltage
    current:        list        # [ch0, ch1, ...] — RMS current per channel, A
    current_peak:   list        # [ch0, ch1, ...] — peak current, A
    power:          list        # [ch0, ch1, ...] — active power (signed), W
    power_factor:   list        # [ch0, ch1, ...] — dimensionless, −1..+1
    frequency:      float       # Hz
    topology:       int         # TOPOLOGY_* constant
    channels:       int         # number of valid channels (1..3, or 5 / 7 on UI5 / UI7)
    has_voltage_hw: bool        # True if a voltage sensor is present

Ungenutzte Kanäle (über channels hinaus) werden mit Nullen aufgefüllt.

RbAmpPeriodSnapshot

Wird von dev.read_period_snapshot() zurückgegeben. Das Grundelement der Energiebilanzierung.

Python
class RbAmpPeriodSnapshot:
    avg_p:        list   # [ch0, ch1, ...] — average P over the period, W (all channels)
    max_p:        float  # peak instantaneous power on channel 0
    latch_ms:     int    # period duration (device's view)
    master_dt_ms: int    # master wall-clock dt since the last snapshot
    valid:        bool   # True if the snapshot-ready flag was set
    avg_p_total:  float  # STD: total average P over the period, W (0.0 on BASIC)
    wh_net:       float  # STD: net energy over the period, Wh (0.0 on BASIC)
    module_restarted: bool  # STD counter source: the module restarted during the period
Hinweis

Für die Energieintegration verwenden Sie master_dt_ms, nicht latch_ms — latch_ms ist ein Diagnose-Timer des Moduls.

Topologiekonstanten

Python
TOPOLOGY_SINGLE      = 1   # 1 current channel (UI1 / I1)
TOPOLOGY_SPLIT_PHASE = 2   # 2 current channels (UI2 / I2)
TOPOLOGY_THREE_PHASE = 3   # 3 current channels (UI3 / I3)
TOPOLOGY_FIVE_CH     = 5   # 5 current channels + voltage (UI5)
TOPOLOGY_SEVEN_CH    = 7   # 7 current channels + voltage (UI7)

topology_name(topology: int) -> str   # 1 → "SINGLE", 2 → "SPLIT_PHASE", ...

Lebenszyklus

RbAmp(bus, addr=0x50)

Konstruktor. Die Backend-Auflösung erfolgt in __init__. Vor begin() wird kein I²C-Verkehr erzeugt.

Parameter Beschreibung
bus I²C-Bus-Objekt (smbus2.SMBus, machine.I2C oder ein Wrapper)
addr 7-Bit-Slave-Adresse. Bereich 0x08..0x77, Standard 0x50

Löst aus: RbAmpParamError, wenn das Bus-Objekt nicht erkannt wird oder addr außerhalb des Bereichs liegt.

dev.begin()

Prüft das Gerät, erkennt die Modulreihe, cached die Topologie und primet den Snapshot-Befehl.

Erkennung der Modulreihe (1.6.0). begin() prüft zuerst, ob das Modul ein STD-Modul ist (16-Bit-Registerabbild). Ist es das, schaltet das Handle in den STD-Modus (dev.is_std wird True, dev.channels und dev.has_voltage_hw kommen vom Modul), und begin() kehrt zurück. Andernfalls läuft die unten beschriebene BASIC-Sequenz. Dafür braucht es ein Bus-Backend, das 16-Bit-Transaktionen ausführen kann; andernfalls wird das Modul als BASIC behandelt.

BASIC-Ablauf:

  1. Liest REG_VERSION — löst RbAmpIOError bei NACK aus, RbAmpVersionError, wenn 0x00 / 0xFF zurückgegeben wird.

  2. Speichert die Topologie zwischen (bei der aktuellen Firmware führt begin() keine automatische Abfrage durch; es verwendet den Hinweis aus dem Konstruktor).

  3. Liest U_rms, um festzustellen, ob ein Spannungssensor vorhanden ist (Schwelle 1.0 V).

  4. Schreibt CMD_LATCH_PERIOD (Primer) und wartet 50 ms. Der erste Snapshot nach dem Einschalten wird verworfen.

  5. Speichert time.monotonic() (bzw. time.ticks_ms() auf uPy) für die anschließende Energieintegration.

Bei einem BASIC-Modul mit SCT-013-Zangen wertet begin() außerdem die SCT-013-Nennwertkorrektur bei Modellwechsel aus.

Idempotent: gefahrlos mehrfach aufrufbar.

Kontextmanager

Python
with RbAmp(bus, 0x50) as dev:
    # dev.begin() has already been called in __enter__
    ...
# __exit__ — no-op (bus closing is the caller's responsibility)

Das empfohlene Idiom. Das __exit__ des Pakets schließt den Bus NICHT — die Verwaltung des Bus-Objekts bleibt Aufgabe des Aufrufers (typisch ist ein verschachteltes with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:).

dev.probe() -> bool

Eine leichtgewichtige Lebendprüfung. Ein einzelner Lesezugriff auf REG_VERSION ohne Nebenwirkungen.

Rückgabe: True, wenn der Slave ACK gesendet und eine unterstützte Version gemeldet hat; sonst False. Löst keine Ausnahme aus — für Polling-Szenarien gedacht.

dev.wait_ready(timeout_ms=1000) -> None

Fragt das Bereitschaftsflag des Moduls ab, bis es gesetzt ist. Nützlich nach dem Einschalten — das Modul kann bis zu 100 ms für sein erstes Echtzeit-Fenster brauchen.

Löst aus: RbAmpTimeoutError, wenn das Bit nicht vor Ablauf von timeout_ms erkannt wird.

Eigenschaften — Handle-Zustand

Python
dev.firmware_version: int      # REG_VERSION — opaque byte
dev.topology:         int      # TOPOLOGY_* constant
dev.topology_name:    str      # "SINGLE" / "SPLIT_PHASE" / "THREE_PHASE"
dev.channels:         int      # 1..3 (BASIC), 5 / 7 on UI5 / UI7, or the STD module's channel count
dev.is_std:           bool     # True if begin() detected an STD module
dev.has_voltage_hw:   bool     # True if begin() detected U_rms > 1.0
dev.address:          int      # 7-bit I²C address (updated after commit_address_change)

firmware_version ist eine Live-Eigenschaft: jeder Zugriff geht über den Bus (ein einbytiger Lesezugriff auf REG_VERSION). Speichern Sie den Wert anwendungsseitig zwischen, wenn Sie ihn in einer engen Schleife abfragen: fw = dev.firmware_version einmal nach begin(). Wurde begin() noch nicht aufgerufen, löst firmware_version RbAmpIOError aus (das Modul kann bei einem „kalten“ Handle mit NACK antworten).

Die übrigen Eigenschaften (topology, channels, has_voltage_hw, address) werden im Handle zwischengespeichert und liefern nach begin() die gespeicherten Werte, ohne den Bus zu belegen.

Echtzeitwerte (RT-Block, Aktualisierung alle 100 ms)

Alle Methoden lösen bei einem Kommunikationsfehler RbAmpIOError aus (NACK nach Wiederholung oder Ablehnung durch Plausibilitätsprüfung) oder bei einem ungültigen Argument RbAmpParamError.

Messfenster von 100 ms laufen lückenlos hintereinander, DRDY pulst einmal pro Fenster, und der Master liest den atomaren Ergebnisblock.

Eigenschaften

Python
dev.voltage         -> float   # V — RMS voltage
dev.voltage_peak    -> float   # V — peak voltage
dev.frequency       -> float   # Hz — mains frequency

Kanalindiziert über _ChannelProxy — unterstützt die Indizierung [ch] und Iteration:

Python
dev.current         # _ChannelProxy → dev.current[0], dev.current[1], ...
dev.current_peak    # _ChannelProxy
dev.power           # _ChannelProxy
dev.power_factor    # _ChannelProxy

Usage:

Python
i0 = dev.current[0]                       # a single channel
for i in dev.current:                      # iterate over all valid channels
    print(i)
total = sum(p for p in dev.power)          # sum of all channels

len(dev.current) ist gleich dev.channels.

Methoden (völlig gleichwertig zur Eigenschaftsform)

Python
dev.read_voltage(phase=0)         -> float
dev.read_voltage_peak(phase=0)    -> float
dev.read_current(ch=0)            -> float
dev.read_current_peak(ch=0)       -> float
dev.read_power(ch=0)              -> float       # signed
dev.read_power_factor(ch=0)       -> float
dev.read_frequency()              -> float

Einmaliges Lesen des gesamten RT-Blocks

Python
dev.read_all()  -> RbAmpSnapshot

Entspricht aufeinanderfolgenden read_voltage + read_voltage_peak + read_current(0..N) + read_current_peak(0..N) + read_power(0..N) + read_power_factor(0..N) + read_frequency. Nicht genutzte Kanäle (über channels hinaus) werden mit Nullen gefüllt.

Löst aus: RbAmpIOError, wenn ein Teillesevorgang fehlschlägt.

Die gängigen Leser — voltage, voltage_peak, current, current_peak, power, power_factor, frequency und ihre read_*-Formen — funktionieren auf jeder Modulreihe. Bei einem STD-Modul wählt phase in read_voltage() / read_voltage_peak() den Spannungseingang (0..n_voltage-1); bei einem BASIC-Modul ist nur phase=0 gültig.

STD-Modulreihe (1.6.0)

Sicherheit

⚠️ Validierungsstatus. Die Funktionen für Energie auf dem Gerät, Spannungswinkel und Anlaufstrom sind unter CPython (smbus2) validiert. Dieselben Aufrufe sind für MicroPython (machine.I2C) implementiert, aber der 16-Bit-Pfad unter MicroPython ist noch nicht an Hardware validiert — verwenden Sie für diese Gerätefunktionen bevorzugt CPython, bis eine Versionsnotiz etwas anderes sagt. Die gängigen Messwerte (dev.voltage, dev.current[ch], dev.power[ch], Periodensnapshots) funktionieren unabhängig davon auf jedem unterstützten Host.

Eine einzige RbAmp-Klasse bedient beide Modulreihen. begin() erkennt die Reihe automatisch; dev.is_std ist True bei einem STD-Modul. Dieselbe I²C-Verdrahtung und Adresse werden verwendet (siehe 04 · Hardware).

  • Die gängigen Leser (voltage, current, power, power_factor, frequency) funktionieren bei jedem Modul.

  • Die Aufrufe in diesem Abschnitt sind nur für STD. Auf einem BASIC-Modul lösen sie RbAmpNotSupportedError aus.

  • Einige STD-Aufrufe brauchen außerdem ein hinreichend neues Modulabbild (Energie auf dem Gerät, Mikro-Einheiten-Zähler, Spannungswinkel, Anlaufstrom). Stellt das Modul sie nicht bereit, löst der Aufruf RbAmpNotSupportedError aus („nicht verfügbar“).

  • Die Periodenaufrufe (latch_period, read_period_*, stream_period) und der Akkumulator dev.energy funktionieren auf einem STD-Modul — siehe „Periodenbilanzierung“ unten. Die eigenen Lebenszeitsummen des Moduls liefert read_std_energy().

  • Die Aufrufe zur Sensorkonfiguration (set_sensor_class, set_ct_model, set_ct_model_ch, set_ct_model_ch_force, read_ct_model_ch, read_sensor_class), reset, factory_reset, das Adressänderungspaar, die Identitätsregister (firmware_version, read_variant, read_capability, read_product_id, read_uid, read_label, set_label, read_seq_digest), der Fehler- und Ereigniskanal (read_last_error, read_event_flags, clear_event_flags, has_error, clear_error), die Flotten-Helfer (read_fleet_config, enable_gc, set_group_id, read_group_id, read_gc_tick), read_period_latch_ms und wait_ready sind nur für BASIC: auf einem STD-Modul lösen sie RbAmpNotSupportedError aus, bevor etwas auf den Bus gesendet wird.

Python
dev.is_std        -> bool   # True on an STD module (set by begin())
dev.std           -> object # internal STD client (advanced use) or None on BASIC

Leser

Python
dev.read_std_voltage(phase=0)    -> RbAmpStdVoltage   # RMS, peak, THD, angle
dev.read_voltage_angle(phase=0)  -> (float, bool)     # (degrees, valid)
dev.read_phase_sequence()        -> int               # 0..3
dev.read_std_channel(ch=0)       -> RbAmpStdChannel   # I / P / Q / S / PF + harmonics
dev.read_std_totals(k=0)         -> RbAmpStdChannel   # totals block k (0 = grand total)
dev.read_reactive(ch=0)          -> float             # var
dev.read_apparent(ch=0)          -> float             # VA
dev.read_std_config()            -> RbAmpStdConfig
dev.read_std_health()            -> RbAmpStdHealth
  • read_voltage_angle(phase) — Phasenwinkel der Spannung relativ zu Phase 0, geliefert als (degrees, valid). valid ist False bei einem Modul mit einer Spannung oder einem Modulabbild, das keine Winkel meldet.

  • read_phase_sequence() — Code der Phasenfolge: PHASE_SEQ_NA (0, nicht verfügbar), PHASE_SEQ_FORWARD (1), PHASE_SEQ_REVERSE (2), PHASE_SEQ_ABNORMAL (3). phase_seq_name(code) liefert den Textnamen. Löst RbAmpNotSupportedError auf einem BASIC-Modul oder auf einem Modulabbild aus, das ihn nicht meldet.

  • read_reactive(ch) / read_apparent(ch) — Blindleistung in var und Scheinleistung in VA für einen Kanal. Nur STD-Module; auf einem BASIC-Modul lösen sie RbAmpNotSupportedError aus (auf BASIC ist Blindleistung über diese Bibliothek nicht verfügbar).

  • read_std_totals(k) — Summenblock k; k=0 ist die Gesamtsumme. Summen je Phase hängen von der Registerkarten-Version des Moduls ab.

  • read_std_config() / read_std_health() — Konfigurations- und Status-/Zustandsblöcke.

Wertobjekte

Einfache Klassen (nicht @dataclass), alle erneut exportiert aus rbamp.

Klasse Felder
RbAmpStdVoltage u_rms, u_peak, thd_u, angle_deg, angle_valid
RbAmpStdChannel i_rms, i_peak, p, q, s, pf, thd_i, pf1, q1
RbAmpStdConfig sensor_class, ct_model, tier, i2c_addr, rate_ms, harmonics, start_ua, start_ua_supported
RbAmpStdHealth status, cal_ok, sensor_ok, mains_ok, time_valid, nvm_fault, maint, frame_count, crc_errors, lta_status, lta_src, cal_src, group_status, ring_drop, lost_frames, uptime_s, reset_cause, boot_count
RbAmpStdEnergy siehe unten

dev.read_std_energy() -> RbAmpStdEnergy

Lebenszeit-Energie-Snapshot auf dem Gerät. Erfordert ein Modul, das Energie auf dem Gerät bereitstellt; sonst RbAmpNotSupportedError.

RbAmpStdEnergy enthält:

Gruppe Felder
Wirkenergie, Wh act_import_wh, act_export_wh, act_net_wh
Aktiv, mWh act_import_mwh, act_export_mwh, act_net_mwh
Aktiv, µWh act_import_uwh, act_export_uwh, act_net_uwh
Blindleistung rea_import_varh, rea_export_varh; µvarh: rea_import_uvarh, rea_export_uvarh
Pro Kanal channels (Anzahl gültiger Einträge); ch_import_mwh[], ch_export_mwh[], ch_import_uwh[], ch_export_uwh[]
Buchführung generation, uptime_s, group_status
Herkunftskennzeichen fine, fine_reactive

Die µWh- / µvarh-Felder sind immer gefüllt. Liefert das Modul-Image die feineren Zähler nicht, werden sie aus den gröberen hochskaliert, und fine (Wirk-) / fine_reactive sind False — prüfen Sie das Flag, wenn Sie wissen müssen, woher der Wert stammt.

RbAmp.std_energy_delta(prev, now) -> (delta, module_restarted)

Zwischen zwei read_std_energy()-Snapshots verbrauchte Energie (statische Methode; auch exportiert als std_energy_delta). Stromausfallsicher.

  • module_restarted ist True, wenn now.uptime_s < prev.uptime_s.
  • delta ist ein RbAmpStdEnergy mit dem Zuwachs je Feld, oder None, wenn sich der Zähler generation geändert hat (die beiden Messwerte sind nicht vergleichbar).

  • Ein Zähler, der knapp unter dem vorherigen Wert liegt (Wiederaufnahme nach Stromausfall), wird auf 0 begrenzt; net ist immer Import − Export der begrenzten Teile.

  • Einträge pro Kanal werden nur ausgefüllt, wenn beide Snapshots dieselbe Kanalzahl haben.

Python
prev = dev.read_std_energy()
time.sleep(60)
now = dev.read_std_energy()
delta, restarted = RbAmp.std_energy_delta(prev, now)
if delta is not None:
    print(delta.act_import_wh, "Wh imported in this interval")

Anlaufstrom und Konfiguration

Python
dev.get_start_current()     -> int    # µA, 0 = off
dev.set_start_current(ua)   -> None
dev.save_config()           -> None   # persist writable STD config to flash (blocking)
dev.set_time(unix_epoch)    -> None   # set the module's clock
  • get_start_current() — der Anlaufstrom der Energie in µA (0 = aus).

  • set_start_current(ua) — unterhalb dieses Stroms je Kanal zählt das Modul keine Energie in Import/Export; die Live-Messwerte (I, P, Q) bleiben unberührt. Der Wert wirkt sofort; rufen Sie save_config() auf, um ihn über einen Neustart hinweg zu behalten. Ein nicht unterstützter Wert löst RbAmpParamError aus, bevor etwas auf den Bus geschrieben wird. Der Wert muss 0 (aus) oder ein Vielfaches von 10 µA im unterstützten Bereich sein.

  • save_config() — speichert die beschreibbare STD-Konfiguration. Blockiert.

  • set_time(unix_epoch) — setzt die Uhr des Moduls aus einer Unix-Epoche; eine Epoche vor 2020 löst RbAmpParamError aus. Setzen Sie die Zeit nach jedem Neustart des Moduls erneut (read_std_health().time_valid ist False, bis die Uhr gesetzt ist).

  • get_start_current() / set_start_current() lösen RbAmpNotSupportedError aus, wenn das Modul-Image die Anlaufstrom-Einstellung nicht bereitstellt; RbAmpStdConfig.start_ua_supported zeigt, ob es das tut.

Latch-Bänke

Ein STD-Modul, das Latch-Bänke meldet, führt 8 unabhängige Bänke. Eine Bank akkumuliert, solange ihr Bit in der Arm-Maske gesetzt ist; ein Latch erfasst und setzt sie beim nächsten Messfenster-Übergang zurück, sodass eine Periode das Intervall zwischen zwei Latches derselben Bank ist, gemessen mit der Uhr des Masters. Diese Aufrufe benötigen ein Modul, das Bänke meldet, und lösen sonst RbAmpNotSupportedError aus; eine Banknummer außerhalb von 0..7 löst RbAmpParamError aus.

Python
dev.std_arm_banks(mask)                 -> None            # bit i = bank i accumulates
dev.std_latch(bank)                     -> None            # snapshot + reset; does not wait
dev.std_read_latch(bank)                -> RbAmpStdLatch
RbAmp.std_latch_wh(snap, dt_ms, ch=0xFF) -> (wh_import, wh_export)
  • std_arm_banks(mask) — setzt die Armierungsmaske. Die Maske bleibt bei einem Neustart des Moduls nicht erhalten.

  • std_latch(bank) — latcht eine Bank. Lesen Sie frühestens 300 ms später.

  • std_read_latch(bank) — liefert den Snapshot der Bank. Das Gültigkeitsflag des Moduls besagt nur, dass die Bank mindestens einmal gelatcht wurde; es ist kein Frische-Flag, daher warten Sie mindestens ein Zeitfenster (300 ms sind ein sicherer Richtwert) nach std_latch(). Eine Bank, die nie gelatcht wurde, löst RbAmpStaleError aus. Eine leere Bank, die nicht mehr armiert ist (das Modul wurde neu gestartet), wird neu armiert und einmal gelatcht, um eine neue Periode zu beginnen; der Aufruf löst RbAmpStaleError aus: Verwerfen Sie diese Periode und starten Sie Ihre eigene Zeitreferenz neu.

  • RbAmp.std_latch_wh(snap, dt_ms, ch=0xFF) — rechnet die Energie des Snapshots über dt_ms der Uhr des Masters in Wh um. ch ist ein Kanalindex oder 0xFF (Standard) für die Modulsumme. Liefert (wh_import, wh_export); Export ist null oder negativ. Löst RbAmpStaleError für einen Snapshot ohne Samples aus.

Python
class RbAmpStdLatch:
    bank:       int     # 0..7
    valid:      bool    # the bank has been latched at least once
    channels:   int
    p_avg, q_avg, s_avg: float     # average P (W), Q (var), S (VA) over the period
    max_p, max_i, max_u, min_u: float   # peak P (W), peak I (A), peak / minimum U (V)
    e_import_mws, e_export_mws: int     # energy, mW·samples (export <= 0)
    nsamp:      int     # samples in the period
    win_count:  int     # measurement windows in the period (0 = not armed / nothing elapsed)
    p_avg_ch:   list    # per-channel average P, W
    e_import_ch_mws, e_export_ch_mws: list   # per-channel energy, mW·samples

Periodenbilanzierung

Den Gesamtüberblick finden Sie unter 01 · Übersicht, eine minimale Vorlage in 05 · Schnellstart, Schritt 5.

Auf einem STD-Modul funktionieren dieselben Aufrufe. begin() wählt die Periodenquelle anhand dessen, was das Modul meldet:

Modul meldet Periodenquelle Latch-Befehl
Energiezähler im Gerät Differenz zweier Zählerstände im Zeitplan des Masters keine
nur Latch-Bänke Latch-zu-Latch auf Bank 0 (mindestens 300 ms Einschwingzeit) CMD_LATCH_PERIOD auf Bank 0
keine von beiden — die Periodenaufrufe lösen RbAmpNotSupportedError aus

Bei der Zählerquelle beginnt die erste Periode bei begin(), latch_period() tut nichts, is_period_valid() ist True, sobald die Zähler verankert sind, read_period_max_power() löst RbAmpNotSupportedError aus (kein Spitzenwert), und read_period_avg_power(ch) existiert nur bei einem Einkanalmodul, nachdem eine Periode gelesen wurde. Ein Wechsel der Zählergeneration verankert die Periode neu und löst RbAmpStaleError aus; ein Neustart des Moduls innerhalb einer Periode wird in snap.module_restarted gemeldet (während des Neustarts wird keine Energie gemessen). Bei der Latch-Quelle löst ein leerer Snapshot RbAmpStaleError aus; hat die Bank ihre Armierung verloren (Neustart des Moduls), wird sie zuerst neu armiert. Der Snapshot enthält avg_p_total, wh_net und module_restarted. read_period_latch_ms() gibt es nur bei BASIC.

dev.latch_period() -> None

Schreibt CMD_LATCH_PERIOD. Wartet nicht — der Aufrufer muss die 50-ms-Einschwingzeit abwarten und vor dem Lesen dev.is_period_valid() prüfen.

Für die meisten Aufgaben verwenden Sie read_period_snapshot() — es kapselt die gesamte Abfolge.

dev.is_period_valid() -> bool

Liest das Bit „Snapshot bereit“. Gibt True zurück, wenn der letzte Snapshot frisch ist.

dev.read_period_avg_power(ch=0) -> float

Mittlere Wirkleistung eines Kanals über die abgeschlossene Periode. Muss nach latch_period() + 50 ms Einschwingzeit + Gültigkeitsprüfung aufgerufen werden.

Löst jeden Kanal des Moduls auf (ch = 0..channels-1), einschließlich der Kanäle 3+ bei 5- und 7-Kanal-Modulen (UI5 / UI7). Der Periodensnapshot und der Wh-Akkumulator decken ebenfalls alle Kanäle ab. dev.read_period_avg_p(ch) ist ein Alias mit demselben Verhalten.

dev.read_period_max_power() -> float

Spitzen-Momentanleistung auf Kanal 0 über die abgeschlossene Periode. ch=0 nur bei Firmware v1.

dev.read_period_latch_ms() -> int

Periodendauer aus Sicht des Geräts, in ms.

Diagnosewert.

Der interne Timer des Moduls hat begrenzte Genauigkeit. Für die Energieintegration verwenden Sie master_dt_ms aus RbAmpPeriodSnapshot, nicht dieses Feld.

dev.read_period_snapshot(settle_ms=50, skip_latch=False) -> RbAmpPeriodSnapshot

Der empfohlene Einstiegspunkt für die Periodenbuchhaltung. Die vollständige Abfolge im Hintergrund:

  1. Bei skip_latch=True — den Snapshot-Befehl überspringen (für das Multi-Modul-Muster nach einer manuellen Reihe von Snapshot-Befehlen).

  2. Andernfalls — CMD_LATCH_PERIOD schreiben.

  3. Erfassen Sie time.monotonic(), um master_dt_ms zu berechnen.
  4. time.sleep(settle_ms / 1000) — standardmäßig 50 ms.
  5. Prüfen Sie das Bereitschaftsflag des Snapshots. Ist es 0, lösen Sie RbAmpStaleError aus (der vorherige Zeitstempel bleibt erhalten, damit der nächste erfolgreiche Snapshot das volle Intervall abdeckt und Wh exakt bleibt).

  6. Lesen Sie avg_p[0..channels-1] + max_p + latch_ms.

  7. Zeitstempel aktualisieren und energy.tick(snap) aufrufen, um Wh zu integrieren (sofern der Akkumulator nicht über energy.disable() deaktiviert ist).
Parameter Beschreibung
settle_ms Wartezeit nach dem Snapshot-Befehl in ms. Standard 50.
skip_latch Bei True — den Snapshot-Befehl nicht senden, nur lesen.

Löst aus: RbAmpStaleError (Snapshot veraltet); RbAmpIOError (Busausfall).

async dev.stream_period(interval_s=60.0, skip_stale=True)

Ein asynchroner Generator, der RbAmpPeriodSnapshot im Abstand von interval_s liefert. Funktioniert auf CPython-asyncio und MicroPython-uasyncio (MicroPython ≥ 1.20 — import asyncio funktioniert ebenfalls; für ältere Versionen verwenden Sie import uasyncio as asyncio).

Python
async for snap in dev.stream_period(interval_s=60.0):
    # snap is an RbAmpPeriodSnapshot, .valid guaranteed True (by default skip_stale=True)
    print(snap.avg_p[0])
Parameter Beschreibung
interval_s Zeitraum zwischen Snapshots (≥ 30 s empfohlen)
skip_stale True (Standard) — veraltete Snapshots werden automatisch übersprungen. False — sie werden mit snap.valid=False geliefert, und Ihr Code muss selbst if not snap.valid: continue prüfen
Sicherheit

⚠ CPython: blockiert die Event-Loop. Intern ruft stream_period() das synchrone, blockierende read_period_snapshot() auf — mit einer time.sleep(0.05)-Einschwingzeit und etwa 50–100 ms Single-Byte-Lesevorgängen über den Bus. Auf CPython blockiert das die gesamte asyncio-Event-Loop für diese 100 ms — andere Coroutinen (MQTT, HTTP, Wi-Fi-Keepalive) bekommen keine CPU-Zeit. Für Produktionsserver umschließen Sie das mit run_in_executor:

Python
import asyncio

async def stream_period_nonblocking(dev, interval_s=60.0):
    loop = asyncio.get_event_loop()
    while True:
        await asyncio.sleep(interval_s)
        snap = await loop.run_in_executor(None, dev.read_period_snapshot)
        if snap.valid:
            yield snap

Auf MicroPython ist das Problem kleiner — der uasyncio-Scheduler gibt seltener an andere Tasks ab, und blockierendes I²C gilt in eingebetteten asynchronen Mustern als akzeptabel. Wenn Sie nichtblockierendes Verhalten brauchen, nutzen Sie einen eigenen Thread über _thread.start_new_thread (auf ESP32 µPy).

Energiebuchführung (Akkumulator auf Masterseite)

dev.energy — Instanz von RbAmpEnergy

Ein Wh-Akkumulator je Kanal. Der Zugriff erfolgt über eine Eigenschaft — das Paket besitzt die Instanz:

Python
dev.energy.wh(ch=0)         -> float    # current Wh total for the channel
dev.energy.reset(ch=0)      -> None     # zero a single channel
dev.energy.reset_all()      -> None     # zero all channels
dev.energy.is_enabled       -> bool     # True while auto-integration is active (default)
dev.energy.disable()        -> None     # turn off auto-integration
dev.energy.enable()         -> None     # turn it back on

Der Akkumulator wird bei jedem erfolgreichen dev.read_period_snapshot() automatisch aktualisiert. Er ist vorzeichenbehaftet — ein negativer Wert bedeutet Nettoexport.

Integrationsformel:

Text
wh[ch] += snap.avg_p[ch] × master_dt_ms / 1000 / 3600
         [W]             [milliseconds]              → [Wh]

dev.energy.disable() ist nützlich für Deep-Sleep-Szenarien, in denen der Master die Wh-Speicherung im RTC-Speicher selbst übernimmt — siehe 06 · Beispiele, Szenario 9.

Sensorkonfiguration

Eine zweistufige Abfolge. Einen detaillierten Leitfaden zur Modellauswahl finden Sie unter 03 · Auswahl des Stromsensors.

dev.set_sensor_class(cls) -> None

Setzt die Sensorklasse des Stromsensors und speichert sie im Flash. Blockierend, ~705 ms.

Python
dev.set_sensor_class(RbAmpSensorClass.SCT_013)
# or equivalently:
dev.set_sensor_class(1)
Parameter Beschreibung
cls Eine RbAmpSensorClass-Enum oder ein int 0..3

Raises:

  • RbAmpParamError — cls außerhalb von 0..3
  • RbAmpModeError — das Modul ist werkseitig gepaart (aktuelle Klasse WIRED_CT / BUILTIN_CT) und cls weicht ab; eine Änderung würde die Kalibrierung des eingebauten Sensors löschen

  • RbAmpIOError — Kommunikationsfehler

Muss vor set_ct_model*() aufgerufen werden. Das Schreiben derselben Klasse, die das Modul bereits hält, ist ein No-Op (kein Bus-Schreibvorgang), weil ein Klassenschreiben die kanalweisen CT-Modelle geräteseitig löscht. Siehe Read-before-write-Schutz.

dev.read_sensor_class() -> int

Liest die festgelegte Sensorklasse: 0 UNSET, 1 SCT_013, 2 WIRED_CT, 3 BUILTIN_CT (die Werte von RbAmpSensorClass). Liefert 0 auf einer Firmware, auf der das Register nicht vorhanden ist.

dev.set_ct_model(code) -> None

Die Form mit einem einzelnen Parameter (veraltet) — legt das CT-Zangenmodell nur auf Kanal 0 fest.

code Modell
1 SCT-013-005
2 SCT-013-010
3 SCT-013-030
4 SCT-013-050
5 SCT-013-100
6 SCT-013-020
7 SCT-013-060
Hinweis

Die zulässige Menge für die Klasse SCT_013 ist {1, 2, 3, 4, 5, 6, 7}. Die vollständige Tabelle der zulässigen Mengen je Klasse steht in 03 · Auswahl des Stromsensors.

Raises:

  • ValueError (und auch RbAmpParamError) — code ist nicht in der Akzeptanzmenge der Klasse für das aktuelle REG_SENSOR_CLASS enthalten (für SCT_013 ist das {1, 2, 3, 4, 5, 6, 7})
  • RbAmpModeError — wenn set_sensor_class() nicht aufgerufen wurde oder das Modul werkseitig gepaart ist (Klasse 2/3) und der Code abweicht (im Servicekontext set_ct_model_ch_force() verwenden)

  • RbAmpIOError — Kommunikationsfehler

Das Setzen des Modells, das der Kanal bereits hält, ist ein No-Op (Read-before-write-Schutz).

RbAmpModeError-Meldung (Klasse nicht gesetzt):

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

Entspricht dev.set_ct_model_ch(0, code).

dev.set_ct_model_ch(channel, code) -> None

Die Form pro Kanal. Legt das CT-Zangenmodell auf einem bestimmten Kanal fest.

Intern: Staging von REG_CT_MODEL (0x05) → Befehl CMD_SET_CT_MODEL_CH0/1/2 (Opcode 0x28/0x29/0x2A) → 5 ms Einschwingzeit → CMD_SAVE_USER_CONFIG (0x32) → 700 ms. Blockierend, ~705 ms.

Hinweis

✅ v1.3: Die Reihenfolge der Kanalbindung spielt keine Rolle. Auf v1.3 bewirkt das Schreiben von REG_CT_MODEL (0x05) ein Staging des Wertes, wendet ihn aber nicht mehr automatisch auf ch0 an. Die Anwendung erfolgt nur über CMD_SET_CT_MODEL_CHn. Sie können die Kanäle in beliebiger Reihenfolge konfigurieren.

Python
dev.set_ct_model_ch(0, 1)  # any order is OK on v1.3
dev.set_ct_model_ch(1, 3)
dev.set_ct_model_ch(2, 6)

Raises:

  • RbAmpParamError — channel außerhalb von 0..dev.channels-1 oder code nicht in der zulässigen Menge der Klasse (für SCT_013 — {1, 2, 3, 4, 5, 6, 7})
  • RbAmpModeError — set_sensor_class() wurde nicht aufgerufen, oder das Modul ist werkseitig gepaart und der Code weicht ab

dev.set_ct_model_ch_force(channel, code) -> None

Service-Variante von set_ct_model_ch(), die den Schutz „erst lesen, dann schreiben“ umgeht: Sie schreibt auch dann, wenn das Modul werkseitig gepaart ist oder den Code bereits hat. Gedacht für Techniker, die ein Gerät neu sensorisieren. Das Modul prüft das Paar (Klasse, Code) weiterhin, und der Aufruf löst bei einem ungültigen Paar RbAmpParamError aus.

Schutz „erst lesen, dann schreiben“

Das Schreiben eines CT-Modells ersetzt die Kalibrierung dieses Kanals durch die generische Voreinstellung für das Modell; deshalb prüfen die Setter seit 1.6.0 zuerst:

Aufruf Das Modul hält den Wert bereits Werkseitig gepaartes Modul (Klasse 2/3) Andernfalls
set_sensor_class(cls) keine Operation, kein Schreibzugriff auf den Bus RbAmpModeError, wenn cls abweicht schreibt + speichert
set_ct_model(code) / set_ct_model_ch(ch, code) keine Operation, kein Schreibzugriff auf den Bus RbAmpModeError, wenn der Code abweicht schreibt + speichert
set_ct_model_ch_force(ch, code) Schreibvorgänge Schreibvorgänge Schreibvorgänge

V2-Verify-Spiegel — CT_MODEL_CH0/1/2 (0x51-0x53)

Nur-Lese-Register, die die tatsächlich auf jedem Kanal angewendete CT-Voreinstellung widerspiegeln. Das Schreib-Wire-Protokoll ändert sich nicht — Schreibvorgänge verwenden den oben beschriebenen Mechanismus. 0x51–0x53 dienen nur der Rücklesung für Zustandsprüfungen und Muster aus Lesen-Vergleichen-Schreiben:

Python
applied_ch0 = dev.read_ct_model_ch(0)   # what is actually applied
applied_ch1 = dev.read_ct_model_ch(1)
applied_ch2 = dev.read_ct_model_ch(2)

SCT-013-Nennwertkorrektur bei Modellwechsel

SCT-013-Module werden werkseitig mit einem Referenzmodell der Zange kalibriert. Wird ein Kanal auf ein anderes Modell umgestellt, wendet ein Modulabbild, das sich nicht selbst neu skaliert, weiterhin die Referenzverstärkung an; Strom und Leistung würden dann im falschen Maßstab gelesen. Seit 1.6.0 korrigiert die Bibliothek dies automatisch bei BASIC-Modulen mit der Sensorklasse SCT_013:

  • Strom, Leistung und die daraus abgeleitete Energie (read_current, read_current_peak, read_power, read_period_avg_power sowie daraus der Periodensnapshot und dev.energy) werden auf das gewählte Modell korrigiert, bezogen auf die Verstärkung, die das Modul tatsächlich anwendet.

  • Spannung und Leistungsfaktor werden nie verändert.

  • Bei Modul-Firmware bis 1.4.19 startet das Modul bei einem Modellwechsel einmal neu (etwa eine Sekunde); ab 1.4.20 korrigiert sich das Modul selbst. Die SCT-Nennwertkorrektur skaliert Strom, Leistung und Energie, niemals Spannung oder Leistungsfaktor.
  • Module, deren Firmware das selbst erledigt, werden erkannt und unverändert gelassen (Skalierung 1).

  • Werkseitig gepaarte Module (Klasse 2/3) werden nie skaliert.

  • Die Korrektur wird in begin() ausgewertet und erneut nach einem Neustart, den die Bibliothek auslöst (reset()), oder nach einem erkannten Neustart. In einer Situation (ein Modell, das während des laufenden Netzzyklus geschrieben wurde) kann die Bibliothek einen Modul-Reset ausführen, um die gespeicherte Verstärkung zu lesen.
Python
dev.set_rating_correction(enabled: bool)  -> None   # default enabled
dev.rating_correction_enabled             -> bool
dev.ct_rating_scale(ch=0)                 -> float  # scale currently applied (1.0 = none)
dev.ct_rating_status(ch=0)                -> (action, detail) | None
dev.refresh_rating_correction()           -> None
  • set_rating_correction(enabled) — schaltet die Korrektur ab, um die rohen, unkorrigierten Werte zu lesen (oder auf einem Modul, dessen Firmware bereits selbst korrigiert). Rechnet sofort neu.

  • ct_rating_scale(ch) — der Skalierungsfaktor, der auf Strom/Leistung/Energie eines Kanals angewendet wird; 1.0, wenn keine Korrektur aktiv ist.

  • ct_rating_status(ch) — (action, detail) der letzten Auswertung für einen Kanal oder None, wenn der Kanal nie ausgewertet wurde (zum Beispiel kein SCT-Kanal). action ist einer von "unity", "ok", "needs_reset", "warn_uncal", "warn_gain"; detail ist Text. Die warn_*-Aktionen bedeuten, dass die Bibliothek keine sichere Skalierung bestimmen konnte und den Messwert unkorrigiert gelassen hat.

  • refresh_rating_correction() — nach einem Neustart neu auswerten, den die Bibliothek nicht ausgelöst hat (zum Beispiel ein Modul, das extern gespeichert und zurückgesetzt wurde).

Dies ist ein Merkmal des SCT-013-Pfads in allen rbAmp-Bibliotheken, nicht spezifisch für Python.

dev.save_gains() -> None

Ein „nackter“ Schreibvorgang CMD_SAVE_GAINS (0x26) — nur werkseitig.

Hinweis

⛔ GESPERRT in der Produktions-Firmware (v1.3 liefert DEV_ERR_PARAM; das Gerät lehnt den Schreibvorgang ab, und ein anschließender Neustart setzt jede Änderung im RAM zurück). CMD_SAVE_GAINS ist für den werkseitigen Provisionierungsmodus reserviert und speichert nur Verstärkungen sowie die Koeffizienten für Rauschzahl und Phase. Für eine nutzerseitige Speicherung von sensor_class / ct_model je Kanal, Adresse und Bezeichnung verwenden Sie dev.save_user_config() (oder die Aufrufe pro Kanal set_ct_model_ch() / set_sensor_class(), die intern bereits CMD_SAVE_USER_CONFIG (0x32) ausführen).

Löst aus: RbAmpModeError, wenn das Modul nicht im Werks-Provisionierungsmodus ist, RbAmpIOError bei einem Kommunikationsfehler.

dev.prepare_address_change(new_addr) -> None

Schritt 1 von 2 für die Änderung der I²C-Adresse des Moduls. Produktionstauglich auf der aktuellen Firmware (v1.3-Zwei-Phasen-Commit).

Szenario: Bereichsprüfung → den Kandidaten in REG_I2C_ADDRESS (0x30) im RAM schreiben → das Magic-Byte 0xA5 in REG_ADDR_COMMIT_MAGIC (0x31) schreiben — armiert. Der Aufrufer muss commit_address_change() innerhalb von 5 Sekunden aufrufen, sonst verfällt die Armierung.

Raises:

  • RbAmpParamError — new_addr außerhalb von 0x08..0x77 oder gleich der aktuellen Adresse

  • RbAmpIOError — Kommunikationsfehler

dev.commit_address_change() -> None

Schritt 2 von 2. Muss innerhalb von 5 Sekunden nach prepare_address_change() aufgerufen werden.

Szenario: Magic-Armierung auf Frische prüfen → CMD_COMMIT_ADDR (Opcode 0x30) → im Flash speichern → CMD_RESET → ~300 ms bis zum Start und zur Antwortbereitschaft → internes Adressfeld aktualisieren. Nach dem Neustart zeigt REG_I2C_ADDRESS (0x30) (v1.3) die neue aktive Adresse — das ist die maßgebliche Prüfung.

Sicherheit

⚠ Historisch: Vor den Korrekturen von v1.3 war die Adressänderung fälschlich als nur werkseitig dokumentiert. In v1.3 ist sie ein Produktionsvorgang über einen Zwei-Phasen-Commit.

Eine zusätzliche Nuance:

Sicherheit

⚠ Neustart und erneute Aufzählung nach dem Commit. Nach einem erfolgreichen Commit setzt sich das Gerät zurück und meldet sich an der NEUEN Adresse erneut an. Folgeaufrufe über dieses Handle sprechen die neue Adresse transparent an — aber jeder ANDERE Master am Bus (ein weiteres Python-Skript, eine ESP-IDF-Komponente, eine Debug-Sonde) hält das Gerät weiterhin für unter der alten Adresse erreichbar, bis dessen interner Zustand manuell aktualisiert wird.

Raises:

  • RbAmpTimeoutError — das Scharfschaltfenster (5 s) ist abgelaufen
  • RbAmpIOError — Kommunikationsfehler

dev.factory_reset() -> None

Der Befehl CMD_FACTORY_RESET + 1500 ms Wartezeit.

Sicherheit

Destruktiver Vorgang. Löscht ALLE Flash-Parameter (CT-Modell, Sensorklasse, Kalibrierkoeffizienten, I²C-Adresse). Das Modul kehrt zu den Werkseinstellungen zurück — RbAmpSensorClass wird UNSET, REG_CT_MODEL wird 0. Jede zuvor über set_sensor_class() / set_ct_model*() angewendete Konfiguration ist verloren. Der nächste Anwender MUSS beide Aufrufe, set_sensor_class() und set_ct_model*(), erneut ausführen, bevor die Messung wieder funktioniert. Das ist kein „weicher Neustart“ — für einen weichen Neustart verwenden Sie reset(). factory_reset() ist für die Wiederherstellung aus einem bekannt fehlerhaften Zustand oder für die Übergabe des Moduls an einen anderen Anwender bzw. eine andere Installation vorgesehen.

Löst aus: RbAmpIOError bei einem Kommunikationsfehler.

dev.reset() -> None

Der Befehl CMD_RESET + 100 ms Wartezeit. Ein weicher Neustart des Geräts ohne Verlust der Flash-Parameter.

Löst aus: RbAmpIOError bei einem Kommunikationsfehler.

Identifikation und Provisionierung (v1.3)

Diese Methoden lassen den Master genau erkennen, was am Bus angeschlossen ist (Variante, Fähigkeitsbitmap, UID, Label), und bereiten ein neues oder frisch geflashtes Modul für den Betrieb vor (Provisionierung

  • Speichern der Konfiguration im Flash).

dev.read_variant() -> int

Liest das Register HW_VARIANT (0x55) des Moduls (das kanonische SKU-Byte von v1.3):

Code SKU I-Kanäle U-Kanal
1 UI1 1 ja
4 I1 1 nein
5 I2 2 nein
6 I3 3 nein

Dies ist der empfohlene Weg für die Autoerkennung — der NACK-Probe-Pfad wurde entfernt (die Firmware sendet bei Lesevorgängen nie ein NACK; nicht zugeordnete Adressen liefern 0x00).

dev.read_capability() -> int

Liest die 16-Bit-Funktionsmatrix aus den Registern CAPABILITY (0x57/0x58), little-endian u16. Die Matrix enthält ein Flag für das Spannungs-Frontend. Verwenden Sie sie zur Funktionserkennung (nicht über Versionsheuristiken).

dev.has_voltage() -> bool

Eine Komfortfunktion über read_capability() — gibt True zurück, wenn das Modul einen U-Kanal hat. Wird beim ersten Aufruf im Handle zwischengespeichert.

dev.read_product_id() -> int

Liest PRODUCT_ID (0x54) — das Byte-Kennzeichen der Familie (rbAmp = 0x01). Wird vom Flottenscanner verwendet, um zu bestätigen, dass das Gerät an einer Adresse tatsächlich ein rbAmp ist.

dev.read_uid() -> bytes

Liest die eindeutige 96-Bit-Kennung des MCU aus UID (0x5C..0x67) in einem einzigen Burst-Vorgang (liefert ein bytes-Objekt der Länge 12). Die UID ist für jedes Modul eindeutig und ändert sich nicht beim erneuten Flashen.

dev.read_label() -> str

Liest das 8-Byte-Anwenderlabel aus LABEL (0x68..0x6F). ASCII, mit Nullen aufgefüllt; liefert eine Zeichenkette (NUL-bereinigt). Eine leere Zeichenkette, wenn kein Label gesetzt ist.

dev.set_label(label: str) -> None

Schreibt ein 8-Byte-Label. Die Zeichenkette wird auf 8 Byte gekürzt oder mit Nullen aufgefüllt. Der Schreibvorgang erfolgt Byte für Byte (rbAmp führt kein Auto-Increment bei Schreibvorgängen aus; das Paket führt die Byte-Schleife automatisch aus). Danach ist dev.save_user_config() nötig, damit das Label einen Reset übersteht.

Löst aus: RbAmpIOError bei einem Kommunikationsfehler.

dev.is_provisioned() -> bool

Prüft, ob das Modul die Erstprovisionierung durchlaufen hat. Es prüft REG_ERROR != 0xFB (DEV_ERR_FLASH_PARAMS_BAD) — 0xFB setzt die Firmware, wenn der Anwenderkonfigurationsblock leer oder beschädigt ist. Ein werksneues Modul liefert False — nach der ersten Einrichtung von CT-Modell und Adresse ist ein save_user_config() nötig.

Hinweis

Auf v1.3 ist dieser Code bei einem unberührten Modul normal (nicht fatal). Brechen Sie die Provisionierung beim ersten Auftreten von 0xFB nicht ab.

dev.save_user_config() -> None

Löst CMD_SAVE_USER_CONFIG (Opcode 0x32) aus — speichert den Anwenderkonfigurationsblock im Flash: SENSOR_CLASS, CT_MODEL je Kanal, I2C_ADDRESS, FLEET_CONFIG, GROUP_ID, LABEL. Die werkseitigen Kalibrierparameter werden nicht gespeichert.

Blockiert den Thread für ~700 ms (Flash-Lösch- und Schreibzyklus). Versuchen Sie während des Aufrufs nicht, aus anderen Tasks auf das Modul zuzugreifen.

Löst aus: RbAmpIOError / RbAmpTimeoutError.

Rücklesen ≠ Persistenz

: Dass ein Wert tatsächlich in den Flash geschrieben wurde, erfordert einen Neustart + erneutes Lesen. Siehe den Abschnitt „Fehlermodell v1.3“ unten.

Fehlermodell v1.3 — zwei unabhängige Kanäle

Fehler haben zwei unabhängige Kanäle, die auf unterschiedliche Weise arbeiten. Der Unterschied ist entscheidend, um den Zustand des Moduls richtig zu deuten.

Kanal A — clientseitig, synchron Kanal B — DUT-seitig, dauerhaft asynchron
Wo es sitzt Validierung innerhalb des Pakets (_validate_ct_code usw.) REG_ERROR (0x02) + EVENT_FLAGS.bit3 (0x2A)
Wann er auslöst Vor der I²C-Transaktion (die Bibliothek fängt sie ab) Nachdem die Firmware einen Schreibvorgang angenommen und dann abgelehnt hat
Was der Master sieht Der Setter löst RbAmpParamError aus; REG_ERROR auf dem Gerät bleibt 0x00 REG_ERROR = der Ablehnungscode sofort; bit3 wird einige hundert Millisekunden nach der Transaktion gesetzt
Dauerhaft nein (nur eine Ausnahme) REG_ERROR letzter Schreibvorgang; bit3 klebrig W1C
Typischer Weg Ein Argument außerhalb der zulässigen Grenzen (channel ∉ {0,1,2}, code ∉ der charakterisierten Menge, sensor_class außerhalb der Enum) Ein roher Registerschreibvorgang, den das Paket nicht vorab validiert (Low-Level dev._io.write_reg() mit einem ungültigen Byte)

Kanal A — clientseitige Validierung (Paket-Setter)

Alle Paket-Setter (set_sensor_class, set_ct_model, set_ct_model_ch, configure_channels usw.) prüfen zuerst die Argumente gegen die zulässigen Werte. Liegt ein Argument außerhalb des Bereichs, wirft der Setter RbAmpParamError, ohne überhaupt eine I²C-Transaktion auszuführen. Dementsprechend bleibt REG_ERROR auf dem Gerät unverändert:

Python
from rbamp import RbAmp, RbAmpParamError

try:
    dev.set_ct_model_ch(99, 3)        # invalid channel
except RbAmpParamError as e:
    print(f"client-side guard: {e}")
    reg_err = dev.read_last_error()
    print(f"REG_ERROR on the device: 0x{reg_err:02X}")
    # → 0x00 (the package stopped it before the wire, REG_ERROR untouched)

Das heißt: Wenn Sie genau wissen wollen, warum ein Setter fehlgeschlagen ist, ist die verlässliche Quelle die Ausnahme selbst (RbAmpParamError.args / str(e)). REG_ERROR auf dem Gerät sagt in diesem Szenario nichts aus.

Kanal B — Ablehnung auf Seiten des DUT (dauerhaft, asynchron)

Wenn ein Schreibvorgang über I²C ging (die Bibliothek ihn nicht abgefangen hat, weil das Argument gültig aussah), das Gerät ihn aber abgelehnt hat, greift der zweite Kanal:

  • read_last_error() liefert sofort den Ursachencode (zum Beispiel 0xFE = DEV_ERR_PARAM). Das ist das Ergebnis des letzten Schreibvorgangs: jeder nächste erfolgreiche Schreibvorgang überschreibt es. Sie müssen es sofort nach Ihrem Schreibvorgang lesen, vor jeder anderen Transaktion.

  • has_error() — der klebrige W1C-Indikator von EVENT_FLAGS.bit3. Er wird nicht sofort gesetzt: im Test wurde zwischen der abgewiesenen Transaktion und dem Setzen von bit3 eine Verzögerung von einigen hundert Millisekunden gemessen.

Sicherheit

⚠ Verwenden Sie has_error() nicht, um einen gerade gemachten Schreibvorgang zu prüfen. Für das Ergebnis genau dieses Schreibvorgangs ist nur read_last_error() verlässlich, gelesen sofort nach dem Schreiben, vor jeder anderen Transaktion (plus die Ausnahme des Setters). has_error() ist der asynchrone Kanal für abfrageartige Überwachung, ob zwischen zwei Prüfungen etwas ausgefallen ist, nicht für die synchrone Validierung.

Einen dauerhaften Fehler löschen — beides löschen (REG_ERROR und bit3)

bit3 wird von der Firmware alle paar hundert Millisekunden aus dem aktuellen Zustand von REG_ERROR neu abgeleitet. Ein einfaches clear_event_flags(1 << 3) funktioniert daher nicht — bit3 wird sofort erneut gesetzt aus dem noch nicht gelöschten REG_ERROR. Die richtige Reihenfolge:

Python
dev.clear_error()                     # zero REG_ERROR
dev.clear_event_flags(1 << 3)         # reset sticky bit3

Wenn Sie Atomarität wollen, darf zwischen ihnen kein abgewiesener Schreibvorgang liegen.

dev.read_last_error() -> int

Liest das Register REG_ERROR (0x02) des Geräts direkt (ein Drahtlesevorgang) — das Ergebnis der letzten auf dem Bus erfolgreich angenommenen Transaktion (ein Schreibvorgang oder Befehl). Nicht klebrig: jeder nächste erfolgreiche Schreibvorgang überschreibt es mit seinem eigenen Ergebnis. Verwendet im Kanal B (Ablehnung auf DUT-Seite) für den erweiterten Ursachencode.

dev.has_error() -> bool

Ein Komfort-Helfer über EVENT_FLAGS.bit3 (ERROR_OCCURRED). Liefert True, wenn bit3 gesetzt ist. Klebrig W1C; bleibt gesetzt, bis es explizit gelöscht wird (mit einem Vorbehalt — siehe den Abschnitt „Dauerhaften Fehler löschen“ oben).

dev.read_event_flags() -> int / dev.clear_event_flags(mask: int) -> None

EVENT_FLAGS (0x2A) ist ein Byte klebriger Flags; die einzelnen Bits sind in der Spezifikation beschrieben (einschließlich ERROR_OCCURRED bit3). Das Löschen erfolgt per Write-1-to-clear.

dev.clear_error() -> None

Gibt CMD_CLEAR_ERROR (Opcode 0x31) aus — setzt REG_ERROR auf null. Nötig, um einen dauerhaften Fehler zu löschen, zusammen mit clear_event_flags(1 << 3).

Mehrkanalkonfiguration (v1.3)

Bei Multi-Kanal-Modulen (I2, I3) hat jeder Stromkanal sein eigenes CT-Sensormodell. Das atomare Hilfsmittel für die Massenkonfiguration ist configure_channels().

dev.configure_channels(cls: RbAmpSensorClass, models: Sequence[int], n: int = None) -> None

Parameters:

  • cls — die Sensorklasse (RbAmpSensorClass.SCT_013 für die SCT-013-Zangen; WIRED_CT/BUILTIN_CT sind reserviert).

  • models — eine Folge von CT-Modellcodes (einer pro Kanal).

  • n — die Länge (optional; Standard = len(models)).

Intern führt die Funktion aus:

  1. set_sensor_class(cls) einmal.
  2. Für jeden Kanal: REG_CT_MODEL = models[k] vorbereiten + CMD_SET_CT_MODEL_CHk.

  3. Ein abschließendes CMD_SAVE_USER_CONFIG am Ende — das heißt ein Flash-Lösch- und Schreibzyklus für die gesamte Konfiguration.

Variantenbegrenzt: Ist len(models) größer als die Kanalzahl der Variante, werden die überzähligen Elemente ignoriert.

Raises:

  • RbAmpParamError — ungültige cls oder models[k] (clientseitige Prüfung je Klasse; REG_ERROR auf dem Gerät bleibt 0x00).

  • RbAmpIOError — Busfehler.

  • RbAmpTimeoutError — Timeout beim Flash-Schreiben.
Hinweis

Akzeptierte Codes je Klasse: SCT_013 → {1, 2, 3, 4, 5, 6, 7}; ein Code außerhalb der Menge löst RbAmpParamError bereits vor dem Bus aus. Siehe 03 · Sensorauswahl.

dev.read_ct_model_ch(ch: int) -> int

Liest das angewandte (Verify-Spiegel-)CT-Sensormodell eines bestimmten Kanals aus Register 0x51 (ch0) / 0x52 (ch1) / 0x53 (ch2). Das ist ein Rücklesen aus dem RAM, keine Bestätigung der Persistenz — für die Bestätigung des Flash-Speicherns verwenden Sie dev.reset() + ein erneutes Lesen des Spiegels.

RbAmpFleet — Verwaltung mehrerer Module

Die Klasse RbAmpFleet ist die wichtigste High-Level-Schnittstelle des Pakets in v1.3. Sie verwaltet eine Sammlung von Modulen an einem gemeinsamen I²C-Bus: Erkennung, Provisionierung, Aggregation der Abfragen, Aggregation der Fehler, synchrone Snapshots über einen General-Call-Broadcast.

Eine Flotte ist an einen Bus gebunden (meist SMBus(1) auf CPython oder I2C(0, ...) auf MicroPython). Die weiche Obergrenze der Modulanzahl ist RBAMP_FLEET_MAX_MODULES = 16.

Lebenszyklus

Python
RbAmpFleet(bus, max_modules: int = 16)

Nach del fleet werden alle übernommenen Handles freigegeben.

Erkennung — scan()

Python
fleet.scan(match_product: bool = True) -> int

Prüft den Bus im Bereich 0x08..0x77. Für jede antwortende Adresse:

  1. Prüft die Identität (PRODUCT_ID, HW_VARIANT, CAPABILITY). Ist match_product = True, ist eine Übereinstimmung mit der rbAmp-PRODUCT_ID erforderlich.

  2. Startet den Konfliktdetektor. Verdächtige Adressen wandern in die Liste excluded, nicht in die Flotte.

Gibt die Anzahl der Module zurück, die der Flotte hinzugefügt wurden.

Löst aus: RbAmpIOError, wenn der Bus blockiert ist (Tier-2-Wedge-Canary).

Modulzugriff

Python
fleet.count                              # property: number of modules in the fleet
len(fleet)                                # equivalent to fleet.count
fleet[index]                              # a module by index
fleet.find(address) -> RbAmp | None       # a module by address
fleet.add(dev: RbAmp) -> None             # adopt an existing handle
for dev in fleet:                         # iteration
    ...
fleet.excluded -> tuple[int]              # addresses that ended up in excluded

Polling — poll_all()

Python
fleet.poll_all() -> list[tuple[RbAmpSnapshot | None, RbAmpFleetPoll]]

Fragt alle Module der Flotte in einem einzigen Aufruf ab. Gibt eine Liste von Tupeln zurück; für jedes Modul:

  • ein RbAmpSnapshot oder None (bei Fehler)
  • ein RbAmpFleetPoll-POD mit den Feldern addr, ok, channels

MISS-resilient: ein stummes Modul bricht die Abfrage der übrigen nicht ab.

Aggregation

Python
fleet.total_power() -> float              # W; summed over all channels
fleet.total_energy_wh() -> float          # W·h; per-handle accumulators
fleet.poll_errors() -> dict[int, bool]    # per-addr bit3 status

total_power summiert die Wirkleistung über alle Kanäle aller Module. I-Varianten haben keine Wirkleistung → sie tragen 0 bei. Im Kanon entsprechen 80 % des Ergebnisses ungefähr der Wirkleistung des Netzmoduls.

fleet.aligned_snapshot(group=0) -> list[dict]

Flottenweiter kohärenter Periodensnapshot über alle Kanäle jedes Mitglieds: sendet einen General-Call-Snapshot per Broadcast und liest danach den mittleren Leistungs-Snapshot jedes synchronen Mitglieds für jeden Kanal (read_period_avg_p). Liefert ein Dict je Mitglied in Flottenreihenfolge mit den Schlüsseln addr, in_sync, period_valid, avg_p (Liste, ein Eintrag je Kanal; None, wenn das Mitglied den Tick verpasst oder nicht geantwortet hat). Der Snapshot gleicht nur die Periodenmittelwerte ab — Live-Messwerte (I, P, PF) lassen sich nicht über Kanäle hinweg abgleichen.

Adressierung und Konfliktprüfung

Python
fleet.assign_address(dev: RbAmp, new_addr: int) -> None
fleet.check_conflict(addr: int) -> bool   # collision detected?

assign_address adressiert ein bestehendes Flottenmodul auf eine neue Adresse um: intern — Zwei-Phasen-Commit + Reset; das Handle in der Flotte wird automatisch aktualisiert.

check_conflict ist eine Best-Effort-Prüfung nur zum Lesen für eine bestimmte Adresse. Um alle bekannten zu prüfen, iterieren Sie über die Flotte.

Bereitstellung

Native Protokoll

6.5 Provisionierung — frisches Flashen + SAVE (API-Referenz)

⚠ In der aktuellen rbamp-Version erfolgt die Provisionierung über dev.prepare_address_change() + dev.commit_address_change() auf einem von Hand erstellten Handle RbAmp(bus, 0x50), danach fleet.add(dev). Den Code-Ausschnitt finden Sie in 06 · Beispiele, Szenario 2.

MUSS: genau ein unberührtes Modul am Bus zum Zeitpunkt der Provisionierung. Zwei Module auf 0x50 gleichzeitig sind über I²C physisch nicht zu unterscheiden — sie lassen sich auch mit Spezialhardware nicht unterscheiden.

Fleet-GC-Synchronisation — synchrone Momentaufnahmen über die gesamte Flotte

Python
fleet.enable_gc_all(group: int = 0) -> int
fleet.gc_latch(group: int = 0, tick: int | None = None,
               settle_ms: int = 50) -> int
fleet.check_sync(expected_tick: int) -> list[RbAmpFleetSync]

Für eine enge Snapshot-Synchronisation (Versatz unter 1 ms über die gesamte Flotte) wird ein I²C-General-Call-Broadcast-Snapshot verwendet.

  1. enable_gc_all(group) setzt das Flag GC_ENABLE von FLEET_CONFIG + GROUP_ID auf allen Flottenmodulen und führt auf jedem CMD_SAVE_USER_CONFIG aus (dauerhaft). Nach dem Aktivieren ist ein Neustart der Module Pflicht — er erfolgt automatisch. Gibt die Anzahl der Module zurück, bei denen die Aktivierung gelang.

  2. gc_latch(group, tick, settle_ms) sendet den GC-Frame A5 27 group tick_lo tick_hi an Adresse 0x00. Ist tick=None, wird der Tick durch einen internen Zähler automatisch erhöht. Gibt den Broadcast-Tick zurück.

  3. check_sync(expected_tick) liest GC_TICK (0x59) auf jedem Modul. Liefert eine Liste von RbAmpFleetSync-PODs mit den Feldern:

Python
class RbAmpFleetSync:
    addr: int          # I²C address of the module
    gc_tick: int       # REG_GC_TICK; 0xFFFF = never received a GC
    in_sync: bool      # True if gc_tick == expected_tick
    reachable: bool    # False if the read NACKs / times out

Flottenkonfiguration je Gerät (v1.3)

Diese Methoden arbeiten direkt mit einem einzelnen Modul (ohne Flotte).

dev.enable_gc(enable: bool = True) -> None

enable_gc(True) schreibt 1 in das Flag GC_ENABLE von FLEET_CONFIG (0x27), speichert im Flash und führt einen Reset aus — das Modul nimmt GC-Snapshots nach dem Start an. enable_gc(False) löscht das Bit symmetrisch. Blockiert etwa 1 Sekunde (Einschwingzeit nach SAVE_USER_CONFIG + Einschwingzeit nach dem Reset). Idempotent: ist der aktuelle Zustand bereits der gewünschte, passiert nichts.

dev.read_fleet_config() -> int

Liest das Byte FLEET_CONFIG (0x27). Nützlich zur Kontrolle durch Rücklesen.

dev.set_group_id(group: int) -> None / dev.read_group_id() -> int

GROUP_ID (0x28) ist ein Filter für GC-Frames: Das Modul reagiert nur auf GC-Frames mit passender group_id. Standard = 0x00 (Broadcast).

dev.read_gc_tick() -> int

Liest GC_TICK (0x59) — den zuletzt empfangenen Tick-Wert aus einem GC-Frame. 0xFFFF = das Modul hat seit dem Start noch nie einen GC-Frame empfangen.

RbAmp.broadcast_latch_group(bus, group: int = 0, tick: int = 0) -> bool

Eine statische Methode. Ein Low-Level-Versand des GC-Frames A5 27 group tick_lo tick_hi direkt über bus (ohne Flotte). Nützlich, wenn noch keine Flotte angelegt wurde oder Sie den Tick-Zähler manuell steuern möchten.

RbAmp.broadcast_latch(bus) -> bool

Eine statische Methode. Ein Legacy-Wrapper — gleichwertig mit broadcast_latch_group(bus, group=0, tick=0). Für Neuentwicklung wird die explizite Form broadcast_latch_group mit eigenem Tick für die Zeugenprüfung bevorzugt.

Voraussetzung

: Die General-Call-Snapshot-Fähigkeit (CAP_GC_LATCH, gemeldet über REG_CAPABILITY) muss in der Firmware gesetzt sein und GC muss auf jedem Modul aktiviert sein (dev.enable_gc(True) oder fleet.enable_gc_all() setzt das Flag GC_ENABLE von FLEET_CONFIG; Standard AUS). Ein neues Modul mit Werkseinstellungen nimmt GC nicht an — das ist so vorgesehen, als Schutz vor einem versehentlichen Broadcast auf einem Inbetriebnahmebus. Ist GC in der gesamten Flotte deaktiviert, weist der Bus den GC-Frame auf NACK-Ebene zurück; das ist erkennbar, kein stiller Verlust. Bei einem älteren Modul ohne CAP_GC_LATCH weicht der Wrapper auf einen sequenziellen Snapshot pro Gerät aus.

Diagnose

dev.set_logger(log_callable) -> None

Eine optionale Diagnosesenke. log_callable nimmt ein einzelnes str-Argument entgegen. Wenn gesetzt, protokolliert das Paket kurz die Ergebnisse von probe(), veraltete Snapshots und abgelehnte Modi.

Typische Verwendung:

Python
import logging
log = logging.getLogger("rbamp")
log.setLevel(logging.INFO)
log.addHandler(logging.StreamHandler())
dev.set_logger(log.info)

# Or, simplest of all — a plain print:
dev.set_logger(print)

dev.sanity_reject_count: int

Ein Zähler für Gleitkommawerte, die vom Plausibilitätsfilter verworfen wurden (!isfinite(x) or |x| > 10000). Im Normalbetrieb 0. Ein Wert ungleich null nach der Wiederholungsbehandlung deutet meist auf ein seltenes I²C-Stack-Artefakt hin, das die Wiederholungsschicht überstanden hat.

Diagnosezähler von MachineI2CBackend (nur MicroPython)

MachineI2CBackend (das interne Backend auf MicroPython) stellt zwei Zähler bereit:

  • backend.retry_exhaustion_count — wie oft die Wiederholungsschleife ohne Erfolg ausgeschöpft wurde (ein RbAmpIOError wurde ausgelöst)

  • backend.retry_count_total — wie oft die Wiederholungsschleife stillschweigend erfolgreich wiederhergestellt hat

Auf diese Zähler greifen Sie über die erweiterte API zu:

Python
from rbamp._io_micropython import MachineI2CBackend
from rbamp import RbAmp

backend = MachineI2CBackend(i2c, retry_attempts=5)
dev = RbAmp(backend, 0x50)   # the address is a parameter of RbAmp, not the backend

# ...soak-test for an hour...
print("retries succeeded:", backend.retry_count_total)
print("retries exhausted:", backend.retry_exhaustion_count)
print("sanity rejects:",    dev.sanity_reject_count)

SMBusBackend (CPython) hat keine Wiederholungsschicht — der I²C-Treiber des Linux-Kernels ist vom NACK-Muster nicht betroffen.

dev.read_seq_digest() -> int

Liest das Digest-Sequenzbyte (0..255). Es ändert sich, sobald das Modul einen neuen Messwertesatz übernimmt; zwei Lesevorgänge mit demselben Wert stammen also aus demselben Commit — nützlich als Kohärenzprüfung bei gebündelter Abfrage. Es ist nur ein Änderungsmerker (keine Prüfsumme).

dev.reset_counters() -> None

Setzt alle Zähler auf null zurück (RbAmp und das Backend, falls es ein MachineI2CBackend ist). Verwenden Sie dies zu Beginn eines Dauertests.

Metadaten und Protokollkonstanten

Python
rbamp.__version__              # "1.6.0" — PEP 440 version
rbamp.__protocol_version__     # 0x04  — RBAMP_PROTOCOL_VERSION (v1.3)
rbamp.RBAMP_REG_SCHEMA_CRC32   # CRC32 of the schema codegen contract

REGISTERS und COMMANDS sind automatisch erzeugte Dicts auf Protokollebene:

Python
from rbamp import REGISTERS, COMMANDS

REGISTERS["U_RMS"]           # 0x86
REGISTERS["PERIOD_VALID"]    # 0x07
COMMANDS["LATCH_PERIOD"]     # 0x27
COMMANDS["SAVE_USER_CONFIG"] # 0x32  — user-facing persistence path
COMMANDS["SAVE_GAINS"]       # 0x26  — factory-only; BLOCKED in production
COMMANDS["FACTORY_RESET"]    # 0xAA

Wird intern im Paket verwendet. Für fortgeschrittene Anwender bereitgestellt, die rohe Übertragungen über ein eigenes Backend durchführen; gewöhnliche Anwender fassen das nicht an.

Details zum Drahtprotokoll

Für Portierung und Debugging mit einem Logikanalysator.

Registerlesezugriffe — automatisches Inkrement

Ein Burst-Lesen + N bytes liefert N aufeinanderfolgende Bytes ab addr. Unter CPython über bus.read_i2c_block_data(addr, start_reg, N) — eine einzige Transaktion.

Registerschreibvorgänge — Byte für Byte (NICHT automatisch erhöht)

⚠ Schreibvorgänge werden NICHT automatisch hochgezählt. Ein Burst-Schreibvorgang + N bytes landet nur im ersten Byte.

Ein mehrbyteiges Register wird Byte für Byte geschrieben:

Python
# WRONG — data loss
label = b"MyMeter1"
bus.write_i2c_block_data(0x50, 0x68, list(label))   # only 'M' lands

# CORRECT — byte-at-a-time loop
for i, byte in enumerate(label):
    bus.write_byte_data(0x50, 0x68 + i, byte)

Betrifft die beschreibbaren Mehrbyte-Register: LABEL (0x68–0x6F), U_GAIN/I_GAIN (f32, werksseitig gesperrt), NF (u16), THRESH (u16). Lesevorgänge — Burst ist zulässig.

Ausnahme: der GC-Broadcast-Frame (5 Byte an Adresse 0x00) ist ein eigener Drahtprotokoll-Pfad (General-Call-Empfang) und wird als einzelne I²C-Transaktion gesendet.

Variantenerkennung

Das maßgebliche SKU-Byte ist REG_HW_VARIANT (0x55) (dev.hw_variant):

Wert SKU
0x01 UI1
0x02 UI2
0x03 UI3
0x04 I1
0x05 I2
0x06 I3

General-Call-Broadcast-Snapshot

Pro Modul aktivierbar über das Flag GC_ENABLE von REG_FLEET_CONFIG. Standardmäßig AUS. Aktiviert über CMD_SAVE_USER_CONFIG + CMD_RESET. Nach dem Reset hört das Modul auf den Broadcast-Frame an Adresse 0x00:

Text
addr=0x00 | A5 27   
  • A5 — Magic; 27 — der Opcode CMD_LATCH_PERIOD.
  • — 0x00 = alle (All-Call), sonst muss er mit REG_GROUP_ID (0x28) übereinstimmen.
  • — ein 16-Bit-Periodenzähler.

Erkennung von Fehlerzuständen (2-stufig, C.10 hardwarebestätigt):

  1. GC-Adressen-NACK: Ist GC in der ganzen Flotte deaktiviert, löst bus.write_i2c_block_data(0x00, ...) OSError aus (oder das Backend-Äquivalent). Das ist ein harter Fehler, kein stiller Verlust.
  2. Zeuge je Modul: Ist kein NACK aufgetreten, lesen Sie REG_PERIOD_VALID (0x07) auf jedem Modul. 1 = Snapshot erfolgreich; 0 = GC auf diesem Modul deaktiviert oder die Periode ist leer.

Fehlermodell (v1.3)

  • REG_ERROR (0x02) — Ergebnis des letzten Schreibvorgangs, NICHT klebrig. Lesen Sie es DIREKT NACH der Operation.
  • EVENT_FLAGS (0x2A) bit3 — dauerhaftes Signal (klebrig, W1C). Kanonische Fehlererkennung über bit3.
Python
# Canonical durable monitoring
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

Referenzen


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