rbAmp
PT
Loja
Docs
Atualizado · Editar no GitHub [Edit on GitHub]

10 · Resolução de problemas

Árvore de decisão para resolução de problemas: sintoma → verificação rápida → ação

Este capítulo está organizado pelo sintoma que observa, e não pela classificação interna de erros. Se chegou aqui, algo não está a funcionar corretamente. Encontre o seu sintoma na lista abaixo, vá à secção correspondente e percorra o procedimento de diagnóstico.

A maioria dos problemas de bancada enquadra-se em três categorias:

  1. Ao nível do barramento — o módulo não responde por I²C; as leituras levantam RbAmpIOError.

  2. Nível de dados — o módulo responde, mas os números estão errados: zeros, valores estranhos, sinal errado.

  3. Nível de aplicação — a ligação é instável, o contador Wh deriva, o script fica bloqueado ou morre por timeout.

Atalho para quem tem pressa: em regime estacionário, os métodos públicos devem devolver valores / produzir snapshots sem lançar exceções. Se vir com frequência RbAmpIOError ou RbAmpStaleError nos registos, vá diretamente a "O módulo não responde por I²C" abaixo.

O módulo não responde por I²C

O que vê: dev.begin() (ou entrar no context manager with RbAmp(bus, 0x50) as dev:) lança RbAmpIOError ou RbAmpVersionError, ou as leituras RT lançam RbAmpIOError com regularidade.

Passo 1 — Pesquisa no barramento

Confirme primeiro que o módulo está de facto presente no barramento.

CPython (SBC Linux)

Ferramenta externa:

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

Ou em 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

Saída esperada: Found 0x50 (ou outro endereço, se o tiver alterado).

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()])

Saída esperada: Found: ['0x50'] (ou o seu endereço).

O que fazer se não for encontrado nada

O problema está na cablagem ou na alimentação:

  • SDA / SCL não são trocados (ver 04 · Cablagem para as predefinições de GPIO por anfitrião).

  • Ambas as linhas têm pull-up para 3.3 V (a placa do módulo tem resistências de 4.7 kΩ integradas — não são necessárias externas para um só módulo).

  • O pino de alimentação do módulo lê na verdade 5 V (4.5–5.5 V).

  • Nenhum outro mestre (sonda de depuração, segundo controlador) está pendurado nas mesmas linhas.

  • Em MicroPython, verifique que freq=50_000 (não 100k nem 400k — no ESP32 com o firmware v1 o padrão de NACK de base consome o orçamento de retries).

  • No CPython, verifique se o driver I²C do kernel está ativo — lsmod | grep i2c_bcm no RPi.

O que fazer se o módulo aparecer num endereço inesperado

Alguém o reatribuiu antes na bancada. Atualize o segundo argumento de RbAmp:

Python
dev = RbAmp(bus, 0x52)   # address from the bus scan

Passo 2 — padrão de NACK de base do MicroPython + ESP32

Se a pesquisa do barramento encontrar o módulo mas dev.read_voltage() lançar RbAmpIOError com regularidade — e estiver em MicroPython + ESP32 — isto é um padrão de base documentado: a pilha I²C da porta ESP32 do MicroPython herdou particularidades do driver ESP-IDF v5, que, ao falar com o rbAmp no firmware atual, dá NACKs frequentes a 100 kHz.

A mitigação já está incorporada em MachineI2CBackend (3 retries com intervalo de 5 ms por predefinição), mas sob carga pesada o orçamento de retries pode esgotar-se.

O que fazer no ESP32:

  1. Reduza a velocidade do barramento para 50 kHz:
Python
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
  1. Aumente o número de tentativas de retry para uma carga pesada — isto exige a API avançada com criação explícita do 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. Monitorize o contador de esgotamento de repetições — deve manter-se a zero em regime estável:
Python
if backend.retry_exhaustion_count > 0:
    print("WARN: retry exhausted:", backend.retry_exhaustion_count)

Passo 3 — Plataformas não-ESP32 (RP2040 / STM32 / CPython)

Em RP2040 / STM32 / Pyboard (via MicroPython) não há padrão de NACK de base — estas plataformas mostram uma taxa de NACK de ~0 % com rbAmp. MachineI2CBackend deteta automaticamente a porta e baixa o retry predefinido para 1 tentativa.

Em CPython (via smbus2) não existe qualquer camada de retry — o driver I²C do kernel Linux não está sujeito ao padrão de NACK; um único OSError do smbus2 é traduzido para RbAmpIOError sem retry.

