rbAmp
FR
Boutique
Docs
Mis à jour le

02 · Initialisation et démarrage

rbAmp commence à mesurer immédiatement après la mise sous tension. Le maître n'a besoin que de :

  1. Initialisez son bus I²C (initialisation standard Wire / HAL).
  2. Attendre ~250 ms, ou interroger DATA_VALID = 1 au registre 0xCE.
  3. Lisez éventuellement la version du firmware depuis 0x03 comme contrôle de cohérence.
  4. Données de lecture — prêtes.

Aucune commande de démarrage, aucune configuration au niveau des registres de la puce n'est nécessaire. L'étalonnage d'usine est chargé automatiquement au démarrage, de sorte que le module émet des valeurs correctes en unités physiques dès la première lecture.

La séquence de la mise sous tension jusqu'à la première lecture valide.

Remarque

Important pour les modules BASIC de la série SCT utilisés avec des capteurs SCT-013 : après la première installation, vous devez écrire le modèle du capteur dans le registre de modèle. Le module a besoin du modèle pour appliquer le bon coefficient mV par ampère. Le code du modèle est stocké en flash et survit aux redémarrages. Sur les firmwares antérieurs à 1.4.20 (bit 12 de CAPABILITY à 0), la mise à l'échelle appliquée revient à la valeur d'usine après un redémarrage du module — un maître qui a sélectionné un modèle non-usine doit le revalider après chaque redémarrage de module détecté (voir Ce qui persiste après un redémarrage et la règle de détection de redémarrage dans period-metering.md) ; à partir du fw 1.4.20, le changement de modèle survit au redémarrage. Sur les images antérieures à 1.4.20, l'énergie sera fausse après tout redémarrage du module, sauf si CT_MODEL est revalidé. Les bibliothèques clientes gèrent les deux cas pour vous. Les détails figurent dans la section Régler la classe de capteur et le modèle CT ci-dessous.

Les modules BASIC de la série CT sont fournis par paires avec leurs capteurs, préréglés et calibrés en usine pour ce capteur ; ils démarrent sans initialisation.

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

Fonctions auxiliaires (C indépendant de la plateforme)

Tous les exemples ci-dessous utilisent trois fonctions auxiliaires faciles à implémenter sur n'importe quelle plateforme :

C
// Read one byte from a slave register.
uint8_t rb_read_u8(uint8_t addr, uint8_t reg);

// Read a little-endian float32 (4 bytes from reg, reg+1, reg+2, reg+3).
// rbAmp supports READ auto-increment — both per-byte access and a single
// 4-byte burst-read are valid. The helpers below show per-byte for clarity;
// production code often uses burst-read for atomicity guarantees (see ch 11).
float rb_read_float_le(uint8_t addr, uint8_t reg);

// Write one byte to a slave register.
void rb_write_u8(uint8_t addr, uint8_t reg, uint8_t val);

Mise en service sur Arduino (Wire.h)

Fonctions auxiliaires

C++
#include 

uint8_t rb_read_u8(uint8_t addr, uint8_t reg) {
  Wire.beginTransmission(addr);
  Wire.write(reg);
  Wire.endTransmission(false);   // repeated start, do not release bus
  Wire.requestFrom(addr, (uint8_t)1);
  return Wire.read();
}

float rb_read_float_le(uint8_t addr, uint8_t reg) {
  uint8_t buf[4];
  for (int i = 0; i < 4; i++) {
    buf[i] = rb_read_u8(addr, reg + i);
  }
  float f;
  memcpy(&f, buf, 4);            // little-endian host (AVR, ESP32, ARM)
  return f;
}

void rb_write_u8(uint8_t addr, uint8_t reg, uint8_t val) {
  Wire.beginTransmission(addr);
  Wire.write(reg);
  Wire.write(val);
  Wire.endTransmission();
}

Test de fonctionnement (module unique)

C++
#include 
#define RB_ADDR 0x50

void setup() {
  Serial.begin(115200);
  Wire.begin();
  Wire.setClock(50000);
  delay(300);                           // wait for module boot

  // Wait DATA_VALID bit
  while ((rb_read_u8(RB_ADDR, 0xCE) & 0x01) == 0) {
    Serial.println("waiting for DATA_VALID...");
    delay(50);
  }

  uint8_t ver = rb_read_u8(RB_ADDR, 0x03);
  Serial.printf("rbAmp ready, version 0x%02X\n", ver);
}

void loop() {
  float u_rms = rb_read_float_le(RB_ADDR, 0x86);
  float i_rms = rb_read_float_le(RB_ADDR, 0x8E);
  float p     = rb_read_float_le(RB_ADDR, 0xA6);
  float pf    = rb_read_float_le(RB_ADDR, 0xB2);

  Serial.printf("U=%.1f V  I=%.3f A  P=%.1f W  PF=%.3f\n",
                u_rms, i_rms, p, pf);
  delay(1000);
}

