rbAmp
DE
Shop
Docs
Aktualisiert · Auf GitHub bearbeiten (Edit on GitHub)

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 bei begin() 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öst RbAmpNotSupportedError aus. 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ält avg_p_total, wh_net und module_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) (ein RbAmpStdLatch: P/Q/S, Spitzen, Energie in mW·Samples, Energie und Mittelwert je Kanal) sowie RbAmp.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 jetzt RbAmpNotSupportedError aus, statt die falsche Adresse zu lesen oder zu schreiben.
  • set_ct_model_ch_force() auf einem werkseitig gepaarten Modul meldet RbAmpModeError („factory-paired module: configuration locked“), wenn die Firmware den Schreibvorgang verweigert. Der Force-Pfad funktioniert nur im Werksmodus.

1.6.0 — 2026-10-22

Hinweis

Ö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ösen RbAmpNotSupportedError auf 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; Wertobjekte RbAmpStdEnergy/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.channels liefert 5 oder 7; alle Live- und Periodenleser arbeiten einheitlich für ch 0..channels-1.

  • CT-Modell pro Kanal, beliebiger Kanal: dev.set_ct_model_ch(channel, code) und dev.read_ct_model_ch(channel) akzeptieren nun channel 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_ACCEPTED ist 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 über CMD_SAVE_USER_CONFIG gespeichert (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-Topic home/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ündeltes poll_all() (fehlerisoliert, MISS-robust); flottenweit total_power() / total_energy_wh() / poll_errors(); General-Call-Synchronisierung (enable_gc_all() / gc_latch() / check_sync()); assign_address() / check_conflict(). Weiche Obergrenze RBAMP_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-Frame A5 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_ms des Moduls (ein diagnostischer Timer, nicht für Energie). Auf CPython verwenden Sie time.monotonic(); auf MicroPython time.ticks_ms() + time.ticks_diff(). Bei einem veralteten Lesewert (PERIOD_VALID = 0) löst die Bibliothek RbAmpStaleError aus 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 Bibliothek RbAmpParamError vor jedem I²C-Vorgang auslöst. REG_CT_MODEL ist 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 Zyklus set_ct_model_ch erhalten).

  • 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-Fenster 0xA5 von 5 Sekunden; commit_address_change() sendet CMD_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() liest REG_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 liefern 0x00).

  • 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 SMBusBackend stellt eine generische NACK-Wiederholung (retry_attempts=3, retry_gap_ms=2) bereit, mit den Diagnosewerten retry_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 MachineI2CBackend behä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)