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

10 · Dépannage

Ce chapitre est organisé par les symptômes que vous observez, et non par classification interne des erreurs. Si vous êtes ici, quelque chose ne fonctionne pas correctement. Repérez votre symptôme dans la liste ci-dessous, allez à la section correspondante et suivez la procédure de diagnostic.

La plupart des problèmes de banc entrent dans trois catégories :

  1. Niveau bus — le module ne répond pas sur I²C, les lectures renvoient ESP_FAIL ou ESP_ERR_INVALID_RESPONSE.

  2. Niveau des données — le module répond, mais les valeurs sont fausses : zéros, valeurs étranges, mauvais signe.

  3. Niveau applicatif — la liaison est instable, le compteur Wh dérive, le projet se fige.

Raccourci pour les pressés : en régime établi, les fonctions publiques rbamp_* doivent renvoyer ESP_OK. Si vous voyez souvent ESP_FAIL ou ESP_ERR_INVALID_RESPONSE dans les journaux, passez directement à la section « Le module ne répond pas sur I²C » ci-dessous.

Arbre de décision de dépannage regroupé par symptôme.

Le module ne répond pas sur I²C

Ce que vous voyez : rbamp_begin(dev) renvoie ESP_FAIL ou ESP_ERR_INVALID_RESPONSE, ou les lectures RT remontent régulièrement ESP_FAIL dans votre code.

Étape 1 — Scan du bus

Vérifiez d'abord que le module est bien présent sur le bus. ESP-IDF v5.x fournit i2c_master_probe() précisément pour cela :

C
#include "driver/i2c_master.h"
#include "esp_log.h"

static const char *TAG = "i2c_scan";

void bus_scan(i2c_master_bus_handle_t bus) {
    ESP_LOGI(TAG, "Scanning...");
    for (uint8_t addr = 0x08; addr <= 0x77; addr++) {
        if (i2c_master_probe(bus, addr, /*xfer_timeout_ms=*/100) == ESP_OK) {
            ESP_LOGI(TAG, "Found 0x%02X", addr);
        }
    }
}

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 (voir 04 · Câblage pour les valeurs GPIO par défaut de chaque puce).

  • Les deux lignes ont une résistance de tirage vers 3.3 V (la carte du module intègre 4.7 kΩ — pour un seul module, les résistances externes ne sont pas nécessaires).

  • La broche d'alimentation du module reçoit en réalité 5 V (4.5–5.5 V).

  • Aucun autre maître (sonde de débogage, second ESP32) ne se trouve sur les mêmes lignes.

  • flags.enable_internal_pullup = true dans votre i2c_master_bus_config_t (s'il n'y a pas de résistances de tirage externes).

Si le module est trouvé mais à une adresse inattendue — quelqu'un l'a précédemment réadressé sur le banc. Mettez à jour le second argument de rbamp_new :

C
rbamp_new(bus, 0x52, &dev);   /* address from the bus scan */

Étape 2 — Schéma de NACK de référence sur ESP32

Si le balayage du bus trouve le module mais que rbamp_read_voltage(dev, 0, &v) renvoie périodiquement ESP_FAIL — c'est un motif de référence documenté : le pilote i2c_master d'ESP-IDF v5 présente des particularités avec rbAmp sur le firmware actuel (NACK fréquents à 100 kHz).

L'atténuation est déjà intégrée au composant (CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=3 par défaut, 50 kHz via CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000), mais sous forte charge le budget de reprises peut s'épuiser.

Ce qu'il faut faire via idf.py menuconfig → Component config → rbAmp client :

  1. Confirmez la valeur par défaut de 50 kHz :
Text
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000
  1. Augmentez le nombre de nouvelles tentatives en cas de forte charge :
Text
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=5
  1. Si nécessaire — augmentez le délai :
Text
CONFIG_RBAMP_I2C_TIMEOUT_MS=200
  1. Activez le niveau DEBUG pour l'étiquette rbamp pour le diagnostic :
Text
CONFIG_RBAMP_LOG_LEVEL_DEBUG=y

Vous pouvez aussi le faire à l'exécution — esp_log_level_set("rbamp", ESP_LOG_DEBUG).

Remarque

À propos des compteurs de reprises et de cohérence. Le composant exporte les accesseurs publics rbamp_retry_exhaustion_count(dev) et rbamp_sanity_reject_count(dev) — ils correspondent à dev.retryExhaustionCount() / dev.sanityRejectCount() de la version Arduino, en multiplateforme. Le schéma canonique instantané + différence pour la surveillance en production est décrit dans la section « Monitoring the counters » ci-dessous.

Flotte : un module s'est retrouvé dans excluded après rbamp_fleet_scan

Ce que vous voyez : rbamp_fleet_scan(fleet, ...) s'est exécuté et a renvoyé ESP_OK, mais rbamp_fleet_count(fleet) est inférieur au nombre de modules que vous avez physiquement connectés. rbamp_fleet_excluded_count(fleet)

Remarque

0 ; parcourez rbamp_fleet_excluded_addr(fleet, i) — chaque adresse exclue signifie « un module a été détecté mais NON ajouté à la flotte — un conflit est suspecté ».

Cause. Le détecteur de conflit repose sur deux signaux indépendants :

  • cohérence d'identité : HW_VARIANT ↔ carte de bits CAPABILITY sont incohérents — signe que deux modules physiques différents répondent à une même adresse (la réponse se « fusionne » partiellement).
  • Valeur en direct : à une même adresse, des lectures « en direct » incompatibles sont observées — par exemple un LABEL différent ou une variante instable.

Si au moins un des signaux se déclenche, l'adresse est exclue de la flotte, et la bibliothèque ne se fie PAS aux lectures de ce module. Si les deux signaux restent silencieux mais que les modules sont configurés à l'identique (même variante, même CT_MODEL, même LABEL), le détecteur ne saura pas les distinguer — c'est un cas indétectable physiquement (voir plus bas la discipline).

Sécurité

