09 · API-Referenz
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
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:
from rbamp import RbAmp, RbAmpSensorClass, RbAmpError
Allgemeine Muster
Die API folgt den üblichen Python-Mustern:
-
Eine Klasse für jede Modulreihe: Dieselbe Klasse
RbAmpbedient BASIC- und STANDARD-Module (STD). Die Reihe wird inbegin()automatisch erkannt (siehe STD-Modulreihe); Sie wählen sie nie selbst. -
Klassenbasiert: die Hauptklasse
RbAmpverwaltet 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 automatischdev.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-Mustertry / except(nichtlast_error()+ ein Rückgabecode). -
Asynchroner Generator für periodisches Streaming:
async for snap in dev.stream_period(interval_s=...).
Typen
RbAmp
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.
: 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:
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
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)
: 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.
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.
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
Für die Energieintegration verwenden Sie master_dt_ms, nicht latch_ms — latch_ms ist ein Diagnose-Timer des Moduls.
Topologiekonstanten
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()
02 · Initialisierung und Start (initialization) · BASIC oder STD? (initialization) · Dauerabfragezyklus (empfohlen) (period-metering)
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:
-
Liest
REG_VERSION— löstRbAmpIOErrorbei NACK aus,RbAmpVersionError, wenn0x00/0xFFzurückgegeben wird. -
Speichert die Topologie zwischen (bei der aktuellen Firmware führt
begin()keine automatische Abfrage durch; es verwendet den Hinweis aus dem Konstruktor). -
Liest
U_rms, um festzustellen, ob ein Spannungssensor vorhanden ist (Schwelle 1.0 V). -
Schreibt
CMD_LATCH_PERIOD(Primer) und wartet 50 ms. Der erste Snapshot nach dem Einschalten wird verworfen. -
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
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
02 · Initialisierung und Start (Initialisierung) · 3. DATA_VALID (0xCE) wird nie 1 (Fehlersuche) · 4 · Registerkarte (Produktion v1.3) (API-Referenz)
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
BASIC oder STD? (initialization) · Mehrkanal-Strom (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.10 V03-Echtzeitblock (0x86..0xBD) (api-reference)
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.
Eigenschaften
Mehrkanaliger Strom (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.14 Kanalzugriffsfenster (0x32 + 0x3C..0x3F) (api-reference)
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:
dev.current # _ChannelProxy → dev.current[0], dev.current[1], ...
dev.current_peak # _ChannelProxy
dev.power # _ChannelProxy
dev.power_factor # _ChannelProxy
Usage:
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)
RT-Registerreferenz (realtime-polling) · Bilanzierung in beide Richtungen (period-metering)
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
RT-Registerreferenz (realtime-polling) · Abfrage — einzelnes Modul (realtime-polling) · 4.10 V03-Echtzeitblock (0x86..0xBD) (api-reference)
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)
⚠️ 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
RbAmpNotSupportedErroraus. -
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
RbAmpNotSupportedErroraus („nicht verfügbar“). -
Die Periodenaufrufe (
latch_period,read_period_*,stream_period) und der Akkumulatordev.energyfunktionieren auf einem STD-Modul — siehe „Periodenbilanzierung“ unten. Die eigenen Lebenszeitsummen des Moduls liefertread_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_msundwait_readysind nur für BASIC: auf einem STD-Modul lösen sieRbAmpNotSupportedErroraus, bevor etwas auf den Bus gesendet wird.
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
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).validistFalsebei 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östRbAmpNotSupportedErrorauf 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 sieRbAmpNotSupportedErroraus (auf BASIC ist Blindleistung über diese Bibliothek nicht verfügbar). -
read_std_totals(k)— Summenblockk;k=0ist 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_restartedistTrue, wennnow.uptime_s < prev.uptime_s.-
deltaist einRbAmpStdEnergymit dem Zuwachs je Feld, oderNone, wenn sich der Zählergenerationgeä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;
netist immer Import − Export der begrenzten Teile. -
Einträge pro Kanal werden nur ausgefüllt, wenn beide Snapshots dieselbe Kanalzahl haben.
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
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 Siesave_config()auf, um ihn über einen Neustart hinweg zu behalten. Ein nicht unterstützter Wert löstRbAmpParamErroraus, bevor etwas auf den Bus geschrieben wird. Der Wert muss0(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östRbAmpParamErroraus. Setzen Sie die Zeit nach jedem Neustart des Moduls erneut (read_std_health().time_validistFalse, bis die Uhr gesetzt ist). -
get_start_current()/set_start_current()lösenRbAmpNotSupportedErroraus, wenn das Modul-Image die Anlaufstrom-Einstellung nicht bereitstellt;RbAmpStdConfig.start_ua_supportedzeigt, 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.
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) nachstd_latch(). Eine Bank, die nie gelatcht wurde, löstRbAmpStaleErroraus. 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östRbAmpStaleErroraus: 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 überdt_msder Uhr des Masters in Wh um.chist ein Kanalindex oder0xFF(Standard) für die Modulsumme. Liefert(wh_import, wh_export); Export ist null oder negativ. LöstRbAmpStaleErrorfür einen Snapshot ohne Samples aus.
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
04 · Periodenmessung und Tarifabrechnung (Periodenmessung) · Kalibrierung und Genauigkeit (Fehlerbehebung)
Liest das Bit „Snapshot bereit“. Gibt True zurück, wenn der letzte Snapshot frisch ist.
dev.read_period_avg_power(ch=0) -> float
Register der Periodenmomentaufnahme (period-metering) · 4.11 V03-Periodenblock (0xBE..0xCF) (api-reference) · 4.12 V03 Q + Periode ch0 (0xD0..0xE3, Produktionsbuild) (api-reference)
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
Register der Periodenmomentaufnahme (period-metering) · 4.12 V03 Q + Periode ch0 (0xD0..0xE3, Produktionsbuild) (api-reference)
Spitzen-Momentanleistung auf Kanal 0 über die abgeschlossene Periode. ch=0 nur bei Firmware v1.
dev.read_period_latch_ms() -> int
13. Takt-Drift mehrerer Module bei langen Tests (troubleshooting) · 4.13 Diagnose-dt auf Chipseite (0xEC) (api-reference)
Periodendauer aus Sicht des Geräts, in ms.
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
Kontinuierlicher Abfragezyklus (empfohlen) (period-metering) · Kalibrierung und Genauigkeit (troubleshooting) · 4.11 V03-Periodenblock (0xBE..0xCF) (api-reference)
Der empfohlene Einstiegspunkt für die Periodenbuchhaltung. Die vollständige Abfolge im Hintergrund:
-
Bei
skip_latch=True— den Snapshot-Befehl überspringen (für das Multi-Modul-Muster nach einer manuellen Reihe von Snapshot-Befehlen). -
Andernfalls —
CMD_LATCH_PERIODschreiben. - Erfassen Sie
time.monotonic(), ummaster_dt_mszu berechnen. time.sleep(settle_ms / 1000)— standardmäßig 50 ms.-
Prüfen Sie das Bereitschaftsflag des Snapshots. Ist es 0, lösen Sie
RbAmpStaleErroraus (der vorherige Zeitstempel bleibt erhalten, damit der nächste erfolgreiche Snapshot das volle Intervall abdeckt und Wh exakt bleibt). -
Lesen Sie
avg_p[0..channels-1]+max_p+latch_ms. - Zeitstempel aktualisieren und
energy.tick(snap)aufrufen, um Wh zu integrieren (sofern der Akkumulator nicht überenergy.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).
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 |
⚠ 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:
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
Algorithmus auf der Masterseite (Periodenmessung) · 7 · Semantik (API-Referenz)
Ein Wh-Akkumulator je Kanal. Der Zugriff erfolgt über eine Eigenschaft — das Paket besitzt die Instanz:
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:
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
Sensorklasse und CT-Modell setzen (Initialisierung) · 4.3 System (0x20..0x25) (API-Referenz) · 6.2 CT-Modell-Zuordnung — reine Vorbereitung + CMD je Kanal (API-Referenz)
Setzt die Sensorklasse des Stromsensors und speichert sie im Flash. Blockierend, ~705 ms.
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—clsaußerhalb von 0..3-
RbAmpModeError— das Modul ist werkseitig gepaart (aktuelle KlasseWIRED_CT/BUILTIN_CT) undclsweicht 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 |
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 auchRbAmpParamError) —codeist nicht in der Akzeptanzmenge der Klasse für das aktuelleREG_SENSOR_CLASSenthalten (fürSCT_013ist das{1, 2, 3, 4, 5, 6, 7})-
RbAmpModeError— wennset_sensor_class()nicht aufgerufen wurde oder das Modul werkseitig gepaart ist (Klasse 2/3) und der Code abweicht (im Servicekontextset_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):
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
Festlegen von Sensorklasse und CT-Modell (initialization) · 6.2 CT-Modell-Bindung — reine Vorbereitung + CMD je Kanal (api-reference)
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.
✅ 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.
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—channelaußerhalb von 0..dev.channels-1odercodenicht in der zulässigen Menge der Klasse (fürSCT_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:
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_powersowie daraus der Periodensnapshot unddev.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.
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 oderNone, wenn der Kanal nie ausgewertet wurde (zum Beispiel kein SCT-Kanal).actionist einer von"unity","ok","needs_reset","warn_uncal","warn_gain";detailist Text. Diewarn_*-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.
⛔ 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
Adressänderung (Initialisierung) · 4.5 Adresse (0x30..0x31) (API-Referenz) · 6.1 Adressänderung — zweiphasiger Commit (produktionstauglich) (API-Referenz)
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_addraußerhalb von 0x08..0x77 oder gleich der aktuellen Adresse -
RbAmpIOError— Kommunikationsfehler
dev.commit_address_change() -> None
Adressänderung (Initialisierung) · 4.5 Adresse (0x30..0x31) (API-Referenz) · 6.1 Adressänderung — zweiphasiger Commit (produktionstauglich) (API-Referenz)
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.
⚠ 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:
⚠ 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 abgelaufenRbAmpIOError— Kommunikationsfehler
dev.factory_reset() -> None
Der Befehl CMD_FACTORY_RESET + 1500 ms Wartezeit.
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
Automatische Erkennung der Modulvariante (initialization) · rbAmp-Drahtprotokoll-Referenz (v1.3) (api-reference) · 3.6 Kanonischer Erkennungsalgorithmus (api-reference)
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
Automatische Erkennung der Modulvariante (Initialisierung) · 3.2 CAPABILITY (Register 0x57/0x58, u16 LE, nur lesbar) (API-Referenz) · 8 · Beispiele für Drahtprotokoll-Mitschnitte (API-Referenz)
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
3.5 PRODUCT_ID (0x54, u8, nur lesbar) (api-reference) · 4.8 Identität (0x54..0x6F) (api-reference)
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
8.3 Mehrbyte-SCHREIBZUGRIFF — LABEL Byte für Byte (api-reference)
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
8.3 Mehrbyte-SCHREIBZUGRIFF — LABEL Byte für Byte (api-reference)
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.
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
6.5 Provisionierung — frisches Flashen + SAVE (API-Referenz) · 8.6 Provisionierung nach frischem Flashen (API-Referenz)
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.
: 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:
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 Beispiel0xFE = 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 vonEVENT_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.
⚠ 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:
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
3. DATA_VALID (0xCE) wird nie 1 (troubleshooting) · Fehlercodes (REG_ERROR = 0x02) (troubleshooting) · 4 · Registerkarte (Produktion v1.3) (api-reference)
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
4.4 Fleet-Konfiguration (0x27..0x2F) (api-reference) · 8.8 Ablauf von Schwellwertereignissen — Schwellwert schreiben → auslösen → W1C-Löschen (api-reference)
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
Fehlercodes (REG_ERROR = 0x02) (troubleshooting) · 6.7 Wiederherstellung nach Fehlerzustand — Entscheidungsbaum (api-reference)
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_013für die SCT-013-Zangen;WIRED_CT/BUILTIN_CTsind reserviert). -
models— eine Folge von CT-Modellcodes (einer pro Kanal). n— die Länge (optional; Standard =len(models)).
Intern führt die Funktion aus:
set_sensor_class(cls)einmal.-
Für jeden Kanal:
REG_CT_MODEL = models[k]vorbereiten +CMD_SET_CT_MODEL_CHk. -
Ein abschließendes
CMD_SAVE_USER_CONFIGam 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ültigeclsodermodels[k](clientseitige Prüfung je Klasse;REG_ERRORauf dem Gerät bleibt0x00). -
RbAmpIOError— Busfehler. RbAmpTimeoutError— Timeout beim Flash-Schreiben.
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
4.7 CT-Modell-Verifikationsspiegel (0x51..0x53) (API-Referenz) · 8.10 Rücklesen des CT-Modell-Verifikationsspiegels (Plausibilität nach der Zuordnung) (API-Referenz)
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
RbAmpFleet(bus, max_modules: int = 16)
Nach del fleet werden alle übernommenen Handles freigegeben.
Erkennung — scan()
Einrichtung mehrerer Module (initialization) · Abfrage mehrerer Module — drei Strategien (realtime-polling) · Probleme mit mehreren Modulen (troubleshooting)
fleet.scan(match_product: bool = True) -> int
Prüft den Bus im Bereich 0x08..0x77. Für jede antwortende Adresse:
-
Prüft die Identität (
PRODUCT_ID,HW_VARIANT,CAPABILITY). Istmatch_product = True, ist eine Übereinstimmung mit der rbAmp-PRODUCT_ID erforderlich. -
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
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()
Einrichtung mehrerer Module (initialization) · Abfrage mehrerer Module — drei Strategien (realtime-polling)
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
RbAmpSnapshotoderNone(bei Fehler) - ein
RbAmpFleetPoll-POD mit den Feldernaddr,ok,channels
MISS-resilient: ein stummes Modul bricht die Abfrage der übrigen nicht ab.
Aggregation
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
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
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
General Call (Broadcast an Adresse 0x00) (initialization) · Mehrere Module — gleichzeitige Momentaufnahme (period-metering) · 6.3 GC-Broadcast-Momentaufnahme — optionale Flottensynchronisation (api-reference)
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.
-
enable_gc_all(group)setzt das FlagGC_ENABLEvon FLEET_CONFIG +GROUP_IDauf allen Flottenmodulen und führt auf jedemCMD_SAVE_USER_CONFIGaus (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. -
gc_latch(group, tick, settle_ms)sendet den GC-FrameA5 27 group tick_lo tick_hian Adresse0x00. Isttick=None, wird der Tick durch einen internen Zähler automatisch erhöht. Gibt den Broadcast-Tick zurück. -
check_sync(expected_tick)liestGC_TICK (0x59)auf jedem Modul. Liefert eine Liste vonRbAmpFleetSync-PODs mit den Feldern:
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
General Call (Broadcast an Adresse 0x00) (Initialisierung) · 4.4 Flottenkonfiguration (0x27..0x2F) (API-Referenz)
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.
: 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:
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 (einRbAmpIOErrorwurde 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:
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
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:
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 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 landet nur im ersten Byte.
Ein mehrbyteiges Register wird Byte für Byte geschrieben:
# 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:
addr=0x00 | A5 27
A5— Magic;27— der OpcodeCMD_LATCH_PERIOD.—0x00= alle (All-Call), sonst muss er mitREG_GROUP_ID (0x28)übereinstimmen.— ein 16-Bit-Periodenzähler.
Erkennung von Fehlerzuständen (2-stufig, C.10 hardwarebestätigt):
- GC-Adressen-NACK: Ist GC in der ganzen Flotte deaktiviert, löst
bus.write_i2c_block_data(0x00, ...)OSErroraus (oder das Backend-Äquivalent). Das ist ein harter Fehler, kein stiller Verlust. - 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.
# 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
- 05 · Schnellstart — Ihr erstes funktionierendes Skript
- 06 · Beispiele — funktionierende Szenarien
-
10 · Fehlerbehebung — Fehlercodes entschlüsseln und gängige Probleme beheben
-
Quelle:
__init__.py,_rbamp_core.py,_snapshot.py,_energy.py,_io_micropython.py,_io_smbus.py
Quelle & Probleme: rb-amp/rbamp-python · diese Seite im Repository: docs/09_api_reference.md (v1.6.1)