05 · Démarrage rapide
Un « bonjour le monde » en cinq minutes : ajoutez le composant à un projet IDF, raccordez le module, sélectionnez un capteur, faites votre première lecture RT et votre premier instantané par période (Wh).
Les détails (brochage pour une puce ESP32 donnée, bus multi-modules, choix d'une SCT-013 selon la plage) figurent dans les chapitres voisins :
-
04 · Câblage — détails matériels et valeurs GPIO par défaut de chaque puce ESP32 prise en charge
-
03 · Choix du capteur de courant — quel modèle SCT-013 utiliser et pourquoi
Ce dont vous avez besoin
- Un module rbAmp (toute gamme ; par simplicité un UI1 — une entrée de tension plus un canal de courant ; les autres variantes sont listées dans 03)
-
Toute puce de la famille ESP32 (
esp32,esp32s2,esp32s3,esp32c2,esp32c3,esp32c6,esp32h2) -
ESP-IDF v5.2+ installé (
. ~/esp/esp-idf/export.shou%IDF_PATH%\export.batsous Windows) -
Une pince CT SCT-013 de calibre correspondant à votre courant maximal (5 A / 10 A / 30 A / 50 A / 100 A)
- Une alimentation 5 V pour le module (depuis un DevKitC USB-5V ou une alimentation externe)
- Un circuit alternatif à mesurer (une lampe, une bouilloire, un appareil domestique)
Étape 0 — Définir la cible
Si c'est un nouveau projet ESP-IDF et que idf.py set-target n'a pas encore été lancé, faites-le avant le premier idf.py build — sinon la compilation échoue avec « no target specified » :
idf.py set-target esp32 # or esp32s3 / esp32c3 / esp32c6 / ...
Sans cette étape, la compilation échoue.
Étape 1 — Ajouter le composant au projet
En tant que dépendance git (recommandé)
Dans le fichier main/idf_component.yml de votre projet (créez-le s'il n'existe pas). Le gestionnaire de composants ESP-IDF récupère la version étiquetée :
dependencies:
rbamp:
git: https://github.com/rb-amp/rbamp-esp-idf.git
version: v1.7.3
Le composant est téléchargé au prochain idf.py build (ou idf.py reconfigure).
Manuellement (sous-module git / clone)
mkdir -p components/
cd components/
git clone https://github.com/rb-amp/rbamp-esp-idf.git rbamp
Ou ajoutez le chemin du composant au CMakeLists.txt racine du projet :
list(APPEND EXTRA_COMPONENT_DIRS
${CMAKE_CURRENT_LIST_DIR}/components/rbamp)
# the directory must be named `rbamp`
La dépendance dans main/
# main/CMakeLists.txt
idf_component_register(
SRCS "main.c"
INCLUDE_DIRS "."
REQUIRES rbamp
)
Le composant tire esp_driver_i2c, esp_timer et log — c'est tout ce dont a besoin le scénario de base de l'étape 3. Les scénarios réseau / SPIFFS / OLED exigent des REQUIRES supplémentaires — voir 06 · Exemples, le tableau CMakeLists au début du chapitre.
Étape 2 — Câblage
Quatre fils + DRDY facultatif :
| Broche rbAmp | ESP32 (par défaut) | ESP32-S3 (par défaut) | ESP32-C3 (par défaut) |
|---|---|---|---|
VCC |
+5 V (4.5 à 5.5 V) | identique | identique |
GND |
GND | GND | GND |
SDA |
GPIO21 | GPIO8 | GPIO5 |
SCL |
GPIO22 | GPIO9 | GPIO6 |
L'alimentation doit être de 5 V. Les lignes I²C fonctionnent en logique 3.3 V — directement compatibles avec les GPIO de l'ESP32. La carte du module intègre déjà des résistances de tirage de 4.7 kΩ — pour un seul module, aucune résistance externe n'est nécessaire.
Le tableau complet du brochage de chaque puce ESP32 se trouve dans 04 · Câblage.
⚠ La tension du secteur peut tuer. Coupez et verrouillez le circuit avant de raccorder les bornes L/N ou de poser la pince ; faites réaliser le câblage secteur et tout travail dans un tableau par une personne qualifiée. Ne serrez qu'UN seul conducteur (L) — jamais le câble entier. Protégez la dérivation L selon les règles locales.
La pince CT SCT-013 se referme autour du conducteur de phase (L), la flèche sur le corps de la pince pointant dans le sens du courant vers la charge. Un module UI a aussi besoin de sa connexion de tension L/N ; la pince CT se branche dans la prise jack 3.5 mm du module (repérée I0, I1, … sur le PCB) ; le côté secteur porte les bornes L et N. Voir 04 · Câblage, « Connexion secteur et CT ».
Étape 3 — Premier projet (première lecture)
Un main/main.c minimal : mettre le bus en service, indiquer au module la pince CT installée, puis afficher U / I / P / PF une fois par seconde.
#include
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/i2c_master.h"
#include "esp_log.h"
#include "rbamp.h"
static const char *TAG = "app";
void app_main(void) {
const i2c_master_bus_config_t bus_cfg = {
.i2c_port = I2C_NUM_0,
.sda_io_num = GPIO_NUM_21, /* ESP32 — adjust for your chip */
.scl_io_num = GPIO_NUM_22,
.clk_source = I2C_CLK_SRC_DEFAULT,
.glitch_ignore_cnt = 7,
.flags.enable_internal_pullup = true, /* optional with the module's own pull-ups */
};
i2c_master_bus_handle_t bus;
ESP_ERROR_CHECK(i2c_new_master_bus(&bus_cfg, &bus));
rbamp_handle_t dev = NULL;
ESP_ERROR_CHECK(rbamp_new(bus, 0x50, &dev)); /* default address 0x50 */
/* rbamp_begin blocks while it tries to reach the slave;
* it runs a primer-snapshot and a valid-check, ~250 ms. */
while (rbamp_begin(dev) != ESP_OK) {
ESP_LOGE(TAG, "rbAmp not responding — check wiring and power");
vTaskDelay(pdMS_TO_TICKS(1000));
}
ESP_LOGI(TAG, "Module ready.");
/* Sensor configuration (see Step 4): class first, then model.
* Code 3 = SCT-013-030; use the code of the clamp you fitted. */
if (rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013) != ESP_OK ||
rbamp_set_ct_model(dev, 3) != ESP_OK) {
ESP_LOGE(TAG, "sensor configuration failed");
return;
}
ESP_LOGI(TAG, "Sensor configured.");
while (1) {
float u = NAN, i = NAN, p = NAN, pf = NAN;
if (rbamp_read_voltage(dev, 0, &u) != ESP_OK) u = NAN;
if (rbamp_read_current(dev, 0, &i) != ESP_OK) i = NAN;
if (rbamp_read_power(dev, 0, &p) != ESP_OK) p = NAN;
if (rbamp_read_power_factor(dev, 0, &pf) != ESP_OK) pf = NAN;
ESP_LOGI(TAG, "U=%.1f V I=%.3f A P=%.1f W PF=%.3f",
(double)u, (double)i, (double)p, (double)pf);
vTaskDelay(pdMS_TO_TICKS(1000));
}
}
Compilez, flashez et ouvrez le moniteur :
idf.py build
idf.py -p /dev/ttyUSB0 flash monitor
(Sous Windows — idf.py -p COM3 ....)
Sortie attendue avec une charge allumée (les valeurs dépendent de votre charge) :
I (1234) app: Module ready.
I (2634) app: Sensor configured.
I (3634) app: U=230.4 V I=0.523 A P=119.8 W PF=0.987
U affiche environ la tension du secteur (220-240 V pour les réseaux 230 V) — cela signifie que le module est correctement câblé.
Si I reste à 0.000 A avec une charge branchée : le module ne sait pas quelle pince CT est utilisée (l'étape de configuration du capteur a été sautée ou a échoué) — sans cela, les lectures de courant restent à zéro. PF est indéfini lorsque I=0 et peut afficher nan, 0 ou une valeur fictive ; ignorez-le tant que le courant n'est pas non nul. Voir 10 · Dépannage, « Current reads zero on a working load » (le courant lit zéro sur une charge en fonctionnement).
Étape 4 — Ce que fait la configuration du capteur
Les deux appels de l'étape 3 indiquent au module la classe et le modèle du capteur. Sans eux, les coefficients d'étalonnage ne sont pas chargés et les lectures de courant restent à zéro. L'ordre compte : d'abord la classe, puis le modèle.
/* Step A: sensor class. The current rbAmp SKU uses SCT-013 clamps. */
rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013);
/* Step B: model. For example, SCT-013-030 for a household feed up to ~7 kW. */
rbamp_set_ct_model(dev, 3);
Codes de modèle :
code |
Modèle | Plage | Usage typique |
|---|---|---|---|
| 1 | SCT-013-005 | 0..5 A | Petites charges, une seule prise |
| 2 | SCT-013-010 | 0..10 A | Réfrigérateur, lave-linge |
| 3 | SCT-013-030 | 0..30 A | Alimentation domestique jusqu'à ~7 kW |
| 4 | SCT-013-050 | 0..50 A | Borne de recharge VE, chauffage électrique |
| 5 | SCT-013-100 | 0..100 A | Entrée de service principale d'une maison ou d'un petit bureau |
| 6 | SCT-013-020 | 0..20 A | Chauffe-eau, chaudière, gros appareil |
| 7 | SCT-013-060 | 0..60 A | Sous-compteur industriel |
Pour plus de détails sur le choix (dont les autres codes pris en charge) — 03 · Choix du capteur de courant.
Ces deux appels sont effectués une seule fois lors de la première installation — le choix est enregistré dans la flash du module et survit à une réinitialisation. Le temps total est d'environ 1.4 seconde (deux écritures en flash × ~700 ms chacune).
Aux exécutions suivantes du firmware, vous pouvez omettre rbamp_set_sensor_class() et rbamp_set_ct_model() (le module s'en souvient). Cela ne pose toutefois aucun problème : un nouvel appel avec la même valeur n'écrit rien.
Étape 5 — Comptabilisation de l'énergie (Wh)
Le module ne renvoie que des grandeurs instantanées + la puissance moyenne sur une période. Les Wh eux-mêmes sont calculés par le composant à partir de esp_timer_get_time() :
E_Wh += avg_P × master_dt_s / 3600
[W] [seconds] → [Wh]
où master_dt_s est le nombre de secondes entre deux appels réussis à rbamp_read_period_snapshot(). Le composant conserve l'horodatage du dernier instantané dans le handle et calcule la différence lui-même.
Un modèle minimal pour une comptabilité périodique (une fois par minute) :
void app_main(void) {
/* ...bus + rbamp_new + rbamp_begin + set_sensor_class + set_ct_model (Step 3)... */
while (1) {
vTaskDelay(pdMS_TO_TICKS(60000)); /* 60-second period */
rbamp_period_snapshot_t snap;
esp_err_t err = rbamp_read_period_snapshot(dev, &snap, 50, false);
if (err != ESP_OK || !snap.valid) {
ESP_LOGW(TAG, "snapshot error: %s", rbamp_err_to_str(err));
continue;
}
ESP_LOGI(TAG, "avg P over period: %.2f W accumulated: %.4f Wh dt=%u ms",
(double)snap.avg_p[0],
rbamp_energy_wh(dev, 0),
(unsigned)snap.master_dt_ms);
}
}
Après l'étape 3, les appels à rbamp_set_sensor_class() et rbamp_set_ct_model() ont déjà été exécutés une fois et sont enregistrés en flash du module ; dans le modèle ci-dessus, ils sont là pour une réexécution du firmware — le module ignore un appel répété avec la même valeur. La gestion des erreurs est en partie omise par souci de concision : ajoutez des gardes if (err != ESP_OK) si vous voulez détecter les rares incidents de communication au démarrage.
Ce que fait rbamp_read_period_snapshot() en coulisse (avec skip_latch=false) :
- Envoie au module la commande d'instantané de période (
CMD_LATCH_PERIOD). - Attend
settle_ms(50 ms par défaut) pendant que le module prépare l'instantané. - Vérifie le drapeau prêt ; lit la puissance moyenne / crête.
- Met à jour le compteur Wh interne :
+= avg_p × master_dt_s / 3600(si le composant est compilé sansCONFIG_RBAMP_DISABLE_ENERGY).
rbamp_energy_wh() repart à 0 après chaque réinitialisation ou coupure de l'ESP32 ; persistez-la vous-même si vous avez besoin qu'elle survive (voir 06 · Exemples, scénario 13).
Le premier appel après rbamp_begin() est une amorce : le module renvoie tout ce qu'il a accumulé depuis la mise sous tension (un intervalle inadapté à la comptabilité tarifaire). Le composant sait de lui-même que cet instantané doit être écarté — le code utilisateur ne le voit jamais.
Sortie attendue :
I (61234) app: avg P over period: 120.18 W accumulated: 2.0036 Wh dt=60012 ms
I (121234) app: avg P over period: 120.21 W accumulated: 4.0073 Wh dt=60005 ms
...
Étape 6 — Démarrage rapide pour une flotte de N modules
Ce démarrage rapide montre l'utilisation d'un seul module. Le scénario canonique réel de la bibliothèque est plusieurs modules sur un même bus sous un handle de flotte unique (compteur principal + N sous-charges). L'exemple complet se trouve dans 06 · Exemples, scénario 1. > Prérequis pour une flotte. Tous les modules sortent d'usine à l'adresse 0x50, et
rbamp_fleet_scan exclut les modules qui partagent une adresse. Donnez d'abord à chaque module sa propre adresse, un module à la fois sur le bus (06 · Exemples, scénario 2, rbamp_provision), puis réglez la classe de capteur et le modèle de CT sur chaque module (03). Sinon, la flotte apparaît vide ou exclue, et les courants lisent 0. La puissance et le Wh nécessitent une variante UI : un bilan « secteur moins somme des charges » exige un module UI sur chaque charge.
Un squelette minimal de flotte :
#include "rbamp_fleet.h"
void app_main(void) {
/* ... bus init as in Step 3 ... */
rbamp_fleet_t fleet;
ESP_ERROR_CHECK(rbamp_fleet_create(bus, &fleet));
size_t added = 0;
esp_err_t scan = rbamp_fleet_scan(fleet, /*match_product=*/true, &added);
if (scan == ESP_ERR_INVALID_STATE) {
ESP_LOGE("app", "bus wedged — see ch.10 \"Fleet: INVALID_STATE\"");
return;
}
ESP_LOGI("app", "fleet: %u modules; excluded: %u",
(unsigned)added,
(unsigned)rbamp_fleet_excluded_count(fleet));
rbamp_snapshot_t snaps[RBAMP_FLEET_MAX_MODULES];
rbamp_fleet_poll_t status[RBAMP_FLEET_MAX_MODULES];
while (1) {
size_t n_ok = 0;
rbamp_fleet_poll_all(fleet, snaps, status,
RBAMP_FLEET_MAX_MODULES, &n_ok);
float p_total;
rbamp_fleet_total_power(fleet, &p_total);
ESP_LOGI("app", "fleet: %u/%u modules OK, total P = %.1f W",
(unsigned)n_ok, (unsigned)rbamp_fleet_count(fleet), p_total);
vTaskDelay(pdMS_TO_TICKS(200));
}
}
Dans le scénario canonique 80 %, l'un des modules est un UI1 sur l'arrivée secteur (il fournit total_power et total_energy_wh), et les autres sont des compteurs de sous-charge en courant I2/I3 (courant seul — ni puissance ni Wh ; utilisez des modules UI là où vous avez besoin de la puissance ou de l'énergie par charge). Les détails et les scénarios avancés (désagrégation secteur + sous-charges, synchronisation GC pour des instantanés serrés, le flux de provisionnement) figurent au chapitre 06.
Suite
- 01 · Présentation — ce qu'est rbAmp et ce que fait le composant
- 02 · Gammes de modules — quelle gamme pour quelle tâche
-
06 · Exemples — scénarios de fonctionnement : secteur + N sous-charges (le canon 80 %), flux de provisionnement, CT mixtes multi-canaux, synchronisation GC de flotte, MQTT, veille profonde
-
07 · Intégrations DIY — Home Assistant / Node-RED / OpenHAB
-
08 · Intégrations cloud — AWS IoT / Azure / GCP / InfluxDB Cloud
-
09 · Référence de l'API — l'API publique complète (dont le gestionnaire de flotte + la configuration de flotte par appareil + la configuration multicanal + le modèle d'erreurs v1.3 + l'identification et le provisionnement)
-
10 · Dépannage — si quelque chose ne fonctionne pas (atténuation en trois couches contre les blocages I²C, conflit de flotte / verrouillage du bus / modes de défaillance du provisionnement)
Sources et tickets : rb-amp/rbamp-esp-idf · cette page dans le dépôt : docs/05_quickstart.md (v1.7.3)