⚠ La détection est au mieux. Il est impossible de garantir que la flotte attrape deux modules identiques à une même adresse — c'est précisément pourquoi la discipline de provisionnement existe (voir la section suivante).

Quoi faire.

  1. Déconnectez physiquement tous les modules sauf un.
  2. Connectez les autres un à la fois, en relançant rbamp_fleet_scan après chacun. Le module après la connexion duquel un excluded apparaît est en conflit avec un module déjà connecté.

  3. Reprovisionnez le module en conflit sur une adresse libre via rbamp_provision(bus, new_address, ...) (il faut qu'il soit le seul sur 0x50 — voir la discipline de provisionnement ci-dessous).

  4. Après la réadressage, relancez rbamp_fleet_scan — excluded_count doit être égal à 0.

Flotte : rbamp_fleet_scan a renvoyé ESP_ERR_INVALID_STATE + flotte vide

Ce que vous voyez : rbamp_fleet_scan a renvoyé ESP_ERR_INVALID_STATE, rbamp_fleet_count(fleet) vaut 0. Aucun module n'a été ajouté à la flotte, alors qu'ils sont physiquement connectés.

Cause. Chien de garde de niveau 2 (wedge-canary) — la bibliothèque a effectué une vérification du bus « y a-t-il une réponse à une adresse qui ne doit pas répondre » (le canari). Si le canari a reçu un ACK, le bus n'est pas dans un état normal : soit du bruit électrique produit des ACK parasites, soit toutes les adresses sont « bloquées » à cause d'un verrouillage, soit il y a une erreur de topologie (plusieurs modules de même code en même temps, avec SDA/SCL maintenus à bas niveau). Dans cet état, vous ne pouvez faire confiance à aucun résultat de balayage — la flotte reste donc vide ; mieux vaut interrompre que d'effectuer une initialisation sciemment incorrecte.

Quoi faire.

  1. Coupez puis rétablissez l'alimentation de tout le bus (coupez le courant des modules quelques secondes, redémarrez l'ESP32). Cela efface les états bloqués.

  2. Connectez les modules strictement un à la fois, en exécutant rbamp_fleet_scan (mise en service d'un module seul) après chacun et en contrôlant le retour :

  3. ESP_OK + count=1 + excluded=0 → le bus est propre, le module est OK.

  4. ESP_ERR_INVALID_STATE persiste → vérifiez les résistances de tirage (voir la section i2c-hang ci-dessus — une résistance externe de 4.7 kΩ sur SDA/SCL est obligatoire).

  5. Une fois la mise en service d'un module seul réussie pour chacun individuellement, ajoutez-les tous au bus en même temps et relancez rbamp_fleet_scan. Si vous obtenez de nouveau INVALID_STATE, le problème est dans l'électrique du bus (longueur, interférences, résistance de tirage manquante), non dans les modules eux-mêmes.

Flotte : rbamp_provision a renvoyé une erreur

Ce que vous voyez : l'appel rbamp_provision(bus, desired_address, save_config, &out) ne s'est pas terminé avec ESP_OK. Selon le code renvoyé :

esp_err_t Ce qui s’est passé Que faire
ESP_ERR_NOT_FOUND Rien n'a répondu sur 0x50 (adresse par défaut d'usine) Confirmez que le module vierge est physiquement connecté et alimenté (VCC) ; vérifiez le câblage I²C (voir « Module doesn't respond over I²C »).
ESP_ERR_INVALID_STATE Un conflit a été détecté sur 0x50 ou l'adresse souhaitée est déjà prise Il y a plus d'un module vierge sur le bus ou l'adresse souhaitée est déjà prise par un autre module. Débranchez tous les modules « en trop » (voir ci-dessous).
ESP_ERR_TIMEOUT La commande de commit d'adresse a abouti, mais le module n'est pas apparu à la nouvelle adresse dans la fenêtre de démarrage Couper puis rallumer le module et réessayer. Si cela revient — vraisemblablement une opération flash incomplète (coupure pendant CMD_SAVE_USER_CONFIG ou CMD_COMMIT_ADDR, si bien que le bloc flash peut être partiellement écrit). Au démarrage suivant, le module renvoie REG_ERROR = 0xFB (ERR_FLASH_PARAMS_BAD), charge les réglages d'usine et réapparaît à 0x50. Reprovisionnez depuis le début ; si cela échoue encore, envoyez-le au service après-vente.
ESP_ERR_INVALID_ARG desired_addr est hors de la plage valide 0x08..0x77 Utilisez une adresse valide.
Sécurité

⚠ Discipline de provisionnement — UN SEUL module vierge à la fois, OBLIGATOIREMENT.

La cause la plus fréquente d'INVALID_STATE pendant le provisionnement est plus d'un module sur le bus à l'adresse d'usine 0x50. Les distinguer par I²C est physiquement impossible (drain ouvert câblé en ET — les deux modules ACK de façon identique, et la relecture des données revient « fusionnée »).

La règle est donc stricte (une exigence MUST normative, non une recommandation) : au moment de l'appel rbamp_provision, il doit y avoir exactement un module sur 0x50 (neuf, ou remis aux réglages d'usine via un outil de banc séparé). Pas de « je suis sûr que ces deux modules sont différents — je vais juste les séparer maintenant » — cela ne marchera pas : la collision apparaîtra plus tard, quand vous pensez déjà que la flotte est propre.

Procédure de reprise en cas de violation suspectée de la discipline : 1. Coupez l'alimentation de tous les modules. 2. Déconnectez physiquement tous les modules sauf celui « vierge » (celui que vous voulez réadresser). 3. Appelez rbamp_provision sur le bus à un seul module. 4. Ajoutez les autres modules un par un, en les provisionnant séparément.

Le courant lit zéro sur une charge en fonctionnement