Se ocorrerem NACKs nestas plataformas, procure:

  • Capacidade elevada do barramento — fios longos + muitos dispositivos. Baixe a velocidade ou encurte o cabo.

  • Disputa de mestre — o pacote não suporta multi-mestre.

  • Um SCL flutuante entre transações — um pull-up em falta.
  • No RPi: verifique dtparam=i2c_arm_baudrate em /boot/config.txt — recomenda-se 100000.

PermissionError: [Errno 13] em /dev/i2c-1 (Linux)

O que vê: SMBus(1) lança PermissionError, enquanto sudo python funciona. O seu utilizador não tem permissão para abrir o dispositivo I²C. Correção:

Shell
sudo usermod -aG i2c $USER   # then log out and in again

Certifique-se também de que o I²C está ativo (sudo raspi-config → Interface Options → I2C) e que ls /dev/i2c-* lista o barramento; sudo apt install i2c-tools dá-lhe i2cdetect -y 1.

A corrente lê zero numa carga em funcionamento

O que vê: dev.current[0] (ou dev.read_current(0)) devolve 0.000 (ou um valor muito pequeno) mesmo com um consumidor real ligado (uma chaleira, um candeeiro, um ferro). dev.power_factor[0] pode mostrar um valor estranho (nan / 0 / ±1) — é uma consequência; a causa está na corrente.

Procedimento de diagnóstico

  1. Verifique se a classe do sensor e o modelo de TC estão configurados:
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})")

Sem estas duas chamadas, os coeficientes de calibração não são carregados e a corrente lê sempre zero. Este passo é feito uma vez na primeira instalação — a escolha fica guardada na flash do módulo.

  1. Verifique se o modelo de CT corresponde à carga. Uma pinça CT grande (por exemplo, SCT-013-100, 100 A) numa carga pequena (uma lâmpada de 50 W = ~0.2 A) produz um sinal na margem do ruído de fundo e as leituras serão zero. Escolha o modelo de CT mais pequeno que cubra a sua corrente máxima esperada. A tabela completa está em 03 · Seleção do sensor de corrente.

Se tiver um módulo multicanal (UI2 / UI3 / UI5 / UI7) e quiser ver tanto cargas pequenas como picos grandes, considere o padrão dual-CT: uma pinça pequena (SCT-013-005) num canal separado para a gama baixa + uma grande (SCT-013-030/100) noutro canal para a gama alta; o master escolhe o valor por limiar. O padrão é discutido em 03 · Seleção do sensor de corrente, na secção "Topologia dual-CT".

  1. Verifique a orientação da pinça. A seta no corpo da pinça tem de apontar no sentido do fluxo de corrente para a carga. Se a pinça estiver "ao contrário", dev.read_current() dará o valor correto em termos absolutos, mas dev.read_power() dará um valor negativo numa carga consumidora. Confirmação — dev.read_power_factor() mostrará exatamente −1.0 numa carga resistiva (em vez de +1.0). Correção: reinstale fisicamente a pinça (desaperte-a, rode a seta no sentido certo, volte a fechá-la), ou inverta o sinal do lado da aplicação (p = -p; pf = -pf; se souber que a carga não é um inversor FV).

Se os três passos passarem e a corrente continuar a zero

Então o sinal na entrada do módulo está de facto abaixo do piso de ruído. Verifique:

  • Se a corrente está de facto a circular — meça-a com um multímetro (uma pinça DC / pinça AC) no mesmo fio.

  • Se a pinça está intacta — deve existir uma tensão AC no conector da pinça proporcional à corrente (alguns milivolts para cargas de consumo).

  • Se está a prender o fio certo — apenas um condutor, o fio vivo (L), não o cabo inteiro (prender L e N lê ~0).

As leituras oscilam ou levantam RbAmpIOError

O que vê: dev.voltage / dev.read_current(...) lança RbAmpIOError periodicamente. O valor da propriedade não foi obtido — precisa de uma nova tentativa do lado da aplicação ou de uma proteção try/except.

RbAmpIOError do pacote cobre duas classes de problema:

  • NACK após esgotar as repetições — a ligação é instável.
  • O filtro de sanidade rejeitou o valor — um NaN / Inf / |x| > 10000 (claramente não um valor físico) chegou do barramento.

Distinga-os através dos contadores de diagnóstico (disponíveis em 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)
Contador O que significa
retry_count_total ↑, retry_exhaustion_count = 0, sanity_reject_count = 0 O barramento está saudável; o pacote recupera discretamente os raros NACKs. Normal.
retry_count_total ↑, retry_exhaustion_count ↑ Patamar de NACK — aumente retry_attempts (ver o Passo 2 acima).
retry_count_total baixo, sanity_reject_count ↑ O filtro de sanidade está a apanhar lixo após retries falhados. Aumente retry_attempts=5+.

