rbAmp
FR
Boutique
Docs
Mis à jour · Modifier sur GitHub [Edit on GitHub]

05 · Démarrage rapide

Un hello-world en cinq minutes : installer la bibliothèque, câbler le module, choisir un capteur, prendre votre première lecture RT et votre premier instantané par période (Wh).

Les détails (brochage pour un hôte précis, bus multi-modules, choix d'un SCT-013 par plage) figurent dans les chapitres voisins :

Première lecture en huit étapes : câblage, mise sous tension, scan de 0x50, begin(), réglage optionnel du capteur, lecture de U, I, P, FP, contrôle de cohérence, puis énergie.

Ce dont vous avez besoin

  • Un module rbAmp (n'importe quel palier, UI1 par souci de simplicité)
  • Un hôte compatible Arduino — UNO / Mega / ESP32 / ESP8266 / STM32duino / RP2040
  • Une pince SCT-013 de calibre supérieur à votre plus grand courant attendu (5 A / 10 A / 30 A / 50 A / 100 A) — ou le TC livré avec votre module
  • Une alimentation 5 V pour le module (depuis le USB-5V de l'hôte ou une source externe)
  • Un circuit alternatif à mesurer (une lampe, une bouilloire, un appareil domestique)

Étape 1 — Installer la bibliothèque

Arduino IDE — Gestionnaire de bibliothèques [Library Manager]

Sketch → Include Library → Manage Libraries… [Sketch → Include Library → Manage Libraries…] → rechercher RbAmp → Install. Aucune dépendance. Après l'installation, les exemples apparaissent sous File → Examples → RbAmp [File → Examples → RbAmp].

Arduino CLI

Shell
arduino-cli lib install RbAmp

PlatformIO

INI
[env:esp32dev]
platform   = espressif32
framework  = arduino
lib_deps   = rbamp/RbAmp@^1.6.1

Étape 2 — Câblage

Sécurité

⚠ La tension du secteur peut tuer. Coupez et verrouillez le circuit avant de raccorder les bornes L/N ou de poser la pince ; faites faire le câblage secteur et tout travail dans un tableau par une personne qualifiée. Ne serrez qu'UN conducteur (L) — jamais le câble entier (L+N s'annulent à ~0). Protégez la dérivation L selon les règles locales.

Quatre fils basse tension, plus un DRDY facultatif, puis les bornes secteur :

Broche rbAmp Hôte
VCC +5 V (plage 4.5..5.5 V)
GND GND
SDA I²C SDA (UNO A4, ESP32 GPIO21, STM32duino PB7)
SCL I²C SCL (UNO A5, ESP32 GPIO22, STM32duino PB6)
DRDY (facultative) à ignorer pour le premier croquis ; voir 04_hardware.md
Bornes L, N le même circuit que celui qui alimente la charge mesurée (côté secteur — voir l'avertissement ci-dessus)
Prise CT Fiche SCT-013 enfoncée à fond

L'alimentation doit être en 5 V. Les lignes I²C fonctionnent en logique 3.3 V mais tolèrent 5 V — connectez-les directement à un Arduino UNO sans adaptateur de niveau. La carte du module embarque déjà des résistances de rappel de 4.7 kΩ — pour un seul module, aucune externe n'est nécessaire.

Le tableau complet du brochage de chaque hôte Arduino se trouve dans 04 · Câblage.

La pince SCT-013 se referme autour du seul conducteur de phase (L), la flèche sur le corps de la pince pointant dans le sens du courant vers la charge. Pour plus de détails (section « Capteur de courant ») voir le chapitre 04 · Câblage.

Connexion côté secteur : la pince CT sur le seul fil L avec la flèche vers la charge, et la dérivation de référence de tension L/N.

Étape 3 — Premier croquis (lecture RT)

Un croquis minimal — vérifiez la communication sans configurer le capteur :

C++
#include 
#include 

RbAmp dev(Wire, 0x50);  // default address 0x50

void setup() {
    Serial.begin(115200);
    while (!Serial && millis() < 3000) { /* wait for USB-CDC */ }

    Wire.begin();
#if defined(ESP32) || defined(ESP_PLATFORM) || defined(ESP8266)
    Wire.setClock(50000);   // ESP32/ESP8266: 50 kHz — required for retry discipline
#endif

    while (!dev.begin()) {
        Serial.print(F("rbAmp begin failed: "));
        Serial.println(dev.errorString());
        delay(1000);
    }

    // v1.3: auto-detect the variant via REG_HW_VARIANT — more accurate than
    // the constructor topology hint (which is now a fallback for legacy fw).
    uint8_t variant = static_cast(dev.readVariant());
    Serial.print(F("Module ready, variant="));
    Serial.println(variant);   // 1=UI1, 4=I1, 5=I2, 6=I3
}

void loop() {
    Serial.print(F("U=")); Serial.print(dev.readVoltage(), 1);
    Serial.print(F("V  I=")); Serial.print(dev.readCurrent(0), 3);
    Serial.print(F("A  P=")); Serial.print(dev.readPower(0), 1);
    Serial.print(F("W  PF=")); Serial.println(dev.readPowerFactor(0), 3);
    delay(1000);
}

Téléversez le croquis et ouvrez le moniteur série à 115200 bauds.

Sortie attendue (sans calibration du capteur) :

Text
Module ready, variant=1
U=230.4V  I=0.000A  P=0.0W  PF=nan
U=230.4V  I=0.000A  P=0.0W  PF=nan

PF peut afficher nan, 0.000 ou un autre marqueur tant que le courant est nul.

Sécurité

U affiche à peu près la tension secteur (220-240 V sur réseau 230 V) — ce qui signifie que le module est correctement connecté. I=0.000 A même avec la charge allumée est normal à ce stade : le module ne sait pas encore quelle pince est utilisée. Avec I=0, PF est mathématiquement indéfini (cela dépend du firmware — il peut valoir NaN, 0 ou une valeur de substitution) — la forme exacte de la valeur n'a pas d'importance tant que le courant est nul. L'étape suivante corrige cela.

Étape 4 — Configuration du capteur de courant

Si vous avez installé une pince SCT-013 séparée, vous devez indiquer au module la classe et le modèle du capteur. Sans cela, les coefficients de calibration ne sont pas chargés et les lectures de courant restent à zéro. Si votre module est livré avec son TC déjà raccordé, sautez cette étape.

Lisez le modèle sur l'étiquette imprimée sur la pince (par exemple SCT-013-030 → code 3, voir le tableau ci-dessous). Choisissez le plus petit calibre de pince supérieur à votre courant maximal attendu. Une pince de calibre trop petit donne des lectures écrêtées et trop basses aux pointes ; une pince de calibre bien trop grand donne des lectures bruitées et imprécises aux faibles courants.

Ajoutez ceci à setup() après dev.begin(). La fonction loop() reste identique à l'étape 3 — seul setup() change :

C++
void setup() {
    Serial.begin(115200);
    while (!Serial && millis() < 3000) { /* wait for USB-CDC */ }
    Wire.begin();
#if defined(ESP32) || defined(ESP_PLATFORM) || defined(ESP8266)
    Wire.setClock(50000);   // ESP32/ESP8266: 50 kHz
#endif

    while (!dev.begin()) { delay(500); }

    // Step 1: sensor class. SCT-013 = the clip-on clamp you fitted.
    if (!dev.setSensorClass(RbAmpSensorClass::Sct013)) {
        Serial.print(F("setSensorClass failed: "));
        Serial.println(dev.errorString());
        while (true) { delay(1000); }
    }

    // Step 2: model. For example, SCT-013-030 for a household feed up to ~7 kW.
    if (!dev.setCTModel(RbAmpCTModel::Sct013_030)) {
        Serial.print(F("setCTModel failed: "));
        Serial.println(dev.errorString());
        while (true) { delay(1000); }
    }

    Serial.println(F("Ready."));
}

Codes de modèle — l'ensemble accepté est {1, 2, 3, 4, 5, 6, 7} :

code Modèle Plage Statut Usage typique
1 SCT-013-005 0..5 A ✅ sélectionnable Petites charges, une seule prise
2 SCT-013-010 0..10 A ✅ sélectionnable Réfrigérateur, lave-linge
3 SCT-013-030 0..30 A ✅ sélectionnable Alimentation domestique jusqu'à ~7 kW
4 SCT-013-050 0..50 A ✅ sélectionnable Borne de recharge VE, chauffage électrique
5 SCT-013-100 0..100 A ✅ sélectionnable Entrée principale de service, gros départs
6 SCT-013-020 0..20 A ✅ sélectionnable Alimentation moyenne — appareils de 3 à 4 kW
7 SCT-013-060 0..60 A ✅ sélectionnable Sous-compteur industriel

Pour en savoir plus sur la sélection, voir 03 · Choix du capteur de courant.

Remarque

Ces deux appels sont effectués une seule fois lors de la première installation — le choix est enregistré en flash du module et survit à une réinitialisation. La durée totale est d'environ 1.4 seconde (deux écritures en flash × ~700 ms chacune). La bibliothèque sérialise les deux appels en interne — chacun bloque jusqu'à la fin de l'écriture en flash, donc vous n'avez pas besoin d'ajouter un delay() entre eux : le second attend de lui-même que le premier ait libéré le fil.

Aux exécutions suivantes du croquis, vous pouvez omettre setSensorClass() et setCTModel() (le module s'en souvient). Mais il n'y a aucun inconvénient à les rappeler : un appel répété avec la même valeur réécrit le même octet.

Après le redémarrage du croquis, la valeur de courant correcte doit apparaître :

Text
Ready.
U=230.4V  I=0.523A  P=119.8W  PF=+0.987

Étape 5 — Comptabilité de l'énergie (Wh)

Le module ne renvoie que des grandeurs instantanées plus la puissance moyenne sur une période. La bibliothèque calcule elle-même les Wh à partir de l'horloge murale du maître :

Text
E_Wh += avg_P × master_dt_s / 3600
        [W]     [seconds]     →  [Wh]

où master_dt_s est le nombre de secondes entre deux appels readPeriodSnapshot() réussis.

Un modèle minimal de comptabilité périodique (une fois par minute) :

C++
void setup() {
    Serial.begin(115200);
    while (!Serial && millis() < 3000) { /* wait for USB-CDC */ }
    Wire.begin();
#if defined(ESP32) || defined(ESP_PLATFORM) || defined(ESP8266)
    Wire.setClock(50000);   // ESP32/ESP8266: 50 kHz
#endif
    while (!dev.begin()) { delay(500); }
    dev.setSensorClass(RbAmpSensorClass::Sct013);
    dev.setCTModel(RbAmpCTModel::Sct013_030);
    Serial.println(F("Period meter started; the first line covers only the time since begin() — ignore it..."));
}

void loop() {
    RbAmpPeriodSnapshot snap;
    if (!dev.readPeriodSnapshot(snap)) {
        Serial.print(F("snapshot error: "));
        Serial.println(dev.errorString());
        delay(60000);
        return;
    }

    Serial.print(F("avg P for period: ")); Serial.print(snap.avg_p[0], 2);
    Serial.print(F(" W   accumulated: ")); Serial.print(dev.energy().wh(0), 4);
    Serial.print(F(" Wh   dt=")); Serial.print(snap.master_dt_ms);
    Serial.println(F(" ms"));

    delay(60000);  // the 60-second period sits at the END of loop — the first
                   // snapshot is taken right after setup() and covers only the
                   // seconds since begin(); full periods follow
}
Remarque

Après l'étape 4, setSensorClass() et setCTModel() ont déjà été exécutés une fois et sont enregistrés en flash du module ; dans le modèle ci-dessus, ils servent aux relances du croquis — le module ignore un appel répété avec la même valeur. La gestion des erreurs est omise par souci de concision — ajoutez des gardes if (!...) si vous voulez détecter les rares incidents de communication au démarrage.

Ce que fait readPeriodSnapshot() en coulisse :

  1. Envoie au module une commande d'instantané de période.
  2. Attend 50 ms pendant que le module prépare l'instantané.
  3. Vérifie le drapeau prêt ; lit la puissance moyenne / crête.
  4. Met à jour le compteur interne de Wh : += avg_p × master_dt_s / 3600.

begin() effectue déjà un premier instantané que la bibliothèque écarte. Le premier readPeriodSnapshot() de votre croquis ne couvre donc que le temps écoulé depuis begin() (quelques secondes, voir dt= dans la sortie) : ignorez cette première ligne et attendez une période complète. À partir du second appel, chaque ligne couvre une période complète.

Sortie attendue :

Text
avg P for period: 119.90 W   accumulated: 0.1332 Wh   dt=4000 ms    <- short first period, ignore
avg P for period: 120.18 W   accumulated: 2.1368 Wh   dt=60012 ms
avg P for period: 120.21 W   accumulated: 4.1405 Wh   dt=60005 ms
...

Plusieurs modules

Pour plusieurs modules sur un même bus (arrivée principale + sous-charges), utilisez RbAmpFleet. L'exemple complet se trouve dans 06 · Exemples, scénario 1 ; les règles de câblage d'un bus multi-modules sont dans 04 · Câblage.

Et ensuite

  • 01 · Vue d'ensemble — ce qu'est rbAmp et ce que fait la bibliothèque
  • 02 · Paliers des modules — quel palier convient à quelle tâche
  • 06 · Exemples — scénarios de travail : secteur + N charges secondaires (le canon des 80 %), flux de provisionnement, capteurs CT mixtes par canal, synchronisation GC de la flotte, MQTT, veille profonde

  • 07 · Intégrations DIY — Home Assistant / Node-RED / OpenHAB

  • 08 · Intégrations cloud — AWS IoT / Azure / GCP / InfluxDB

  • 09 · Référence de l'API — l'API publique complète (y compris RbAmpFleet + multi-canaux + modèle d'erreurs v1.3 + identité et provisionnement)

  • 10 · Dépannage — quand quelque chose ne fonctionne pas (atténuation i2c-hang en trois couches, modes de défaillance de conflit / blocage / échec de provisionnement du parc)


Sources et problèmes : rb-amp/rbamp-arduino · cette page dans le dépôt : docs/05_quickstart.md (v1.6.2)