Ce que vous voyez : rbamp_read_current(dev, 0, &i) renvoie ESP_OK mais i = 0.000 (ou une valeur très faible), alors qu'un vrai consommateur est allumé (bouilloire, lampe, fer). rbamp_read_power_factor(dev, 0, &pf) peut afficher une valeur étrange (nan / 0 / ±1) — c'est une conséquence ; la cause se trouve dans le courant.

Procédure de diagnostic

  1. Vérifiez que la classe de capteur et le modèle de CT sont configurés :
C
esp_err_t err = rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013);
if (err != ESP_OK) {
    ESP_LOGE(TAG, "set_sensor_class: %s", rbamp_err_to_str(err));
}
err = rbamp_set_ct_model(dev, 3);   /* or your model */
if (err != ESP_OK) {
    ESP_LOGE(TAG, "set_ct_model: %s", rbamp_err_to_str(err));
}

Sans ces deux appels, les coefficients d'étalonnage ne sont pas chargés et le courant reste toujours à zéro. Cette étape se fait une seule fois à la première installation — le choix est enregistré dans la flash du module.

Remarque

Piège concernant RBAMP_SENSOR_UNSET. Si vous appelez par erreur rbamp_set_sensor_class(dev, RBAMP_SENSOR_UNSET) — la fonction renvoie ESP_OK, mais réinitialise en pratique la configuration de classe. Un rbamp_set_ct_model*() ultérieur renverra ESP_ERR_INVALID_STATE. La solution est de rappeler rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013), puis rbamp_set_ct_model().

  1. Vérifiez que le modèle de CT correspond à la charge. Une grande pince CT (par exemple SCT-013-100, 100 A) sur une petite charge (une lampe de 50 W ≈ 0.2 A) produit un signal à la limite du plancher de bruit, et les lectures seront nulles. Choisissez le plus petit modèle de CT qui couvre votre courant maximal attendu. Le tableau complet se trouve dans 03 · Choix du capteur de courant.

Si vous avez un module multicanal (UI2 / UI3 / UI5 / UI7) et que vous voulez voir à la fois les petites charges et les pics, envisagez un motif à double CT : une petite pince (par exemple SCT-013-005) sur un canal dédié pour la plage basse + une grosse (SCT-013-030/100) sur un autre canal pour la plage haute ; le maître choisit la valeur selon un seuil. Ce motif est traité dans 03 · Choix du capteur de courant, section « Dual-CT topology » (topologie à double CT).

  1. Vérifiez le sens 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 », rbamp_read_current() donne la bonne valeur en valeur absolue, mais rbamp_read_power() donne une valeur négative sur une charge consommatrice. Confirmation : rbamp_read_power_factor() affichera exactement −1.0 sur une charge résistive (au lieu de +1.0). Correctif : soit remonter physiquement la pince (la désserrer, la tourner pour que la flèche soit dans le bon sens, la remettre en place), soit inverser le signe côté maître.

Si les trois étapes réussissent mais que le courant reste nul

Alors le signal à l'entrée du module est réellement sous le plancher de bruit. Vérifiez :

  • Le courant circule-t-il réellement — mesurez avec un multimètre (pince DC / pince AC) sur le même fil.

  • La pince est-elle intacte — au connecteur de la pince, il doit y avoir une tension alternative proportionnelle au courant (quelques millivolts pour les charges domestiques).

  • Pincez-vous le bon fil — le conducteur de phase (ligne), et seulement celui-là (jamais tout le câble).

Les lectures sautent ou renvoient ESP_FAIL

Ce que vous voyez : rbamp_read_voltage(dev, ...) ou rbamp_read_current(dev, ...) renvoie périodiquement ESP_FAIL. La valeur dans *out est indéfinie après une erreur.

ESP_FAIL émis par le composant couvre deux classes de problème :

  • NACK après épuisement des nouvelles tentatives — la liaison est instable.
  • Le filtre de cohérence a rejeté la valeur — un flottant NaN / Inf / |x| > 10000 est arrivé par le bus (une valeur manifestement non physique).

L'API ESP-IDF ne distingue pas ces cas par des codes esp_err_t distincts (contrairement à RB_ERR_NACK / RB_ERR_NON_PHYSICAL d'Arduino) — les deux renvoient ESP_FAIL. Vous pouvez les départager par les compteurs de diagnostic (voir la section « Surveiller les compteurs » ci-dessous). Les deux symptômes se traitent de la même façon :

  1. Confirmez la valeur par défaut de 50 kHz + portez les tentatives à 5 via Kconfig — voir la section précédente.

  2. Réduisez la densité de charge sur le bus — si votre boucle effectue de nombreuses lectures d'un seul octet, essayez rbamp_read_all() (une seule transaction I²C au lieu d'environ 13).

  3. Vérifiez CONFIG_RBAMP_I2C_TIMEOUT_MS — si l'appareil répond plus lentement que d'habitude (câble long, mauvais contact), augmentez le délai d'attente.

  4. Activez la journalisation DEBUG via CONFIG_RBAMP_LOG_LEVEL_DEBUG=y ou esp_log_level_set("rbamp", ESP_LOG_DEBUG) — le composant affichera les détails du cycle de reprise et des rejets de cohérence sous l'étiquette "rbamp".

Surveiller les compteurs

Le composant exporte deux compteurs monotones publics pour la surveillance de l'état du bus en production :

C
uint32_t rbamp_retry_exhaustion_count(rbamp_handle_t dev);
uint32_t rbamp_sanity_reject_count(rbamp_handle_t dev);

retry_exhaustion_count est incrémenté lorsqu'une transaction d'un seul octet a épuisé le budget CONFIG_RBAMP_NACK_RETRY_ATTEMPTS et renvoyé ESP_FAIL. sanity_reject_count est incrémenté lorsque le filtre de cohérence rejette un flottant (!isfinite(x) || |x| > 10000).

Le motif canonique consiste à prendre un instantané + la différence une fois toutes les 60 secondes, pour obtenir un « taux d'événements par minute » :