No CPython (SMBusBackend) não há camada de retry — RbAmpIOError é levantado logo na primeira falha. Os sintomas são raros (o kernel Linux é normalmente fiável), mas se aparecerem verifique a ligação, os pull-ups e a velocidade do barramento.

O fator de potência parece estranho

O que vê: dev.power_factor[0] (ou dev.read_power_factor(0)) devolve um valor que não corresponde ao tipo de carga.

Expectativas por carga:

Carga PF esperado
Chaleira, ferro de engomar, lâmpada incandescente +0.95 .. +1.0 (resistivo)
Frigorífico, compressor de motor +0.6 .. +0.85 (indutivo)
Lâmpada LED, televisor (fonte de alimentação comutada) +0.5 .. +0.95 (não linear)
Inversor PV a exportar potência PF negativo

PF = nan ou 0 com I = 0

O PF é definido como P / (U × I). Com corrente zero (I=0) a conta é indefinida. O valor exato devolvido depende do firmware (pode ser nan, 0 ou um valor de substituição) — é normal enquanto a corrente for de facto zero. Assim que aparecer corrente, aparece um PF válido.

PF estritamente −1.0 numa carga puramente consumidora

A pinça está instalada "ao contrário" — a seta não aponta no sentido do fluxo de corrente para a carga. Correção: ou reinstale a pinça corretamente, ou trate o sinal do lado da aplicação (p = -p; pf = -pf; se souber que a carga não pode ser um inversor FV).

O PF oscila entre +0.3 e +0.7 numa carga resistiva

  • Causa possível: a pinça TC está num fio de uma fase diferente daquela à qual está ligada a entrada U do módulo. Numa distribuição trifásica é fácil prender a fase errada por engano — um desfasamento de 120° ou 180° entre U e I dá exatamente estes valores de PF. A correção é instalar o módulo de modo que a entrada U e o TC estejam na mesma fase.

  • Alternativa: a carga não é de facto puramente resistiva. Repita o teste com uma carga conhecida como resistiva (uma chaleira elétrica à potência máxima).

Os snapshots por período são sempre RbAmpStaleError

O que vê: dev.read_period_snapshot() levanta RbAmpStaleError em todas as chamadas. Isto significa que o módulo não terminou de integrar o período anterior antes da leitura seguinte.

Numa leitura obsoleta o pacote mantém o carimbo temporal anterior, pelo que o snapshot bem-sucedido seguinte cobre o intervalo completo desde o último bom e o total de Wh fica exato (sem contagem dupla, sem perda).

Aceitável: leituras obsoletas raras (1–2 por hora com cadência de 60 s). Não aceitável: leituras obsoletas consecutivas — isso significa que o firmware não responde ou que o mestre consulta com demasiada frequência.

Procedimento de verificação da cadência

  1. Verifique a cadência: 60 s entre snapshots é confortável; 30 s é marginal; < 10 s garante leituras obsoletas.

  2. Verifique a capacidade de resposta do módulo entre instantâneos:

Python
if dev.probe():
    print("alive")
  1. Verifique o sinalizador diretamente:
Python
if dev.is_period_valid():
    # avg_p[] can be read
    ...
  1. Verifique a versão do firmware — dev.firmware_version >= 0x04 (v1.3) tem o menor número de leituras obsoletas; 0x02/0x03 (v1.1/v1.2) continuam suportadas, mas a taxa de leituras obsoletas sobe; 0x01 (v1.0) é a mais ruidosa.

Caso especial — acordar de deep-sleep em MicroPython

Se usar um padrão de deep-sleep em MicroPython, o predefinido dev.read_period_snapshot() após a entrada no context manager dará sempre um resultado obsoleto (ou quase zero) — __enter__ tira um snapshot (comando LATCH) que repõe o acumulador do firmware. O padrão canónico usa skip_latch=True + uma duração de sono conhecida (o argumento machine.deepsleep(SLEEP_MS)) — ver 06 · Exemplos, Cenário 9.

A contabilidade de Wh desvia-se da referência

O que vê: dev.energy.wh(0) após várias horas ou dias de funcionamento deriva da leitura do contador da concessionária ou de um contador de referência (Kill-A-Watt ou similar).

Primeiro descarte o trivial

  1. Calibração da pinça de corrente: certifique-se de que dev.set_sensor_class() e dev.set_ct_model() são chamados com o modelo TC correto (ver 03 · Seleção do sensor de corrente). Sem isto, a corrente RMS é calculada com o piso predefinido e o valor de potência fica sistematicamente enviesado.

  2. Snapshots obsoletos descartados: se dev.energy.wh(0) estiver consistentemente abaixo da referência, podem ser intervalos perdidos. Um único snapshot obsoleto não perde energia (o seguinte bom cobre o intervalo completo), mas falhas repetidas ou um script que não estava a correr, sim. Verifique a cadência (ver acima).

  3. Deriva do relógio mestre: time.monotonic() (CPython) e time.ticks_ms() (MicroPython) são fiáveis em funcionamento normal. Mas se o mestre entrar em deep sleep, use o padrão de memória RTC + duração conhecida do sono do Cenário 9.

