11 · Änderungsprotokoll
Diese Seite spiegelt CHANGELOG.md aus dem Repository.
1.6.1 — 2026-11-01
Die Periodenmessung funktioniert jetzt auf STD-Modulen mit denselben Aufrufen wie auf BASIC. Die Latch-Bank-Aufrufe sind hinzugekommen, und BASIC-only-Aufrufe werden auf STD-Modulen sauber abgewiesen.
Hinzugefügt
- Periodenmessung an STD-Modulen (
read_period_snapshot,read_period_avg_power/read_period_avg_p,read_period_max_power,is_period_valid,latch_period,dev.energy). Die Quelle wird einmal beibegin()festgelegt: Ein Modul mit Gerätezählern verwendet die Differenz zweier Zählerwerte im Takt des Masters (es wird kein Latch-Befehl gesendet); ein Modul nur mit Latch-Bänken latcht Bank 0 (Latch zu Latch, mindestens 300 ms Einschwingzeit); ein Modul ohne beides löstRbAmpNotSupportedErroraus. Ein Wechsel der Zählergeneration oder eine Bank, die nach einem Modul-Reset ihre Armierung verloren hat, wird neu verankert, und diese Periode wird übersprungen (RbAmpStaleError). Der Periodensnapshot erhältavg_p_total,wh_netundmodule_restarted. Eine zählerbasierte Periode hat keine Spitzenleistung, und ein Mittelwert pro Kanal gibt es nur bei einem Einkanalmodul. - Latch-Bank-Aufrufe, verfügbar, wenn das Modul Bänke meldet:
dev.std_arm_banks(mask),dev.std_latch(bank),dev.std_read_latch(bank)(einRbAmpStdLatch: P/Q/S, Spitzen, Energie in mW·Samples, Energie und Mittelwert je Kanal) sowieRbAmp.std_latch_wh(snap, dt_ms, ch). Das Gültigkeitsflag einer Bank ist klebrig und kein Frischeindikator: Lesen Sie eine Bank frühestens 300 ms nach dem Latchen. - Sensormodelle 11 (50 A) und 13 (100 A) der Zangenklasse sind charakterisiert, mit Nenn-, Endwert- und Spitzengrenzen. Modell 12 (80 A) ist unverändert.
Fest
- Aufrufe, die nur in der BASIC-Registerkarte existieren (Sensorklasse-/CT-Modell-Konfiguration, Reset und Adressänderung, Identitätsregister, Fehler- und Ereigniskanal, Flotten- und General-Call-Helfer,
read_period_latch_ms,wait_ready) lösen auf einem STD-Modul jetztRbAmpNotSupportedErroraus, statt die falsche Adresse zu lesen oder zu schreiben. set_ct_model_ch_force()auf einem werkseitig gepaarten Modul meldetRbAmpModeError(„factory-paired module: configuration locked“), wenn die Firmware den Schreibvorgang verweigert. Der Force-Pfad funktioniert nur im Werksmodus.
1.6.0 — 2026-10-22
Öffentliche Veröffentlichungen werden mit dieser Version fortgesetzt; Zwischenversionen (1.4.x, 1.5.x) wurden nur intern veröffentlicht.
Ergänzt die STD-Modulreihe (16-Bit-Registerabbild) neben den bestehenden Modulen, Periodenenergie pro Kanal bei 5/7-Kanal-Modulen und eine SCT-013-Nennwertkorrektur. Eine RbAmp-Klasse bedient beide Modulreihen; der Modultyp wird bei begin() automatisch erkannt.
Hinzugefügt
- SCT-013-060 und -100 werden akzeptiert (sie wurden clientseitig als reserviert abgelehnt); die Grenzwerte der Sensormodelle wurden auf gemessene Werte aktualisiert.
- STD-Modulreihe (16-Bit-Karte), automatisch erkannt. Die gängigen Leser (
voltage,current,power,power_factor,frequency) funktionieren bei jedem Modul; STD-only-Aufrufe lösenRbAmpNotSupportedErrorauf einem Modul aus, das sie nicht bereitstellt. - Energie auf dem Gerät:
dev.read_std_energy()(Wirkenergie Bezug/Einspeisung/netto + Blindenergie, Wh/mWh/µWh, pro Kanal);RbAmp.std_energy_delta(prev, now)(stromausfallsicher). - Mehrphasig:
dev.read_voltage_angle(phase),dev.read_phase_sequence(),dev.read_reactive(ch),dev.read_apparent(ch). - Anlaufstrom:
dev.get_start_current()/dev.set_start_current(µA)+dev.save_config(). dev.read_std_voltage/channel/totals/config/health(),dev.set_time(),dev.is_std; WertobjekteRbAmpStdEnergy/Voltage/Channel/Config/Health;RbAmpNotSupportedError.- Auf CPython (
smbus2) validiert; der 16-Bit-Pfad für MicroPython ist implementiert, aber noch nicht an Hardware validiert. - Periodenenergie je Kanal bei 5-/7-Kanal-Modulen:
dev.read_period_avg_power(ch)löst jeden Kanal auf; der Periodensnapshot und der Wh-Akkumulator decken alle Kanäle ab. - SCT-013-Nennwert-Umschaltkorrektur: Wird ein Kanal auf ein anderes Sensormodell umgestellt, werden Strom, Leistung und Energie auf das gewählte Modell bezogen korrigiert, relativ zur Verstärkung, die das Modul anwendet; Leistungsfaktor und Spannung bleiben unverändert. Automatisch;
dev.set_rating_correction(),dev.ct_rating_scale(ch),dev.ct_rating_status(ch). Firmware, die das selbst erledigt, wird erkannt und unverändert gelassen. - Read-before-write-Schutz bei Schreibvorgängen für Sensorklasse / CT-Modell;
dev.set_ct_model_ch_force(),dev.read_sensor_class().
Fest
- Der Periodensnapshot bei 5/7-Kanal-Modulen meldete keinen Fehler mehr für Kanäle jenseits des dritten.
1.5.0 — 2026-09-04
Kanalweise CT-Modellzuordnung für alle Kanäle, Unterstützung für Oberklasse-SKUs (UI5/UI7), Sensormodell-Register und Persistenz-Fix. Firmware: v1.4.18+.
Hinzugefügt
-
UI5- / UI7-Unterstützung (Oberklasse-SKUs): automatisch erkannt über
REG_TOPOLOGY+REG_HW_VARIANT;dev.channelsliefert 5 oder 7; alle Live- und Periodenleser arbeiten einheitlich fürch 0..channels-1. -
CT-Modell pro Kanal, beliebiger Kanal:
dev.set_ct_model_ch(channel, code)unddev.read_ct_model_ch(channel)akzeptieren nunchannel 0..channels-1. Kanäle 0–2 nutzen den flachen Registerpfad; Kanäle 3 und höher nutzen das Kanalzugriffsfenster (Feld 15). -
Modellvalidierung aus der Registry: Die Modell-Registry ist jetzt die einzige Quelle für CT-Modellcodes. Automatisch erzeugt in
rbamp/_sensor_models.py; das früher von Hand gepflegte Wörterbuch_CT_ACCEPTEDist entfallen. -
RbAmpWindowField.CT_MODEL = 15(öffentliche Enum). RbAmpFleet.aligned_snapshot()füllt die Listen pro Kanal für die gesamte Kanalbreite des Moduls.
Fest
- CT-Modell / Sensorklasse bleiben im Produktivbetrieb erhalten. Frühere Versionen speicherten diese über
CMD_SAVE_GAINS, was werkseitig gesperrt ist — auf einem Produktionsmodul war das Speichern ein stiller No-op, sodass die Bindung nur im RAM angewendet, beim Neustart aber verloren wurde. Jetzt wird überCMD_SAVE_USER_CONFIGgespeichert (nicht gesperrt). Anwender früherer Versionen haben im Produktivbetrieb die CT-Modellbindung bei jedem Neustart stillschweigend verloren — aktualisieren Sie, bevor Sie Geräte ausliefern.
1.4.0 — 2026-08-19
Unterstützung für Senior-SKUs (UI5/UI7), RT-Kennzahlen für Senior-Kanäle, flottenweit abgeglichene Snapshots für Module mit mehreren Kanälen.
1.3.1 — 2026-07-30
Geändert
- Die Multimodul-Beispiele (
examples_cpython/03_multi_module_broadcast.py,examples_upy/03_multi_module.py) sowie die Beispiele zur Energiebilanz des ganzen Hauses (examples_cpython/07_home_energy_balance.py,examples_upy/08_home_energy_balance.py) wurden auf den kohärenten General-Call-Latch von v1.3 (CAP_GC_LATCH) umgestellt:RbAmpFleet.enable_gc_all()→gc_latch()→check_sync(), anstelle des sequenziellen Latchings pro Gerät vor v1.3. Das Beispiel zur Energiebilanz des ganzen Hauses veröffentlicht nun außerdem ein MQTT-Topichome/energy/sync/in_sync. Nur Beispiel-Patch — die Bibliotheks-API bleibt unverändert.
1.3.0 — Flotte + Protokoll v1.3
Das Python-Paket rbamp wurde an den Drahtvertrag von rbAmp v1.3 und das plattformübergreifende Referenzmodell (Arduino / ESP-IDF / ESPHome / STM32 HAL) angepasst. Mock-Testsuite: 179/179 bestanden.
Hinzugefügt
-
RbAmpFleet— Verwaltung mehrerer Module auf Host-Seite:scan()(mit Konflikterkennung + Tier-2-Wedge-Canary),add(),find(),count, Iteration; gebündeltespoll_all()(fehlerisoliert, MISS-robust); flottenweittotal_power()/total_energy_wh()/poll_errors(); General-Call-Synchronisierung (enable_gc_all()/gc_latch()/check_sync());assign_address()/check_conflict(). Weiche ObergrenzeRBAMP_FLEET_MAX_MODULES = 16. -
POD-Strukturen:
RbAmpFleetPoll(Abfrageergebnis je Mitglied),RbAmpFleetSync(GC-Synchronisierungszeuge je Mitglied). -
Identität / Fähigkeit:
read_variant()(Byte HW_VARIANT 0x55, 1..6 = UI1/UI2/UI3/I1/I2/I3),read_capability()(u16 LE-Merkmalsbitmap; nach Bits verzweigen, nicht nach Versionsheuristik),read_product_id()(0x01 = rbAmp-Sensorfamilie),read_uid()(12 Byte),read_label()/set_label()(8-Byte-ASCII über schrittweisen Byte-Schreibvorgang). -
Ereignis-/Fehlerkanal (Zwei-Kanal-Modell v1.3):
read_last_error()(Byte REG_ERROR des Geräts, ein Lesezugriff auf den Draht),read_event_flags(),clear_event_flags(mask),has_error()(Hilfsfunktion für das klebrige bit3),clear_error()(CMD_CLEAR_ERROR). -
Kanalweise CT-Konfiguration:
configure_channels(class, models, n)(gebündelt, ein abschließendes Flash-SAVE; auf die Variante begrenzt; clientseitige Validierung je Klasse_validate_ct_code);read_ct_model_ch(ch)(Rücklesen des Spiegels des angewandten Modells von 0x51–0x53). -
Primitive pro Gerät für die Flotte:
enable_gc(enable=True)(Lese-Modifiziere-Schreibe des Flags GC_ENABLE von FLEET_CONFIG + Speichern + Reset; ~1 s blockierend; idempotent, wirkungslos wenn bereits korrekt),read_fleet_config(),set_group_id()/read_group_id(),read_gc_tick()(u16-Zeuge; 0xFFFF = nie empfangen),RbAmp.broadcast_latch_group(bus, group, tick)statisch (5-Byte-GC-FrameA5 27 g tl th). -
Ausnahmehierarchie: Basis
RbAmpError+RbAmpIOError,RbAmpTimeoutError,RbAmpStaleError,RbAmpParamError,RbAmpModeError,RbAmpVersionError.
Geändert
-
Energie wird gegen die Wanduhr des Masters integriert, niemals gegen das diagnostische
latch_msdes Moduls (ein diagnostischer Timer, nicht für Energie). Auf CPython verwenden Sietime.monotonic(); auf MicroPythontime.ticks_ms()+time.ticks_diff(). Bei einem veralteten Lesewert (PERIOD_VALID = 0) löst die BibliothekRbAmpStaleErroraus und setzt den Anker NICHT zurück; der nächste gültige Snapshot deckt das volle Intervall ab, und die Firmware erhält den Akkumulator — die Integration bleibt exakt, ohne Doppel- oder Unterzählung. -
CT-Modellcodes sind je Klasse eine akzeptierte Menge (
SCT_013 {1,2,3,4,5,6,7},WIRED_CT {1,2,3},BUILTIN_CT ∅); ein Code außerhalb der Klassenmenge führt dazu, dass die BibliothekRbAmpParamErrorvor jedem I²C-Vorgang auslöst.REG_CT_MODEList reines Staging: die Bindung erfolgt über einen kanalweisen Befehl, und Mehrkanal-Bindungen sind auf Firmware v1.3 reihenfolgeunabhängig (bei älterem v1.x bleibt das defensive absteigende Muster im Zyklusset_ct_model_cherhalten). -
Adressänderung ist ein im Produktivbetrieb zulässiger Zwei-Phasen-Magic-Commit; der Fabrikmodus ist nicht erforderlich.
prepare_address_change()armiert den Kandidaten + das Magic-Fenster0xA5von 5 Sekunden;commit_address_change()sendetCMD_COMMIT_ADDR+ Reset. Die Bibliothek stellt über try/finally sicher, dass der Armierungszustand bei einem Teilfehler gelöscht wird; ein abgelaufenes Zeitfenster →RbAmpTimeoutError. Kompatibel mit älterer v1.x-Firmware über einen fähigkeitsgesteuerten Rückfall. -
Erkennung der Variante —
read_variant()liestREG_HW_VARIANT(das kanonische SKU-Byte von v1.3). Der NACK-Probe-Pfad wurde entfernt (die Firmware sendet bei Lesevorgängen nie ein NACK; nicht zugeordnete Lesevorgänge liefern0x00). -
Mehrbyte-WRITE Byte für Byte. Die
set_label()der Bibliothek schreibt die 8 LABEL-Bytes automatisch in einer Byte-Schleife (rbAmp führt bei Schreibvorgängen kein Auto-Increment aus).
Robustheit am Prüfstand (Stufe 1B)
-
CPython
SMBusBackendstellt eine generische NACK-Wiederholung (retry_attempts=3,retry_gap_ms=2) bereit, mit den Diagnosewertenretry_count_total+retry_exhaustion_count. Sie wird bei allen Bus-Operationen verwendet (Konfigurationsschreibvorgänge folgen derselben Disziplin wie Lesevorgänge — andernfalls wäre ein Konfigurationsschreiben, das auf einem umkämpften Bus still verworfen wird, unsichtbar). -
MicroPython auf ESP32
MachineI2CBackendbehält das Spin-Discipline des IDF-i2c_master mit 50 kHz bei (NACK-Wiederholung mit knappem Warten zwischen den Versuchen, damit ein umkämpfter Bus einen Schreibvorgang nicht still verwirft). Siehe 09 · API-Referenz → „Details zum Drahtprotokoll“ für den vollständigen Vertrag.
Hinweise
- Marginaler Bus / ESP32-basierte Hosts: derselbe IDF-i2c_master-Treiber wie in nativen ESP-IDF-Projekten — er kann auf einem gehaltenen Bus unterhalb der Bibliotheksebene hängen. Wir empfehlen externe 4.7-kΩ-Pull-ups, keinen Debugger-NRST im Produktivbetrieb und einen Anwendungs-Task-Watchdog auf dem Abfrage-Task als Wiederherstellungsstrategie. Siehe Kapitel 10 · Fehlerbehebung.
1.1.0 — erweiterter Periodensnapshot
Erweiterter Periodensnapshot (maximale P, Diagnose latch_ms), Wh-Buchhaltung auf Masterseite.
1.0.0 — Erstveröffentlichung
Einzelgeräte-Echtzeitmessung (Effektiv-U / I / P / PF / Frequenz), Integration der Periodenenergie (Wh), Konfiguration von CT-Modell und Sensorklasse sowie Adressänderung über I²C. Zwei Backends (CPython smbus2 / MicroPython machine.I2C).
Quelle & Probleme: rb-amp/rbamp-python · diese Seite im Repository: docs/11_changelog.md (v1.6.1)