C
uint32_t prev_retry  = rbamp_retry_exhaustion_count(dev);
uint32_t prev_sanity = rbamp_sanity_reject_count(dev);
/* ...60 s of normal operation (do N rbamp_read_* calls)... */
uint32_t now_retry  = rbamp_retry_exhaustion_count(dev);
uint32_t now_sanity = rbamp_sanity_reject_count(dev);
uint32_t retry_delta  = now_retry  - prev_retry;
uint32_t sanity_delta = now_sanity - prev_sanity;
if (retry_delta > THRESHOLD || sanity_delta > THRESHOLD) {
    ESP_LOGW(TAG, "bus health: retry+%u sanity+%u per minute",
             retry_delta, sanity_delta);
}

Les seuils d'alarme dépendent de la charge de travail. Pour un motif de soak dense (comme le SoakMonitor d'Arduino — ~70 octets par cycle, une fois toutes les 5 minutes) :

  • retry_delta > 1/heure — bruit bénin, peut être ignoré.
  • retry_delta systématiquement > 5/heure — à examiner (mauvais contacts, capacité du bus, dérive thermique des résistances de rappel).

  • sanity_delta > 0 en régime établi — presque toujours le signe d'interférences électromagnétiques sur le bus ou d'une régression du firmware.

Les compteurs ne font qu'augmenter (jamais de remise à zéro) — pour les remettre à zéro, il faut recréer le handle via rbamp_del(dev) + rbamp_new(...). C'est voulu : vous ne perdez pas l'historique à cause des courses entre « remise à zéro » et « lecture dans l'enregistreur ».

Remarque

Multiplateforme, ces compteurs ont la même sémantique que dev.retryExhaustionCount() / dev.sanityRejectCount() de la version Arduino — mêmes noms (snake_case au lieu de camelCase), mêmes seuils fonctionnant de la même façon.

Le facteur de puissance semble faux

Ce que vous voyez : rbamp_read_power_factor(dev, 0, &pf) renvoie ESP_OK mais pf 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 lorsque I = 0

PF est défini par P / (U × I). Avec un courant nul I=0, le calcul n'est pas défini. La valeur renvoyée dépend du firmware (elle peut valoir 0 ou une valeur proche de zéro) — c'est normal tant que le courant est réellement nul. Dès qu'un courant apparaît, un PF valide apparaît. Le filtre de cohérence du composant ne rejette pas cette valeur (donc le compteur sanityRejectCount équivalent dans IDF n'augmente pas) — c'est une mesure valide d'une grandeur indéfinie, et non un artefact de liaison.

PF strictement −1.0 sur une charge purement consommatrice

La pince est montée « à l'envers » — la flèche pointe à l'opposé du sens du courant, vers la charge. Correctif : soit remonter la pince correctement, soit gérer le signe côté maître (p = -p; pf = -pf; si vous savez que la charge ne peut pas être un onduleur PV).

Le FP oscille entre +0.3 et +0.7 sur une charge résistive

  • Cause possible : la pince CT est sur un fil d'une phase différente de celle à laquelle l'entrée U du module est raccordée. Dans un tableau de distribution à plusieurs phases, il est facile de pincer par erreur la mauvaise phase — un déphasage de 120° ou 180° entre U et I donne exactement ces valeurs de facteur de puissance. La solution est de monter le module de sorte que l'entrée U et la pince soient sur la même phase.

  • Alternative : la charge n'est pas vraiment purement résistive. Refaites le test avec une charge connue résistive (une bouilloire électrique à pleine puissance).

Les instantanés de période sont toujours stale

Ce que vous voyez : rbamp_read_period_snapshot(dev, ...) renvoie ESP_ERR_INVALID_RESPONSE, ou *out.valid == false. Cela signifie que le module n'a pas fini d'intégrer la période précédente au moment de la lecture suivante.

Le composant évite le double comptage des Wh : sur une lecture périmée, il enregistre un horodatage maître (esp_timer_get_time()), et l'instantané réussi suivant couvre une seule période, non 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 cadence

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

  2. Vérifiez la réactivité du module entre deux instantanés :

C
if (rbamp_probe(dev) == ESP_OK) {
    ESP_LOGI(TAG, "alive");
}
  1. Vérifiez directement le drapeau — rbamp_is_period_valid() effectue une lecture d'un octet sans effet de bord :
C
bool valid;
if (rbamp_is_period_valid(dev, &valid) == ESP_OK && valid) {
    /* avg_p[] can be read */
}
  1. Vérifiez la version du firmware — rbamp_firmware_version(dev) >= 0x02 produit moins d'obsolescences que 0x01. Le firmware canonique actuel est 0x04 (v1.3) ; 0x01 = v1.0, 0x02 = v1.1, 0x03 = v1.2.

Cas particulier — réveil de veille profonde

Si vous utilisez un schéma de deep-sleep, l'appel par défaut rbamp_read_period_snapshot() juste après rbamp_begin() sera toujours périmé (ou donnera des valeurs proches de zéro) — begin() effectue un instantané approximatif qui réinitialise l'accumulateur du firmware. Le schéma canonique utilise skip_latch=true + l'horodatage RTC sauvegardé par le maître lui-même — voir 06 · Exemples, scénario 9.

La comptabilisation Wh dérive par rapport à une référence

Ce que vous voyez : rbamp_energy_wh(dev, 0) après plusieurs heures / jours de fonctionnement diverge du relevé du compteur du fournisseur ou d'un compteur de référence (Kill-A-Watt, etc.).

Écartez d'abord le cas trivial

  1. Calibration du capteur de courant : confirmez que rbamp_set_sensor_class() et rbamp_set_ct_model() ont été appelées avec le bon modèle de CT (voir 03 · Choix du capteur de courant). Sans cela, le courant efficace est calculé avec un plancher par défaut et la valeur de puissance sera faussée systématiquement.

  2. Instantanés périmés abandonnés : si rbamp_energy_wh() est systématiquement en dessous de la référence, ce sont peut-être des intervalles manqués — l'instantané est arrivé périmé, le composant a empêché le double comptage, mais la mesure de l'intervalle a été perdue. Vérifiez la cadence (voir ci-dessus).

  3. Dérive de l'horloge maître : esp_timer_get_time() est fiable en soi. Mais si le maître passe en veille profonde sans sauvegarder la RTC, l'intervalle entre l'instantané précédent et le suivant est perdu. Utilisez le motif RTC_DATA_ATTR du scénario 9 pour les scénarios de veille profonde.