Segurança

⚠ ticks_ms() dá a volta em MicroPython. time.ticks_ms() volta a zero em 2**30 ms (~12.4 dias) — uma subtração ingénua t1 - t0 através desse limite de 12.4 dias dá um número negativo ou enorme. Internamente o pacote usa time.ticks_diff(t1, t0), que é seguro para a volta. Se calcular master_dt_ms no seu código (fora do pacote), use ticks_diff, não a subtração direta.

Precisão do acumulador

O acumulador de Wh dentro do handle:

Runtime Tipo
CPython float de 64 bits (float do Python)
MicroPython (compilação de dupla precisão) float de 64 bits
MicroPython em portas sem double-float float de 32 bits

Verificar a precisão em MicroPython (sys.float_info existe apenas em CPython; em uPy usamos uma verificação empírica):

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

Para portes de MicroPython de ponto flutuante simples em instalações de longa duração, reponha periodicamente dev.energy.reset(0) e guarde o total de longo prazo no seu próprio armazenamento persistente (por exemplo, via uma mensagem MQTT com retain no HA).

O script bloqueia / morre por timeout

O que vê: o script Python arranca normalmente e depois entra num bloqueio / RuntimeError após alguns minutos.

MicroPython@ESP32: uma operação I²C bloqueia num barramento marginal — mitigação em três camadas

O que vê especificamente: um script no ESP32 (MicroPython machine.I2C) consulta o rbAmp sem problemas durante vários minutos, depois fica "morto" a meio de uma chamada dev.read_period_snapshot() / fleet.poll_all(). O WDT (se tiver um ativado) apanha o bloqueio; caso contrário o script simplesmente deixa de responder. Se tiver um REPL, também bloqueia.

O que está a acontecer: o machine.I2C do MicroPython-em-ESP32 envolve o mesmo driver i2c_master do IDF que os projetos nativos ESP-IDF usam. Num barramento marginal (pull-ups fracos, pistas longas, EMI, ruído ZC) SDA/SCL podem "prender" momentaneamente num estado indefinido. Antes da transação seguinte, o i2c_master do IDF fica em ciclo na i2c_ll_is_bus_busy à espera que o barramento se liberte — este ciclo não é limitado pelo timeout I²C da biblioteca.

Isto não é um "artefacto apenas do depurador". Validado na bancada (entre bibliotecas, mesmo banco de testes e carga):

Configuração do barramento Taxa de bloqueios
2 pull-ups fracos do módulo + NRST do depurador ligado ~1 bloqueio / 2.1 min
1 resistência de pull-up fraca no módulo, sem depurador ~1 bloqueio / 3.3 min (≈ 12 bloqueios por hora)
+ pull-up externo de 4.7 kΩ em SDA/SCL do DUT 0 bloqueios (soak de 12 minutos, 0 reinícios)

A correlação é clara — uma correção de integridade do barramento elimina totalmente o bloqueio. A lógica da biblioteca não tem culpa.

Mitigação em três camadas (aplique as três):

  1. Pull-up externo (~4.7 kΩ) em SDA e SCL para 3.3 V num único ponto do barramento. Os pull-ups internos do ESP32 (~45 kΩ) são fracos para um barramento multi-módulo de comprimento real, enquanto os 4.7 kΩ incorporados nos módulos, em paralelo, ficam fortes demais. Num barramento assim, corte os incorporados em todos os módulos menos um. Ver 04 · Ligação, secção "Barramento multi-módulo — a topologia principal".

  2. Não execute uma compilação de produção com o NRST do depurador ligado. Numa sessão de depuração a linha de reset pode manter SDA/SCL num estado indefinido ao desligar/ligar, provocando um bloqueio do barramento na transação seguinte.

  3. Um task-WDT da aplicação na tarefa de polling — defesa em profundidade. Os pull-ups corretos no barramento são a correção no terreno; o task-WDT é uma postura de recuperação.

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)

O que NÃO fazer: não tente contornar o problema com um parâmetro I2C(..., timeout=ms) maior — não limita o ciclo de pré-espera de barramento ocupado, que é outro caminho de código no driver IDF. O que é preciso corrigir é a integridade do barramento (camada 1) e o supervisor (camada 3).

CPython@Linux SBC: o I²C do kernel não sofre este problema