Utilisez une charge d'au moins ~1 % de la plage nominale du capteur — en dessous, les mesures deviennent bruitées et la classe n'est pas garantie (une lampe de 60 W ne représente que 0.9 % d'une pince de 30 A ; voir le tableau des caractéristiques). Sur une pince de 30 A, une bouilloire de 2 kW convient bien comme charge de test. Pour les modules BASIC de la série SCT avec un capteur SCT-013, réglez la classe du capteur et le modèle de pince avant le test de fonctionnement (voir Réglage de la classe du capteur et du modèle de pince) — sans le modèle, les mesures de courant n'ont aucun sens.

Sortie attendue (une bouilloire de 2 kW sur 230 V, pince de 30 A) :

Text
rbAmp ready, version 0x04
U=229.8 V  I=8.72 A  P=2004 W  PF=0.999
U=230.1 V  I=8.73 A  P=2008 W  PF=0.999
...

Mise en service sur STM32 HAL (C)

C
#include "stm32f1xx_hal.h"
extern I2C_HandleTypeDef hi2c1;

#define RB_ADDR_8BIT (0x50 << 1)        // HAL expects 8-bit address format

uint8_t rb_read_u8(uint8_t reg) {
  uint8_t v;
  HAL_I2C_Mem_Read(&hi2c1, RB_ADDR_8BIT, reg, I2C_MEMADD_SIZE_8BIT, &v, 1, 100);
  return v;
}

float rb_read_float_le(uint8_t reg) {
  uint8_t buf[4];
  for (int i = 0; i < 4; i++) {
    HAL_I2C_Mem_Read(&hi2c1, RB_ADDR_8BIT, reg + i, I2C_MEMADD_SIZE_8BIT,
                     &buf[i], 1, 100);
  }
  float f;
  memcpy(&f, buf, 4);
  return f;
}

void main_app(void) {
  while ((rb_read_u8(0xCE) & 0x01) == 0) HAL_Delay(50);

  uint8_t ver = rb_read_u8(0x03);
  printf("rbAmp version: 0x%02X\n", ver);

  while (1) {
    float u = rb_read_float_le(0x86);
    float i = rb_read_float_le(0x8E);
    float p = rb_read_float_le(0xA6);
    printf("U=%.1f V  I=%.3f A  P=%.1f W\n", u, i, p);
    HAL_Delay(1000);
  }
}

Modules de la série CT : démarrage sans configuration

Un module de la série CT est livré avec chaque canal de courant déjà configuré : classe de capteur, calibre et étalonnage sont écrits en usine pour la pince fournie avec ce canal. Aucune écriture d'initialisation n'est nécessaire — l'hôte se contente de lire.

Sécurité

⚠ N'écrivez pas la classe de capteur ni le modèle de capteur sur un module de la série CT. - Écrire le modèle sur un canal remplace l'étalonnage d'usine de ce canal par un préréglage générique : l'erreur actuelle devient −2…+3 % et le seuil de faible courant est faux. - Écrire la classe efface le modèle de chaque canal.

Sur le firmware 1.4.22 et ultérieur, un module de la série CT refuse en fonctionnement normal les écritures de classe et de modèle avec ERR_PARAM (0xFE) ; les bibliothèques clientes les refusent sur tous les firmwares.

Le canal et sa pince forment une paire. Chaque pince est étiquetée avec le canal auquel elle appartient. Ne déplacez pas une pince vers un autre canal et ne branchez pas une autre pince sur un canal : l'étalonnage ne s'applique qu'à l'appairage d'usine. Les calibres sont fixes ; il n'y a aucun calibre à choisir.

Séquence de démarrage

  1. Raccordez les pinces (flèche vers la charge — voir hardware-connection.md) puis alimentez le module.
  2. Lire la classe (SENSOR_CLASS, 0x25) : 2 = série de pinces CT.
  3. Lire le modèle appliqué de chaque canal (0x51..0x53, un registre par canal ; UI5/UI7 canaux 3 et plus : via la fenêtre d'accès aux canaux, champ CT_MODEL) et le faire correspondre au calibre :
Code de modèle 0x06 0x07 0x08 0x09 0x0A 0x0B 0x0D
Calibre 1 A 5 A 10 A 20 A 30 A 50 A 100 A

Utilisez le calibre pour régler les plages d'affichage et valider les mesures ; le module renvoie déjà des ampères.

  1. Interrogez comme pour tout module BASIC — fenêtre de mesure de 100 ms, broche de données prêtes ou lecture périodique (voir realtime-polling.md) ; comptage de période comme dans period-metering.md.

Rien d'autre n'est requis : pas de sélection de capteur, pas d'étage de gain, pas de commande de sauvegarde. Le module conserve sa configuration à travers les redémarrages.

Remplacer une pince ou un module

L'étalonnage appartient à la paire. Une pince ou un canal ne peut pas être remplacé sur le terrain : un module qui a besoin d'une nouvelle pince est renvoyé au service après-vente d'usine pour un réappairage.

Régler la classe de capteur et le modèle CT

Remarque

Requis uniquement pour les modules BASIC de la série SCT utilisés avec des capteurs SCT-013. Les modules BASIC de la série CT sont fournis en paire avec leurs capteurs : tout est préréglé et étalonné en usine pour ce capteur précis, et ils démarrent sans initialisation — ignorez cette section.

Deux registres décrivent le capteur externe : SENSOR_CLASS (la famille — pinces SCT-013 à serrage, série de pinces CT filaires, CT intégré) et CT_MODEL (le code de modèle précis dans cette famille). En v1.3, le modèle s'écrit selon un schéma de préparation pure — écrire CT_MODEL ne l'applique pas à lui seul ; une commande dédiée par canal valide la valeur préparée.

Registres

Nom Adresse Type Remarques
SENSOR_CLASS 0x25 u8 RW 0 = non défini, 1 = SCT_013, 2 = WIRED_CT (la série de pinces CT), 3 = BUILTIN_CT (capteur intégré, étalonnage d'usine par unité — pas de code de modèle). Changer la classe remet CT_MODEL à 0.
CT_MODEL 0x05 u8 RW Code du modèle de pince — registre de préparation uniquement. L'écriture seule n'applique rien.

Choisir un capteur

Achetez l'un des modèles SCT-013 à sortie en tension listés dans le tableau ci-dessous (fiche jack 3.5 mm) — pas une variante à sortie en courant. Choisissez la pince de calibre le plus petit qui soit au-dessus de votre courant maximal attendu ; pour la classe annoncée, la charge ne doit pas descendre sous environ 1 % du calibre (voir le tableau de précision).

Codes de modèle CT — famille SCT-013 (SENSOR_CLASS = 1)

Code Capteur Calibre nominal Début d'écrêtage RMS Limite de crête
0x00 non défini (valeur par défaut sur les modules BASIC de la série SCT neufs d'usine) — — —
0x01 SCT-013-005 5 A 5.8 A 8.2 A
0x02 SCT-013-010 10 A 11.6 A 16.4 A
0x03 SCT-013-030 30 A 34.8 A 49.2 A
0x04 SCT-013-050 50 A 58 A 82 A
0x05 SCT-013-100 100 A 116 A 164 A
0x06 SCT-013-020 20 A 23.2 A 32.8 A
0x07 SCT-013-060 60 A 69.6 A 98.4 A
Remarque

Les codes 0x06 et 0x07 ne sont pas monotones selon le calibre — ils ont été ajoutés après l'ensemble initial 0x01..0x05. Choisissez toujours selon le calibre dont vous avez besoin, et non selon l'ordre des codes.

Sémantique des limites : le courant nominal et le début d'écrêtage RMS supposent une charge sinusoïdale ; le début d'écrêtage mesuré est ≈ 1.16 × le calibre. La limite de crête (≈ 1.64 × le calibre) est le vrai plafond — une charge déformée (facteur de crête élevé) commence à écrêter à crête / facteur de crête, en dessous des chiffres RMS. Restez au niveau du calibre ou en dessous pour la précision spécifiée : les mesures écrêtent vers 115–120 % du calibre.

Les chiffres par calibre (plancher détectable et lisible, classe, tolérance du capteur, point d'écrêtage) figurent dans le tableau de précision de overview.md. Changer de modèle de capteur revient à écrire le code de modèle dans le module — rien d'autre n'est requis ; il n'y a pas d'étape de recalibrage.

Codes de modèle CT — série de pinces CT filaires (SENSOR_CLASS = 2)

Les modules de la série CT- sont livrés sous forme de jeu étalonné en usine avec leur propre pince : la classe et le modèle sont déjà réglés et font partie de l'étalonnage — voir Modules de la série CT : démarrage sans configuration. Ne les écrivez pas. Le tableau ci-dessous sert de référence pour lire le modèle appliqué ; l'utilisateur ne sélectionne rien sur un module de la série CT-.

Code Pince Calibre nominal Fenêtre
0x01..0x05 anciens préréglages CT filaires — —
0x06 Pince CT, 1 A 1 A 6 mm
0x07 Pince CT, 5 A 5 A 6 mm
0x08 Pince CT, 10 A 10 A 6 mm
0x09 Pince CT, 20 A 20 A 10 mm
0x0A Pince CT, 30 A 30 A 10 mm
0x0B Pince CT, 50 A 50 A 10 mm
0x0D Pince CT, 100 A 100 A 16 mm
Remarque

La taille de fenêtre découle du courant nominal (6 mm pour 1–10 A, 10 mm pour 20–50 A, 16 mm pour 100 A) et n'affecte pas l'étalonnage.

Commandes

Nom Code d'opération Effet Attendre
CMD_SET_CT_MODEL_CH0 0x28 Lier la valeur CT_MODEL préparée au canal 0 ~5 ms
CMD_SET_CT_MODEL_CH1 0x29 Lier au canal 1 (UI2/UI3/I2/I3) ~5 ms
CMD_SET_CT_MODEL_CH2 0x2A Liez au canal 2 (UI3/I3) ~5 ms
CMD_SAVE_USER_CONFIG 0x32 Rendre persistant le bloc de configuration utilisateur (classe du capteur, modèle CT, adresse, étiquette) en flash ~700 ms

Procédure

  1. Branchez la ou les pinces CT sur la ou les prises du module (flèche vers la charge — voir hardware-connection.md).
  2. Réglez la classe du capteur(une fois, si ce n'est pas déjà fait) :

    C++
    rb_write_u8(0x50, 0x25, 0x01);    // SCT_013
    

  3. Pour chaque canal, le module expose :

  4. Préparer le code du modèle CT dansCT_MODEL:
    C++
    rb_write_u8(0x50, 0x05, 0x03);    // example: SCT-013-030
    
  5. Liez-le au canal correspondantCMD_SET_CT_MODEL_CHn:
    C++
    rb_write_u8(0x50, 0x01, 0x28);    // CMD_SET_CT_MODEL_CH0
    delay(5);
    
  6. Répétez pour ch1 / ch2 si la variante les possède (les canaux sont indépendants — vous pouvez mélanger les codes de modèle par canal).
  7. Rendre persistantvers la flash avecCMD_SAVE_USER_CONFIG:

    C++
    rb_write_u8(0x50, 0x01, 0x32);
    delay(700);                          // flash erase/write
    

  8. Terminé — avec une réserve sur les firmwares antérieurs à 1.4.20 (bit 12 de CAPABILITY à 0) : là, le code du modèle sauvegardé survit aux redémarrages, mais l'échelle appliquée ne survit pas (voir Ce qui persiste après un redémarrage ci-dessous) — si vous avez choisi un modèle non usine, répétez l'étape 3 (préparer + commit) après chaque redémarrage détecté du module ; CMD_SAVE_USER_CONFIG n'a pas à être répété. À partir du fw 1.4.20, le changement de modèle survit aux redémarrages.

Indépendance de l'ordre des canaux

: en v1.3, vous pouvez appeler CMD_SET_CT_MODEL_CH0/1/2 dans n'importe quel ordre. Aucun contournement par ordre décroissant n'est requis (c'était un artefact interne des firmwares antérieurs).

Comportement avec les bibliothèques clientes actuelles

Les bibliothèques clientes rbAmp (Arduino, ESP-IDF, ESPHome, Python) enveloppent cette procédure et ajoutent :

  • La réécriture de la même valeur est ignorée. Régler la classe de capteur ou le modèle CT à la valeur déjà présente dans le module n'émet ni écriture sur le bus ni cycle de flash — appeler le réglage à chaque démarrage est sans danger.

  • Les modules appairés en usine refusent les changements de classe et de modèle. Sur les références livrées en jeu étalonné en usine avec leur propre capteur de courant (série CT-), la classe et le modèle du capteur font partie de l'étalonnage : le module (firmware 1.4.22 et ultérieurs) refuse l'écriture avec ERR_PARAM (0xFE) en fonctionnement normal, et les bibliothèques la refusent avant envoi sur tous les firmwares. Le réappairage d'un capteur de remplacement est une prestation d'usine.

  • Limites par modèle. Pour chaque modèle CT, les bibliothèques exposent son courant nominal, le niveau RMS où l'écrêtage commence et la limite de crête — utilisez-les pour valider les mesures par rapport au capteur connecté.

Vérification

Après la liaison, le modèle CT appliqué sur chaque canal est reflété en 0x51..0x53 (miroirs de vérification en lecture seule). Ce ne sont PAS le registre de préparation 0x05 :

C++
uint8_t ch0 = rb_read_u8(0x50, 0x51);  // applied on ch0
uint8_t ch1 = rb_read_u8(0x50, 0x52);  // applied on ch1
uint8_t ch2 = rb_read_u8(0x50, 0x53);  // applied on ch2
Serial.printf("Applied: ch0=0x%02X ch1=0x%02X ch2=0x%02X\n", ch0, ch1, ch2);
Sécurité

⚠ Relecture ≠ persistance. Une lecture réussie de 0x51..0x53 confirme que la valeur est active en RAM, pas qu'elle a survécu jusqu'en flash. Pour vérifier la persistance, lancez CMD_RESET (ou coupure d'alimentation) et relisez après la fenêtre de démarrage. Le schéma complet figure dans period-metering.md.

Lors de la mise en service d'un nouveau module, faites un contrôle de cohérence avec une charge résistive connue (par exemple une lampe à incandescence de 100 W) : I_rms ≈ 100 W / U_rms ≈ 0.43 A et P_real ≈ 100 W. Si les valeurs sont fausses d'un facteur important, le code de modèle est probablement mauvais.

Ce qui persiste après un redémarrage

CMD_SAVE_USER_CONFIG enregistre le bloc de configuration utilisateur en flash, mais tout ce que le maître règle n'est pas réappliqué au démarrage suivant. Sur les firmwares antérieurs à 1.4.20 (bit 12 de CAPABILITY à 0) :

Élément Survit à un redémarrage ?
Adresse I²C oui
Étiquette du module oui
Classe du capteur + code du modèle CT (lisible en retour) oui
Échelle par modèle appliquée avant fw 1.4.20 : non — revient à la valeur d'usine ; à partir de 1.4.20 (bit 12 de CAPABILITY à 1) : oui
FLEET_CONFIG (activation GC) + GROUP_ID oui (via CMD_SAVE_USER_CONFIG ; effectif après reset)
configuration en RAM seule (seuils d'événements, configuration du digest) non

La conséquence sur ces images : un module qui a été basculé sur un modèle différent de celui sorti d'usine relit le code de modèle enregistré après un redémarrage, mais mesure avec la mise à l'échelle d'usine tant que le modèle n'est pas à nouveau validé. La règle pour tout maître (et pour un concentrateur gérant une flotte, indexée par UID de module) :

  1. Détecter le redémarrage — bit d'événement UPTIME_S / RESET_OCCURRED, voir period-metering.md → Détection d'un redémarrage du module.

  2. Reprendre la préparation et le commit du modèle CT sur chaque canal (CT_MODEL + CMD_SET_CT_MODEL_CHn), puis réappliquer toute configuration en RAM seule.

Les bibliothèques clientes implémentent exactement cela dans leur chemin de reprise. À partir du fw 1.4.20 (bit 12 de CAPABILITY, SCT_RATING_SELF), le changement de modèle conserve l'étalonnage de l'unité et survit aux redémarrages — l'étape 2 n'est alors pas nécessaire pour le modèle CT ; une configuration uniquement en RAM doit toujours être réinitialisée. Les modules fonctionnant sur leur modèle d'usine (y compris chaque module CT-série appairé en usine) ne sont concernés sur aucune image — la mise à l'échelle d'usine est la bonne.

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

Flux de travail pour un seul module

  1. Câblez le module selon hardware-connection.md.
  2. Pour les modules BASIC de la série SCT, écrivez le modèle de capteur une fois (section précédente).
  3. Flasher le maître avec le croquis de test de fonctionnement.
  4. Ouvrez le moniteur série — vous devriez voir U/I/P chaque seconde.
  5. Si les valeurs semblent fausses, voir troubleshooting.md.

Configuration multi-modules

Scénario : trois modules rbAmp sur un seul bus pour surveiller différentes parties d'une maison (arrivée principale, chauffe-eau, climatisation).

Étape 1 — Adresses

À la sortie de l'emballage, les trois modules portent l'adresse 0x50. Ils doivent être réadressés un à un. Ne connectez qu'un seul module au bus jusqu'à la fin du réadressage.

Étape 2 — Test de fonctionnement avec un module

Suivez la section ci-dessus. Vérifiez qu'un module fonctionne correctement.

Étape 3 — Changer l'adresse (et, si besoin, régler le modèle CT)

Suivez la procédure de changement d'adresse ci-dessous. Si les modules utilisent des capteurs SCT-013 différents, réglez le modèle CT sur chacun avant de changer les adresses.

Étape 4 — boucle d'interrogation multi-modules

C++
#include 

const uint8_t modules[] = {0x50, 0x51, 0x52};   // main, boiler, AC
const char* labels[]    = {"MAIN", "BOIL", "AC  "};
const int N = sizeof(modules) / sizeof(modules[0]);

void setup() {
  Serial.begin(115200);
  Wire.begin();
  Wire.setClock(50000);
  delay(300);

  for (int i = 0; i < N; i++) {
    Wire.beginTransmission(modules[i]);
    uint8_t rc = Wire.endTransmission();
    Serial.printf("Module %s (0x%02X): %s\n",
                  labels[i], modules[i], rc == 0 ? "OK" : "MISSING");
  }
}

void loop() {
  for (int i = 0; i < N; i++) {
    float u = rb_read_float_le(modules[i], 0x86);
    float p = rb_read_float_le(modules[i], 0xA6);
    Serial.printf("[%s] U=%.1f  P=%.1f W\n", labels[i], u, p);
  }
  Serial.println();
  delay(1000);
}

Sortie attendue :

Text
Module MAIN (0x50): OK
Module BOIL (0x51): OK
Module AC   (0x52): OK
[MAIN] U=229.8  P=850.3 W
[BOIL] U=229.7  P=1850.0 W
[AC  ] U=229.9  P=0.0 W
...
Dans les bibliothèques clientes

— la même tâche sans accès aux registres :

Bibliothèque Appel Ce qu'il fait
Arduino RbAmpFleet::scan(match_product, added) / RbAmpFleet::pollAll(snaps, status, capacity, n_ok) découvrir les modules sur le bus ; les lire tous en une seule passe
ESP-IDF rbamp_fleet_scan() / rbamp_fleet_poll_all() découvrir les modules sur le bus ; les lire tous en une seule passe
Python fleet.scan(match_product=True) / fleet.poll_all() découvrir les modules sur le bus ; les lire tous en une seule passe
ESPHome rbamp: (list) un bloc rbamp: par module, chacun avec son propre id et address

Changement d'adresse

L'adresse d'usine 0x50 est stockée dans le bloc de configuration utilisateur en flash. La v1.3 utilise une séquence de validation en deux phases pour rendre les changements d'adresse accidentels difficiles : une adresse candidate va d'abord dans un registre de préparation en RAM, doit être armée par un octet magique, puis n'est validée en flash que par une commande explicite. Une réinitialisation fait réénumérer le module à sa nouvelle adresse.

Le changement d'adresse en deux phases : préparer l'adresse candidate, l'armer, la valider, puis réinitialiser.

Registres et commandes

Nom Adresse / opcode Type Objet
REG_I2C_ADDRESS 0x30 u8 RW Préparation pour l'adresse candidate (0x08..0x77). Règle : avant le reset, 0x30 renvoie le candidat préparé ; après démarrage, il lit l'adresse active.
ADDR_COMMIT_MAGIC 0x31 u8 W Armer la validation avec 0xA5. Consommé (effacé) lors de la tentative de validation.
CMD_COMMIT_ADDR opcode 0x30 écrit dans REG_COMMAND (0x01) commande Valide l'adresse préparée par rapport au magic, la persiste en flash.
CMD_RESET code d'opération 0x01 écrit dans REG_COMMAND (0x01) commande Reset logiciel. Le module se réénumère à la nouvelle adresse après ~300 ms.

Procédure

  1. Ne connectez qu'un seul module (toujours sur 0x50) au bus.
  2. Préparer la nouvelle adresse :

    C++
    rb_write_u8(0x50, 0x30, 0x51);    // candidate address → RAM staging
    

  3. Armer le commit :

    C++
    rb_write_u8(0x50, 0x31, 0xA5);    // ADDR_COMMIT_MAGIC
    

  4. ProblèmeCMD_COMMIT_ADDR (opcode 0x30):

    C++
    rb_write_u8(0x50, 0x01, 0x30);
    

  5. Attendre≥ 700 mspour l'effacement / l'écriture de la flash :

    C++
    delay(700);
    

  6. ProblèmeCMD_RESET (opcode 0x01) — CMD_COMMIT_ADDRfaitnon auto-reset:

    C++
    rb_write_u8(0x50, 0x01, 0x01);
    

  7. Attendre ~300 ms pour la fenêtre de démarrage. N'émettez pas de commandes pendant cette fenêtre.

  8. Vérifiez que le module répond par ACK à la nouvelle adresse :

    C++
    uint8_t ver = rb_read_u8(0x51, 0x03);    // VERSION should be 0x04 on v1.3
    if (ver == 0x04) Serial.println("Address change OK");
    

  9. Marquez le circuit imprimé avec la nouvelle adresse au crayon à cire ou avec une étiquette, pour identifier physiquement le module.

Remarques importantes

  • Les deux étapes sont obligatoires. Écrire le candidat dans 0x30 seul n'a aucun effet persistant — il n'atterrit qu'en RAM et est perdu au prochain reset. Le couple magique-et-validation est ce qui réécrit réellement la flash.
  • L'adresse préparée doit se situer dans la plage 0x08..0x77 (I²C valide sur 7 bits). Les écritures hors plage sont rejetées avec ERR_PARAM ; le module conserve son adresse actuelle.
  • Adresses I²C réservées : 0x00 (appel général, voir ci-dessous), 0x01..0x07 (CBus réservé), 0x78..0x7F (10 bits réservé). Ne les utilisez pas.
  • Règle de relecture : avant le reset, 0x30 renvoie le candidat préparé ; après démarrage, il lit l'adresse active.
  • Le magic armé expire au bout de 5 s sans validation (chapitre 11 §6.1) — réarmez-le si vous avez attendu trop longtemps.
  • Rappel d'espace de noms — une même valeur d'octet peut être une adresse et un opcode :
Octet Comme adresse de registre En tant qu'opcode (écrit dans 0x01)
0x27 FLEET_CONFIG CMD_LATCH_PERIOD
0x28 GROUP_ID CMD_SET_CT_MODEL_CH0
0x30 REG_I2C_ADDRESS CMD_COMMIT_ADDR

Exemple complet de changement d'adresse

C++
#include 

bool change_address(uint8_t old_addr, uint8_t new_addr) {
  if (new_addr < 0x08 || new_addr > 0x77) {
    Serial.println("ERROR: invalid address");
    return false;
  }

  Serial.printf("Changing 0x%02X -> 0x%02X\n", old_addr, new_addr);

  rb_write_u8(old_addr, 0x30, new_addr);   // 1. stage candidate
  rb_write_u8(old_addr, 0x31, 0xA5);       // 2. arm magic
  rb_write_u8(old_addr, 0x01, 0x30);       // 3. CMD_COMMIT_ADDR
  delay(700);                              // 4. flash erase/write
  rb_write_u8(old_addr, 0x01, 0x01);       // 5. CMD_RESET (mandatory)
  delay(300);                              // 6. boot window

  Wire.beginTransmission(new_addr);
  if (Wire.endTransmission() == 0) {
    Serial.printf("OK, module now at 0x%02X\n", new_addr);
    return true;
  }
  Serial.printf("FAIL: module not found at 0x%02X\n", new_addr);
  return false;
}

void setup() {
  Serial.begin(115200);
  Wire.begin();
  delay(300);
  change_address(0x50, 0x51);
}
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

Appel général (diffusion à l'adresse 0x00)

Le protocole I²C réserve l'adresse 0x00 (appel général) — les trames envoyées à cette adresse sont reçues simultanément par tous les esclaves du bus. rbAmp peut prendre son instantané de période sur une trame d'appel général, mais seulement après activation explicite de la fonction sur le module.

Activation volontaire (désactivé par défaut)

La réception des instantanés General Call est désactivée par défaut — un module neuf NACK la trame d'appel général, que le maître détecte comme erreur matérielle et qu'il remplace automatiquement par un instantané séquentiel module par module. Pour activer GC sur un module :

  1. Mettez le bit 0 àFLEET_CONFIG:
    C++
    rb_write_u8(0x50, 0x27, 0x01);    // bit0 = GC_ENABLE
    
Remarque

Remarque sur la valeur 0x27 : c'est l'adresse de registre de FLEET_CONFIG. Le même octet 0x27 est aussi l'opcode de commande de CMD_LATCH_PERIOD (espace de noms distinct — les opcodes vont dans REG_COMMAND à 0x01). La collision est purement cosmétique ; l'adresse et l'opcode ne se confondent jamais au niveau du fil.

  1. (Facultatif) réglerGROUP_IDpour le partitionnement de la flotte —0x00accepte l'appel général :

    C++
    rb_write_u8(0x50, 0x28, 0x00);    // all-call
    

  2. Persist:

    C++
    rb_write_u8(0x50, 0x01, 0x32);    // CMD_SAVE_USER_CONFIG
    delay(700);
    

  3. Réinitialiser et vérifier que le bit a bien été pris en compte :

    C++
    rb_write_u8(0x50, 0x01, 0x01);    // CMD_RESET
    delay(300);
    uint8_t cfg = rb_read_u8(0x50, 0x27);
    if (cfg & 0x01) Serial.println("GC enabled");
    

Format de trame GC

Les trames d'instantané GC ont une disposition fixe magic-et-opcode :

Disposition des octets de la trame d'instantané General Call.

Text
addr 0x00 | A5 27   
  • A5 — octet magique de trame (l'esclave rejette tout autre octet).
  • 27 — opcode (CMD_LATCH_PERIOD).
  • — groupe cible (0x00 = tous ; sinon doit correspondre au GROUP_ID du module).
  • — compteur de ticks 16 bits côté maître, reproduit dans le registre GC_TICK (0x59) de chaque module pour détecter les trames manquées.

Par conception, les trames GC ne transportent que la commande d'instantané — les codes d'opération destructeurs (SAVE_*, COMMIT_ADDR, FACTORY_RESET) ne sont pas exécutés via l'appel général.

Exemple d'instantané de diffusion (après activation)

C++
// All modules with GC enabled take their snapshots at once.
Wire.beginTransmission(0x00);
Wire.write(0xA5);                       // frame magic
Wire.write(0x27);                       // CMD_LATCH_PERIOD opcode
Wire.write(0x00);                       // group_id = all-call
Wire.write(tick & 0xFF);                // tick_lo
Wire.write((tick >> 8) & 0xFF);         // tick_hi
uint8_t rc = Wire.endTransmission();
if (rc != 0) {
  // NACK at GC level → no module on the bus has GC enabled.
  // Fall back to per-module sequential snapshot.
}

Après la diffusion, chaque module met à jour son instantané de façon indépendante. Le maître lit ensuite chaque module par son adresse propre. Contrôle témoin (recommandé) : après un délai de stabilisation d'environ ~50 ms, lisez V03_PERIOD_VALID (0x07) sur chaque module attendu — 1 confirme que l'instantané a été pris ; 0 entraîne un instantané par module sur ce seul module.

Application : synchronisation précise des périodes pour l'équilibrage énergétique multi-modules (par ex. mains_input − solar_output), lorsque l'instant de l'instantané doit être identique sur tous les modules.

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) / RbAmpFleet::gcLatch(group, tick, settle_ms) activer General Call sur un module ; envoyer la trame d'instantané à la flotte
ESP-IDF rbamp_enable_gc() / rbamp_fleet_gclatch() activer General Call sur un module ; envoyer la trame d'instantané à la flotte
Python dev.enable_gc(enable=True) / fleet.gc_latch(group, tick, settle_ms) activer General Call sur un module ; envoyer la trame d'instantané à la flotte
ESPHome fleet_gc_enable: / group_id: Options YAML pour l'adhésion General Call et l'identifiant de groupe
Text
Step 1: Unbox all modules — every module is on address 0x50.

Step 2: For each module, one at a time:
   a) Connect only this module to the bus.
   b) If it is a BASIC SCT-series module: set SENSOR_CLASS (0x25), stage CT_MODEL (0x05),
      issue CMD_SET_CT_MODEL_CHn for each channel, then CMD_SAVE_USER_CONFIG.
   c) On images before fw 1.4.20 (`CAPABILITY` bit 12 clear): after any later reset of this
      module, re-stage and re-commit CT_MODEL on each channel (see the persistence table above).
   d) Run change_address(0x50, ).
   e) Verify the module responds at the new address.
   f) Physically mark the module (label with 0x51, 0x52, ...).
   g) Disconnect and move to the next module.

Step 3: After readdressing all modules, connect them in parallel.
        With four or more modules (or a longer bus), cut the built-in
        pull-up jumpers on all but one (see hardware-connection.md → I2C pull-ups).

Step 4: At master boot, run a scan loop and verify every readdressed
        module responds at its expected address.

BASIC ou STD ?

La ligne STD de rbAmp répond sur le même bus mais utilise une carte de registres différente, sur 16 bits. Avant d'appliquer la détection BASIC ci-dessous, vous pouvez les distinguer : envoyez le pointeur 16 bits 0x00 0x00 et lisez 2 octets — un module STD renvoie la paire ASCII 'S','T' (0x53 0x54) ; un module BASIC ne le fait pas (il traite les octets comme des écritures de registre sur 8 bits et renvoie ses données habituelles). Les modules STD sont couverts par leur propre documentation de référence.

Vous n'avez pas à le faire vous-même si vous utilisez une bibliothèque cliente. Les bibliothèques (Arduino, ESP-IDF, Python, ESPHome) détectent déjà la ligne de modules et gèrent les différentes tailles de registres — vous n'avez pas à vous demander si la carte de registres est sur 8 ou 16 bits.

Comment distinguer un module BASIC d'un module STD à l'exécution.

Dans les bibliothèques clientes

— la même tâche sans accès aux registres :

Bibliothèque Appel Ce qu'il fait
Arduino RbAmp::line() / RbAmp::begin() ligne détectée dans begin() ; relisez-la depuis la valeur en cache
ESP-IDF rbamp_line() / rbamp_begin() ligne détectée dans begin ; la relire depuis la valeur en cache
Python dev.is_std / dev.begin() ligne détectée dans begin(); la relire depuis la propriété
ESPHome — non exposé — détection automatique, rien à configurer en YAML

Détection automatique de la variante du module

Sécurité

⚠ Ne détectez pas la variante en cherchant un NACK sur les lectures de registres. Le firmware ne renvoie jamais de NACK sur les lectures de registres — les adresses non mappées renvoient 0x00 (voir chapitre 11 §5.2). Une vérification fondée sur le NACK affirme toujours « canal présent ».

Utilisez la paire de référence HW_VARIANT (0x55) + CAPABILITY (0x57/0x58) :

C++
struct VariantInfo {
  uint8_t hw_variant;     // 1=UI1, 2=UI2, 3=UI3, 4=I1, 5=I2, 6=I3
  uint8_t n_current;      // 1..3
  bool    has_voltage;    // true on UI*, false on I*
};

VariantInfo detect_variant(uint8_t addr) {
  VariantInfo v = {0, 0, false};
  uint8_t product = rb_read_u8(addr, 0x54);             // PRODUCT_ID
  if (product != 0x01) return v;                         // not an rbAmp sensor
  v.hw_variant = rb_read_u8(addr, 0x55);                 // HW_VARIANT
  uint8_t hw = v.hw_variant;
  v.n_current = (hw == 1 || hw == 4) ? 1
              : (hw == 2 || hw == 5) ? 2
              : (hw == 3 || hw == 6) ? 3 : 0;
  uint8_t cap_hi = rb_read_u8(addr, 0x58);               // CAPABILITY high byte
  v.has_voltage = (cap_hi & 0x01) != 0;                  // bit 8 of u16 = voltage-HW
  return v;
}

HW_VARIANT 1..3 sont des variantes UI (has_voltage == true) ; 4..6 sont des variantes à courant seul (has_voltage == false). Une incohérence entre la famille HW_VARIANT et CAPABILITY.bit8 indique un module défectueux ou mal flashé.

AC_FREQ (0x20) fonctionne sur toutes les variantes — le signal de passage par zéro provient d'une broche dédiée au passage par zéro du secteur, indépendante de l'étage d'entrée de tension.

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 et la carte des capacités
ESP-IDF rbamp_read_variant() / rbamp_read_capability() lire la variante matérielle et la carte des capacités
Python dev.read_variant() / dev.read_capability() lire la variante matérielle et la carte des capacités
ESPHome get_variant_str() / get_capability_hex() chaîne de variante et carte des capacités depuis la surface d'identité

Suivant