Précision de l'accumulateur

L'accumulateur Wh du handle est stocké sous forme de double 64 bits.

Si vous avez compilé le composant avec CONFIG_RBAMP_DISABLE_ENERGY=y, le stockage d'énergie et l'API sont entièrement retirés du binaire. Dans ce cas, vous devez tenir votre propre compteur Wh dans le code utilisateur.

snap.latch_ms — diagnostic, non destiné à l'énergie

latch_ms est un compteur de diagnostic du module ; ne l'utilisez pas pour l'énergie — utilisez l'horloge du maître.

Le projet ESP32 se fige après quelques minutes

Ce que vous voyez : un projet ESP32 démarre normalement, puis passe en blocage / boucle de redémarrage / expiration du chien de garde après 1 à 30 minutes.

Blocages de i2c_master d'IDF sur un bus marginal — atténuation en trois couches

Ce que vous voyez concrètement : un projet ESP32 (v1.0 classique, IDF v5.4.1, nouveau pilote i2c_master) interroge rbAmp correctement pendant plusieurs minutes, puis se « fige » au milieu d'un appel rbamp_*_read_* ou de rbamp_fleet_poll_all. Le chien de garde de tâche (s'il est activé) détecte le blocage ; sinon le projet cesse simplement de répondre. La trace décodée se termine à i2c_ll_is_bus_busy (fichier i2c_master.c:526, attente de bus occupé avant émission).

Ce qui se passe : sur un bus marginal (résistances de tirage faibles, pistes longues, EMI, interférences des fronts de passage à zéro), SDA/SCL peuvent momentanément « se bloquer » dans un état indéterminé. Avant chaque transaction, le i2c_master de l'IDF tourne dans la boucle d'attente i2c_ll_is_bus_busy en attendant que le bus se libère — cette attente n'est PAS bornée par le paramètre xfer_timeout_ms. Si le bus reste occupé plus longtemps que ne peut tourner l'attente sans céder la main aux autres tâches, la tâche IDLE de FreeRTOS n'obtient jamais le CPU et l'application entière se bloque.

Ce n'est pas un « artefact réservé au débogueur ». Validé sur banc : sur le même montage matériel et la 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 tirage externe de 4.7 kΩ sur SDA/SCL du DUT 0 blocages (essais de 5 min + 25 min, 0 redémarrage)

La corrélation est claire — une correction de l'intégrité du bus supprime entièrement le blocage. La logique de la bibliothèque n'est pas en cause : la mécanique par module (fleet_poll_all, MISS/désynchronisation, contrôles de fuite) est restée propre dans chaque essai jusqu'au blocage.

Atténuation en trois couches (appliquez les trois couches) :

  1. Résistance de tirage externe (~4.7 kΩ) sur SDA et SCL vers 3.3 V en un seul point du bus. Les résistances de tirage internes à l'ESP32 (~45 kΩ) sont faibles pour un bus multi-module de longueur réelle, tandis que les résistances de 4.7 kΩ intégrées aux modules, mises en parallèle, deviennent trop fortes. Sur un tel bus, coupez les résistances intégrées sur tous les modules sauf un (ou sur tous — vous ne vous appuyez alors que sur les externes). Voir 04 · Câblage, section « Multi-module bus — primary topology » (bus multi-module — topologie principale).

  2. Ne lancez pas une compilation de production avec le NRST du débogueur connecté. En session de débogage, la ligne de réinitialisation peut maintenir SDA/SCL dans un état indéterminé au détachement / rattachement, provoquant un blocage du bus à la transaction suivante. Dans une compilation terrain (sans débogueur), ce facteur disparaît.

  3. Chien de garde de tâche au niveau applicatif sur la tâche d'interrogation — défense en profondeur. Si, pour une raison quelconque, les résistances de tirage restent marginales, ou qu'une autre cause de blocage survient, le chien de garde redémarre le projet ; et si un superviseur est présent (par exemple un bootloader applicatif de type rolling ou un superviseur de type systemd), il revient en service. Lors d'un test d'endurance de plus d'une heure sur banc, le chien de garde a détecté et récupéré les 12 blocages dans la configuration sans résistance de tirage externe.

C
#include "esp_task_wdt.h"

void app_main(void) {
    /* Layer 3 setup — defense-in-depth. */
    esp_task_wdt_config_t wdt_cfg = {
        .timeout_ms = 10000,           /* 10 s with plenty of margin */
        .idle_core_mask = 0,
        .trigger_panic = true,         /* on timeout — panic+reboot */
    };
    ESP_ERROR_CHECK(esp_task_wdt_reconfigure(&wdt_cfg));
    ESP_ERROR_CHECK(esp_task_wdt_add(NULL));   /* this task is under the WDT */

    /* ... bus / fleet init ... */

    while (1) {
        rbamp_fleet_poll_all(fleet, snaps, status, RBAMP_FLEET_MAX_MODULES, &n_ok);
        /* ... processing ... */
        esp_task_wdt_reset();            /* "I'm alive" — every cycle */
        vTaskDelay(pdMS_TO_TICKS(200));
    }
}

Ce qu'il ne faut PAS faire : n'essayez pas de contourner le problème avec un xfer_timeout_ms plus grand — il ne borne pas l'attente de bus occupé en amont, c'est un autre chemin de code dans le pilote. La solution est l'intégrité du bus (couche 1) + le superviseur (couche 3).

Expiration du chien de garde pendant la connexion Wi-Fi

Cause : une boucle d'attente de connexion WiFi sans borne à l'intérieur d'un gestionnaire d'événements déclenche le WDT de tâche après ~5 s (par défaut).

