09 · Référence de l'API
L'API publique complète du composant rbamp pour ESP-IDF. La source est le fichier d'en-tête include/rbamp.h avec des commentaires Doxygen ; le gestionnaire multi-modules se trouve dans include/rbamp_fleet.h et le type d'accumulateur Wh dans include/rbamp_energy.h.
Ce chapitre est une référence : signatures, valeurs de retour, effets de bord, cas limites. Pour des exemples fonctionnels, consultez 06 · Exemples ; pour un démarrage rapide, voir 05 · Démarrage rapide.
Fichier d'en-tête
#include "rbamp.h" — l'en-tête public principal. Il inclut transitivement esp_err.h pour esp_err_t et driver/i2c_master.h pour le type i2c_master_bus_handle_t. Aucune inclusion supplémentaire n'est requise.
L'API est enveloppée dans un bloc extern "C" — compatible avec les appelants C et C++.
Idiomes généraux
L'API suit les schémas standard d'ESP-IDF :
-
Handle opaque :
rbamp_handle_t— un typedef pourstruct rbamp_obj_t *; l'utilisateur n'accède pas à ses éléments internes. Créé viarbamp_new(), libéré viarbamp_del(). -
Retours
esp_err_t—ESP_OKen cas de succès, l'un des codesESP_ERR_*en cas d'échec. UtilisezESP_ERROR_CHECK()pour une gestion avec arrêt sur erreur, ou vérifiez manuellement. -
Sortie par pointeur : les fonctions qui renvoient une valeur prennent un pointeur vers un tampon comme dernier paramètre. Cela permet à un seul appel de renvoyer à la fois un
esp_err_tet une valeur. -
Chaînes d'erreur lisibles :
rbamp_err_to_str(err)renvoie un pointeur vers une chaîne statique. Elle ne renvoie jamaisNULL. -
Un handle, deux gammes de modules : le même handle et la même API scalaire servent la gamme BASIC et la gamme STD ;
rbamp_begin()détecte la gamme et route chaque appel. Les fonctions qui n'existent que sur une gamme renvoientESP_ERR_NOT_SUPPORTEDsur l'autre (voirrbamp_line_tet Gamme STD). -
Les commandes ne sont pas réessayées. Une écriture de commande (instantané, réinitialisation, sauvegarde, ...) n'est jamais répétée après une erreur de transport — une nouvelle tentative pourrait délivrer l'opcode deux fois. Les lectures et écritures de registres de données conservent la nouvelle tentative sur NACK.
-
Correspondance des erreurs utilisée dans toute l'API :
ESP_ERR_NOT_SUPPORTED— la fonction ou la fonctionnalité n'existe pas sur cette gamme / ce firmware / ce module ;ESP_ERR_NOT_FOUND— le module ou l'enregistrement est absent (personne ne répond, pas d'enregistrement d'historique, pas de certificat) ;ESP_ERR_INVALID_STATE— une précondition ou un enchaînement d'appels est incorrect, ou un module à capteur appairé est protégé (voir Codes d'erreur).
Types
rbamp_handle_t
typedef struct rbamp_obj_t *rbamp_handle_t;
Un handle opaque vers un périphérique esclave. L'utilisateur n'a pas accès à ses champs. Créé via rbamp_new(), libéré via rbamp_del().
rbamp_topology_t
typedef enum {
RBAMP_TOPOLOGY_SINGLE = 1, /* 1 current channel (UI1 / I1) */
RBAMP_TOPOLOGY_SPLIT_PHASE = 2, /* 2 current channels (UI2 / I2) */
RBAMP_TOPOLOGY_THREE_PHASE = 3, /* 3 current channels (UI3 / I3) */
RBAMP_TOPOLOGY_FIVE_CH = 5, /* 5 current channels (UI5) */
RBAMP_TOPOLOGY_SEVEN_CH = 7, /* 7 current channels (UI7) */
} rbamp_topology_t;
La valeur est le nombre de canaux. rbamp_begin() le reprend de la variante du module ; rbamp_new_with_topology() le fige à la place. L'énumération est volontairement non contiguë (il n'y a ni 4 ni 6) : les SKU plus grands passent de 3 à 5 puis à 7.
Deux constantes dimensionnent vos tableaux :
| Macro | Valeur | Signification |
|---|---|---|
RBAMP_MAX_CHANNELS |
7 | Le plus grand nombre de canaux qu'un SKU expose. Dimensionnez les tableaux de canaux avec lui. |
RBAMP_SNAPSHOT_CHANNELS |
3 | Canaux portés par rbamp_snapshot_t (ch0 à 2). Les canaux 3 et plus sont lus avec rbamp_read_channel() / rbamp_read_all_channels(). |
rbamp_sensor_class_t
typedef enum {
RBAMP_SENSOR_UNSET = 0, /* Factory default */
RBAMP_SENSOR_SCT013 = 1, /* SCT-013 fitted by the user */
RBAMP_SENSOR_WIRED_CT = 2, /* Wired CT shipped with the module, calibrated as a pair */
RBAMP_SENSOR_BUILTIN_CT = 3, /* Built-in CT, calibrated as a pair */
} rbamp_sensor_class_t;
La classe 1 est un module auquel l'utilisateur adjoint une pince SCT-013 de son choix — le modèle de CT sélectionne le type de capteur. Les classes 2 et 3 sont des modules livrés avec leur capteur et calibrés avec lui. La bibliothèque ne réécrit pas la classe ni le modèle de ce type de module : rbamp_set_sensor_class() et rbamp_set_ct_model_ch() renvoient ESP_ERR_INVALID_STATE. Un réappairage de maintenance passe par rbamp_set_ct_model_ch_force().
rbamp_variant_t
La variante matérielle de construction, renvoyée par rbamp_variant() et rbamp_read_variant() :
| Valeur | Énumération | Canaux | Tension / puissance |
|---|---|---|---|
| 0 | RBAMP_VARIANT_UNKNOWN |
— | pas encore lu / non publié |
| 1 | RBAMP_VARIANT_UI1 |
1 | oui |
| 2 | RBAMP_VARIANT_UI2 |
2 | oui |
| 3 | RBAMP_VARIANT_UI3 |
3 | oui |
| 4 | RBAMP_VARIANT_I1 |
1 | non |
| 5 | RBAMP_VARIANT_I2 |
2 | non |
| 6 | RBAMP_VARIANT_I3 |
3 | non |
| 7 | RBAMP_VARIANT_UI5 |
5 | oui |
| 8 | RBAMP_VARIANT_UI7 |
7 | oui |
rbamp_line_t
typedef enum {
RBAMP_LINE_BASIC = 0, /* default until rbamp_begin() has run */
RBAMP_LINE_STD = 1,
} rbamp_line_t;
Un seul type de handle et une seule API servent les deux gammes de modules. rbamp_begin() détecte la gamme à partir du bloc d'identité du module, et chaque appel ultérieur est routé en interne. Interrogez-la avec rbamp_line(dev). Les appels sans équivalent sur la gamme détectée renvoient ESP_ERR_NOT_SUPPORTED — jamais une lecture de mauvais registre. Ce que seule la gamme STD offre (puissance réactive / apparente, THD, compteurs d'énergie signés, banques d'instantanés, historique) est regroupé dans Gamme STD.
rbamp_snapshot_t
Renvoyé par rbamp_read_all(). Tous les champs sont en unités SI. Les canaux inutilisés (au-delà de channels) sont remplis de zéros.
typedef struct {
float voltage; /* V — RMS voltage */
float voltage_peak; /* V — peak voltage */
float current[3]; /* A — RMS current, ch0–2 */
float current_peak[3]; /* A — peak current, ch0–2 */
float power[3]; /* W — active power, ch0–2 (signed) */
float power_factor[3]; /* dimensionless, −1..+1 */
float frequency; /* Hz — mains frequency */
rbamp_topology_t topology;
uint8_t channels; /* the module's channel count: 1, 2, 3, 5 or 7 */
bool has_voltage_hw; /* true if a voltage sensor is present */
uint8_t implausible; /* bitmask of RBAMP_FIELD_* classes set to NaN; 0 = all OK */
} rbamp_snapshot_t;
Les tableaux ne contiennent que les canaux 0–2. Sur un UI5/UI7, channels indique le nombre complet (5 ou 7) ; lisez les canaux 3+ avec rbamp_read_channel() / rbamp_read_all_channels().
Champs non plausibles. Un champ hors borne ne fait pas échouer tout l'instantané : un champ qui dépasse sa borne de cohérence par grandeur est mis à NaN et son bit de classe est levé dans implausible, tandis que le reste reste utilisable et que rbamp_read_all() renvoie toujours ESP_OK. Vérifiez implausible (ou isnan() par champ) avant d'exploiter une valeur.
| Bit | Signification |
|---|---|
RBAMP_FIELD_VOLTAGE |
voltage / voltage_peak rejeté |
RBAMP_FIELD_CURRENT |
un courant / current_peak rejeté |
RBAMP_FIELD_POWER |
une puissance rejetée |
RBAMP_FIELD_PF |
un power_factor rejeté |
RBAMP_FIELD_FREQUENCY |
fréquence rejetée |
Les bornes sont RBAMP_SANITY_LIMIT_V / _I / _P / _PF (500 V, 150 A, 30 000 W, 1.5). Seule une véritable défaillance de transport fait renvoyer une valeur non OK à rbamp_read_all().
rbamp_channel_reading_t
Renvoyé par rbamp_read_channel() / rbamp_read_all_channels() — un canal, n'importe quel indice.
typedef struct {
float i_rms; /* A */
float i_peak; /* A */
float p_real; /* W (signed) */
float pf; /* −1..+1 */
uint8_t implausible; /* RBAMP_FIELD_* bits; the flagged field is NaN */
} rbamp_channel_reading_t;
rbamp_period_snapshot_t
Renvoyé par rbamp_read_period_snapshot(). La primitive de comptabilisation de l'énergie.
typedef struct {
float avg_p[3]; /* W — average active power over the period, ch0–2 */
float max_p; /* W — peak power on channel 0 during the period */
uint32_t latch_ms; /* ms — module-reported duration; DIAGNOSTIC, not for energy */
uint32_t master_dt_ms; /* ms — master wall-clock window since the previous consumed read (CANONICAL) */
bool valid; /* the period was ready at read time */
float avg_p_total; /* W — average active power summed over ALL channels (signed) */
double wh_net; /* Wh — net energy of this period as the library accounted it (signed) */
bool module_restarted; /* the module rebooted inside this period */
uint32_t module_window_ms; /* ms — the module's own length of the closed window (0 on STD) */
uint16_t module_commit_ms; /* ms — length of one module commit as inferred: 100 or 200 (0 on STD) */
uint32_t module_uptime_s; /* s — module uptime read with the snapshot (0 if not published) */
bool window_from_boot; /* the window started at the module's boot */
bool window_long; /* module_window_ms exceeds 6 h */
} rbamp_period_snapshot_t;
| Champ | Remarques |
|---|---|
avg_p[3] |
Canaux 0–2 uniquement. Sur un UI5/UI7, le module prend son instantané de puissance moyenne pour tous les canaux de façon atomique ; lisez les canaux 3+ avec rbamp_read_period_avg_power() et leurs Wh avec rbamp_energy_wh() (l'accumulateur intègre chaque canal). |
max_p |
Un pic global, pris sur le canal 0. |
latch_ms |
Diagnostic seulement ; la durée peut paraître courte sous charge. La fenêtre d'intégration d'énergie est master_dt_ms ou module_window_ms. |
master_dt_ms |
La fenêtre sur laquelle la bibliothèque intègre l'énergie : le temps esp_timer propre du maître entre deux lectures consommées consécutives. |
avg_p_total, wh_net |
La période sommée sur tous les canaux. wh_net est la puissance moyenne × master_dt_ms, ou — sur les modules qui conservent l'énergie dans l'appareil — la différence de leur propre compteur. |
module_window_ms, module_commit_ms |
La mesure du module pour la fenêtre fermée : validations comptées sur l'horloge de mesure du module, 100 ms chacune sur le firmware actuel et 200 ms sur un firmware antérieur à la v1.2 — la bibliothèque déduit lequel à partir du même instantané. Sert normalement de contrôle croisé avec master_dt_ms. Les deux valent 0 sur la gamme STD. |
module_restarted |
Le module a redémarré pendant la période. Ses réglages en RAM (horloge, masque d'événements, seuils, champs du digest) doivent être réappliqués — la bibliothèque réapplique ceux qu'elle gère. Sur un module BASIC, cela se fait au premier instantané après rbamp_begin_resume() lorsque la fenêtre a commencé au démarrage du module. |
module_uptime_s, window_from_boot |
window_from_boot est vrai lorsque la fenêtre d'instantané a commencé au démarrage du module (un redémarrage, ou le premier instantané depuis le démarrage). Toujours faux lorsque le firmware ne publie pas le temps de fonctionnement (module_uptime_s = 0). |
window_long |
La fenêtre dépasse 6 h : la moyenne du module perd en précision sur des fenêtres très longues — prenez des instantanés plus souvent. |
⚠ latch_ms est un diagnostic, pas un outil pour l'énergie. C'est la mesure propre du module pour la période et elle peut être trop courte sous charge. Ne l'utilisez pas pour l'intégration de l'énergie. Le dt canonique pour l'énergie est master_dt_ms (ou votre propre delta esp_timer_get_time()), ou module_window_ms pour le premier instantané après rbamp_begin_resume().
Bits d'événement — rbamp_event_bit_t
Bits du drapeau EVENT_FLAGS persistant, à effacement par écriture de 1 (voir Événements) :
| Énumération | Signification |
|---|---|
RBAMP_EVENT_PERIOD_READY |
Un instantané de période a été pris |
RBAMP_EVENT_THRESH_I |
Seuil de courant franchi |
RBAMP_EVENT_THRESH_P |
Seuil de puissance franchi |
RBAMP_EVENT_ERROR |
Indicateur d'erreur durable (voir Modèle d'erreur) |
RBAMP_EVENT_CONFIG_CHANGED |
Configuration persistée modifiée |
RBAMP_EVENT_RESET_OCCURRED |
La réinitialisation du module depuis la dernière remise à zéro |
RBAMP_EVENT_NVM_FAULT |
STD seulement : défaut du stockage d'énergie |
rbamp_drdy_event_t
Rempli par rbamp_wait_data_ready() / rbamp_read_all_ready() :
typedef struct {
bool fresh; /* a new snapshot of THIS module is available (true on ESP_OK) */
bool by_edge; /* woken by the DRDY edge (false = found by polling) */
uint16_t seq; /* snapshot sequence now */
uint16_t missed; /* snapshots published since the previous call that were not read */
bool alarm; /* the line was held LOW: an unmasked event is pending on this module */
uint8_t event_flags; /* EVENT_FLAGS consumed on an alarm (RBAMP_EVENT_*), else 0 */
uint32_t latency_us; /* edge to return, µs (0 when polling) */
} rbamp_drdy_event_t;
Types de condensé
typedef enum {
RBAMP_DIGEST_I = ..., /* RMS current per channel */
RBAMP_DIGEST_U = ..., /* RMS voltage (modules with voltage sensing only) */
RBAMP_DIGEST_P = ..., /* real power per channel, whole watts, signed */
RBAMP_DIGEST_PF = ..., /* |power factor| per channel */
} rbamp_digest_field_t;
typedef struct {
uint8_t status; /* STATUS mirror at the moment of the publish */
uint8_t seq; /* window sequence (one step per published window, wraps 255→0) */
uint8_t n_ch; /* channels in the digest: min(module channels, 3) */
uint8_t fields; /* which rbamp_digest_field_t bits were read */
float i_a[3]; /* A; 0 when the field is off */
float u_v; /* V; 0 when off or no voltage sensing */
int16_t p_w[3]; /* W, signed, truncated toward 0 (|P| < 1 W reads 0); 0 when off */
float pf[3]; /* |PF| 0..1; 0 when off */
} rbamp_digest_t;
Types de correction SCT-013
typedef enum {
RBAMP_SCT_NONE, /* no correction (scale 1) */
RBAMP_SCT_CORRECTED, /* scale applied to this channel */
RBAMP_SCT_UNCALIBRATED, /* after a reset the module applies the raw preset; scale 1, warning logged */
RBAMP_SCT_GAIN_UNEXPECTED,/* applied gain is not that of a 30 A-calibrated module; scale 1, warning logged */
RBAMP_SCT_UNKNOWN_MODEL, /* model code without a known preset; scale 1, warning logged */
RBAMP_SCT_PENDING, /* not evaluated yet (before rbamp_begin); scale 1 */
} rbamp_sct_status_t;
typedef struct {
rbamp_sct_status_t status;
uint8_t model; /* CT model the module reports for the channel */
float scale; /* factor applied to current, power, energy and digest (1.0 unless CORRECTED) */
float gain_applied; /* gain the module applies (0 when not read) */
} rbamp_sct_correction_t;
RBAMP_SCT_NONE est signalé sur la gamme STD, pour la classe de capteur 2/3, sans modèle lié, avec le modèle 3 (le capteur 30 A d'usine), sur un module qui se corrige lui-même (voir Correction de calibre SCT-013) et lorsque CONFIG_RBAMP_SCT_RATING_CORRECTION est désactivé.
Les types de la gamme STD (rbamp_std_info_t, rbamp_std_channel_t, ...) sont décrits avec leurs fonctions dans Gamme STD.
Cycle de vie
rbamp_new
esp_err_t rbamp_new(i2c_master_bus_handle_t bus,
uint8_t addr,
rbamp_handle_t *out);
Crée un handle opaque pour un appareil esclave. En interne, il crée un i2c_master_dev_handle_t via i2c_master_bus_add_device().
Le nombre de canaux et la présence de tension sont repris du module dans rbamp_begin() : un UI1 signale 1 canal, un UI3 en signale 3, un UI7 en signale 7, etc., si bien que rbamp_channels(dev) est juste après begin et que l'API par canal (rbamp_set_ct_model_ch, ...) protège contre les canaux absents du module. Ce n'est que lorsque le module ne publie pas sa variante (firmware antérieur à v1.3) que le handle retombe sur RBAMP_TOPOLOGY_THREE_PHASE ; la surdétection y est sans conséquence — les canaux inutilisés lisent 0.0 A. Utilisez rbamp_new_with_topology() pour figer un nombre quel que soit ce que dit le module.
| Paramètre | Description |
|---|---|
bus |
Handle de bus I²C créé via i2c_new_master_bus(). |
addr |
Adresse esclave sur 7 bits. Plage 0x08..0x77, défaut 0x50. |
out |
Où écrire le nouveau handle. |
Retours : ESP_OK en cas de succès ; ESP_ERR_NO_MEM si la mémoire n'a pu être allouée ; ESP_ERR_INVALID_ARG si bus == NULL ou out == NULL ou si addr est hors plage ; le esp_err_t issu de i2c_master_bus_add_device() en cas d'erreur du pilote de bus.
rbamp_new_with_topology
esp_err_t rbamp_new_with_topology(i2c_master_bus_handle_t bus,
uint8_t addr,
rbamp_topology_t topology,
rbamp_handle_t *out);
Identique à rbamp_new, mais avec une topologie explicite. Elle fixe le nombre de canaux : rbamp_begin() le conserve même si le module en annonce un autre (un avertissement est journalisé). La variante et la présence de tension suivent toujours le module. Nécessaire uniquement pour un firmware antérieur à la v1.3 qui ne publie pas sa variante, ou pour exposer délibérément moins ou plus de canaux que n'en possède le module.
rbamp_del
void rbamp_del(rbamp_handle_t dev);
Libère le handle et retire le i2c_master_dev_handle_t associé du bus. Sans danger avec NULL — c'est un no-op.
rbamp_begin
02 · Initialisation et démarrage (initialization) · BASIC ou STD ? (initialization) · Cycle d'interrogation continu (recommandé) (period-metering)
esp_err_t rbamp_begin(rbamp_handle_t dev);
Sonde l'appareil, détecte la gamme du module, adopte le nombre de canaux et la variante, et amorce un instantané.
Sequence:
-
Lit
REG_VERSION(0x03). Si l'appareil n'a pas envoyé d'ACK —ESP_FAIL. S'il a renvoyé0x00/0xFF—ESP_ERR_INVALID_RESPONSE. -
Détecte la gamme de produits (BASIC / STD) à partir du bloc d'identité du module et la met en cache (
rbamp_line()). Sur la gamme STD, l'identité est aussi mise en cache (rbamp_std_info()) et le mécanisme de période est choisi. -
Adopte le nombre de canaux, la variante et la présence de tension depuis le module (sauf si une topologie a été figée par
rbamp_new_with_topology). -
Évaluez la correction de calibre SCT-013 (voir Correction de calibre SCT-013).
-
Envoyer
CMD_LATCH_PERIODcomme amorçage + attendre 50 ms. Le premier instantané après la mise sous tension est écarté. (rbamp_begin_resume()saute cette étape.) -
Sauvegardez
esp_timer_get_time()pour l'intégration d'énergie ultérieure.
Idempotent mais pas gratuit : chaque appel émet un instantané d'amorçage.
Retours : ESP_OK en cas de succès ; les codes d'erreur ci-dessus sinon.
rbamp_begin_resume
esp_err_t rbamp_begin_resume(rbamp_handle_t dev);
rbamp_begin() sans l'instantané d'amorçage — il conserve la fenêtre que le module a accumulée pendant l'absence du maître. Un module BASIC continue de moyenner jusqu'au prochain instantané, donc après un redémarrage ou une panne du maître, le module conserve toute la fenêtre depuis le dernier instantané consommé ; rbamp_begin() prendrait un instantané et le jetterait, cet appel ne le fait pas.
Le premier rbamp_read_period_snapshot() valide consommé après intègre sur la fenêtre propre du module (module_window_ms) : wh_net = avg_p_total × module_window_ms, master_dt_ms est égal à module_window_ms et module_restarted = window_from_boot. Chaque instantané ultérieur utilise l'horloge maître comme d'habitude. Une première lecture périmée (période non valide, accumulateur vide) est écartée comme toute autre, et la lecture valide suivante utilise toujours la fenêtre du module.
Sur un firmware qui ne publie pas la durée de fonctionnement, window_from_boot et module_restarted restent à faux : la fenêtre récupérée peut alors inclure un redémarrage du module que la bibliothèque ne peut pas voir. Sur les modules STD, l'appel est identique à rbamp_begin() (leur énergie réside dans des compteurs du module).
rbamp_begin_event_flags
uint8_t rbamp_begin_event_flags(rbamp_handle_t dev);
Les EVENT_FLAGS tels que rbamp_begin() les a trouvés (les deux gammes ; 0 s'ils n'étaient pas lisibles). RBAMP_EVENT_RESET_OCCURRED signifie ici que le module avait redémarré avant que la bibliothèque ne le rencontre — réappliquez ses réglages en RAM (horloge, masque d'événements, seuils). La bibliothèque n'efface rien au begin. Aucun trafic sur le bus.
rbamp_probe
esp_err_t rbamp_probe(rbamp_handle_t dev);
Un contrôle de vie léger. Une seule lecture de REG_VERSION, sans effet de bord.
Retour : ESP_OK si l'esclave a envoyé un ACK et signalé une version prise en charge (ni 0 ni 0xFF) ; ESP_FAIL sinon.
rbamp_wait_ready
02 · Initialisation et démarrage (initialization) · 3. DATA_VALID (0xCE) ne passe jamais à 1 (troubleshooting) · 4 · Carte des registres (production v1.3) (api-reference)
esp_err_t rbamp_wait_ready(rbamp_handle_t dev, uint32_t timeout_ms);
Interroge le drapeau prêt du module jusqu'à ce que le bit 0 soit positionné. Utile après la mise sous tension — le module peut avoir besoin de jusqu'à 100 ms pour la première fenêtre RT.
Retours : ESP_OK si le bit est vu avant l'expiration de timeout_ms ; ESP_ERR_TIMEOUT sinon.
Accesseurs d'état du handle
BASIC ou STD ? (initialization) · Courant multicanal (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.10 Bloc temps réel V03 (0x86..0xBD) (api-reference)
uint8_t rbamp_firmware_version(rbamp_handle_t dev);
rbamp_topology_t rbamp_topology (rbamp_handle_t dev);
uint8_t rbamp_channels (rbamp_handle_t dev);
rbamp_variant_t rbamp_variant (rbamp_handle_t dev);
bool rbamp_has_voltage_hw (rbamp_handle_t dev);
uint8_t rbamp_address (rbamp_handle_t dev);
rbamp_line_t rbamp_line (rbamp_handle_t dev);
Renvoient toutes des valeurs en cache sans accéder au bus.
| Fonction | Retours |
|---|---|
rbamp_firmware_version |
L'octet REG_VERSION mis en cache après rbamp_begin() — sur la gamme STD, il s'agit de la version de la carte de registres, non de la version de l'image du firmware (voir rbamp_std_read_image_version). 0 avant rbamp_begin() ou en cas d'échec. |
rbamp_topology |
L'énumération du nombre de canaux — issue du module après rbamp_begin(), ou figée par rbamp_new_with_topology() ; THREE_PHASE avant begin / sur un firmware qui ne publie pas sa variante. |
rbamp_channels |
Nombre de canaux de courant valides (1, 2, 3, 5 ou 7). |
rbamp_variant |
La variante mise en cache par rbamp_begin() ; RBAMP_VARIANT_UNKNOWN avant begin ou lorsque le module ne la publie pas. rbamp_read_variant() relit le registre. |
rbamp_has_voltage_hw |
true si le matériel de détection de tension a été détecté. |
rbamp_address |
L'adresse 7 bits actuelle (mise à jour après rbamp_commit_address_change()). |
rbamp_line |
RBAMP_LINE_BASIC jusqu'à ce que rbamp_begin() ait été exécuté, puis la gamme détectée. |
rbamp_basic_fw_name
const char *rbamp_basic_fw_name(uint8_t version);
Une simple table de correspondance (sans trafic sur le bus) : le nom de firmware lisible pour un octet REG_VERSION BASIC tel que renvoyé par rbamp_firmware_version() — par exemple 0x0D → "1.4.21", 0x0C → "1.4.20", 0x0B → "1.4.19", 0x0A → "1.4.18", 0x07 → "1.4.15-1.4.17", 0x05 → "1.4.4-1.4.14", 0x04 → "1.2-1.4.3", 0x00..0x03 → "<1.2". Tout autre octet → NULL (inconnu, ou non BASIC).
Lectures temps réel (bloc RT, rafraîchissement de 100 ms)
Toutes les fonctions renvoient esp_err_t. En cas de ESP_OK, la valeur est écrite au pointeur out ; en cas d'erreur, *out est indéfini. En coulisse, une discipline de reprise et de cohérence assure la résilience face aux rares incidents de liaison de la pile I²C d'ESP-IDF.
Lectures par canal
Référence des registres RT (realtime-polling) · Comptabilité bidirectionnelle (period-metering)
esp_err_t rbamp_read_voltage (rbamp_handle_t dev, uint8_t phase, float *out);
esp_err_t rbamp_read_voltage_peak (rbamp_handle_t dev, uint8_t phase, float *out);
esp_err_t rbamp_read_current (rbamp_handle_t dev, uint8_t ch, float *out);
esp_err_t rbamp_read_current_peak (rbamp_handle_t dev, uint8_t ch, float *out);
esp_err_t rbamp_read_power (rbamp_handle_t dev, uint8_t ch, float *out);
esp_err_t rbamp_read_power_factor (rbamp_handle_t dev, uint8_t ch, float *out);
esp_err_t rbamp_read_frequency (rbamp_handle_t dev, float *out);
| Fonction | Valeur de retour | Remarques |
|---|---|---|
rbamp_read_voltage |
Tension efficace, V | phase = 0 sur la gamme BASIC |
rbamp_read_voltage_peak |
Tension de crête, V | Lit 0 sur la carte STD 0x34 et antérieures — utilisez le max_u / min_u d'une banque d'instantanés |
rbamp_read_current |
Courant efficace du canal, A | ch < rbamp_channels(dev) ; les canaux 3 et plus (UI5 / UI7) passent transparemment par la fenêtre de canaux |
rbamp_read_current_peak |
Courant de crête du canal, A | Lit 0 sur la carte de mappage STD 0x34 et antérieures — utilisez le max_i d'une banque d'instantanés |
rbamp_read_power |
Puissance active, W (signée) | Négatif = export (installations PV / bidirectionnelles) |
rbamp_read_power_factor |
Facteur de puissance | Sans dimension, −1..+1 |
rbamp_read_frequency |
Fréquence du secteur, Hz | 50.0 ou 60.0 sur un réseau sain. STD : une valeur de module de 0 (pas de secteur) renvoie ESP_ERR_INVALID_RESPONSE avec *out = NaN |
Si ch ou phase est hors plage, renvoie ESP_ERR_INVALID_ARG.
Lecture unique de tout le bloc RT
Référence des registres RT (realtime-polling) · Interrogation — module unique (realtime-polling) · 4.10 Bloc temps réel V03 (0x86..0xBD) (api-reference)
esp_err_t rbamp_read_all(rbamp_handle_t dev, rbamp_snapshot_t *out);
Équivalent à des appels séquentiels de rbamp_read_voltage + rbamp_read_voltage_peak + rbamp_read_current(0..N) + rbamp_read_current_peak(0..N) + rbamp_read_power(0..N) + rbamp_read_power_factor(0..N) + rbamp_read_frequency. Les canaux inutilisés (au-delà de rbamp_channels(dev)) sont remplis de zéros.
Sur un module à plus de trois canaux (UI5 / UI7), seuls les canaux 0 à 2 sont lus dans la structure (RBAMP_SNAPSHOT_CHANNELS = 3) ; les canaux 3 et plus ne sont pas touchés — lisez-les avec rbamp_read_channel() / rbamp_read_all_channels(). Sur la gamme STD, le bloc de tension et chaque bloc de canal sont lus en entier (une transaction chacun).
Un champ qui dépasse sa borne de cohérence ne fait pas échouer l'appel : il est mis à NaN et signalé dans snap.implausible, et l'appel renvoie toujours ESP_OK (voir rbamp_snapshot_t).
Retours : ESP_OK en cas de succès (vérifiez implausible) ; la première erreur de transport sinon — auquel cas le contenu de out est partiel et ne doit pas être utilisé.
Puissances réactive et apparente
esp_err_t rbamp_read_reactive_power(rbamp_handle_t dev, uint8_t ch, float *out);
esp_err_t rbamp_read_apparent_power(rbamp_handle_t dev, uint8_t ch, float *out);
Puissance réactive du canal ch en var (signée) et puissance apparente en VA. Ces grandeurs n'existent que sur la gamme STD ; sur BASIC, la puissance réactive n'est pas exposée par cette bibliothèque, et sur un handle BASIC les deux renvoient ESP_ERR_NOT_SUPPORTED.
Accès aux canaux (canaux 3 et plus)
Courant multi-canaux (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.14 Fenêtre d'accès aux canaux (0x32 + 0x3C..0x3F) (api-reference)
Les canaux 0 à 2 se trouvent dans le bloc RT plat. Sur les références plus grandes (UI5 / UI7), les canaux 3 et plus ne sont accessibles que par la fenêtre de canaux du module. La bibliothèque gère cela de façon transparente : rbamp_read_current(), rbamp_read_current_peak(), rbamp_read_power() et rbamp_read_power_factor() acceptent tout ch dans 0..rbamp_channels(dev)-1 et passent les canaux 3 et plus par la fenêtre. La sélection de fenêtre est une ressource unique partagée dans le module, et la sélection + la lecture forment une section atomique — ne partagez pas un handle entre tâches sans votre propre mutex.
esp_err_t rbamp_read_channel (rbamp_handle_t dev, uint8_t ch,
rbamp_channel_reading_t *out);
esp_err_t rbamp_read_all_channels(rbamp_handle_t dev,
rbamp_channel_reading_t *out, uint8_t n);
-
rbamp_read_channellit les quatre champs RT d'un canal dans unrbamp_channel_reading_t. Un champ qui dépasse sa borne de cohérence vautNaNavec son bitRBAMP_FIELD_*dansimplausible. -
rbamp_read_all_channelsremplitout[]avec chaque canal renseigné ;nest la capacité deout(dimensionnez-la avecRBAMP_MAX_CHANNELS) ; l'appel remplitmin(n, rbamp_channels(dev))entrées.
Retour : ESP_OK (vérifiez implausible) ; ESP_ERR_INVALID_ARG pour un canal invalide ou NULL ; sinon la première erreur de transport.
Ce sont des valeurs en direct, instantanées. Un balayage des canaux lit des fenêtres de publication adjacentes et n'est pas un instantané simultané — pour une énergie alignée sur les canaux, utilisez le chemin par période.
rbamp_read_all() sur un UI5 / UI7 renvoie les trois premiers canaux (RBAMP_SNAPSHOT_CHANNELS = 3) et laisse le reste intact ; snap.channels indique toujours le nombre réel de canaux du module.
rbamp_read_commit_seq
esp_err_t rbamp_read_commit_seq(rbamp_handle_t dev, uint8_t *out);
Lit l'octet de séquence du condensé : un uint8_t qui s'incrémente une fois par fenêtre de mesure (toutes les 100 ms sur le firmware actuel, 200 ms sur les images antérieures à v1.2 ; revient de 255 à 0). Lisez-le avant et après un balayage multi-registres — une valeur inchangée prouve que toutes les lectures proviennent d'un même commit. Le condensé ne comporte pas de CRC.
Data-ready (DRDY)
01 · Connexion matérielle (hardware-connection) · 03 · Interrogation temps réel (realtime-polling) · Interrogation — module unique (realtime-polling)
DRDYsortie : repos HAUT (résistance de rappel du maître), une impulsion BASSE d'environ 10 µs à chaque publication d'un instantané de mesure complet (toutes les 100 ms sur toute la famille ; images BASIC antérieures à v1.2 et images STD jusqu'à 0x7B : 200 ms). Plusieurs modules peuvent partager une ligne en OU câblé. Les modules BASIC maintiennent aussi la ligne fermement au niveau BAS tant qu'un événement non masqué est en attente (alarme).
La bibliothèque transforme l'impulsion en réveil, de sorte qu'un lecteur ne relise jamais le même instantané, ne chevauche jamais une publication et apprenne combien d'instantanés il a manqués. Sur les modules STD, le compteur de publication indique quel module a émis l'impulsion sur une ligne partagée. Sans fil DRDY, les mêmes appels fonctionnent par scrutation du compteur du module tous les CONFIG_RBAMP_DRDY_POLL_MS. Les modules STD antérieurs à l'image 0x00010075 pilotent la broche différemment : la bibliothèque les considère comme dépourvus de ligne DRDY et scrute.
esp_err_t rbamp_set_drdy_gpio (rbamp_handle_t dev, int gpio);
esp_err_t rbamp_wait_data_ready(rbamp_handle_t dev, uint32_t timeout_ms,
rbamp_drdy_event_t *ev);
esp_err_t rbamp_read_all_ready (rbamp_handle_t dev, uint32_t timeout_ms,
rbamp_snapshot_t *out, rbamp_drdy_event_t *ev);
esp_err_t rbamp_read_data_seq (rbamp_handle_t dev, uint16_t *out);
| Fonction | Description |
|---|---|
rbamp_set_drdy_gpio(dev, gpio) |
Raccorde la ligne DRDY de ce module, ou la détache avec -1. La broche GPIO est configurée en entrée avec rappel et interruption sur front descendant ; un nombre quelconque de handles peut partager une même broche. Appelez-la après rbamp_begin() (le contrat électrique de la ligne dépend du module détecté). Renvoie ESP_ERR_NO_MEM si plus de 4 lignes distinctes ou 8 handles par ligne sont utilisés. |
rbamp_wait_data_ready(dev, timeout_ms, ev) |
Bloque jusqu'à ce que le module ait publié un instantané plus récent que le dernier renvoyé par cet appel (ou que la dernière lecture via rbamp_read_all_ready), au plus timeout_ms. ev peut être NULL. |
rbamp_read_all_ready(dev, timeout_ms, out, ev) |
rbamp_wait_data_ready() suivi de rbamp_read_all() : une lecture cohérente par instantané publié, jamais le même instantané deux fois. |
rbamp_read_data_seq(dev, &seq) |
La séquence d'instantanés en cours, sans attente. |
Fonctionnement de l'attente avec une ligne DRDY. Elle se réveille sur le front descendant, puis vérifie que la séquence du module a avancé (une impulsion sur une ligne partagée peut appartenir à un autre module — l'appel continue d'attendre). Si la ligne est toujours au niveau BAS 5 ms après le front, un événement non masqué est en attente sur un module quelconque de la ligne : les drapeaux de chaque module rattaché sont lus puis effacés (écriture de 1 pour effacer, ce qui libère la ligne — une ligne maintenue masquerait les impulsions des autres modules). Les drapeaux de ce module reviennent dans ev avec alarm positionné ; les drapeaux des autres modules sont remis à leurs propres handles et signalés lors de leur prochaine attente.
Retours (rbamp_wait_data_ready) : ESP_OK (instantané frais) ; ESP_ERR_TIMEOUT ; ESP_ERR_NOT_SUPPORTED sur les modules STD sans compteur de publication (version de carte de registres inférieure à 0x36).
rbamp_set_drdy_gpio(dev, GPIO_NUM_4);
while (1) {
rbamp_snapshot_t s;
rbamp_drdy_event_t ev;
if (rbamp_read_all_ready(dev, 500, &s, &ev) == ESP_OK) {
if (ev.missed) ESP_LOGW(TAG, "missed %u snapshot(s)", ev.missed);
/* use s — exactly one read per published snapshot */
}
}
Digest BASIC
4.9 Fenêtre digest (0x70..0x85) (api-reference) · 8.7 Aller-retour DIGEST — configurer + lire (api-reference)
Le digest est un bloc compact qu'un module BASIC publie à chaque fenêtre. Il permet au maître de lire le résultat de la fenêtre en une seule transaction I²C au lieu d'une par champ.
esp_err_t rbamp_set_digest_fields(rbamp_handle_t dev, uint8_t fields);
esp_err_t rbamp_read_digest (rbamp_handle_t dev, rbamp_digest_t *out);
-
rbamp_set_digest_fields(dev, fields)choisit les champs que le module empaquette dans le digest : un OR deRBAMP_DIGEST_I,_U,_P,_PF(non 0). La valeur par défaut, lorsque l'appel n'a jamais été fait, est courant + puissance réelle, plus la tension sur les modules avec détection de tension. Le choix est écrit dans le module à la prochainerbamp_read_digest()(ou immédiatement, lorsque le handle est déjà démarré sur un module BASIC doté de la capacité digest). Le module le conserve en RAM seulement, donc la bibliothèque le réécrit après un redémarrage de module détecté. RetoursESP_ERR_INVALID_ARGpour 0, pour des bits inconnus, ou lorsque le module rejette un champ qu'il n'a pas (tension sur un module à courant seul) ;ESP_ERR_NOT_SUPPORTEDsur la gamme STD ou sur un firmware sans la capacité digest. -
rbamp_read_digest(dev, &d)lit l'état, la séquence de fenêtre et les champs choisis pour les canaux 0 à 2 en une seule transaction. Conçu pour lire chaque fenêtre publiée sur DRDY :rbamp_wait_data_ready()puisrbamp_read_digest()donne la puissance réelle signée de chaque fenêtre pour quelques octets de bus. Les canaux 3 et plus ne sont pas dans le digest (utilisezrbamp_read_channel()). La puissance réelle est exprimée en watts entiers — une charge inférieure à 1 W lit 0. RetoursESP_OK;ESP_ERR_NOT_SUPPORTEDsur la gamme STD ou sur un firmware BASIC sans la capacité digest ; erreurs de transport.
Comptabilisation par période
Voir 01 · Présentation pour la vue d'ensemble et 05 · Démarrage rapide, étape 5, pour un modèle minimal.
rbamp_latch_period
esp_err_t rbamp_latch_period(rbamp_handle_t dev);
Écrit CMD_LATCH_PERIOD (0x27) dans REG_COMMAND. Il n'attend pas — l'appelant doit laisser 50 ms de stabilisation et vérifier rbamp_is_period_valid() avant de lire.
Pour la plupart des usages, utilisez rbamp_read_period_snapshot() — il encapsule toute la séquence.
rbamp_is_period_valid
04 · Comptage par période et comptabilité tarifaire (period-metering) · Calibration et précision (troubleshooting) · 7.5 Préservation de la période après un instantané échoué (api-reference)
esp_err_t rbamp_is_period_valid(rbamp_handle_t dev, bool *out);
Lit le bit d'instantané prêt. *out = true si le dernier instantané est frais.
rbamp_read_period_avg_power
Registres d'instantané de période (period-metering) · 4.11 Bloc de période V03 (0xBE..0xCF) (api-reference) · 4.12 V03 Q + période ch0 (0xD0..0xE3, build de production) (api-reference)
esp_err_t rbamp_read_period_avg_power(rbamp_handle_t dev,
uint8_t ch, float *out);
Puissance active moyenne sur le canal pendant la période de l'instantané. Doit être appelée après rbamp_latch_period() + une stabilisation de 50 ms + une vérification de validité.
rbamp_read_period_max_power
Registres d'instantané de période (period-metering) · 4.12 V03 Q + période ch0 (0xD0..0xE3, build de production) (api-reference)
esp_err_t rbamp_read_period_max_power(rbamp_handle_t dev, float *out);
Puissance instantanée de crête sur le canal 0 pendant la période d'instantané. ch=0 uniquement sur le firmware v1.
rbamp_read_period_latch_ms
13. Dérive d'horloge multi-modules dans les longs tests (troubleshooting) · 4.13 dt côté puce de diagnostic (0xEC) (api-reference)
esp_err_t rbamp_read_period_latch_ms(rbamp_handle_t dev, uint32_t *out);
La durée de la période telle que vue par l'appareil, en ms.
La durée annoncée par le module peut paraître courte sous charge. Pour l'intégration d'énergie, utilisez master_dt_ms (ou module_window_ms) de rbamp_period_snapshot_t, non ce champ.
rbamp_read_period_snapshot
Cycle d'interrogation continu (recommandé) (period-metering) · Multi-modules — instantané simultané (period-metering) · Calibration et précision (troubleshooting)
esp_err_t rbamp_read_period_snapshot(rbamp_handle_t dev,
rbamp_period_snapshot_t *out,
uint16_t settle_ms,
bool skip_latch);
Le point d'entrée recommandé pour la comptabilisation par période. La séquence complète en coulisse :
-
Si
skip_latch == true— ne pas écrire LATCH (utilisé après une série manuelle de commandes d'instantané ou un instantané diffusé pour la synchronisation multi-module). -
Sinon — écrivez
CMD_LATCH_PERIOD. - Capturez
esp_timer_get_time()pour calculermaster_dt_ms. vTaskDelay(pdMS_TO_TICKS(settle_ms))— 50 ms par défaut.-
Vérifiez l'indicateur d'instantané prêt. S'il vaut 0 — positionnez
ESP_ERR_INVALID_RESPONSEet enregistrez l'horodatage (pour que l'instantané suivant ne compte pas deux foisdt). -
Lisez
avg_p[0..channels-1]+max_p+latch_ms. - Met à jour l'horodatage + appelle l'intégrateur d'énergie pour tous les canaux (si le composant n'est pas compilé avec
CONFIG_RBAMP_DISABLE_ENERGY).
| Paramètre | Description |
|---|---|
out |
Structure de sortie. |
settle_ms |
Attendez après l'instantané (50 recommandé). |
skip_latch |
Si true — n'écrivez pas LATCH, lisez seulement (pour le schéma multi-module). |
Retour : ESP_OK si out->valid == true ; ESP_ERR_INVALID_RESPONSE si l'instantané est périmé (dans ce cas l'énergie n'est pas intégrée et l'ancrage est conservé) ; ESP_ERR_NOT_SUPPORTED sur un module STD qui n'offre ni banques d'instantanés ni compteurs ; sinon le esp_err_t issu des opérations de bus. Voir Appels de période sur la gamme STD pour le comportement STD.
L'énergie s'intègre sur master_dt_ms — la fenêtre propre du maître entre deux lectures consommées successives. Après rbamp_begin_resume(), le premier instantané consommé s'intègre plutôt sur la fenêtre propre du module.
Entre deux appels d'instantané : 60 s est confortable, 30 s est limite, < 10 s garantit des lectures périmées. Le firmware intègre en interne l'accumulateur périodique ; appeler rbamp_read_period_snapshot() plus souvent que le firmware ne peut préparer la période suivante renverra toujours un instantané périmé (ESP_ERR_INVALID_RESPONSE). Pour une télémétrie à haute cadence, utilisez les fonctions RT rbamp_read_power(ch) / rbamp_read_all() — elles se rafraîchissent à ~10 Hz.
rbamp_read_uptime_s
Détecter un redémarrage du module (period-metering) · 4.6 Santé / diagnostics (0x46..0x4F) (api-reference)
esp_err_t rbamp_read_uptime_s(rbamp_handle_t dev, uint32_t *out);
Secondes depuis le démarrage du module. Une valeur décroissante entre deux lectures signifie que le module a redémarré. Sur un firmware BASIC qui ne publie pas la durée de fonctionnement, elle vaut 0.
Appels de période sur la gamme STD
La même API de période sert les deux gammes, mais ce qui se passe en dessous dépend de ce qu'offre le module STD (rbamp_std_info_t.period_source, décidé par rbamp_begin()) :
period_source |
Comportement de rbamp_read_period_snapshot() |
|---|---|
RBAMP_STD_PERIOD_LATCH |
Le module dispose de banques d'instantanés. La bibliothèque utilise la banque 0 (armée par rbamp_begin()) : elle latch, attend au moins 300 ms quelle que soit une valeur settle_ms plus petite (le module prend l'instantané à sa prochaine limite de fenêtre de mesure), lit la banque et la convertit en énergie sur master_dt_ms. Avec skip_latch, l'appelant gère le calendrier : latch, attente ≥ 300 ms, puis lecture. Gardez le bit 0 positionné dans rbamp_std_arm_banks(). |
RBAMP_STD_PERIOD_COUNTERS |
Pas de banques d'instantanés, mais des compteurs de durée de vie persistants. Aucun latch n'est envoyé et settle_ms / skip_latch sont ignorés : l'appel lit les compteurs et indique la différence depuis la lecture consommée précédente dans avg_p_total / wh_net. Rien n'est perdu lors d'un redémarrage du module (module_restarted le signale). |
RBAMP_STD_PERIOD_NONE |
Aucun des deux. Les appels de période renvoient ESP_ERR_NOT_SUPPORTED au lieu de signaler silencieusement une période invalide. |
Pour le chemin des compteurs : avg_p[] contient la période pour un module à canal unique, les différences de compteurs par canal sur les modules qui publient des compteurs par canal, et NaN sur les modules multi-canaux qui n'en publient pas ; max_p vaut NaN. Sur les modules à compteurs sans compteurs fins, choisissez une période assez longue pour qu'un pas de compteur soit une petite fraction de celle-ci (minutes, pas secondes). ESP_ERR_INVALID_RESPONSE réancre la bibliothèque (cette période est écartée) lorsque le compteur de génération du module a changé (ses compteurs ont été remis à zéro ou adoptés) ou qu'un compteur a reculé.
Autres remarques STD : rbamp_latch_period() latch la banque 0 (sans effet, renvoie ESP_OK sur les modules à compteurs) ; rbamp_is_period_valid() est vrai sur les modules à compteurs dès que la bibliothèque détient un ancrage de compteur (toujours après rbamp_begin()) ; rbamp_read_period_avg_power() renvoie la moyenne de la dernière période consommée pour les modules à compteurs à canal unique et ESP_ERR_NOT_SUPPORTED sur les modules multi-canaux ; rbamp_read_period_max_power() renvoie ESP_ERR_NOT_SUPPORTED sur les modules à compteurs ; rbamp_read_period_snapshot() renvoie ESP_ERR_INVALID_RESPONSE lorsque la banque 0 ne signale aucune fenêtre écoulée — si une réinitialisation du module a effacé le masque d'armement de la banque, la bibliothèque réarme la banque 0, prend un instantané d'amorçage et redémarre l'ancrage d'horloge (cette fenêtre-là n'est pas intégrée, la suivante redevient complète).
Fonction d'aide en ligne
static inline esp_err_t
rbamp_read_period_snapshot_simple(rbamp_handle_t dev,
rbamp_period_snapshot_t *out);
Un raccourci pour les arguments par défaut : settle_ms=50, skip_latch=false. À utiliser pour l'interrogation périodique ordinaire.
Comptabilisation de l'énergie (accumulateur côté maître)
Algorithme côté maître (period-metering) · 7 · Sémantique (api-reference)
Si le composant est compilé sans CONFIG_RBAMP_DISABLE_ENERGY=y, des fonctions d'accès sont disponibles pour l'accumulateur Wh à l'intérieur du handle :
double rbamp_energy_wh (rbamp_handle_t dev, uint8_t ch);
void rbamp_energy_reset (rbamp_handle_t dev, uint8_t ch);
void rbamp_energy_reset_all (rbamp_handle_t dev);
void rbamp_energy_disable (rbamp_handle_t dev);
void rbamp_energy_enable (rbamp_handle_t dev);
L'accumulateur est mis à jour automatiquement à chaque rbamp_read_period_snapshot() réussi. Il est signé — une valeur négative signifie export net.
| Fonction | Description |
|---|---|
rbamp_energy_wh(dev, ch) |
Total Wh courant du canal. Si ch est hors plage — 0.0. |
rbamp_energy_reset(dev, ch) |
Remet à zéro un seul canal. |
rbamp_energy_reset_all(dev) |
Remettre à zéro tous les canaux. |
rbamp_energy_disable(dev) |
Désactive l'intégration automatique. Utile lorsque le maître gère lui-même la persistance des Wh (veille profonde — voir 06 · Exemples scénario 9). |
rbamp_energy_enable(dev) |
Réactivez l'intégration automatique. |
rbamp_energy_wh() accepte soit un indice de canal (0..rbamp_channels(dev)-1, jusqu'à 6 sur un UI7), soit le sélecteur RBAMP_ENERGY_CH_TOTAL (0xFF) pour le total de tous les canaux. La valeur est signée — négative signifie export net — et vaut 0 si ch est hors plage ou si l'énergie est désactivée.
Modules STD sans banques d'instantanés (voie des compteurs) : le total est la somme des différences des compteurs propres du module — exacte, rien n'est intégré côté hôte. Les valeurs par canal proviennent des compteurs par canal du module lorsqu'il les publie, valent NaN sur les modules multicanaux qui ne les publient pas, et égalent le total sur les modules monocanaux.
Formule d'intégration :
wh[ch] += snap.avg_p[ch] × master_dt_ms / 1000 / 3600
[W] [milliseconds] → [Wh]
Compilé avec CONFIG_RBAMP_DISABLE_ENERGY=y, les fonctions (prototypes et stockage) sont retirées du binaire via les gardes #if — un appel à rbamp_energy_wh() produit une erreur d'édition de liens « unresolved external ».
Le type de l'accumulateur (rbamp_energy.h)
L'accumulateur derrière le handle se trouve dans un en-tête séparé, rbamp_energy.h. L'en-tête le décrit comme une API interne — l'application utilise normalement les enveloppes rbamp_energy_* ci-dessus et n'a jamais besoin de celle-ci. Elle est listée ici parce que ses symboles sont visibles :
typedef struct {
double wh[RBAMP_ENERGY_MAX_CH]; /* per-channel running total, Wh (signed) */
double wh_total; /* all-channel total, Wh (signed) */
bool enabled; /* false: tick() is a no-op */
} rbamp_energy_t;
void rbamp_energy_init (rbamp_energy_t *e);
void rbamp_energy_tick (rbamp_energy_t *e, const float avg_p[], uint8_t channels,
uint32_t period_ms, bool valid);
double rbamp_energy_wh_get (const rbamp_energy_t *e, uint8_t ch);
void rbamp_energy_add_wh (rbamp_energy_t *e, uint8_t ch, double wh);
void rbamp_energy_reset_ch (rbamp_energy_t *e, uint8_t ch);
void rbamp_energy_reset_all_ch(rbamp_energy_t *e);
static inline void rbamp_energy_set_enabled(rbamp_energy_t *e, bool en);
| Fonction | Description |
|---|---|
rbamp_energy_init |
Remet les compteurs à zéro ; l'accumulateur démarre activé. |
rbamp_energy_tick |
Intégrez une période : wh[ch] += avg_p[ch] × period_ms / 1000 / 3600 pour jusqu'à RBAMP_ENERGY_MAX_CH (7) canaux. Ignoré silencieusement si valid est faux, si period_ms vaut 0 ou si l'accumulateur est désactivé. period_ms doit être la fenêtre d'horloge murale du maître (master_dt_ms), non le latch_ms du module. |
rbamp_energy_wh_get |
Total cumulé d'un canal ; 0 si hors plage. |
rbamp_energy_add_wh |
Ajoute un montant déjà mesuré (Wh, signé) à un canal ou, avec RBAMP_ENERGY_CH_TOTAL, au total de tous les canaux. Utilisé lorsque le module publie lui-même ses compteurs d'énergie. Sans effet pendant que la fonction est désactivée. |
rbamp_energy_reset_ch / rbamp_energy_reset_all_ch |
Remet à zéro un canal / tous les canaux. |
rbamp_energy_set_enabled |
Active ou désactive l'intégration. Pendant la désactivation, tick() et add_wh() ne font rien et les lectures continuent de renvoyer la valeur figée. |
Identification et provisionnement
Ces fonctions permettent au maître de savoir exactement ce qui est connecté au bus (variante, carte de bits de capacité, UID) et de préparer un module neuf ou fraîchement flashé à l'exploitation (provisionnement + sauvegarde de la configuration en flash).
rbamp_read_variant
Détection automatique de la variante du module (initialization) · Référence du protocole filaire rbAmp (v1.3) (api-reference) · 3.6 Algorithme canonique de détection (api-reference)
esp_err_t rbamp_read_variant(rbamp_handle_t dev, rbamp_variant_t *out);
Lit le registre de variante et le fait correspondre à l'énumération rbamp_variant_t (RBAMP_VARIANT_UI1 / _I1 / _I2 / _I3, _UI5, _UI7, ... ; chaque code connu est mappé). Pour la compatibilité avec le code plus ancien qui lit l'octet « brut », vous pouvez le reconvertir en uint8_t. La valeur mise en cache par rbamp_begin() est disponible sans trafic sur le bus via rbamp_variant(). Valeurs :
| Code | SKU | Canaux I | Canal U |
|---|---|---|---|
1 |
UI1 | 1 | oui |
2 |
UI2 | 2 | oui |
3 |
UI3 | 3 | oui |
4 |
I1 | 1 | non |
5 |
I2 | 2 | non |
6 |
I3 | 3 | non |
7 |
UI5 | 5 | oui |
8 |
UI7 | 7 | oui |
La valeur est en lecture seule, stockée en ROM, et modifiée uniquement par un reflashage en usine.
rbamp_read_capability
Détection automatique de la variante du module (initialization) · 3.2 CAPABILITY (registres 0x57/0x58, u16 LE, lecture seule) (api-reference) · 8 · Exemples de traces filaires (api-reference)
esp_err_t rbamp_read_capability(rbamp_handle_t dev, uint16_t *out);
Lit la carte des fonctions à partir des registres CAPABILITY (0x57/0x58), en u16 little-endian. Un drapeau indique la présence d'un étage d'entrée en tension : s'il est à zéro, le module ne calcule pas P / PF / Q et les valeurs de ces registres valent 0.0f. Voir la section « CAPABILITY (0x57/0x58, u16 LE) — feature-detect map » ci-dessous.
rbamp_has_voltage
bool rbamp_has_voltage(rbamp_handle_t dev);
Une aide pratique au-dessus de rbamp_read_capability — renvoie true si le module possède un canal U (c'est-à-dire (cap >> 8) & 1). Elle est mise en cache dans le handle au premier appel ; les appels suivants n'effectuent aucune opération I²C.
rbamp_read_product_id
3.5 PRODUCT_ID (0x54, u8, lecture seule) (api-reference) · 4.8 Identité (0x54..0x6F) (api-reference)
esp_err_t rbamp_read_product_id(rbamp_handle_t dev, uint8_t *out);
Lit PRODUCT_ID (0x54) — un identifiant d'un octet de la famille (rbAmp = 0x01). Utilisé par le scanner de flotte pour confirmer que l'appareil à une adresse est bien un rbAmp, et non un autre esclave I²C qui aurait répondu à la même adresse.
rbamp_read_uid
esp_err_t rbamp_read_uid(rbamp_handle_t dev, uint8_t uid[12]);
Lit l'identifiant unique de 96 bits du microcontrôleur depuis UID (0x5C..0x67) en une seule opération en rafale. L'UID est garanti unique par module et ne change pas lors d'un reflashage — pratique pour les journaux série, les vérifications anti-clonage côté maître et l'identification lors du remplacement d'un module dans une flotte déployée.
rbamp_is_provisioned
esp_err_t rbamp_is_provisioned(rbamp_handle_t dev, bool *out);
Vérifie si le module a suivi le provisionnement initial. Techniquement, il contrôle REG_ERROR != 0xFB (ERR_FLASH_PARAMS_BAD) sur un module fraîchement démarré — 0xFB est positionné par le firmware lorsque le bloc de configuration utilisateur est vide ou corrompu. Un module sorti d'usine renvoie false — il faut rbamp_save_user_config (ou un provisionnement via la flotte) après le premier réglage du modèle de CT et de l'adresse.
En v1.3, ce code est normal pour un module vierge (non fatal). Ne pas interrompre le provisionnement à la première occurrence de 0xFB.
Gamme STD. Renvoie true lorsque le module signale que sa page d'étalonnage est valide. Fiable à partir de la version d'image de module 0x00010079 ; les images plus anciennes positionnent aussi le bit sur les gains d'usine par défaut, si bien que « provisionné » ne peut pas être distingué de « non étalonné » par cet appel (utilisez plutôt la source d'étalonnage dans rbamp_std_read_health()). À partir de la version d'image de module 0x0001007A, le bit provient d'un marqueur que le module écrit lors de la sauvegarde de l'étalonnage : un appareil étalonné avec un firmware plus ancien renvoie false après la mise à jour, jusqu'à un rbamp_save_gains() sur lui (son étalonnage lui-même est intact).
rbamp_save_user_config
6.5 Provisionnement — flashage neuf + SAVE (api-reference) · 8.6 Provisionnement après flashage neuf (api-reference)
esp_err_t rbamp_save_user_config(rbamp_handle_t dev);
Émet CMD_SAVE_USER_CONFIG (opcode 0x32) — sauvegarde le bloc de configuration utilisateur en flash : SENSOR_CLASS, CT_MODEL par canal, I2C_ADDRESS, FLEET_CONFIG, GROUP_ID, LABEL. Il ne sauvegarde pas les paramètres d'étalonnage d'usine (gain, NF, phase) — ceux-ci relèvent d'un CMD_SAVE_GAINS séparé, verrouillé en mode production.
Il bloque le thread pendant ~700 ms (cycle d'effacement et d'écriture de la flash). Pendant l'appel, n'essayez pas d'accéder au module depuis d'autres tâches.
Returns:
ESP_OK— configuration enregistrée, survit à une coupure d'alimentation.-
ESP_ERR_TIMEOUT— le module n'a pas répondu à temps ; l'alimentation a pu chuter pendant le cycle de flash. Revérifiez par réinitialisation + relecture. -
ESP_FAIL— le module a renvoyéREG_ERROR != OKaprès la commande. Consultezrbamp_read_last_errorpour le détail.
: la confirmation qu'une valeur a été écrite en flash exige un redémarrage + relecture. Voir la section Modèle d'erreurs v1.3 ci-dessous et 03 · Choix du capteur de courant.
rbamp_read_active_address
esp_err_t rbamp_read_active_address(rbamp_handle_t dev, uint8_t *out);
Lit l'adresse I²C active du module. Au démarrage, ce registre est fiable — il lit l'adresse active en flash (un module réadressé lit sa nouvelle adresse). Après avoir préparé un candidat avec rbamp_prepare_address_change(), il renvoie le candidat jusqu'au commit + réinitialisation. Utile pour vérifier un changement d'adresse en deux phases après le redémarrage consécutif au commit. Sur la gamme STD, il lit l'adresse persistée (appliquée à la prochaine réinitialisation).
Modèle d'erreurs v1.3
Les erreurs ont deux canaux indépendants qui fonctionnent différemment. Comprendre la différence est indispensable pour interpréter correctement l'état du module.
| Canal A — côté client, synchrone | Canal B — côté DUT, asynchrone durable | |
|---|---|---|
| Où il réside | Validation à l'intérieur du composant (bibliothèque) | REG_ERROR (0x02) + EVENT_FLAGS.bit3 (0x2A) |
| Quand elle se déclenche | Avant la transaction I²C (la bibliothèque intercepte) | Après que le firmware accepte une écriture et la rejette |
| Ce que voit le maître | ESP_ERR_INVALID_ARG depuis le setter ; REG_ERROR reste à 0x00 |
REG_ERROR = le code de rejet immédiat ; bit3 se verrouille quelques centaines de millisecondes après la transaction |
| Collant | non (seulement un code de retour) | dernière écriture de REG_ERROR ; bit3 collant W1C |
| Chemin typique | Argument hors des bornes autorisées (canal ≥ rbamp_channels(dev), classe inconnue, ...) |
Écriture de registre brute que le composant ne pré-valide pas (écriture bas niveau personnalisée) ; un modèle de CT inconnu, que le module lui-même rejette |
Canal A — validation côté client (setters du composant)
Tous les setters du composant (rbamp_set_sensor_class, rbamp_set_ct_model_ch, rbamp_configure_channels, etc.) vérifient d'abord les arguments par rapport aux valeurs autorisées. Si un argument est hors plage, le setter renvoie ESP_ERR_INVALID_ARG sans effectuer aucune transaction I²C. En conséquence, REG_ERROR sur l'appareil n'est pas touché :
esp_err_t err = rbamp_set_ct_model_ch(dev, /*channel=*/99, /*code=*/3);
/* err == ESP_ERR_INVALID_ARG (lib client-side validation) */
uint8_t reg_err;
rbamp_read_last_error(dev, ®_err);
/* reg_err == 0x00 — REG_ERROR untouched, lib intercepted before I²C */
Cela signifie que si vous voulez savoir exactement pourquoi un setter a refusé, la source fiable est le code de retour de la fonction + la vérification de votre propre argument. REG_ERROR ne vous dira rien dans ce scénario (la transaction réussie suivante le remet à jour).
Canal B — rejet côté DUT (asynchrone durable)
Si une écriture a bien transité par I²C (la bibliothèque ne l'a pas interceptée parce que l'argument semblait valide), mais que le firmware l'a rejetée, le second canal entre en jeu :
-
REG_ERROR (0x02)contient immédiatement le code de motif (par exemple0xFE = ERR_PARAM). C'est le résultat de la dernière écriture : toute écriture réussie ultérieure l'écrase. Vous devez le lire juste après votre propre écriture, avant toute autre transaction. -
EVENT_FLAGS.bit3(rbamp_has_error) — persistant W1C. Il ne se verrouille pas instantanément : sur le banc, un délai de quelques centaines de millisecondes a été mesuré entre la transaction rejetée et le positionnement de bit3. Juste après l'écriture, bit3 vaut encore0; après 300 ms, il vaut1. Ensuite,bit3reste en place quel que soit le nombre de lectures.
Sortie de banc (écriture brute DIGEST_CONFIG = 0xFF) :
raw write 0x29=0xFF → read_last_error → REG_ERROR=0xFE (immediate)
has_error(bit3): immediate=0, +300 ms poll#1=1, poll#2=1
⚠ N'utilisez pas has_error pour valider une écriture que vous venez de faire. Pour le résultat de cette écriture précise, seule la lecture de rbamp_read_last_error immédiatement après l'écriture, avant toute autre transaction, est fiable (ainsi que le code de retour du setter, s'il en a un). has_error est un canal asynchrone pour une surveillance par interrogation, « une panne est-elle survenue entre deux contrôles ? », et non une validation synchrone.
Effacer une erreur durable — effacer les deux (REG_ERROR et bit3)
bit3 est repris par le firmware toutes les quelques centaines de millisecondes à partir de l'état actuel de REG_ERROR. Donc un simple clear_event_flags(1<<3) ne fonctionnera pas — bit3 est immédiatement repositionné depuis REG_ERROR, encore non effacé :
state: REG_ERROR=0xFE, bit3=1
clear_event_flags(1<<3) → bit3=1 still (re-latched from REG_ERROR=0xFE)
clear_error + clear_event_flags(1<<3)
→ bit3=0 (cleared cleanly)
L'ordre correct : d'abord rbamp_clear_error() (efface REG_ERROR), puis rbamp_clear_event_flags(1<<3) (efface le verrou persistant). Si vous voulez l'atomicité, il ne doit pas y avoir d'écriture rejetée entre les deux.
rbamp_read_last_error
3. DATA_VALID (0xCE) ne passe jamais à 1 (troubleshooting) · Codes d'erreur (REG_ERROR = 0x02) (troubleshooting) · 4 · Carte des registres (production v1.3) (api-reference)
esp_err_t rbamp_read_last_error(rbamp_handle_t dev, uint8_t *out);
Lit REG_ERROR (0x02) directement — l'issue de la dernière transaction acceptée par le bus (une écriture ou une commande). Non persistant : toute écriture réussie suivante l'écrase par sa propre issue.
Utilisé sur le canal B (rejet côté DUT) pour le code de motif étendu.
rbamp_has_error
esp_err_t rbamp_has_error(rbamp_handle_t dev, bool *out);
Une aide pratique au-dessus de EVENT_FLAGS.bit3 (ERROR_OCCURRED, registre 0x2A). Renvoie true si bit3 est positionné. Drapeau W1C persistant ; il n'est pas effacé avant un effacement explicite (avec une réserve — voir la section « Clearing a durable error » ci-dessus).
Utilisé pour la surveillance par interrogation « une panne est-elle survenue ? » — par exemple dans des boucles longue durée où des écritures intermédiaires peuvent avoir écrasé REG_ERROR, mais où bit3 conserve le fait qu'au moins l'une d'elles a été rejetée.
rbamp_read_event_flags / rbamp_clear_event_flags
8.8 Flux d'événements de seuil — écriture du seuil → déclenchement → effacement W1C (api-reference)
esp_err_t rbamp_read_event_flags(rbamp_handle_t dev, uint8_t *out);
esp_err_t rbamp_clear_event_flags(rbamp_handle_t dev, uint8_t mask);
EVENT_FLAGS (0x2A) — un octet de drapeaux persistants (RBAMP_EVENT_*, voir Bits d'événements, dont RBAMP_EVENT_ERROR = bit3). L'effacement se fait en écrivant 1 pour effacer : écrivez un masque dont les bits à remettre à zéro sont positionnés. Les drapeaux fonctionnent sur les deux gammes ; sur la gamme STD, ils exigent la version de carte de registres 0x36 ou plus récente (ESP_ERR_NOT_SUPPORTED en deçà).
Cela aide à séparer les causes : vous pouvez d'abord lire tous les drapeaux, puis ne remettre à zéro que ceux qui ont été traités, en laissant les autres pour le cycle de scrutation suivant.
rbamp_clear_error
Codes d'erreur (REG_ERROR = 0x02) (troubleshooting) · 6.7 Rétablissement après erreur — arbre de décision (api-reference)
esp_err_t rbamp_clear_error(rbamp_handle_t dev);
Émet CMD_CLEAR_ERROR (opcode 0x31) — remet REG_ERROR à zéro. Nécessaire pour effacer une erreur durable, en tandem avec clear_event_flags(1<<3) (voir ci-dessus). Sans clear_error, un simple clear_event_flags(1<<3) laissera bit3 à 1 après quelques centaines de millisecondes à cause du re-verrouillage.
Événements et ligne d'alarme
4.4 Configuration de la flotte (0x27..0x2F) (api-reference) · 8.8 Flux d'événements de seuil — écriture du seuil → déclenchement → effacement W1C (api-reference)
Les événements constituent un seul modèle sur les deux lignes : drapeaux persistants (RBAMP_EVENT_*), écriture-1-pour-effacer. Les drapeaux également positionnés dans le masque d'événements maintiennent la ligne DRDY à BAS (une alarme) jusqu'à leur effacement ou démasquage. Le masque et les seuils résident en RAM du module — réarmez-les après chaque réinitialisation du module (RBAMP_EVENT_RESET_OCCURRED vous l'indique ; voir aussi rbamp_begin_event_flags()).
esp_err_t rbamp_read_event_mask (rbamp_handle_t dev, uint8_t *out);
esp_err_t rbamp_set_event_mask (rbamp_handle_t dev, uint8_t mask);
esp_err_t rbamp_set_event_thresholds(rbamp_handle_t dev, float i_amps, float p_watts);
| Fonction | Description |
|---|---|
rbamp_read_event_mask |
Quels drapeaux maintiennent la ligne DRDY au niveau BAS (la classe d'alarme). |
rbamp_set_event_mask |
Réglez le masque (en RAM du module ; 0 = la ligne n'est jamais maintenue). L'écriture est relue et vérifiée. |
rbamp_set_event_thresholds |
Réglez les seuils (en RAM sur le module) : le canal de courant le plus élevé au-dessus de i_amps règle RBAMP_EVENT_THRESH_I, la puissance active totale au-dessus de p_watts règle RBAMP_EVENT_THRESH_P. Une valeur <= 0 ou NaN désactive ce seuil. Renvoie ESP_ERR_NOT_SUPPORTED sur un module STD de version de carte de registres inférieure à 0x36. |
La comparaison diffère selon la gamme. La gamme STD compare la puissance totale absolue (le sens n'importe pas). La gamme BASIC compare la somme signée des puissances des canaux, si bien que l'export ne déclenche jamais le seuil de puissance ; les valeurs au-delà de ce que l'encodage BASIC peut contenir sont traitées comme « désactivées ». Sur STD, rbamp_read_event_flags() exige la version de table de registres 0x36 ou ultérieure (sinon ESP_ERR_NOT_SUPPORTED).
Configuration multi-canaux
Sur les modules multi-canaux (I2, I3, UI2, UI3, et les plus grands UI5 / UI7), chaque canal de courant a son propre modèle de capteur CT. L'utilitaire atomique pour la configuration en bloc est rbamp_configure_channels.
rbamp_configure_channels
esp_err_t rbamp_configure_channels(rbamp_handle_t dev,
rbamp_sensor_class_t cls,
const uint8_t *models,
uint8_t n);
Parameters:
cls— la classe de capteur, appliquée en premier viarbamp_set_sensor_class().models— un tableau dencodes de modèle de CT, un par canal.n— la longueur du tableau. Bornée à la variante : sinest supérieur au nombre de canaux de cette variante (par exemplen=3surI2), la fonction le ramène au nombre réel de canaux ; les éléments en trop du tableau sont ignorés. Sinest inférieur au nombre de canaux, les canaux manquants restent intacts (ils gardent leur modèle précédent). Une entrée0dansmodelssaute ce canal. L'appel couvre tous les canaux du module, y compris les canaux 3 et plus sur un UI5 / UI7.
En interne, la fonction effectue :
set_sensor_class(cls)une fois.-
Pour chaque canal
k < min(n, n_channels): liezmodels[k]; chaque liaison est vérifiée de façon synchrone et confirmée par relecture. -
Une sauvegarde terminale de la configuration utilisateur à la fin (plus celle incluse dans
set_sensor_class) — soit deux cycles d'effacement + écriture de la flash pour toute la configuration, au lieu de1 + n. C'est la propriété « ménagée pour la flash ».
Lire avant d'écrire. Toute la requête est décidée avant la première écriture. Une classe ou un modèle que le module détient déjà n'est pas réécrit : réappliquer la même configuration ne coûte donc que des lectures et aucun cycle de flash. Sur un module de classe 2 ou 3, une requête qui changerait la classe ou un modèle demandé est refusée d'emblée avec ESP_ERR_INVALID_STATE et rien n'est écrit. Sur un module de classe 1 avec un firmware plus ancien (jusqu'à 1.4.19), une configuration qui change un modèle se termine par un redémarrage du module (voir rbamp_set_ct_model_ch).
Returns:
ESP_OK— configuration appliquée et enregistrée.-
ESP_ERR_INVALID_ARG—clsoumodels[k]invalide (validation à l'étape de liaison, voir la section « Modèle d'erreur » ci-dessus). -
ESP_ERR_INVALID_STATE— un canal n'a pas pu être lié, ou le module est calibré avec son capteur monté (classe 2 / 3). -
Autres codes ESP-IDF — erreur de bus, délai dépassé, etc.
rbamp_read_ct_model_ch
4.7 Miroirs de vérification du modèle de TC (0x51..0x53) (api-reference) · 8.10 Relecture du miroir de vérification du modèle de TC (contrôle après liaison) (api-reference)
esp_err_t rbamp_read_ct_model_ch(rbamp_handle_t dev,
uint8_t channel,
uint8_t *out);
Lit le modèle de capteur CT effectivement appliqué à un canal donné (0 = non défini). Utilisez-le pour vérifier la liaison après rbamp_set_ct_model_ch(). Les canaux 0–2 lisent les miroirs plats (0x51 / 0x52 / 0x53) ; les canaux 3+ (UI5 / UI7) se relisent via la fenêtre de canal. C'est une relecture depuis la RAM, et non une confirmation de persistance — pour confirmer une sauvegarde en flash, faites une réinitialisation puis relisez. Sur la gamme STD, il lit l'entrée de table du canal.
Gestionnaire de flotte — gestion de plusieurs modules
L'API de flotte est la surface de haut niveau principale de la bibliothèque. Elle gère un ensemble de modules sur un bus I²C partagé : découverte, provisionnement, agrégation des scrutations, agrégation des erreurs, instantanés synchrones.
Toutes les fonctions de flotte sont thread-safe via un mutex interne ; les appels concurrents depuis des tâches différentes sont sérialisés. Un seul propriétaire de fleet depuis une tâche, plus un accès en lecture seule (par ex. _count, _get) depuis les autres, est acceptable, mais coordonnez explicitement les opérations complexes en plusieurs étapes.
Cycle de vie
esp_err_t rbamp_fleet_create(i2c_master_bus_handle_t bus,
rbamp_fleet_t *out);
void rbamp_fleet_destroy(rbamp_fleet_t fleet);
create prend un bus et renvoie une flotte vide. destroy libère tous les handles gérés et la flotte elle-même — après l'appel, tout pointeur de handle obtenu via rbamp_fleet_get est invalide.
Découverte — rbamp_fleet_scan
Configuration multi-modules (initialization) · Interrogation multi-modules — trois stratégies (realtime-polling) · Problèmes multi-modules (troubleshooting)
esp_err_t rbamp_fleet_scan(rbamp_fleet_t fleet,
bool match_product,
size_t *added);
Sonde le bus sur la plage 0x08..0x77 ; pour chaque adresse qui accuse réception :
-
Vérifie l'identité (
PRODUCT_ID,HW_VARIANT,CAPABILITY). Simatch_product = true, il exige une correspondance avec le PRODUCT_ID rbAmp. -
Lance le détecteur de conflit (deux signaux indépendants ; voir 10 · Dépannage, section « Fleet: a module ended up in excluded »). Les adresses suspectes vont dans la liste
excluded, non dans la flotte. -
Effectue un canari de niveau 2 (wedge-canary) : il sonde une adresse où il doit être garanti que personne ne répond. Si le canari reçoit un ACK, il renvoie
ESP_ERR_INVALID_STATE— le bus est bloqué, la flotte reste vide (voir les diagnostics au ch. 10).
Après succès, *added contient le nombre de modules ajoutés à la flotte. excluded_count (voir ci-dessous) est disponible via un accesseur séparé.
Sortie de banc (validée sur matériel sur une flotte hétérogène UI1+I2+I3 avec résistances de rappel externes de 4.7 kΩ) :
rbamp_fleet_scan() → 3 module(s), 0 excluded
module[0] @0x50 channels=1 voltage=yes (UI1 — mains)
module[1] @0x51 channels=2 voltage=no (I2 — sub-meter)
module[2] @0x52 channels=3 voltage=no (I3 — sub-meter)
rbamp_fleet_count() = 3
rbamp_fleet_excluded_count() = 0
Dans ce scénario, un conflit d'adresse finirait dans la liste des exclus (excluded_count > 0), et un bus bloqué aboutirait à ESP_ERR_INVALID_STATE avec une flotte vide (voir 10 · Dépannage).
Accès au module
size_t rbamp_fleet_count(rbamp_fleet_t fleet);
rbamp_handle_t rbamp_fleet_get(rbamp_fleet_t fleet, size_t index);
rbamp_handle_t rbamp_fleet_find(rbamp_fleet_t fleet, uint8_t address);
esp_err_t rbamp_fleet_add(rbamp_fleet_t fleet, rbamp_handle_t dev);
size_t rbamp_fleet_excluded_count(rbamp_fleet_t fleet);
esp_err_t rbamp_fleet_excluded_addr(rbamp_fleet_t fleet,
size_t index,
uint8_t *out);
_get renvoie NULL hors plage ; _find renvoie NULL si l'adresse ne figure pas dans la flotte (par exemple parce qu'elle a fini dans les exclus). _add permet d'ajouter manuellement un handle créé séparément (par exemple après un provisionnement manuel).
Interrogation — rbamp_fleet_poll_all
Configuration multi-modules (initialization) · Interrogation multi-modules — trois stratégies (realtime-polling)
esp_err_t rbamp_fleet_poll_all(rbamp_fleet_t fleet,
rbamp_snapshot_t *snaps,
rbamp_fleet_poll_t *status,
size_t capacity,
size_t *n_ok);
Interroge tous les modules de la flotte en un seul appel. Pour chaque module, une lecture RT complète (rbamp_read_all) est effectuée, le résultat étant rattaché à l'élément snaps[i] correspondant. En parallèle, status[i] reçoit le résultat par module : ESP_OK, ESP_ERR_TIMEOUT (module muet), ESP_FAIL (rejet de cohérence), etc.
Après le retour, *n_ok est le nombre de modules pour lesquels un instantané valide a été obtenu (status[i] == ESP_OK).
Résistant aux manques : un module muet n'annule pas la scrutation des autres. C'est essentiel pour une flotte en production — perdre un seul module (défaut de câblage, panne) ne doit pas faire tomber toute la surveillance.
Agrégation
esp_err_t rbamp_fleet_total_power(rbamp_fleet_t fleet, float *out_w);
esp_err_t rbamp_fleet_total_energy_wh(rbamp_fleet_t fleet, double *out_wh);
esp_err_t rbamp_fleet_poll_errors(rbamp_fleet_t fleet,
uint32_t *error_mask,
size_t *n_errors);
_total_power additionne la puissance active sur tous les canaux de tous les modules. Sur les variantes I, il n'y a pas de puissance active → elles contribuent 0. Dans le déploiement canonique (UI1 secteur + sous-compteurs I2/I3), le résultat est la puissance active du module secteur.
_total_energy_wh additionne de même les accumulateurs Wh des handles. Il fonctionne aussi correctement : les variantes I contribuent 0, UI1 contribue l'énergie du secteur.
_poll_errors parcourt la flotte en appelant rbamp_has_error sur chaque module. *error_mask est un masque de bits des modules signalés par EVENT bit3, repérés par leur position dans la flotte (significatif pour les 32 premiers modules) ; *n_errors est le nombre total de modules portant un drapeau d'erreur au moment de la scrutation. L'un ou l'autre pointeur peut être passé à NULL s'il n'est pas nécessaire.
Adressage et contrôle des conflits
esp_err_t rbamp_fleet_assign_address(rbamp_fleet_t fleet,
rbamp_handle_t dev,
uint8_t new_addr);
esp_err_t rbamp_fleet_check_conflict(rbamp_fleet_t fleet,
uint8_t addr,
bool *collision);
_assign_address réadresse un module existant de la flotte à une nouvelle adresse : en interne — validation en deux phases + réinitialisation ; le handle dans la flotte est mis à jour automatiquement (les appels suivants continuent de fonctionner).
_check_conflict — une vérification en lecture seule, au mieux, pour une adresse précise : appelez-la une fois par adresse concernée. Elle lit l'identité (PRODUCT_ID / HW_VARIANT / CAPABILITY) et la compare à l'état mis en cache de la flotte. Si une incohérence est détectée (deux appareils répondant à la même adresse avec des octets « fusionnés » ; identité différente de l'état mis en cache) — *collision = true. Pour balayer toutes les adresses connues, parcourez la flotte vous-même : for i in 0..count, check_conflict(fleet, addr, &col). Elle ne garantit pas de détecter des modules identiques — voir la discipline de provisionnement.
Provisionnement — rbamp_provision
esp_err_t rbamp_provision(i2c_master_bus_handle_t bus,
uint8_t desired_addr,
bool save_config,
rbamp_handle_t *out);
Provisionne exactement un module vierge (à l'adresse d'usine 0x50) à l'adresse indiquée. En interne :
-
Vérifie qu'il y a une réponse à
0x50(ESP_ERR_NOT_FOUNDsinon). -
Vérifie qu'il n'y a personne encore à
desired_addr(ESP_ERR_INVALID_STATEsi occupée). -
Effectue une validation d'adresse en deux phases.
-
Réinitialise le module et attend qu'il apparaisse à
desired_addrdans la fenêtre de démarrage (ESP_ERR_TIMEOUTs'il n'apparaît pas). -
Crée un handle ; si
save_config = true, appellerbamp_save_user_config(persistance en flash). -
Renvoie le handle prêt via
*out.
⚠ OBLIGATOIRE : exactement un module vierge sur le bus au moment de l'appel. Deux modules sur 0x50 en même temps sont physiquement indiscernables sur I²C — ils ne peuvent pas être distingués même avec un matériel spécial. La garantie repose sur l'opérateur, et non sur la bibliothèque. Pour la récupération, voir 10 · Dépannage, section « Flotte : rbamp_provision a renvoyé une erreur ».
Synchronisation GC de la flotte — instantanés synchrones sur toute la flotte
General Call (diffusion à l'adresse 0x00) (initialization) · Multi-modules — instantané simultané (period-metering) · 6.3 Instantané par diffusion GC — synchronisation de flotte sur option (api-reference)
esp_err_t rbamp_fleet_enable_gc_all(rbamp_fleet_t fleet,
uint8_t group,
size_t *ok_count);
esp_err_t rbamp_fleet_gclatch(rbamp_fleet_t fleet,
uint8_t group,
uint16_t tick,
uint32_t settle_ms);
esp_err_t rbamp_fleet_check_sync(rbamp_fleet_t fleet,
uint16_t expected_tick,
rbamp_fleet_sync_t *status,
size_t status_cap,
size_t *n_missed);
Pour une synchronisation serrée des instantanés (décalage < 1 ms sur toute la flotte), on utilise une diffusion d'instantané I²C General-Call.
-
_enable_gc_allpositionneFLEET_CONFIG.bit0+GROUP_IDsur tous les modules de la flotte et émetCMD_SAVE_USER_CONFIGsur chacun (persistant). Un redémarrage des modules est obligatoire après l'activation — il est effectué automatiquement. Il suffit de l'appeler une fois lors de la mise en place initiale de la flotte.*ok_count(facultatif) est le nombre de modules pour lesquels l'activation a réussi. -
_gclatchenvoie la trame GCA5 27 group tick_lo tick_hià l'adresse0x00— tous les modules avec GC activé et ungroupcorrespondant prennent instantanément l'instantané (LATCH_PERIOD).settle_msest la pause après la trame (typiquement 50 ms) avant la vérification. -
_check_synclitGC_TICK (0x59)sur chaque module dansrbamp_fleet_sync_t status[status_cap]. Le résultat par module :
typedef struct {
uint8_t addr; /* module I²C address */
uint16_t gc_tick; /* REG_GC_TICK; 0xFFFF = never received a GC */
bool in_sync; /* true if gc_tick == expected_tick */
bool reachable; /* false if the read NACKed / timed out */
} rbamp_fleet_sync_t;
*n_missed est le nombre de modules avec in_sync = false (ou qui ne répondent tout simplement pas). Si tous sont in_sync, n_missed == 0.
Ne les confondez pas : le rbamp_broadcast_latch par appareil (voir la section « Bus multi-modules » ci-dessous) est une trame sur tout le bus ; la synchronisation GC de flotte est la même trame, mais l'API de flotte fournit en plus une vérification témoin (qu'elle a bien atteint tous les modules attendus). Voir aussi 04 · Câblage pour les préconditions GC.
Configuration de flotte par appareil
Ces fonctions travaillent sur un seul module directement (sans flotte) — pour les cas où vous configurez un module individuel avant de l'ajouter à une flotte, ou souhaitez un contrôle fin.
rbamp_enable_gc / rbamp_read_fleet_config
Appel général (diffusion à l'adresse 0x00) (initialization) · 4.4 Configuration de parc (0x27..0x2F) (api-reference)
esp_err_t rbamp_enable_gc(rbamp_handle_t dev, bool enable);
esp_err_t rbamp_read_fleet_config(rbamp_handle_t dev, uint8_t *out);
enable_gc(dev, true) écrit 1 dans FLEET_CONFIG.bit0 (0x27) — le module commencera à accepter les instantanés GC après le prochain CMD_SAVE_USER_CONFIG + réinitialisation. enable_gc(dev, false) fait l'inverse en effaçant le bit (le module cesse d'accepter le GC après réinitialisation). read_fleet_config renvoie l'octet de configuration courant — utile pour une confirmation par relecture.
rbamp_set_group_id / rbamp_read_group_id
esp_err_t rbamp_set_group_id(rbamp_handle_t dev, uint8_t group_id);
esp_err_t rbamp_read_group_id(rbamp_handle_t dev, uint8_t *out);
GROUP_ID (0x28) — le filtre des trames GC : le module ne réagit qu'aux trames GC dont le group_id correspond. Par défaut = 0x00 (diffusion, réagit à toutes). Utile pour les bus multi-locataires — par exemple un groupe « phase A » et un groupe « phase B » sur un même bus partagé.
rbamp_read_gc_tick
esp_err_t rbamp_read_gc_tick(rbamp_handle_t dev, uint16_t *out);
Lit GC_TICK (0x59) — la dernière valeur de tick reçue d'une trame GC. Sert à détecter les trames manquées (si deux modules ont un tick différent, quelqu'un a manqué une trame).
rbamp_read_label / rbamp_write_label
esp_err_t rbamp_read_label(rbamp_handle_t dev, char out[9]);
esp_err_t rbamp_write_label(rbamp_handle_t dev, const char *label);
LABEL (0x68..0x6F) — une chaîne d'étiquette utilisateur de 8 octets (ASCII, complétée par des zéros). Elle aide à identifier les modules dans une flotte — par exemple « MAINS », « BOILER », « AC1 ». read_label renvoie toujours un tableau de 9 octets (8 octets de données + un \0 de fin). write_label prend une chaîne terminée par un zéro — les octets en trop sont tronqués.
L'écriture se fait octet par octet (pas d'incrémentation automatique à l'écriture — voir « Register writes » ci-dessous). Après écriture, il faut rbamp_save_user_config pour que l'étiquette survive à une réinitialisation.
rbamp_broadcast_latch_group
esp_err_t rbamp_broadcast_latch_group(i2c_master_bus_handle_t bus,
uint8_t group_id,
uint16_t tick);
Un envoi bas niveau de la trame GC A5 27 group tick_lo tick_hi directement via le handle bus (sans flotte). Utile si la flotte n'a pas encore été créée, ou si vous voulez un contrôle manuel du compteur de tick.
rbamp_reset_counters
esp_err_t rbamp_reset_counters(rbamp_handle_t dev);
Remet à zéro les compteurs de diagnostic du module (nombre d'erreurs i2c, nombre de réinitialisations de périphérique). Cela n'affecte ni la configuration utilisateur ni l'étalonnage. Utilisé pour les essais de banc et les remises à zéro périodiques lors de longues endurances en production.
Configuration du capteur
Une séquence en deux temps : d'abord la classe de capteur, puis le modèle. Les deux étapes sont obligatoires sur un module avec un capteur monté par l'utilisateur (classe 1). Les modules livrés avec leur capteur (classe 2 / 3) arrivent configurés et sont protégés contre une réécriture accidentelle — voir les notes de lecture avant écriture ci-dessous.
Pour un guide détaillé du choix de modèle, voir 03 · Choix du capteur de courant.
rbamp_set_sensor_class
Définir la classe de capteur et le modèle de TC (initialization) · 4.3 Système (0x20..0x25) (api-reference) · 6.2 Liaison du modèle de TC — simple préparation + CMD par canal (api-reference)
esp_err_t rbamp_set_sensor_class(rbamp_handle_t dev,
rbamp_sensor_class_t cls);
Règle la classe de capteur et la conserve.
Lire avant d'écrire. La fonction lit d'abord la classe détenue par le module. Écrire la valeur déjà détenue est une opération sans effet, sans écriture sur le bus (ESP_OK) — sur le module, toute écriture de classe, même inchangée, efface le modèle de CT et la forme d'étalonnage de chaque canal, si bien qu'une écriture inutile dégraderait les mesures. Un module dont la classe vaut 2 ou 3 (étalonné avec son capteur ajusté) n'est pas réécrit : ESP_ERR_INVALID_STATE.
Sinon, il écrit la classe, vérifie que le module l'a acceptée et la persiste avec la sauvegarde de configuration utilisateur (~700 ms, bloquant). Régler la classe efface aussi les modèles de CT sur le module : réglez donc les modèles ensuite.
Sur le firmware v1.2+, une classe réglée est une condition préalable à rbamp_set_ct_model() et rbamp_set_ct_model_ch() — appeler l'un ou l'autre alors que la classe est encore RBAMP_SENSOR_UNSET renvoie ESP_ERR_INVALID_STATE. Voir 10 · Dépannage, section « Le courant lu est nul », pour le symptôme « on a écrit UNSET par erreur ».
Retour : ESP_OK en cas de succès, ou lorsque le module détient déjà cette classe ; ESP_ERR_INVALID_ARG si dev == NULL, cls non reconnu, ou lorsque le module rejette l'écriture ; ESP_ERR_INVALID_STATE lorsque la classe actuelle du module est 2 ou 3 ; codes d'erreur I²C en cas de défaillance de la liaison.
Gamme STD. Écrit la classe comme métadonnée (la gamme STD n'a pas de table de préréglages) et la persiste ; le verdict de commande du module est vérifié.
rbamp_set_ct_model
esp_err_t rbamp_set_ct_model(rbamp_handle_t dev, uint8_t code);
La forme à paramètre unique — elle règle le modèle de pince sur le canal 0 uniquement (équivalent à rbamp_set_ct_model_ch(dev, 0, code) ; sur la ligne STD, c'est cet appel). Bloquant, ~700 ms lorsqu'il écrit.
L'ensemble de modèles accepté pour la classe active est la vérité d'exécution du firmware — la bibliothèque ne tient aucune liste de codes côté client. Une paire (classe, modèle) inconnue est rejetée par le module et remontée comme ESP_ERR_INVALID_STATE (ou ESP_ERR_INVALID_ARG issu de la vérification synchrone de l'écriture). Les codes et noms de modèles figurent dans le rbamp_sensor_models.h généré (rbamp_sensor_model_lookup()) ; pour la classe 1 :
code |
Modèle |
|---|---|
| 1 | SCT-013-005 |
| 2 | SCT-013-010 |
| 3 | SCT-013-030 |
| 4 | SCT-013-050 |
| 5 | SCT-013-100 |
| 6 | SCT-013-020 |
| 7 | SCT-013-060 |
(Les sept codes SCT-013 sont tous sélectionnables ; l'ensemble accepté est {1, 2, 3, 4, 5, 6, 7}.)
rbamp_set_sensor_class() doit avoir été appelée au préalable (sinon ESP_ERR_INVALID_STATE, sans écriture). La garde de lecture avant écriture de rbamp_set_ct_model_ch() s'applique également.
Pour les modules multi-canaux, utilisez la forme par canal ci-dessous.
rbamp_set_ct_model_ch
Réglage de la classe de capteur et du modèle de CT (initialization) · 6.2 Liaison du modèle de CT — préparation pure + CMD par canal (api-reference)
esp_err_t rbamp_set_ct_model_ch(rbamp_handle_t dev,
uint8_t channel, uint8_t code);
La forme par canal. Un seul appel public pour n'importe quel canal ; l'aiguillage est interne : les canaux 0 à 2 mettent le modèle en attente et l'appliquent avec la commande par canal, les canaux 3 et plus (UI5 / UI7, firmware v1.4.18+) l'appliquent par la fenêtre de canaux. Dans les deux cas, le modèle appliqué est confirmé par relecture puis persisté (~700 ms). channel est validé par rapport au nombre réel de canaux du module.
L'ordre de liaison est indifférent (canon v1.3). La liaison du CT est une préparation pure : chaque application par canal ne lie que son propre canal, si bien que les canaux peuvent être configurés dans n'importe quel ordre — croissant, décroissant ou entrelacé — sans s'écraser mutuellement :
rbamp_set_ct_model_ch(dev, 0, 1); /* channel 0 = SCT-013-005 */
rbamp_set_ct_model_ch(dev, 1, 3); /* channel 1 = SCT-013-030 */
rbamp_set_ct_model_ch(dev, 2, 6); /* channel 2 = SCT-013-020 */
rbamp_set_ct_model_ch(dev, 4, 3); /* channel 4 (UI5 / UI7) */
Garde de lecture avant écriture. Appliquer un modèle remplace toute calibration que l'appareil porte pour ce canal par le préréglage générique du modèle, et le module le fait même lorsque le modèle ne change pas. Donc :
-
le modèle que le canal détient déjà (voir
rbamp_read_ct_model_ch()) est une opération sans effet, sans écriture sur le bus — réappliquer une configuration mémorisée à chaque reconnexion est sûr et n'entraîne aucun redémarrage inutile du module ; -
un module de classe 2 ou 3 renvoie
ESP_ERR_INVALID_STATE;rbamp_set_ct_model_ch_force()est la voie de maintenance.
Redémarrage du module sur un firmware de classe 1 plus ancien. Sur un module BASIC de classe 1 sans la capacité d'auto-correction (firmware jusqu'à 1.4.19), un appel qui change le modèle se termine par un redémarrage du module (environ une seconde, même UID vérifié) : c'est le seul moyen pour le module de revenir à son gain étalonné après une écriture de modèle. La bibliothèque évalue alors la correction de puissance nominale (rbamp_sct_correction()) et met à l'échelle les lectures à partir du gain appliqué par le module. L'état en RAM du module (champs de condensé, masque d'événements, seuils) est réappliqué par la bibliothèque là où elle en a la charge ; les accumulateurs de période repartent de zéro, comme après toute réinitialisation du module.
Retours : ESP_OK ; ESP_ERR_INVALID_ARG si dev == NULL ou channel >= rbamp_channels(dev) ; ESP_ERR_NOT_SUPPORTED sur un firmware antérieur à la v1.2 (canaux 0 à 2), ou sur un module STD qui ne persiste pas un modèle de CT par canal ; ESP_ERR_INVALID_STATE si la classe est UNSET, si le module rejette la paire (class, model), si le modèle appliqué échoue à la relecture de confirmation, ou si le module est de classe 2 / 3 ; ESP_FAIL / ESP_ERR_TIMEOUT en cas d'échec de transport.
Gamme STD. Le modèle de CT n'est qu'une référence (métadonnée SKU) : il ne règle aucun gain — le module porte son propre étalonnage par canal. Sur le firmware actuel des modules à canal unique, seul le modèle du canal 0 survit à une réinitialisation.
rbamp_set_ct_model_ch_force
esp_err_t rbamp_set_ct_model_ch_force(rbamp_handle_t dev,
uint8_t channel, uint8_t code);
La voie de maintenance : comme rbamp_set_ct_model_ch(), mais elle écrit quelle que soit la classe du module et le modèle actuellement détenu. Elle remplace l'étalonnage apparié de ce canal par le préréglage générique du modèle — à n'utiliser que pour réapparier un module à un nouveau capteur en maintenance, et à faire suivre d'un étalonnage.
rbamp_read_sensor_class
esp_err_t rbamp_read_sensor_class(rbamp_handle_t dev, uint8_t *out);
La classe de capteur de courant du module sous forme de valeur rbamp_sensor_class_t (BASIC : le registre de classe ; STD : le champ de configuration de classe).
Limites des modèles de capteur
bool rbamp_sensor_model_limits (uint8_t sensor_class, uint8_t code,
float *nominal_a, float *fs_a, float *peak_a);
float rbamp_sensor_model_rated_a(uint8_t sensor_class, uint8_t code);
Simples recherches dans le registre de modèles généré (rbamp_sensor_models.h) — aucun trafic sur le bus.
-
rbamp_sensor_model_limitsremplit (toute sortie peut êtreNULL) :nominal_a— le courant efficace nominal, A ;fs_a— le courant efficace auquel une sinusoïde commence à écrêter, A ;peak_a— le plafond d'écrêtage instantané, A (une charge déformée écrête àpeak_adivisé par son facteur de crête).0signifie inconnu pour ce modèle (codes historiques de tore / de charge). Renvoietruesi la paire(classe, code)figure dans le registre,falsesinon (les sorties valent alors 0). -
rbamp_sensor_model_rated_aest le raccourci denominal_a. C'est le calibre du capteur, qui peut différer des ampères du nom du modèle (la pince « 5 A » a un calibre de 4.6 A). Utilisezrbamp_sensor_model_lookup()pour le nom du modèle.
Une correspondance dans le registre ne signifie pas que le module connecté accepte le code — c'est la vérité à l'exécution.
Correction de calibre SCT-013
Un module BASIC de classe de capteur 1 est calibré en usine avec le capteur 30 A (modèle 3). Sur un firmware allant jusqu'à 1.4.19, un passage à un autre modèle laisse le module appliquer la calibration 30 A après un redémarrage, de sorte qu'un capteur plus grand lit trop bas. Un module qui déclare la capacité d'autocorrection (firmware 1.4.20 et ultérieur) se corrige lui-même et n'a besoin d'aucune de ces étapes.
Pour les anciens firmwares, la bibliothèque lit le gain que le module applique réellement — à rbamp_begin(), après une écriture de modèle et après chaque redémarrage de module détecté — et met à l'échelle le courant, le courant de crête, la puissance active, la puissance moyenne de période, l'énergie intégrée, le digest et les seuils d'événements à partir de ce gain et du modèle choisi. La tension et le facteur de puissance ne sont pas mis à l'échelle. L'issue par canal est rbamp_sct_status_t (voir Types). Un gain encore égal au préréglage brut (le modèle a été changé dans ce démarrage sans redémarrage) déclenche un redémarrage du module ; un gain appliqué inattendu, un modèle inconnu, ou un préréglage brut qui survit au redémarrage laissent les lectures non mises à l'échelle avec un avertissement dans le journal. CONFIG_RBAMP_SCT_RATING_CORRECTION (activé par défaut) désactive le mécanisme, et les valeurs brutes du module sont alors renvoyées.
esp_err_t rbamp_sct_correction(rbamp_handle_t dev, uint8_t ch,
rbamp_sct_correction_t *out);
esp_err_t rbamp_sct_refresh (rbamp_handle_t dev);
| Fonction | Description |
|---|---|
rbamp_sct_correction(dev, ch, &c) |
La correction mise en cache du canal ch — sans trafic sur le bus. Évaluée par rbamp_begin(), par rbamp_set_ct_model*() et après un redémarrage de module détecté (un RESET_OCCURRED effacé, un RESET en attente dans le digest, une durée de fonctionnement décroissante). ESP_ERR_NOT_SUPPORTED sur la gamme STD. |
rbamp_sct_refresh(dev) |
Relit maintenant la classe, les modèles et les gains appliqués, puis recalcule les échelles. Déclenche un redémarrage du module (et réinterroge le module, avec vérification du même UID) lorsque le gain appliqué d'un canal est encore le préréglage brut d'un modèle autre que celui de 30 A. Appelé en interne si nécessaire ; exposé pour un hôte qui sait que le module a redémarré par d'autres moyens. Sans effet, renvoie ESP_OK sur la gamme STD et sur un module qui se corrige lui-même. |
rbamp_save_gains
esp_err_t rbamp_save_gains(rbamp_handle_t dev);
Une écriture CMD_SAVE_GAINS « nue », sans modification de registre associée.
⚠ Normalement appelé à l'intérieur du composant. Un rbamp_save_gains() nu ne convient QUE si l'appelant a écrit manuellement dans des registres d'étalonnage non publics via un accès bus brut — c'est une opération hors garantie, qui contourne la table de préréglages par SKU. Des valeurs incorrectes produiront des lectures de courant/puissance erronées sans avertissement explicite. Chaque appel effectue un cycle d'effacement et d'écriture en flash (~700 ms) ; l'endurance de la flash est limitée (~10000 cycles par page) — ne l'appelez pas en boucle.
Gamme STD. Émet la sauvegarde de calibration (enregistre le bloc de calibration : gains, planchers de bruit et de THD) et vérifie le verdict de la commande.
rbamp_prepare_address_change / rbamp_commit_address_change
Changement d'adresse (initialization) · 4.5 Adresse (0x30..0x31) (api-reference) · 6.1 Changement d'adresse — commit en deux phases (compatible production) (api-reference)
Le changement de l'adresse I²C du module se fait par un commit en deux phases en mode production. Le firmware exclut délibérément l'adresse du flux général CMD_SAVE_USER_CONFIG / CMD_SAVE_GAINS — un changement exige une séquence explicite armée par un code magique.
esp_err_t rbamp_prepare_address_change(rbamp_handle_t dev,
uint8_t new_addr);
esp_err_t rbamp_commit_address_change(rbamp_handle_t dev);
Protocole filaire sous le capot :
-
prepare: valide la plage denew_addr(0x08..0x77, ≠ actuelle) → écritnew_addrdansREG_I2C_ADDRESS(0x30) — la valeur atterrit en RAM. -
prepare: écrire0xA5dansREG_ADDR_COMMIT_MAGIC(0x31) — cela « arme » le commit. La fenêtre d'état armé dure 5 secondes. -
commit: vérifier la fraîcheur de l'armement → envoyerCMD_COMMIT_ADDR(opcode 0x30) → persister en flash →CMD_RESET -
~400 ms de démarrage → mise à jour du champ d'adresse interne du handle.
Après une commit réussie, tous les appels sur cette instance de handle sont adressés à la nouvelle adresse. L'opération fonctionne en mode production (non verrouillée), ce qui permet le remplacement sur site de modules de rechange de production.
⚠ Si la fenêtre armée (5 s) a expiré — commit renvoie ESP_ERR_TIMEOUT, le drapeau d'armement est effacé, et vous devez recommencer avec prepare.
Gamme STD. Le changement d'adresse est synchrone et le handle ne bascule qu'une fois qu'un module répond à la nouvelle adresse — voir rbamp_commit_address_change sur la gamme STD. En cas d'échec, le handle conserve l'ancienne adresse (ESP_ERR_NOT_FOUND).
⚠ La persistance n'est confirmée qu'après une réinitialisation. Avant la réinitialisation, rbamp_read_* peut renvoyer les nouvelles valeurs depuis la RAM, mais l'écriture en flash peut ne pas être terminée. Le composant effectue lui-même un CMD_RESET + attente de démarrage intégrés dans commit, donc après un retour réussi l'état est garanti persistant.
⚠ Redémarrage et réénumération après la validation. Après une validation réussie, l'appareil se réinitialise et se réénumère à la NOUVELLE adresse. Les appels suivants sur cette instance de handle sont adressés à la nouvelle adresse de façon transparente — mais tout AUTRE maître sur le bus (un script Python, un composant ESP-IDF sur un autre MCU, une sonde de débogage) continuera de croire que l'appareil est à l'ancienne adresse tant que son état interne n'aura pas été mis à jour manuellement.
rbamp_factory_reset
esp_err_t rbamp_factory_reset(rbamp_handle_t dev);
La commande CMD_FACTORY_RESET (0xAA) + une attente de 1500 ms.
⚠ Opération destructive. Elle efface TOUS les paramètres en flash (modèle de CT, classe de capteur, coefficients d'étalonnage, adresse I²C). Le module revient aux réglages d'usine — rbamp_sensor_class_t devient RBAMP_SENSOR_UNSET, REG_CT_MODEL devient 0. Tout réglage appliqué précédemment via rbamp_set_sensor_class() / rbamp_set_ct_model*() disparaît. Le prochain utilisateur DOIT réappliquer rbamp_set_sensor_class() et rbamp_set_ct_model*() avant que la comptabilisation redevienne opérationnelle. Ce n'est pas un « redémarrage à chaud » — pour un redémarrage à chaud, utilisez rbamp_reset(). rbamp_factory_reset() est réservé à la récupération depuis un état connu défaillant ou à la remise du module à un autre utilisateur / une autre installation.
Gamme STD. Il n'existe pas de commande de réinitialisation d'usine : rbamp_factory_reset() renvoie ESP_ERR_NOT_SUPPORTED.
rbamp_reset
esp_err_t rbamp_reset(rbamp_handle_t dev);
La commande CMD_RESET (0x01) + une attente de 100 ms. Un redémarrage à chaud de l'appareil sans perdre les paramètres en flash.
Bus multi-module
rbamp_broadcast_latch
esp_err_t rbamp_broadcast_latch(i2c_master_bus_handle_t bus,
uint32_t timeout_ms);
Sur le firmware v1.3 (REG_VERSION = 0x04), c'est le chemin canonique de synchronisation de flotte une fois General-Call activé à l'échelle de la flotte via rbamp_fleet_enable_gc_all(). La trame General-Call de 5 octets A5 27 fait prendre à chaque module son instantané dans le groupe correspondant au même instant sur le fil, donnant une synchronisation serrée entre les sous-compteurs. La fonction ne prend que le bus : elle émet la trame (ESP_OK signifie que le pilote hôte n'a pas signalé d'erreur ; General Call est en écriture seule, aucun module n'envoie d'ACK ; ESP_ERR_INVALID_ARG sur un bus NULL). Les modules sans prise en charge de General-Call, ou l'ayant laissé désactivé, ignorent simplement la trame — vérifiez avec le témoin par module (ci-dessous) et utilisez le repli séquentiel s'ils n'ont pas pris l'instantané. rbamp_broadcast_latch_group(bus, group, tick, timeout_ms) fait la même chose avec un filtre de groupe explicite et un tick de flotte.
Repli séquentiel (firmware ancien ou GC laissé désactivé) : une série de rbamp_latch_period() sur chaque appareil, une pause commune de 50 ms, et un rbamp_read_period_snapshot(skip_latch=true) par appareil — voir 06 · Exemples, scénario « Monitoring multiple modules ».
Gamme STD
La gamme de modules STD parle un modèle de registres différent derrière le même handle. rbamp_begin() le détecte ; l'API scalaire des chapitres précédents fonctionne sans modification sur les deux gammes (rbamp_read_current, _power, _voltage, rbamp_read_period_snapshot, rbamp_energy_wh, les appels de configuration, …). Les fonctions de ce chapitre sont les ajouts réservés au STD : canaux entiers en une seule rafale, grandeurs que seule cette gamme mesure (puissance réactive / apparente, THD, compteurs d'énergie signés), banques d'instantanés, horloge du module, historique, état de santé, mise à jour du firmware. Chaque fonction rbamp_std_* renvoie ESP_ERR_NOT_SUPPORTED sur un handle BASIC.
De nombreuses fonctions exigent une version minimale de la carte de registres du module (indiquée « map 0x35+ » et similaires ci-dessous). La conditionnalité des fonctionnalités suit les capacités et la version de carte que le module déclare (rbamp_std_info()), jamais une supposition ; lorsqu'un module est trop ancien, la fonction renvoie ESP_ERR_NOT_SUPPORTED — le plus souvent sans aucun trafic sur le bus. Un exemple fonctionnel est examples/std_meter/.
Identité et découverte
typedef struct {
uint8_t map_version;
uint16_t capabilities; /* RBAMP_STD_CAP_* bitmap */
uint8_t status; /* RBAMP_STD_ST_* bits at begin() time */
uint8_t n_voltage; /* populated voltage channels */
uint8_t n_current; /* populated current channels */
uint8_t variant; /* raw RBAMP_STD_VARIANT_* byte */
uint32_t active_bank; /* running firmware bank, 0 without OTA capability */
uint32_t ota_bank_size; /* flash bank size, 0 if none */
rbamp_std_period_source_t period_source;
} rbamp_std_info_t;
typedef struct {
uint8_t i2c_addr;
uint8_t map_version;
uint16_t capabilities;
uint8_t variant;
uint8_t n_voltage, n_current;
uint8_t uid[12]; /* chip UID — the identity; addresses can change */
uint32_t fw_version; /* running image version (map 0x35+; 0 if unknown) */
uint32_t board_id; /* map 0x36+; 0 below */
} rbamp_std_identity_t;
| Fonction | Description |
|---|---|
rbamp_std_info(dev, &info) |
L'identité mise en cache par rbamp_begin() — aucun trafic sur le bus. Renvoie ESP_ERR_NOT_SUPPORTED sur un handle BASIC ou avant rbamp_begin(). Le contrôle des canaux se fait selon n_voltage / n_current : les registres des canaux au-delà de ces nombres sont non spécifiés et la bibliothèque refuse de les lire. |
rbamp_std_identify(dev, &id) |
Tout ce dont un maître a besoin pour reconnaître le module derrière un handle (deux à quatre courtes lectures). |
rbamp_std_probe(bus, addr, &id) |
Sonde une adresse sur un bus sans handle — la brique de base d'un balayage. Rapide : sans nouvelles tentatives, un NACK est la réponse. ESP_OK avec id renseigné ; ESP_ERR_NOT_FOUND si rien n'envoie d'ACK ; ESP_ERR_INVALID_RESPONSE si quelque chose répond qui n'est pas un module STD (un module BASIC, une autre puce). |
rbamp_std_read_image_version(dev, &v) |
La version d'image du firmware en cours d'exécution (u32, par exemple 0x00010072). Distincte de rbamp_firmware_version(), qui est la version de la table de registres sur cette gamme. 0 si le module ne peut pas la déterminer. |
rbamp_std_read_board_id(dev, &id) |
Identifiant de carte de l'image en cours (carte 0x36+) : un mot qui code le matériel pour lequel l'image a été construite. Une image firmware n'est acceptée que si son mot de carte correspond (voir rbamp_std_ota_board_ok). |
rbamp_std_locate(dev) |
Faites clignoter les LED du module pendant environ 10 s pour qu'une personne puisse le repérer. |
rbamp_std_set_address_by_uid(bus, shared_addr, uid, new_addr, restart_ms) |
Donnez à un module à une adresse partagée sa propre adresse, sélectionné par UID (carte 0x36+). Plusieurs modules peuvent se trouver sur shared_addr (par exemple l'adresse par défaut d'usine) ; seul celui dont l'UID correspond prend new_addr, la persiste et redémarre ; les autres ignorent la commande. Ne nécessite pas de handle. Après le redémarrage, la bibliothèque sonde new_addr et vérifie l'UID à cet endroit. restart_ms 0 = 1500 ms. ESP_ERR_NOT_FOUND si rien ne répond à new_addr ; ESP_ERR_INVALID_RESPONSE si un module répond à cet endroit mais que son UID diffère. |
Comment un module STD fournit l'énergie de période
typedef enum {
RBAMP_STD_PERIOD_NONE = 0,
RBAMP_STD_PERIOD_LATCH = 1,
RBAMP_STD_PERIOD_COUNTERS = 2,
} rbamp_std_period_source_t;
Déterminé par rbamp_begin() à partir des capacités du module et exposé dans rbamp_std_info_t.period_source :
-
LATCH— le module dispose de banques d'instantanés. Une période va d'instantané à instantané sur la banque 0 ; les moyennes et l'énergie par canal proviennent de la banque. Voir Banques d'instantanés. -
COUNTERS— pas de banques d'instantanés, mais des compteurs de durée de vie persistants. Une période est la différence de deux lectures de compteur, prises selon le calendrier du maître ; il n'y a pas de commande d'instantané, rien à armer, et rien n'est perdu lors d'un redémarrage du module. Voir Compteurs d'énergie de durée de vie. -
NONE— ni l'un ni l'autre : les appels de période et d'énergie renvoientESP_ERR_NOT_SUPPORTED.
Blocs temps réel
typedef struct {
float i_rms; /* A */
float i_peak; /* A — reads 0 on module map 0x34 and earlier */
float p, q, s; /* W (signed), var (signed), VA */
float pf; /* −1..+1 */
float thd_i; /* % — 0 while harmonics are off */
float pf1; /* displacement power factor — 0 while harmonics are off */
float q1; /* fundamental reactive power, var — 0 while harmonics are off */
int64_t e_import_mws; /* raw signed import accumulator, mW·samples (>= 0) */
int64_t e_export_mws; /* raw signed export accumulator, mW·samples (<= 0) */
uint8_t implausible; /* RBAMP_FIELD_* bits set to NaN */
} rbamp_std_channel_t;
typedef struct {
float u_rms, u_peak, thd_u; /* V, V (0 on map 0x34 and earlier), % */
uint8_t implausible;
float angle_deg; /* phase angle against voltage input 0, (−180, 180]; input 0 reads 0 */
bool angle_valid; /* the module publishes the angle for this input */
} rbamp_std_voltage_t;
| Fonction | Description |
|---|---|
rbamp_std_read_channel(dev, ch, &c) |
Un bloc de canal de courant (I / P / Q / S / PF / crête / accumulateurs d'énergie / harmoniques) en une seule rafale ; ch vaut 0..rbamp_channels(dev)-1. Les champs sont aussi cohérents que le module les publie (par fenêtre de publication) ; pour un instantané multi-champs strictement atomique, utilisez l'instantané de période. Un champ qui dépasse une borne de cohérence vaut NaN avec son bit RBAMP_FIELD_* dans implausible. |
rbamp_std_read_totals(dev, k, &c) |
Un bloc agrégé : k = 0 le total général (somme de tous les canaux de courant), k = 1..3 les totaux par phase A/B/C (modules polyphasés uniquement). Les totaux par phase sont publiés depuis la carte 0x36 — sur un module monophasé, k = 1 égale le canal 0 et k = 2/3 lisent 0 ; en deçà de 0x36, ils renvoient ESP_ERR_NOT_SUPPORTED (k = 0 fonctionne toujours). Les champs d'énergie (e_import_mws / e_export_mws) ne sont pas renseignés pour les blocs agrégés et lisent 0 — l'énergie provient des compteurs persistants (rbamp_std_read_energy). |
rbamp_std_read_voltage(dev, v, &u) |
Un bloc de canal de tension (RMS / crête / THD / angle de phase) en une seule rafale ; v vaut 0..n_voltage-1. angle_deg / angle_valid sont publiés par les modules triphasés de version d'image 0x0001007A ou ultérieure ; sinon angle_valid vaut false et le reste du bloc n'est pas affecté. Sur un module triphasé à séquence directe, l'entrée 1 lit environ −120° et l'entrée 2 environ +120°. |
rbamp_std_read_phase_seq(dev, &seq) |
L'ordre des entrées de tension, déduit par le module à partir des angles : RBAMP_STD_PHASE_SEQ_NA (moins de trois entrées, ou une entrée trop faible), _FORWARD (L1-L2-L3), _REVERSE (L1-L3-L2), _ABNORMAL (pas de motif à 120°, par ex. deux entrées câblées sur la même phase). Renvoie ESP_ERR_NOT_SUPPORTED (et *seq = NA) sur une version d'image de module antérieure à 0x0001007A, sans trafic de bus. |
thd_i, pf1, q1 et thd_u valent 0 sauf si l'extraction des harmoniques est activée — voir Configuration. e_import_mws / e_export_mws sont les accumulateurs bruts du module en mW·échantillons ; le module n'ayant pas d'horloge, la conversion en Wh exige le nombre d'échantillons et votre propre chronométrage de période (utilisez le chemin des instantanés ou les compteurs de durée de vie). Pour la surveillance, intégrez p sur votre intervalle d'interrogation.
rbamp_read_all() sur un module STD lit le bloc de tension et chaque bloc de canal en entier (une transaction chacun) au lieu de champ par champ. rbamp_read_frequency() sur un module STD renvoie ESP_ERR_INVALID_RESPONSE avec *out = NaN lorsque le module publie 0 (pas de secteur) ; rbamp_read_all() lève alors RBAMP_FIELD_FREQUENCY. rbamp_read_voltage_peak() / rbamp_read_current_peak() lisent 0 sur la carte de mappage 0x34 et antérieures — utilisez le max_u / min_u / max_i d'une banque d'instantanés pour le pic sur une période.
Santé
typedef struct {
uint8_t status; /* RBAMP_STD_ST_* bits: cal_ok / sensor_ok / mains_ok / locked / time_valid */
uint32_t frame_count; /* sensor frame counter — must grow between polls */
uint32_t crc_errors; /* sensor frame CRC error counter */
bool time_valid; /* the module clock is set; false after every module reset */
bool nvm_fault; /* energy store fault or corrupt (details in lta_status) */
uint8_t lta_status; /* life-time energy store: 0 ok · 1 new · 2 fault · 3 corrupt (service) */
uint8_t lta_src; /* counters loaded from: 0 none · 1 NVM · 2 backup domain · 3 legacy · 4 rollback anchor */
uint8_t cal_src; /* calibration in use: 0 defaults · 1 flash · 2 EEPROM · 3 stored cal is for another range */
uint32_t lost_frames; /* sensor frames lost since boot — should stay flat */
uint16_t ring_drop; /* acquisition ring overruns since boot — should stay flat */
uint32_t uptime_s; /* seconds since the module booted */
bool maint; /* maintenance mode active */
uint8_t group_status; /* per-channel energy store: 0 ok · 1 new · 2 fault · 3 restarted at 0 */
uint16_t legal_noen; /* metering-relevant operations executed outside maintenance mode */
uint8_t reset_cause; /* image 0x76+: cause of THIS boot, RBAMP_STD_RST_* bits; 0 below */
uint16_t boot_count; /* image 0x76+: persisted boot counter (low 16 bits); 0 below */
} rbamp_std_health_t;
rbamp_std_read_health(dev, &h) lit l'état en direct. Considérez les lectures comme valides lorsque status contient RBAMP_STD_ST_SENSOR_OK et que frame_count augmente entre deux scrutations. Les champs après crc_errors existent sur les modules de carte 0x35+ et valent zéro / faux sur les plus anciens.
Alerte sur : nvm_fault ou lta_status >= 2 (stockage d'énergie) ; cal_src == 3 (la calibration mémorisée concerne une autre plage, les valeurs par défaut sont utilisées, cal_ok également à faux) ; lost_frames / ring_drop qui augmentent ; time_valid à faux (réglez l'horloge) ; uptime_s qui diminue (le module a redémarré). reset_cause porte des bits RBAMP_STD_RST_* (broche, alimentation, logiciel = réinitialisation / activation / changement d'adresse, chiens de garde, basse consommation, octet d'option) ; le bit de broche accompagne la plupart des réinitialisations internes, donc jugez d'après les autres bits.
Configuration
typedef struct {
uint8_t sensor_class; /* rbamp_sensor_class_t value; 0 = unset. Persisted. */
uint8_t ct_model; /* CT model reference for channel 0 (metadata, sets no gain). Persisted. */
uint8_t tier; /* 0 or 1. Persisted. */
uint8_t i2c_addr; /* persisted 7-bit address (applies on reset) */
uint16_t rate_ms; /* report-rate hint, ms (RAM only) */
bool harmonics; /* base-harmonics extraction enabled (RAM only) */
uint16_t start_ua; /* starting current for energy, µA (0 = off); 0 when start_ua_supported is false */
bool start_ua_supported; /* the module has the starting-current setting */
} rbamp_std_config_t;
| Fonction | Description |
|---|---|
rbamp_std_read_config(dev, &cfg) |
Le bloc de configuration (une rafale, plus le registre du courant de démarrage lorsque le module le possède). |
rbamp_std_set_harmonics(dev, enable) |
Active ou désactive l'extraction des harmoniques de base (THD, PF de déplacement, Q1). Désactivé par défaut sur le palier standard (économise le CPU du module) ; les champs d'harmoniques lisent 0 tant que c'est désactivé. RAM seulement : repasse à désactivé à la réinitialisation du module. Relu et confirmé. ESP_ERR_NOT_SUPPORTED sans la capacité THD. |
rbamp_std_cal_thd_floor(dev) |
Étalonne le plancher de THD de la chaîne de capteurs : capture le THD brut lissé actuel comme plancher, le persiste et l'applique immédiatement. Précondition : secteur propre et AUCUNE charge sur le CT — la valeur capturée est soustraite de toutes les lectures de THD ultérieures. Bloque le temps de stabilisation de la persistance ; le verdict vient du registre d'erreur du module (carte 0x34+). ESP_ERR_NOT_SUPPORTED sans la capacité THD. |
rbamp_std_get_start_current(dev, &ua) |
Le courant de démarrage pour l'énergie, en µA (0 = désactivé). En dessous de ce courant de canal, le module ne compte aucune énergie pour ce canal (import ou export, total général et par canal) ; les lectures elles-mêmes ne sont pas affectées. ESP_ERR_NOT_SUPPORTED sans trafic de bus sur un module ne disposant pas de ce réglage (version d'image de module antérieure à 0x0001007B). |
rbamp_std_set_start_current(dev, ua) |
Réglage : 0 = désactivé, sinon une valeur de l'ensemble des paliers acceptés par le module. S'applique immédiatement ; rbamp_save_user_config() le persiste. Relu et confirmé. ESP_ERR_INVALID_ARG pour une valeur hors de l'ensemble accepté — rien n'est écrit ; ESP_ERR_NOT_SUPPORTED comme ci-dessus ; ESP_ERR_INVALID_STATE si le module n'a pas retenu la valeur. |
Les appels de configuration scalaires (rbamp_set_sensor_class, rbamp_set_ct_model_ch, rbamp_configure_channels, rbamp_save_user_config, rbamp_save_gains, rbamp_prepare_address_change / rbamp_commit_address_change, rbamp_reset) fonctionnent sur les deux gammes ; chacun a une note « STD line » dans sa section. Deux différences à connaître : rbamp_factory_reset() renvoie ESP_ERR_NOT_SUPPORTED (il n'existe pas de telle commande sur cette gamme), et rbamp_save_gains() persiste le bloc de calibration.
rbamp_commit_address_change() sur la gamme STD est synchrone : la sauvegarde de la configuration attend le module et lit le verdict (une adresse hors plage → ESP_ERR_INVALID_ARG ; la limite de débit d'écriture flash du module → ESP_ERR_NOT_FINISHED — préparez à nouveau et réessayez après environ 5 s ; rien ne change dans les deux cas), puis redémarre le module et ne bascule le handle qu'une fois qu'un module répond à la nouvelle adresse (dans environ 3 s). Si rien ne répond là, ESP_ERR_NOT_FOUND et le handle conserve l'ancienne adresse. rbamp_read_active_address() lit l'adresse persistée.
Compteurs d'énergie à vie
Pour un module qui conserve des compteurs d'énergie persistants sur l'appareil (RBAMP_STD_CAP_ONDEVICE_ENERGY).
typedef struct {
int64_t act_import_wh, act_export_wh, act_net_wh; /* Wh; net = import − export */
int64_t rea_import_varh, rea_export_varh; /* varh */
uint32_t generation; /* changes when the counters were reset or adopted */
uint32_t uptime_s; /* module uptime */
int64_t act_import_mwh, act_export_mwh, act_net_mwh;/* mWh (map 0x36+) */
uint8_t channels; /* valid entries in the per-channel arrays (map 0x36+) */
uint8_t group_status; /* per-channel store: 0 ok · 1 new · 2 fault · 3 restarted at 0 */
int64_t ch_import_mwh[RBAMP_MAX_CHANNELS], ch_export_mwh[RBAMP_MAX_CHANNELS];
bool fine, fine_reactive;
int64_t act_import_uwh, act_export_uwh, act_net_uwh; /* µWh */
int64_t rea_import_uvarh, rea_export_uvarh; /* µvarh */
int64_t ch_import_uwh[RBAMP_MAX_CHANNELS], ch_export_uwh[RBAMP_MAX_CHANNELS];
} rbamp_std_energy_t;
Les compteurs sont en unités entières, monotones et persistants après une coupure d'alimentation. L'import et l'export sont des grandeurs distinctes. L'énergie d'une période est la différence de deux lectures.
-
generationchange lorsque les compteurs ont été remis à zéro ou adoptés sur le module — ne prenez jamais de différence à travers ce changement. -
uptime_squi diminue signifie que le module a redémarré. Les compteurs sont persistants, donc la différence reste bonne, mais l'horloge du module et les réglages en RAM ont disparu. -
Après une coupure d'alimentation, un compteur peut reprendre légèrement en dessous de votre dernière lecture (une fraction de seconde d'énergie) ;
rbamp_std_energy_delta()ramène une telle différence à 0 et conserve l'intervalle. -
Les champs
*_uwh/*_uvarhsont toujours renseignés, vous pouvez donc les utiliser sur chaque module : un module qui publie des compteurs de résolution micro (version d'image de module0x0001007Aet plus récente ; réactifs à partir de0x0001007B) les fournit depuis le même instantané, etfine/fine_reactivevalent vrai ; sur les modules plus anciens, ce sont les compteurs grossiers mis à l'échelle etfinevaut faux. -
channels > 0(map 0x36+) : le canalcest le canal de courantc; sur un module triphasé, la phasec.
rbamp_std_energy_t gagne des champs d'une version de composant à l'autre. Si vous le sauvegardez (NVS, fichier), stockez les champs individuels dont vous avez besoin dans votre propre format fixe — et non la structure comme un blob brut.
| Fonction | Description |
|---|---|
rbamp_std_read_energy(dev, &e) |
Lisez les compteurs. Chaque bloc décodé est une transaction (le module le sert à partir d'un instantané cohérent). ESP_ERR_NOT_SUPPORTED sauf si le module déclare la capacité d'énergie embarquée ; ESP_ERR_INVALID_RESPONSE si le bloc se lit comme non programmé. |
rbamp_std_energy_delta(&prev, &now, &delta, &restarted) |
Énergie entre deux lectures, avec les règles de continuité appliquées. delta = now − prev par compteur (grandeurs import / export, net, réactif ; generation et uptime_s recopiés de now) ; restarted est vrai si uptime_s a diminué. L'une ou l'autre sortie peut être NULL. Un compteur qui a diminué est ramené à une différence de 0, canal par canal également et à chaque résolution ; chaque champ net est la différence d'import moins la différence d'export. Les différences par canal sont produites lorsque les deux lectures portent le même nombre de canaux, sinon delta->channels vaut 0. ESP_ERR_INVALID_STATE si la génération diffère — ne comptabilisez pas cet intervalle ; repartez de now. |
Banques d'instantanés
Le module conserve 8 banques indépendantes (uniquement sur les modules disposant de la capacité multi-instantanés, period_source == RBAMP_STD_PERIOD_LATCH). Une banque accumule tant que son bit est positionné dans le masque d'armement ; rbamp_std_latch() prend un instantané et la remet à zéro à la limite de la prochaine fenêtre de mesure du module. Une période est donc l'intervalle entre deux instantanés d'une même banque, mesuré par l'horloge du maître (le module n'en a pas). La banque 0 est aussi ce qu'utilisent rbamp_read_period_snapshot() et rbamp_energy_wh(). Les trois appels de banque renvoient ESP_ERR_NOT_SUPPORTED sans trafic de bus sur tout autre module — utilisez-y rbamp_std_read_energy() / rbamp_std_energy_delta().
Usage typique : armez les banques une fois, puis pour chaque banque selon votre propre calendrier rbamp_std_latch(bank) → attendez ≥ 300 ms (borne supérieure sûre d'une fenêtre de mesure sur chaque image) → rbamp_std_read_latch() → rbamp_std_latch_wh() avec le dt mesuré par le maître depuis l'instantané précédent.
typedef struct {
float p_avg, q_avg, s_avg; /* average P / Q / S over the period */
float max_p, max_i, max_u, min_u;/* peaks in the period */
int64_t e_import_mws, e_export_mws;/* energy, mW·samples */
uint32_t nsamp; /* sensor samples in the period */
uint32_t win_count; /* measurement windows in the period (0 = not armed / nothing elapsed) */
uint8_t channels; /* valid entries in the per-channel arrays */
uint8_t bank;
bool valid; /* the bank has EVER been snapshotted (not a freshness signal) */
float p_avg_ch[RBAMP_MAX_CHANNELS];
int64_t e_import_ch_mws[RBAMP_MAX_CHANNELS], e_export_ch_mws[RBAMP_MAX_CHANNELS];
} rbamp_std_latch_t;
| Fonction | Description |
|---|---|
rbamp_std_arm_banks(dev, mask) |
Réglez le masque d'accumulation : bit b = la banque b accumule (les banques nouvellement armées démarrent à zéro ; les banques désarmées se figent et conservent leur dernier instantané). Le bit 0 doit rester positionné si vous utilisez rbamp_read_period_snapshot(). Le masque est en RAM sur le module : toute réinitialisation du module l'efface, et prendre un instantané d'une banque non armée renvoie un instantané vide. La bibliothèque réarme elle-même la banque 0 (dans rbamp_begin(), après ses propres réinitialisations, et lorsqu'un instantané de période revient vide). Pour vos propres banques, rbamp_std_read_latch() détecte l'armement perdu, réarme et prend un instantané d'amorçage. |
rbamp_std_latch(dev, bank) |
Demande un instantané + une réinitialisation de bank à la prochaine limite de fenêtre. N'attend pas — lisez-le ≥ 300 ms plus tard. |
rbamp_std_read_latch(dev, bank, &l) |
Lit le dernier instantané de bank (une rafale : totaux + énergie par canal pour chaque canal renseigné). ESP_ERR_INVALID_RESPONSE si le module n'a jamais latché cette banque (les autres champs sont mis à zéro). ESP_ERR_INVALID_STATE si l'instantané est vide parce que la banque a été désarmée par une réinitialisation du module — la bibliothèque l'a réarmée et latchée en amorçage : abandonnez cette période et réinitialisez votre ancrage dt. Lisez une banque au moins une fenêtre de mesure après l'avoir latchée ; win_count == 0 signifie qu'elle n'était pas armée ou qu'aucune fenêtre ne s'est écoulée. |
rbamp_std_latch_wh(&l, dt_ms, ch, &wh_import, &wh_export) |
Convertit les tranches d'énergie d'un instantané en Wh sur la période mesurée par le maître dt_ms (l'horloge murale du maître entre l'instantané précédent et celui-ci de la banque). ch est un indice de canal ou RBAMP_STD_TOTAL (0xFF) pour les totaux de banque. Wh = E[mW·échantillons] / 1000 / 3600 × (dt / nsamp) : le nombre d'échantillons et le dt du maître normalisent le résultat. Import ≥ 0, export ≤ 0 ; l'une ou l'autre sortie peut être NULL. ESP_ERR_INVALID_STATE si nsamp vaut 0. |
Horloge, commandes et maintenance
Le module conserve son horloge en RAM : elle est invalide après chaque réinitialisation du module. Sans horloge valide, le module n'enregistre aucun historique.
| Fonction | Description |
|---|---|
rbamp_std_set_time(dev, unix_epoch) |
Règle l'horloge du module (secondes Unix) et attend la fin. À appeler après rbamp_begin() et chaque fois que rbamp_std_health_t.time_valid est à faux (ou qu'une période signale module_restarted). Le premier réglage après une réinitialisation clôt l'intervalle d'historique en cours sans le reporter. ESP_ERR_INVALID_ARG si le module refuse l'époque (avant 2020) ; ESP_ERR_INVALID_STATE si l'horloge n'est pas devenue valide ; ESP_ERR_NOT_SUPPORTED en dessous de la carte 0x35. |
rbamp_std_read_time(dev, &epoch, &valid) |
Lit l'horloge du module et indique si elle est valide. |
rbamp_std_command(dev, opcode, settle_ms, timeout_ms) |
Écrit un opcode de commande et attend sa fin : attend d'abord que le module soit inactif (une commande écrite pendant qu'il est occupé est perdue), dort settle_ms, attend que BUSY retombe, puis lit le verdict. timeout_ms 0 = 1 s. Verdicts : ESP_ERR_INVALID_ARG (paramètre incorrect), ESP_ERR_NOT_SUPPORTED (commande inconnue), ESP_ERR_INVALID_CRC (contrôle de valeur), ESP_ERR_NOT_FINISHED (écriture flash limitée en débit — réessayez après environ 5 s), ESP_ERR_NOT_ALLOWED (clé ou verrou de maintenance), ESP_ERR_TIMEOUT (toujours occupé). |
rbamp_std_wait_idle(dev, timeout_ms) |
Attend que le module ait fini la commande qu'il exécute. Chaque commande émise par cette bibliothèque attend déjà ; utilisez ceci uniquement autour des commandes que vous écrivez vous-même dans le registre de commandes — une commande écrite pendant l'état BUSY est perdue. Renvoie immédiatement sur les modules sans registre d'état de commande. |
rbamp_std_hist_flush(dev) |
Écrit maintenant les accumulateurs d'énergie en flash (implicite aussi lors d'une réinitialisation / d'un commit du firmware). |
Une écriture de commande n'est jamais réessayée en cas d'erreur de transport (une nouvelle tentative pourrait délivrer l'opcode deux fois) ; les lectures et écritures de registres de données conservent la nouvelle tentative.
Historique et journal d'événements
Le module conserve le dernier enregistrement de 15 minutes en RAM (perdu à une réinitialisation du module — un indicateur en direct, pas un historique) et un anneau horaire en flash qui survit aux réinitialisations et sert de source pour le rattrapage ; les deux ne sont écrits que lorsque l'horloge du module est valide. Un journal d'événements jamais effacé enregistre les changements pertinents pour le comptage. Chaque enregistrement HOUR porte les compteurs de durée de vie en valeur absolue à la fin de la période : l'énergie totale de la période est la différence de deux enregistrements consécutifs (les réinitialisations et les trous restent visibles). Rattrapage après une panne du maître : parcourez back depuis 0 (le plus récent) jusqu'aux horodatages que vous possédez déjà.
typedef enum {
RBAMP_STD_HIST_MIN15 = 0, /* 15-minute records (RAM, lost at module reset) */
RBAMP_STD_HIST_HOUR = 1, /* hourly records (flash ring) */
RBAMP_STD_HIST_EVENTS = 2, /* event log — read with rbamp_std_event_read */
} rbamp_std_hist_period_t;
typedef struct {
uint16_t count; /* records available (0 while the ring is being cleared) */
uint16_t capacity; /* ring depth */
uint16_t record_size; /* bytes per record */
uint32_t oldest_ts, newest_ts; /* unix */
} rbamp_std_hist_info_t;
typedef struct {
uint32_t ts; /* period start, unix */
uint16_t flags; /* RBAMP_STD_HF_* bits */
uint16_t n; /* samples (MIN15) or 15-minute children (HOUR: 4 = complete) */
bool from_ram; /* record came from the RAM ring (not yet persisted) */
float v_rms, i_total, p_avg, q_avg, s_avg, pf;
float p_min, p_max, i_min, i_max;
uint64_t e_import_wh, e_export_wh; /* life-time counters ABSOLUTE at period end */
uint8_t phases; /* valid entries in the per-phase arrays */
double ph_import_wh[3], ph_export_wh[3]; /* per-phase energy OF THIS PERIOD, Wh */
} rbamp_std_hist_record_t;
typedef struct {
uint32_t ts; /* unix time (0 = clock was not set) */
uint32_t uptime_s; /* module uptime at the event */
uint8_t type; /* RBAMP_STD_EV_* */
uint8_t flags; /* RBAMP_STD_EVF_* (maintenance mode was active) */
uint16_t boot; /* boot counter (low 16 bits) */
uint32_t a_before, a_after; /* type-specific values before / after the change */
uint64_t e_before_wh, e_after_wh; /* grand import counter before / after, Wh */
} rbamp_std_event_t;
| Fonction | Description |
|---|---|
rbamp_std_hist_info(dev, period, &info) |
État en anneau d'une période d'historique (la sélectionne aussi sur le module). |
rbamp_std_hist_read(dev, period, back, &rec) |
Récupère et décode l'enregistrement back (0 = le plus récent) de MIN15 ou HOUR. ESP_ERR_NOT_FOUND s'il n'existe pas d'enregistrement de ce type. Prenez l'énergie d'une période à partir de deux enregistrements consécutifs seulement si leurs horodatages diffèrent exactement d'une période et qu'aucun ne porte le drapeau RBAMP_STD_HF_LTA_JUMP. |
rbamp_std_hist_read_raw(dev, period, back, rec, &flags) |
Le même enregistrement non décodé : rec (un tampon RBAMP_STD_REG_HIST_REC_SIZE ; la longueur utile est record_size) reçoit les octets de l'enregistrement du module, flags les drapeaux d'enregistrement du module. |
rbamp_std_event_read(dev, back, &ev) |
Récupère et décode l'entrée du journal d'événements back (0 = la plus récente). ESP_ERR_NOT_FOUND s'il n'y en a aucune. Les types d'événements sont les constantes générées RBAMP_STD_EV_* (réinitialisation / adoption du compteur de durée de vie, sauvegarde de calibration, validation du firmware, effacement de l'historique, ...). |
Authenticité
Un module provisionné porte un certificat d'appareil signé par la clé du fabricant et répond à un défi par une signature numérique faite avec la clé de l'appareil nommée dans ce certificat. La bibliothèque récupère les deux ; leur vérification relève de l'application (avec une bibliothèque de signature de votre choix).
typedef struct {
uint8_t raw[RBAMP_STD_REG_SEC_CERT_SIZE]; /* certificate bytes as read */
uint8_t state; /* the module's own check: 0 none · 1 ok · 2 bad · 3 not checked yet (shortly after boot) */
uint8_t version, variant, hw_rev;
uint8_t uid[12]; /* chip UID the certificate was issued for (compare with rbamp_read_uid) */
uint32_t batch, issued; /* production batch; issue time, unix */
uint8_t device_pubkey[32];
uint32_t mfr_key_id;
} rbamp_std_certificate_t;
typedef struct {
uint8_t signature[64]; /* signature over the attested message */
uint8_t data[24]; /* attested data exactly as signed */
uint32_t fw_version, generation; /* from data */
int64_t e_import_wh, e_export_wh; /* from data: life-time import / export, Wh */
} rbamp_std_attestation_t;
| Fonction | Description |
|---|---|
rbamp_std_read_certificate(dev, &cert) |
Lit le certificat de l'appareil. ESP_ERR_NOT_FOUND si le module n'en a pas (non provisionné ; state reste renseigné) ; ESP_ERR_NOT_SUPPORTED en dessous de la carte 0x35. |
rbamp_std_attest(dev, challenge, &att) |
Soumettez le module à un défi de 32 octets aléatoires de votre choix (gardez votre copie — le module écrase la zone de défi par la signature) et récupérez la réponse signée (environ 60 ms). Les données attestées lient la version du firmware et les compteurs de durée de vie à la clé de l'appareil. ESP_ERR_NOT_FOUND si le module n'a pas de clé d'appareil ; ESP_ERR_INVALID_STATE si le module n'a pas signalé l'attestation comme effectuée. |
Mise à jour du firmware (OTA)
Une mise à jour en deux phases sur I²C. Toutes les fonctions de cette page renvoient ESP_ERR_NOT_SUPPORTED sauf si le module signale la capacité OTA (carte 0x33 ou supérieure). Chaque commande s'achève de façon synchrone à l'intérieur de la bibliothèque (elle attend l'état de commande du module, sans délai fixe).
Séquence : rbamp_std_ota_begin → rbamp_std_ota_write_page × N (pages de 256 octets ; les pages vierges à 0xFF peuvent être sautées) → rbamp_std_ota_commit (vérifie et arme la bascule, sans redémarrage) → rbamp_std_ota_activate (redémarre sur la nouvelle image quand vous le décidez). Le module est hors bus quelques secondes, puis exécute un essai d'environ 10 s avant que l'image soit confirmée. Après chaque page, la session doit toujours être ouverte, sinon l'appel échoue avec ESP_ERR_INVALID_STATE (redémarrez depuis begin). Une mauvaise image est annulée par le module lui-même ; la calibration survit.
Seules les images préparées par le fournisseur sont acceptées. Les images de version sont produites par l'outillage du fabricant du module (signées et, si requis, chiffrées) ; le module refuse un en-tête construit sur l'hôte à la validation. rbamp_std_ota_write_image() (image construite sur l'hôte, non signée) renvoie donc ESP_ERR_NOT_SUPPORTED avant de toucher au module et n'est conservée que pour la compatibilité ABI.
| Fonction | Description |
|---|---|
rbamp_std_ota_status(dev, &st) |
L'état OTA du module (RBAMP_STD_OTA_IDLE / READY / OK / ERR / DOWNGRADE). |
rbamp_std_ota_begin(dev, timeout_ms) |
Efface la banque inactive et attend que le module signale READY. timeout_ms 0 = par défaut (5 s). ESP_ERR_TIMEOUT si READY n'a pas été atteint. |
rbamp_std_ota_write_page(dev, page_idx, page) |
Écrit une page de 256 octets à l'index page_idx (décalage / 256 dans la banque). ESP_ERR_INVALID_STATE si le module signale une erreur d'écriture. |
rbamp_std_ota_commit(dev, timeout_ms) |
Vérifie l'image écrite et arme la bascule de banque. timeout_ms 0 = valeur par défaut (3 s). ESP_OK armée · ESP_ERR_INVALID_CRC image défectueuse (CRC / en-tête) · ESP_ERR_INVALID_MAC authentification échouée · ESP_ERR_INVALID_VERSION image plus ancienne que celle en fonctionnement · ESP_ERR_TIMEOUT. |
rbamp_std_ota_diag(dev, &reason) |
Raison pour laquelle le module a rejeté la dernière page ou le dernier commit : l'octet de motif de ses diagnostics OTA (0 = aucun). rbamp_std_ota_commit() fait déjà correspondre le motif au code d'erreur ci-dessus et journalise son nom ; appelez cette fonction lorsque vous avez besoin du code lui-même. |
rbamp_std_ota_activate(dev) |
Redémarrer dans l'image armée, attendre le retour du module (environ 4 s), le redécouvrir, puis tenir la fenêtre d'essai et confirmer : la banque en cours a changé, l'image en cours est la version préparée, l'échange n'est plus en attente. Bloque pendant environ 10 s au total — ne réinitialisez ni ne coupez l'alimentation du module pendant cette fenêtre (le chargeur de démarrage restaure une image non confirmée). Le handle reste valide et rbamp_std_info() reflète le nouveau firmware. ESP_ERR_INVALID_STATE si rien n'était armé, si le module est revenu sur l'image précédente (retour arrière), ou si l'échange est toujours en attente après l'essai. |
rbamp_std_ota_staged_version(dev, &v) |
Version de l'image armée (validée, non encore activée) ; 0 lorsque rien n'est armé (carte 0x35+). |
rbamp_std_ota_abort(dev) |
Fermez une session de mise à jour et désarmez une image armée ; le module continue d'exécuter ce qu'il exécute (carte 0x35+). |
rbamp_std_ota_board_ok(dev, image_board_word) |
Vérification préalable avant de diffuser une image préparée : le mot de carte de l'image (fourni à côté du fichier image par l'outillage du fournisseur) doit être égal à l'identifiant de carte du module. ESP_OK s'il correspond ; ESP_ERR_INVALID_ARG sinon (journalisé) ; ESP_ERR_NOT_SUPPORTED en dessous de la carte 0x36. |
rbamp_std_ota_write_prepared(dev, image, size, cb, ctx) |
Diffuse une banque préparée telle quelle : début, pages dans l'ordre croissant (la page 0 est toujours envoyée, les autres pages entièrement à 0xFF sont ignorées), validation. Rien n'est modifié par la bibliothèque. N'active pas. size doit être égal à la taille de banque annoncée par le module (rbamp_std_info_t.ota_bank_size) — sinon ESP_ERR_INVALID_SIZE et rien n'est écrit. cb(done, total, ctx) est un rappel de progression facultatif (rbamp_std_ota_progress_cb_t). |
rbamp_std_ota_write_prepared_pair(dev, bank_a, size_a, bank_b, size_b, cb, ctx) |
Comme ci-dessus, avec les deux images de banque : la bibliothèque demande au module quelle banque est active et envoie l'autre. ESP_ERR_NOT_SUPPORTED sur les modules qui ne signalent pas leur banque active (carte inférieure à 0x35) — utilisez alors rbamp_std_ota_write_prepared() et choisissez vous-même selon active_bank. |
rbamp_std_crc32(data, len) |
CRC-32 (compatible zlib) — la somme de contrôle que le module vérifie à la validation. |
rbamp_std_ota_make_header(out, version, len, crc32) |
Construit l'en-tête d'image en petit-boutiste. Disponible uniquement lorsque l'en-tête de registres généré définit les constantes d'en-tête ; conservé pour l'ABI. |
Diagnostic
rbamp_err_to_str
const char *rbamp_err_to_str(esp_err_t err);
Renvoie un pointeur vers une chaîne statique contenant une description lisible du code d'erreur. Il ne renvoie jamais NULL. Il utilise esp_err_to_name() standard pour les codes système et développe les descriptions pour les sémantiques propres à rbamp (par exemple, ce que signifie ESP_ERR_INVALID_STATE dans le contexte de set_ct_model_ch sans set_sensor_class).
Utilisation type :
esp_err_t err = rbamp_read_period_snapshot(dev, &snap, 50, false);
if (err != ESP_OK) {
ESP_LOGE(TAG, "snapshot failed: %s", rbamp_err_to_str(err));
}
rbamp_retry_exhaustion_count / rbamp_sanity_reject_count / rbamp_reset_counters
uint32_t rbamp_retry_exhaustion_count(rbamp_handle_t dev);
uint32_t rbamp_sanity_reject_count (rbamp_handle_t dev);
void rbamp_reset_counters (rbamp_handle_t dev);
Accesseurs publics de deux compteurs de diagnostic (tous deux renvoient 0 sur un handle NULL) :
-
rbamp_retry_exhaustion_count(dev)— un compteur monotone d'événements « budget de reprises épuisé ». Chaque incrément = une transaction d'un octet qui, aprèsCONFIG_RBAMP_NACK_RETRY_ATTEMPTStentatives, n'a jamais reçu d'ACK de l'appareil. -
rbamp_sanity_reject_count(dev)— un compteur monotone des rejets par le filtre de cohérence lors des lectures de flottants (NaN, Inf, ou une valeur absolue au-dessus de la limite par grandeur —RBAMP_SANITY_LIMIT_V/_I/_P/_PF). Chaque incrément = un flottant arrivé par le bus, jugé non conforme à une valeur physique, et écarté ; la lecture renvoieESP_ERR_INVALID_RESPONSE.
rbamp_reset_counters(dev) remet à zéro les deux compteurs de ce handle (sans effet pour NULL). Il est prévu pour les scénarios de test qui ont besoin d'une base propre. Pour la surveillance en production, privilégiez le motif canonique « débit sur un intervalle » — instantané + différence, robuste face aux fenêtres de remise à zéro manquées :
uint32_t prev = rbamp_retry_exhaustion_count(dev);
/* ...60 s of normal operation... */
uint32_t delta = rbamp_retry_exhaustion_count(dev) - prev;
if (delta > THRESHOLD) { /* alert */ }
Ces noms correspondent à la bibliothèque Arduino multiplateforme (dev.retryExhaustionCount() / dev.sanityRejectCount() — même sémantique, en snake_case). Pour les charges de travail pratiques et les seuils d'alarme, voir 10 · Dépannage, section « Surveillance des compteurs ».
Journalisation via esp_log
Le composant journalise sous le tag "rbamp". Le niveau de journalisation est compilé via Kconfig — le esp_log_level_set("rbamp", ...) à l'exécution fonctionne mais est plafonné par le niveau de compilation.
esp_log_level_set("rbamp", ESP_LOG_DEBUG); /* for debugging */
Codes d'erreur
Les fonctions rbamp_* renvoient les valeurs standard esp_err_t. Les codes spécifiques et leur sémantique dans le contexte rbamp :
| Code | Quand | Où regarder |
|---|---|---|
ESP_OK (0) |
Succès | — |
ESP_FAIL (-1) |
La transaction I²C a échoué après les reprises | câblage, alimentation, vitesse du bus — section « The module does not respond over I²C » dans 10 · Dépannage |
ESP_ERR_INVALID_ARG (0x102) |
Argument invalide : dev == NULL, channel ou phase hors plage, un cls non reconnu, une valeur rejetée par le module (modèle de CT inconnu, courant de démarrage hors de l'ensemble accepté, une horloge antérieure à 2020) |
vérifier les arguments de l'appel |
ESP_ERR_TIMEOUT (0x107) |
rbamp_wait_ready / rbamp_wait_data_ready expiré ; la fenêtre rbamp_commit_address_change (5 s) expirée ; une commande STD ou un état OTA non achevé |
vérifiez la réactivité via rbamp_probe() |
ESP_ERR_INVALID_STATE (0x103) |
Une condition préalable ou un ordre d'appels est incorrect : set_ct_model* avant set_sensor_class ; le module est de classe 2 / 3 (étalonné avec son capteur — utilisez rbamp_set_ct_model_ch_force() pour la maintenance) ; le module a rejeté la paire (classe, modèle) ; commit d'adresse non armé ; banque d'instantanés STD réarmée après une réinitialisation du module (abandonner cette période) ; le compteur STD a changé de génération (rbamp_std_energy_delta) ; session OTA non ouverte |
section « rbamp_set_* renvoie ESP_ERR_INVALID_STATE » dans 10 · Dépannage |
ESP_ERR_NOT_SUPPORTED (0x106) |
La fonction ou la fonctionnalité n'existe pas sur cette gamme / ce firmware / ce module : tout appel rbamp_std_* sur un handle BASIC, puissances réactive / apparente sur BASIC, rbamp_read_digest sur STD ou sans la capacité digest, appels de période sur un module STD sans banques d'instantanés ni compteurs, rbamp_factory_reset sur STD, une version de carte de registres trop ancienne, OTA sans la capacité |
vérifiez rbamp_line(dev), rbamp_std_info() et rbamp_variant(dev) |
ESP_ERR_NOT_FOUND |
Rien de présent : rbamp_std_probe — rien n'accuse réception à l'adresse ; pas d'historique ni d'enregistrement d'événement ; pas de certificat ni de clé de périphérique ; commit d'adresse — rien ne répond à la nouvelle adresse (le handle conserve l'ancienne) |
vérifiez le câblage / l'adresse ; ne remontez back que jusqu'à rbamp_std_hist_info().count |
ESP_ERR_INVALID_RESPONSE (0x108) |
Instantané de période périmé (drapeau prêt = 0) ou période sautée (compteurs STD réancrés, banque réarmée) ; REG_VERSION = 0/0xFF sur rbamp_begin ; un flottant a échoué au filtre de cohérence ; fréquence secteur STD à 0 (pas de secteur) ; rbamp_std_probe — quelque chose répond qui n'est pas un module STD |
section « Les instantanés de période sont toujours périmés » / « Impossible de quitter rbamp_begin » dans 10 · Dépannage |
ESP_ERR_NO_MEM (0x101) |
Impossible d'allouer la mémoire du handle ; plus de 4 lignes DRDY / 8 handles par ligne | vérifier le budget de tas |
ESP_ERR_NOT_FINISHED |
STD : l'écriture en flash du module est limitée en fréquence | réessayer après environ 5 s |
ESP_ERR_INVALID_CRC, ESP_ERR_INVALID_MAC, ESP_ERR_INVALID_VERSION, ESP_ERR_INVALID_SIZE, ESP_ERR_NOT_ALLOWED |
Verdicts de commande / OTA STD : une valeur ou une vérification d'image a échoué, l'authentification a échoué, l'image est plus ancienne que celle en cours, l'image ne tient pas dans la banque, le module a refusé l'opération (voir rbamp_std_command, rbamp_std_ota_commit) |
rbamp_std_ota_diag() pour la raison |
Tous les codes renvoyés peuvent être affichés de façon lisible par rbamp_err_to_str().
Configuration à la compilation (Kconfig)
Les symboles CONFIG_RBAMP_* suivants sont disponibles dans idf.py menuconfig → Component config → rbAmp client [Component config → rbAmp client] :
| Symbole | Type | Plage / choix | Par défaut | Objet |
|---|---|---|---|---|
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ |
int | 50000–1000000 Hz | 50000 | Fréquence SCL. 50 kHz est la valeur imposée pour le firmware actuel sur ESP32. |
CONFIG_RBAMP_I2C_TIMEOUT_MS |
int | 10–1000 ms | 100 | Délai d'attente de i2c_master_transmit/receive. Il doit être suffisamment long pour absorber la latence de pré-lecture du module. |
CONFIG_RBAMP_I2C_SCL_WAIT_US |
int | 2000–60000 µs | 10000 | Tolérance à l'étirement d'horloge SCL : durée pendant laquelle le périphérique I²C accepte que le module maintienne SCL à bas niveau avant d'abandonner la transaction. La valeur par défaut du pilote est de 2 ms ; un module étire SCL plus longtemps pendant qu'il efface un secteur de flash lors d'une mise à jour du firmware, et chaque étirement de ce type aboutirait à une ligne de journal « I2C hardware timeout » et à une nouvelle tentative. 10 ms couvre l'effacement de secteur. L'ESP32 d'origine ne peut pas attendre plus d'environ 13 ms (compteur matériel de 20 bits) ; le composant borne la valeur à ce plafond sur cette cible. |
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS |
int | 1–10 | 3 | Tentatives par lecture d'un octet. |
CONFIG_RBAMP_NACK_RETRY_GAP_MS |
int | 1–100 ms | 5 | Intervalle entre les tentatives de reprise. |
CONFIG_RBAMP_BUS_RESET_ON_RETRY_EXHAUSTION |
bool | n/y | n | Lorsque toutes les nouvelles tentatives NACK d'une transaction échouent, appelez i2c_master_bus_reset() une fois avant la dernière tentative. Le pilote IDF réinitialise déjà sa machine d'état après chaque transaction échouée, et la réinitialisation explicite ne prend aucun verrou de bus : avec plusieurs tâches partageant le bus, elle peut interrompre la transaction d'une autre tâche (sur ESP32, elle émet un STOP sur les broches, que le gestionnaire d'interruption du pilote peut prendre pour la fin d'une lecture). À laisser désactivé sauf si le maître est mono-tâche et si l'on constate que le bus reste bloqué après des erreurs du pilote. |
CONFIG_RBAMP_SCT_RATING_CORRECTION |
bool | n/y | y | Correction des lectures SCT-013 sur le firmware BASIC jusqu'à 1.4.19, qui conserve l'étalonnage 30 A après que l'utilisateur a changé le canal pour un autre modèle. La bibliothèque met à l'échelle le courant, la puissance, la puissance par période, l'énergie et le condensé selon le modèle sélectionné (rbamp_sct_correction() indique le résultat par canal). Un module qui se corrige lui-même (firmware 1.4.20 et ultérieur) n'est pas concerné. Désactivez pour lire les valeurs brutes du module. Voir Correction de la puissance nominale SCT-013. |
CONFIG_RBAMP_DRDY_POLL_MS |
int | 5–50 ms | 20 | Lorsqu'un handle n'a pas de GPIO DRDY, rbamp_wait_data_ready() interroge le compteur de publication du module (STD) ou la séquence de commit (BASIC) à cet intervalle. Le module publie toutes les 100 ms (images plus anciennes : 200 ms). |
CONFIG_RBAMP_DISABLE_ENERGY |
bool | n/y | n | Retire entièrement l'accumulateur Wh de la compilation (stockage et API). |
CONFIG_RBAMP_LOG_LEVEL_* |
choix | NONE / ERROR / WARN / INFO / DEBUG | INFO | LOG_LOCAL_LEVEL à la compilation pour l'étiquette rbamp. Contrôle si les chaînes de journalisation sont même compilées dans le binaire ; indépendant de CONFIG_LOG_DEFAULT_LEVEL. |
Un exemple de sdkconfig.defaults pour un scénario de production typique :
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=3
CONFIG_RBAMP_NACK_RETRY_GAP_MS=5
CONFIG_RBAMP_I2C_TIMEOUT_MS=100
CONFIG_RBAMP_LOG_LEVEL_INFO=y
# leave CONFIG_RBAMP_DISABLE_ENERGY disabled (default n)
Pour un essai de banc sous forte charge :
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=5
CONFIG_RBAMP_I2C_TIMEOUT_MS=200
CONFIG_RBAMP_LOG_LEVEL_DEBUG=y
Constantes de temps de stabilisation
Le composant utilise en interne les temps de stabilisation suivants lors de l'exécution des commandes (pour un utilisateur qui travaille sur l'API brute via i2c_master_transmit_receive et qui veut respecter les mêmes temporisations) :
La bibliothèque exporte un petit ensemble de constantes de stabilisation (ms) destinées aux utilisateurs de l'API brute qui envoient directement des commandes au module et doivent attendre que celui-ci ait fini de traiter avant de lire les registres concernés. Les fonctions d'enveloppe du composant (rbamp_save_gains, rbamp_factory_reset, rbamp_set_ct_model_ch, etc.) appliquent en interne le délai correct : ces constantes ne sont nécessaires que si vous contournez les enveloppes.
| Macro | Objet | ms |
|---|---|---|
RBAMP_SETTLE_MS_LATCH_PERIOD |
Après CMD_LATCH_PERIOD |
50 |
RBAMP_SETTLE_MS_RESET |
Après CMD_RESET |
100 |
RBAMP_SETTLE_MS_SAVE_GAINS |
Après CMD_SAVE_GAINS (effacement + écriture de la flash) |
700 |
RBAMP_SETTLE_MS_FACTORY_RESET |
Après CMD_FACTORY_RESET |
1500 |
RBAMP_SETTLE_MS_SET_CT_MODEL_CH0 |
Après CMD_SET_CT_MODEL_CH0 |
5 |
RBAMP_SETTLE_MS_SET_CT_MODEL_CH1 |
Après CMD_SET_CT_MODEL_CH1 |
5 |
RBAMP_SETTLE_MS_SET_CT_MODEL_CH2 |
Après CMD_SET_CT_MODEL_CH2 |
5 |
La source de vérité est le bloc @defgroup rbamp_settle_ms dans include/rbamp.h. Les valeurs sont les minimums de spécification du protocole rbAmp ; vous ne pouvez pas descendre en dessous, mais vous pouvez aller plus haut.
Détails du protocole filaire
Lectures de registres — incrémentation automatique
Une lecture en rafale renvoie N octets consécutifs à partir de addr. Exemple : une seule transaction i2c_master_transmit_receive(slave, {0x86}, 1, buf, 16, ...) lit 16 octets à partir de 0x86 (U_RMS + U_PEAK + I_RMS + I_PEAK sur UI1).
Écritures de registres — octet par octet (PAS d'incrémentation automatique)
arriveseul le premier octet— les octets 1..N sont abandonnés.
Un registre multi-octets s'écrit octet par octet — une transaction I²C distincte d'un seul octet par adresse :
/* WRONG — data loss */
uint8_t label[8] = "MyMeter1";
uint8_t buf[9] = { 0x68, 'M', 'y', 'M', 'e', 't', 'e', 'r', '1' };
i2c_master_transmit(slave, buf, 9, 100); /* only 'M' lands */
/* CORRECT — byte-at-a-time loop */
for (int i = 0; i < 8; i++) {
uint8_t tx[2] = { 0x68 + i, label[i] };
i2c_master_transmit(slave, tx, 2, 100);
}
Cela concerne les registres multi-octets inscriptibles : LABEL (0x68-0x6F), U_GAIN / I_GAIN (f32, verrouillé en usine), NF (u16), THRESH (u16). Les lectures en rafale sont admises (l'incrémentation automatique fonctionne en LECTURE).
Lecture de registres non cartographiés
Toute lecture d'une adresse non mappée renvoie 0x00. Le firmware ne répond jamais par un NACK aux lectures de registres. La détection d'un appareil absent doit passer par l'ACK de la trame d'adresse I²C, non par une sonde des registres.
Détection de variante
L'octet de référence SKU faisant foi est le registre 0x55 (mis en cache sous rbamp_variant()) :
| valeur | SKU |
|---|---|
0x01 |
UI1 (1× I + U) |
0x02 |
UI2 (2× I + U) |
0x03 |
UI3 (3× I + U) |
0x04 |
I1 (1× I, sans U) |
0x05 |
I2 (2× I, sans U) |
0x06 |
I3 (3× I, sans U) |
0x07 |
UI5 (5× I + U) |
0x08 |
UI7 (7× I + U) |
rbamp_topology() est auxiliaire ; il ne renvoie que le nombre de canaux (1/2/3/5/7) et ne distingue pas la présence de U.
⚠ REG_SENSOR_CLASS (0x25) n'est PAS un discriminant de variante (il est fourni par la configuration utilisateur). L'invariant de variante = HW_VARIANT (0x55) + CAPABILITY (0x57/0x58) — tous deux en lecture seule.
CAPABILITY (0x57/0x58, u16 LE) — carte de détection des fonctionnalités
Une carte des capacités de l'appareil (par exemple : étage d'entrée en tension présent, instantané General-Call pris en charge, bloc digest, drapeaux d'événements, changement d'adresse en deux phases). C'est la façon canonique de détecter les fonctionnalités (au lieu de comparer une version numérique). Vérifiez les drapeaux de capacité individuels via les fonctions d'aide ; l'ensemble des drapeaux s'étend avec le firmware du module.
has_voltage (sans lire HW_VARIANT) :
/* Option 1 — the cached helper (no bus traffic after rbamp_begin). */
bool has_voltage = rbamp_has_voltage(dev);
/* Option 2 — read the full 16-bit CAPABILITY (LE). */
uint16_t cap;
rbamp_read_capability(dev, ∩);
bool has_voltage_2 = (cap & RBAMP_CAP_ZC_PHASE_OFFSET) != 0; /* voltage front-end flag */
Les deux options sont équivalentes.
Cohérence HW_VARIANT ⟷ CAPABILITY : HW_VARIANT 1..3 (UI) → drapeau de l'étage d'entrée en tension positionné ; HW_VARIANT 4..6 (I) → drapeau effacé. Une incohérence = une anomalie matérielle.
Atomicité / gel de lecture (B1)
- Bloc RMS flottant V03 (0x86+ : U_RMS, U_PEAK, I_RMS, I_PEAK, P, PF, fréquence) — gel de lecture présent, la lecture en rafale est atomique.
- Bloc digest (0x70-0x85) — gel de lecture présent.
- GC_TICK (0x59) / miroir d'adresse (0x30) / miroirs de modèles de CT (0x51-0x53) — absence de gel de lecture ; pour une lecture fiable, utilisez le motif lecture-deux-fois-accord (lisez deux fois, ne considérez la valeur valide que si les deux concordent).
Sémantique de la pince NF
I_RMS = 0x00000000 signifie « signal sous le plancher de bruit » (le firmware calcule rms_corr² = max(0, raw² − nf²)), et NON « pas de données » / « erreur ». C'est une mesure valide pour les scénarios sans charge.
Registres de tension seuls sur les variantes courant-seul
U_RMS, U_PEAK sur I1/I2/I3 lisent 0. Ils ne sont valides que lorsque le drapeau d'étage de tension CAPABILITY est positionné. REG_AC_FREQ est dérivé du passage à zéro et disponible sur toutes les variantes (y compris I*).
Instantané diffusé General-Call (synchronisation multi-modules)
Activation par module via bit0 du registre REG_FLEET_CONFIG (0x27) — GC_ENABLE. Désactivé par défaut. Activé via CMD_SAVE_USER_CONFIG + CMD_RESET (à chaud ou à froid). Après une réinitialisation, le module écoute la trame de diffusion à l'adresse d'appel général I²C 0x00 :
addr=0x00 | A5 27
A5— magique.27— l'opcodeCMD_LATCH_PERIOD.—0x00= appel général, sinon doit correspondre àREG_GROUP_ID(0x28).— un compteur de période sur 16 bits (synchronisation du maître).
La trame ne déclenche que l'instantané de période ; elle ne transporte jamais d'opcodes destructeurs.
Détection des modes de défaillance (à deux niveaux, confirmé sur matériel C.10) :
- NACK d'adresse générale (GC) (immédiat, au niveau du bus) : si le GC est désactivé sur toute la flotte,
i2c_master_transmitvers0x00renvoieESP_FAIL/ESP_ERR_INVALID_STATE. C'est une erreur franche, non un rejet silencieux. La bibliothèque interprète le NACK comme « GC non activé » (elle exige les préconditions activation + réinitialisation). - Témoin par module (après stabilisation) : si aucun NACK ne s'est produit — le maître lit
REG_V03_PERIOD_VALID (0x07)sur chaque esclave attendu :1= l'instantané a réussi,0= GC désactivé sur ce module précis, ou la période est vide.
Liens
- 05 · Démarrage rapide — votre premier projet fonctionnel
- 06 · Exemples — scénarios de fonctionnement
-
10 · Dépannage — décodage des erreurs et résolution des problèmes courants
-
Le fichier d'en-tête source avec les commentaires Doxygen :
include/rbamp.h
Annexe — Sous le capot
Déplacé du chapitre Vue d'ensemble : comparaison au niveau des registres, architecture et diagrammes d'interaction.
Sans le composant (accès direct via i2c_master_transmit_receive)
// Read U_RMS — a single 4-byte burst-read (the firmware supports
// address auto-increment on read).
i2c_master_dev_handle_t slave;
i2c_master_bus_add_device(bus, &(i2c_device_config_t){
.device_address = 0x50, .scl_speed_hz = 50000,
}, &slave);
uint8_t reg = 0x86, buf[4] = { 0 };
if (i2c_master_transmit_receive(slave, ®, 1, buf, 4,
/*xfer_timeout_ms=*/100) != ESP_OK) {
return; // handle the error
}
float u_rms;
memcpy(&u_rms, buf, sizeof(float));
Avec le composant
float u_rms;
ESP_ERROR_CHECK(rbamp_read_voltage(dev, 0, &u_rms));
Lire une période — sans le composant
// Snapshot + 50 ms settle + ready-flag check + burst-read avg_p
uint8_t latch_cmd[2] = { 0x01, 0x27 }; // REG_COMMAND, CMD_LATCH_PERIOD
ESP_ERROR_CHECK(i2c_master_transmit(slave, latch_cmd, 2, /*xfer_timeout_ms=*/100));
int64_t t_latch_us = esp_timer_get_time();
vTaskDelay(pdMS_TO_TICKS(50)); // settle
uint8_t valid_reg = 0x07, valid_byte = 0;
i2c_master_transmit_receive(slave, &valid_reg, 1, &valid_byte, 1, /*xfer_timeout_ms=*/100);
if ((valid_byte & 0x01) == 0) {
// snapshot is stale — t_latch_us STILL must be recorded,
// otherwise the next snapshot will count Wh over two periods
return;
}
// burst-read 4 bytes of avg_p (auto-increment), then assemble the float
// and integrate Wh:
// double dt_s = (esp_timer_get_time() - t_prev_latch_us) / 1e6;
// E_Wh += avg_p * dt_s / 3600.0;
Lecture d'une période — avec le composant
rbamp_period_snapshot_t snap;
if (rbamp_read_period_snapshot(dev, &snap, 50, false) == ESP_OK && snap.valid) {
// snap.avg_p[0] is populated,
// rbamp_energy_wh(dev, 0) has increased by avg_p × master_dt_ms/1000/3600,
// master_dt_ms = master wall-clock dt between snapshots (canonical for energy).
// snap.latch_ms (0xEC) — diagnostic module timer, NOT for energy.
}
En interne, le composant garantit :
-
Une stabilisation de 50 ms après
CMD_LATCH_PERIOD(configurable via le paramètresettle_ms), puis lecture correcte de l'instantané (instantané atomique côté module). -
Un contrôle du drapeau
REG_V03_PERIOD_VALIDavant la lecture (le champsnap.valid). -
Enregistrer l'heure selon l'horloge du maître même sur un instantané périmé (protège contre le double comptage des Wh à la période suivante).
-
Comptabilisation Wh par canal en double précision (le type
doubleà l'intérieur du handle). -
Chargement automatique des coefficients d'étalonnage lorsque le capteur de courant est sélectionné via
rbamp_set_sensor_class()+rbamp_set_ct_model()— l'utilisateur n'a pas besoin de connaître les registres d'étalonnage internes.
Quand utiliser le composant, quand accéder directement au bus
| Tâche | Composant | Accès direct via i2c_master_* |
|---|---|---|
| Lecture de U / I / P / FP / fréquence | ✅ | seulement pour le débogage à l'analyseur logique |
| Comptabilisation de l'énergie par période | ✅ | seulement si les Wh sont stockés hors du composant (par exemple dans une base de données côté maître) |
| Plusieurs modules sur un bus | ✅ (instantané séquentiel + stabilisation partagée, voir 06_examples.md) | — |
| Comptabilisation bidirectionnelle sur BASIC | ✅ (via les lectures RT — voir 06_examples.md) | l'alternative est votre propre boucle de lecture RT + intégration manuelle |
| Portage vers une autre plateforme | n/a | ✅ — voir 09 · Référence API pour les détails du protocole filaire |
| Limite stricte de RAM | rarement significatif (~85 octets par handle) | ✅ si même ces ~85 octets sont critiques |
Pour toutes les tâches typiques des premières lignes, le composant est le bon choix.
Architecture
Diagrammes d'interaction
Le déroulement de rbamp_begin()
Le premier instantané est une amorce (le module renvoie tout ce qui s'est accumulé depuis la mise sous tension, inadapté à la comptabilité tarifaire). Le composant enregistre lui-même que cet instantané doit être écarté — le code utilisateur ne le voit jamais.
Le déroulement de rbamp_read_period_snapshot(dev, &snap, 50, false)
L'instantané atomique côté module garantit que chaque mesure d'une période tombe dans exactement un instantané — sans doublon ni perte à la frontière de période.
Correspondance avec l'API de registres directe
Un tableau pour ceux qui migrent depuis leur propre code d'accès direct :
API directe (i2c_master_transmit_receive) |
Équivalent via le composant |
|---|---|
Lecture manuelle de 4 octets + memcpy |
rbamp_read_voltage(dev, 0, &v) / rbamp_read_power(dev, ch, &p) |
tx([0x01, 0x27]); vTaskDelay(50) |
rbamp_latch_period(dev); vTaskDelay(pdMS_TO_TICKS(50)) (ou directement rbamp_read_period_snapshot()) |
Vérifier read_u8(0x07) & 1 |
le champ snap.valid après rbamp_read_period_snapshot() |
Formule manuelle E_Wh += avg_p * dt_s / 3600 |
rbamp_energy_wh(dev, 0) — mis à jour automatiquement |
| Configuration manuelle du capteur de courant via l'API de registres directe | rbamp_set_sensor_class(dev, cls) + rbamp_set_ct_model(dev, code) — les préréglages d'usine sont chargés automatiquement |
Sources et tickets : rb-amp/rbamp-esp-idf · cette page dans le dépôt : docs/09_api_reference.md (v1.7.3)