Os drivers do kernel Linux (i2c-bcm2835 no Raspberry Pi, i2c-i801 em x86, etc.) fazem a sondagem de barramento ocupado com timeout — num barramento bloqueado devolvem IOError(Errno 110: ETIMEDOUT) ou EREMOTEIO em vez de bloquear. A biblioteca envolve isso em RbAmpIOError. Assim, a mitigação em três camadas não é necessária em CPython — o Linux trata disso sozinho. Um pull-up externo de ~4.7 kΩ continua a ser desejável para a integridade do sinal num barramento longo.

latch_ms não corresponde ao período do relógio de parede

latch_ms é um temporizador de diagnóstico do módulo; não o use para energia — use o relógio do master.

A biblioteca integra a energia pelo relógio de parede do mestre: CPython — time.monotonic(); MicroPython — time.ticks_ms() + time.ticks_diff(). A integração do lado do mestre não acrescenta erro próprio além da precisão da potência ativa do módulo.

Se o seu código depender de snap.latch_ms para cálculos de sub-período, mude para o seu próprio time.monotonic() / time.ticks_diff().

RbAmpStaleError em todas as leituras — a biblioteca mantém a âncora automaticamente

O que vê: dev.read_period_snapshot() lança RbAmpStaleError periodicamente.

Tratamento canónico de dt: numa leitura obsoleta a biblioteca Python não põe a zero a âncora interna _last_latch_ms. A leitura válida seguinte recebe um master_dt_ms igual ao intervalo completo desde o snapshot bem-sucedido anterior — ou seja, cobre tanto o período "perdido" como o atual. O firmware preserva o acumulador avg_p através de um snapshot vazio (persistência no firmware): no snapshot válido seguinte já é um valor médio sobre o intervalo inteiro. A integração de Wh mantém-se exata — sem contagem dupla, sem contagem a menos.

Padrão para arranque a frio (prime-until-valid, orçamento de ~25 retries é suficiente):

Python
from rbamp import RbAmpStaleError

while True:
    try:
        snap = dev.read_period_snapshot()
        break
    except RbAmpStaleError:
        time.sleep(3.0)

Depois da preparação — ignore simplesmente RbAmpStaleError se for raro; se for frequente, diagnostique a cadência (a secção "Os snapshots de período são sempre RbAmpStaleError" acima).

CPython: signal.SIGTERM / KeyboardInterrupt não são tratados

Causa: um time.sleep(60) longo bloqueia o handler de sinal. Num deploy de produção (systemd), systemctl stop rbamp espera pela resposta ao SIGTERM até um timeout (predefinição 90 s) e depois mata com SIGKILL — o Wh pode perder-se.

Correção: um ciclo sensível a sinais:

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 use asyncio com um signal_handler — ver a secção abaixo.

MicroPython (ESP32): timeout do watchdog na ligação Wi-Fi

Causa: um ciclo de ligação WiFi sem limite aciona o WDT da tarefa após ~5 s (a predefinição).

Correção: uma espera limitada com um fallback de reinício:

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()

O broker MQTT desliga-se

No CPython (paho-mqtt): o keepalive predefinido é 60 s, mas mqtt.connect() é bloqueante e mqtt.loop() tem de ser chamado num ciclo de eventos. Use mqtt.loop_start() (uma thread em segundo plano) ou a variante asyncio aiomqtt.

Em MicroPython (umqtt.simple): síncrono sem keepalive — tem de chamar mqtt.ping() manualmente a cada ~30 s. A alternativa é o pacote assíncrono mqtt_as, com keepalive integrado.

Falha no handshake TLS (nuvem CPython + RPi com pouca RAM)

Raramente um problema num Pi com 1+ GB de RAM, mas num Pi Zero / Zero W (512 MB) um handshake TLS com um armazenamento de certificados grande pode ser morto pelo OOM killer.

Fix:

  • Use um CA específico em vez do ca-certificates do sistema — menos memória.

  • Reduza os buffers do MQTT.

  • Passe para um Pi 3/4/5 para uma implementação cloud em produção.

set_sensor_class() / set_ct_model() lança RbAmpModeError

O que vê: uma das chamadas de configuração levanta RbAmpModeError com a mensagem:

Text
REG_SENSOR_CLASS is UNSET;
call dev.set_sensor_class(RbAmpSensorClass.SCT_013) first

Causa: set_ct_model[_ch] exige que set_sensor_class() tenha sido chamado antes. É uma guarda intencional.

O que fazer:

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)

Mais detalhes — 03 · Seleção do sensor de corrente e 09 · Referência da API, a secção "Configuração do sensor".

