02 · Gammes de modules
Les modules rbAmp sont proposés en gammes de modules : BASIC et STANDARD (STD). Une gamme de modules est un ensemble complet de révision matérielle et de firmware, et non un drapeau logiciel. Passer d'une gamme à l'autre exige un changement physique de référence (SKU), et non une mise à jour du firmware.
Ce qu'est une ligne de modules
Du point de vue du composant et du code utilisateur : un seul handle et une seule API rbamp_* servent les deux gammes de modules commercialisées. rbamp_begin() détecte si le module derrière le handle est un module BASIC ou STD (rbamp_line()), et les appels qui n'existent que sur l'une des deux gammes renvoient ESP_ERR_NOT_SUPPORTED sur l'autre. Les différences apparaissent dans les valeurs renvoyées par le module, dans les grandeurs supplémentaires que mesure le module STD, et dans la façon dont le firmware traite les données (en particulier — l'export vers le réseau).
État actuel
Les modules BASIC et STANDARD (STD) sont livrés et sont tous deux pris en charge par ce composant (version 1.7.3).
| Gamme de modules | Statut dans ce composant |
|---|---|
| BASIC | ✅ livré — RBAMP_LINE_BASIC |
| STANDARD (STD) | ✅ livré — RBAMP_LINE_STD |
BASIC — gamme de modules de comptage de consommation d'entrée de gamme
Matériel
Un chemin analogique à faible coût adapté aux charges domestiques typiques. Le module comprend un frontal analogique isolé, un régulateur d'alimentation embarqué et un étalonnage d'usine stocké en flash.
Comportement du firmware
La logique d'un compteur à disque mécanique classique — le comptage n'avance que dans un sens, l'export vers le réseau n'est pas soustrait.
Les trois « couches » des valeurs de puissance active se comportent différemment :
| Signal | Signification | Comportement sur BASIC |
|---|---|---|
rbamp_read_power(dev, ch, &p) |
puissance RT instantanée, mise à jour environ toutes les 100 ms | signé — une valeur négative est visible en temps réel (export) |
snap.avg_p[ch] (dans rbamp_read_period_snapshot) |
puissance moyenne sur la période | chaque fenêtre de moyenne P de 100 ms est ramenée à max(P, 0) avant d'être ajoutée à l'accumulateur de période |
rbamp_energy_wh(dev, ch) |
Wh cumulés par le composant | monotone — consommation seulement, l'export n'est pas compté |
Autrement dit : l'utilisateur voit l'export dans la lecture RT, mais le compteur Wh du composant sur BASIC n'inclut pas celui-ci.
Applications typiques
-
Foyers sans production propre (pas de panneaux solaires, d'éoliennes ni de systèmes de batteries)
-
Sous-compteurs pour les charges purement consommatrices (chauffe-eau, moteurs, appareils domestiques)
-
Surveillance de la consommation d'un bâtiment où le comptage bidirectionnel n'est pas nécessaire
Comptage bidirectionnel sur BASIC (côté maître)
rbamp_read_power(dev, 0, &p)est signé, donc :
#include "esp_timer.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
static double consume_wh = 0.0;
static double export_wh = 0.0;
void bidirectional_loop(rbamp_handle_t dev) {
int64_t t_prev_us = esp_timer_get_time();
while (1) {
/* Sample RT power at 10 Hz. Slower polling loses resolution
* on sharp load transitions; faster adds little for typical
* mixed loads with an inverter. */
vTaskDelay(pdMS_TO_TICKS(100));
int64_t t_now_us = esp_timer_get_time();
double dt_s = (double)(t_now_us - t_prev_us) / 1e6;
t_prev_us = t_now_us;
float p;
if (rbamp_read_power(dev, 0, &p) != ESP_OK) continue;
double dwh = (double)p * dt_s / 3600.0;
if (p >= 0.0f) consume_wh += dwh;
else export_wh += -dwh;
}
}
Un exemple complet du motif se trouve dans 06_examples.md, au scénario « Comptage bidirectionnel côté maître ».
STANDARD (STD) — la gamme de modules de mesure étendue
Les modules STD sont pris en charge par la même API rbamp_* ; rbamp_begin() les détecte. En plus de ce que propose BASIC, un module STD fournit :
-
Énergie signée. L'import et l'export sont des grandeurs séparées, et le module conserve des compteurs de durée de vie persistants (Wh / varh, plus des résolutions plus fines sur les firmwares récents). L'export n'est pas écrêté : l'énergie d'une période est la différence de deux lectures de compteur (
rbamp_std_read_energy()/rbamp_std_energy_delta()), etrbamp_energy_wh()porte une valeur nette signée sur ces modules. -
Plus de grandeurs : puissance réactive et puissance apparente par canal (
rbamp_read_reactive_power(),rbamp_read_apparent_power(),rbamp_std_read_channel()), totaux par phase et généraux, et — une fois l'extraction des harmoniques activée — THD et facteur de puissance de déplacement. Les modules triphasés rapportent aussi les angles de phase de tension et la séquence de phases. -
Mécanismes de période : banques d'instantanés (huit périodes indépendantes, cadencées par le maître) sur les modules qui en disposent, ou différences de compteurs sur les modules qui conservent l'énergie sur l'appareil. Le mécanisme est choisi à
rbamp_begin()(rbamp_std_info_t.period_source). -
Le modèle de CT n'est qu'une étiquette. Sur un module STD, le modèle de CT n'est qu'une étiquette et ne règle aucun gain.
- Horloge du module, historique embarqué et journal d'événements, santé et diagnostics, mise à jour du firmware par I²C, certificat d'appareil et attestation.
Tout cela est documenté dans 09 · Référence de l'API, chapitre « STD line ». Un exemple fonctionnel est examples/std_meter/ (voir 06 · Exemples, scénario 18).
Comportement qui diffère de BASIC
| Sujet | BASIC | STD |
|---|---|---|
Export dans rbamp_energy_wh() |
non comptée (monotone, consommation seule) | signé — net de l'import et de l'export |
| Puissance réactive / apparente, THD | non disponible — sur BASIC, la puissance réactive n'est pas exposée par cette bibliothèque (ESP_ERR_NOT_SUPPORTED) |
disponible |
| Source de période | instantané de l'accumulateur de période | banques d'instantanés, ou différences de compteurs |
| Horloge du module | aucun | réglez-la avec rbamp_std_set_time() après chaque réinitialisation du module |
rbamp_factory_reset() |
pris en charge | ESP_ERR_NOT_SUPPORTED |
Condensé (rbamp_read_digest()) |
pris en charge sur un firmware doté de la capacité | ESP_ERR_NOT_SUPPORTED |
| Appels de période sur un module sans banques d'instantanés ni compteurs | — | ESP_ERR_NOT_SUPPORTED |
Applications typiques
- Logements équipés de production solaire en toiture, d'éoliennes ou de batteries
- Charges régénératives, recharge de véhicules électriques en V2G
- Installations qui ont besoin de la puissance réactive, du facteur de puissance et des harmoniques en plus de la puissance active
Comment détecter la gamme du module à l'exécution
rbamp_begin():
/* BASIC or STD — available after rbamp_begin() */
rbamp_line_t line = rbamp_line(dev); /* RBAMP_LINE_BASIC / RBAMP_LINE_STD */
/* Full SKU — cached by rbamp_begin(), no bus traffic */
rbamp_variant_t variant = rbamp_variant(dev); /* UI1 / UI2 / ... / I3 / UI5 / UI7 */
/* Voltage-sensing presence (UI* variants vs I*-only) */
bool voltage_hw = rbamp_has_voltage_hw(dev);
/* Number of current channels (1 / 2 / 3 / 5 / 7) */
uint8_t channels = rbamp_channels(dev);
/* Firmware: BASIC — REG_VERSION byte; STD — register-map version */
uint8_t fw = rbamp_firmware_version(dev);
/* STD only: identity, capabilities and the period mechanism */
rbamp_std_info_t info;
if (rbamp_line(dev) == RBAMP_LINE_STD && rbamp_std_info(dev, &info) == ESP_OK) {
/* info.capabilities, info.n_voltage, info.n_current, info.period_source */
}
: rbamp_line() distingue BASIC de STD. Utilisez l'étiquette SKU figurant sur le boîtier du module comme source de vérité pour le produit exact.
Où les détails dépendant de la gamme sont signalés dans la documentation
Dans le texte du composant et la documentation canonique, les fonctionnalités dépendant de la gamme sont signalées explicitement, par exemple :
— cette fonction n'est pas disponible sur le module BASIC (ESP_ERR_NOT_SUPPORTED).
Ou, à l'inverse, un comportement propre à BASIC :
: le compteur rbamp_energy_wh(dev, ch) est monotone — l'export vers le réseau n'est pas compté. Pour un comptage bidirectionnel, voir le scénario « Comptage bidirectionnel côté maître » dans 06_examples.md, ou utilisez un module STD.
Suite
-
03 · Choix du capteur de courant — quelle SCT-013 pour quel usage
-
04 · Câblage — particularités matérielles
-
06 · Exemples — scénarios pour BASIC, dont le comptage bidirectionnel côté maître
-
09 · Référence de l'API — l'API publique complète
Sources et tickets : rb-amp/rbamp-esp-idf · cette page dans le dépôt : docs/02_tiers.md (v1.7.3)