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

10 · Resolução de problemas

Árvore de decisão de resolução de problemas: do sintoma a uma verificação rápida e a uma ação.

Este capítulo está organizado pelos sintomas observados, e não pela classificação interna de erros. Se chegou aqui, algo não funciona como deveria. Encontre o seu sintoma na lista abaixo, salte para a secção correspondente e siga o procedimento de diagnóstico.

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

  1. Nível de barramento — o módulo não responde por I²C, as leituras devolvem NaN ou RB_ERR_NACK.

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

  3. Nível da aplicação — a ligação é instável, o contador de Wh diverge, o esboço fica bloqueado.

Atalho para quem tem pressa: os contadores dev.retryExhaustionCount() e dev.sanityRejectCount() têm de estar a 0 em regime estacionário. Se não estiverem, vá diretamente à secção «O módulo não responde por I²C» abaixo.

Verificar primeiro: U=0 → L/N não ligados ou disjuntor desligado; I=0 → conector da CT não totalmente inserido (ou nenhum modelo de TC definido, ver abaixo).

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

O que observa: dev.begin() devolve false com lastError() == RB_ERR_NACK, ou as leituras em execução «deixam escapar» regularmente RB_ERR_NACK para o código do utilizador.

Passo 1 — Pesquisa no barramento

Primeiro, confirme que o módulo está mesmo presente no barramento:

C++
#include 

void setup() {
    Serial.begin(115200);
    Wire.begin();
    Serial.println(F("Scanning..."));
    for (uint8_t addr = 0x08; addr <= 0x77; addr++) {
        Wire.beginTransmission(addr);
        if (Wire.endTransmission() == 0) {
            Serial.print(F("Found 0x")); Serial.println(addr, HEX);
        }
    }
}
void loop() {}

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

Se não encontrar nada — o problema está na ligação ou na alimentação:

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

  • O pino de alimentação do módulo transporta de facto 5 V (4.5–5.5 V) — as revisões de placa mais antigas não toleram 3.3 V.

  • Nenhum outro master (sonda de depuração, outro Arduino) está pendurado nas mesmas linhas.

Se o módulo é encontrado, mas num endereço inesperado — alguém o reendereçou antes na bancada. Atualize o argumento do construtor:

C++
RbAmp dev(Wire, 0x52);   // address from the bus scan

Passo 2 — Padrão de NACK de base do ESP32

Se a pesquisa do barramento encontrar o módulo, mas dev.readVoltage() devolver periodicamente NaN com RB_ERR_NACK — e estiver num ESP32 — trata-se de um padrão de base documentado: o driver i2c_master do ESP-IDF v5 tem particularidades ao trabalhar com o rbAmp no firmware v1.0.

A mitigação já está incorporada na biblioteca (RBAMP_NACK_RETRY_ATTEMPTS=3 por predefinição no ESP32), mas sob carga pesada o orçamento de repetições pode esgotar-se.

O que fazer no ESP32:

  1. Reduza a velocidade do barramento para 50 kHz:
C++
Wire.begin();
Wire.setClock(50000);
  1. Aumente o número de tentativas de repetição para uma carga pesada:
C++
#define RBAMP_NACK_RETRY_ATTEMPTS 5
#include 
  1. Monitorize o contador de esgotamento de repetições — deve manter-se a zero em regime estável:
C++
if (dev.retryExhaustionCount() > 0) {
    Serial.print(F("WARN: retry exhausted: "));
    Serial.println(dev.retryExhaustionCount());
}

Passo 3 — NACKs em plataformas não-ESP32

Em AVR / STM32duino / ESP8266 / SAMD / RP2040 não existe padrão de NACK de base — estas plataformas mostram uma taxa de NACK de ~0 % com o rbAmp. A biblioteca usa por predefinição RBAMP_NACK_RETRY_ATTEMPTS=1 nelas.

Se ocorrerem NACKs aqui, procure:

  • Capacidade elevada do barramento — cabos longos + muitos dispositivos. Reduza a velocidade para 100 kHz ou encurte o cabo.

  • Contenção de mestres — a biblioteca não suporta uma configuração multimestre.

  • Um SCL flutuante entre transações — um pull-up em falta.

A corrente lê zero numa carga em funcionamento

