10 · Dépannage
Un guide de dépannage orienté symptômes pour le composant rbamp dans ESPHome. Chaque entrée suit la même structure : ce que vous voyez dans le journal, ce que cela signifie, comment diagnostiquer, et une correction concrète.
Contents:
- I2C / matériel
- Qualité des données
- Énergie et persistance
- Intégration Home Assistant
- Compilation et chaîne d'outils
- Identité / Capacité / Erreur (v1.3)
1. Matériel I²C
Sonde échouée à 0x50 — aucune réponse
Ce que vous voyez dans le journal :
[E][rbamp:xxx]: Probe failed at 0x50 — no response. Check wiring/address.
[E][component:xxx]: Component rbamp was marked as failed.
Le composant appelle alors mark_failed() et cesse les appels update(). Toutes les entités liées restent « Unknown » dans Home Assistant.
Signification :
L'ESP32 a envoyé la phase d'adresse à 0x50 (ou une autre adresse de address:) et n'a reçu aucun ACK. Le module est absent, non alimenté ou sur une autre adresse.
Comment diagnostiquer :
-
Vérifiez que
scan: trueest défini dans le bloc YAMLi2c:. Redémarrez l'ESP32 et surveillez :Text[I][i2c.arduino:069]: Found i2c device at address 0x50Si le scan a trouvé l'appareil, la clé
address:de votre blocrbamp:est erronée — mettez-la à jour. -
Mesurez l'alimentation sur la broche VCC du module avec un multimètre : elle doit être de 4.5..5.5 V (5 V nominal, voir 04_hardware.md). Zéro ou sous 4.5 V signifie une alimentation absente ou marginale.
-
Vérifiez la continuité de SDA et SCL depuis le GPIO de l'ESP32 jusqu'au connecteur du module. Un fil manquant ou inversé est la cause la plus fréquente sur les montages neufs.
-
Vérifiez les résistances de tirage sur SDA et SCL (4.7 kΩ vers 3.3 V). Sans tirage, le bus reste bas et chaque phase d'adresse ressemble à un NACK.
-
Si vous avez récemment changé d'adresse (clé
new_address:), le module se trouve peut-être désormais à la nouvelle adresse. Ajoutezscan: true, repérez l'appareil, mettez à jouraddress:en conséquence et supprimeznew_address:.
Correction : corrigez le câblage / l'alimentation, et mettez à jour address: si le module a changé. Si le module ne répond pas après un changement d'adresse, voir « Adresse changée mais module ne répondant pas » ci-dessous.
Bloc RT non prêt — publication ignorée
Ce que vous voyez :
[D][rbamp:xxx]: RT block not ready (STATUS=0x00) — skipping live publish
Ce que cela signifie : le registre d'état indique que le module n'est pas prêt. Cela arrive lorsque le module n'a pas encore validé son premier bloc de valeurs instantanées après le démarrage, qu'il est en pleine écriture flash, ou qu'il est en réinitialisation logicielle.
Comment diagnostiquer :
-
Si l'entrée apparaît une fois au démarrage (dans les 30 s suivant la mise sous tension) puis disparaît, c'est normal. Le module a besoin d'un cycle de validation (~100 ms) pour positionner le bit READY après la mise sous tension. L'instantané de démarrage dans
setup()produit aussi un cycle sauté. -
Si le flux de messages continue après le préchauffage, le module est peut-être bloqué. Vérifiez les entrées
ct_model:/ct_models:répétées (par exemple une clé oubliée dans le YAML, écrite à chaque démarrage, produisant une fenêtre d'écriture flash permanente). -
Si le message apparaît de temps en temps (une fois tous les quelques cycles), c'est une variabilité normale liée aux NACK. La boucle de relance rattrape la plupart des transitoires ; il arrive que la lecture d'état échoue encore, ce qui déclenche cette entrée DEBUG.
Fix:
- Les sauts de préchauffage au démarrage sont normaux ; attendez deux cycles
update_intervalcomplets. - Si
ct_model:/ct_models:est défini dans le YAML, laissez-le : à chaque démarrage, l'écriture répétée est idempotente (le module n'écrit pas si la valeur est déjà en flash). Si les pauses de préchauffage vous gênent, commentez la clé après une première exécution réussie. - Si le module reste non prêt pendant 60 s ou plus, coupez l'alimentation du module (pas celle de l'ESP32) pour un démarrage à froid propre.
"rbamp took a long time for an operation (XXX ms)"
Ce que vous voyez :
[W][component:522]: rbamp took a long time for an operation (406 ms), max is 30 ms
Signification : cet avertissement se déclenche lorsque le update() d'un composant dépasse le budget par défaut de 30 ms du planificateur coopératif d'ESPHome. Pour le composant rbamp, c'est attendu et sans danger.
Sur le firmware v1.3, la lecture à incrémentation automatique (READ auto-increment) est prise en charge pour le bloc des valeurs instantanées (la plage contiguë couvrant U / I / P / PF / Q pour tous les canaux déclarés). Le composant émet une seule lecture en rafale pour ce bloc — une phase d'adresse suivie d'environ 36 octets de données — ce qui coûte ≈ 8–10 ms de temps de bus à 50 kHz. L'écriture à incrémentation automatique n'est pas prise en charge : les écritures par registre (préparation du modèle CT, classe de capteur, validation de l'adresse) passent donc toujours octet par octet. Si la lecture en rafale échoue (NACK en cours de route, bit de capacité absent sur un firmware ancien), le composant revient à des lectures par registre (4 transactions par float, jusqu'à 36 transactions ≈ 90 ms à 50 kHz). Avec le triplet de relance par octet (jusqu'à 3 × 5 ms d'attente sur un cycle riche en NACK), le chemin de repli au pire cas dure normalement 300–450 ms — ce qui produit cet avertissement lorsqu'il apparaît.
La temporisation de stabilisation de l'instantané (set_timeout("rbamp_period", 50, ...)) est non bloquante — update() rend la main à l'ordonnanceur pendant les 50 ms. L'avertissement reflète le temps réel de l'ensemble de la lecture bloquante des valeurs instantanées, et non une famine du WiFi ou de l'API.
Aucune action de l'utilisateur n'est requise. L'avertissement est cosmétique ; les capteurs HA se mettent à jour correctement. Sur les modules v1.3 sains, le chemin de lecture en rafale reste normalement sous 30 ms et l'avertissement ne se déclenche pas du tout.
Si l'avertissement se déclenche à chaque cycle : le bus force le repli registre par registre (firmware hérité sans la capacité de lecture en rafale, ou tirages marginaux produisant des NACK en milieu de rafale). Vérifiez la version du firmware (Firmware version: 0x04 dans le journal de démarrage = v1.3) et la topologie des tirages (paire unique de 4.7 kΩ vers 3.3 V propre).
Échec de la lecture de l'instantané de période
Ce que vous voyez :
[W][rbamp:xxx]: Failed to read PERIOD_AVG_P[0]
[W][rbamp:xxx]: Failed to read PERIOD_AVG_P[1]
Ce que cela signifie : après la commande d'instantané et l'attente de 50 ms, le composant n'a pas pu lire le registre de puissance moyenne de période pour le canal N après trois tentatives. L'accumulateur d'énergie de ce canal n'est pas mis à jour dans ce cycle.
Les causes les plus fréquentes :
- Blackout d'écriture en flash. Le module écrit un modèle de pince CT (déclenché par
ct_model:ouct_models:au démarrage) ou sauvegarde une nouvelle adresse. La fenêtre est d'environ 700 ms ; si la temporisation de 50 ms de l'instantané tombe dedans, la lecture expire. - Instantané manqué sous interrogation intensive. Sous une interrogation I²C intensive et consécutive, le côté module peut manquer un instantané. L'instantané reste vide, mais l'indicateur de validité vaut 0 — le composant ignore l'intégration avec le message "Period snapshot not yet valid; keeping previous integration window". L'avertissement ne se déclenche que si l'indicateur de validité est levé mais que la lecture du registre a échoué.
- Épuisement des NACK transitoires. Les trois tentatives ont échoué sur au moins l'un des quatre octets du float. Rare à 50 kHz (< 1 % des cycles) ; plus fréquent à 100 kHz.
Que devient l'énergie : en cas d'avertissement, last_latch_ms_ n'est pas mis à jour. Au cycle réussi suivant, dt_ms couvre à la fois la fenêtre manquée et la nouvelle — l'énergie se rattrape, en supposant une charge à peu près stable sur l'intervalle. C'est une imprécision mineure et acceptable.
Fix:
- Supprimez les clés de changement d'adresse (
new_address:) du YAML après le premier démarrage réussi. - Si l'avertissement se déclenche plus d'une fois par heure, vérifiez la vitesse du bus (
50kHzrecommandé) et les résistances de tirage (4.7 kΩ). - Si l'avertissement se déclenche à chaque cycle, vérifiez un conflit avec un autre appareil sur le bus.
Adresse modifiée mais le module ne répond pas
Ce que vous voyez :
[E][rbamp:xxx]: Address change applied but slave not responding at 0x51 —
check wiring and try power-cycling the rbAmp.
[E][component:xxx]: Component rbamp was marked as failed.
Ce que cela signifie : la procédure de changement d'adresse a suivi toutes les étapes (écriture de la nouvelle adresse, sauvegarde en flash, réinitialisation logicielle, bascule de l'adresse I²C interne du composant), mais le module n'a pas répondu sur la nouvelle adresse au premier contrôle.
Causes possibles :
- L'adresse a été écrite et sauvegardée, mais le module est passé dans un mauvais état (corruption des paramètres en flash, coupure d'alimentation pendant la fenêtre d'écriture de 700 ms).
- Sur le firmware historique (v1.0-v1.2) : le module n'était pas en mode provisionnement en usine au moment de la tentative. Sur le firmware v1.3+ cette cause ne s'applique pas (la validation en deux phases est prête pour la production). Si la lecture même du mode a échoué (NACK), le composant écrit par anticipation, avec un avertissement dans le journal.
- Un problème de câblage antérieur au changement d'adresse (la sonde sur l'ancienne adresse n'a réussi que par coïncidence sur l'un des trois essais).
Procédure de récupération :
- Le module se trouve à une adresse inconnue. Utilisez un YAML de test avec
i2c: scan: trueet une coupure d'alimentation — trouvez à quelle adresse le module répond. - Si le module est trouvé sur la nouvelle adresse (par exemple 0x51), mettez à jour le YAML avec
address: 0x51, retireznew_address:, puis reflashez. Le prochain démarrage se déroulera proprement. - Si le module ne répond à aucune adresse, l'écriture flash a pu corrompre les paramètres. La récupération exige une intervention physique : consultez la documentation du module ou votre fournisseur.
Contexte : le flux de changement d'adresse sur le firmware v1.3 est une validation en deux phases — le maître écrit la nouvelle adresse dans un registre de transit, puis émet CMD_COMMIT_ADDR pour la rendre persistante. La fenêtre d'écriture de 700 ms correspond à l'effacement et à la programmation de la page de configuration utilisateur en flash. Voir 09 · Référence API.
i2c_master bloqué — ESP32 en boucle au démarrage ou bloc RT qui ne publie jamais
Ce que vous voyez :
[I][i2c.idf:xxx]: Performing I2C bus reset...
[E][i2c.idf:xxx]: i2c_master_send_buf failed: ESP_ERR_TIMEOUT
[E][rbamp:xxx]: Probe failed at 0x50 — no response. Check wiring/address.
[E][component:xxx]: Component rbamp was marked as failed.
Dans le pire des cas, un dépassement du chien de garde de tâche redémarre l'ESP32 après plusieurs minutes d'endurance (sous charge, pas à la mise en service). Cela peut ressembler à « le module a fonctionné une heure puis s'est arrêté ».
Signification : le pilote i2c_master de l'ESP-IDF v5 présente un défaut connu : sur un bus marginal (temps de montée lent, tirage faible, salve EMI) la fonction interne i2c_ll_is_bus_busy tourne sans fin, en attendant une condition STOP qui n'arrive jamais. Dans ESPHome 2025.x, cette boucle peut épuiser le budget du chien de garde applicatif et provoquer un redémarrage. C'est un problème canonique de l'ESP-IDF, non propre à rbAmp.
Atténuation en trois couches (toutes actives dans le composant par défaut, plus les recommandations matérielles) :
-
Logiciel : la discipline NACK intégrée — 50 kHz par défaut + 3 nouvelles tentatives par octet avec un intervalle de 5 ms + le filtre de cohérence IP-009
std::isfinite(). Déjà présente dans le composant depuis la v0.2+. Le correctif de durcissement du gestionnaire d'arrêt est livré dans les firmwares v1.1/v1.3, mais 50 kHz reste recommandé sur les maîtres ESP-IDF car l'interaction de temporisation du pilote persiste. -
Matériel : une résistance de tirage externe de 4.7 kΩ sur SDA + SCL (une seule paire de tirages externes, avec les straps internes au module coupés — voir §Bus multi-modules). Les tirages internes de l'ESP32 (~50 kΩ) sont faibles — sur un bus long ou avec une alimentation marginale, ils ne suffisent pas. Des tirages de 4.7 kΩ vers un 3.3 V propre sont obligatoires pour un déploiement en production.
-
Matériel : ne maintenez pas le débogueur / la réinitialisation OTA enclenchés pendant les transactions I²C. Un RESET activé au milieu d'une transaction laisse le bus bloqué (l'esclave continue de piloter SDA), ce qui provoque exactement la boucle infinie « bus busy ».
Taux de blocage observé lors d'un test d'endurance de 24 heures :
| Couche | Taux de blocage | Remarque |
|---|---|---|
| Logiciel uniquement (sans tirage externe) | ~1× par 10 minutes | le chien de garde du pont se déclenche et récupère par reset, mais Wh perd une fenêtre |
| Logiciel + tirage externe de 4.7 kΩ | ~1× par 24 heures | Cas de salve EMI ; récupération automatique |
| Logiciel + tirage externe + réinitialisation propre | 0 bloqué après un essai de 24 h | cible de production |
Gravité = au moment de la mesure (endurance complète), et non à la mise en service. À la mise en service, la discipline NACK intercepte plus de 99 % des cas grâce au triplet de nouvelles tentatives — les vrais blocages n'apparaissent qu'après des heures d'endurance propre. Pour la référence complète de la discipline, voir 09 · Référence API.
: en dernier recours, configurez wdt: (noyau esphome) avec un app_wdt_timeout_seconds: augmenté (par défaut 5 s ; réglez 10–15 s). Cela laisse du temps à la récupération du composant sans redémarrage.
2. Qualité des données
La tension oscille — 228 V / 502 V / 1.96 V mélangés
Ce que vous voyez :
[D][sensor:xxx]: 'Mains Voltage': Sending state 502.730 V
[D][sensor:xxx]: 'Mains Voltage': Sending state 1.964 V
[D][sensor:xxx]: 'Mains Voltage': Sending state 228.365 V
[D][sensor:xxx]: 'Mains Voltage': Sending state 502.730 V
Dans Home Assistant, le graphe de tension est en dents de scie entre ~228 V, ~2 V et ~503 V. Le courant peut simultanément afficher 0 A ou −2 A.
Signification : des valeurs « fantômes » remontent d'un tampon défaillant du pilote i2c_master de l'ESP-IDF en cas de NACK à 100 kHz. Ce problème doit être éliminé par la configuration par défaut de la version actuelle du composant. Si le symptôme apparaît :
- Le bloc
i2c:afrequency: 100kHz— remplacez-le par50kHz. - La version du composant est antérieure au 2026-05-24 — mettez-la à jour.
Fix:
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz # required for reliable operation
scan: true
Pour en savoir plus sur le mécanisme de discipline NACK (50 kHz par défaut + relance par octet + filtre de cohérence NaN/Inf), voir 09 · Référence API.
Compatibilité avec framework: type: — le problème des valeurs fantômes après NACK ne se manifeste que sous le pilote ESP-IDF i2c_master. Avec framework: type: arduino (par défaut), la pile Arduino Wire est utilisée ; elle se comporte différemment en cas de NACK et ne reproduit pas ce symptôme. Cela signifie :
- Si le YAML contient
esp32: framework: type: arduino, vous pouvez en théorie garderfrequency: 100kHzsans pics fantômes visibles, mais la boucle de relance par octet du composant tourne toujours sur Wire et les NACK périodiques à 100 kHz subsistent — simplement sans les fantômes. Pour des graphes HA stables, nous recommandons 50 kHz quel que soit le framework. - Si le YAML contient
esp32: framework: type: esp-idf, alorsfrequency: 50kHzest obligatoire. C'est la configuration dans laquelle le pilotei2c_mastermontre le plus nettement le symptôme fantôme.
Le composant lui-même ne choisit pas le framework — il fonctionne au-dessus des deux. C'est uniquement une décision dans votre YAML.
Le courant reste à 0 A en permanence sous charge
Ce que vous voyez :
[D][sensor:xxx]: 'Mains Current': Sending state 0.000 A
La puissance est de 0 W, l'énergie ne croît pas, mais la tension se lit correctement (par exemple 228 V).
Ce que cela signifie : l'une des deux causes typiques :
Cause 1 — ct_model: non défini ou ne correspondant pas à la pince physique. Sur le firmware v1.2+, le module utilise les coefficients d'usine du modèle choisi dans le YAML. Si ct_model: n'est pas défini, ou est réglé sur par ex. SCT_013_050 avec une vraie SCT-013-005, la plage de mesure est tellement plus large que le signal physique que le module ne peut pas la résoudre et affiche zéro.
Cause 2 — la pince est mal installée sur le conducteur (voir la polarité dans 03_sensor_selection.md et l'entourage d'un seul conducteur).
Comment diagnostiquer :
- Vérifiez que la pince est bien installée autour d'un conducteur réellement parcouru par le courant (utilisez une pince ampèremétrique comme référence, si vous en avez une).
- Ouvrez le YAML et vérifiez que
ct_model:(ouct_models:pour UI3) correspond au modèle de pince physique. - Si
ct_model:est défini sur le firmware v1.2+ mais quesensor_class:est omis ou différent deSCT_013, le module refuse l'écriture du modèle. Le journal de démarrage affiche un avertissement qui pointe la condition préalable manquante.
Fix:
rbamp:
id: meter1
sensor_class: SCT_013 # default; required on v1.2+ before ct_model
ct_model: SCT_013_005 # match the physical clamp
Après le démarrage, le module écrit le modèle en flash une fois (~700 ms) et charge les coefficients d'usine. La publication suivante des valeurs instantanées donne déjà le bon courant.
Précision sur petits courants sur UI2 / UI3 — le motif double CT. Si vous voulez une haute résolution sur les petites charges (éclairage, veille) et une plage large pour les pointes (bouilloire, lave-linge) en même temps, utilisez deux canaux de courant sur la même phase, avec des pinces différentes :
rbamp:
id: home_meter
sensor_class: SCT_013
ct_models: [SCT_013_005, SCT_013_030, SCT_013_050]
# CH0 — SCT-013-005 for resolving idle loads (~5..50 W)
# CH1 — SCT-013-030 for the main household load (~50..7000 W)
# CH2 — SCT-013-050 for the peak (EV-charging headroom up to 11.5 kW)
# For peaks above 50 A use SCT_013_060 (60 A) or SCT_013_100 (100 A) on that channel
Les trois pinces entourent le même conducteur de phase L. SCT-013-005 offre une résolution environ 10× meilleure sur les petits courants que le SCT-013-030, mais sature vers ~5 A. Le SCT-013-030 couvre le « milieu » de la plage utile ; le SCT-013-050 capte les pointes jusqu'à ~11.5 kW sans saturer. Côté HA, un capteur de modèle sélectionne la mesure « active » par seuil :
YAML Home Assistant (pas ESPHome) — à placer dans votre configuration Home Assistant, pas dans le YAML du nœud.
# configuration.yaml — select the active channel by range
template:
- sensor:
- name: "Mains Current (active)"
unit_of_measurement: "A"
device_class: current
state_class: measurement
state: >
{% set i0 = states('sensor.rbamp_ch0_current') | float(0) %}
{% set i1 = states('sensor.rbamp_ch1_current') | float(0) %}
{% set i2 = states('sensor.rbamp_ch2_current') | float(0) %}
{% if i2 > 25 %}{{ i2 }}
{% elif i1 > 4 %}{{ i1 }}
{% else %}{{ i0 }}
{% endif %}
Cela couvre la plage allant du plus petit au plus grand calibre des trois pinces (5 A … 50 A). Compromis : trois pinces CT sur un même conducteur sont physiquement encombrantes, et chacune occupe un canal du module (sur UI3, c'est tout le module). Pour la plupart des déploiements, une seule pince dont le calibre correspond à la charge couvre 99 % des scénarios — le motif double/triple CT n'est nécessaire que lorsqu'une grande plage dynamique est requise.
Instantané de période non valide — l'énergie ne croît pas
Étalonnage et précision (dépannage) · 7.5 Préservation de la période après instantané échoué (référence API)
Ce que vous voyez :
[D][rbamp:xxx]: Period snapshot not yet valid; keeping previous integration window
Le capteur energy dans Home Assistant affiche une valeur constante (ou reste à 0 Wh après le démarrage), alors que la puissance est lue correctement.
Ce que cela signifie : le bit de validité de l'instantané de période valait 0 lorsque le composant l'a vérifié 50 ms après la commande d'instantané. Le module n'a pas encore validé d'instantané de période valide.
Causes habituelles :
- Premier instantané après le démarrage. L'instantané de démarrage dans
setup()écarte toujours son résultat — l'accumulateur du module est réinitialisé au premier ordre d'instantané. Le second instantané (uneupdate_intervalaprès le démarrage) est le premier à intégrer. L'énergie commence à s'accumuler après la premièreupdate_intervalcomplète depuis le démarrage. - Démarrage à froid du module. Le module a besoin d'au moins un cycle de validation d'environ 100 ms pour que des données soient présentes dans l'accumulateur de période. Si le premier instantané survient plus tôt, l'indicateur de validité vaut 0.
- Instantané manqué sous interrogation intensive. Sous une charge I²C intensive, le côté module peut manquer un instantané. L'instantané reste vide ; le suivant devrait réussir.
Si l'entrée se déclenche à chaque cycle update() indéfiniment (et pas seulement les deux premières fois), le module est peut-être dans un état où l'accumulateur de période ne se valide jamais. Couper l'alimentation du module efface cet état.
3. Énergie et persistance
Compteur d'énergie remis à 0 après un redémarrage
L'énergie provient des compteurs propres du module et est en plus sauvegardée dans la flash de l'ESP32 (NVS), donc un redémarrage de l'ESP32 ou du module ne la remet pas à zéro, et les totaux ne reculent pas. Si un capteur d'un module STANDARD repart de 0, la cause est un effacement de la NVS (effacement flash, table de partitions modifiée) et une remise à zéro du compteur du module au même moment. Les capteurs de total général (energy_total, energy_exported_total, energy_net, reactive_energy*) utilisent leur propre emplacement NVS, distinct des emplacements energy par canal, de sorte qu'une mise à niveau du composant n'efface pas les valeurs par canal.
Ce que vous voyez dans le tableau de bord Énergie de HA : une chute brutale à 0 Wh, puis une accumulation normale à partir de 0. L'historique des Wh antérieurs est conservé dans les statistiques à long terme de HA, mais la « lecture courante du compteur » semble remise à zéro.
Signification : la restauration depuis la NVS n'a trouvé aucune donnée ou des données invalides. Causes possibles :
- Montée de version de la disposition NVS. La clé NVS est dérivée de l'identifiant du composant, combiné par XOR à une constante de version de disposition. Si la structure a changé (lors d'une mise à jour du composant), la clé de l'emplacement NVS change et les anciennes données ne sont plus trouvées. La restauration repart silencieusement de 0.
- Fragmentation ou corruption de la NVS. La partition NVS de l'ESP32 utilise un nivellement d'usure de la mémoire flash. Sur de très anciens déploiements ou après de nombreux flashs, la fragmentation peut faire échouer une sauvegarde. Le journal affiche :
[W][rbamp:xxx]: Failed to save Wh totals to NVS — will retry next cycle. - Changement de la table de partitions. Flasher un nouveau
partitions.csvqui modifie la taille ou la position de la partitionnvsinvalide toutes les valeurs sauvegardées. - Premier démarrage après une réinitialisation d'usine ou un effacement complet du flash. Attendu : la NVS est vide, l'accumulateur repart de 0.
Comment diagnostiquer :
Recherchez dans le journal de démarrage :
[C][rbamp:xxx]: No saved energy state — starting from 0 Wh
Si présent, la restauration n'a rien trouvé. Aussi :
[C][rbamp:xxx]: Restored Wh from NVS: total[0.310, 0.000, 0.000] export[...]
Si la valeur restaurée est nettement inférieure à l'attendu, la dernière sauvegarde NVS de 5 minutes a peut-être été sautée (perte au pire cas : ≈ 5 Wh à une moyenne de 60 W).
Fix:
- Lors d'une mise à niveau du composant qui modifie la disposition NVS, les anciens totaux ne se restaurent pas automatiquement. Les statistiques HA à long terme conservent l'historique même si la « lecture courante » repasse à zéro.
- Pour conserver les Wh lors d'un effacement forcé de la NVS, relevez les valeurs actuelles des capteurs dans les Outils de développement HA avant l'effacement et notez-les. Il n'existe aucun moyen d'injecter une valeur de départ dans le composant.
L'énergie dans HA ne correspond pas à un compteur de référence
Ce que vous observez : le capteur energy dans HA affiche nettement moins (par exemple 10–20 %) qu'un compteur intelligent de référence ou que le compteur du distributeur sur la même période.
Ce que cela signifie : sur les modules BASIC, le composant intègre la puissance moyenne de la période sur le temps côté ESP32 entre les commandes d'instantané. Sur les modules STANDARD, il accumule les compteurs d'énergie propres du module.
Si l'énergie est trop basse, cherchez parmi ces causes :
- Caractère de la charge. Le registre de puissance moyenne par période est réellement une puissance moyennée dans le temps sur une période close, et non une valeur instantanée. Une charge pulsée (moteur, compresseur) avec un temps de conduction court dans la période de 60 secondes donne une moyenne inférieure à sa puissance de crête.
- Placement de la pince et calibrage de la charge. Si le modèle CT d'usine (
ct_model:) ne correspond pas à la réalité, les plages de coefficients seront décalées. Vérifiez quect_model:dans le YAML correspond à la pince physique sur le conducteur. - Niveau firmware BASIC. Sur la référence BASIC, les échantillons P par fenêtre sont ramenés à 0 avant intégration. Si la charge a une composante régénérative (par exemple un moteur de pompe avec force contre-électromotrice), BASIC sous-compte.
4. Intégration Home Assistant
HA affiche « Unavailable » pour tous les capteurs rbamp
Ce que vous voyez dans HA : toutes les entités sensor.rbamp_* affichent « Unavailable ».
Causes et corrections :
- ESP32 hors ligne. Exécutez
esphome logs --device— si vous ne pouvez pas vous connecter, l'ESP32 est hors ligne. Vérifiez les identifiants WiFi et le point d'accès de secours s'il est configuré. -
Connexion API perdue. L'API native ESPHome (port 6053) peut être bloquée par un pare-feu. Vérifiez que l'ESP32 est joignable par IP :
ShellpingSi le ping réussit mais que HA affiche toujours « indisponible », l'intégration ESPHome dans HA doit être supprimée puis rajoutée (Paramètres → Intégrations → ESPHome → Supprimer, puis redécouvrir).
-
Discordance de clé de chiffrement de l'API. Si
api: encryption: key:est configuré dans le YAML, l'intégration HA doit connaître la même clé. Une discordance fait considérer l'appareil comme hors ligne par HA. Supprimez puis rajoutez l'intégration après avoir mis à jour la clé. - mDNS ne fonctionne pas dans votre topologie réseau. Si l'ESP32 est sur un VLAN différent de HA, le multicast mDNS peut ne pas franchir la frontière. Ajoutez l'appareil par IP manuellement dans l'intégration ESPHome.
Le flash OTA échoue
Ce que vous voyez :
ERROR Error resolving IP address: ...
# or
ERROR Upload Failed
Causes fréquentes :
- L'adresse IP a changé. L'ESP32 a obtenu un nouveau bail DHCP. Vérifiez la table DHCP du routeur, repérez l'appareil par son adresse MAC et attribuez une IP statique, ou utilisez la clé YAML
wifi: use_address:. -
L'ESP32 est en mode sans échec. Après trois démarrages échoués d'affilée, ESPHome passe en mode sans échec (aucun composant personnalisé, seulement WiFi + OTA). L'OTA en mode sans échec fonctionne, mais l'appareil exécute un firmware allégé. Le marqueur dans
esphome logs:Text[I][safe_mode:xxx]: Entering safe modeForcez un démarrage propre : maintenez le bouton BOOT à la mise sous tension, ou ajoutez
safe_mode: num_attempts: 10pour élargir le seuil. -
Le port 3232 (OTA) est bloqué. Le protocole OTA utilise TCP 3232. Vérifiez qu'aucune règle de pare-feu ne le bloque entre la machine qui exécute
esphome run(ou l'hôte HA) et l'IP de l'ESP32. - Un firmware volumineux après l'ajout de rbamp. Le premier OTA après l'ajout d'un composant externe peut dépasser la taille de la partition OTA sur la disposition ESP32 4 Mo par défaut. Vérifiez les avertissements de taille binaire dans la sortie de
esphome compileet passez à une disposition à partition OTA plus grande si nécessaire.
OTA juste après le provisionnement new_address: : le provisionnement ne se charge pas
Symptôme : après un premier démarrage réussi avec la clé new_address: (le journal affiche Address change SUCCESS, new address 0x51), l'OTA suivant échoue avec une erreur de compilation ou un avertissement d'exécution address 0x50 NACK.
Ce qui s'est passé : le module se trouve désormais à la nouvelle adresse (0x51), mais le YAML pointe encore sur l'ancienne (address: 0x50). Au prochain update(), le composant essaie 0x50, n'obtient rien et journalise des NACK constants. L'OTA lui-même n'échoue pas réellement ici — c'est un symptôme voisin : vous voyez un flot d'erreurs rbamp dans esphome logs et concluez que l'appareil est défaillant.
Récupération en 3 étapes :
-
Modifiez le YAML :
YAMLrbamp: id: meter1 address: 0x51 # new address — set instead of 0x50 # new_address: 0x51 # ← REMOVE this line. Do not comment it out, # delete it entirely, otherwise the component # tries to provision again and logs a warning update_interval: 60s ct_model: SCT_013_030 -
Lancez
esphome run(via la CLI) ou Compile + Upload (via l'Add-on HA). Le nœud reçoit le nouveau binaire par OTA sur WiFi. -
Ouvrez
esphome logset vérifiez que le message de démarragedump_configaffiche la bonne adresse et queupdate()s'exécute sans NACK.
Règle — new_address: est une opération de provisionnement unique. Une fois que le module a migré vers la nouvelle adresse et l'a sauvegardée en flash, la clé doit être supprimée du YAML. Sinon, à chaque démarrage le composant tentera de reprovisionner (sur v1.2+ le module ignore l'écriture répétée, mais l'avertissement reste dans le journal et encombre la notify de HA).
Si le module ne répond à aucune adresse après le changement, voir « Adresse modifiée mais le module ne répond pas » ci-dessus.
5. Compilation et chaîne d'outils
Erreur de compilation : 'esphome/core/component.h' file not found
Ce que vous voyez dans VS Code / clangd : des soulignements rouges partout dans rbamp.h et rbamp.cpp. Fenêtre :
'esphome/core/component.h' file not found
Signification : clangd (l'IntelliSense C++ de VS Code) n'accède pas aux chemins d'inclusion ESPHome + PlatformIO. Le système de compilation les résout correctement pendant esphome compile ; clangd non.
Ce n'est pas une erreur de compilation. Si esphome compile example/ui1.yaml passe sans erreur, le code est correct.
Pour supprimer les soulignements rouges : créez un fichier .clangd dans le répertoire du composant, pointant vers les chemins d'en-têtes générés par la compilation ESPHome (.esphome/build/). C'est purement cosmétique et facultatif.
PlatformIO plante avec 0xC0000001D (EXCEPTION_ILLEGAL_INSTRUCTION)
Ce que vous voyez :
Error: Failed to install Python dependencies (exit code: 3221225501)
(0xC0000001D = 3221225501 en décimal)
Signification : PlatformIO 6.1.19+ utilise le binaire Rust uv pour installer les dépendances Python dans son penv interne. Sur certains processeurs Intel portables récents, uv plante avec EXCEPTION_ILLEGAL_INSTRUCTION à cause d'une incompatibilité du jeu d'instructions. Cela touche l'étape penv_setup.py install sur une installation fraîche de PlatformIO.
Contournement (préinstaller toutes les dépendances via pip, en contournant uv) :
# Step 1: install the ESP32 platform's Python dependencies directly
& "$env:USERPROFILE\.platformio\penv\Scripts\python.exe" -m pip install `
"littlefs-python>=0.16.0" "fatfs-ng>=0.1.14" "pyyaml>=6.0.2" `
"rich-click>=1.8.6" "zopfli>=0.2.2" "intelhex>=2.3.0" "rich>=14.0.0" `
"cryptography>=45.0.3" "certifi>=2025.8.3" "ecdsa>=0.19.1" `
"bitstring>=4.3.1" "reedsolo>=1.5.3,<1.8" "esp-idf-size>=2.0.0" `
"esp-coredump>=1.14.0" "pyelftools>=0.32"
# Step 2: bootstrap the nested ESP-IDF venv (see the next entry)
& "$env:USERPROFILE\.platformio\penv\.espidf-5.5.4\Scripts\python.exe" `
-m ensurepip --default-pip
& "$env:USERPROFILE\.platformio\penv\.espidf-5.5.4\Scripts\python.exe" `
-m pip install -r `
"$env:USERPROFILE\.platformio\packages\framework-espidf\tools\requirements\requirements.core.txt"
Une fois ces paquets installés, get_packages_to_install() dans penv_setup.py renvoie une liste vide et l'installation pip via uv n'est plus appelée. Les exécutions suivantes de esphome compile fonctionnent normalement.
Le contournement doit être réappliqué après une nouvelle installation de PlatformIO ou après avoir vidé le cache ~/.platformio.
venv ESP-IDF : aucun module idf_component_manager
Ce que vous voyez :
ModuleNotFoundError: No module named 'idf_component_manager'
Cela apparaît à la première esphome compile sur une machine où PlatformIO a téléchargé le framework ESP-IDF sans exécuter l'amorçage complet de ses prérequis.
Signification : le framework ESP-IDF de PlatformIO est installé dans le venv imbriqué ~/.platformio/penv/.espidf-5.5.4/ (le numéro de version peut varier). Ce venv a besoin de requirements.core.txt du paquet du framework. Lorsque le contournement uv ci-dessus est appliqué, l'étape 2 amorce pip dans le venv et installe les prérequis.
Si l'erreur apparaît après l'application du contournement uv mais que l'étape 2 a été sautée :
# Find the IDF venv (the version number may differ):
ls "$env:USERPROFILE\.platformio\penv\" | Where-Object { $_.Name -like ".espidf-*" }
# Bootstrap pip into the IDF venv:
& "$env:USERPROFILE\.platformio\penv\.espidf-5.5.4\Scripts\python.exe" `
-m ensurepip --default-pip
# Install the IDF core requirements:
& "$env:USERPROFILE\.platformio\penv\.espidf-5.5.4\Scripts\python.exe" `
-m pip install -r `
"$env:USERPROFILE\.platformio\packages\framework-espidf\tools\requirements\requirements.core.txt"
Remplacez 5.5.4 par le numéro de version de votre IDF (vérifiez dans ~/.platformio/penv/).
esphome compile échoue : get_object_id_hash introuvable
Ce que vous voyez :
error: 'class esphome::rbamp::RbAmpComponent' has no member named 'get_object_id_hash'
Ce que cela signifie : une ancienne version de rbamp.cpp appelait this->get_object_id_hash() pour initialiser l'emplacement NVS. Cette méthode a été supprimée de PollingComponent dans ESPHome 2025.x.
Correction : mettez le composant à jour vers la version actuelle. Le code récent utilise une génération de hachage compatible avec ESPHome 2025.x et ultérieur.
ESPHome trop ancien — set_i2c_address introuvable
Ce que vous voyez :
error: 'class esphome::i2c::I2CDevice' has no member named 'set_i2c_address'
Signification : le flux de changement d'adresse new_address: appelle i2c::I2CDevice::set_i2c_address(), que les anciennes versions d'ESPHome ne possèdent pas.
Correction : mettez à jour vers ESPHome 2025.3.0 ou ultérieur. L'Add-on HA ESPHome suit automatiquement la version courante — c'est le chemin d'installation recommandé.
# If using a local Python venv:
pip install --upgrade esphome
6. Identité / capacité / erreur (v1.3)
Cette section explique ce que signifient les valeurs individuelles des entités d'identité (un text_sensor de modèle via lambda:), le bitmap de capacités et les codes REG_ERROR ajoutés en v1.3.
Les lectures d'identité renvoient « UNK » / « UNREADABLE »
Ce que vous voyez (text_sensor template) :
text_sensor:
- platform: template
name: "Meter variant"
lambda: 'return id(my_meter).get_variant_str();' # → "UNK" in HA
[D][rbamp:xxx]: get_variant_str(): REG_HW_VARIANT read failed (NACK) — returning UNK
Signification :
-
"UNK"— le composant n'a pas pu lireREG_HW_VARIANT(0x55) après toutes les tentatives. Causes : le module est sur un firmware hérité (v1.0–v1.1, avant la détection de variante), ou bus I²C marginal avec épuisement des NACK sur ce registre précis. -
"UNREADABLE"— la lecture a renvoyé une valeur hors de0x55..0x5A, au-delà de la plage des codes de variante valides. Cela indique une corruption du firmware ou une collision de registre brute (par exemple un tampon périmé).
Fix:
-
Si le firmware est inférieur à v1.2, la détection de variante n'est pas disponible. Le
text_sensorpublie quand même ; utilisez une indication côté YAML viatopology:ou réinitialisez via un modèle HA. -
Si le firmware est en v1.3+ et que le bus est marginal, voir i2c_master bloqué.
Bitmap CAPABILITY = 0x0000
Ce que vous voyez :
text_sensor:
- platform: template
name: "Meter capability"
lambda: 'return id(my_meter).get_capability_hex();' # → "0x0000"
Signification : le registre de capacités n'existe pas sur ce firmware — il se lit 0 (le comportement standard « registre non implémenté » du firmware rbAmp). Il s'agit du firmware hérité v1.0–v1.2.
Comportement du composant : toutes les fonctions conditionnées par les capacités (GC de flotte, validation d'adresse en deux phases, save_user_config, clear_error) basculent automatiquement sur le chemin hérité :
fleet_gc_enable: true→ avertissement + ignoré (non annoncé par le firmware)new_address:→ repli monophasé, exige le mode provisionnement en usineclear_error()→ repli sur l'opcode fournisseur (au mieux)
Zéro régression : les déploiements v0.4.0 existants continuent de fonctionner sans modification du YAML ni du comportement. C'est le canon C5 — la capacité conditionnée ne casse jamais l'existant.
last_error_str() affiche "ERR_PARAM" après un changement de ct_model: ou sensor_class:
Ce que vous voyez :
[W][rbamp:xxx]: REG_ERROR after CT_MODEL write: 0xFE (DEV_ERR_PARAM)
get_last_error_str() → "ERR_PARAM".
Ce que cela signifie : le firmware a rejeté la valeur écrite. Les déclencheurs les plus fréquents :
-
Un code hors de l'ensemble accepté — pour
SCT_013, les codes acceptés sont{1, 2, 3, 4, 5, 6, 7}. -
Modèle de pince CT absent de l'ensemble autorisé pour la classe — par exemple
WIRED_CT_1avecsensor_class: SCT_013. Voir tableau par classe de 03_sensor_selection.md. -
Code 0 (UNSET) — tentative d'effacer le modèle CT via 0. Non pris en charge ; utilisez
dev.factoryReset()pour une réinitialisation complète.
Récupération : appelez id(my_meter).write_clear_error(); via un service YAML ou via lambda: dans on_boot: pour effacer REG_ERROR + le bit3 de EVENT_FLAGS. Ensuite, vous pouvez réessayer avec une valeur correcte.
api:
services:
- service: my_meter_clear_error
then:
- lambda: 'id(my_meter).write_clear_error();'
Le changement de ct_model: / sensor_class: est refusé (ligne de journal, aucune écriture)
Ce que vous voyez :
[W][rbamp:xxx]: ct_model refused: module is calibrated with its fitted sensor (class N) — ...
[W][rbamp:xxx]: sensor_class refused: module is calibrated with its fitted sensor (class N); ...
Signification : le module a été calibré en couple avec son propre capteur intégré (WIRED_CT / BUILTIN_CT). Écrire une classe ou un modèle générique remplacerait cette calibration individuelle, donc le composant refuse. C'est la protection en écriture, non une panne. Une valeur identique n'est jamais écrite (rien n'est journalisé au niveau avertissement pour ce cas).
Correction : retirez sensor_class: / ct_model: / ct_models: du YAML pour un tel module. Seulement si vous voulez délibérément le préréglage générique, définissez ct_model_force: true avec le modèle, flashez une fois et retirez les deux lignes ensuite (le schéma rejette ct_model_force: sans clé de modèle).
ct_models: non pris en charge par cet appareil (module STANDARD)
Ce que vous voyez :
[W][rbamp:xxx]: ct_models: (per-channel) not supported by this device — it does not advertise persistent per-channel model storage ... Use the global `ct_model:` key. (Keys ignored.)
Ce que cela signifie : le module ne peut pas conserver les modèles par canal à travers une coupure d'alimentation ; les écrire ferait donc revenir silencieusement à l'ancienne valeur. Le composant refuse plutôt que de perdre la valeur.
Correction : utilisez la clé unique ct_model: pour tous les canaux.
Changer ct_model: redémarre le module une fois
Sur les modules SCT avec firmware jusqu'à 1.4.19, changer de calibre se termine par un redémarrage du module (sauvegarde, réinitialisation, réidentification). Le journal affiche le redémarrage puis, ensuite, que courant, puissance et énergie sont mis à l'échelle du nouveau calibre ; les capteurs peuvent sauter un update() entre-temps. Cela fait partie du déroulement normal. Le firmware 1.4.20 et ultérieur effectue le changement sur le module, et aucun redémarrage n'a lieu. Si le journal indique que le gain appliqué est hors de la plage attendue, le composant ne met pas à l'échelle ; vérifiez que ct_model: correspond à la pince réellement installée.
Les capteurs de total général / d'angle ne publient jamais
Ce que vous voyez (journal de démarrage) :
[W][rbamp:xxx]: energy_total/energy_net/reactive_energy sensors need on-device energy counters, which this device does not advertise — they will never publish. Per-channel `energy:` keys still work ...
[W][rbamp:xxx]: voltage_angle_*/phase_sequence sensors need a newer device firmware — they will never publish on this device
Signification : le module connecté (ou son firmware) ne fournit pas ces valeurs. Les clés se valident, mais rien n'est publié.
Correction : utilisez les capteurs energy: par canal, ou mettez à jour le firmware du module.
start_current_ua: ignoré
[W][rbamp:xxx]: start_current_ua: not supported by this device firmware — key ignored — le module compte l'énergie à tout courant. La clé n'a d'effet que sur les modules STANDARD disposant de compteurs d'énergie embarqués. Les valeurs autres que 0 ou 10..2540 par pas de 10 sont rejetées à esphome config.
update_interval rejeté
Un update_interval inférieur à 1s est rejeté par le schéma à esphome config. latch_interval ne doit pas être plus court que update_interval.
EVENT_FLAGS bit3 (ERR_LATCH) — comportement de réarmement
Ce que vous voyez : après clear_error(), quelques centaines de millisecondes plus tard, le bit3 de EVENT_FLAGS est de nouveau positionné (réarmement collant).
Signification : le canal d'erreur durable du firmware réarme le bit3 après effacement si la condition d'erreur d'origine n'a pas été résolue. C'est voulu — le maître peut manquer le premier effacement et ne doit pas supposer que l'erreur a disparu à jamais si le paramètre est toujours incorrect.
Correction : une récupération complète exige deux étapes :
- Supprimez la cause (remplacez le mauvais code de modèle CT, corrigez le YAML).
write_clear_error()— cet appel efface à la foisREG_ERRORet le bit3 deEVENT_FLAGSen une seule opération.
Si le bit3 se réarme en permanence, le paramètre est toujours erroné ; relisez get_last_error_str() pour savoir exactement ce que le firmware rejette.
Source et signalements : rb-amp/rbamp-esphome · cette page dans le dépôt : docs/10_troubleshooting.md (v1.9.1)