Desde a 1.6.0 estes setters têm guarda de leitura antes da escrita:

  • Definir a classe ou o modelo que o módulo já tem é um no-op silencioso (reaplicar apagaria a calibração do canal).

  • Num módulo emparelhado de fábrica (classe WIRED_CT / BUILTIN_CT), uma classe ou modelo diferente é recusado com RbAmpModeError. Num contexto de assistência técnica, use dev.set_ct_model_ch_force(ch, code).

RbAmpModeError também surge de dev.factory_reset() e dev.save_gains() (operações de fábrica exigem modo de fábrica). Uma mudança de endereço no v1.3 é adequada para produção e não lança RbAmpModeError.

set_sensor_class() / set_ct_model*() lança RbAmpParamError ou ValueError

O que vê: a chamada lança RbAmpParamError (em CPython herda também ValueError via herança múltipla).

Possíveis causas:

  1. Código de modelo inválido — para a classe SCT_013 o conjunto aceite é {1, 2, 3, 4, 5, 6, 7} (os códigos 5 e 7 são SCT-013-100 e SCT-013-060). Para as outras classes, veja a tabela de conjuntos aceites por classe em 03 · Escolher um modelo SCT-013. Valores fora do conjunto aceite lançam RbAmpParamError(ValueError).

  2. Índice de canal inválido na forma por canal dev.set_ct_model_ch(channel, code) — tem de ser < dev.channels.

  3. Um valor de classe de sensor fora de 0..3. (WIRED_CT / BUILTIN_CT são valores válidos, mas um módulo emparelhado de fábrica recusa ser reconfigurado — isso lança RbAmpModeError, ver abaixo.)

Tratamento de erros: última escrita em REG_ERROR + EVENT_FLAGS.bit3 durável (v1.3)

v1.3: REG_ERROR (0x02) é o resultado da última escrita, não persistente. Em cada escrita de registo o firmware define reg_error = ERR_OK; uma escrita não relacionada posterior limpa o erro anterior.

O sinal de erro durável = EVENT_FLAGS (0x2A) bit3 — pegajoso (W1C), ativado de imediato em qualquer escrita/comando rejeitado.

Padrão 1 — captura pontual após a operação (o resultado exatamente desta operação):

Python
dev.save_user_config()
dev_err = dev.read_reg(0x02)   # IMMEDIATELY, before the next write

Padrão 2 — monitorização durável (canónico para funcionamento de longa duração):

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()
Segurança

⚠ INVERSÃO da documentação inicial "pegajosa" (v1.3). REG_ERROR é o resultado da última escrita, não é pegajoso. A durabilidade é dada pelo EVENT bit3.

⚠ bit3 é um canal assíncrono, não para validação síncrona de escrita: numa escrita rejeitada, o bit3 é definido com atraso em relação ao momento em que a transação I²C retorna (algumas centenas de milissegundos). Não consulte o bit3 logo após uma escrita para verificar o resultado dessa escrita — para o resultado da sua própria escrita use o Padrão 1 (captura pontual de read_last_error(), imediata) ou o RbAmpParamError levantado pelo setter. O bit3 serve para monitorização prolongada de factos assíncronos (tempo de execução, caminho de comandos), não para validar uma operação que acabou de executar.

Ressalva: DEV_ERR_CLONE (0xF9) não é limpo por CMD_CLEAR_ERROR — é um marcador anticlone.

Um módulo recém-gravado mostra 0xFB no primeiro arranque (NORMAL)

O que vê: um módulo recém-gravado mostra no primeiro arranque REG_ERROR = 0xFB (DEV_ERR_FLASH_PARAMS_BAD) + bit3 de EVENT.

Causa: a página de parâmetros não está inicializada → carregam-se os valores de fábrica. Isto é NORMAL num módulo virgem, não é fatal.

Correção: configure sensor_class + ct_model + (opcionalmente) o endereço e depois dev.save_user_config(). Após um SAVE bem-sucedido → REG_ERROR = 0x00, bit3 limpo.

As leituras falham ao comutar cargas com relé (transitórios EMI)

O que vê: dev.voltage / dev.current() levantam periodicamente RbAmpIOError / OSError — mas apenas durante a comutação ativa de uma carga com relé ou indutiva na mesma instalação. As leituras em regime estável são fiáveis.

Causa (C.12 confirmado em hardware): durante a comutação de relés (carga de 5 A), a EMI faz falhar cerca de 67 % das transações I²C. O barramento recupera sozinho, não ocorre bloqueio e nenhum módulo se perde.

Correção — repetição ao nível da aplicação:

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")
Segurança

⚠ O retry do backend, por si só, não basta: quando uma falha EMI ultrapassa a janela de retry do backend, é preciso um retry explícito ao nível da aplicação com uma pausa.

commit_address_change() lança RbAmpIOError após um reinício do barramento

O que vê: prepare_address_change() teve sucesso, mas após o commit + reset o módulo não responde no novo endereço.

