02 · Gammes de modules
Ce qu'est une gamme de modules
Les modules rbAmp existent en deux gammes : BASIC et STANDARD (STD). Une gamme est un ensemble complet de révision matérielle et firmware, et non un drapeau logiciel. Passer d'une gamme à l'autre exige un changement physique de SKU, et non une mise à jour du firmware.
Du point de vue du paquet et du code utilisateur : une seule classe RbAmp couvre toutes les gammes de modules, et les lectures communes (voltage, current, power, power_factor, frequency) fonctionnent sur toutes. La gamme est détectée automatiquement à begin(). Les modules STANDARD (STD) exposent en plus les appels réservés à STD (énergie embarquée, etc., voir ci-dessous) ; appeler l'un d'eux sur un module BASIC lève RbAmpNotSupportedError.
État actuel
Les modules BASIC et STANDARD sont pris en charge par cette bibliothèque (STANDARD depuis la 1.6.0).
| Gamme de modules | Expédition |
|---|---|
| BASIC | ✅ oui |
| STANDARD (STD) | ✅ oui (pris en charge par cette bibliothèque à partir de la 1.6.0) |
BASIC — gamme de modules de mesure de consommation d'entrée de gamme
Matériel
Une voie analogique peu coûteuse, adaptée aux charges domestiques typiques. Le module comprend un front-end analogique isolé, un régulateur de puissance embarqué et un étalonnage d'usine en mémoire flash.
Comportement du firmware
La logique d'un compteur à disque mécanique classique — le compte n'avance que dans un sens ; l'export vers le réseau n'est pas soustrait.
Les trois « couches » des valeurs de puissance active se comportent différemment :
| Signal | Signification | Comportement sur BASIC |
|---|---|---|
dev.power[ch] / dev.read_power(ch) |
puissance active RT instantanée, mise à jour ~100 ms | signé — une valeur négative est visible en temps réel (export) |
snap.avg_p[ch] (depuis dev.read_period_snapshot()) |
puissance moyenne sur la période | chaque fenêtre de moyenne P de 100 ms est ramenée à max(P, 0) avant d'être ajoutée à l'accumulateur de période |
dev.energy.wh(ch) |
Wh accumulés par le paquet | monotone — consommation seulement ; l'injection n'est pas comptée |
Autrement dit : l'utilisateur voit l'export dans la lecture RT, mais il n'est pas présent dans le compteur de Wh du paquet sur BASIC.
Applications typiques
-
Foyers sans production propre (pas de panneaux solaires, d'éoliennes ni de systèmes de batteries)
-
Sous-comptage des charges purement consommatrices (chauffe-eau, moteurs, appareils domestiques)
-
Surveillance de la consommation d'un bâtiment où le comptage bidirectionnel n'est pas nécessaire
Mesure bidirectionnelle sur BASIC (côté maître)
Si vous devez suivre l'export vers le réseau séparément sur un module BASIC, faites-le côté maître. La puissance RT dev.power[0] est signée (ou la méthode équivalente dev.read_power(0)), donc :
import time
from rbamp import RbAmp, RbAmpIOError
def bidirectional_loop(dev):
consume_wh = 0.0
export_wh = 0.0
t_prev = time.monotonic()
while True:
# Sample RT power at 10 Hz — matches the firmware-commit
# cadence (100 ms per channel). Faster yields empty repeated
# reads; slower loses resolution on sharp load transitions.
time.sleep(0.1)
t_now = time.monotonic()
dt_s = t_now - t_prev
t_prev = t_now
try:
p = dev.read_power(0)
except RbAmpIOError:
continue
dwh = p * dt_s / 3600.0
if p >= 0.0:
consume_wh += dwh
else:
export_wh += -dwh
Sous MicroPython, remplacez time.monotonic() par time.ticks_ms() / time.ticks_diff() (plus précis et peu coûteux en RAM sur les plateformes embarquées) et time.sleep(0.1) par time.sleep_ms(100). Sous CPython, aucune modification.
Un exemple complet du schéma se trouve dans 06_examples.md, au scénario « Mesure bidirectionnelle côté maître », ainsi que dans les fichiers sources examples_upy/07_bidirectional_energy.py et examples_cpython/05_bidirectional_energy.py.
STANDARD (STD) — gamme de modules livrée
Les modules STANDARD sont une gamme de modules livrée, prise en charge par cette bibliothèque depuis la version 1.6.0. Ils utilisent une carte de registres différente (16 bits) de celle du BASIC ; la bibliothèque masque la différence — même classe RbAmp, même câblage I²C et même adresse, et mêmes lecteurs communs.
Ce que la bibliothèque ajoute sur un module STD :
-
Énergie embarquée :
dev.read_std_energy()renvoie les compteurs à vie propres au module — énergie active import / export / nette et réactive, en Wh, mWh et µWh, avec les chiffres par voie.RbAmp.std_energy_delta(prev, now)donne l'énergie consommée entre deux lectures et est sûre en cas de coupure de courant. Vous n'intégrez pas la puissance côté maître pour ces compteurs. -
Mesure par période :
read_period_snapshot()et les autres appels de période fonctionnent comme sur BASIC.begin()choisit la source — les compteurs d'énergie du module (la période est la différence de deux lectures ; aucune commande de latch n'est envoyée) ou, sur un module ne disposant que de banques de latch, la banque de latch 0. L'énergie est nette (l'export se soustrait). -
Latch banks (modules qui les exposent) :
dev.std_arm_banks(mask),dev.std_latch(bank),dev.std_read_latch(bank),RbAmp.std_latch_wh(snap, dt_ms). -
Fonctions multiphasées :
dev.read_voltage_angle(phase),dev.read_phase_sequence(),dev.read_reactive(ch)(STD uniquement ; sur BASIC, la puissance réactive n'est pas exposée par cette bibliothèque),dev.read_apparent(ch). -
Courant de démarrage :
dev.get_start_current()/dev.set_start_current(µA)+dev.save_config(). -
Blocs complets :
dev.read_std_voltage(),read_std_channel(),read_std_totals(),read_std_config(),read_std_health(),dev.set_time().
Notes:
-
Certains appels STD exigent une image de module assez récente (compteurs d'énergie en micro-unités, angles de tension, courant de démarrage). Si le module n'en fournit pas, l'appel lève
RbAmpNotSupportedError(« non disponible »). -
Utilisez
dev.is_stdpour brancher le code applicatif. -
La configuration de la classe de capteur et du modèle de pince, la réinitialisation et le changement d'adresse, les registres d'identité, le canal d'erreurs / d'événements, les fonctions de flotte et
wait_ready()sont réservés au BASIC ; sur un module STD, ils lèventRbAmpNotSupportedError. -
Les fonctions d'énergie embarquée, d'angle et de courant de démarrage sont validées sur CPython (
smbus2). Le chemin 16 bits MicroPython est implémenté mais pas encore validé sur matériel — préférez CPython pour ces fonctions tant qu'une note de version n'indique pas le contraire.
Signatures complètes : 09 · Référence API.
Comment détecter la gamme de module à l'exécution
Dans le firmware actuel, il n'existe pas de registre explicite de « gamme de module ». Des indicateurs indirects sont disponibles via les propriétés du handle :
# Firmware version — opaque byte
fw = dev.firmware_version
# Presence of a voltage sensor (UI* variants vs I*-only)
voltage_hw = dev.has_voltage_hw
# Number of current channels (1 / 2 / 3 on BASIC; 5 / 7 on UI5 / UI7)
channels = dev.channels
# BASIC variant byte (1=UI1, 2=UI2, 3=UI3, 4=I1, 5=I2, 6=I3, 7=UI5, 8=UI7)
variant = dev.read_variant()
# Module line: True on an STD module (detected in begin())
is_std = dev.is_std
: dev.is_std indique la gamme de module (STD ou BASIC). Les autres indicateurs (version du firmware, nombre de voies, présence d'un capteur de tension, variante) décrivent le module mais n'identifient pas la gamme. dev.read_variant() est l'octet de variante BASIC ; utilisez l'étiquette de référence figurant sur le boîtier du module comme source de vérité pour le produit.
Où les emplacements dépendant de la gamme de modules sont signalés dans la documentation
Dans le texte du paquet et la documentation de référence, les fonctions dépendant de la gamme de modules sont signalées explicitement, par exemple :
— cet appel n'est pas disponible sur un module BASIC.
Ou, à l'inverse, un comportement propre à BASIC :
: le compteur dev.energy.wh(ch) est monotone — l'export vers le réseau n'est pas compté. Pour la mesure bidirectionnelle, voir le scénario « Mesure bidirectionnelle côté maître » dans 06_examples.md, ou utilisez un module STANDARD, où l'énergie par période est nette et dev.read_std_energy() fournit des compteurs d'import et d'export séparés.
Et ensuite
-
03 · Choix du capteur de courant — quel SCT-013 pour quelle tâche
-
04 · Câblage — spécificités matérielles de chaque hôte (RPi / ESP32 / RP2040 / STM32 / Pyboard)
-
06 · Exemples — scénarios pour BASIC, y compris la mesure bidirectionnelle côté maître
-
09 · Référence API — l'API publique complète
Sources et problèmes : rb-amp/rbamp-python · cette page dans le dépôt : docs/02_tiers.md (v1.6.1)