Correctif : utilisez un motif piloté par les événements plutôt qu'une attente active. Le pilote WiFi d'ESP-IDF émet les événements WIFI_EVENT_STA_DISCONNECTED et IP_EVENT_STA_GOT_IP — réagissez-y via esp_event_handler_register() au lieu d'interroger dans une boucle.

Motif minimal :

C
static EventGroupHandle_t wifi_event_group;
#define WIFI_CONNECTED_BIT BIT0
#define WIFI_FAIL_BIT      BIT1

static void wifi_event_handler(void *arg, esp_event_base_t event_base,
                                int32_t event_id, void *event_data) {
    if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_DISCONNECTED) {
        esp_wifi_connect();   /* auto-reconnect */
    } else if (event_base == IP_EVENT && event_id == IP_EVENT_STA_GOT_IP) {
        xEventGroupSetBits(wifi_event_group, WIFI_CONNECTED_BIT);
    }
}

/* In app_main, wait for the event with a timeout: */
EventBits_t bits = xEventGroupWaitBits(
    wifi_event_group, WIFI_CONNECTED_BIT | WIFI_FAIL_BIT,
    pdFALSE, pdFALSE, pdMS_TO_TICKS(30000));
if (!(bits & WIFI_CONNECTED_BIT)) {
    esp_restart();
}

le broker MQTT se déconnecte toutes les ~15 s

Cause : dans la plupart des cas, ce n'est pas le keepalive. Le session.keepalive par défaut dans esp_mqtt_client_config_t est de 120 s, et disable_keepalive vaut false par défaut (c'est-à-dire que le keepalive est activé). Réécrire explicitement ces champs avec les mêmes valeurs ne change rien — si la connexion meurt toutes les 15 s, la vraie cause se trouve dans le réseau (un NAT/pare-feu intermédiaire qui coupe le TCP inactif) ou une coupure WiFi.

Correction : enregistrez MQTT_EVENT_DISCONNECTED et reconnectez explicitement. esp_mqtt_client_start() lance sa propre tâche en interne ; vous n'avez pas à faire tourner une mqtt.loop() séparée — reconnectez simplement sur l'événement.

C
static void mqtt_event_handler(void *arg, esp_event_base_t base,
                               int32_t event_id, void *event_data) {
    if (event_id == MQTT_EVENT_DISCONNECTED) {
        ESP_LOGW("mqtt", "disconnected — reconnecting on timeout");
        /* esp-mqtt reconnects automatically with backoff;
         * this handler is the place to clean up application state
         * (retained flags, discovery payload caches). */
    }
}

const esp_mqtt_client_config_t cfg = {
    .broker.address.uri = "mqtt://192.168.1.10:1883",
    /* leave keepalive at the default — 120 s;
     * for aggressive NATs, lower it to 30 s: */
    /* .session.keepalive = 30, */
};
esp_mqtt_client_handle_t client = esp_mqtt_client_init(&cfg);
esp_mqtt_client_register_event(client, ESP_EVENT_ANY_ID,
                                mqtt_event_handler, NULL);
esp_mqtt_client_start(client);

Si les déconnexions coïncident dans le temps avec des coupures Wi-Fi, la vraie cause se trouve dans le Wi-Fi (RSSI, canal encombré), non dans MQTT. Vérifiez la charge utile de MQTT_EVENT_ERROR et les journaux Wi-Fi avant de toucher au keepalive.

Échec de la négociation TLS (intégrations cloud)

Cause : le tas de l'ESP32 est insuffisant pour la négociation TLS (~30 kB requis). Souvent combiné au Wi-Fi + MQTT + tampons, ce qui laisse moins de 20 kB.

Fix:

  • Utilisez WiFi.mode(WIFI_MODE_STA) (et non STA+AP).
  • Désactivez le BLE si vous n'en avez pas besoin : CONFIG_BT_ENABLED=n dans sdkconfig.

  • Réduisez les tailles de tampons MQTT dans esp_mqtt_client_config_t.

  • Passer à l'ESP32-S2 (sans Bluetooth — environ 30 kB de tas en plus).

Si esp_get_free_heap_size() affiche moins de 25 ko avant esp_mqtt_client_start() ou esp_http_client_perform(), la négociation TLS échouera très probablement.

Gestion des erreurs : dernière écriture de REG_ERROR + EVENT_FLAGS.bit3 durable (v1.3)

Canon v1.3 (confirmé sur matériel) : REG_ERROR (0x02) est le résultat de la dernière écriture, NON persistant. À chaque écriture de registre, le firmware positionne reg_error = ERR_OK ; une écriture sans rapport ultérieure 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.

Motif 1 — capture ponctuelle après une opération (si le résultat de CETTE opération précise importe) :

C
esp_err_t err = rbamp_save_user_config(dev);
uint8_t dev_err;
rbamp_read_last_error(dev, &dev_err);   /* IMMEDIATELY, before the next write */

Motif 2 — surveillance durable des erreurs (canonique pour les longues durées) :

C
uint8_t event_flags;
rbamp_read_event_flags(dev, &event_flags);
if (event_flags & RBAMP_EVENT_ERROR) {
    uint8_t last_err;
    rbamp_read_last_error(dev, &last_err);   /* what was the last rejected */
    /* handle the error */
    rbamp_clear_error(dev);                  /* clears REG_ERROR ... */
    rbamp_clear_event_flags(dev, RBAMP_EVENT_ERROR);  /* ... then the sticky bit */
}
Sécurité

⚠ RENVERSEMENT de la documentation « persistante » précédente (canon v1.3 A3). REG_ERROR est l'issue de la dernière écriture, non persistante. La durabilité est assurée par EVENT bit3.

