Intégration hôte
Comment piloter un module STD depuis votre propre code — avec nos bibliothèques ou avec un simple maître I²C/Modbus.
Avec les bibliothèques rbAmp
Une seule bibliothèque cliente par plateforme couvre toute la gamme ; le nombre de canaux et les fonctions sont découverts à l'exécution :
- Arduino (rbamp-arduino) — prise en charge STD : découverte, temps réel, configuration, événements/DRDY, OTA, historique, énergie en micro-résolution, courant de démarrage, angle de phase et séquence. Sur un module avec banques d'instantanés et compteurs d'énergie, utilisez la v1.6.2 ou ultérieure (les versions antérieures prennent la période depuis la banque 0 au lieu des compteurs ; source d'énergie et version minimale).
- ESP-IDF (rbamp-esp-idf) — composant avec prise en charge STD, y compris l'énergie en micro-résolution et le courant de démarrage. Sur un module avec banques d'instantanés et compteurs d'énergie, utilisez la v1.7.3 ou ultérieure (les versions antérieures prennent la période depuis la banque 0 au lieu des compteurs ; version minimale).
- ESPHome / Home Assistant (rbamp-esphome) — composant externe : compteurs d'énergie embarqués, courant de démarrage et diagnostics de phase. Utilisez la v1.9.0 ou ultérieure ; les banques d'instantanés (
period_banks:) à partir de la v1.9.1. - Python (rbamp-python) — prise en charge du STD : une seule classe cliente, la gamme du module est détectée à la connexion. Utilisez la v1.6.0 ou ultérieure ; les appels aux banques d'instantanés à partir de la v1.6.1. Validé sur Python Linux standard (smbus2).
Les bibliothèques couvrent ces procédures (contrôle de la découverte, interrogation occupé/erreur, OTA à image préparée, comptabilité des deltas d'énergie) ; préférez-les lorsque la plateforme le permet.
Présentation des fonctions d'énergie à micro-résolution et de courant de démarrage — chaque appel se dégrade proprement sur les modules qui ne publient pas la fonction (sans trafic de bus, ou avec des valeurs dérivées des compteurs grossiers) :
| Fonctionnalité | Arduino | ESP-IDF | ESPHome (YAML) | Python |
|---|---|---|---|---|
Énergie à micro-résolution (les champs µWh / µvarh sont toujours exploitables ; un drapeau fine indique s'il s'agit des compteurs propres du module) |
stdReadEnergy() → champs RbAmpStdEnergy *_uwh / *_uvarh, stdEnergyDelta() |
champs rbamp_std_energy_t *_uwh / *_uvarh, rbamp_std_energy_delta() |
energy_total · energy_exported_total · energy_net · reactive_energy / reactive_energy_exported |
read_std_energy() → champs RbAmpStdEnergy *_uwh / *_uvarh, RbAmp.std_energy_delta() |
| Courant de démarrage pour l'énergie | stdSetEnergyStartCurrent() / stdReadEnergyStartCurrent() |
rbamp_std_set_start_current() / rbamp_std_get_start_current() |
start_current_ua: |
set_start_current() / get_start_current() |
| Angle de phase de tension | 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 |
| Ordre des phases | stdReadPhaseSequence() |
rbamp_std_read_phase_seq() |
phase_sequence |
read_phase_sequence() |
Si votre application sauvegarde un instantané d'énergie de la bibliothèque (NVS, EEPROM, fichier), stockez les champs individuels dont vous avez besoin dans votre propre format fixe, et non la structure en blob brut — les structures d'instantané gagnent des champs d'une version de bibliothèque à l'autre.
Sans nos bibliothèques
Tout ce que font les bibliothèques est de l'E/S de registres ordinaire. Le protocole est documenté et stable ; les changements de table sont versionnés (VERSION) et conditionnés par fonctionnalité (CAPABILITIES). Les procédures canoniques pas à pas (initialisation, commande, configuration, changement d'adresse, énergie, historique, OTA, déverrouillage) sont dans Séquences — ci-dessous, les schémas de fonctionnement les plus courts.
Mise en route I²C minimale (pseudo-code)
# 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
Schéma de comptabilisation de l'énergie
# 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
Lisez le bloc énergie en une transaction de ≤ 128 octets — les champs i64 lus dans des transactions séparées peuvent se déchirer entre deux publications (Transport I²C).
N'intégrez jamais la puissance dans le temps côté hôte — les compteurs du module sont compensés des interruptions et persistés ; votre intégrale n'est ni l'un ni l'autre. Détails : Mesure et énergie.
Lecture des enregistrements horaires
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
Les enregistrements portent le Wh absolu à vie à la fin de la période, plus l'énergie de période par phase (disposition).
Interrogation de santé
Voir la liste de contrôle des diagnostics — six lectures couvrent la vie du module, la santé du stockage, les redémarrages et les générations de compteurs.
Intégration Modbus sans bibliothèques
-
Profil float32 : les points que publie le module — V/I/P par phase, P total, fréquence, énergie importée/exportée en kWh — aux adresses d'entrée float32 (liste). Les autres adresses du profil affichent 0.
-
Profil natif : lectures FC04 à 0x6000 (découverte), 0x6100/0x6200 (canaux), 0x6B00+ (énergie), 0x6C00 (totaux) ; configuration et commandes par FC16 à partir de 0x8000+ avec UNLOCK pour les commandes qui modifient l'état. Table complète : table de registres ; règles : Transport Modbus.
-
Les maîtres FC03 seuls lisent les données natives par le miroir 0xA000+ (entrée + 0x4000).
Règles d'intégration à retenir
- Conditionnez les canaux à
N_VOLTAGE/N_CURRENT, les fonctions àCAPABILITIES, et la disposition de la carte àVERSION. - Identifiez les modules par UID, non par adresse de bus.
- Réarmer l'état en RAM (masque d'événements, seuils, horloge) après toute réinitialisation détectée du module.
- Tolérez le NACK et l'étirement d'horloge pendant les commandes qui touchent la flash ; respectez les temps de stabilisation.
- Énergie : deltas de compteurs avec gestion de la génération et des redémarrages — jamais de P·dt côté hôte.
- Mises à jour du micrologiciel : transmettez le fichier de version préparé tel quel ; vérifiez d'abord
BOARD_ID.