rbAmp
FR
Boutique
Docs
Mis à jour le

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.

Public visé

: 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
Remarque

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é sans tBUF) 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.

Dans les bibliothèques clientes

— 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 :

Text
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

Python
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
Dans les bibliothèques clientes

— 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.

Dans les bibliothèques clientes

— 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

Python
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
Dans les bibliothèques clientes

— 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.

Vue d'ensemble de la carte de registres rbAmp et de ses blocs d'adresses.

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..0x1A sont des diagnostics de production, voir §4.2).
  • 0x36..0x3B, 0x40..0x45 — page 0 réservée (0x32 + 0x3C..0x3F forment 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

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é)
Dans les bibliothèques clientes

— 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)
Dans les bibliothèques clientes

— 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é
Dans les bibliothèques clientes

— 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.

Dans les bibliothèques clientes

— 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.
Dans les bibliothèques clientes

— 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
Dans les bibliothèques clientes

— 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)
Dans les bibliothèques clientes

— 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é).

Dans les bibliothèques clientes

— 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 –
Dans les bibliothèques clientes

— 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.
Dans les bibliothèques clientes

— 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
Dans les bibliothèques clientes

— 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
Dans les bibliothèques clientes

— 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

  1. ⛔ 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, et 0x9A prolonge ce pas — mais 0x9A est V03_I0_PEAK, pas V03_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.
  2. Resélectionnez avant chaque lecture. REG_CHANNEL_DATA est un instantané pris au moment de l'écriture du sélecteur, et non une vue en direct. Interroger 0x3C..0x3F en boucle sans réécrire 0x32 renvoie une valeur figée indéfiniment. Chaque nouvelle lecture exige une nouvelle écriture dans 0x32.
  3. 0x32 adresse de registre ≠ opcode de commande 0x32. CMD_SAVE_USER_CONFIG utilise l'opcode 0x32 écrit dans REG_COMMAND (0x01) — il s'agit d'un espace d'adresses différent de REG_CHANNEL_SELECT (situé à l'adresse de registre 0x32). Ne citez jamais 0x32 sans préciser l'espace.
  4. Pour les canaux 3 et plus, la période et l'énergie proviennent uniquement du champ 13 (CHFIELD_PERIOD_AVG_P). Les registres V03_PERIOD_AVG_P* (0xC2/0xC6/0xDC) ne couvrent que les canaux 0/1/2. Il n'existe pas de V03_PERIOD_AVG_P_CH3 plat — lisez le champ 13 via la fenêtre à la place.

Exemple au niveau du fil — lire le courant RMS du canal 3

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

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

Dans les bibliothèques clientes

— 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

Les lectures en rafale s'auto-incrémentent, tandis que les écritures multi-octets se font un octet à la fois.

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) :

Text
# CORRECT: low byte first (LE)
write(addr=0x2C, value=0x34)   # LO byte
write(addr=0x2D, value=0x12)   # HI byte

Exemple FAUX / CORRECT (pseudo-code)

Text
# 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 met reg_error = ERR_OK ; toute écriture ultérieure sans rapport efface l'erreur précédente.
  • EVENT_FLAGS (0x2A) bit 3 est 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) :

Text
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) :

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

Dans les bibliothèques clientes

— 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.

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 :

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

Dans les bibliothèques clientes

— 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)
Remarque

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 :

Text
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
Dans les bibliothèques clientes

— 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) :

Text
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)
Remarque

: 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 via CMD_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_MAGIC non 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 prepare doit être répétée.
Dans les bibliothèques clientes

— 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

Remarque

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) :

Text
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) lorsque CMD_SET_CT_MODEL_CHn est émis → REG_ERROR = ERR_PARAM.
  • CT_MODEL hors de 1..7 (SCT-013-005/-010/-030/-050/-100/-020/-060) lors d'un CMD_SET → ERR_PARAM.
Dans les bibliothèques clientes

— 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)

Text
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

Text
I²C general-call address 0x00 | A5 27      (5-byte payload)
  • A5 — magic de trame.
  • 27 — code d'opération CMD_LATCH_PERIOD.
  • — 0x00 = tous ; sinon doit correspondre au REG_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 via GC_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 :

Text
foreach module where witness == 0:
    write_cmd(module, CMD_LATCH_PERIOD)
sleep(50 ms)
foreach module: read period snapshot with skip_latch=true
Dans les bibliothèques clientes

— 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)

Text
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=1 signifie 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 = 0 parce 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_PERIOD adressé 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.
Dans les bibliothèques clientes

— 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.bit3 positionné.
  • 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:

Text
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
Dans les bibliothèques clientes

— 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 :

Text
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) :

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

Dans les bibliothèques clientes

— 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)
Remarque

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

Remarque

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.

Sécurité

⚠ 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
Sécurité

⚠ 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 :

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

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

Dans les bibliothèques clientes

— 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_ms est 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 :

Text
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)
Dans les bibliothèques clientes

— 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) :

Text
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

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

Dans les bibliothèques clientes

— 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)

Text
# 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
Dans les bibliothèques clientes

— 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

Text
# 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
Dans les bibliothèques clientes

— 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

Text
# 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
Dans les bibliothèques clientes

— 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

Text
# 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
Dans les bibliothèques clientes

— 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

Text
# 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
Dans les bibliothèques clientes

— 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

Text
# 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)
Dans les bibliothèques clientes

— 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

Text
# 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
Dans les bibliothèques clientes

— 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.

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

Text
# 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)
Dans les bibliothèques clientes

— 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 via CMD_SET_CT_MODEL_CHn (indépendante de l'ordre).
  • Commit d'adresse à deux phases (compatible production) : I2C_ADDRESS est rendue persistante via ADDR_COMMIT_MAGIC + CMD_COMMIT_ADDR. REG_I2C_ADDRESS lit l'adresse active au démarrage.
  • REG_ERROR = résultat de la dernière écriture (non persistant). EVENT_FLAGS.bit3 est 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é via CMD_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.0 signifie « 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).

Fin du document.