rbAmp
FR
Boutique
Docs
Mis à jour le · Modifier sur GitHub (Edit on GitHub)

10 · Dépannage

Arbre de décision de dépannage : symptôme → contrôle rapide → action

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 :

  1. Niveau bus — le module ne répond pas sur I²C ; les lectures lèvent RbAmpIOError.

  2. Niveau 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 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 :

Shell
i2cdetect -y 1     # bus 1 — the standard one on the RPi 40-pin header

Ou en Python :

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

Python
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_bcm sur 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 :

Python
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 :

  1. Abaissez la vitesse du bus à 50 kHz :
Python
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
  1. Augmentez le nombre de tentatives pour une charge lourde — cela nécessite l'API avancée, via la création explicite du backend :
Python
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
  1. Surveillez le compteur d'épuisement des tentatives — il doit rester à zéro en régime permanent :
Python
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_baudrate dans /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 :

Shell
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

  1. Vérifiez que la classe de capteur et le modèle de CT sont configurés :
Python
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.

  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) 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 ».

  1. 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, mais dev.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 / Inf flottant / |x| > 10000 (clairement pas une valeur physique) est sorti du bus.

Distinguez-les par les compteurs de diagnostic (disponibles sur MicroPython) :

Python
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

  1. Vérifiez la cadence : 60 s entre les instantanés est confortable ; 30 s est limite ; < 10 s garantit des lectures périmées.

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

Python
if dev.probe():
    print("alive")
  1. Vérifiez le drapeau directement :
Python
if dev.is_period_valid():
    # avg_p[] can be read
    ...
  1. 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

  1. Calibration du capteur de courant : assurez-vous que dev.set_sensor_class() et dev.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.

  2. 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).

  3. Dérive de l'horloge maître : time.monotonic() (CPython) et time.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.

Sécurité

⚠ 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) :

Python
# 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) :

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

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

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

Python
# 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) :

Python
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 :

Python
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 :

Python
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-certificates du 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 :

Text
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 :

Python
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é avec RbAmpModeError. Dans un contexte de maintenance, utilisez dev.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 :

  1. 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èvent RbAmpParamError(ValueError).

  2. Indice de voie invalide dans la forme par voie dev.set_ct_model_ch(channel, code) — il doit être < dev.channels.

  3. Une valeur de classe de capteur hors de 0..3. (WIRED_CT / BUILTIN_CT sont des valeurs valides, mais un module appairé en usine refuse d'être reconfiguré — cela lève RbAmpModeError, 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) :

Python
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) :

Python
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()
Sécurité

⚠ 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 :

Python
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")
Sécurité

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

Remarque

✅ 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_ms ou 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 VCC au 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 :

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

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

  3. dev.is_std vaut False sur 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. Utilisez smbus2 sous 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) ou python -c "import rbamp; print(rbamp.__version__)".

  • Version du firmware du module — dev.firmware_version relevé 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 scan ne 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 avec i2cdetect -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 de rbamp --verbose scan.

  • rbamp échoue avec PermissionError: /dev/i2c-1 — l'utilisateur n'appartient pas au groupe i2c. Voir la section Installation du README pour sudo usermod -aG i2c $USER + reconnexion.

  • rbamp: command not found après pip install — l'entrée de console [project.scripts] n'est pas active. Vérifiez que pip show rbamp indique l'emplacement installé ; assurez-vous que $HOME/.local/bin figure dans $PATH (pour pip install --user).


Source et signalements : rb-amp/rbamp-python · cette page dans le dépôt : docs/10_troubleshooting.md (v1.6.1)