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

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 :

Diagramme de déroulement des étapes, du câblage à la première lecture et à la première valeur d'énergie.

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.sh ou %IDF_PATH%\export.bat sous 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 » :

Shell
idf.py set-target esp32      # or esp32s3 / esp32c3 / esp32c6 / ...

Sans cette étape, la compilation échoue.

Étape 1 — Ajouter le composant au projet

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 :

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

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

CMake
list(APPEND EXTRA_COMPONENT_DIRS
     ${CMAKE_CURRENT_LIST_DIR}/components/rbamp)
# the directory must be named `rbamp`

La dépendance dans main/

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

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

Raccordement pas à pas de la prise secteur et de la pince.

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

C
#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 :

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

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

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.

C
/* 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.

Remarque

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

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

C
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);
    }
}
Remarque

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

  1. Envoie au module la commande d'instantané de période (CMD_LATCH_PERIOD).
  2. Attend settle_ms (50 ms par défaut) 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 Wh interne : += avg_p × master_dt_s / 3600 (si le composant est compilé sans CONFIG_RBAMP_DISABLE_ENERGY).
Le compteur Wh réside en RAM.

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 :

Text
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

Sécurité

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 :

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