⚠ bit3 est un canal asynchrone, non destiné à la validation synchrone d'écriture : en cas d'écriture rejetée, bit3 est positionné avec un délai par rapport au moment où la transaction I²C revient. Ne scrutez pas bit3 juste après une écriture pour vérifier l'issue de cette écriture : pour l'issue de votre propre écriture, utilisez le motif 1 (une capture ponctuelle de REG_ERROR immédiatement 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 de fonctionnement, chemin de commande), non à valider une opération que vous venez d'effectuer.

Mise en garde : DEV_ERR_CLONE (0xF9) n'est PAS effacé par CMD_CLEAR_ERROR — c'est une sentinelle anti-clonage (seuls un redémarrage ou une réinitialisation d'usine l'effacent).

Un module à flash neuve affiche 0xFB au premier démarrage (NORMAL)

Ce que vous voyez : un module à flash neuve affiche au premier démarrage REG_ERROR = 0xFB (DEV_ERR_FLASH_PARAMS_BAD) + EVENT bit3.

Cause : la page de paramètres n'est pas initialisée → les réglages d'usine sont chargés. C'est NORMAL pour un module vierge, pas une erreur fatale.

Solution : configurez sensor_class + ct_model + (facultativement) l'adresse, puis CMD_SAVE_USER_CONFIG. Après un SAVE réussi → REG_ERROR = 0x00, bit3 effacé.

rbamp_set_sensor_class / rbamp_set_ct_model* renvoie ESP_ERR_INVALID_STATE

Ce que vous voyez : l'un des appels de configuration renvoie ESP_ERR_INVALID_STATE.

ESP_ERR_INVALID_STATE pour ce groupe de fonctions est un code parapluie couvrant trois causes distinctes. Vous pouvez les distinguer par la ligne ESP_LOGW que le composant affiche sous l'étiquette "rbamp" juste avant de renvoyer :

Ligne de journal (ESP_LOGW, TAG="rbamp") Cause Solution
set_ct_model_ch refused: sensor class is UNSET (call rbamp_set_sensor_class first) Précondition : la classe de capteur doit être réglée avant d'écrire le modèle de CT Appelez rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013) avant rbamp_set_ct_model*().
set_ct_model_ch refused: bind sequence error (call rbamp_set_sensor_class first to reset batch) Le suivi de lot interne du composant est désynchronisé avec l'état de mise en attente du firmware Sur le firmware v1.3, l'ordre de liaison des canaux est indifférent (mise en attente pure Fix-A — voir 03 · Choix du capteur de courant). Rappelez rbamp_set_sensor_class() pour réinitialiser le suivi du lot, puis liez les canaux dans n'importe quel ordre. La formulation « ordre décroissant requis » des anciens messages de journal se rapporte au comportement d'avant la v1.3 et n'est plus en vigueur.

Il existe aussi le cas d'un handle initialisé mais pour lequel rbamp_begin() n'a pas été appelé — cela renvoie ESP_ERR_INVALID_STATE sans ligne ESP_LOGW (le handle reste « froid »). Solution : appelez rbamp_begin(dev) après rbamp_new() et avant tout rbamp_set_*.

Remarque