Nota

✅ v1.3: REG_I2C_ADDRESS (0x30) lê o endereço ativo no arranque. Após o reinício pós-commit, ler 0x30 no novo endereço mostrará esse mesmo endereço — isto confirma que o commit passou. Se o módulo não responder no novo endereço, experimente uma pesquisa do barramento via _io_smbus (mostrará em que endereço o módulo está de facto).

Mais sobre o commit em duas fases — ver 09 · Referência da API e 04 · Cablagem.

commit_address_change() levanta RbAmpTimeoutError

Se prepare teve êxito mas commit lança RbAmpTimeoutError, a janela de "armação" expirou (5 segundos após prepare). dev.probe() não ajuda aqui (o módulo responde; o problema está na máquina de estados do módulo). A correção é chamar outra vez dev.prepare_address_change(new_addr) e depois, imediatamente, na mesma função/iteração, sem chamadas de rede pelo meio, chamar dev.commit_address_change(). Qualquer E/S bloqueante entre prepare e commit (Wi-Fi, MQTT, HTTP) é a principal causa de a janela expirar.

wait_ready() levanta RbAmpTimeoutError

A flag de pronto do módulo não foi definida dentro de timeout_ms. Causas possíveis:

  • O módulo ainda não terminou o arranque a frio (~250 ms) — aumente timeout_ms ou repita a chamada.

  • O módulo não responde por I²C — ver a secção "O módulo não responde por I²C" acima.

  • O nível de alimentação caiu abaixo de 4.5 V — verifique VCC com um multímetro.

Mais sobre os métodos públicos mas com aviso — ver 09 · Referência da API, a secção "Configuração do sensor" (a subsecção de mudança de endereço está lá, juntamente com save_gains e factory_reset).

RbAmpNotSupportedError (chamadas STD)

O que vê: uma chamada como dev.read_std_energy(), dev.read_voltage_angle(), dev.read_phase_sequence(), dev.get_start_current() ou dev.set_time() lança RbAmpNotSupportedError.

Causas e o que fazer:

  1. O módulo é um módulo BASIC. As chamadas exclusivas do STD não estão disponíveis em BASIC. Verifique dev.is_std; em BASIC use os leitores comuns (voltage, current, power, power_factor, frequency) e a API de período.

  2. A imagem do módulo é demasiado antiga para essa funcionalidade. Os contadores de energia em micro-unidades, os ângulos de tensão e a corrente de arranque precisam de uma imagem de módulo suficientemente recente; numa mais antiga a chamada indica "not available". As leituras comuns continuam a funcionar.

  3. dev.is_std é False num módulo STD. A biblioteca deteta a linha com uma transação de barramento de 16 bits; um objeto de barramento ou adaptador que não consegue fazer uma é tratado como BASIC. Use smbus2 em CPython (validado) e veja 04 · Hardware.

A mesma cablagem I²C aplica-se às duas linhas de módulos. Note que as funcionalidades de energia no dispositivo, ângulo e corrente de arranque estão validadas em CPython; o caminho de 16 bits do MicroPython ainda não está validado em hardware.

Tabela resumo de exceções

RbAmpError (subclasse de OSError) é a classe base. Um handler except OSError: existente na aplicação continua a apanhar erros rbAmp sem alterações — a convenção Python padrão para drivers de E/S de hardware.

Exceção Quando Onde procurar
RbAmpIOError NACK após retry; rejeição por sanidade; falha ao nível do barramento a secção "O módulo não responde por I²C"
RbAmpTimeoutError wait_ready() expirou; a janela de commit_address_change (5 s) expirou a secção "commit_address_change devolve RbAmpTimeoutError" abaixo
RbAmpNotReadyError (reservado; não lançado pela biblioteca, exportado para compatibilidade futura) se apanhar este tipo — reproduza-o num issue
RbAmpStaleError snapshot de período obsoleto a secção "Os snapshots por período são sempre RbAmpStaleError"
RbAmpParamError (em CPython também ValueError) argumento inválido: dev=None, ch fora do intervalo, code fora do conjunto aceite por classe (para SCT_013 — {1, 2, 3, 4, 5, 6, 7}), uma cls reservada. Também uma violação de pré-condição: set_ct_model*() sem um set_sensor_class() anterior verifique os argumentos da chamada e se set_sensor_class() foi chamado
RbAmpModeError operação apenas de fábrica (modo de fábrica não definido; uma alteração de endereço na v1.3 é aceitável em produção); classe de sensor não definida; módulo emparelhado de fábrica recusa uma alteração de classe/modelo verifique a flag de modo; set_sensor_class() primeiro; set_ct_model_ch_force() para uso de assistência técnica
RbAmpNotSupportedError Chamada exclusiva do STD num módulo BASIC, ou uma funcionalidade STD que a imagem do módulo não fornece a secção "RbAmpNotSupportedError" abaixo
RbAmpVersionError REG_VERSION = 0/0xFF em begin() (o módulo não responde ou o firmware está corrompido). set_ct_model_ch por canal em v1.0/v1.1 pode receber NACK (o opcode não existe) e lança RbAmpIOError, não RbAmpVersionError — a guarda de versão NÃO está implementada no cliente; verifique dev.firmware_version ≥ 0x03 antes da chamada verifique dev.firmware_version

