10 · Dépannage
Ce chapitre est organisé par les symptômes observés, et non par classification interne des erreurs. Si vous êtes ici, quelque chose ne fonctionne pas comme prévu. Repérez votre symptôme dans la liste ci-dessous, rendez-vous dans la section correspondante et suivez la procédure de diagnostic.
La plupart des problèmes de banc entrent dans trois catégories :
-
Niveau bus — le module ne répond pas sur I²C, les lectures renvoient
NaNouRB_ERR_NACK. -
Niveau des données — le module répond, mais les valeurs sont fausses : zéros, valeurs étranges, mauvais signe.
-
Niveau applicatif — la liaison est instable, le compteur de Wh diverge, le croquis se bloque.
Raccourci pour les impatients : les compteurs dev.retryExhaustionCount() et dev.sanityRejectCount() doivent être à 0 en régime établi. S'ils ne le sont pas, allez directement à la section « Le module ne répond pas sur I²C » ci-dessous.
À vérifier d'abord : U=0 → L/N non raccordés ou disjoncteur ouvert ; I=0 → prise CT non enfoncée à fond (ou aucun modèle de CT défini, voir ci-dessous).
Le module ne répond pas sur I²C
Ce que vous observez : dev.begin() renvoie false avec lastError() == RB_ERR_NACK, ou les lectures à l'exécution font régulièrement « fuir » RB_ERR_NACK dans le code utilisateur.
Étape 1 — Scan du bus
Commencez par confirmer que le module est bien présent sur le bus :
#include
void setup() {
Serial.begin(115200);
Wire.begin();
Serial.println(F("Scanning..."));
for (uint8_t addr = 0x08; addr <= 0x77; addr++) {
Wire.beginTransmission(addr);
if (Wire.endTransmission() == 0) {
Serial.print(F("Found 0x")); Serial.println(addr, HEX);
}
}
}
void loop() {}
Sortie attendue : Found 0x50 (ou une autre adresse si vous l'avez modifiée).
Si rien n'est trouvé — le problème vient du câblage ou de l'alimentation :
- SDA / SCL ne sont pas inversés.
-
Les deux lignes ont une résistance de rappel vers 3.3 V (la carte du module comprend des résistances de rappel intégrées de 4.7 kΩ — aucune externe n'est nécessaire pour un seul module).
-
La broche d'alimentation du module reçoit réellement 5 V (4.5–5.5 V) — les anciennes révisions de carte ne tolèrent pas 3.3 V.
-
Aucun autre maître (sonde de débogage, autre Arduino) n'est bloqué sur les mêmes lignes.
Si le module est trouvé, mais à une adresse inattendue — quelqu'un l'a réadressé plus tôt sur le banc. Mettez à jour l'argument du constructeur :
RbAmp dev(Wire, 0x52); // address from the bus scan
Étape 2 — Schéma de NACK de référence sur ESP32
Si le scan du bus trouve le module, mais que dev.readVoltage() renvoie périodiquement NaN avec RB_ERR_NACK — et que vous êtes sur un ESP32 — il s'agit d'un schéma de référence documenté : le pilote i2c_master d'ESP-IDF v5 présente des particularités avec rbAmp sur le firmware v1.0.
La protection est déjà intégrée à la bibliothèque (RBAMP_NACK_RETRY_ATTEMPTS=3 par défaut sur ESP32), mais sous forte charge le budget de reprises peut s'épuiser.
Que faire sur ESP32 :
- Abaissez la vitesse du bus à 50 kHz :
Wire.begin();
Wire.setClock(50000);
- Augmentez le nombre de tentatives de reprise pour une charge lourde :
#define RBAMP_NACK_RETRY_ATTEMPTS 5
#include
- Surveillez le compteur d'épuisement des tentatives — il doit rester à zéro en régime permanent :
if (dev.retryExhaustionCount() > 0) {
Serial.print(F("WARN: retry exhausted: "));
Serial.println(dev.retryExhaustionCount());
}
Étape 3 — NACK sur les plateformes autres que ESP32
Sur AVR / STM32duino / ESP8266 / SAMD / RP2040, il n'existe pas de schéma de NACK de référence — ces plateformes présentent un taux de NACK d'environ 0 % avec rbAmp. La bibliothèque utilise par défaut RBAMP_NACK_RETRY_ATTEMPTS=1 sur elles.
Si des NACK se produisent ici, recherchez :
-
Capacité de bus élevée — longs câbles + nombreux appareils. Abaissez la vitesse à 100 kHz ou raccourcissez le câble.
-
Contention maître — la bibliothèque ne prend pas en charge une configuration multi-maîtres.
-
Un SCL flottant entre les transactions — une résistance de rappel manquante.
Le courant lit zéro sur une charge en fonctionnement
Ce que vous observez : dev.readCurrent(0) renvoie 0.000 (ou une valeur très faible), alors qu'un vrai consommateur est allumé (une bouilloire, une lampe, un fer). dev.readPowerFactor(0) peut afficher une valeur étrange (NaN / 0 / ±1) — c'est une conséquence ; la cause est dans le courant.
Procédure de diagnostic
- Vérifiez que la classe de capteur et le modèle de CT sont configurés :
if (!dev.setSensorClass(RbAmpSensorClass::Sct013)) {
Serial.println(F("class set failed"));
}
if (!dev.setCTModel(3)) { // or your model: see below
Serial.println(F("model set failed"));
}
Sans ces deux appels, les coefficients de calibration ne sont pas chargés et le courant affiche toujours zéro. Cette étape se fait une seule fois lors de la première installation — le choix est enregistré dans la flash du module.
- Vérifiez que le modèle de TC correspond à la charge. Une grande pince (par exemple SCT-013-100, 100 A) sur une petite charge (une lampe de 50 W ≈ 0.2 A) produit un signal juste au niveau du bruit de fond et les lectures seront nulles. Choisissez la plus petite pince au calibre supérieur à votre plus grand courant attendu. Le tableau complet se trouve dans 03 · Sélection du capteur de courant.
Si vous disposez d'un module multi-canaux (UI2 / UI3 / UI5 / UI7) et souhaitez voir à la fois les petites charges et les pointes, envisagez le schéma à double TC : une petite pince (par exemple SCT-013-005) sur un canal dédié pour la plage basse + une grande (SCT-013-030/100) sur un autre canal pour la plage haute ; le maître choisit la valeur selon un seuil. Ce schéma est traité dans 03 · Sélection du capteur de courant, section « Topologie à double TC ».
- Vérifiez l'orientation de la pince. La flèche sur le corps de la pince doit pointer dans le sens du courant vers la charge. Si la pince est « à l'envers »,
readCurrent()donnera la bonne grandeur, maisreadPower()donnera une valeur négative sur une charge consommatrice. La confirmation —readPowerFactor()affichera exactement −1.0 sur une charge résistive (au lieu de +1.0). La solution : reposez physiquement la pince (circuit hors tension : décrochez-la, retournez la flèche dans le bon sens, réclipsez-la). N'inversez pas le signe dans le logiciel.
Si les trois étapes réussissent et que le courant reste nul
Alors le signal à l'entrée du module est réellement sous le plancher de bruit. Vérifiez :
-
Si le courant circule réellement — mesurez-le avec un multimètre (pince CC / pince ampèremétrique CA) sur le même fil.
-
Si la pince est intacte — il doit y avoir une tension alternative au connecteur de la pince, proportionnelle au courant (quelques millivolts pour les charges domestiques).
-
Vérifiez que vous serrez le bon fil — un seul conducteur, la phase (L) ; jamais la totalité du câble.
Les lectures sautent ou reviennent en NaN
Ce que vous observez : dev.readVoltage() ou dev.readCurrent() renvoient périodiquement NaN. dev.lastError() affiche soit RB_ERR_NACK, soit RB_ERR_NON_PHYSICAL.
Si lastError() indique RB_ERR_NACK
Voir la section « Le module ne répond pas sur I²C » ci-dessus — c'est la même classe de problème, avec une différence : la liaison fonctionne en partie, mais le budget de reprises s'épuise parfois.
Steps:
-
Sur ESP32 — abaissez la vitesse à 50 kHz et augmentez
RBAMP_NACK_RETRY_ATTEMPTS=5. -
Sur les autres plateformes, vérifiez la capacité du bus et les résistances de rappel.
- Surveillez
dev.retryExhaustionCount()pour suivre la tendance.
Si lastError() affiche RB_ERR_NON_PHYSICAL
Le filtre de cohérence de la bibliothèque s'est déclenché : un flottant est arrivé du bus et est soit NaN, soit Inf, soit |x| > 10000 — manifestement pas une valeur physique. La bibliothèque écarte cette valeur et signale RB_ERR_NON_PHYSICAL au lieu de laisser des données erronées atteindre l'application.
C'est un artefact rare. La valeur en régime permanent de dev.sanityRejectCount() est 0. Si elle n'est pas nulle :
-
Vérifiez
dev.retryExhaustionCount(). Si les deux compteurs sont non nuls, le lien est instable et le filtre de cohérence rattrape des données erronées après des tentatives échouées. Augmentez le budget de tentatives (voir ci-dessus). -
Si
retryExhaustionCount == 0mais quesanityRejectCount > 0, un artefact a traversé la couche de nouvelles tentatives. Cela arrive sous charge de bus très élevée. AugmentezRBAMP_NACK_RETRY_ATTEMPTS=5et refaites le test.
Serial.print(F("retries exhausted: "));
Serial.print(dev.retryExhaustionCount());
Serial.print(F(" sanity rejects: "));
Serial.println(dev.sanityRejectCount());
Le facteur de puissance semble étrange
Ce que vous observez : dev.readPowerFactor(0) renvoie une valeur qui ne correspond pas au type de charge.
Attentes selon la charge :
| Charge | FP attendu |
|---|---|
| Bouilloire, fer à repasser, lampe à incandescence | +0.95 .. +1.0 (résistif) |
| Réfrigérateur, moteur de compresseur | +0.6 .. +0.85 (inductif) |
| Lampe LED, téléviseur (alimentation à découpage) | +0.5 .. +0.95 (non linéaire) |
| Onduleur PV injectant de la puissance | PF négatif |
PF = NaN ou 0 quand I = 0
PF est défini comme P / (U × I). Quand le courant est nul (I=0), le calcul n'est pas défini. La valeur renvoyée dépend du firmware (elle peut être NaN, 0 ou un marqueur) — c'est normal tant que le courant est réellement nul. Dès qu'il y a du courant, un PF valide apparaîtra.
Le FP vaut exactement −1.0 sur une charge purement consommatrice
La pince est montée « à l'envers » — la flèche ne pointe pas dans le sens du courant vers la charge. Correctif : remontez la pince correctement (retournez-la physiquement ; n'inversez pas le signe dans le logiciel).
Le FP oscille entre +0.3 et +0.7 sur une charge résistive
-
Cause possible : la pince CT est posée sur un fil d'une autre phase que celle à laquelle l'entrée U du module est raccordée. Dans un tableau de distribution à plusieurs phases, il est facile de pincer la mauvaise phase par erreur — un déphasage de 120° ou 180° entre U et I donne exactement ces valeurs de FP. Le correctif consiste à installer le module de sorte que l'entrée U et la pince soient sur la même phase.
-
Autre hypothèse : la charge n'est pas réellement purement résistive. Refaites le test avec une charge résistive connue (une bouilloire électrique à pleine puissance).
Les instantanés de période sont toujours stale
Ce que vous observez : dev.readPeriodSnapshot(snap) renvoie false avec lastError() == RB_ERR_STALE. Cela signifie que le module n'a pas fini d'intégrer la période précédente au moment de la lecture suivante.
La bibliothèque protège contre le double comptage des Wh : sur une lecture périmée, elle enregistre un horodatage maître, et l'instantané valide suivant couvre une période, pas deux.
Acceptable : des instantanés périmés rares (1 à 2 par heure à une cadence de 60 s). Non acceptable : des instantanés périmés consécutifs — cela signifie que le firmware ne répond plus ou que le maître interroge trop souvent.
Procédure de contrôle de la cadence
-
Vérifiez la cadence : 60 s entre les instantanés est confortable ; 30 s est limite ; < 10 s garantit des instantanés périmés.
-
Vérifiez la réactivité du module entre deux instantanés :
if (dev.probe()) {
Serial.println(F("alive"));
}
-
Vérification directe du drapeau —
dev.isPeriodValid()effectue une lecture d'un seul octet sans effet de bord. -
Vérifiez la version du firmware —
dev.firmwareVersion()doit renvoyer0x04(v1.3, production actuelle) ; les firmwares plus anciens (0x01v1.0 /0x02v1.1 /0x03v1.2) affichent davantage d'instantanés périmés.
Le comptage des Wh diverge d'une référence
Ce que vous observez : dev.energy().wh(0) s'écarte, après plusieurs heures / jours de fonctionnement, de la lecture du compteur du distributeur ou d'un compteur de référence (Kill-A-Watt ou similaire).
Écartez d'abord le cas trivial
-
Calibration du capteur de courant : assurez-vous que
setSensorClass()etsetCTModel()ont été appelés avec le bon modèle de CT (voir 03 · Choix du capteur de courant). Sans cela, le courant efficace est calculé avec le plancher par défaut et la valeur de puissance sera systématiquement biaisée. -
Instantanés périmés écartés : si
dev.energy().wh()est systématiquement inférieur à la référence, il peut s'agir d'intervalles manqués — un instantané est revenu périmé, la bibliothèque a protégé contre le double comptage, mais la mesure de l'intervalle a été perdue. Vérifiez la cadence (voir ci-dessus). -
Dérive de l'horloge maître :
millis()est fiable en soi. Mais si le maître entre en veille profonde sans conserver l'horloge RTC, l'intervalle entre l'instantané précédent et le suivant est perdu. Activez la RTC pour ces scénarios.
Précision de l'accumulateur selon la plateforme
| Plateforme | Type de l'accumulateur |
|---|---|
| ESP32 / ESP8266 / STM32duino / SAMD / RP2040 | double 64 bits |
| Arduino AVR (Uno, Mega, Nano) | float 32 bits (chaîne d'outils) |
L'intégration côté maître n'ajoute aucune erreur propre au-delà de la précision de puissance active du module.
Pour AVR sur les installations de longue durée, réinitialisez périodiquement l'accumulateur et enregistrez le total à long terme dans votre propre stockage persistant :
// Once a day in the MQTT-publish hook
mqtt.publish("rbamp/wh_daily", String(dev.energy().wh(0)));
dev.energy().reset(0);
snap.latch_ms diffère de la période réelle
latch_ms est une minuterie de diagnostic du module ; ne l'utilisez pas pour l'énergie — utilisez l'horloge du maître (master_dt_ms).
RB_ERR_STALE à chaque lecture — le maître conserve automatiquement l'ancre
Ce que vous observez : dev.readPeriodSnapshot(snap) renvoie périodiquement false avec lastError() == RB_ERR_STALE. (Voir aussi la section « Les instantanés de période sont toujours périmés » ci-dessus.)
Gestion canonique de dt : sur une lecture périmée, la bibliothèque Arduino ne remet PAS à zéro son ancre interne _last_latch_ms. La lecture valide suivante obtient un master_dt égal à l'intervalle complet depuis l'instantané réussi précédent — c'est-à-dire qu'il couvre à la fois la période « perdue » périmée et la période courante. Le firmware conserve l'accumulateur avg_p à travers un instantané vide (persistance côté firmware) : sur l'instantané valide suivant, c'est déjà la valeur moyennée sur tout l'intervalle. L'intégration des Wh reste exacte — ni double comptage, ni sous-comptage.
Aucun traitement particulier des instantanés périmés n'est nécessaire dans le code du maître : la bibliothèque fait tout correctement, automatiquement. Ignorez simplement RB_ERR_STALE s'il est rare ; s'il est fréquent, diagnostiquez la cadence (section ci-dessus).
Le croquis ESP32 se bloque après quelques minutes
Ce que vous observez : le croquis sur ESP32 démarre correctement, puis passe en blocage / boucle de redémarrage / délai du WDT après 1 à 30 minutes.
Wire se bloque sur un bus marginal — protection à trois niveaux
Ce que vous observez précisément : un croquis sur ESP32 (cœur Arduino-ESP32) interroge rbAmp correctement pendant plusieurs minutes, puis reste « mort » au milieu d'un appel dev.readAll(...) / dev.readVoltage() / fleet.pollAll(). Si le chien de garde de tâche est activé, il détecte le blocage ; sinon le croquis cesse simplement de répondre. La trace décodée se termine à la fonction i2c_ll_is_bus_busy (le pilote IDF i2c_master, fichier i2c_master.c:526, attente de bus occupé avant émission).
Ce qui se passe : le Wire d'Arduino-ESP32 encapsule le même pilote IDF i2c_master que les projets ESP-IDF natifs. Sur un bus limite (résistances de rappel faibles, longues pistes, EMI, interférences ZC), SDA/SCL peuvent brièvement « coller » dans un état indéfini. Avant chaque transaction, l'i2c_master IDF tourne dans la boucle i2c_ll_is_bus_busy, en attendant que le bus se libère — cette attente est NON bornée par le délai I²C de la bibliothèque. Si l'occupation du bus dure plus longtemps que l'attente sans laisser la main aux autres tâches, la tâche IDLE de FreeRTOS n'obtient pas le CPU et tout le croquis se bloque.
Ce n'est pas un « artefact réservé au débogueur ». Validé au banc (même harnais matériel et même charge) :
| Configuration du bus | Taux de blocage |
|---|---|
| 2 résistances de rappel faibles du module + NRST du débogueur branché | ~1 blocage / 2.1 min |
| 1 résistance de rappel faible sur le module, pas de débogueur | ~1 blocage / 3.3 min (≈ 12 blocages par heure) |
| + résistance de rappel externe de 4.7 kΩ sur le SDA/SCL du DUT | 0 blocage (test de 12 min, 1300 cycles, 0 redémarrage, 0 déclenchement du WDT) |
La corrélation est claire : le correctif d'intégrité du bus supprime complètement le blocage. La logique de la bibliothèque n'est pas en cause : RbAmpFleet::pollAll(), les modules MISS individuels et les compteurs de reprises / de cohérence sont restés propres à chaque exécution, jusqu'au blocage lui-même.
Atténuation en trois couches (appliquez les trois couches) :
-
Résistance de rappel externe (~4.7 kΩ) sur SDA et SCL vers 3.3 V en un seul point du bus. Les résistances de rappel internes à l'ESP32 (~45 kΩ) sont trop faibles pour un bus multi-modules de longueur réelle, alors que les 4.7 kΩ intégrées aux modules, en parallèle, deviennent trop fortes. Sur un tel bus, coupez celles intégrées sur tous les modules sauf un (ou sur tous — vous vous fiez alors uniquement aux externes). Voir 04 · Câblage, section « Bus multi-modules — la topologie principale ».
-
N'exécutez pas une version de production avec le débogueur NRST connecté. En session de débogage, la ligne de réinitialisation peut maintenir SDA/SCL dans un état indéfini lors du détachement/rattachement, provoquant un blocage du bus à la transaction suivante. Sur une version terrain (sans débogueur), ce facteur disparaît.
-
WDT de tâche au niveau de l'application sur la tâche d'interrogation — défense en profondeur. Si, pour une raison quelconque, les résistances de rappel restaient marginales, ou si une autre cause de blocage survenait, le WDT redémarrera le croquis. Test de 12 min au banc : le WDT a détecté et récupéré les 12 blocages dans la configuration sans résistance de rappel externe. De bonnes résistances de rappel du bus — correctif terrain ; WDT applicatif — posture de rétablissement.
#include "esp_task_wdt.h"
void setup() {
// Layer 3 setup — defense-in-depth.
esp_task_wdt_config_t wdt_cfg = {
.timeout_ms = 8000, // 8 s with a large margin
.idle_core_mask = 0,
.trigger_panic = true, // on timeout — panic+reboot
};
esp_task_wdt_reconfigure(&wdt_cfg);
esp_task_wdt_add(NULL); // this task (loop) under WDT
// ... rest of the initialization ...
}
void loop() {
fleet.pollAll(snaps, status, RBAMP_FLEET_MAX_MODULES, n_ok);
// ... processing ...
esp_task_wdt_reset(); // "I'm alive" — every cycle
delay(200);
}
Ce qu'il NE FAUT PAS faire : n'essayez pas de contourner le problème avec un Wire.setTimeout() plus grand — il ne borne pas l'attente préalable de bus occupé, qui relève d'un autre chemin de code du pilote IDF. Le correctif est l'intégrité du bus (niveau 1) + un superviseur (niveau 3).
Délai de garde dans wifi_connect()
Cause : la boucle sans borne while (WiFi.status() != WL_CONNECTED) delay(500) déclenche le chien de garde de tâche après ~5 s (par défaut).
Correctif : une attente bornée avec un repli par redémarrage :
uint32_t t0 = millis();
while (WiFi.status() != WL_CONNECTED) {
delay(500);
if (millis() - t0 > 30000) { ESP.restart(); }
}
Le broker MQTT se déconnecte toutes les ~15 s
Cause : PubSubClient utilise par défaut un keepalive de 15 s, alors que mqtt.loop() n'est appelé que dans le chemin « lent » (une fois toutes les 60 s avec readPeriodSnapshot()).
Correctif : réglez le keepalive à 60 s et appelez mqtt.loop() à chaque passage de loop() :
mqtt.setKeepAlive(60);
void loop() {
if (!mqtt.connected()) mqtt.connect("rbamp-id");
mqtt.loop(); // every iteration, not once every 60 s
// ...rest of the logic, slowed down via millis()...
}
Échec de la négociation TLS (intégrations cloud)
Cause : le tas de l'ESP32 est insuffisant pour la négociation TLS (~30 ko requis). Cela se combine souvent avec le Wi-Fi + MQTT + les tampons — il ne reste alors pas plus de 20 ko.
Fix:
- Réduisez
setBufferSize()du client MQTT au minimum. - Utilisez
WiFi.mode(WIFI_STA)(et nonWIFI_AP_STA). - Désactivez le BLE :
btStop()danssetup().
Si ESP.getFreeHeap() affiche < 25 ko avant client.connect(), la négociation TLS échouera très probablement.
setSensorClass() / setCTModel() renvoie RB_ERR_PARAM
Ce que vous observez : l'un des appels de configuration renvoie false, avec lastError() == RB_ERR_PARAM.
Causes possibles :
-
setCTModel()appelé avantsetSensorClass(). Classe de capteur d'abord, puis modèle — voir 03 · Sélection du capteur de courant et 09 · Référence de l'API § Configuration du capteur. -
Code de modèle invalide — pour la classe
Sct013, l'ensemble valide est{1, 2, 3, 4, 5, 6, 7}(les codes 5 et 7 sont le SCT-013-100 et le SCT-013-060). Pour les autres classes, voir le tableau des ensembles acceptés par classe dans 03 · Sélection du capteur de courant. Les codes qui ne correspondent pas à la classe renvoientRB_ERR_PARAM(garde côté bibliothèque avant le bus) ouDEV_ERR_PARAM(côté firmware, si le YAML passe au travers). -
Indice de canal invalide dans la forme par canal
setCTModel(channel, code)— il doit être <dev.channels(). Un canal égal ou supérieur àRBAMP_MAX_CHANNELS(7) n'est jamais exposé et renvoie aussiRB_ERR_PARAM. -
Le module a rejeté le code — un code présent dans le registre mais que le module n'accepte pas est refusé par le module ; le canal conserve son modèle précédent.
Si l'appel renvoie plutôt false avec RB_ERR_MODE, le module est d'une classe appariée en usine (WiredCT / BuiltinCT) — il a été livré et calibré avec son capteur et les setters ne le réécrivent pas. Le réappariement en service se fait par setCTModelChForce().
Comportement attendu, pas une panne :
-
Définir une classe ou un modèle que le module détient déjà ne fait rien (
true, aucune écriture sur le bus, aucun cycle de flash). -
Définir un modèle de CT redémarre le module sur le firmware BASIC jusqu'à 1.4.19 avec la classe SCT-013 (environ une seconde, bloquant). Les lectures sont indisponibles pendant ce temps ; la bibliothèque relit ensuite la correction de calibre.
-
Après le changement de modèle SCT-013, les lectures de courant, de puissance et d'énergie suivent automatiquement le nouveau calibre (le facteur de puissance et la tension ne sont pas affectés).
dev.sctRating(ch, r)affiche le statut par canal ; s'il signaleUnexpectedGainouUnknown, aucune correction n'est appliquée (échelle 1).
Notes sur les modules STD (STANDARD)
La ligne STD utilise le même câblage I²C que BASIC (voir 04 · Câblage) ; dev.begin() la détecte et dev.line() indique laquelle vous possédez. Points propres à STD :
-
RB_ERR_NOT_IMPLEMENTEDsur un appelstd*,readReactivePower()oureadApparentPower()— le module connecté est un BASIC (vérifiezdev.line()). Inversement, les appels réservés au BASIC (factoryReset(), General-Call, aides aux étiquettes,readCapability(),readCommitSeq()) le renvoient sur un module STD. -
Une fonction signale « non disponible » — l'énergie à micro-résolution (
RbAmpStdEnergy::fine == false), le courant de démarrage pour l'énergie (RB_ERR_NOT_IMPLEMENTED), les angles de phase de tension (angle_valid == false) et la séquence de phases (NotAvailable) dépendent de la version de l'image du module : ils exigent une image d'au moins0x0001007B. Lisez-la avecdev.stdReadImageVersion(); sur une image plus ancienne, la valeur n'est pas disponible, et non fausse. -
L'angle de tension et la séquence de phases restent « non disponibles » sur une image récente — ils exigent que toutes les entrées de tension soient alimentées et mesurables, et un module à trois tensions pour la séquence de phases.
-
Les lectures d'instantané de période reviennent vides (
RB_ERR_STALE) après un redémarrage du module — attendu : l'armement de l'instantané réside dans la RAM du module. La bibliothèque réarme la banque et écarte cette seule période ; redémarrez votre propre ancredt. Attendez au moins 300 ms entrestdLatch()etstdReadLatch(). -
Aucun enregistrement d'historique — le module n'enregistre l'historique que lorsque son horloge est réglée. L'horloge est perdue à chaque redémarrage du module : appelez
dev.stdSetTime()aprèsbegin()et chaque fois questdReadHealth()signaletime_valid == false. -
Une commande renvoie
RB_ERR_PARAM— sur STD, le verdict de chaque commande est relu ; le module a rejeté la valeur et n'a pas changé. -
Une sauvegarde renvoie
RB_ERR_NOT_READY— le module limite la fréquence de ses écritures dans son stockage ; la bibliothèque réessaie déjà une fois après 5 s.
Gestion des erreurs : dernière écriture de REG_ERROR + EVENT_FLAGS.bit3 durable (v1.3)
Comportement v1.3 : REG_ERROR (0x02) est le résultat de la dernière écriture, et NON persistant. À chaque écriture de registre, le firmware met reg_error = ERR_OK ; une écriture ultérieure sans rapport efface l'erreur précédente.
Signal d'erreur durable = EVENT_FLAGS (0x2A) bit3 — collant (W1C), levé immédiatement sur toute écriture ou commande rejetée.
Schéma 1 — capture ponctuelle après une opération (si le résultat de cette opération précise importe) :
bool ok = dev.saveUserConfig();
uint8_t dev_err = dev.readReg(0x02); // IMMEDIATELY, before the next write
Schéma 2 — surveillance durable des erreurs (canonique) :
uint8_t event_flags = dev.readReg(0x2A);
if (event_flags & (1 << 3)) {
uint8_t last_err = dev.readReg(0x02);
// handle
dev.writeReg(0x2A, (1 << 3)); // W1C clear bit3
// or dev.clearError();
}
⚠ REG_ERROR est le résultat de la dernière écriture, non collant. La durabilité est assurée par EVENT bit3.
⚠ bit3 est un canal asynchrone, non destiné à la validation synchrone d'écriture : sur une écriture rejetée, bit3 est levé avec un délai par rapport au moment où la transaction I²C revient. Ne scrutez pas bit3 immédiatement après une écriture pour vérifier son résultat — pour le résultat de votre propre écriture, utilisez le Motif 1 (capture ponctuelle de lastError() juste après l'opération) ou le code de retour du setter. bit3 sert à la surveillance de longue durée de faits asynchrones (durée d'exécution, chemin de commande), pas à valider une opération que vous venez d'effectuer.
lastError() et readLastError() — deux canaux différents, pas des synonymes
Deux fonctions aux noms proches, mais avec une sémantique totalement différente :
lastError() |
readLastError(out) |
|
|---|---|---|
| Ce qu'il renvoie | Code RB_ERR_* mis en cache par la bibliothèque lors de l'appel précédent |
Une seule lecture sur le fil du registre REG_ERROR (0x02) de l'appareil |
| Une opération I²C ? | Non — simple lecture mémoire | Oui — une seule transaction de lecture |
| Sémantique | Résultat de la validation côté bibliothèque (garde client, état des nouvelles tentatives, etc.) | Résultat côté appareil de la dernière écriture (mnémonique DEV_ERR_*) |
| Quand elle est mise à jour | Après chaque méthode de la bibliothèque | Après chaque écriture acceptée par le bus sur l'appareil |
| Exemple de valeur | RB_ERR_PARAM après une garde côté client |
0xFE (DEV_ERR_PARAM) après une écriture rejetée sur l'appareil |
| Exemple de discordance | lastError() == RB_ERR_PARAM (le setter l'a bloqué avant le bus) |
readLastError() → 0x00 (rien n'a atteint l'appareil) |
Quand utiliser chacune :
-
lastError()— pour la logique applicative, l'analyse des résultats côté bibliothèque (reprise, repli, classification des erreurs), sans surcoût I²C. -
readLastError()— lorsque vous voulez le code de cause étendu côté appareil (par exempleDEV_ERR_PARAM (0xFE)ouDEV_ERR_NOT_READYouDEV_ERR_FLASH_PARAMS_BAD (0xFB)) sur le canal B (rejet côté DUT). Voir le § « modèle d'erreur v1.3 — deux canaux indépendants » dans 09 · Référence API.
La distinction est particulièrement importante lors du débogage du canal A (garde côté client) : le setter renvoie false + lastError() == RB_ERR_PARAM, mais readLastError() == 0x00 — parce que la bibliothèque l'a bloqué avant l'opération sur le bus, et que REG_ERROR sur l'appareil n'a pas été touché.
Mise en garde : DEV_ERR_CLONE (0xF9) n'est pas effacé par CMD_CLEAR_ERROR — c'est une sentinelle anti-clonage (seul un redémarrage ou une réinitialisation d'usine l'efface).
Un module fraîchement flashé affiche 0xFB au premier démarrage (NORMAL)
Ce que vous observez : un module fraîchement flashé, à son premier démarrage, affiche REG_ERROR = 0xFB (DEV_ERR_FLASH_PARAMS_BAD) + bit3 de EVENT.
Cause : la page des paramètres n'est pas initialisée → les valeurs d'usine sont chargées. C'est NORMAL pour un module vierge, pas fatal.
Correctif : configurez sensor_class + ct_model + (facultativement) l'adresse, puis dev.saveUserConfig(). Après une SAUVEGARDE réussie → REG_ERROR = 0x00, bit3 à zéro.
commitAddressChange() renvoie RB_ERR_TIMEOUT
Ce que vous observez : prepareAddressChange() a réussi, mais commitAddressChange() renvoie false, lastError() == RB_ERR_TIMEOUT.
Cause : la fenêtre d'état armé (5 s après prepareAddressChange) a expiré. Le Wi-Fi, MQTT ou toute E/S bloquante entre prepare et commit est la principale cause de l'expiration de la fenêtre. dev.probe() ne vous aidera pas ici (le module répond ; le problème est dans la machine d'état).
Que faire : rappelez prepareAddressChange() immédiatement, et, dans la même itération de loop(), sans appel réseau entre les deux, appelez commitAddressChange().
✅ REG_I2C_ADDRESS (0x30) lit désormais l'adresse ACTIVE au démarrage (v1.3). Après un redémarrage suivant le commit, la lecture de 0x30 affiche la nouvelle adresse active. Pour la vérification la plus fiable d'un commit d'adresse en deux phases, tentez une lecture sur la nouvelle adresse (elle doit être ACKée sur le bus). Après une écriture de l'hôte (préparation), le registre renvoie le candidat préparé jusqu'à CMD_COMMIT_ADDR + réinitialisation — c'est le comportement prévu.
Pour en savoir plus sur le commit d'adresse en deux phases, voir 09 · Référence de l'API et 04 · Câblage.
Lectures en échec pendant la commutation de charges à relais (transitoires électromagnétiques)
Ce que vous observez : dev.readVoltage() / dev.readCurrent() renvoient périodiquement NAN, lastError() == RB_ERR_NACK ou RB_ERR_IO — mais uniquement pendant une commutation active d'un relais ou d'une charge inductive sur la même installation. En régime établi, les lectures sont fiables.
Cause : pendant la commutation de relais (charge de 5 A), les perturbations électromagnétiques font échouer environ 67 % des transactions I²C (environ 8/12 dans la mesure matérielle). Le bus se rétablit seul, aucun blocage ne se produit, aucun module n'est perdu — mais la lecture en cours échoue.
Correctif — nouvelle tentative au niveau de l'application :
float robust_read_voltage(RbAmp& dev) {
for (int attempt = 0; attempt < 5; attempt++) {
float v = dev.readVoltage();
if (!isnan(v)) return v;
delay(20); // a short pause before the retry
}
return NAN;
}
⚠ La récupération de bus côté bibliothèque ne suffit pas seule : lorsqu'une perturbation électromagnétique chevauche la fenêtre de reprise du pilote, une reprise explicite au niveau applicatif avec une pause est nécessaire.
Alternative : si le maître voit les événements de commutation de relais, retardez les lectures d'environ 50-100 ms après la commutation.
Tableau récapitulatif des codes d'erreur
dev.lastError() renvoie l'un de ces codes après chaque appel public de l'API. RbAmp::errorString(code) renvoie une chaîne lisible par l'humain.
| Code | Chaîne | Quand | Où regarder |
|---|---|---|---|
RB_OK (0) |
"OK" | succès | — |
RB_ERR_IO (-1) |
"Échec du transport I2C" | le pilote de bus a renvoyé un code autre que OK | câblage, alimentation, résistances de rappel |
RB_ERR_NACK (-2) |
"NACK — appareil absent ou occupé" | reprises épuisées | Section « Le module ne répond pas sur I²C » |
RB_ERR_TIMEOUT (-3) |
"Délai d'attente du bus dépassé" | la fenêtre waitReady / waitDataReady / commitAddressChange a expiré |
Section « commitAddressChange() renvoie RB_ERR_TIMEOUT » |
RB_ERR_NOT_READY (-4) |
"Appareil non prêt" | le module n'est pas prêt / il n'existe aucun enregistrement d'historique de ce type / rien n'est armé / rien ne répond à la nouvelle adresse | les remarques STD ci-dessus |
RB_ERR_STALE (-5) |
"Instantané de période périmé" | le drapeau de période prête = 0 | Section « Les instantanés de période sont toujours périmés » |
RB_ERR_PARAM (-6) |
"Mauvais paramètre" | indice de canal invalide / code de modèle invalide / plage d'adresses invalide | Section « setSensorClass() / setCTModel() renvoie RB_ERR_PARAM » |
RB_ERR_MODE (-7) |
"Non autorisé dans le mode actuel du module (mode usine / voie de service requise)" | une opération réservée à l'usine, ou un setter de CT sur un module de classe WiredCT / BuiltinCT |
n'appelez pas d'opérations réservées à l'usine sur un firmware de production ; utilisez setCTModelChForce() uniquement pour un réappairage de maintenance |
RB_ERR_CHECKSUM (-8) |
"Échec de la vérification de valeur — somme de contrôle / signature / plage" | la vérification de valeur du module a échoué (STD : image firmware rejetée, CRC de charge utile, époque hors plage, anneau d'historique vide) | renvoyer la page / vérifier l'image |
RB_ERR_VERSION (-9) |
"Version de firmware non prise en charge" | REG_VERSION = 0 / 0xFF |
vérifiez le raccordement du module |
RB_ERR_NOT_IMPLEMENTED (-10) |
"Non implémenté sur ce firmware" | l'appel n'a pas d'équivalent sur la gamme détectée, ou l'image du module n'offre pas la fonction | dev.line(), dev.stdReadImageVersion() |
RB_ERR_NON_PHYSICAL (-11) |
"Valeur non physique (NaN/Inf/hors limites)" | le filtre de cohérence a rejeté un float | Section « Les lectures sautent ou renvoient NaN » |
Tableau récapitulatif des compteurs de diagnostic
Dans un essai d'endurance sain (12 h, croquis SoakMonitor), tous restent à zéro :
| Compteur | Régime établi | Réinitialisation |
|---|---|---|
dev.retryExhaustionCount() |
0 | dev.resetCounters() |
dev.sanityRejectCount() |
0 | dev.resetCounters() |
dev.lastError() après une lecture |
RB_OK (0) |
automatiquement au prochain appel |
| fraction d'instantanés périmés dans les instantanés de période | < 1 % | (cumulatif — pas de remise à zéro) |
Si l'un de ces compteurs est non nul en régime permanent, revenez à la section correspondante ci-dessus.
Débogage au niveau du bus avec un analyseur logique
Pour un débogage poussé, lorsque la bibliothèque ne peut plus vous dire ce qui se passe sur le fil, capturez SDA + SCL avec un analyseur logique (Saleae, DSLogic Plus, ou un modèle compatible Sigrok) :
- Fréquence d'échantillonnage ≥ 1 MS/s à 100 kHz I²C ; ≥ 4 MS/s à 400 kHz.
- Le décodeur I²C de Sigrok / Saleae affichera ACK / NACK sur chaque octet
- la phase d'adresse.
- Comparez les appels de votre croquis (
dev.readVoltage(), etc.) à la séquence d'octets attendue — elles doivent correspondre exactement. Les lectures par rafale (plusieurs octets dans une transaction via l'incrémentation automatique d'adresse) sont prises en charge. Les écritures ne sont PAS à incrémentation automatique — chaque octet est une transaction distincte.
Si le comportement de la bibliothèque diverge de la capture, ouvrez un ticket avec le fichier de capture joint (.sal / .dsl / .csv).
Quand contacter le support
Si vous avez suivi la section pertinente ci-dessus et que le problème persiste, ouvrez un ticket :
github.com/rb-amp/rbamp-arduino/issues
Dans le ticket, incluez :
-
MCU hôte + version du cœur Arduino (par exemple ESP32-S3 sur Arduino-ESP32 3.0.4).
-
Version de la bibliothèque (
RbAmpdepuis le Gestionnaire de bibliothèques [Library Manager]). - Version du firmware du module —
dev.firmwareVersion(). - Croquis minimal qui reproduit le problème (~30 lignes de code).
-
dev.lastError()+dev.errorString(dev.lastError())+dev.retryExhaustionCount()+dev.sanityRejectCount()au moment de l'échec. -
(Si disponible) un fichier de capture de l'analyseur logique au moment de la panne.
Liens
- 05 · Démarrage rapide — votre premier croquis fonctionnel
-
09 · Référence API — l'API publique complète + mises en garde sur les méthodes publiques signalées WARNING
-
03 · Sélection du capteur de courant — tableau des modèles SCT-013, topologie à double TC pour une large plage dynamique, approches pour améliorer la sensibilité aux faibles courants
Source et problèmes : rb-amp/rbamp-arduino · cette page dans le dépôt : docs/10_troubleshooting.md (v1.6.2)