Le schéma de désambiguïsation par journal est un idiome ESP-IDF standard : comparez avec esp_driver_i2c, qui renvoie ESP_ERR_TIMEOUT pour un dépassement d'ACK comme pour un dépassement de bus occupé, et les distingue par le journal. Si vous voyez ESP_ERR_INVALID_STATE sans cause claire, augmentez le niveau de journalisation via esp_log_level_set("rbamp", ESP_LOG_WARN) (ou _DEBUG) et répétez l'appel : le composant vous indiquera lequel des trois cas vous avez. rbamp_err_to_str(ESP_ERR_INVALID_STATE) renvoie une description générique : « Wrong call sequence (check log: factory mode / sensor class UNSET / bind batch out of sync) » (séquence d'appels incorrecte : vérifiez le journal — mode usine / classe de capteur UNSET / lot de liaison désynchronisé).

rbamp_set_sensor_class / rbamp_set_ct_model* renvoie ESP_ERR_INVALID_ARG

Ce que vous voyez : l'appel renvoie ESP_ERR_INVALID_ARG.

Causes possibles :

  1. Code de modèle invalide pour la classe — les codes valides dépendent de la classe de capteur : SCT013 accepte {1, 2, 3, 4, 5, 6, 7} (voir le tableau de 03 · Choix du capteur de courant) ; WIRED_CT accepte 1 à 10 et 12. Un code inconnu pour la classe renvoie ESP_ERR_INVALID_ARG.

  2. Indice de canal invalide dans la forme par canal rbamp_set_ct_model_ch(dev, channel, code) — doit être < rbamp_channels(dev).

  3. Une valeur rbamp_sensor_class_t invalide — une classe supérieure à 3 renvoie ESP_ERR_INVALID_ARG. Les modules livrés étalonnés avec leur propre capteur (RBAMP_SENSOR_WIRED_CT, RBAMP_SENSOR_BUILTIN_CT) refusent tout changement de classe ou de modèle (ESP_ERR_INVALID_STATE) ; pour une pince SCT-013 à serrage, utilisez RBAMP_SENSOR_SCT013.

  4. dev == NULL ou out == NULL — vérifiez que rbamp_new() a réussi (renvoyé ESP_OK).

rbamp_commit_address_change renvoie ESP_ERR_TIMEOUT

Si prepare a réussi mais que commit renvoie ESP_ERR_TIMEOUT, la fenêtre d'« armement » a expiré (5 secondes après prepare). rbamp_probe() n'aidera pas ici (le module répond ; le problème est dans la machine d'états). Solution : rappelez rbamp_prepare_address_change() puis immédiatement — dans la même itération de app_main, sans appel réseau entre les deux — rbamp_commit_address_change(). Le Wi-Fi / MQTT / toute entrée/sortie bloquante entre prepare et commit est la principale cause d'expiration de la fenêtre.

Pour en savoir plus sur les méthodes publiques avec avertissement, voir 09 · Référence API, section « Configuration du capteur ».

Les lectures échouent lors de la commutation de charges à relais (transitoires EMI)

Ce que vous voyez : rbamp_read_* renvoie périodiquement ESP_FAIL / ESP_ERR_INVALID_RESPONSE, mais uniquement pendant qu'une charge à relais ou inductive commute activement sur la même installation. En régime établi, les lectures sont fiables.

Cause (C.12 confirmée sur le matériel) : pendant la commutation des relais (une charge de 5 A), les EMI font échouer ~67 % des transactions I²C (~8/12 dans la mesure matérielle). Le bus se rétablit de lui-même, aucun verrouillage ne se produit, aucun module n'est perdu — mais la lecture en cours échoue.

Solution — nouvelle tentative au niveau applicatif :

C
esp_err_t robust_read_voltage(rbamp_handle_t dev, float *v) {
    for (int attempt = 0; attempt < 5; attempt++) {
        esp_err_t err = rbamp_read_voltage(dev, 0, v);
        if (err == ESP_OK) return ESP_OK;
        vTaskDelay(pdMS_TO_TICKS(20));   // short pause before retry
    }
    return ESP_FAIL;
}
Sécurité

⚠ Un bus_reset côté maître seul ne suffit pas : lorsqu'une perturbation EMI chevauche la fenêtre de reprise du pilote, il faut une reprise explicite au niveau applicatif avec une pause.

Alternative : si le maître voit des événements de commutation de relais, décalez les lectures d'environ 50-100 ms après la commutation.

Réinitialisation par chien de garde de tâche sous EMI / forte charge

Ce que vous voyez : l'ESP32 redémarre de façon inattendue avec la raison TASK_WDT. Cela survient généralement lors d'événements EMI (commutation de relais, transitoires inductifs).

Cause : sous des lectures ralenties par les EMI (cycles de nouvelle tentative NACK + réinitialisation de bus), le pilote i2c_master d'ESP-IDF peut étirer une transaction jusqu'à ~100 ms et plus. Si une tâche exécute une boucle serrée de lectures en rafale sans céder la main — délai d'attente du WDT de tâche.

Solution — céder la main dans la boucle de lecture en rafale :

C
// WRONG — no yield, under EMI → WDT reboot
for (int i = 0; i < N_METERS; i++) {
    rbamp_read_period_snapshot(meters[i], &snaps[i], 0, true);
}

// CORRECT — yield every N reads (or every iteration)
for (int i = 0; i < N_METERS; i++) {
    rbamp_read_period_snapshot(meters[i], &snaps[i], 0, true);
    vTaskDelay(1);   // yield + WDT feed
}

Alternative : esp_task_wdt_reset() explicitement si la tâche est suivie par le WDT.

Tableau récapitulatif des codes d'erreur

Les fonctions rbamp_* renvoient les valeurs standard esp_err_t. rbamp_err_to_str(err) renvoie une chaîne lisible.

Code Quand Où regarder
ESP_OK (0) succès —
ESP_FAIL (-1) NACK après nouvelle tentative ; ou le filtre de cohérence a rejeté la valeur Section « Le module ne répond pas sur I²C »
ESP_ERR_INVALID_ARG (0x102) dev == NULL, channel/phase hors plage, un cls non reconnu, une valeur que le module rejette vérifier les arguments de l'appel
ESP_ERR_TIMEOUT (0x107) rbamp_wait_ready a expiré (module ne répondant pas) OU la fenêtre de 5 s entre prepare_address_change et commit_address_change a expiré pour wait_ready — via rbamp_probe() ; pour la validation — réarmez : prepare + commit enchaînés sans entrée/sortie bloquante entre les deux
ESP_ERR_INVALID_STATE (0x103) précondition : set_ct_model* avant set_sensor_class la section set_* ci-dessus
ESP_ERR_NOT_SUPPORTED (0x106) la fonction n'est pas disponible sur le SKU actuel (par ex. l'API de tension sur une variante I*) vérifier rbamp_line(dev) et rbamp_variant(dev)
ESP_ERR_INVALID_RESPONSE (0x108) instantané de période périmé ; ou REG_VERSION = 0/0xFF sur rbamp_begin Section « Period snapshots are always stale » / « Module doesn't respond »
ESP_ERR_NO_MEM (0x101) échec de l'allocation de mémoire pour le handle vérifier le budget de tas (esp_get_free_heap_size())

Débogage au niveau du bus avec un analyseur logique

Pour un débogage approfondi, lorsque le composant ne peut plus vous dire ce qui se passe sur le fil, capturez SDA + SCL avec un analyseur logique (Saleae, DSLogic Plus, 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 pour chaque octet + la phase d'adresse.

  • Comparez les appels de votre code (rbamp_read_voltage(), etc.) à la séquence d'octets attendue : elles doivent correspondre exactement. Les lectures en rafale (plusieurs octets dans une seule transaction grâce à l'incrémentation automatique de l'adresse) sont prises en charge.

Si le comportement du composant diverge de la capture, ouvrez un ticket en joignant le fichier de capture (.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-esp-idf/issues

Dans le ticket, incluez :

  • SoC cible (ESP32 / S2 / S3 / C2 / C3 / C6 / H2) + version d'ESP-IDF (sortie de idf.py --version).

  • Version du composant rbamp (par exemple, 1.1.0).

  • Version du firmware du module — rbamp_firmware_version(dev) dans les journaux.

  • Un projet IDF minimal reproduisant le problème (~30 lignes de code dans main/main.c).

  • Les valeurs esp_err_t + rbamp_err_to_str(err) au moment de la défaillance, tirées des journaux sous le tag rbamp.

  • Kconfig pertinents : CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ, CONFIG_RBAMP_NACK_RETRY_ATTEMPTS, CONFIG_RBAMP_LOG_LEVEL_*.

  • (Si disponible) un fichier de capture de l'analyseur logique au moment de la défaillance.


Source et problèmes : rb-amp/rbamp-esp-idf · cette page dans le dépôt : docs/10_troubleshooting.md (v1.7.3)