Référence du protocole filaire rbAmp (v1.3)
rbAmp est un module matériel compact pour la mesure des paramètres du secteur alternatif via une interface I²C. Le module se comporte comme un esclave I²C standard avec une carte de registres fixe (page 0, 0x00..0xFF). Ce document décrit le protocole filaire au niveau des registres, des commandes et des séquences.
: intégrateurs tiers et avancés qui écrivent leurs propres pilotes I²C pour le module rbAmp sans utiliser les bibliothèques clientes (Arduino / ESP-IDF / Python / ESPHome).
Périmètre : protocole filaire canonique du module rbAmp en version v1.3 — carte des registres, séquences de protocole, garanties de comportement. Il s'agit de la documentation de référence complète au niveau du contrat filaire.
Version : « v1.3 » est la version du protocole filaire (le registre VERSION 0x03 renvoie 0x04), et non la version de ce document. C'est le protocole de tous les firmwares actuels des modules BASIC (1.4.x) ; les modules STANDARD (STD) utilisent une carte de registres différente — voir la référence technique STD.
HORS PÉRIMÈTRE : intégration avec une bibliothèque, un système d'exploitation ou un framework spécifique — consultez la documentation de la bibliothèque concernée.
1 · Introduction
1.1 Gamme des références SKU
Les variantes de module (SCT-UI1 … SCT-I3, avec leurs canaux de tension et de courant) sont listées dans overview.md → Variantes de module.
Les variantes I (I1/I2/I3) n'ont aucun matériel de tension — les registres U_RMS, U_PEAK et P renvoient 0.0. La fréquence (AC_FREQ) est disponible sur toutes les variantes (issue du passage par zéro).
L'étalonnage est d'usine. Le maître client NE configure PAS le bruit de fond (NF), le gain, la compensation de phase, ni aucun autre paramètre d'usine — tout cela est de l'étalonnage d'usine gravé dans le module (voir §4.0 plages réservées). Sur les modules BASIC de la série SCT (utilisés avec des capteurs SCT-013), le client n'écrit que SENSOR_CLASS + CT_MODEL (voir §6.2) — le module applique tout le reste automatiquement depuis la table de préréglages. Les modules BASIC de la série CT et STANDARD (STD) sont fournis par paires avec leurs capteurs, préréglés et calibrés en usine : rien n'est écrit.
1.2 Versions
| Champ | Valeur |
|---|---|
protocol_version |
1.3 |
schema_version |
2 |
Registre VERSION (0x03) |
0x04 pour v1.3 |
| Contrat de la page 0 | figé à la sortie de la v1.3 |
2 · Bases du protocole de bus
2.0 Puissance et alimentation
| Paramètre | Valeur |
|---|---|
VCC nominal |
+5 V |
Plage de VCC |
4.5..5.5 V |
| Consommation de courant typique | ~15 mA |
| Appel de courant de crête (instantané + écriture en flash) | ~25 mA |
| Appel de courant au démarrage | ≤ 50 mA @ 5 ms |
| Séquencement | VCC peut être appliqué en même temps que l'I²C ; les résistances de rappel (3.3 V) sont admises avant l'application de VCC |
| Isolation | le module est entièrement basse tension : la pince se couple magnétiquement, et la prise de tension de l'UI est isolée galvaniquement |
Quatre fils sont obligatoires côté basse tension : VCC, GND, SDA, SCL. DRDY (drain ouvert) est facultatif. Voir §2.3 pour les résistances de rappel et les conseils multi-modules.
2.1 Paramètres I²C
- Adresse par défaut :
0x50(7 bits). - Plage d'adresses autorisée :
0x08..0x77(bornes I²C réservées standard). - Niveaux logiques : 3.3 V (tolérant 5 V sur des résistances de rappel vers 3.3 V).
- Pull-ups intégrés : 4.7 kΩ sur SDA/SCL vers 3.3 V (module).
- Étirement d'horloge : le module n'utilise PAS l'étirement de SCL comme contrôle de flux de routine. Entre les transactions, le maître doit respecter un intervalle inter-transactions ≥ 100 µs (
tBUF). Les transactions enchaînées sans intervalle (START répété sanstBUF) sont permises mais déconseillées — certaines piles hôtes (ESP-IDF i2c_master) présentent un taux de NACK plus élevé. Voir la section §5 acceptation / EMI séparément.
2.2 Vitesse du bus
| Vitesse | Applicabilité | Remarque |
|---|---|---|
| 50 kHz | recommandé sur les hôtes ESP32 et ESP8266 | Le pilote I²C ESP-IDF affiche un taux de NACK d'environ 20 % à 100 kHz — une limitation du pilote hôte, non du module ; 50 kHz + 3 nouvelles tentatives donnent un taux d'erreur < 0.8 %. |
| 100 kHz | recommandé sur les autres hôtes | également praticable sur ESP32/ESP8266 avec 3 reprises au niveau applicatif. |
| 400 kHz | non recommandé | la vitesse est au choix de l'utilisateur. |
2.3 Bus multi-modules
Plusieurs modules rbAmp peuvent partager un même bus :
- Jusqu'à ~16 modules (limité par la capacité totale du bus ≤ 400 pF à 100 kHz).
- Pull-ups : avec 2 à 3 modules sur un bus de 15 cm maximum, laissez les pull-ups embarqués tranquilles ; avec quatre modules ou plus, ou sur un bus plus long, les pull-ups de 4.7 kΩ en parallèle surchargent le collecteur. Coupez les pull-ups embarqués sur chaque module sauf un (ou utilisez un tampon I²C PCA9515/9615).
- Longueur : jusqu'à 0.15 m en simple → 100 kHz ; 0.15–1 m en paire torsadée (SDA+GND et SCL+GND en paires séparées) → 100 kHz ; > 1 m — tampon I²C ; > 3 m — bus différentiel (PCA9615 / LTC4332).
2.4 Budget d'interrogation du bus
À 50 kHz, une lecture de registre prend ≈ 200–400 µs. Le bloc RT complet d'un canal (U + I + P + PF, 4 flottants = 16 octets en rafale) prend ≈ 5–8 ms par canal.
| Configuration | Bus par cycle | Cadence d'interrogation maximale |
|---|---|---|
| 1× UI1, bloc RT | ~5 ms | 100+ Hz (mais le module se met à jour à 10 Hz) |
| 5× UI1, bloc RT | ~25 ms | 10 Hz |
| 16× I3, temps réel + période | ~400 ms | ne peut pas suivre — lit environ toutes les 4 fenêtres de 100 ms |
Règle empirique : à 50 kHz, les limites confortables sont 8–10× I3 ou 15–16× UI1 lorsqu'on interroge toutes les deux fenêtres (5 Hz) ; divisez le nombre de modules par deux pour interroger chaque fenêtre (10 Hz).
3 · Modèle des variantes
3.1 HW_VARIANT (registre 0x55, u8, lecture seule)
Octet SKU faisant foi :
| Valeur | SKU | N_I | Matériel de tension |
|---|---|---|---|
0x01 |
UI1 | 1 | oui |
0x02 |
UI2 | 2 | oui |
0x03 |
UI3 | 3 | oui |
0x04 |
I1 | 1 | non |
0x05 |
I2 | 2 | non |
0x06 |
I3 | 3 | non |
0x07 |
UI5 | 5 | oui |
0x08 |
UI7 | 7 | oui |
Toute autre valeur → l'appareil n'est pas identifié comme rbAmp.
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmp::readVariant() |
lire la variante matérielle (SKU) |
| ESP-IDF | rbamp_read_variant() |
lire la variante matérielle (SKU) |
| Python | dev.read_variant() |
lire la variante matérielle (SKU) |
| ESPHome | get_variant_str() |
lire la variante matérielle (SKU) |
3.2 CAPABILITY (registres 0x57/0x58, u16 LE, lecture seule)
Carte des fonctionnalités. C'est la façon canonique de détecter les fonctions prises en charge — sans comparaison numérique de version.
| bit | Indicateur | Signification |
|---|---|---|
| 0 | EXT_ADDRESSING | adressage étendu 16 bits (préfixe 0xFF) |
| 1 | GC_LATCH | L'instantané General-Call est pris en charge |
| 2 | GC_GROUP_FILTER | le filtre GROUP_ID est actif |
| 3 | DIGEST | le bloc digest (0x70..0x85) est exposé |
| 4 | EVENTS | EVENT_FLAGS est pris en charge |
| 5 | UID_ARBITRATION | arbitrage d'adresse par UID (aucune commande publique) |
| 6 | SEAL | réservé — non implémenté |
| 7 | TWO_PHASE_ADDR | changement d'adresse en commit à deux phases |
| 8 | ZC_PHASE_OFFSET = matériel tension | le module possède une voie U |
| 9 | SAVE_USER_CONFIG | CMD_SAVE_USER_CONFIG est disponible |
| 10 | CLEAR_ERROR | CMD_CLEAR_ERROR est disponible |
| 11 | IAP | programmation en cours d'application (niveaux F4 uniquement) |
| 12 | SCT_RATING_SELF | fw 1.4.20+ : un changement de modèle SCT conserve l'étalonnage de l'unité et survit à un redémarrage ; les bibliothèques sautent leur propre correction de calibre |
3.2.1 Détection des fonctions
Détectez chaque fonction par son bit propre — ne comparez jamais le registre entier à une constante attendue : la carte grandit avec le firmware (le bit 12 est apparu en fw 1.4.20, par exemple), donc la comparaison de la valeur complète casse sur les modules récents.
3.2.2 Disposition des octets de CAPABILITY u16 LE
CAPABILITY fait 2 octets aux adresses 0x57 (octet de poids faible) et 0x58 (octet de poids fort), little-endian :
register layout (byte-addressed):
0x57 0x58
┌──────┬──────┐
│ LO │ HI │
└──────┴──────┘
bits bits
0-7 8-15
full u16 = (read_u8(0x58) << 8) | read_u8(0x57)
Correspondance des bits :
- l'octet
0x57(LO) contient les bits 0..7 : EXT_ADDRESSING, GC_LATCH, GC_GROUP_FILTER, DIGEST, EVENTS, UID_ARBITRATION, SEAL, TWO_PHASE_ADDR. - l'octet
0x58(HI) contient les bits 8..15 : ZC_PHASE_OFFSET (= HW de tension), SAVE_USER_CONFIG, CLEAR_ERROR, IAP, SCT_RATING_SELF (bit 12, fw 1.4.20+), bits 13-15 réservés.
3.2.3 Recette canonique de has_voltage
cap_hi = read_u8(0x58) # high byte holds bits 8..15
has_voltage = bool(cap_hi & 0x01) # bit 8 of the u16 = bit 0 of byte 0x58
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmp::readCapability(out) / RbAmp::hasVoltageHw() |
lire la carte de fonctionnalités sur 16 bits ; vérifier la présence d'un canal de tension |
| ESP-IDF | rbamp_read_capability() / rbamp_has_voltage() |
lire la carte de fonctionnalités sur 16 bits ; vérifier la présence d'un canal de tension |
| Python | dev.read_capability() / dev.has_voltage() |
lire la carte de fonctionnalités sur 16 bits ; vérifier la présence d'un canal de tension |
| ESPHome | get_capability_hex() |
lire la carte des capacités |
3.3 Tableau des profils de variante — invariant
| SKU | HW_VARIANT (0x55) | N_I | matériel tension | Bit 8 de CAPABILITY (matériel tension) |
|---|---|---|---|---|
| UI1 | 1 | 1 | oui | bit 8 à 1 |
| UI2 | 2 | 2 | oui | bit 8 à 1 |
| UI3 | 3 | 3 | oui | bit 8 à 1 |
| I1 | 4 | 1 | non | bit 8 à 0 |
| I2 | 5 | 2 | non | bit 8 à 0 |
| I3 | 6 | 3 | non | bit 8 à 0 |
| UI5 | 7 | 5 | oui | bit 8 à 1 |
| UI7 | 8 | 7 | oui | bit 8 à 1 |
Cohérence HW_VARIANT ⟷ CAPABILITY : HW_VARIANT 1..3 et 7..8 (UI) → bit 8 à 1 ; HW_VARIANT 4..6 (I) → bit 8 à 0. Un écart indique une anomalie matérielle ou firmware (appareil défectueux ou mauvais flashage).
3.4 SENSOR_CLASS ≠ discriminant de variante
⚠ SENSOR_CLASS (0x25) n'est PAS un discriminant de variante. C'est un registre de configuration utilisateur (sélecteur de classe de capteur CT : Unset/Sct013/WiredCT/BuiltinCT) qui ne reflète pas la variante matérielle. Pour détecter la variante, utilisez uniquement HW_VARIANT (0x55) + CAPABILITY (0x57/0x58).
3.5 PRODUCT_ID (0x54, u8, lecture seule)
Discriminant de famille de produits :
| Valeur | Famille |
|---|---|
0x01 |
capteur rbAmp (ce document) |
0x02 |
rbDimmer (carte de registres distincte ; non couverte par ce document) |
Le maître DOIT lire PRODUCT_ID avant d'interpréter tout registre propre à une famille.
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmp::readProductId() |
lire l'octet d'identifiant de famille |
| ESP-IDF | rbamp_read_product_id() |
lire l'octet d'identifiant de famille |
| Python | dev.read_product_id() |
lire l'octet d'identifiant de famille |
| ESPHome | — | non exposé |
3.6 Algorithme de détection canonique
if not i2c_addr_acks(addr):
return NO_DEVICE
product = read_u8(addr, 0x54)
if product != 0x01:
return NOT_RBAMP_SENSOR
hw = read_u8(addr, 0x55)
if 1 <= hw <= 8:
cap_hi = read_u8(addr, 0x58)
has_voltage = bool(cap_hi & 0x01)
return {sku: SKU[hw], N_I: N_I_TABLE[hw], has_voltage: has_voltage}
return UNKNOWN_DEVICE
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmp::begin() / RbAmp::readVariant() |
interroger le module et détecter sa ligne ; lire la variante |
| ESP-IDF | rbamp_begin() / rbamp_read_variant() |
interroger le module et détecter sa ligne ; lire la variante |
| Python | dev.begin() / dev.read_variant() |
interroger le module et détecter sa ligne ; lire la variante |
| ESPHome | rbamp: address: / get_variant_str() |
adresse du module réglée en YAML ; la variante en texte |
4 · Carte des registres (production v1.3)
Filtre appliqué: build: production(registres de build calibration exclus). Les registres d'étalonnage d'usine (NF, GAIN, PHASE) sontnon documenté— elles relèvent du banc d'usine, et non de la surface destinée au consommateur.
4.0 Plages réservées (interne)
Les plages suivantes sont réservées à un usage interne/d'usine et ne sont pas décrites dans ce document. Les lectures renvoient soit des données sans intérêt pour la logique consommateur, soit 0x00 pour les adresses inexistantes (voir §5.2). Les écritures vers ces adresses sont soit ignorées silencieusement, soit acquittées avec ERR_PARAM :
0x04— indicateur de mode interne (contrôlé par l'usine, non modifiable par le client).0x06,0x26— paramètres d'étalonnage internes (banc d'usine).0x08..0x0F— vue de débogage LUT (diagnostic usine).0x1B..0x1F— page 0 réservée (0x18..0x1Asont des diagnostics de production, voir §4.2).0x36..0x3B,0x40..0x45— page 0 réservée (0x32+0x3C..0x3Fforment la fenêtre d'accès aux canaux, voir §4.14).0x4F,0x50— réservés (pré-réservation du bloc d'identité).0xE4..0xEB,0xF0..0xFF— étalonnage d'usine (NF, GAIN) ; écritures soumises à l'usine.
Remarque sur 0xD0..0xE3 : dans le firmware de production, cette plage est occupée par le bloc V03 Q (voir §4.12). Dans le firmware d'étalonnage séparé (non livré au client), la même plage est recouverte par le bloc d'étalonnage (build:cal). Le maître client ne voit que la couche de production — le bloc Q.
Les intégrateurs tiers (3rd-party) doivent ignorer ces plages.
4.1 Bloc de contrôle (0x00..0x07)
| Adr | Nom | Taille | Type | Accès | Persistance | Remarques |
|---|---|---|---|---|---|---|
0x00 |
STATUS |
1 | u8 | r | ram | bit0=PRÊT, bit1=ERREUR (miroir de REG_ERROR != 0), bit2=EVENTS_PENDING (miroir de EVENT_FLAGS != 0) |
0x01 |
COMMAND |
1 | u8 | w | ram | Écrire un code d'opération CMD_* (voir §5.2) |
0x02 |
ERROR |
1 | u8 | r | ram | résultat de la dernière écriture ; 0x00 = OK ; 0xFA..0xFF classes d'erreur. Effacer via CMD_CLEAR_ERROR. Voir §5.3 |
0x03 |
VERSION |
1 | u8 | r | rom | Version du protocole. 0x04 = v1.3 |
0x05 |
CT_MODEL |
1 | u8 | rw | user_config | Code de référence SCT-013 (préparation pure v1.3 — voir §6.2) |
0x07 |
V03_PERIOD_VALID |
1 | u8 | r | ram | Positionné par CMD_LATCH_PERIOD : 1 = frais, 0 = vide/périmé. NON effacé à la lecture. Voir §6.3.3 (témoin) + §7.5 (préservation d'un instantané échoué) |
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmp::waitReady(timeout_ms) / RbAmp::readLastError() |
attendre l'indicateur prêt ; lire le code d'erreur du périphérique |
| ESP-IDF | rbamp_wait_ready() / rbamp_read_last_error() |
attendre l'indicateur prêt ; lire le code d'erreur du périphérique |
| Python | dev.wait_ready(timeout_ms=1000) / dev.read_last_error() |
attendre le drapeau de disponibilité (lève une erreur au délai) ; lire le code d'erreur de l'appareil |
| ESPHome | Vérification de disponibilité de update() / get_last_error_str() |
les lectures sont publiées dès que le module signale qu'il est prêt ; le code d'erreur en texte |
4.2 Diagnostics — moyennes d'entrée brutes et fenêtre de capture (0x10..0x1C)
| Adr | Nom | Taille | Type | Accès | Persistance | Remarques |
|---|---|---|---|---|---|---|
0x10 |
ADC_MEAN_U |
2 | u16 LE | r | ram | Moyenne de l'entrée brute, canal U (~2048 centré) |
0x12 |
ADC_MEAN_I0 |
2 | u16 LE | r | ram | Moyenne d'entrée brute, I0 |
0x14 |
ADC_MEAN_I1 |
2 | u16 LE | r | ram | Moyenne d'entrée brute, I1 (UI2/I2/I3/UI3) |
0x16 |
ADC_MEAN_I2 |
2 | u16 LE | r | ram | Moyenne de l'entrée brute, I2 (UI3/I3) |
0x18 |
CAPTURE_STATUS |
1 | u8 | r | ram | Capture d'échantillons bruts : bit0=prêt |
0x19 |
CAPTURE_PAGE |
1 | u8 | rw | ram | Page 0..15 → 16 échantillons I0 bruts dans CAPTURE_WINDOW |
0x1A |
CAPTURE_WINDOW |
32 | octets | r | ram | 16×u16 LE codes I0 pré-LUT. Lecture en rafale de 32 octets. |
4.3 Système (0x20..0x25)
| Adr | Nom | Taille | Type | Accès | Persistance | Remarques |
|---|---|---|---|---|---|---|
0x20 |
AC_FREQ |
1 | u8 | r | ram | Issu du passage par zéro. 50 ou 60 Hz entier. Le passage par zéro est actif sur toutes les variantes (y compris I*) |
0x21 |
AC_PERIOD |
2 | u16 LE | r | ram | Demi-période secteur, µs |
0x23 |
CALIBRATION |
1 | u8 | r | ram | Octet d'état d'étalonnage hérité |
0x24 |
TOPOLOGY |
1 | u8 | r | rom | Nombre de canaux de courant (= V03_N_I) : 1, 2 ou 3 ; 5 = UI5, 7 = UI7 |
0x25 |
SENSOR_CLASS |
1 | u8 | rw | user_config | 0 = UNSET, 1 = SCT_013, 2 = WIRED_CT (série des pinces CT, modèles 1..13 : 1..5 hérités ; appairées en usine sur les références CT- — sur le firmware 1.4.22 et ultérieur, le module refuse les écritures de classe et de modèle en fonctionnement normal avec ERR_PARAM (0xFE) ; les bibliothèques clientes les refusent sur tous les firmwares), 3 = BUILTIN_CT (étalonnage d'usine par unité, code de modèle non utilisé). Un changement de classe remet CT_MODEL = 0. Ce n'est pas un discriminant de variante (voir §3.4) |
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmp::setSensorClass(cls) / RbAmp::readSensorClass(out) |
réglez la classe du capteur ; relisez-la |
| ESP-IDF | rbamp_set_sensor_class() / rbamp_read_sensor_class() |
réglez la classe du capteur ; relisez-la |
| Python | dev.set_sensor_class(cls) / dev.read_sensor_class() |
réglez la classe du capteur ; relisez-la |
| ESPHome | sensor_class: |
Option YAML qui fixe la classe du capteur |
4.4 Configuration de flotte (0x27..0x2F)
| Adr | Nom | Taille | Type | Accès | Persistance | Remarques |
|---|---|---|---|---|---|---|
0x27 |
FLEET_CONFIG |
1 | u8 | rw | user_config | bit0 = GC_ENABLE (réception d'instantanés General-Call ; effectif après reset). bits 1-7 réservés |
0x28 |
GROUP_ID |
1 | u8 | rw | user_config | Filtre de groupe d'instantané GC. 0 = répondre à l'appel général. L'octet de groupe de la trame GC doit correspondre ou valoir 0x00 |
0x29 |
DIGEST_CONFIG |
1 | u8 | rw | ram | Masque de composition de la fenêtre de digest (voir §4.9) ; l'écriture d'un bit non pris en charge → ERR_PARAM. Vaut 0x00 (digest désactivé) après réinitialisation ; à réécrire à chaque initialisation |
0x2A |
EVENT_FLAGS |
1 | u8 | w1c | ram | Indicateurs d'événements persistants (voir §5.3 modèle d'erreur). Vaut 0x00 après réinitialisation (mais le bit5 RESET_OCCURRED est positionné au démarrage) |
0x2B |
EVENT_MASK |
1 | u8 | rw | ram | Quels bits de EVENT_FLAGS pilotent DRDY à un niveau BAS continu |
0x2C |
THRESH_I_HI |
2 | u16 LE | rw | ram | Seuil de courant → EVENT_FLAGS.THRESH_I. Unités : 0.01 A. 0xFFFF = désactivé |
0x2E |
THRESH_P_HI |
2 | u16 LE | rw | ram | Seuil de puissance → EVENT_FLAGS.THRESH_P. Unités : W. 0xFFFF = désactivé |
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmp::enableGc(enable) / RbAmp::setEventThresholds(i_amps, p_watts) |
activer General Call sur un module ; régler les seuils de courant et de puissance |
| ESP-IDF | rbamp_enable_gc() / rbamp_set_event_thresholds() |
activer General Call sur un module ; régler les seuils de courant et de puissance |
| Python | dev.enable_gc(enable=True) / dev.read_event_flags() |
activer General Call sur un module ; lire les indicateurs d'événements (pas de réglage de seuil au niveau de l'appareil) |
| ESPHome | fleet_gc_enable: / group_id: |
Options YAML pour l'adhésion General Call et l'identifiant de groupe |
4.5 Adresse (0x30..0x31)
| Adr | Nom | Taille | Type | Accès | Persistance | Remarques |
|---|---|---|---|---|---|---|
0x30 |
I2C_ADDRESS |
1 | u8 | rw | user_config | Commit à deux phases : écrire l'adresse candidate 0x08..0x77 → préparation en RAM ; armer ADDR_COMMIT_MAGIC ; puis CMD_COMMIT_ADDR ; effectif après reset. Au démarrage, l'adresse active est relue (v1.3 correctif 4) |
0x31 |
ADDR_COMMIT_MAGIC |
1 | u8 | w | ram | Écrivez 0xA5 pour armer CMD_COMMIT_ADDR. Consommé (effacé) à la tentative de commit. Les lectures renvoient 0x00 |
Voir §6.1 pour la séquence.
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmp::prepareAddressChange(new_addr) / RbAmp::readActiveAddress(out) |
préparer et armer la nouvelle adresse ; lire l'adresse active |
| ESP-IDF | rbamp_prepare_address_change() / rbamp_read_active_address() |
préparer et armer la nouvelle adresse ; lire l'adresse active |
| Python | dev.prepare_address_change(new_addr) / dev.commit_address_change() |
préparer et armer la nouvelle adresse, puis la valider |
| ESPHome | new_address: |
changement d'adresse ponctuel au démarrage ; supprimez l'option ensuite |
4.6 Santé / diagnostic (0x46..0x4F)
| Adr | Nom | Taille | Type | Accès | Persistance | Remarques |
|---|---|---|---|---|---|---|
0x46 |
UPTIME_S |
4 | u32 LE | r | ram | Compteur de temps de fonctionnement propre au module (en principe des secondes depuis le démarrage) — détecteur de redémarrage uniquement : sur les firmwares jusqu'à 1.4.21, il tourne plus lentement que l'horloge murale (mesuré 0.58–0.80×), donc ne l'utilisez jamais comme horloge. Détection de redémarrage pour un maître : la valeur a diminué, ou elle est inférieure au temps écoulé depuis le dernier instantané du maître |
0x4A |
RESET_CAUSE |
1 | u8 | r | ram | Indicateurs de cause de réinitialisation (bit0=PIN, bit1=POR/BOR, bit2=SW, bit3=IWDG, bit4=WWDG, bit5=LPWR). Pour la journalisation uniquement — la gestion du redémarrage est la même quelle qu'en soit la cause |
0x4B |
I2C_ERR_COUNT |
2 | u16 LE | r | ram | Erreurs de bus (BERR+OVR) depuis le démarrage, saturant |
0x4D |
I2C_REINIT_COUNT |
1 | u8 | r | ram | Nombre de réinitialisations I²C après récupération BUSY du périphérique, saturant |
0x4E |
ZC_OFFSET |
2 | u16 LE | r | ram | µs entre le front STOP du dernier instantané GC et le prochain passage par zéro de la tension — utilisé pour la compensation de phase U/I dans le calcul de puissance. Forcé à 0xFFFF au niveau firmware sur les variantes I uniquement (pas d'étage d'entrée de tension → pas de passage par zéro de tension). Ce n'est pas la source de passage par zéro de la fréquence secteur — AC_FREQ (0x20) est dérivé d'une broche dédiée de passage par zéro secteur et est disponible sur toutes les variantes. |
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | — | Registres de santé BASIC non exposés (ligne STD uniquement) |
| ESP-IDF | rbamp_read_uptime_s() |
lire le temps de fonctionnement du module en secondes |
| Python | — | Registres de santé BASIC non exposés (ligne STD uniquement) |
| ESPHome | — | aucune entité de temps de fonctionnement ou de santé |
4.7 Miroirs de vérification du modèle CT (0x51..0x53)
Miroirs en lecture seule du préréglage du modèle CT appliqué par canal. Le protocole d'écriture reste inchangé (voir §6.2) — il s'agit uniquement d'une relecture pour vérification.
| Adr | Nom | Taille | Type | Accès | Persistance | Remarques |
|---|---|---|---|---|---|---|
0x51 |
CT_MODEL_CH0 |
1 | u8 | r | user_config | Préréglage du modèle CT appliqué sur ch0 (miroir de vérification) |
0x52 |
CT_MODEL_CH1 |
1 | u8 | r | user_config | Préréglage du modèle CT appliqué sur ch1 |
0x53 |
CT_MODEL_CH2 |
1 | u8 | r | user_config | Préréglage de modèle CT appliqué sur ch2 |
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmp::readCTModelCh(channel, out) |
lire le modèle CT réellement appliqué sur un canal |
| ESP-IDF | rbamp_read_ct_model_ch() |
lire le modèle CT réellement appliqué sur un canal |
| Python | dev.read_ct_model_ch(ch) |
lire le modèle CT réellement appliqué sur un canal |
| ESPHome | journal de démarrage ct_model[0]: matches |
lignes de journal confirmant que la classe et le modèle du capteur ont été appliqués |
4.8 Identité (0x54..0x6F)
| Adr | Nom | Taille | Type | Accès | Persistance | Remarques |
|---|---|---|---|---|---|---|
0x54 |
PRODUCT_ID |
1 | u8 | r | rom | Famille : 0x01 = capteur rbAmp. Le maître lit ceci avant tout registre propre à la famille |
0x55 |
HW_VARIANT |
1 | u8 | r | rom | Voir §3.1 |
0x56 |
FW_TIER |
1 | u8 | r | rom | bits 0-1 : 0=BASIC, 1=STANDARD (2 = non implémenté) ; bit 2=bidirectionnel ; bit 3=étalonné par LUT |
0x57 |
CAPABILITY |
2 | u16 LE | r | rom | Voir §3.2 |
0x59 |
GC_TICK |
2 | u16 LE | r | ram | Tick du maître à partir de la dernière trame GC acceptée ; 0xFFFF = jamais reçue |
0x5C |
UID |
12 | octets | r | rom | UID de puce de 96 bits. Une seule lecture en rafale. |
0x68 |
LABEL |
8 | octets | rw | user_config | Étiquette d'emplacement utilisateur (ASCII, complétée de zéros). Vide = non défini. Écrire octet par octet (voir §5.1) |
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmp::readProductId() / RbAmp::readUid(uid) |
lire l'identifiant de famille ; lire l'UID 96 bits |
| ESP-IDF | rbamp_read_product_id() / rbamp_read_uid() |
lire l'identifiant de famille ; lire l'UID 96 bits |
| Python | dev.read_product_id() / dev.read_uid() |
lire l'identifiant de famille ; lire l'UID 96 bits |
| ESPHome | get_uid_hex() / get_variant_str() |
l'UID en hexadécimal ; la variante en texte |
4.9 Fenêtre de digest (0x70..0x85)
DIGEST est une fenêtre d'interrogation compacte, servie par une seule lecture en rafale. Sa composition est choisie par DIGEST_CONFIG (0x29) ; une écriture qui règle un bit non pris en charge est rejetée avec ERR_PARAM :
DIGEST_CONFIG bit |
Contenu | Format |
|---|---|---|
| bit 0 | I_RMS[N] |
u16 par canal, 0.01 A |
| bit 1 | U_RMS |
u16, 0.1 V (variante à mesure de tension seulement) |
| bit 2 | P_REAL[N] |
i16 par canal, 1 W (has_power seulement) |
| bit 3 | PF[N] |
u8 par canal, 0..100 (has_power uniquement) |
| Adr | Nom | Taille | Type | Accès | Persistance | Remarques |
|---|---|---|---|---|---|---|
0x70 |
DIGEST |
22 | octets | r | ram | Format : [STATUS_MIRROR u8][SEQ u8] + champs activés par masque. La charge utile maximale (masque UI3 complet) est de 19 o + 2 o d'en-tête = 21 o utilisés ; 1 o de queue inutilisé (lit 0x00). SEQ s'incrémente à chaque commit RT, de 255 à 0. Atomique par gel de lecture (voir §5.4). |
La disposition est dynamique selon DIGEST_CONFIG — chaque bit activé ajoute ses champs dans un ordre fixe : I_RMS[N] → U_RMS → P[N] → PF[N]. Les bits désactivés ne laissent aucun remplissage — les champs se décalent vers l'avant. Le maître doit analyser avec le même masque que celui qu'il a écrit dans DIGEST_CONFIG. Une lecture en rafale de 22 octets est sûre (la queue vaut 0x00 dès que la charge utile totale est < 22 octets). L'octet de queue est toujours 0x00 (réservé).
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | — | fenêtre de digest non exposée |
| ESP-IDF | rbamp_set_digest_fields() / rbamp_read_digest() |
choisir les champs de digest ; les lire en une seule transaction (BASIC) |
| Python | — | fenêtre de digest non exposée |
| ESPHome | — | fenêtre de digest non exposée |
4.10 Bloc temps réel V03 (0x86..0xBD)
Tous en float32 LE (virgule flottante simple précision IEEE 754, ordre des octets little-endian standard). La disposition octet par octet est figée depuis la v1.2. Chaque registre est en accès r, persistance ram, groupe v03_rt. Atomique par gel de lecture (voir §5.4) : une lecture en rafale de 56 octets (0x86..0xBD) est garantie contiguë (pas d'instantané déchiré).
| Adr | Nom | Taille | Type | Accès | Persistance | Unités | Remarques |
|---|---|---|---|---|---|---|---|
0x86 |
V03_U_RMS |
4 | float32 LE | r | ram | V | 0.0 sur les variantes I |
0x8A |
V03_U_PEAK |
4 | float32 LE | r | ram | V | |
0x8E |
V03_I0_RMS |
4 | float32 LE | r | ram | A | |
0x92 |
V03_I1_RMS |
4 | float32 LE | r | ram | A | 0.0 si la variante n'a pas ch1 |
0x96 |
V03_I2_RMS |
4 | float32 LE | r | ram | A | 0.0 si la variante n'a pas ch2 |
| ⛔ | STOP — la carte RMS plate par canal s'arrête au canal 2. | La ligne suivante (0x9A) est V03_I0_PEAK, PAS V03_I3_RMS. NE PAS extrapoler le schéma de l'étape 4 au-delà du canal 2 — vous lirez des nombres plausibles mais silencieusement faux (crête, pas RMS ; canal 0, pas canal 3). Les canaux 3+ (UI5/UI7) ne sont accessibles que par la fenêtre d'accès aux canaux — voir §4.14. |
|||||
0x9A |
V03_I0_PEAK |
4 | float32 LE | r | ram | A | |
0x9E |
V03_I1_PEAK |
4 | float32 LE | r | ram | A | |
0xA2 |
V03_I2_PEAK |
4 | float32 LE | r | ram | A | |
0xA6 |
V03_P0_REAL |
4 | float32 LE | r | ram | W | 0.0 sur les variantes I (pas de calcul de puissance) |
0xAA |
V03_P1_REAL |
4 | float32 LE | r | ram | W | |
0xAE |
V03_P2_REAL |
4 | float32 LE | r | ram | W | |
0xB2 |
V03_PF0 |
4 | float32 LE | r | ram | – | plage −1..+1 |
0xB6 |
V03_PF1 |
4 | float32 LE | r | ram | – | |
0xBA |
V03_PF2 |
4 | float32 LE | r | ram | – |
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmp::readAll(snapshot) / RbAmp::channels() |
lire le bloc temps réel complet ; nombre de canaux de courant |
| ESP-IDF | rbamp_read_all() / rbamp_channels() |
lire le bloc temps réel complet ; nombre de canaux de courant |
| Python | dev.read_all() / dev.channels |
lire le bloc temps réel complet ; nombre de canaux de courant |
| ESPHome | voltage / power |
Capteurs YAML pour les valeurs temps réel |
4.11 Bloc de période V03 (0xBE..0xCF)
Un instantané de période pris sur CMD_LATCH_PERIOD. Disposition hétérogène (héritage historique de la v1.2, figée en v1.3) : avg_p pour ch1/ch2 se trouve ici, tandis que avg_p pour ch0 se trouve au §4.12 à l'adresse 0xDC (la primitive d'énergie historique n'a pas été déplacée, pour éviter une rupture d'API pour les intégrateurs existants). Logiquement, ces trois valeurs appartiennent au même groupe.
| Adr | Nom | Taille | Type | Accès | Persistance | Unités | Remarques |
|---|---|---|---|---|---|---|---|
0xBE |
V03_PERIOD_COMMIT_CNT |
4 | u32 LE | r | ram | – | Commits RT dans la période close. Un commit = 0.1 s depuis la v1.2 (0.2 s avant) — count × la longueur du commit est la mesure propre du module de la longueur de fenêtre (voir §7.4) |
0xC2 |
V03_PERIOD_AVG_P_CH1 |
4 | float32 LE | r | ram | W | P moyenne de l'instantané, canal 1 (UI2, UI3) |
0xC6 |
V03_PERIOD_AVG_P_CH2 |
4 | float32 LE | r | ram | W | P moyenne de l'instantané, canal 2 (UI3) |
0xCA |
V03_PERIOD_MS |
4 | u32 LE | r | ram | ms | Durée de la période en cours |
0xCE |
V03_STATUS |
1 | u8 | r | ram | – | bit 0 = valide (résultat de validation temps réel). NON effacé à la lecture. Le maître interroge STATUS (0x00) pour attendre l'état prêt. L'alias DATA_VALID est parfois utilisé pour ce registre dans les chapitres de tutoriel — même adresse, même sémantique. |
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmp::readPeriodAvgPower(ch) / RbAmp::readPeriodSnapshot() |
lire la puissance moyenne de période ; prendre et lire un instantané de période complet |
| ESP-IDF | rbamp_read_period_avg_power() / rbamp_read_period_snapshot() |
lire la puissance moyenne de période ; prendre et lire un instantané de période complet |
| Python | dev.read_period_avg_power(ch) / dev.read_period_snapshot() |
lire la puissance moyenne de période ; prendre et lire un instantané de période complet |
| ESPHome | update_interval: / latch_interval: |
options YAML pour la cadence de période et d'instantané |
4.12 V03 Q + période canal 0 (0xD0..0xE3, build de production)
| Adr | Nom | Taille | Type | Accès | Persistance | Unités | Remarques |
|---|---|---|---|---|---|---|---|
0xD0 |
V03_Q0_REAC |
4 | float32 LE | r | ram | VAr | Puissance réactive canal 0 = √(S² − P²), S = U_rms × I_rms — non signée (≥ 0), inclut la puissance de distorsion ; 0 sur les variantes I uniquement ; bruitée près de PF ≈ 1. Précision non spécifiée |
0xD4 |
V03_Q1_REAC |
4 | float32 LE | r | ram | VAr | |
0xD8 |
V03_Q2_REAC |
4 | float32 LE | r | ram | VAr | |
0xDC |
V03_PERIOD_AVG_P |
4 | float32 LE | r | ram | W | Primitive d'énergie de PRODUCTION : instantané de la P moyenne du canal 0, ≥ 0 (pince unidirectionnelle BASIC). Regroupée logiquement avec V03_PERIOD_AVG_P_CH1/CH2 (§4.11) ; la disposition historique est conservée pour compatibilité |
0xE0 |
V03_PERIOD_MAX_P |
4 | float32 LE | r | ram | W | P de crête instantané du canal 0 sur cette période |
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmp::readPeriodAvgPower(ch) / RbAmp::readPeriodMaxPower() |
lire la moyenne et la puissance maximale de la période |
| ESP-IDF | rbamp_read_period_avg_power() / rbamp_read_period_max_power() |
lire la moyenne et la puissance maximale de la période |
| Python | dev.read_period_avg_power(ch) / dev.read_period_max_power() |
lire la moyenne et la puissance maximale de la période |
| ESPHome | reactive_power / update_interval: |
capteur de puissance réactive ; chaque mise à jour ferme la période et lit les moyennes |
4.13 dt côté puce de diagnostic (0xEC)
| Adr | Nom | Taille | Type | Accès | Persistance | Unités | Remarques |
|---|---|---|---|---|---|---|---|
0xEC |
V03_PERIOD_LATCH_MS |
4 | u32 LE | r | ram | ms | dt côté puce entre les deux derniers instantanés. Minuteur de diagnostic du module — il peut afficher une valeur courte sous charge ; utilisez l'horloge maître pour l'énergie. Voir §7.4 |
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmp::readPeriodLatchMs() |
lire la longueur de période côté module (diagnostic uniquement) |
| ESP-IDF | rbamp_read_period_latch_ms() |
lire la longueur de période côté module (diagnostic uniquement) |
| Python | dev.read_period_latch_ms() |
lire la longueur de période côté module (diagnostic uniquement) |
| ESPHome | — | non exposé |
4.14 Fenêtre d'accès aux canaux (0x32 + 0x3C..0x3F)
S'applique aux modules UI5 (5 canaux) et UI7 (7 canaux). Sur UI1/UI2/UI3 et I1/I2/I3, il est également disponible — une voie unifiée unique si vous la préférez aux registres plats du §4.10.
Les canaux 3..6 n'ont pas de registres à plat par canal (il y avait la place pour 8 octets dans l'espace d'adresses 8 bits, et une disposition à plat aurait nécessité ~88). On expose donc une fenêtre de sélection puis lecture :
| Adr | Nom | Taille | Type | Accès | Persistance | Remarques |
|---|---|---|---|---|---|---|
0x32 |
REG_CHANNEL_SELECT |
1 | u8 | rw | ram | Il s'agit de l'adresse d'un registre, PAS de l'opcode de commande CMD_SAVE_USER_CONFIG — elles entrent en collision numérique. Citez toujours 0x32 en précisant l'espace registre ou commande visé. Encodé comme (field << 4) \| channel. La plage du nibble channel est 0..15 (réservée à jusqu'à 16 canaux) ; le maximum physique par référence est channels() (7 sur UI7). Un sélecteur dont l'index de canal est >= channels() est accepté sans ERR_PARAM ; la fenêtre de données renvoie alors 0 et les écritures y sont ignorées. field selon le tableau ci-dessous. Écrire le sélecteur copie la valeur demandée dans REG_CHANNEL_DATA. |
0x3C..0x3F |
REG_CHANNEL_DATA |
4 | float32 LE | r | ram | Tampon de données pour la sélection. float32 LE pour tous les champs publics. |
Codes de champ (demi-octet haut dans 0x32) :
| Code | Champ | Type | Accès | Signification |
|---|---|---|---|---|
0 |
CHFIELD_I_RMS |
float32 LE | r | Courant efficace RMS en direct pour le canal sélectionné (unité A) |
1 |
CHFIELD_I_PEAK |
float32 LE | r | Courant de crête en direct (unités A) |
2 |
CHFIELD_P_REAL |
float32 LE | r | Puissance active réelle en direct (unité W) |
3 |
CHFIELD_PF |
float32 LE | r | Facteur de puissance en direct (−1..+1) |
4..12 |
(reserved) | – | – | Non documenté pour le code utilisateur ; ne dépendez pas des valeurs ni des codes. |
13 |
CHFIELD_PERIOD_AVG_P |
float32 LE | r | Puissance active moyenne sur la période d'instantané (W). Pour les canaux 3 et plus, c'est le SEUL champ de période/énergie — les registres plats V03_PERIOD_AVG_P* (§4.11/§4.12) ne couvrent que ch0..ch2. |
14 |
(reserved) | – | – | Réservé aux firmwares futurs ; ne vous y fiez pas. |
15 |
CHFIELD_CT_MODEL |
u8 dans 0x3C (les octets 0x3D..0x3F sont lus comme bourrage à zéro) |
rw | Firmware ≥ 1.4.18. Code du modèle de pince par canal pour le canal sélectionné (0..N-1). La lecture renvoie le modèle appliqué sur le canal. L'écriture ne touche que la RAM et s'applique immédiatement : l'échelle du canal passe au préréglage du modèle sélectionné dans la même transaction ; pas de commande de validation séparée, CMD_SET_CT_MODEL_CH* n'est pas nécessaire. Les écritures se font octet par octet selon la règle du protocole filaire (§5.1). Une paire (SENSOR_CLASS, code) inconnue renvoie ERR_PARAM (0xFE) et le canal conserve son modèle précédent — aucun état partiel. Les canaux des références supérieures (ch3+) n'héritent PLUS du modèle global — chaque canal doit être configuré explicitement via le champ 15. Persistance : CMD_SAVE_USER_CONFIG (opcode 0x32 sur REG_COMMAND, non verrouillée) enregistre les modèles de tous les canaux dans la page flash de configuration utilisateur en une seule commande. Une écriture sans CMD_SAVE_USER_CONFIG ultérieure revient à l'état précédent au redémarrage. L'ensemble des paires (class, code) acceptées est défini par la table de modèles de votre version de firmware ; le module confirme un code de façon faisant foi — écrivez-le, relisez-le et vérifiez REG_ERROR. Sur les modules v1.4.0, l'écriture de ce champ renvoie ERR_PARAM ; utilisez plutôt les commandes par canal et la préparation à plat REG_CT_MODEL. |
Les quatre pièges — à lire avant d'écrire du code
- ⛔ Le RMS plat par canal s'arrête au canal 2. Les lignes
V03_I0_RMS(0x8E) →V03_I1_RMS(0x92) →V03_I2_RMS(0x96) ont un pas de 4, et0x9Aprolonge ce pas — mais0x9AestV03_I0_PEAK, pasV03_I3_RMS. Extrapoler le motif renvoie silencieusement le pic du canal 0 au lieu du RMS du canal 3. Le firmware ne peut pas détecter l'erreur ; la valeur paraît plausible. Les canaux 3 et plus ne sont accessibles que par la fenêtre d'accès aux canaux. - Resélectionnez avant chaque lecture.
REG_CHANNEL_DATAest un instantané pris au moment de l'écriture du sélecteur, et non une vue en direct. Interroger0x3C..0x3Fen boucle sans réécrire0x32renvoie une valeur figée indéfiniment. Chaque nouvelle lecture exige une nouvelle écriture dans0x32. 0x32adresse de registre ≠ opcode de commande0x32.CMD_SAVE_USER_CONFIGutilise l'opcode0x32écrit dansREG_COMMAND(0x01) — il s'agit d'un espace d'adresses différent deREG_CHANNEL_SELECT(situé à l'adresse de registre0x32). Ne citez jamais0x32sans préciser l'espace.- Pour les canaux 3 et plus, la période et l'énergie proviennent uniquement du champ
13(CHFIELD_PERIOD_AVG_P). Les registresV03_PERIOD_AVG_P*(0xC2/0xC6/0xDC) ne couvrent que les canaux 0/1/2. Il n'existe pas deV03_PERIOD_AVG_P_CH3plat — lisez le champ 13 via la fenêtre à la place.
Exemple au niveau du fil — lire le courant RMS du canal 3
# select field=0 (I_RMS), channel=3 → (0 << 4) | 3 = 0x03
write_u8(REG_CHANNEL_SELECT=0x32, 0x03)
# read 4 bytes at REG_CHANNEL_DATA — float32 LE
bytes = read(0x3C, 4)
i3_rms = unpack_float32_le(bytes) # amperes
Pour le courant de crête du canal 4 : sélecteur = (1 << 4) | 4 = 0x14, puis lire 0x3C..0x3F. Pour la puissance moyenne de période du canal 5 : sélecteur = (13 << 4) | 5 = 0xD5, puis lire 0x3C..0x3F.
Exemple au niveau du fil — lire le courant efficace sur TOUS les canaux d'un module UI7
Combine les deux chemins dans une seule boucle : bloc RT à plat pour ch 0..2, fenêtre d'accès aux canaux pour ch 3..6.
# --- Discover physical channel count -----------------------------
N = read_u8(TOPOLOGY=0x24) # 5 on UI5, 7 on UI7
# --- ch 0..2 via flat block (single 12-byte burst) ---------------
bytes = read(V03_I0_RMS=0x8E, 12)
i0 = unpack_float32_le(bytes[0:4])
i1 = unpack_float32_le(bytes[4:8])
i2 = unpack_float32_le(bytes[8:12])
# --- ch 3..N-1 via channel access window (re-select per read) ----
i_rms = [i0, i1, i2]
for ch in range(3, N):
write_u8(REG_CHANNEL_SELECT=0x32, (0 << 4) | ch) # field 0 = I_RMS
i_rms.append(unpack_float32_le(read(REG_CHANNEL_DATA=0x3C, 4)))
# i_rms is now length-N: RMS current for every physical channel of the module.
Le même schéma s'étend à I_PEAK (champ 1), P_REAL (champ 2), PF (champ 3) et à l'instantané PERIOD_AVG_P (champ 13) — bloc à plat pour ch0..ch2, fenêtre pour ch3+. Le champ 13 est la SEULE source période/énergie pour ch3+ — le bloc à plat n'a pas de V03_PERIOD_AVG_P_CH3..6.
Pour la configuration du modèle CT par canal sur n'importe quel canal (0..N-1), utilisez le champ de fenêtre 15 (CHFIELD_CT_MODEL) : écrivez (15 << 4) | ch dans 0x32, puis écrivez le code de modèle sur un octet dans 0x3C. Enregistrez les modèles de tous les canaux avec un seul CMD_SAVE_USER_CONFIG (code d'opération 0x32 sur REG_COMMAND (0x01) — sans garde).
Recommandation pour les nouvelles intégrations
La fenêtre couvre les canaux 0..6 — vous pouvez l'utiliser comme chemin unifié pour tous les canaux, au lieu de bifurquer entre registres à plat (ch0..ch2) et fenêtre (ch3..ch6). Pour les flottes mêlant références junior (UI1/UI2/UI3) et senior (UI5/UI7), cela supprime une division du code. La latence équivaut à une petite écriture supplémentaire par lecture (par rapport à une lecture en rafale directe du bloc à plat).
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmp::readCurrent(ch) / RbAmp::channels() |
lire n'importe quel canal par index ; nombre de canaux |
| ESP-IDF | rbamp_read_channel() / rbamp_read_all_channels() |
lire un canal par index, canaux 3 et suivants inclus ; lire tous les canaux |
| Python | dev.current[ch] / dev.channels |
index sur les canaux valides ; nombre de canaux |
| ESPHome | current_N: |
emplacements de capteur par canal, jusqu'à sept canaux de courant |
5 · Protocole filaire
5.1 Asymétrie LECTURE / ÉCRITURE
Comportement canonique voulu par conception :
| Sens | Auto-incrémentation | Motif |
|---|---|---|
| LECTURE (lecture en rafale de N octets) | ✅ OUI | read(addr, N) renvoie N octets consécutifs à partir de addr. |
| ÉCRITURE (registres multi-octets) | ❌ NON | Un registre multi-octets s'écrit octet par octet — une transaction distincte d'un octet par adresse. Une écriture en rafale perd les octets 1..N-1 et n'accepte que le premier. |
Registres multi-octets inscriptibles concernés (écriture octet par octet)
LABEL(0x68-0x6F, 8 octets)THRESH_I_HI(0x2C, 2 octets u16 LE)THRESH_P_HI(0x2E, 2 octets u16 LE)
Ordre des octets pour l'écriture multi-octets : l'octet à l'adresse inférieure est l'octet faible (LE). Par exemple, pour écrire THRESH_I_HI = 0x1234 (4660 en décimal) :
# CORRECT: low byte first (LE)
write(addr=0x2C, value=0x34) # LO byte
write(addr=0x2D, value=0x12) # HI byte
Exemple FAUX / CORRECT (pseudo-code)
# WRONG — only 'M' (first byte) is accepted, the rest are dropped
write(addr=0x50, reg=0x68, data=b"MyMeter1") # 8-byte burst
# CORRECT — byte-at-a-time loop
label = b"MyMeter1"
for i, byte in enumerate(label):
write(addr=0x50, reg=0x68 + i, data=byte)
Exception — trame de diffusion General Call
La trame de diffusion GC (adresse d'appel général 0x00 + charge utile de 5 octets) est un chemin de protocole filaire distinct, pas une écriture de registre. L'asymétrie lecture/écriture du §5.1 ne s'applique pas au GC. Voir §6.3.
5.2 Comportement des registres non cartographiés
Toute lecture d'une adresse non mappée renvoie 0x00. Le firmware ne renvoie jamais de NACK sur les lectures de registres. C'est volontaire (correctif de blocage du bus).
Conséquence pour la détection : la détection d'un appareil absent doit passer par l'ACK de l'adresse I²C, et non par des sondes de registres.
5.3 Modèle d'erreur
Référence v1.3 :
REG_ERROR (0x02)est le résultat de la dernière écriture, NON persistant. À chaque écriture de registre, le firmware metreg_error = ERR_OK; toute écriture ultérieure sans rapport efface l'erreur précédente.EVENT_FLAGS (0x2A) bit 3est le signal persistant (sticky W1C), activé sur toute écriture ou commande rejetée.
Codes d'erreur
| Code | Nom | Gravité |
|---|---|---|
0x00 |
OK | – |
0xF9 |
CLONE |
réservé — jamais levé |
0xFA |
LUT_BAD |
erreur |
0xFB |
FLASH_PARAMS_BAD |
erreur (voir §6.5 flash neuf) |
0xFC |
NOT_READY |
erreur |
0xFD |
SENSOR_OVERFLOW |
erreur |
0xFE |
PARAM |
erreur (écriture rejetée — argument invalide / opcode inconnu / énumération hors plage ; lève EVENT.bit3. Les tout premiers images, 1.2–1.4.3, ignoraient silencieusement les opcodes inconnus) |
0xFF |
UNHANDLED |
erreur |
disposition de EVENT_FLAGS (0x2A) (W1C persistant)
| bit | Nom | Remarques |
|---|---|---|
| 0 | PERIOD_READY |
instantané de période disponible |
| 1 | THRESH_I |
I_rms a franchi THRESH_I_HI |
| 2 | THRESH_P |
La somme P a dépassé THRESH_P_HI |
| 3 | ERROR |
REG_ERROR != 0 (signal d'erreur persistant) |
| 4 | CONFIG_CHANGED |
classe/modèle/adresse/étiquette modifiés |
| 5 | RESET_OCCURRED |
module redémarré (positionné au démarrage jusqu'au W1C). Le maître doit réinitialiser la configuration en RAM. |
Motifs d'erreur de référence
Schéma 1 — capture ponctuelle après opération (résultat de cette seule opération) :
write target_reg(...)
err = read_u8(0x02) # IMMEDIATELY after the operation, before the next write
Schéma 2 — surveillance persistante (référence pour un maître en fonctionnement continu) :
event_flags = read_u8(0x2A)
if event_flags & (1 << 3): # ERROR bit
last_err = read_u8(0x02)
# handle
write_u8(0x2A, 1 << 3) # W1C clear bit 3
# or CMD_CLEAR_ERROR
⚠ mise en garde sur le bit 3 asynchrone
Un rejet d'écriture lève EVENT_FLAGS.bit3 de façon asynchrone, dans une fenêtre de mesure (~100 ms depuis la v1.2 ; 200 ms sur les images antérieures à la v1.2) après l'opération, et non immédiatement. N'interrogez pas le bit 3 juste après une écriture — attendez ≥ 200 ms (couvre toutes les images), ou utilisez le schéma 1 (capture immédiate de REG_ERROR) pour connaître le résultat d'une opération précise, et réservez l'interrogation du bit 3 à la surveillance longue durée.
Sentinelle anti-clonage
DEV_ERR_CLONE (0xF9) est réservé — il n'est jamais levé. Le code est conservé pour la compatibilité future.
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmp::readLastError() / RbAmp::hasError(out) |
lire le code d'erreur de la dernière écriture ; lire l'indicateur d'erreur durable |
| ESP-IDF | rbamp_read_last_error() / rbamp_has_error() |
lire le code d'erreur de la dernière écriture ; lire l'indicateur d'erreur durable |
| Python | dev.read_last_error() / dev.has_error() |
lire le code d'erreur de la dernière écriture ; lire l'indicateur d'erreur durable |
| ESPHome | get_last_error_str() / get_event_flags() |
le code d'erreur sous forme de texte ; les indicateurs d'événements |
5.4 Sémantique d'atomicité / gel de lecture
5.4.1 Gel de lecture présent (atomique — PAS déchiré)
Ces blocs sont protégés par un gel de lecture côté firmware. Une lecture en rafale est atomique vis-à-vis de la commit RT :
- Bloc V03 RMS / P / PF (0x86..0xBD) — le bloc flottant complet.
- Bloc digest (0x70..0x85).
Les lectures en rafale de ces plages sont sûres — il n'y a pas d'échantillon coupé entre deux validations consécutives.
5.4.2 Pas de gel de lecture — read-twice-agree recommandé
Ces registres sont mis à jour de façon asynchrone, sans gel de lecture intra-lecture. Les lectures d'un octet sont tolérantes, mais la valeur peut changer entre deux transactions :
GC_TICK (0x59)— compteur de tops GC.I2C_ADDRESS (0x30)— miroir de préparation en RAM.CT_MODEL_CH0/1/2 (0x51..0x53)— miroirs de vérification.
Schéma pour des lectures fiables :
val1 = read_u8(addr)
val2 = read_u8(addr)
if val1 == val2:
return val1 # stable
else:
retry # value changed between reads
5.4.3 Sémantique de la pince NF
I_RMS = 0x00000000 signifie « signal sous le plancher de bruit » (le firmware calcule rms_corr² = max(0, raw² − nf²)), PAS « pas de données » / « erreur ». C'est une mesure valide pour les scénarios à vide ou à très faible charge.
Le code maître ne doit pas interpréter I_RMS = 0.0 comme une erreur ou une donnée manquante.
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmp::readAll(snapshot) |
lire tout le bloc temps réel en un seul appel |
| ESP-IDF | rbamp_read_all() |
lire tout le bloc temps réel en un seul appel |
| Python | dev.read_all() |
lire tout le bloc temps réel en un seul appel |
| ESPHome | lecture en rafale du bloc instantané | le composant lit le bloc instantané en une seule rafale à chaque mise à jour |
6 · Séquences de protocole
6.0 Chronologie du démarrage à froid
Après POR (reset à la mise sous tension) ou reset matériel, le module passe par les phases suivantes :
| Temps depuis la mise sous tension (POR) | État |
|---|---|
| 0 ms | POR — tous les registres en état de reset, SCL/SDA en haute impédance |
| ~10 ms | Réactif sur le bus (le module envoie ACK à son adresse) |
| ~50 ms | Première validation temps réel (le bloc RT à partir de 0x86 contient des données valides ; STATUS.bit0 = 1) |
| ~60-80 ms | Premier V03_STATUS.bit0 valide (le pipeline RT a parcouru une période secteur complète) |
| ~100 ms | Le premier CMD_LATCH_PERIOD peut renvoyer V03_PERIOD_VALID = 1 (l'instantané exige au moins 1 période du secteur d'accumulation ; environ 200 ms sur les images antérieures à la v1.2) |
| ~250 ms | Toutes les mesures stables (typique) |
Démarrage à froid complet jusqu'à la première mesure valide ≈ 250 ms (typique). Après un CMD_RESET logiciel, la chronologie est identique (la machine d'état de réinitialisation complète s'exécute).
Séquence d'initialisation du maître :
1. wait ~50 ms after VCC stable
2. probe slave address (read PRODUCT_ID = 0x54); retry up to 300 ms on NACK
3. read identity (HW_VARIANT 0x55, CAPABILITY 0x57/0x58); validate
4. check REG_ERROR (0x02):
- 0x00 — normal boot
- 0xFB — fresh flash, provisioning required (§6.5)
- other — see §6.7 error-state recovery
5. configure (SENSOR_CLASS, CT_MODEL, FLEET_CONFIG, etc.)
6. poll STATUS (0x00) until bit0 = 1 (READY) — usually immediate after step 5
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmp::begin() / RbAmp::waitReady(timeout_ms) |
interroger le module, puis attendre le drapeau de disponibilité |
| ESP-IDF | rbamp_begin() / rbamp_wait_ready() |
interroger le module, puis attendre le drapeau de disponibilité |
| Python | dev.begin() / dev.wait_ready(timeout_ms=1000) |
interroger le module, puis attendre le drapeau de disponibilité |
| ESPHome | rbamp: address: |
adresse du module réglée en YAML ; le composant sonde le module au setup |
6.1 Changement d'adresse — commit à deux phases (compatible production)
Protocole filaire (référence v1.3) :
1. write candidate_addr (1 byte) → REG_I2C_ADDRESS (0x30) # RAM staging, not persisted
2. write 0xA5 → REG_ADDR_COMMIT_MAGIC (0x31) # arm commit
3. issue CMD_COMMIT_ADDR (opcode 0x30 in REG_COMMAND) # persists into flash
4. wait ~700 ms (flash write completion; see §6.6 settle)
5. issue CMD_RESET (opcode 0x01) # module resets
6. wait ~300 ms boot-to-responsive
7. verify: bus-probe the new address (ACK = success)
: CMD_COMMIT_ADDR ne réinitialise PAS automatiquement le module — un CMD_RESET explicite est requis à l'étape 5. Si le maître saute ce reset explicite, la nouvelle adresse reste enregistrée en flash, mais l'ancienne reste active jusqu'au prochain reset externe (coupure d'alimentation, broche de reset matériel, IWDG).
Guarantees:
- Le changement d'adresse fonctionne en mode production (non réservé à l'usine).
REG_I2C_ADDRESS (0x30)au démarrage lit l'adresse active (référence v1.3). Jusqu'au redémarrage après préparation, il renvoie le candidat.- L'adresse est exclue de l'espace de noms
CMD_SAVE_GAINS/CMD_SAVE_USER_CONFIG— elle n'est persistée que viaCMD_COMMIT_ADDR.
Temporisation de la fenêtre de démarrage pour la vérification :
- Au minimum 300 ms entre la mise sous tension et la réponse.
- Fenêtre de reprise sur la nouvelle adresse : ~1 s au total (si un NACK persiste après 1 à 2 reprises, un délai de démarrage supplémentaire peut être nécessaire).
- Dès que la nouvelle adresse répond par ACK, vérifiez éventuellement en lisant
0x30(qui reflète désormais la nouvelle adresse active) pour confirmation.
Modes de défaillance :
ADDR_COMMIT_MAGICnon armé →CMD_COMMIT_ADDR→REG_ERROR = ERR_PARAM (0xFE).- Candidat hors plage (< 0x08 ou > 0x77) →
ERR_PARAM. - délai de 5 s sans validation → le magic est effacé ; l'étape
preparedoit être répétée.
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmp::prepareAddressChange(new_addr) / RbAmp::commitAddressChange() |
préparer et armer la nouvelle adresse, puis la valider |
| ESP-IDF | rbamp_prepare_address_change() / rbamp_commit_address_change() |
préparer et armer la nouvelle adresse, puis la valider |
| Python | dev.prepare_address_change(new_addr) / dev.commit_address_change() |
préparer et armer la nouvelle adresse, puis la valider |
| ESPHome | new_address: |
changement d'adresse ponctuel au démarrage ; supprimez l'option ensuite |
6.2 Liaison du modèle de pince — simple préparation + CMD par canal
Sur les images antérieures au firmware 1.4.20 (bit 12 de CAPABILITY à 0), l'échelle appliquée par modèle revient à la valeur d'usine après un redémarrage du module — réappliquez et validez CT_MODEL par canal après chaque redémarrage détecté, faute de quoi l'énergie sera fausse.
Référence v1.3 à préparation pure : écrire REG_CT_MODEL (0x05) n'applique plus automatiquement le préréglage à ch0. La liaison ne se fait que par CMD_SET_CT_MODEL_CHn.
Protocole filaire canonique par canal (indépendant de l'ordre en v1.3) :
1. write REG_SENSOR_CLASS (0x25) = sct013 # if not already set
2. write REG_CT_MODEL (0x05) = model_code # stages, applies nothing
3. issue CMD_SET_CT_MODEL_CHn (opcode 0x28/0x29/0x2A for ch0/1/2)
# VALIDATES (class, model) + binds to channel n
4. wait 5 ms settle
5. (optional) issue CMD_SAVE_USER_CONFIG (opcode 0x32) for persistence
Indépendant de l'ordre : en v1.3, les canaux peuvent être configurés dans n'importe quel ordre — ch0 en premier, en dernier, comme vous voulez. Le contournement « lier ch0 en dernier » de la v1.2 n'est plus nécessaire.
Vérification par relecture : après la liaison, lisez CT_MODEL_CH0/1/2 (0x51..0x53) — ils reflètent l'état appliqué par canal.
Modes de défaillance (la validation de (classe, modèle) se fait à l'étape de liaison CMD_SET_CT_MODEL_CHn, et non à l'écriture en préparation pure sur 0x05) :
SENSOR_CLASS = 0(NON DÉFINI) lorsqueCMD_SET_CT_MODEL_CHnest émis →REG_ERROR = ERR_PARAM.CT_MODELhors de 1..7 (SCT-013-005/-010/-030/-050/-100/-020/-060) lors d'unCMD_SET→ERR_PARAM.
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmp::setSensorClass(cls) / RbAmp::setCTModel(channel, code) |
réglez la classe du capteur et le modèle de pince par canal |
| ESP-IDF | rbamp_set_sensor_class() / rbamp_set_ct_model_ch() |
réglez la classe du capteur et le modèle de pince par canal |
| Python | dev.set_sensor_class(cls) / dev.set_ct_model_ch(channel, code) |
réglez la classe du capteur et le modèle de pince par canal |
| ESPHome | sensor_class: / ct_model: |
Options YAML pour la classe du capteur et le modèle de pince |
6.3 Diffusion d'instantané GC — synchronisation de flotte sur demande
Activation par module via REG_FLEET_CONFIG.bit0 (GC_ENABLE). Désactivé par défaut. Le changement prend effet après reset (CMD_RESET logiciel ou reset matériel).
6.3.1 Séquence d'activation (une fois par module)
1. write REG_FLEET_CONFIG (0x27) = 0x01 # bit0 = GC_ENABLE
2. issue CMD_SAVE_USER_CONFIG (opcode 0x32, ungated)
3. issue CMD_RESET (opcode 0x01)
4. wait ~300 ms boot
5. verify: read REG_FLEET_CONFIG → bit 0 should be 1
6.3.2 Format de trame GC
I²C general-call address 0x00 | A5 27 (5-byte payload)
A5— magic de trame.27— code d'opérationCMD_LATCH_PERIOD.—0x00= tous ; sinon doit correspondre auREG_GROUP_ID (0x28)de l'appareil.— compteur de ticks 16 bits côté maître (pour la numérotation des fenêtres à l'échelle de la flotte et la détection des trames manquées par module viaGC_TICK (0x59)).
Instantané uniquement : les trames GC ne transportent pas les opcodes destructeurs (SAVE_*, COMMIT_ADDR, FACTORY_RESET, etc.) — par conception.
6.3.3 Détection des modes de défaillance — 2 niveaux
Niveau 1 — NACK de l'adresse GC (immédiat, au niveau du bus) :
- Si GC est désactivé sur toute la flotte → le maître reçoit une erreur franche (NACK sur l'adresse
0x00, ou l'équivalent côté pilote). - Il s'agit d'une erreur franche, PAS d'un rejet silencieux — le maître peut la détecter et réagir.
- Déclenchement : NACK sur GC = « GC n'est activé sur aucun appareil de la flotte. »
Niveau 2 — témoin par module (après stabilisation) :
- Si aucun NACK n'est reçu (au moins un module écoute), le maître lit
REG_V03_PERIOD_VALID (0x07)sur chaque esclave attendu. 1= l'instantané a réussi sur ce module.0= GC est désactivé sur ce module précis, ou la période en cours est vide.
Repli sur un instantané par appareil si le témoin renvoie 0 :
foreach module where witness == 0:
write_cmd(module, CMD_LATCH_PERIOD)
sleep(50 ms)
foreach module: read period snapshot with skip_latch=true
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmpFleet::gcLatch(group, tick, settle_ms) / RbAmpFleet::checkSync() |
envoyer la trame d'instantané General Call ; vérifier chaque module |
| ESP-IDF | rbamp_fleet_gclatch() / rbamp_fleet_check_sync() |
envoyer la trame d'instantané General Call ; vérifier chaque module |
| Python | fleet.gc_latch(group, tick, settle_ms) / fleet.check_sync(expected_tick) |
envoyer la trame d'instantané General Call ; vérifier chaque module |
| ESPHome | fleet_gc_enable: / journal de vérification de synchronisation |
instantané General Call activé par l'utilisateur ; ligne de journal confirmant que les modules sont synchronisés |
6.4 Synchronisation de période — deux stratégies
Stratégie 1 — instantané séquentiel + stabilisation partagée (tout firmware)
for module in modules:
write_cmd(module, CMD_LATCH_PERIOD)
sleep(50 ms)
for module in modules:
read_period_snapshot(module) # skip_latch=true
Décalage entre modules : environ 1 ms par module à 50 kHz. Sur 16 modules, par rapport à une période de 60 secondes, cela fait 0.027 %. Négligeable pour la comptabilité tarifaire.
Temps de stabilisation après CMD_LATCH_PERIOD :
- Au minimum 50 ms avant de lire
V03_PERIOD_VALID (0x07)ou l'instantané de période : cela couvre la latence d'instantané dans le pire cas (1 période du secteur à 50 Hz = 20 ms + validation temps réel + stabilisation du périphérique I²C). - Le maître peut éventuellement interroger
STATUS.bit0 (READY)au lieu d'une pause fixe :READY=1signifie que le bloc temps réel est dans un état cohérent, donc l'instantané de période peut être lu en rafale en toute sécurité. - Sur un module tout neuf (< ~100 ms après le démarrage à partir de la v1.2 ; < 200 ms avant), un instantané peut renvoyer
V03_PERIOD_VALID = 0parce que moins de 1 période du secteur s'est accumulée — voir la chronologie de démarrage à froid du §6.0.
Stratégie 2 — instantané de diffusion General-Call (activation requise)
Décalage = 0 (atomique au niveau du bus). Voir §6.3.
Quand utiliser quoi :
- < 8 modules : Stratégie 1 (plus simple, aucune validation requise).
- ≥ 8 modules ou synchronisation serrée : stratégie 2.
- Une méthode par module : le
CMD_LATCH_PERIODadressé et l'instantané de diffusion GC remettent à zéro le même accumulateur unique — les mélanger sur un module raccourcit la période en cours. Le repli par module (§6.3.3) est sûr, car il ne se déclenche que sur un module que la diffusion n'a pas atteint.
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmp::readPeriodSnapshot(..., skip_latch=true) / RbAmpFleet::gcLatch() |
lecture séquentielle après un instantané partagé ; trame d'instantané General Call |
| ESP-IDF | rbamp_read_period_snapshot(..., skip_latch=true) / rbamp_fleet_gclatch() |
lecture séquentielle après un instantané partagé ; trame d'instantané General Call |
| Python | instantané séquentiel, skip_latch=True / fleet.gc_latch() |
lecture séquentielle après un instantané partagé ; trame d'instantané General Call |
| ESPHome | latch_interval: / fleet_gc_enable: |
cadence d'instantané distincte ; instantané General Call sur option |
6.5 Provisionnement — flash neuf + SAVE
Comportement d'un module fraîchement flashé :
- Au premier démarrage après le flashage du firmware :
REG_ERROR = 0xFB (FLASH_PARAMS_BAD)+EVENT_FLAGS.bit3positionné. - La page des paramètres n'est pas initialisée → les valeurs d'usine sont chargées.
C'est NORMAL pour un module vierge et pas fatal. N'interrompez pas le provisionnement sur le 0xFB du premier démarrage.
Recovery:
1. configure SENSOR_CLASS + CT_MODEL (per §6.2)
2. (optional) configure FLEET_CONFIG + GROUP_ID + LABEL
3. issue CMD_SAVE_USER_CONFIG (opcode 0x32, ungated)
4. wait ~700 ms (flash write)
5. verify: REG_ERROR = 0x00, EVENT_FLAGS.bit3 cleared
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmpFleet::provision() / RbAmp::saveUserConfig() |
amener un module vierge à son adresse ; sauvegarder la configuration utilisateur |
| ESP-IDF | rbamp_provision() / rbamp_save_user_config() |
amener un module vierge à son adresse ; sauvegarder la configuration utilisateur |
| Python | provisionnement de flotte / dev.save_user_config() |
provisionner un module vierge, puis l'ajouter à la flotte ; enregistrer la configuration utilisateur |
| ESPHome | Flux de provisionnement / new_address: |
YAML pas à pas pour un module vierge ; changement d'adresse unique |
6.7 Récupération après état d'erreur — arbre de décision
Si, au démarrage ou pendant l'exécution, STATUS.bit1 (ERROR) = 1 ou si le signal persistant EVENT_FLAGS.bit3 (ERROR) est positionné, le maître lit REG_ERROR (0x02) et décide selon le code :
read REG_ERROR (0x02):
0x00 → no error (false signal — clear stale EVENT bit3 via W1C)
action: write 1<<3 → EVENT_FLAGS (W1C clear)
0xF9 → CLONE (reserved)
action: not raised. If ever observed, treat as
vendor-reserved and contact the supplier.
0xFA → LUT_BAD (calibration LUT corrupted)
action: device unusable for measurement. Factory recovery required.
0xFB → FLASH_PARAMS_BAD (params page uninitialized — virgin module)
action: NORMAL for a freshly flashed module. Provision per §6.5
(configure SENSOR_CLASS/CT_MODEL/...; issue CMD_SAVE_USER_CONFIG).
Cleared after a successful SAVE.
0xFC → NOT_READY (transient; module still booting)
action: wait 50 ms, retry. If persistent > 300 ms — power cycle.
0xFD → SENSOR_OVERFLOW (transient; signal saturated)
action: physical overload detected. The chosen CT clamp has
insufficient range for the measured current, or a real overload.
Issue CMD_CLEAR_ERROR (0x31) after the cause is removed.
0xFE → PARAM (last operation rejected — invalid argument / unknown opcode;
EVENT bit3 set. Very early images, 1.2–1.4.3, ignored unknown
opcodes silently)
action: master-side bug — review the last write. Issue CMD_CLEAR_ERROR
after fixing the master logic.
0xFF → UNHANDLED (firmware-side anomaly)
action: open an issue with the vendor; CMD_CLEAR_ERROR attempts to clear.
If persistent after CMD_RESET — the device is suspect.
Procédure générale de reprise pour les erreurs transitoires (0xFC/0xFD/0xFE) :
1. capture context (what was the last write? master state?)
2. issue CMD_CLEAR_ERROR (opcode 0x31)
3. wait 5 ms
4. re-read STATUS / REG_ERROR — verify cleared
Pour les erreurs persistantes — émettez CMD_RESET et parcourez la chronologie de démarrage à froid (§6.0). Si l'erreur persiste après réinitialisation et n'est pas 0xFB (flash neuf) — contactez le support du fournisseur.
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmp::readLastError() / RbAmp::clearError() |
lire le code d'erreur ; l'effacer |
| ESP-IDF | rbamp_read_last_error() / rbamp_clear_error() |
lire le code d'erreur ; l'effacer |
| Python | dev.read_last_error() / dev.clear_error() |
lire le code d'erreur ; l'effacer |
| ESPHome | write_clear_error() / write_reset() |
effacer l'erreur ; reset logiciel du module |
6.6 Référence des commandes
Codes d'opération principaux (écriture dans REG_COMMAND (0x01))
| Code d'opération | Nom | Stabilisation | Verrouillé | Remarques |
|---|---|---|---|---|
0x01 |
RESET |
~300 ms | – | Réinitialisation logicielle (HAL_NVIC_SystemReset) |
0x27 |
LATCH_PERIOD |
50 ms | – | Copier les compteurs RT dans l'instantané de période |
0x28 |
SET_CT_MODEL_CH0 |
5 ms | – | Lier REG_CT_MODEL préparé au canal 0 |
0x29 |
SET_CT_MODEL_CH1 |
5 ms | – | Lier REG_CT_MODEL préparé au canal 1 |
0x2A |
SET_CT_MODEL_CH2 |
5 ms | – | Lier REG_CT_MODEL préparé au canal 2 |
0x30 |
COMMIT_ADDR |
700 ms | – | Rendez persistant I2C_ADDRESS (voir §6.1) |
0x31 |
CLEAR_ERROR |
0 | – | Effacer REG_ERROR (classes transitoires uniquement ; CLONE (0xF9) est réservé, non levé) |
0x32 |
SAVE_USER_CONFIG |
700 ms | – | Rendre persistant le groupe user_config (compatible production) |
Les codes d'opération hors de la plage publique (usage d'usine) ne sont pas documentés dans cette référence. Un maître consommateur ne les envoie pas en fonctionnement normal ; un code d'opération non pris en charge → REG_ERROR = ERR_PARAM (0xFE).
7 · Sémantique
7.0 Endurance flash et comportement au reset
Rappel : avant le firmware 1.4.20, un reset rétablit aussi l'échelle du modèle CT à la valeur d'usine par défaut (CAPABILITY bit 12 à 0) — voir §6.2.
Endurance de la flash : ~10 000 cycles par page (typique, spécification du fabricant). Chaque CMD_SAVE_USER_CONFIG ou CMD_COMMIT_ADDR est un cycle d'effacement + écriture sur la page de paramètres.
⚠ Ne bouclez pas SAVE/COMMIT dans une boucle d'exécution. À 1 SAVE/s, un module grille en environ 3 heures. La configuration se fait une fois à l'installation ; aucune mise à jour de réglage en cours d'exécution n'est nécessaire (un maître grand public change rarement ces valeurs).
Rétention : généralement 10 ans et plus à la température de fonctionnement typique.
Comparaison du comportement au reset :
| Type de réinitialisation | Conservé | Effacé |
|---|---|---|
CMD_RESET (0x01) |
flash (configuration, adresse, étiquette, gains, NF) | RAM (UPTIME, ZC_OFFSET, EVENT_FLAGS — sauf le bit RESET_OCCURRED 5 positionné au démarrage ; THRESH_* ; DIGEST_CONFIG) |
| Broche de cycle d'alimentation / réinitialisation matérielle | flash | identique à CMD_RESET, plus toute RAM externe détenue côté hôte |
CMD_FACTORY_RESET (0xAA) (mode usine uniquement) |
rien | tout — l'ensemble du bloc de paramètres, étalonnage d'usine des canaux compris |
⚠ CMD_FACTORY_RESET n'est pas une « restauration des valeurs par défaut » de niveau utilisateur. Il réécrit tout le bloc de paramètres, étalonnage d'usine des canaux compris, et le module ne l'accepte qu'en mode usine — une opération de fabrication, pas une étape de maintenance. Un module BASIC n'a pas de commande de reset utilisateur. Pour ramener un module à un état connu, utilisez CMD_RESET (0x01) (reset logiciel : rien en flash n'est modifié) puis reconfigurez les réglages de niveau utilisateur avec CMD_SAVE_USER_CONFIG (0x32).
Motif de bits RESET_OCCURRED (référence) :
- Après une réinitialisation, au démarrage :
EVENT_FLAGS.bit5 = 1. - Le maître voit le bit 5 → il sait que le module a redémarré → il doit réinitialiser les champs uniquement en RAM (DIGEST_CONFIG, THRESH_*, EVENT_MASK).
- Le maître efface le bit 5 via W1C :
écrire 1<<5 → EVENT_FLAGS.
7.1 Modèle de persistance
| Commande | Production | Persiste |
|---|---|---|
CMD_SAVE_USER_CONFIG (0x32) |
✅ OK | i2c_address (via validation en deux phases), ct_model, sensor_class, fleet_config, group_id, label |
CMD_COMMIT_ADDR (0x30) |
✅ OK (armé magique) | i2c_address |
CMD_RESET (0x01) |
✅ OK | — (reset logiciel) |
CMD_LATCH_PERIOD (0x27) |
✅ OK | — (prend l'instantané de période) |
CMD_CLEAR_ERROR (0x31) |
✅ OK | — (efface REG_ERROR) |
CMD_SAVE_GAINS (0x26) |
❌ BLOQUÉ en production (rejeté : REG_ERROR = 0xFE ; un redémarrage rétablit l'état antérieur) |
étalonnage d'usine |
CMD_FACTORY_RESET (0xAA) |
❌ BLOQUÉ en production | — |
7.2 Relecture ≠ persistance
⚠ La protection de production accepte l'écriture en RAM (une lecture ultérieure renvoie la valeur écrite), mais la sauvegarde en flash peut être refusée. Après redémarrage, la valeur revient à son état antérieur à l'écriture.
Le seul moyen valide de confirmer la persistance est CMD_RESET + attente du démarrage + relecture :
1. write target_reg(...)
2. issue CMD_RESET (0x01)
3. wait ~300 ms boot
4. re-read target_reg
5. assert read == written # only now is persistence confirmed
L'adresse fait exception (référence v1.3) : REG_I2C_ADDRESS (0x30) au démarrage lit l'adresse active. Après la préparation, il renvoie le candidat ; après redémarrage, il affiche la valeur réellement persistée.
7.3 Réserve sur la référence de tension unique
Le module utilise une voie U pour calculer P sur toutes les voies I. Si une pince CT est posée sur un fil d'une autre phase (tableau de distribution multiphasé), les lectures P de ce canal seront fausses (décalage de phase U/I arbitraire). I_RMS reste correct.
La mesure polyphasée (L1/L2/L3 simultanément) est une référence distincte avec sa propre spécification.
7.4 Intégration d'énergie du maître — référence de l'horloge murale
⚠ V03_PERIOD_LATCH_MS (0xEC) est un minuteur de diagnostic du module ; il peut afficher une valeur courte sous charge — utilisez l'horloge maître pour l'énergie.
Intégration d'énergie de référence côté maître :
# CORRECT — master wall-clock
t_now = master_clock()
dt_s = (t_now - t_prev_latch) / time_unit
energy_wh[ch] += avg_p[ch] * dt_s / 3600
t_prev_latch = t_now
# WRONG — the module diagnostic timer may read short under load
dt_chip_s = read_u32(0xEC) / 1000.0
energy_wh[ch] += avg_p[ch] * dt_chip_s / 3600 # systematically under-reported
La mesure côté module de la fenêtre close est V03_PERIOD_COMMIT_CNT (0xBE) multiplié par la longueur d'une validation — il compte les validations temps réel entières et n'est pas affecté par la famine de minuterie qui fait afficher une valeur trop courte à V03_PERIOD_LATCH_MS. Une validation = 0.1 s à partir de la v1.2 ; les images antérieures utilisaient 0.2 s. Pour savoir lequel s'applique sans table de versions : le rapport V03_PERIOD_LATCH_MS / V03_PERIOD_COMMIT_CNT vaut environ 100 ou environ 200. Utilisez-le pour les vérifications croisées ; l'horloge murale du maître reste la référence pour la comptabilité tarifaire.
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmp::energyWh(ch) |
total Wh courant d'un canal |
| ESP-IDF | rbamp_energy_wh() |
total Wh courant d'un canal |
| Python | dev.energy.wh(ch) |
total Wh courant d'un canal |
| ESPHome | energy |
Compteur Wh par canal |
7.5 Préservation de la période en cas d'instantané échoué
Le firmware CONSERVE l'accumulateur de période sur un instantané vide. Lorsque g_period_count == 0 (instantané sans période lisible) :
REG_V03_PERIOD_VALID = 0(signal périmé).period_start_msest conservé → le prochain instantané réussi couvre l'intervalle complet voulu par le maître.
Conséquence : le maître ne perd pas de données sur un instantané périmé. Schéma d'intégration côté maître :
issue snapshot
if PERIOD_VALID == 1:
integrate(avg_p, master_dt)
reset_master_clock
# else: skip integration (FW will automatically recover on the next success)
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmp::readPeriodSnapshot() / RbAmp::isPeriodValid() |
prendre un instantané de période et n'intégrer que s'il est valide ; vérifier le bit de disponibilité |
| ESP-IDF | rbamp_read_period_snapshot() / rbamp_is_period_valid() |
prendre un instantané de période et n'intégrer que s'il est valide ; vérifier le bit de disponibilité |
| Python | dev.read_period_snapshot() / RbAmpStaleError |
prendre un instantané de période ; levé lorsque l'instantané n'est pas prêt, le suivant couvre l'intervalle complet |
| ESPHome | Instantané de période non valide | journalisé lorsque l'indicateur de validité vaut 0 ; le premier instantané après démarrage est écarté |
7.6 Tolérance à la dérive d'horloge
Référence : la base de temps interne du module peut afficher une valeur courte de jusqu'à 30 % sous charge — c'est normal, propriété de la base de temps du module, par conception. Mesuré sur matériel en charge de production.
Acceptation : la puce est correcte avec une dérive ≤ 30 %.
⚠ Le seuil historique de 3 % est FAUX. Ce seuil rejetterait en masse des puces saines.
7.7 Résilience aux EMI / transitoires de commutation
Les lectures pendant la commutation active de relais (EMI 5 A) échouent environ 67 % du temps (mesuré matériellement). Les lectures en régime établi sont fiables. Le bus se rétablit seul, aucun blocage ne se produit, aucun module n'est perdu.
Schéma maître — reprise au niveau applicatif (obligatoire lors de la commutation de charges inductives) :
for attempt in range(5):
result = read_register(...)
if result is OK:
return result
sleep(20 ms)
raise IOError("read failed after retries")
Le bus_reset côté maître seul ne suffit pas lorsqu'une perturbation EMI chevauche la fenêtre de nouvelles tentatives du pilote.
7.8 Résumé des limitations connues
Liste consolidée des caractéristiques connues dont le maître doit tenir compte :
| Sujet | Comportement | Voir |
|---|---|---|
| Dérive de la minuterie de la puce | Peut afficher une valeur trop courte sous charge, jusqu'à 30 % (enveloppe d'acceptation) | §7.4, §7.6 |
| Commutation de relais (EMI) | ~67 % de taux d'échec de lecture pendant la commutation ; le bus se rétablit seul | §7.7 |
EVENT.bit3 latence asynchrone |
jusqu'à une fenêtre (~100 ms ; 200 ms avant la v1.2) entre le rejet de l'écriture et la levée du bit 3 | §5.3 |
V03_PERIOD_LATCH_MS (0xEC) |
Minuteur de diagnostic du module ; il peut afficher une valeur courte sous charge — le maître utilise sa propre horloge murale | §4.13, §7.4 |
Sémantique de REG_ERROR (0x02) |
Résultat de la dernière écriture (non persistant) ; bit 3 de EVENT = signal durable | §5.3 |
I_RMS = 0.0 |
Sous le plancher de bruit (mesure valide), PAS « pas de donnée » | §5.4.3 |
U_RMS/U_PEAK/P sur les variantes I |
Lu comme 0.0 (valide seulement si le bit 8 de CAPABILITY = 1) |
§4.10, §7.3 |
| Écriture multi-octets | Pas d'auto-incrémentation ; boucle octet par octet obligatoire | §5.1 |
| Vérification du changement d'adresse | Via un scan de bus sur la nouvelle adresse ; 0x30 reste juste après un redémarrage |
§6.1 |
| Premier démarrage après flashage | REG_ERROR = 0xFB est normal ; SAVE l'efface |
§6.5 |
| GC par défaut | DÉSACTIVÉ (activation module par module) ; NACK sur GC = « non activé » | §6.3 |
| Endurance de la flash | ~10000 cycles/page ; ne bouclez pas SAVE | §7.0 |
8 · Exemples de traces filaires
8.1 Détection — lire PRODUCT_ID + HW_VARIANT + CAPABILITY
# I²C operations on default slave addr 0x50
S 0xA0 W 0x54 Sr 0xA1 R [PRODUCT_ID] P # read 0x54
S 0xA0 W 0x55 Sr 0xA1 R [HW_VARIANT] P # read 0x55
S 0xA0 W 0x57 Sr 0xA1 R [CAP_lo][CAP_hi] P # burst-read 0x57..0x58 (auto-increment)
Où S=start, Sr=start répété, P=stop, W=bit d'écriture, R=bit de lecture, 0xA0=adresse esclave 0x50 << 1.
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmp::readVariant() / RbAmp::readCapability(out) |
lire la variante matérielle ; lire la carte des capacités |
| ESP-IDF | rbamp_read_variant() / rbamp_read_capability() |
lire la variante matérielle ; lire la carte des capacités |
| Python | dev.read_variant() / dev.read_capability() |
lire la variante matérielle ; lire la carte des capacités |
| ESPHome | get_variant_str() / get_capability_hex() |
la variante en texte ; la carte de capacités en hexadécimal |
8.2 Lecture en rafale du bloc RT (variante UI, tous les canaux)
# Read all of V03 RMS + P + PF (0x86..0xBD) — 56 bytes, atomic via read-freeze
S 0xA0 W 0x86 Sr 0xA1 R [56 bytes] P
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmp::readAll(snapshot) |
lire tout le bloc temps réel en un seul appel |
| ESP-IDF | rbamp_read_all() |
lire tout le bloc temps réel en un seul appel |
| Python | dev.read_all() |
lire tout le bloc temps réel en un seul appel |
| ESPHome | lecture en rafale du bloc instantané | le composant lit le bloc instantané en une seule rafale à chaque mise à jour |
8.3 Écriture multi-octets — LABEL octet par octet
# WRONG: burst-write — only 'M' is accepted
S 0xA0 W 0x68 'M' 'y' 'M' 'e' 't' 'e' 'r' '1' P
# CORRECT: byte-at-a-time loop
S 0xA0 W 0x68 'M' P
S 0xA0 W 0x69 'y' P
S 0xA0 W 0x6A 'M' P
S 0xA0 W 0x6B 'e' P
S 0xA0 W 0x6C 't' P
S 0xA0 W 0x6D 'e' P
S 0xA0 W 0x6E 'r' P
S 0xA0 W 0x6F '1' P
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmp::writeLabel(label) / RbAmp::readLabel(out) |
écrire l'étiquette de 8 octets (BASIC uniquement) ; la relire |
| ESP-IDF | rbamp_write_label() / rbamp_read_label() |
écrire l'étiquette de 8 caractères ; la relire |
| Python | dev.set_label(label) / dev.read_label() |
écrire l'étiquette de 8 octets ; la relire |
| ESPHome | — | option label non documentée |
Instantané de diffusion GC 8.4 + repli témoin
# Send GC frame: A5 27
S 0x00 W 0xA5 0x27 0x00 0x2A 0x00 P
# Wait 50 ms settle
# Witness check for every expected module
foreach module in [0x50, 0x51, 0x52]:
S (module<<1)|W 0x07 Sr (module<<1)|R [VALID] P
if VALID != 1:
# Fall back to per-device snapshot
S (module<<1)|W 0x01 0x27 P # CMD_LATCH_PERIOD
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmpFleet::gcLatch(group, tick, settle_ms) / RbAmpFleet::checkSync() |
envoyer la trame d'instantané General Call ; vérifier chaque module |
| ESP-IDF | rbamp_fleet_gclatch() / rbamp_fleet_check_sync() |
envoyer la trame d'instantané General Call ; vérifier chaque module |
| Python | fleet.gc_latch(group, tick, settle_ms) / fleet.check_sync(expected_tick) |
envoyer la trame d'instantané General Call ; vérifier chaque module |
| ESPHome | fleet_gc_enable: / journal de vérification de synchronisation |
instantané General Call activé par l'utilisateur ; ligne de journal confirmant que les modules sont synchronisés |
8.5 Changement d'adresse en 5 étapes
# 1. Stage candidate addr (0x51) → REG_I2C_ADDRESS
S 0xA0 W 0x30 0x51 P
# 2. Arm magic → ADDR_COMMIT_MAGIC
S 0xA0 W 0x31 0xA5 P
# 3. Issue CMD_COMMIT_ADDR (opcode 0x30) → REG_COMMAND
S 0xA0 W 0x01 0x30 P
# 4. Wait 700 ms flash write
# 5. Issue CMD_RESET (opcode 0x01) → REG_COMMAND
S 0xA0 W 0x01 0x01 P
# Wait ~300 ms boot
# Verify: probe the new addr
S 0xA2 W 0x55 Sr 0xA3 R [HW_VARIANT] P # 0xA2 = 0x51 << 1
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmp::prepareAddressChange(new_addr) / RbAmp::commitAddressChange() |
préparer et armer la nouvelle adresse, puis la valider |
| ESP-IDF | rbamp_prepare_address_change() / rbamp_commit_address_change() |
préparer et armer la nouvelle adresse, puis la valider |
| Python | dev.prepare_address_change(new_addr) / dev.commit_address_change() |
préparer et armer la nouvelle adresse, puis la valider |
| ESPHome | new_address: |
changement d'adresse ponctuel au démarrage ; supprimez l'option ensuite |
8.6 Provisionnement après flash neuf
# 1. Check fresh-flash state
S 0xA0 W 0x02 Sr 0xA1 R [0xFB] P # ERR_FLASH_PARAMS_BAD — normal
# 2. Configure sensor_class
S 0xA0 W 0x25 0x01 P # SCT_013
# 3. Stage CT model + bind ch0
S 0xA0 W 0x05 0x03 P # SCT-013-030
S 0xA0 W 0x01 0x28 P # CMD_SET_CT_MODEL_CH0
# Wait 5 ms
# 4. Save user_config
S 0xA0 W 0x01 0x32 P # CMD_SAVE_USER_CONFIG
# Wait 700 ms
# 5. Verify: REG_ERROR should be 0x00 (read IMMEDIATELY before the next write)
S 0xA0 W 0x02 Sr 0xA1 R [0x00] P
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmp::configureChannels(cls, models, n) / RbAmp::saveUserConfig() |
régler la classe et tous les modèles de canaux ; enregistrer la configuration utilisateur |
| ESP-IDF | rbamp_configure_channels() / rbamp_save_user_config() |
régler la classe et tous les modèles de canaux ; enregistrer la configuration utilisateur |
| Python | dev.configure_channels(cls, models) / dev.save_user_config() |
régler la classe et tous les modèles de canaux ; enregistrer la configuration utilisateur |
| ESPHome | sensor_class: / ct_model: |
Options YAML pour la classe du capteur et le modèle de pince |
8.7 Aller-retour DIGEST — configurer + lire
# 1. Configure digest mask: I_RMS + U_RMS + P_REAL (bits 0+1+2 = 0x07)
S 0xA0 W 0x29 0x07 P
# 2. Wait one RT-commit cycle (~100 ms from v1.2; waiting 200 ms covers all images; or poll STATUS.bit0)
# 3. Burst-read the digest window (22 bytes)
S 0xA0 W 0x70 Sr 0xA1 R [22 bytes] P
# Parse the layout per DIGEST_CONFIG = 0x07 on UI1 (N_I = 1):
# byte[0] = STATUS_MIRROR
# byte[1] = SEQ
# byte[2..3] = I_RMS[0] u16 (0.01 A units)
# byte[4..5] = U_RMS u16 (0.1 V units)
# byte[6..7] = P[0] i16 (1 W units)
# byte[8..21] = unused (0x00)
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | — | fenêtre de digest non exposée |
| ESP-IDF | rbamp_set_digest_fields() / rbamp_read_digest() |
choisir les champs de digest ; les lire en une seule transaction (BASIC) |
| Python | — | fenêtre de digest non exposée |
| ESPHome | — | fenêtre de digest non exposée |
8.8 Flux d'événements de seuil — écriture du seuil → déclenchement → effacement W1C
# 1. Write current threshold = 30 A (0x0BB8 in 0.01 A units → 2 bytes LE)
S 0xA0 W 0x2C 0xB8 P # LO byte
S 0xA0 W 0x2D 0x0B P # HI byte
# 2. Unmask THRESH_I event (bit 1) → DRDY solid-LOW on trip
S 0xA0 W 0x2B 0x02 P # EVENT_MASK = bit 1 only
# 3. (runtime) The master polls EVENT_FLAGS
S 0xA0 W 0x2A Sr 0xA1 R [event_flags] P
# event_flags == 0x02 → threshold tripped
# 4. (optional) Read context — REG_ERROR, RT block, etc.
# 5. Clear EVENT_FLAGS.bit1 via W1C
S 0xA0 W 0x2A 0x02 P
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmp::setEventThresholds(i_amps, p_watts) / RbAmp::readEventFlags(out) |
régler les seuils de courant et de puissance ; lire et effacer les indicateurs d'événements |
| ESP-IDF | rbamp_set_event_thresholds() / rbamp_read_event_flags() |
régler les seuils de courant et de puissance ; lire et effacer les indicateurs d'événements |
| Python | dev.read_event_flags() |
lire et effacer les indicateurs d'événement (pas de setter de seuil côté périphérique) |
| ESPHome | Alarmes de seuil en YAML / get_event_flags() |
automatisations à seuil sur les valeurs des capteurs ; les indicateurs d'événements |
8.9 Rafale de diagnostic de capture brute (CAPTURE_*)
CMD_CAPTURE_RAW (0x38) et les registres CAPTURE_* constituent une fonction de diagnostic — inutile en fonctionnement normal ; à utiliser uniquement sur demande du fournisseur pour capturer des échantillons bruts.
# 1. Arm raw-capture
S 0xA0 W 0x01 0x38 P # CMD_CAPTURE_RAW (opcode 0x38)
# Wait ~80 ms (3 DMA-TC cycles)
# 2. Check ready
S 0xA0 W 0x18 Sr 0xA1 R [status & 0x01] P # bit 0 = ready
# 3. Select page 0 (16 raw I0 samples → CAPTURE_WINDOW)
S 0xA0 W 0x19 0x00 P
# 4. Burst-read CAPTURE_WINDOW (32 bytes = 16×u16 LE samples)
S 0xA0 W 0x1A Sr 0xA1 R [32 bytes] P
# Repeat steps 3-4 for pages 1..15 (256 samples total ≈ 1.3 mains periods)
8.10 Relecture du miroir de vérification du modèle CT (contrôle de cohérence après liaison)
# After the §6.2 sequence — verify the applied state per channel via 0x51..0x53 (burst):
S 0xA0 W 0x51 Sr 0xA1 R [model_ch0][model_ch1][model_ch2] P
# Expected on UI2 mixed-CT (e.g. ch0=SCT-013-005, ch1=SCT-013-030):
# byte[0] = 0x01 # SCT-013-005 applied on ch0
# byte[1] = 0x03 # SCT-013-030 applied on ch1
# byte[2] = 0x00 # unused (UI2 N_I=2)
— la même tâche sans accès aux registres :
| Bibliothèque | Appel | Ce qu'il fait |
|---|---|---|
| Arduino | RbAmp::readCTModelCh(channel, out) |
lire le modèle CT réellement appliqué sur un canal |
| ESP-IDF | rbamp_read_ct_model_ch() |
lire le modèle CT réellement appliqué sur un canal |
| Python | dev.read_ct_model_ch(ch) |
lire le modèle CT réellement appliqué sur un canal |
| ESPHome | journal de démarrage ct_model[0]: matches |
lignes de journal confirmant que la classe et le modèle du capteur ont été appliqués |
9 · Acceptation / tolérance
| Paramètre | Seuil | Source |
|---|---|---|
| Dérive d'horloge de la puce par rapport à l'horloge murale du maître | ≤ 30 % | validé au banc |
| Taux d'échec de lecture lors de la commutation des relais (EMI) | jusqu'à ~67 % pendant la commutation | validé au banc |
| Taux de NACK du bus (Linux/ESP I²C @ 100 kHz sans nouvelle tentative) | jusqu'à ~20 % | caractéristique côté hôte |
| Taux de NACK du bus à 50 kHz + 3 reprises | < 0.8 % | validé au banc |
Valeur de REG_ERROR au premier démarrage après flashage |
0xFB (FLASH_PARAMS_BAD) |
NORMAL sur un module vierge |
| Démarrage à froid jusqu'à la première mesure valide | ~250 ms | typique |
10 · Journal des modifications
1.3.0 (2026-06-15) — Première publication publique.
Firmware de référence : protocol_version = 1.3, schema_version = 2. Contrat de la page 0 figé.
Principaux changements v1.3 par rapport aux versions internes précédentes
- Préparation pure du CT_MODEL :
REG_CT_MODEL (0x05)ne s'applique plus automatiquement à ch0 à l'écriture. La liaison se fait uniquement viaCMD_SET_CT_MODEL_CHn(indépendante de l'ordre). - Commit d'adresse à deux phases (compatible production) :
I2C_ADDRESSest rendue persistante viaADDR_COMMIT_MAGIC+CMD_COMMIT_ADDR.REG_I2C_ADDRESSlit l'adresse active au démarrage. - REG_ERROR = résultat de la dernière écriture (non persistant).
EVENT_FLAGS.bit3est le signal durable (W1C persistant ; se lève dans une fenêtre, ~100 ms, après le rejet d'écriture). - Opcodes inconnus / énumérations hors plage → rejetés :
REG_ERROR = ERR_PARAM (0xFE)+EVENT.bit3. Les tout premiers images (1.2–1.4.3) ignoraient silencieusement les opcodes inconnus. - Premier flashage / provisionnement :
ERR_FLASH_PARAMS_BAD (0xFB)sur un module vierge → effacé viaCMD_SAVE_USER_CONFIG. - Diffusion d'instantané GC — activation par module via
FLEET_CONFIG.bit0(désactivé par défaut ; effectif après reset). NACK si désactivé = erreur matérielle, pas silencieuse. - Asymétrie lecture/écriture par conception : la LECTURE avec auto-incrémentation ✅ ; l'ÉCRITURE doit être octet par octet ❌ (confirmé matériellement).
- Registre CAPABILITY (0x57/0x58 u16 LE) : carte des fonctionnalités — détectez les fonctions bit par bit (§3.2), jamais en comparant la valeur entière ; bit 12 = SCT_RATING_SELF (fw 1.4.20+).
- Atomicité : le bloc RMS V03 + Digest bénéficie d'un gel de lecture (lecture en rafale atomique) ; les miroirs GC_TICK / I2C_ADDRESS / CT_MODEL_CHn sont lus deux fois et doivent concorder.
- Sémantique de la pince NF :
I_RMS = 0.0signifie « sous le plancher de bruit », une mesure valide. - AC_FREQ issu du passage par zéro sur toutes les variantes (y compris I uniquement).
- L'intégration d'énergie du maître doit utiliser sa propre horloge murale, et non
V03_PERIOD_LATCH_MS (0xEC)(minuterie de diagnostic du module — peut afficher une valeur trop courte sous charge).