Todas as exceções têm uma mensagem __str__ com significado — o pacote constrói cuidadosamente as mensagens de erro com contexto.

Tabela-resumo dos contadores de diagnóstico

Numa execução saudável de soak (o harness de soak longo de 1 hora) todos permanecem a zero:

Contador Regime estacionário Reinício Disponibilidade
dev.sanity_reject_count 0 dev.reset_counters() ambos os runtimes
MachineI2CBackend.retry_exhaustion_count 0 backend.reset_counters() Apenas MicroPython
MachineI2CBackend.retry_count_total baixo (~5-20 por hora é normal) backend.reset_counters() Apenas MicroPython
fração de dados obsoletos em instantâneos de período < 1 % (acumulado — sem repor) ambos os runtimes

Se algum destes valores for diferente de zero em regime estacionário, volte à secção correspondente acima.

Depuração ao nível do barramento com um analisador lógico

Para depuração profunda, quando o pacote já não consegue dizer o que se passa no fio, capture SDA + SCL com um analisador lógico (Saleae, DSLogic Plus, qualquer um compatível com Sigrok):

  • Taxa de amostragem ≥ 1 MS/s a 100 kHz de I²C; ≥ 4 MS/s a 400 kHz.
  • O descodificador I²C no Sigrok / Saleae mostrará ACK / NACK para cada byte + a fase de endereço.

  • Compare as chamadas do seu script (dev.voltage, etc.) com a sequência de bytes esperada — devem coincidir exatamente. As leituras admitem rajada (auto-incremento). As escritas NÃO fazem auto-incremento (um byte de cada vez para registos de vários bytes).

Se o comportamento do pacote divergir da captura, abra um issue com o ficheiro de captura anexado (.sal / .dsl / .csv).

Quando contactar o suporte

Se já percorreu a secção correspondente acima e o problema persiste, abra um issue:

github.com/rb-amp/rbamp-python/issues

No issue inclua:

  • Runtime + versão: python --version / mpremote eval 'import sys; print(sys.version, sys.implementation)'.

  • Plataforma anfitriã: "RPi 4B Bookworm", "ESP32-S3 N16R8 MicroPython 1.22", etc.

  • Versão do pacote: rbamp --version (CPython) ou python -c "import rbamp; print(rbamp.__version__)".

  • Versão do firmware do módulo — dev.firmware_version nos registos.

  • Um script mínimo (~30 LOC) que reproduza o problema.
  • O traceback da exceção com o contexto completo.
  • Os contadores no momento da falha: dev.sanity_reject_count, backend.retry_exhaustion_count (apenas uPy).

  • Os registos verbosos da biblioteca — a forma mais simples de os recolher é dev.set_logger(print) antes da operação que falha. O pacote imprime os seus passos internos (o ciclo de retry, os timeouts de estabilização, o primer do snapshot, etc.) — anexe o stdout ao problema.

  • (Se disponível) o ficheiro de captura do analisador lógico.

CLI — rbamp scan / rbamp read / rbamp address

A CLI rbamp é um invólucro fino sobre RbAmp.* para operações de bancada (ver 09 · Referência da API, a secção "CLI"). Como usa a mesma classe RbAmp, TODOS os sintomas acima se aplicam. Erros específicos da CLI:

  • rbamp scan não encontra nada — o mesmo que no Passo 1 da secção "O módulo não responde por I²C" acima. Verifique diretamente com i2cdetect -y 1. Se o encontrar, é um problema da deteção automática do nosso backend; abra um issue com o resultado de rbamp --verbose scan.

  • rbamp falha com PermissionError: /dev/i2c-1 — o utilizador não está no grupo i2c. Veja a secção de Instalação do README para sudo usermod -aG i2c $USER + nova sessão.

  • rbamp: command not found após pip install — a entrada de consola [project.scripts] não está ativa. Verifique se pip show rbamp mostra a localização instalada; confirme que $HOME/.local/bin está em $PATH (para pip install --user).


Fonte e problemas: rb-amp/rbamp-python · esta página no repositório: docs/10_troubleshooting.md (v1.6.1)