10 · Dépannage
Ce chapitre est organisé par le symptôme observé, et non par classification interne des erreurs. Si vous êtes ici, quelque chose ne fonctionne pas correctement. Trouvez 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 :
-
Niveau bus — le module ne répond pas sur I²C ; les lectures lèvent
RbAmpIOError. -
Niveau 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 dérive, le script se bloque ou meurt sur timeout.
Raccourci pour les pressés : en régime établi, les méthodes publiques doivent renvoyer des valeurs ou produire des instantanés sans lever d'exception. Si vous voyez souvent RbAmpIOError ou RbAmpStaleError dans les journaux, allez directement à « Le module ne répond pas sur I²C » ci-dessous.
Le module ne répond pas sur I²C
Ce que vous voyez : dev.begin() (ou l'entrée dans le gestionnaire de contexte with RbAmp(bus, 0x50) as dev:) lève RbAmpIOError ou RbAmpVersionError, ou les lectures temps réel lèvent régulièrement RbAmpIOError.
Étape 1 — Scan du bus
Vérifiez d'abord que le module est bien présent sur le bus.
CPython (SBC Linux)
Outil externe :
i2cdetect -y 1 # bus 1 — the standard one on the RPi 40-pin header
Ou en Python :
from smbus2 import SMBus
with SMBus(1) as bus:
print("Scanning...")
for addr in range(0x08, 0x78):
try:
bus.write_quick(addr)
print(f"Found 0x{addr:02X}")
except OSError:
pass
Sortie attendue : Found 0x50 (ou une autre adresse, si vous l'avez modifiée).
MicroPython
from machine import I2C, Pin
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
print("Found:", [hex(a) for a in i2c.scan()])
Sortie attendue : Found: ['0x50'] (ou votre adresse).
Que faire 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 GPIO par défaut de chaque hôte).
-
Les deux lignes ont une pull-up vers 3.3 V (la carte du module intègre des résistances de 4.7 kΩ — aucune résistance externe n'est nécessaire pour un seul module).
-
La broche d'alimentation du module lit en réalité 5 V (4.5–5.5 V).
-
Aucun autre maître (sonde de débogage, second contrôleur) n'occupe les mêmes lignes.
-
Sous MicroPython, vérifiez que
freq=50_000(ni 100k ni 400k — sur ESP32 + firmware v1, le motif de NACK de base consommerait le budget de nouvelles tentatives). -
Sur CPython, vérifiez que le pilote I²C du noyau est activé —
lsmod | grep i2c_bcmsur le RPi.
Que faire si le module apparaît à une adresse inattendue
Quelqu'un l'a réadressé plus tôt sur le banc. Mettez à jour le second argument de RbAmp :
dev = RbAmp(bus, 0x52) # address from the bus scan
Étape 2 — schéma NACK de référence MicroPython + ESP32
Si le scan du bus trouve le module mais que dev.read_voltage() lève périodiquement RbAmpIOError — et que vous êtes sur MicroPython + ESP32 — il s'agit d'un schéma de référence documenté : la pile I²C du portage ESP32 de MicroPython a hérité des particularités du pilote ESP-IDF v5, qui, face à rbAmp sur le firmware actuel, produit des NACK fréquents à 100 kHz.
L'atténuation est déjà intégrée à MachineI2CBackend (3 nouvelles tentatives × intervalle de 5 ms par défaut), mais sous forte charge le budget de nouvelles tentatives peut s'épuiser.
Que faire sur ESP32 :
- Abaissez la vitesse du bus à 50 kHz :
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
- Augmentez le nombre de tentatives pour une charge lourde — cela nécessite l'API avancée, via la création explicite du backend :
from rbamp._io_micropython import MachineI2CBackend
from rbamp import RbAmp
backend = MachineI2CBackend(i2c, retry_attempts=5, retry_gap_ms=5)
dev = RbAmp(backend, 0x50) # the address goes to RbAmp, not to the backend
- Surveillez le compteur d'épuisement des tentatives — il doit rester à zéro en régime permanent :
if backend.retry_exhaustion_count > 0:
print("WARN: retry exhausted:", backend.retry_exhaustion_count)
Étape 3 — Plateformes non ESP32 (RP2040 / STM32 / CPython)
Sur RP2040 / STM32 / Pyboard (via MicroPython) il n'y a pas de motif de NACK de base — ces plateformes affichent un taux de NACK d'environ 0 % avec rbAmp. MachineI2CBackend détecte automatiquement le port et ramène la valeur par défaut des nouvelles tentatives à 1.
Sur CPython (via smbus2) il n'existe aucune couche de nouvelle tentative — le pilote I²C du noyau Linux n'est pas sujet au schéma NACK ; une seule OSError de smbus2 est traduite en RbAmpIOError, sans nouvelle tentative.
Si des NACK surviennent sur ces plateformes, recherchez :
-
Capacité de bus élevée — fils longs + nombreux appareils. Abaissez la vitesse ou raccourcissez le câble.
-
Contention maître — le paquet ne prend pas en charge le multi-maître.
- Un SCL flottant entre les transactions — une résistance de rappel manquante.
- Sur le RPi : vérifiez
dtparam=i2c_arm_baudratedans/boot/config.txt— 100000 est recommandé.
PermissionError: [Errno 13] sur /dev/i2c-1 (Linux)
Ce que vous voyez : SMBus(1) lève PermissionError, alors que sudo python fonctionne. Votre utilisateur n'est pas autorisé à ouvrir le périphérique I²C. Correction :
sudo usermod -aG i2c $USER # then log out and in again
Vérifiez aussi que l'I²C est activé (sudo raspi-config → Interface Options → I2C) et que ls /dev/i2c-* liste le bus ; sudo apt install i2c-tools vous donne i2cdetect -y 1.
Le courant lit zéro sur une charge en marche
Ce que vous voyez : dev.current[0] (ou dev.read_current(0)) renvoie 0.000 (ou une valeur très faible) alors qu'une vraie charge est allumée (une bouilloire, une lampe, un fer). dev.power_factor[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 :
from rbamp import RbAmp, RbAmpError, RbAmpSensorClass, RbAmpModeError
try:
dev.set_sensor_class(RbAmpSensorClass.SCT_013)
except RbAmpError as e:
print("set_sensor_class failed:", e)
try:
dev.set_ct_model(3) # or your model — see the table in 03
except RbAmpModeError:
print("Class must be set first!")
except ValueError:
print("Code not in per-class accept-set (SCT_013: {1,2,3,4,5,6,7})")
Sans ces deux appels, les coefficients d'étalonnage ne sont pas chargés, et le courant est toujours lu comme nul. Cette étape se fait une seule fois lors de la première installation — le choix est enregistré en flash du module.
- 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) produira un signal à la limite du bruit de fond et les lectures seront nulles. Choisissez le modèle de CT le plus petit couvrant votre courant maximal attendu. Le tableau complet est dans 03 · Sélection du capteur de courant.
Si vous avez un module multi-canaux (UI2 / UI3 / UI5 / UI7) et que vous voulez voir à la fois les petites charges et les pics, envisagez le schéma à double CT : une petite pince (SCT-013-005) sur un canal pour la plage basse + une grande (SCT-013-030/100) sur un autre canal pour la plage haute ; le maître choisit la valeur par seuil. Le schéma est traité dans 03 · Choix du capteur de courant, section « Topologie à double CT ».
- 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 »,
dev.read_current()donnera la bonne valeur en absolu, maisdev.read_power()donnera une valeur négative sur une charge consommatrice. Confirmation —dev.read_power_factor()affichera exactement −1.0 sur une charge résistive (au lieu de +1.0). Correction : soit remettre physiquement la pince dans le bon sens (la déclipser, retourner la flèche, la reclipser), soit inverser le signe côté application (p = -p; pf = -pf;si vous savez que la charge n'est pas un onduleur PV).
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 un courant circule réellement — mesurez-le avec un multimètre (une pince DC / pince AC) 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, le fil sous tension (L), et non le câble entier (serrer L et N lit ~0).
Les lectures sautent ou lèvent RbAmpIOError
Ce que vous voyez : dev.voltage / dev.read_current(...) lève périodiquement RbAmpIOError. La valeur de la propriété n'a pas été obtenue — il faut une nouvelle tentative côté application ou une garde try/except.
RbAmpIOError du paquet couvre deux classes de problèmes :
- NACK après épuisement des nouvelles tentatives — la liaison est instable.
- Le filtre de cohérence a rejeté la valeur — un
NaN/Infflottant /|x| > 10000(clairement pas une valeur physique) est sorti du bus.
Distinguez-les par les compteurs de diagnostic (disponibles sur MicroPython) :
from rbamp._io_micropython import MachineI2CBackend
# Build the backend yourself, then pass IT (not the raw I2C object) to RbAmp.
# This is where `backend` comes from; the address belongs to RbAmp.
backend = MachineI2CBackend(i2c, retry_attempts=5)
dev = RbAmp(backend, 0x50)
# After a period of operation:
print("retries succeeded:", backend.retry_count_total)
print("retries exhausted:", backend.retry_exhaustion_count)
print("sanity rejects:", dev.sanity_reject_count)
| Compteur | Ce que cela signifie |
|---|---|
retry_count_total ↑, retry_exhaustion_count = 0, sanity_reject_count = 0 |
Le bus est sain ; le paquet rattrape discrètement les rares NACK. Normal. |
retry_count_total ↑, retry_exhaustion_count ↑ |
Plateau de NACK — augmentez retry_attempts (voir l'étape 2 ci-dessus). |
retry_count_total faible, sanity_reject_count en hausse |
Le filtre de cohérence capte des données parasites après des nouvelles tentatives échouées. Augmentez retry_attempts=5+. |
Sous CPython (SMBusBackend) il n'y a pas de couche de nouvelles tentatives — RbAmpIOError est levée dès le tout premier échec. Les symptômes sont rares (le noyau Linux est en général fiable), mais s'ils apparaissent, vérifiez le câblage, les tirages et la vitesse du bus.
Le facteur de puissance semble étrange
Ce que vous voyez : dev.power_factor[0] (ou dev.read_power_factor(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, compresseur de moteur | +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 à I = 0
Le PF est défini comme P / (U × I). À courant nul I=0, le calcul est indéfini. La valeur exacte 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'un courant apparaît, un PF valide apparaît.
PF strictement −1.0 sur une charge purement consommatrice
La pince est installée « à l'envers » — la flèche ne pointe pas dans le sens du courant vers la charge. Correction : soit remettre la pince correctement, soit gérer le signe côté application (p = -p; pf = -pf; si vous savez que la charge ne peut pas être un onduleur PV).
PF oscille entre +0.3 et +0.7 sur une charge résistive
-
Cause possible : la pince CT est placée sur un fil d'une phase différente de celle à laquelle l'entrée U du module est connectée. Dans un tableau de distribution polyphasé, il est facile de serrer la mauvaise phase par erreur — un déphasage de 120° ou 180° entre U et I donnera exactement ces valeurs de PF. La solution est d'installer le module pour que l'entrée U et la pince soient sur la même phase.
-
Alternative : la charge n'est vraiment pas purement résistive. Refaites le test avec une charge connue résistive (une bouilloire électrique à pleine puissance).
Les instantanés de période lèvent toujours RbAmpStaleError
Ce que vous voyez : dev.read_period_snapshot() lève RbAmpStaleError à chaque appel. Cela signifie que le module n'a pas fini d'intégrer la période précédente au moment de la lecture suivante.
Sur une lecture obsolète, le paquet conserve l'horodatage précédent, de sorte que l'instantané valide suivant couvre tout l'intervalle depuis le dernier bon instantané et que le total de Wh reste exact (ni double comptage, ni perte).
Acceptable : rares lectures obsolètes (1–2 par heure à une cadence de 60 s). Inacceptable : lectures obsolètes consécutives — 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 lectures périmées.
-
Vérifiez la réactivité du module entre deux instantanés :
if dev.probe():
print("alive")
- Vérifiez le drapeau directement :
if dev.is_period_valid():
# avg_p[] can be read
...
- Vérifiez la version du firmware —
dev.firmware_version >= 0x04(v1.3) a le moins de lectures périmées ;0x02/0x03(v1.1/v1.2) restent pris en charge mais le taux de lectures périmées augmente ;0x01(v1.0) est le plus bruité.
Cas particulier — réveil MicroPython depuis la veille profonde
Si vous utilisez un schéma de deep sleep sur MicroPython, l'appel par défaut dev.read_period_snapshot() après l'entrée dans le gestionnaire de contexte donnera toujours un résultat obsolète (ou proche de zéro) — __enter__ prend un instantané (commande LATCH) qui sert d'amorce et réinitialise l'accumulateur du firmware. Le schéma canonique utilise skip_latch=True + une durée de sommeil connue (l'argument machine.deepsleep(SLEEP_MS)) — voir 06 · Exemples, scénario 9.
La comptabilité des Wh dérive de la référence
Ce que vous voyez : dev.energy.wh(0) après plusieurs heures ou jours de fonctionnement dérive du relevé du compteur d'énergie 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
dev.set_sensor_class()etdev.set_ct_model()sont 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 obsolètes écartés : si
dev.energy.wh(0)est systématiquement inférieur à la référence, il peut s'agir d'intervalles manqués. Un seul instantané obsolète ne fait pas perdre d'énergie (le bon suivant couvre tout l'intervalle), mais des échecs répétés ou un script qui n'a pas tourné, si. Vérifiez la cadence (voir ci-dessus). -
Dérive de l'horloge maître :
time.monotonic()(CPython) ettime.ticks_ms()(MicroPython) sont fiables en fonctionnement normal. Mais si le maître passe en veille profonde, utilisez le motif mémoire RTC + durée de veille connue du scénario 9.
⚠ ticks_ms() : débordement sur MicroPython. time.ticks_ms() revient à zéro à 2**30 ms (~12.4 jours) — une simple soustraction t1 - t0 à cheval sur la limite de 12.4 jours donne un nombre négatif ou énorme. En interne, le paquet utilise time.ticks_diff(t1, t0), sûr vis-à-vis du débordement. Si vous calculez vous-même master_dt_ms dans votre code (hors du paquet), utilisez ticks_diff, et non une soustraction directe.
Précision de l'accumulateur
L'accumulateur de Wh dans le handle :
| Exécution | Type |
|---|---|
| CPython | float 64 bits (float Python) |
| MicroPython (build à double précision) | float sur 64 bits |
| MicroPython sur les ports sans double précision | float 32 bits |
Vérifier la précision sous MicroPython (sys.float_info n'existe que sous CPython ; sur uPy, nous utilisons une vérification empirique) :
# On CPython:
import sys
print(sys.float_info.dig) # 15 → double; 7 → single
# On MicroPython — empirically:
import sys
print(sys.implementation.name) # 'micropython'
test = 1.0 + 1e-15
print("double" if test != 1.0 else "single") # 1.0 + 1e-15 != 1.0 only on double
Pour les installations de longue durée sur des ports MicroPython à flottant simple précision, réinitialisez périodiquement dev.energy.reset(0) et conservez le total à long terme dans votre propre stockage persistant (par exemple via un message MQTT retain dans HA).
Le script se bloque ou meurt sur dépassement de délai
Ce que vous voyez : le script Python démarre normalement, puis se bloque ou lève RuntimeError après quelques minutes.
MicroPython sur ESP32 : une opération I²C se bloque sur un bus limite — atténuation en trois couches
Ce que vous voyez précisément : un script sur ESP32 (MicroPython machine.I2C) interroge correctement rbAmp pendant plusieurs minutes, puis se bloque « mort » au milieu d'un appel dev.read_period_snapshot() / fleet.poll_all(). Le WDT (si vous en avez un activé) détecte le blocage ; sinon le script cesse simplement de répondre. Si vous avez un REPL, il se bloque aussi.
Ce qui se passe : le machine.I2C de MicroPython sur ESP32 encapsule le même pilote i2c_master IDF que celui qu'utilisent les projets ESP-IDF natifs. Sur un bus limite (tirages faibles, pistes longues, EMI, bruit ZC), SDA/SCL peuvent momentanément « se bloquer » dans un état indéfini. Avant la transaction suivante, i2c_master d'IDF tourne dans une boucle i2c_ll_is_bus_busy en attendant la libération du bus — cette attente n'est pas bornée par le délai I²C de la bibliothèque.
Ce n'est pas un « artefact réservé au débogueur ». Validé sur banc (inter-bibliothèques, même banc 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 tirage externe de 4.7 kΩ sur SDA/SCL du DUT | 0 blocages (test de longue durée de 12 min, 0 redémarrage) |
La corrélation est nette — une correction de l'intégrité du bus supprime complètement le blocage. La logique de la bibliothèque n'est pas en cause.
Atténuation en trois couches (appliquez les trois couches) :
-
Tirage externe (~4.7 kΩ) sur SDA et SCL vers 3.3 V en un seul point du bus. Les tirages internes de l'ESP32 (~45 kΩ) sont faibles pour un bus multi-modules de longueur réelle, tandis que les tirages de 4.7 kΩ intégrés aux modules, en parallèle, deviennent trop forts. Sur un tel bus, coupez les tirages intégrés sur tous les modules sauf un. Voir 04 · Câblage, section « Bus multi-modules — la topologie principale ».
-
N'exécutez pas une version 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éfini au détachement/rattachement, provoquant un blocage du bus à la transaction suivante.
-
Un WDT de tâche au niveau applicatif sur la tâche d'interrogation — défense en profondeur. Des tirages de bus corrects sont la correction de terrain ; le WDT de tâche est une posture de récupération.
# MicroPython-on-ESP32
from machine import WDT
import time
wdt = WDT(timeout=8000) # 8 s
while True:
snap = dev.read_period_snapshot()
# ... processing ...
wdt.feed() # "I'm alive" — every cycle
time.sleep_ms(200)
Ce qu'il NE FAUT PAS faire : n'essayez pas de contourner le problème avec un paramètre I2C(..., timeout=ms) plus grand — il ne borne pas l'attente préalable de bus occupé, c'est un autre chemin de code dans le pilote IDF. Ce qu'il faut corriger, c'est l'intégrité du bus (couche 1) et le superviseur (couche 3).
CPython sur SBC Linux : le bus I²C du noyau n'a pas ce problème
Les pilotes du noyau Linux (i2c-bcm2835 sur Raspberry Pi, i2c-i801 sur x86, etc.) font leur sondage de bus occupé avec un délai — sur un bus bloqué, ils renvoient IOError(Errno 110: ETIMEDOUT) ou EREMOTEIO au lieu de se bloquer. La bibliothèque encapsule cela dans RbAmpIOError. Par conséquent, l'atténuation en trois couches n'est pas nécessaire sous CPython — Linux s'en charge. Une pince ~4.7 kΩ externe reste souhaitable pour l'intégrité du signal sur un bus long.
latch_ms ne correspond pas à la période de l'horloge murale
latch_ms est un compteur de diagnostic du module ; ne l'utilisez pas pour l'énergie — utilisez l'horloge du maître.
La bibliothèque intègre l'énergie à partir de l'horloge murale du maître : CPython — time.monotonic() ; MicroPython — time.ticks_ms() + time.ticks_diff(). L'intégration côté maître n'ajoute pas d'erreur propre au-delà de la précision de puissance active du module.
Si votre code s'appuie sur snap.latch_ms pour des calculs de sous-période, passez à votre propre time.monotonic() / time.ticks_diff().
RbAmpStaleError à chaque lecture — la bibliothèque conserve l'ancrage automatiquement
Ce que vous voyez : dev.read_period_snapshot() lève périodiquement RbAmpStaleError.
Traitement canonique de dt : sur une lecture obsolète, la bibliothèque Python ne remet pas à zéro l'ancrage interne _last_latch_ms. La lecture valide suivante obtient un master_dt_ms égal à l'intervalle complet depuis l'instantané valide précédent — c'est-à-dire qu'il couvre à la fois la période « perdue » obsolète et la période courante. Le firmware conserve l'accumulateur avg_p à travers un instantané vide (persistance côté firmware) : à l'instantané valide suivant, il s'agit déjà d'une valeur moyennée sur tout l'intervalle. L'intégration des Wh reste exacte — ni double comptage, ni sous-comptage.
Schéma de démarrage à froid (prime-until-valid, budget d'environ 25 nouvelles tentatives suffisant) :
from rbamp import RbAmpStaleError
while True:
try:
snap = dev.read_period_snapshot()
break
except RbAmpStaleError:
time.sleep(3.0)
Après l'amorçage, ignorez simplement RbAmpStaleError s'il est rare ; s'il est fréquent, diagnostiquez la cadence (la section « Les instantanés de période lèvent toujours RbAmpStaleError » ci-dessus).
CPython : signal.SIGTERM / KeyboardInterrupt ne sont pas gérés
Cause : un time.sleep(60) long bloque le gestionnaire de signal. En déploiement de production (systemd), systemctl stop rbamp attend la réponse SIGTERM jusqu'à un délai d'expiration (90 s par défaut) puis tue le processus avec SIGKILL — les Wh peuvent être perdus.
Correction : une boucle sensible aux signaux :
import signal, time
shutdown = False
def on_sig(sig, frame):
global shutdown
shutdown = True
signal.signal(signal.SIGTERM, on_sig)
signal.signal(signal.SIGINT, on_sig)
while not shutdown:
snap = dev.read_period_snapshot()
# ... publish ...
for _ in range(60): # wake on signal every second
if shutdown: break
time.sleep(1)
Ou utilisez asyncio avec un signal_handler — voir la section ci-dessous.
MicroPython (ESP32) : dépassement du chien de garde lors de la connexion Wi-Fi
Cause : une boucle de connexion WiFi sans limite déclenche le chien de garde de tâche après ~5 s (la valeur par défaut).
Correctif : une attente bornée avec un repli par redémarrage :
import network, time, machine
wlan = network.WLAN(network.STA_IF)
wlan.active(True)
wlan.connect("ssid", "pass")
t0 = time.ticks_ms()
while not wlan.isconnected():
time.sleep_ms(100)
if time.ticks_diff(time.ticks_ms(), t0) > 30_000:
machine.reset()
Le broker MQTT se déconnecte
Sous CPython (paho-mqtt) : le keepalive par défaut est de 60 s, mais mqtt.connect() est bloquant et mqtt.loop() doit être appelé dans une boucle d'événements. Utilisez mqtt.loop_start() (un thread en arrière-plan) ou la variante asyncio aiomqtt.
Sur MicroPython (umqtt.simple) : synchrone sans keepalive — il faut appeler mqtt.ping() à la main environ toutes les 30 s. L'alternative est le paquet asynchrone mqtt_as, avec keepalive intégré.
Échec de la négociation TLS (cloud CPython + RPi à peu de RAM)
Rarement un problème sur un Pi de 1 Go de RAM ou plus, mais sur un Pi Zero / Zero W (512 Mo) un handshake TLS avec un grand magasin de certificats peut être tué par l'OOM killer.
Fix:
-
Utilisez une autorité de certification spécifique au lieu du
ca-certificatesdu système — moins de mémoire. -
Réduisez les tampons MQTT.
- Passez à un Pi 3/4/5 pour un déploiement cloud en production.
set_sensor_class() / set_ct_model() lève RbAmpModeError
Ce que vous voyez : l'un des appels de configuration lève RbAmpModeError avec le message :
REG_SENSOR_CLASS is UNSET;
call dev.set_sensor_class(RbAmpSensorClass.SCT_013) first
Cause : set_ct_model[_ch] exige que set_sensor_class() ait été appelé auparavant. C'est une garde volontaire.
Que faire :
from rbamp import RbAmpSensorClass
# Class first — MANDATORY
dev.set_sensor_class(RbAmpSensorClass.SCT_013)
# Then the model
dev.set_ct_model(3) # or per-channel dev.set_ct_model_ch(ch, code)
Pour plus de détails — 03 · Choix du capteur de courant et 09 · Référence API, la section « Configuration des capteurs ».
Depuis la 1.6.0, ces setters sont protégés par une garde de lecture avant écriture :
-
Régler la classe ou le modèle que le module détient déjà est un no-op silencieux (le réappliquer effacerait l'étalonnage des canaux).
-
Sur un module appairé en usine (classe
WIRED_CT/BUILTIN_CT), une autre classe ou un autre modèle est refusé avecRbAmpModeError. Dans un contexte de maintenance, utilisezdev.set_ct_model_ch_force(ch, code).
RbAmpModeError survient aussi depuis dev.factory_reset() et dev.save_gains() (les opérations d'usine exigent le mode usine). Un changement d'adresse sur v1.3 est compatible production et ne lève pas RbAmpModeError.
set_sensor_class() / set_ct_model*() lève RbAmpParamError ou ValueError
Ce que vous voyez : l'appel lève RbAmpParamError (sur CPython il hérite aussi de ValueError par héritage multiple).
Causes possibles :
-
Code de modèle invalide — pour la classe
SCT_013, l'ensemble admis est{1, 2, 3, 4, 5, 6, 7}(les codes 5 et 7 sont les SCT-013-100 et SCT-013-060). Pour les autres classes, voir le tableau des ensembles admis par classe dans 03 · Choisir un modèle SCT-013. Les valeurs hors de l'ensemble admis lèventRbAmpParamError(ValueError). -
Indice de voie invalide dans la forme par voie
dev.set_ct_model_ch(channel, code)— il doit être <dev.channels. -
Une valeur de classe de capteur hors de 0..3. (
WIRED_CT/BUILTIN_CTsont des valeurs valides, mais un module appairé en usine refuse d'être reconfiguré — cela lèveRbAmpModeError, voir ci-dessous.)
Gestion des erreurs : dernière écriture de REG_ERROR + EVENT_FLAGS.bit3 durable (v1.3)
v1.3 : REG_ERROR (0x02) est le résultat de la dernière écriture, non persistant. À chaque écriture de registre, le firmware met reg_error = ERR_OK ; une écriture suivante sans rapport efface l'erreur précédente.
Le signal d'erreur durable = EVENT_FLAGS (0x2A) bit3 — collant (W1C), levé immédiatement à toute écriture ou commande rejetée.
Schéma 1 — capture ponctuelle après opération (le résultat de cette seule opération) :
dev.save_user_config()
dev_err = dev.read_reg(0x02) # IMMEDIATELY, before the next write
Schéma 2 — surveillance durable (canonique pour un fonctionnement de longue durée) :
event_flags = dev.read_reg(0x2A)
if event_flags & (1 << 3):
last_err = dev.read_reg(0x02)
# handle it
dev.write_reg(0x2A, (1 << 3)) # W1C clear bit3
# or dev.clear_error()
⚠ RENVERSEMENT de la documentation initiale « collante » (v1.3). REG_ERROR est le résultat de la dernière écriture, et non un état collant. La persistance est assurée par le bit3 d'EVENT.
⚠ bit3 est un canal asynchrone, pas fait pour la validation synchrone d'écriture : sur une écriture rejetée, bit3 est positionné avec un retard par rapport au retour de la transaction I²C (quelques centaines de millisecondes). Ne sondez pas bit3 juste après une écriture pour connaître le résultat de cette écriture — pour le résultat de votre propre écriture, utilisez le motif 1 (capture ponctuelle de read_last_error(), immédiate) ou la RbAmpParamError levée par le setter. bit3 sert à la surveillance de longue durée de faits asynchrones (durée de fonctionnement, chemin de commande), pas à valider une opération qui vient d'être effectuée.
Mise en garde : DEV_ERR_CLONE (0xF9) n'est pas effacé par CMD_CLEAR_ERROR — c'est une sentinelle anti-clone.
Un module fraîchement flashé 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 des paramètres n'est pas initialisée → les valeurs d'usine sont chargées. C'est NORMAL pour un module vierge, pas fatal.
Correction : configurez sensor_class + ct_model + (facultativement) l'adresse, puis dev.save_user_config(). Après un SAVE réussi → REG_ERROR = 0x00, bit3 effacé.
Lectures en échec pendant la commutation de charges à relais (transitoires électromagnétiques)
Ce que vous voyez : dev.voltage / dev.current() lèvent périodiquement RbAmpIOError / OSError — mais seulement pendant une commutation active d'une charge à relais ou inductive sur le même montage. Les lectures en régime établi sont fiables.
Cause (C.12 confirmée sur matériel) : pendant la commutation de relais (charge de 5 A), l'EMI fait échouer environ 67 % des transactions I²C. Le bus se rétablit seul, aucun blocage ne survient et aucun module n'est perdu.
Correctif — nouvelle tentative au niveau de l'application :
def robust_read_voltage(dev, attempts=5, gap_s=0.020):
for _ in range(attempts):
try:
return dev.voltage
except (RbAmpIOError, OSError):
time.sleep(gap_s)
raise RbAmpIOError("read failed after retries")
⚠ La nouvelle tentative du backend ne suffit pas à elle seule : lorsqu'une perturbation EMI dépasse la fenêtre de nouvelles tentatives du backend, il faut une nouvelle tentative explicite au niveau applicatif, avec une pause.
commit_address_change() lève RbAmpIOError après une réinitialisation du bus
Ce que vous voyez : prepare_address_change() a réussi, mais après la validation et la réinitialisation le module ne répond pas à la nouvelle adresse.
✅ v1.3 : REG_I2C_ADDRESS (0x30) lit l'adresse active au démarrage. Après le redémarrage consécutif au commit, lire 0x30 à la nouvelle adresse renverra cette même adresse — ce qui confirme que le commit a abouti. Si le module ne répond pas à la nouvelle adresse, essayez un scan du bus via _io_smbus (il indiquera à quelle adresse se trouve réellement le module).
Pour en savoir plus sur le commit en deux phases — voir 09 · Référence API et 04 · Câblage.
commit_address_change() lève RbAmpTimeoutError
Si prepare a réussi mais que commit lève RbAmpTimeoutError, la fenêtre d'« armement » a expiré (5 secondes après prepare). dev.probe() n'aidera pas ici (le module répond ; le problème est dans la machine d'état du module). La solution est de rappeler dev.prepare_address_change(new_addr), puis d'appeler immédiatement, dans la même fonction ou itération, sans appel réseau entre les deux, dev.commit_address_change(). Toute E/S bloquante entre prepare et commit (WiFi, MQTT, HTTP) est la principale cause de l'expiration de la fenêtre.
wait_ready() lève RbAmpTimeoutError
Le bit « prêt » du module n'a pas été activé dans timeout_ms. Causes possibles :
-
Le module n'a pas fini son démarrage à froid (~250 ms) — augmentez
timeout_msou répétez l'appel. -
Le module ne répond pas sur I²C — voir la section « Le module ne répond pas sur I²C » ci-dessus.
-
Le niveau d'alimentation est passé sous 4.5 V — vérifiez
VCCau multimètre.
Pour en savoir plus sur les méthodes publiques mais signalées — voir 09 · Référence API, la section « Configuration des capteurs » (la sous-section de changement d'adresse s'y trouve avec save_gains et factory_reset).
RbAmpNotSupportedError (appels STD)
Ce que vous voyez : un appel comme dev.read_std_energy(), dev.read_voltage_angle(), dev.read_phase_sequence(), dev.get_start_current() ou dev.set_time() lève RbAmpNotSupportedError.
Causes et que faire :
-
Le module est un module BASIC. Les appels réservés au STD ne sont pas disponibles sur BASIC. Vérifiez
dev.is_std; sur BASIC, utilisez les lecteurs communs (voltage,current,power,power_factor,frequency) et l'API de période à la place. -
L'image du module est trop ancienne pour cette fonction. Les compteurs d'énergie en micro-unités, les angles de tension et le courant de démarrage exigent une image de module assez récente ; sur une image plus ancienne, l'appel signale « non disponible ». Les lectures communes continuent de fonctionner.
-
dev.is_stdvautFalsesur un module STD. La bibliothèque détecte la gamme à l'aide d'une transaction de bus 16 bits ; un objet bus ou un adaptateur incapable de la faire est traité comme BASIC. Utilisezsmbus2sous CPython (validé), et voir 04 · Matériel.
Le même câblage I²C s'applique aux deux gammes de modules. Notez que les fonctions d'énergie embarquée, d'angle et de courant de démarrage sont validées sur CPython ; le chemin 16 bits MicroPython n'est pas encore validé sur matériel.
Tableau récapitulatif des exceptions
RbAmpError (sous-classe de OSError) est la classe de base. Un gestionnaire except OSError: existant côté application continue d'intercepter les erreurs rbAmp sans modification — la convention Python standard pour les pilotes d'E/S matérielles.
| Exception | Quand | Où regarder |
|---|---|---|
RbAmpIOError |
NACK après nouvelle tentative ; rejet de cohérence ; panne au niveau du bus | la section « Le module ne répond pas sur I²C » |
RbAmpTimeoutError |
wait_ready() a expiré ; la fenêtre commit_address_change (5 s) a expiré |
la section « commit_address_change renvoie RbAmpTimeoutError » ci-dessous |
RbAmpNotReadyError |
(réservé ; non levé par la bibliothèque, exporté pour la compatibilité future) | si vous interceptez ce type — reproduisez-le dans un ticket |
RbAmpStaleError |
instantané de période obsolète | la section « Les instantanés de période lèvent toujours RbAmpStaleError » |
RbAmpParamError (sur CPython aussi ValueError) |
argument incorrect : dev=None, ch hors plage, code absent de l'ensemble d'acceptation de la classe (pour SCT_013 — {1, 2, 3, 4, 5, 6, 7}), une cls réservée. Également une violation de précondition : set_ct_model*() sans set_sensor_class() préalable |
vérifiez les arguments d'appel et que set_sensor_class() a été appelé |
RbAmpModeError |
fonctionnement réservé à l'usine (mode usine non activé ; un changement d'adresse sur v1.3 est admis en production) ; classe de capteur non définie ; un module appairé en usine refuse un changement de classe ou de modèle | vérifiez le drapeau de mode ; set_sensor_class() d'abord ; set_ct_model_ch_force() pour un usage de maintenance |
RbAmpNotSupportedError |
Appel réservé au STD sur un module BASIC, ou fonction STD que l'image du module ne fournit pas | la section « RbAmpNotSupportedError » ci-dessous |
RbAmpVersionError |
REG_VERSION = 0/0xFF sur begin() (le module ne répond pas ou le firmware est corrompu). set_ct_model_ch par canal sur v1.0/v1.1 peut recevoir un NACK (le code opération n'existe pas) et lever RbAmpIOError, et non RbAmpVersionError — le garde de version n'est PAS implémenté côté client ; vérifiez dev.firmware_version ≥ 0x03 avant l'appel |
vérifiez dev.firmware_version |
Toutes les exceptions ont un message __str__ explicite — le paquet construit soigneusement les messages d'erreur avec leur contexte.
Tableau récapitulatif des compteurs de diagnostic
Dans un essai de longue durée sain (le banc de test de 1 heure), ils restent tous à zéro :
| Compteur | Régime établi | Réinitialisation | Disponibilité |
|---|---|---|---|
dev.sanity_reject_count |
0 | dev.reset_counters() |
les deux environnements d'exécution |
MachineI2CBackend.retry_exhaustion_count |
0 | backend.reset_counters() |
MicroPython uniquement |
MachineI2CBackend.retry_count_total |
faible (environ 5 à 20 par heure est normal) | backend.reset_counters() |
MicroPython uniquement |
| fraction d'instantanés périmés dans les instantanés de période | < 1 % | (cumulatif — pas de remise à zéro) | les deux environnements d'exécution |
Si l'une de ces valeurs est non nulle en régime établi, revenez à la section correspondante ci-dessus.
Débogage au niveau du bus avec un analyseur logique
Pour un débogage approfondi, quand le paquet ne peut plus vous dire ce qui se passe sur le fil, capturez SDA + SCL avec un analyseur logique (Saleae, DSLogic Plus, tout appareil 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 script (
dev.voltage, etc.) à la séquence d'octets attendue — elles doivent correspondre exactement. Les lectures sont en rafale (incrément automatique). Les écritures n'ont PAS d'incrément automatique (un octet à la fois pour les registres multi-octets).
Si le comportement du paquet diverge de la capture, ouvrez un signalement avec le fichier de capture joint (.sal / .dsl / .csv).
Quand contacter le support
Si vous avez suivi la section correspondante ci-dessus et que le problème persiste, ouvrez un signalement :
github.com/rb-amp/rbamp-python/issues
Dans le signalement, incluez :
-
Exécution + version :
python --version/mpremote eval 'import sys; print(sys.version, sys.implementation)'. -
Plateforme hôte : « RPi 4B Bookworm », « ESP32-S3 N16R8 MicroPython 1.22 », etc.
-
Version du paquet :
rbamp --version(CPython) oupython -c "import rbamp; print(rbamp.__version__)". -
Version du firmware du module —
dev.firmware_versionrelevé dans les journaux. - Un script minimal (environ 30 lignes) qui reproduit le problème.
- La trace d'exception avec tout le contexte.
-
Les compteurs au moment de la panne :
dev.sanity_reject_count,backend.retry_exhaustion_count(uPy seulement). -
Les journaux détaillés de la bibliothèque — le moyen le plus simple de les collecter est
dev.set_logger(print)avant l'opération en échec. Le paquet affichera ses étapes internes (la boucle de nouvelles tentatives, les délais de stabilisation, l'amorçage de l'instantané, etc.) — joignez la sortie standard au signalement. -
(Si disponible) le fichier de capture de l'analyseur logique.
CLI — rbamp scan / rbamp read / rbamp address
La CLI rbamp est une fine enveloppe autour de RbAmp.* pour les opérations de banc (voir 09 · Référence API, section « CLI »). Comme elle utilise la même classe RbAmp, TOUS les symptômes ci-dessus s'appliquent. Erreurs propres à la CLI :
-
rbamp scanne trouve rien — même chose qu'à l'étape 1 de la section « Le module ne répond pas sur I²C » ci-dessus. Vérifiez directement aveci2cdetect -y 1. S'il trouve le module, c'est un problème de la détection automatique de notre backend ; ouvrez un ticket avec la sortie derbamp --verbose scan. -
rbampéchoue avecPermissionError: /dev/i2c-1— l'utilisateur n'appartient pas au groupei2c. Voir la section Installation du README poursudo usermod -aG i2c $USER+ reconnexion. -
rbamp: command not foundaprèspip install— l'entrée de console[project.scripts]n'est pas active. Vérifiez quepip show rbampindique l'emplacement installé ; assurez-vous que$HOME/.local/binfigure dans$PATH(pourpip install --user).
Liens
- 05 · Démarrage rapide — votre premier script fonctionnel
-
09 · Référence API — l'API complète + avertissements sur les méthodes publiques marquées WARNING
-
03 · Sélection du capteur de courant — le tableau des modèles SCT-013, la topologie double pince pour une large plage dynamique, approches pour augmenter la sensibilité aux faibles courants
Source et signalements : rb-amp/rbamp-python · cette page dans le dépôt : docs/10_troubleshooting.md (v1.6.1)