rbAmp
DE
Shop
Docs
Aktualisiert

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)

Text
# 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

Text
# 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

Text
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

  1. Kanäle über N_VOLTAGE/N_CURRENT freigeben, Funktionen über CAPABILITIES, Layout der Übersicht über VERSION.
  2. Module über ihre UID identifizieren, nicht über die Bus-Adresse.
  3. Den RAM-Zustand (Ereignismaske, Schwellen, Uhr) nach jedem erkannten Modul-Neustart neu scharfstellen.
  4. NACK und Clock-Stretching bei Flash-Befehlen tolerieren; Einschwingzeiten einhalten.
  5. Energie: Zählerdifferenzen mit Behandlung von Generationswechsel und Neustart — niemals host-seitig P·dt.
  6. Firmware-Updates: die vorbereitete Freigabedatei unverändert streamen; vorher BOARD_ID prüfen.