Host-Integration
Wie Sie ein STD-Modul aus Ihrem eigenen Code betreiben — mit unseren Bibliotheken oder nur mit einem I²C-/Modbus-Master.
Mit den rbAmp-Bibliotheken
Eine Client-Bibliothek je Plattform deckt die gesamte Reihe ab; Kanalanzahl und Funktionen werden zur Laufzeit erkannt:
- Arduino (rbamp-arduino) — STD-Unterstützung: Erkennung, Echtzeit, Konfiguration, Ereignisse/DRDY, OTA, Verlauf, Energie mit Mikroauflösung, Anlaufstrom, Phasenwinkel und Reihenfolge. Bei einem Modul mit Snapshot-Bänken und Energiezählern v1.6.2 oder neuer verwenden (ältere Versionen übernehmen die Periode aus Bank 0 statt aus den Zählern; Energiequelle und Mindestversion).
- ESP-IDF (rbamp-esp-idf) — Komponente mit STD-Unterstützung, einschließlich Energie mit Mikroauflösung und Anlaufstrom. Bei einem Modul mit Snapshot-Bänken und Energiezählern v1.7.3 oder neuer verwenden (ältere Versionen übernehmen die Periode aus Bank 0 statt aus den Zählern; Mindestversion).
- ESPHome / Home Assistant (rbamp-esphome) — externe Komponente: Energiezähler im Gerät, Anlaufstrom und Phasendiagnose. Verwenden Sie v1.9.0 oder neuer; Snapshot-Bänke (
period_banks:) ab v1.9.1. - Python (rbamp-python) — STD-Unterstützung: eine Client-Klasse; die Modulreihe wird beim Verbinden erkannt. Verwenden Sie v1.6.0 oder neuer; Snapshot-Bank-Aufrufe ab v1.6.1. Geprüft auf Standard-Linux-Python (smbus2).
Die Bibliotheken decken diese Abläufe ab (Freigabe der Erkennung, Abfrage von Beschäftigt/Fehler, OTA mit vorbereitetem Image, Energie-Differenzbuchung), daher sind sie zu bevorzugen, wo die Plattform es erlaubt.
Die Funktionen für Energie mit Mikroauflösung und Anlaufstrom auf einen Blick — jeder Aufruf arbeitet bei Modulen ohne die Funktion geordnet weiter (kein Buszugriff, oder Werte aus den groben Zählern abgeleitet):
| Merkmal | Arduino | ESP-IDF | ESPHome (YAML) | Python |
|---|---|---|---|---|
Energie mit Mikroauflösung (µWh-/µvarh-Felder sind immer nutzbar; ein Flag fine zeigt, ob es die eigenen Zähler des Moduls sind) |
stdReadEnergy() → Felder RbAmpStdEnergy *_uwh / *_uvarh, stdEnergyDelta() |
rbamp_std_energy_t Felder *_uwh / *_uvarh, rbamp_std_energy_delta() |
energy_total · energy_exported_total · energy_net · reactive_energy / reactive_energy_exported |
read_std_energy() → RbAmpStdEnergy Felder *_uwh / *_uvarh, RbAmp.std_energy_delta() |
| Anlaufstrom für Energie | stdSetEnergyStartCurrent() / stdReadEnergyStartCurrent() |
rbamp_std_set_start_current() / rbamp_std_get_start_current() |
start_current_ua: |
set_start_current() / get_start_current() |
| Spannungs-Phasenwinkel | stdReadVoltage(v) → angle_deg / angle_valid |
rbamp_std_voltage_t.angle_deg / angle_valid |
voltage_angle_b / voltage_angle_c |
read_std_voltage(phase) → angle_deg / angle_valid |
| Phasenfolge | stdReadPhaseSequence() |
rbamp_std_read_phase_seq() |
phase_sequence |
read_phase_sequence() |
Wenn Ihre Anwendung einen Bibliotheks-Energie-Snapshot persistiert (NVS, EEPROM, Datei), speichern Sie die einzelnen benötigten Felder in Ihrem eigenen festen Format, nicht die Struktur als rohen Block — die Snapshot-Strukturen erhalten zwischen Bibliotheksversionen neue Felder.
Ohne unsere Bibliotheken
Alles, was die Bibliotheken tun, ist reine Registerein- und -ausgabe. Das Protokoll ist dokumentiert und stabil; Kartenänderungen sind versioniert (VERSION) und funktional gesteuert (CAPABILITIES). Die verbindlichen Schritt-für-Schritt-Abläufe (Initialisierung, Befehl, Konfiguration, Adressänderung, Energie, Verlauf, OTA, Entsperren) stehen unter Abläufe — unten finden Sie die kürzesten funktionierenden Muster.
Minimale I²C-Inbetriebnahme (Pseudocode)
# discovery (once)
id = read(0x0000, 2) # expect 'S','T'
ver = read(0x0003, 1) # map version, expect >= 0x36
caps = read_u16(0x0004)
nv = read(0x0007, 1); ni = read(0x0008, 1)
uid = read(0x00F4, 12) # device identity for your database
fwv = read_u32(0x0114) # firmware version: high word . low word (1.126)
# clock (after every module reset: STATUS bit4 == 0)
write_u32(0x08C0, unix_epoch) # TIME_SET
write(0x0060, 0x06) # SET_TIME; then poll CMD_STATE 0x006A bit0 -> 0, check ERROR == 0
# realtime poll (every 0.2..1 s, or on the DRDY edge)
u_mv = read_i32(0x0200 + v*0x20) # per voltage channel
i_ua = read_i32(0x1000 + c*0x40) # per current channel
p_mw = read_i32(0x1000 + c*0x40 + 0x04) # signed
pf = read_i16(0x1000 + c*0x40 + 0x10) # /1024
freq = read_u16(0x0010) # /100 Hz
tot_p = read_i32(0x0300 + 0x04) # grand active power
Muster der Energiebuchhaltung
# at each interval boundary (your clock):
blk = read(0x0800, 0x44) # ONE transaction <= 128 B: Wh + mWh counters + LT_GEN — coherent
e_imp = i64(blk, 0x28); e_exp = i64(blk, 0x30) # grand import/export, mWh
gen = u32(blk, 0x40) # LT_GEN (0x0840)
up = read_u32(0x08A0) # UPTIME
interval_import = e_imp - last_imp # delta of cumulative counters
if gen != last_gen: re-anchor, no delta # counter was reset/adopted (event-logged)
if up < last_up: delta = max(0, delta) # restart: ~last second of energy may be missing; re-feed time
Den Energieblock in einer Transaktion von ≤ 128 Byte lesen — i64-Felder, die in getrennten Transaktionen gelesen werden, können über eine Veröffentlichung hinweg auseinanderlaufen (I²C-Übertragungsweg).
Leistung niemals auf dem Host über die Zeit integrieren — die Zähler des Moduls sind lückenkompensiert und gespeichert; Ihr Integral ist weder das eine noch das andere. Details: Mess- & Energiemodell.
Stündliche Datensätze lesen
write(0x0C00, 1) # HIST_PERIOD = hourly
write_u16(0x0C04, n) # n records back from newest
write(0x0060, 0x08) # HIST_READ
poll CMD_STATE (0x006A) bit0 -> 0
err = read(0x0002, 1) # 0xFC = no such record
flags = read(0x0C02, 1) # bit0 = record valid
rec = read(0x0C20, 80) # one transaction; see record layout
Datensätze enthalten die absoluten Lebensdauer-Wh am Periodenende plus die Periodenenergie je Phase (Aufbau).
Gesundheitsabfrage
Siehe die Diagnose-Checkliste — sechs Lesevorgänge decken Lebenszeichen, Speichergesundheit, Neustarts und Zählergenerationen ab.
Modbus-Integration ohne Bibliotheken
-
Float32-Profil: die Punkte, die das Modul veröffentlicht — V/I/P je Phase, Gesamt-P, Frequenz, Bezug/Einspeisung kWh — an den Float32-Eingangsadressen (Liste). Andere Adressen des Profils liefern 0.
-
Natives Profil: FC04-Lesevorgänge bei 0x6000 (Discovery), 0x6100/0x6200 (Kanäle), 0x6B00+ (Energie), 0x6C00 (Summen); Konfiguration und Befehle über FC16 bei 0x8000+ mit UNLOCK für zustandsändernde Befehle. Vollständige Karte: Registerübersicht; Regeln: Modbus-Transport.
-
Master, die nur FC03 beherrschen, lesen die nativen Daten über den Spiegel ab 0xA000+ (Eingang + 0x4000).
Integrationsregeln, die sich zu wiederholen lohnen
- Kanäle über
N_VOLTAGE/N_CURRENTfreigeben, Funktionen überCAPABILITIES, Layout der Übersicht überVERSION. - Module über ihre UID identifizieren, nicht über die Bus-Adresse.
- Den RAM-Zustand (Ereignismaske, Schwellen, Uhr) nach jedem erkannten Modul-Neustart neu scharfstellen.
- NACK und Clock-Stretching bei Flash-Befehlen tolerieren; Einschwingzeiten einhalten.
- Energie: Zählerdifferenzen mit Behandlung von Generationswechsel und Neustart — niemals host-seitig P·dt.
- Firmware-Updates: die vorbereitete Freigabedatei unverändert streamen; vorher
BOARD_IDprüfen.