O que observa: dev.readCurrent(0) devolve 0.000 (ou um valor muito pequeno), apesar de um consumidor real estar ligado (uma chaleira, uma lâmpada, um ferro). dev.readPowerFactor(0) pode mostrar um valor estranho (NaN / 0 / ±1) — isso é 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:
C++
if (!dev.setSensorClass(RbAmpSensorClass::Sct013)) {
    Serial.println(F("class set failed"));
}
if (!dev.setCTModel(3)) {   // or your model: see below
    Serial.println(F("model set failed"));
}

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 é guardada na flash do módulo.

  1. Verifique se o modelo de TC corresponde à carga. Uma pinça de TC grande (por exemplo, SCT-013-100, 100 A) numa carga pequena (uma lâmpada de 50 W ≈ 0.2 A) produz um sinal mesmo no piso de ruído e as leituras serão zero. Escolha a pinça de menor calibre acima da sua maior corrente 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 de duplo TC: uma pinça pequena (por exemplo, SCT-013-005) num canal dedicado para a gama baixa + uma grande (SCT-013-030/100) noutro canal para a gama alta; o mestre seleciona o valor por um limiar. O padrão é discutido em 03 · Seleção do sensor de corrente, secção "Topologia de duplo TC".

  1. Verifique a orientação da pinça. A seta no corpo da pinça tem de apontar no sentido da corrente em direção à carga. Se a pinça estiver "ao contrário", readCurrent() dará a magnitude correta, mas readPower() dará um valor negativo numa carga de consumo. A confirmação — readPowerFactor() mostrará exatamente −1.0 numa carga resistiva (em vez de +1.0). A correção: reinstale fisicamente a pinça (com o circuito desligado: solte-a, rode a seta no sentido certo, volte a fixá-la). Não inverta o sinal em software.

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 há corrente a passar de facto — meça-a com um multímetro (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, a linha (L); nunca o cabo inteiro.

As leituras saltam ou voltam como NaN

O que observa: dev.readVoltage() ou dev.readCurrent() devolvem periodicamente NaN. dev.lastError() mostra RB_ERR_NACK ou RB_ERR_NON_PHYSICAL.

Se lastError() mostrar RB_ERR_NACK

Veja a secção «O módulo não responde por I²C» acima — é da mesma classe de problema, com uma diferença: a ligação está parcialmente a funcionar, mas o orçamento de repetições esgota-se ocasionalmente.

Steps:

  1. No ESP32 — baixe a velocidade para 50 kHz e aumente RBAMP_NACK_RETRY_ATTEMPTS=5.

  2. Noutras plataformas — verifique a capacidade do barramento e as resistências de pull-up.

  3. Monitorize dev.retryExhaustionCount() para acompanhar a tendência.

Se lastError() mostrar RB_ERR_NON_PHYSICAL

O filtro de sanidade da biblioteca disparou: chegou do barramento um float que é NaN, ou Inf, ou |x| > 10000 — obviamente não é um valor físico. A biblioteca descarta esse valor e reporta RB_ERR_NON_PHYSICAL em vez de deixar lixo chegar aos dados da aplicação.

Trata-se de um artefacto raro. O valor em regime estável de dev.sanityRejectCount() é 0. Se não for zero:

  1. Verifique dev.retryExhaustionCount(). Se ambos os contadores forem diferentes de zero, a ligação é instável e o filtro de sanidade está a apanhar lixo após repetições falhadas. Aumente o orçamento de repetições (ver acima).

  2. Se retryExhaustionCount == 0 mas sanityRejectCount > 0, um artefacto passou pela camada de repetição. Isto acontece com carga muito pesada no barramento. Aumente RBAMP_NACK_RETRY_ATTEMPTS=5 e repita o teste.

C++
Serial.print(F("retries exhausted: "));
Serial.print(dev.retryExhaustionCount());
Serial.print(F("  sanity rejects: "));
Serial.println(dev.sanityRejectCount());

O fator de potência parece estranho

O que observa: dev.readPowerFactor(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, motor de compressor +0.6 .. +0.85 (indutivo)
Lâmpada LED, TV (fonte comutada) +0.5 .. +0.95 (não linear)
Inversor PV a exportar potência PF negativo

PF = NaN ou 0 quando I = 0

O PF é definido como P / (U × I). Com corrente zero I=0 a conta é indefinida. O valor concreto devolvido depende do firmware (pode ser NaN, 0, ou um marcador) — isto é normal enquanto a corrente for genuinamente zero. Assim que houver corrente, haverá um PF válido.

O PF é exatamente −1.0 numa carga puramente de consumo

A pinça foi instalada «ao contrário» — a seta não aponta no sentido da corrente em direção à carga. A correção: volte a instalar a pinça corretamente (rode-a fisicamente; não inverta o sinal em software).

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

  • Causa possível: a pinça de TC está a ser colocada num fio de uma fase diferente da ligada à entrada U do módulo. Num quadro de distribuição com várias fases é fácil pôr a pinça na fase errada — um desfasamento de 120° ou 180° entre U e I dá exatamente estes valores de PF. A correção é instalar o módulo de forma que a entrada U e a pinça estejam na mesma fase.

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

Os instantâneos de período estão sempre stale

O que observa: dev.readPeriodSnapshot(snap) devolve false com lastError() == RB_ERR_STALE. Isto significa que o módulo não terminou de integrar o período anterior até ao momento da leitura seguinte.

A biblioteca protege contra a dupla contagem de Wh: numa leitura desatualizada regista um carimbo temporal do master, e o instantâneo válido seguinte cobre um período, não dois.

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

Procedimento de verificação da cadência

  1. Verifique a cadência: 60 s entre instantâneos é confortável; 30 s é marginal; < 10 s garante instantâneos obsoletos.

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

C++
if (dev.probe()) {
    Serial.println(F("alive"));
}
  1. Verificação direta da flag — dev.isPeriodValid() faz uma leitura de um byte sem efeitos colaterais.

  2. Verifique a versão do firmware — dev.firmwareVersion() deve devolver 0x04 (v1.3, produção atual); firmwares mais antigos (0x01 v1.0 / 0x02 v1.1 / 0x03 v1.2) mostram mais leituras desatualizadas.

A contabilidade de Wh diverge de uma referência

O que observa: dev.energy().wh(0) diverge, após várias horas / dias de funcionamento, da leitura do contador da rede ou de um contador de referência (Kill-A-Watt e similares).

Primeiro descarte o trivial

  1. Calibração do sensor de corrente: certifique-se de que setSensorClass() e setCTModel() foram chamados com o modelo de 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. Instantâneos obsoletos descartados: se dev.energy().wh() estiver sistematicamente abaixo da referência, podem ter-se perdido intervalos — um instantâneo voltou obsoleto, a biblioteca protegeu contra dupla contagem, mas a medição do intervalo perdeu-se. Verifique a cadência (ver acima).

  3. Deriva do relógio do mestre: o millis() é fiável por si só. Mas se o mestre entrar em deep-sleep sem preservar o RTC, perde-se o intervalo entre o instantâneo anterior e o seguinte. Ative o RTC para estes cenários.

Precisão do acumulador por plataforma

Plataforma Tipo do acumulador
ESP32 / ESP8266 / STM32duino / SAMD / RP2040 double de 64 bits
Arduino AVR (Uno, Mega, Nano) float de 32 bits (toolchain)

A integração do lado do master não acrescenta qualquer erro próprio para além da precisão de potência ativa do módulo.

Para o AVR em instalações de ensaio de longa duração, reponha periodicamente o acumulador e guarde o total de longo prazo no seu próprio armazenamento persistente:

C++
// Once a day in the MQTT-publish hook
mqtt.publish("rbamp/wh_daily", String(dev.energy().wh(0)));
dev.energy().reset(0);

snap.latch_ms difere do período real

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

RB_ERR_STALE em todas as leituras — o master mantém automaticamente a âncora

O que observa: dev.readPeriodSnapshot(snap) devolve periodicamente false com lastError() == RB_ERR_STALE. (Veja também a secção "Os instantâneos de período estão sempre obsoletos" acima.)

Tratamento canónico de dt: numa leitura obsoleta a biblioteca Arduino NÃO põe a zero a sua âncora interna _last_latch_ms. A leitura válida seguinte obtém um master_dt igual ao intervalo completo desde o instantâneo bem-sucedido anterior — isto é, cobre tanto o período "perdido" obsoleto como o atual. O firmware preserva o acumulador avg_p ao longo de um instantâneo vazio (persistência do lado do firmware): no instantâneo válido seguinte, este já é o valor médio sobre o intervalo inteiro. A integração de Wh mantém-se exata — sem dupla contagem, sem subcontagem.

Não é necessário tratamento especial de leituras desatualizadas no código do master: a biblioteca faz tudo corretamente, de forma automática. Basta ignorar RB_ERR_STALE se for raro; se for frequente, diagnostique a cadência (secção acima).

O esboço ESP32 bloqueia após alguns minutos

O que observa: o esboço no ESP32 arranca bem, depois entra num bloqueio / ciclo de reinícios / timeout do WDT após 1–30 minutos.

Wire bloqueia num barramento marginal — mitigação em três camadas

O que observa concretamente: um sketch num ESP32 (núcleo Arduino-ESP32) consulta o rbAmp sem problemas durante vários minutos e depois "morre", bloqueando a meio de uma chamada a dev.readAll(...) / dev.readVoltage() / fleet.pollAll(). Se o task-WDT estiver ativo, ele apanha o bloqueio; caso contrário, o sketch simplesmente deixa de responder. O backtrace descodificado termina na função i2c_ll_is_bus_busy (o driver IDF i2c_master, ficheiro i2c_master.c:526, espera de barramento ocupado antes do envio).

O que está a acontecer: o Wire do Arduino-ESP32 envolve o mesmo driver IDF i2c_master dos projetos ESP-IDF nativos. Num barramento limítrofe (pull-ups fracas, pistas longas, EMI, interferência de ZC), SDA/SCL podem "encravar" brevemente num estado indefinido. Antes de cada transação o IDF i2c_master fica a rodar no ciclo i2c_ll_is_bus_busy, à espera que o barramento se liberte — esta espera NÃO é limitada pelo timeout I²C da biblioteca. Se o barramento ocupado durar mais do que a espera sem deixar outras tarefas correr, a tarefa IDLE do FreeRTOS não recebe CPU e todo o sketch fica bloqueado.

Isto não é um "artefacto exclusivo do depurador". Validado na bancada (o mesmo equipamento de teste e a mesma 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Ω no SDA/SCL do DUT 0 bloqueios (ensaio de 12 min, 1300 ciclos, 0 reinícios, 0 disparos do WDT)

A correlação é clara — a correção da integridade do barramento elimina o bloqueio por completo. A lógica da biblioteca não está em causa: RbAmpFleet::pollAll(), os módulos individuais em MISS e os contadores de repetição/sanidade mantiveram-se limpos em todas as execuções até ao próprio bloqueio.

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

  1. Pull-up externa (~4.7 kΩ) em SDA e SCL para 3.3 V num único ponto do barramento. As resistências de pull-up internas do ESP32 (~45 kΩ) são fracas para um barramento multimódulo de comprimento real, enquanto as de 4.7 kΩ integradas nos módulos, em paralelo, ficam demasiado fortes. Num barramento assim, corte as integradas em todos os módulos exceto um (ou em todos — e então depende apenas das externas). Ver 04 · Ligação, secção "Barramento multimó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 reinício pode manter SDA/SCL num estado indefinido ao desligar/ligar, provocando um bloqueio do barramento na transação seguinte. Numa compilação de campo (sem depurador) este fator desaparece.

  3. WDT de tarefa ao nível da aplicação na tarefa de consulta — defesa em profundidade. Se, por alguma razão, os pull-ups ficarem marginais, ou surgir outra causa de bloqueio, o WDT reinicia o esboço. Ensaio de 12 min na bancada: o WDT apanhou e recuperou os 12 bloqueios na configuração sem pull-up externo. Pull-ups adequados no barramento — correção no terreno; WDT da aplicação — postura de recuperação.

C++
#include "esp_task_wdt.h"

void setup() {
    // Layer 3 setup — defense-in-depth.
    esp_task_wdt_config_t wdt_cfg = {
        .timeout_ms = 8000,            // 8 s with a large margin
        .idle_core_mask = 0,
        .trigger_panic = true,         // on timeout — panic+reboot
    };
    esp_task_wdt_reconfigure(&wdt_cfg);
    esp_task_wdt_add(NULL);            // this task (loop) under WDT

    // ... rest of the initialization ...
}

void loop() {
    fleet.pollAll(snaps, status, RBAMP_FLEET_MAX_MODULES, n_ok);
    // ... processing ...
    esp_task_wdt_reset();              // "I'm alive" — every cycle
    delay(200);
}

O que NÃO fazer: não tente contornar o problema com um parâmetro maior de Wire.setTimeout() — não limita a espera prévia com o barramento ocupado, que é outro caminho de código no driver IDF. A correção é a integridade do barramento (camada 1) + um supervisor (camada 3).

Timeout do watchdog em wifi_connect()

Causa: o ciclo sem limite while (WiFi.status() != WL_CONNECTED) delay(500) dispara o task-WDT após ~5 s (predefinição).

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

C++
uint32_t t0 = millis();
while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    if (millis() - t0 > 30000) { ESP.restart(); }
}

O broker MQTT desliga-se a cada ~15 s

Causa: o PubSubClient usa por predefinição keepalive = 15 s, enquanto o mqtt.loop() só é chamado no caminho "lento" (uma vez a cada 60 s, junto com readPeriodSnapshot()).

Correção: defina o keepalive para 60 s e chame mqtt.loop() em cada passagem de loop():

C++
mqtt.setKeepAlive(60);

void loop() {
    if (!mqtt.connected()) mqtt.connect("rbamp-id");
    mqtt.loop();    // every iteration, not once every 60 s
    // ...rest of the logic, slowed down via millis()...
}

Falha do handshake TLS (integrações na cloud)

Causa: o heap do ESP32 é insuficiente para o handshake TLS (~30 kB necessários). Costuma combinar-se com WiFi + MQTT + buffers — deixando menos de 20 kB.

Fix:

  • Reduza setBufferSize() do cliente MQTT ao mínimo.
  • Use WiFi.mode(WIFI_STA) (e não WIFI_AP_STA).
  • Desative o BLE: btStop() em setup().

Se ESP.getFreeHeap() mostrar < 25 kB antes de client.connect(), o handshake TLS vai muito provavelmente falhar.

setSensorClass() / setCTModel() devolve RB_ERR_PARAM

O que observa: uma das chamadas de configuração devolve false, lastError() == RB_ERR_PARAM.

Possíveis causas:

  1. setCTModel() chamado antes de setSensorClass(). Primeiro a classe do sensor, depois o modelo — ver 03 · Seleção do sensor de corrente e 09 · Referência da API § Configuração do sensor.

  2. Código de modelo inválido — para a classe Sct013 o conjunto válido é {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 · Seleção do sensor de corrente. Os códigos que não correspondem à classe devolvem RB_ERR_PARAM (guarda do lado da biblioteca, antes do barramento) ou DEV_ERR_PARAM (do lado do firmware, se o YAML passar).

  3. Índice de canal inválido na forma por canal setCTModel(channel, code) — tem de ser < dev.channels(). Um canal igual ou superior a RBAMP_MAX_CHANNELS (7) nunca é exposto e também devolve RB_ERR_PARAM.

  4. O módulo rejeitou o código — um código que está no registo mas que o módulo não aceita é recusado pelo módulo; o canal mantém o modelo anterior.

Se a chamada devolver false com RB_ERR_MODE, o módulo é de uma classe emparelhada de fábrica (WiredCT / BuiltinCT) — foi fornecido e calibrado em conjunto com o seu sensor e os setters não o reescrevem. Para voltar a emparelhar em assistência técnica use setCTModelChForce().

Comportamento esperado, não é uma falha:

  • Definir uma classe ou modelo que o módulo já tem é uma operação nula (true, sem escrita no barramento, sem ciclo de flash).

  • Definir um modelo de TC reinicia o módulo em firmware BASIC até 1.4.19 com a classe SCT-013 (cerca de um segundo, bloqueante). As leituras ficam indisponíveis nesse período; a biblioteca volta a ler a correção de classificação depois.

  • Após mudar o modelo SCT-013, as leituras de corrente, potência e energia seguem automaticamente o novo calibre (o fator de potência e a tensão não são afetados). dev.sctRating(ch, r) mostra o estado por canal; se indicar UnexpectedGain ou Unknown, não é aplicada correção (escala 1).

Notas sobre o módulo STD (STANDARD)

A linha STD usa a mesma ligação I²C que o BASIC (ver 04 · Ligação); dev.begin() deteta-a e dev.line() indica qual a linha que tem. Coisas específicas do STD:

  • RB_ERR_NOT_IMPLEMENTED numa chamada std*, em readReactivePower() ou em readApparentPower() — o módulo ligado é BASIC (verifique dev.line()). Inversamente, as chamadas apenas-BASIC (factoryReset(), Chamada Geral, auxiliares de etiqueta, readCapability(), readCommitSeq()) devolvem-no num módulo STD.

  • Uma funcionalidade indica «não disponível» — energia de micro-resolução (RbAmpStdEnergy::fine == false), a corrente de arranque para a energia (RB_ERR_NOT_IMPLEMENTED), os ângulos de fase de tensão (angle_valid == false) e a sequência de fases (NotAvailable) dependem da versão da imagem do módulo: exigem uma imagem de pelo menos 0x0001007B. Leia-a com dev.stdReadImageVersion(); numa imagem mais antiga o valor não está disponível, não está errado.

  • O ângulo de tensão / a sequência de fases continuam «não disponíveis» numa imagem recente — exigem que todas as entradas de tensão estejam energizadas e sejam mensuráveis, e um módulo de três tensões para a sequência de fases.

  • As leituras de instantâneo de período voltam vazias (RB_ERR_STALE) após um reinício do módulo — esperado: o armamento do instantâneo vive na RAM do módulo. A biblioteca volta a armar o banco e descarta esse período; reinicie a sua própria âncora dt. Aguarde pelo menos 300 ms entre stdLatch() e stdReadLatch().

  • Sem registos de histórico — o módulo só regista histórico enquanto o seu relógio estiver definido. O relógio perde-se a cada reinício do módulo: chame dev.stdSetTime() após begin() e sempre que stdReadHealth() indicar time_valid == false.

  • Um comando devolve RB_ERR_PARAM — na STD o veredito de cada comando é lido de volta; o módulo rejeitou o valor e ficou inalterado.

  • Uma gravação devolve RB_ERR_NOT_READY — o módulo limita a frequência com que escreve o seu armazenamento; a biblioteca já repete uma vez após 5 s.

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

Comportamento na v1.3: REG_ERROR (0x02) é o resultado da última escrita, e NÃO é pegajoso. Em cada escrita de registo o firmware define reg_error = ERR_OK; uma escrita não relacionada subsequente limpa o erro anterior.

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

Padrão 1 — captura pontual pós-operação (se o resultado desta operação específica importar):

C++
bool ok = dev.saveUserConfig();
uint8_t dev_err = dev.readReg(0x02);   // IMMEDIATELY, before the next write

Padrão 2 — monitorização de erros durável (canónico):

C++
uint8_t event_flags = dev.readReg(0x2A);
if (event_flags & (1 << 3)) {
    uint8_t last_err = dev.readReg(0x02);
    // handle
    dev.writeReg(0x2A, (1 << 3));        // W1C clear bit3
    // or dev.clearError();
}
Segurança

⚠ REG_ERROR é o resultado da última escrita, não persistente. A durabilidade é assegurada pelo bit3 de EVENT.

⚠ O bit3 é um canal assíncrono, não para validação síncrona de escrita: numa escrita rejeitada, o bit3 é ativado com atraso em relação ao momento em que a transação I²C retorna. 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 lastError() logo após a operação) ou o código de retorno do setter. O bit3 serve para a 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.

lastError() vs readLastError() — dois canais diferentes, não sinónimos

Duas funções com nomes semelhantes, mas semânticas completamente diferentes:

lastError() readLastError(out)
O que devolve Código RB_ERR_* em cache da biblioteca, da chamada anterior à biblioteca Uma única leitura de fio do registo REG_ERROR (0x02) do dispositivo
Uma operação I²C? Não — apenas uma leitura de memória Sim — uma única transação de leitura
Semântica Resultado da validação do lado da biblioteca (proteção do cliente, estado de repetição, etc.) Resultado da última escrita no lado do dispositivo (mnemónico DEV_ERR_*)
Quando é atualizado Após cada método da biblioteca Após cada escrita aceite pelo barramento no dispositivo
Valor de exemplo RB_ERR_PARAM após uma guarda do lado do cliente 0xFE (DEV_ERR_PARAM) após uma escrita rejeitada no dispositivo
Exemplo de incompatibilidade lastError() == RB_ERR_PARAM (o setter bloqueou-a antes do barramento) readLastError() → 0x00 (nada chegou ao dispositivo)

Quando usar cada um:

  • lastError() — para a lógica da aplicação, interpretar os resultados do lado da biblioteca (repetição, recurso, classificação de erros), sem sobrecarga I²C.

  • readLastError() — quando quer o código de causa estendido do lado do dispositivo (por exemplo, DEV_ERR_PARAM (0xFE) vs DEV_ERR_NOT_READY vs DEV_ERR_FLASH_PARAMS_BAD (0xFB)) no Canal B (rejeição do lado do DUT). Ver o §«modelo de erros v1.3 — dois canais independentes» em 09 · Referência da API.

A distinção é especialmente importante na depuração do Canal A (proteção do lado do cliente): o setter devolve false + lastError() == RB_ERR_PARAM, mas readLastError() == 0x00 — porque a biblioteca o bloqueou antes da operação no barramento e o REG_ERROR do dispositivo não foi tocado.

Atenção: DEV_ERR_CLONE (0xF9) NÃO é limpo via CMD_CLEAR_ERROR — é uma sentinela anticlonagem (só um reinício ou uma reposição de fábrica o limpa).

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

O que observa: um módulo recém-gravado, no primeiro arranque, mostra 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, depois dev.saveUserConfig(). Após um SAVE bem-sucedido → REG_ERROR = 0x00, bit3 limpo.

commitAddressChange() devolve RB_ERR_TIMEOUT

O que observa: prepareAddressChange() passou, mas commitAddressChange() devolve false, lastError() == RB_ERR_TIMEOUT.

Causa: a janela de estado armado (5 s após prepareAddressChange) expirou. WiFi/MQTT ou qualquer E/S bloqueante entre prepare e commit é a principal fonte de expiração da janela. dev.probe() não ajuda aqui (o módulo responde; o problema está na máquina de estados).

O que fazer: chame prepareAddressChange() de novo e de imediato, na mesma iteração de loop(), sem chamadas de rede pelo meio, e depois chame commitAddressChange().

Nota

✅ REG_I2C_ADDRESS (0x30) passa agora a ler o endereço ATIVO no arranque (v1.3). Após um reinício pós-commit, ler 0x30 mostrará o novo endereço ativo. Para a verificação mais fiável de um commit de endereço em duas fases, tente uma leitura no novo endereço (deve dar ACK no barramento). Após uma escrita do anfitrião (preparação), o registo repete o candidato preparado até CMD_COMMIT_ADDR + reinício — isto é um comportamento por conceção.

Para mais sobre o commit de endereço em duas fases, veja 09 · Referência da API e 04 · Ligação.

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

O que observa: dev.readVoltage() / dev.readCurrent() devolvem periodicamente NAN, lastError() == RB_ERR_NACK ou RB_ERR_IO — mas apenas durante a comutação ativa de uma carga com relé/indutiva na mesma instalação. As leituras em regime estacionário são fiáveis.

Causa: durante a comutação de relés (carga de 5 A) a EMI faz falhar ~67 % das transações I²C (~8/12 na medição em hardware). O barramento recupera-se sozinho, não há bloqueio, nenhum módulo se perde — mas a leitura de corrente falha.

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

C++
float robust_read_voltage(RbAmp& dev) {
    for (int attempt = 0; attempt < 5; attempt++) {
        float v = dev.readVoltage();
        if (!isnan(v)) return v;
        delay(20);   // a short pause before the retry
    }
    return NAN;
}
Segurança

⚠ A recuperação do barramento do lado da biblioteca não é suficiente por si só: quando um glitch de EMI se sobrepõe à janela de repetição do driver, é necessária uma repetição explícita ao nível da aplicação com uma pausa.

Alternativa: se o master vir os eventos de comutação dos relés, atrase as leituras em ~50–100 ms após a comutação.

Tabela-resumo dos códigos de erro

dev.lastError() devolve um destes códigos após cada chamada da API pública. RbAmp::errorString(code) devolve uma cadeia legível por pessoas.

Código Cadeia de caracteres Quando Onde procurar
RB_OK (0) "OK" sucesso —
RB_ERR_IO (-1) "Falha de transporte I2C" o driver do barramento devolveu um resultado diferente de OK cablagem, alimentação, pull-ups
RB_ERR_NACK (-2) "NACK — dispositivo ausente ou ocupado" repetições esgotadas secção "O módulo não responde por I²C"
RB_ERR_TIMEOUT (-3) «Tempo limite do barramento» a janela de waitReady / waitDataReady / commitAddressChange expirou secção «commitAddressChange() devolve RB_ERR_TIMEOUT»
RB_ERR_NOT_READY (-4) «Dispositivo não pronto» o módulo não está pronto / não existe esse registo de histórico / nada está armado / nada responde no novo endereço as notas STD acima
RB_ERR_STALE (-5) "Instantâneo de período obsoleto" o flag de período pronto = 0 Secção «Os instantâneos do período estão sempre desatualizados»
RB_ERR_PARAM (-6) «Parâmetro inválido» índice de canal inválido / código de modelo inválido / intervalo de endereços inválido secção «setSensorClass() / setCTModel() devolve RB_ERR_PARAM»
RB_ERR_MODE (-7) «Não permitido no modo atual do módulo (requer modo de fábrica / caminho de assistência técnica)» uma operação exclusiva de fábrica, ou um setter de TC num módulo de classe WiredCT / BuiltinCT não chame operações exclusivas de fábrica em firmware de produção; use setCTModelChForce() apenas para o reemparelhamento de assistência
RB_ERR_CHECKSUM (-8) "Verificação de valor falhou — checksum / assinatura / intervalo" a verificação de valores do módulo falhou (STD: imagem de firmware rejeitada, CRC da carga, época fora do intervalo, anel de histórico vazio) reenvie a página / verifique a imagem
RB_ERR_VERSION (-9) «Versão de firmware não suportada» REG_VERSION = 0 / 0xFF verifique a ligação do módulo
RB_ERR_NOT_IMPLEMENTED (-10) "Não implementado neste firmware" a chamada não tem equivalente na linha detetada, ou a imagem do módulo não fornece a funcionalidade dev.line(), dev.stdReadImageVersion()
RB_ERR_NON_PHYSICAL (-11) "Valor não físico (NaN/Inf/fora dos limites)" o filtro de sanidade rejeitou um float Secção "As leituras saltam ou voltam como NaN"

Tabela-resumo dos contadores de diagnóstico

Numa execução de ensaio prolongado saudável (12 h, o esboço SoakMonitor) todos ficam a zero:

Contador Regime estacionário Reinício
dev.retryExhaustionCount() 0 dev.resetCounters()
dev.sanityRejectCount() 0 dev.resetCounters()
dev.lastError() após uma leitura RB_OK (0) automaticamente na chamada seguinte
fração de dados obsoletos em instantâneos de período < 1 % (acumulado — sem repor)

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

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

Para depuração profunda, quando a biblioteca já não consegue dizer o que está a acontecer no fio, capture SDA + SCL com um analisador lógico (Saleae, DSLogic Plus, ou 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 em cada byte
  • a fase de endereço.
  • Compare as chamadas do seu esboço (dev.readVoltage() etc.) com a sequência de bytes esperada — devem coincidir exatamente. As leituras em rajada (vários bytes numa só transação através do auto-incremento de endereço) são suportadas. As escritas NÃO são auto-incrementadas — cada byte é uma transação separada.

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

Quando contactar o suporte

Se tiver trabalhado a secção relevante acima e o problema persistir, abra um issue:

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

No problema, inclua:

  • MCU anfitrião + versão do núcleo Arduino (por exemplo, ESP32-S3 com Arduino-ESP32 3.0.4).

  • Versão da biblioteca (RbAmp do Gestor de Bibliotecas [Library Manager]).

  • Versão do firmware do módulo — dev.firmwareVersion().
  • Esboço mínimo que reproduz o problema (~30 LOC).
  • dev.lastError() + dev.errorString(dev.lastError()) + dev.retryExhaustionCount() + dev.sanityRejectCount() no momento da falha.

  • (Se disponível) um ficheiro de captura do analisador lógico do momento da falha.


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