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

10 · Resolução de problemas

Este capítulo está organizado pelos sintomas que observa, e não por classificação interna de erros. Se chegou aqui, algo não está a funcionar bem. 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. Ao nível do barramento — o módulo não responde por I²C; as leituras devolvem ESP_FAIL ou ESP_ERR_INVALID_RESPONSE.

  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 de Wh desvia-se, o projeto bloqueia.

Atalho para quem tem pressa: em regime estacionário, as funções públicas rbamp_* devem devolver ESP_OK. Se vir frequentemente ESP_FAIL ou ESP_ERR_INVALID_RESPONSE nos registos, salte diretamente para a secção "O módulo não responde por I²C" abaixo.

Árvore de decisão para resolução de problemas, agrupada por sintoma.

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

O que vê: rbamp_begin(dev) devolve ESP_FAIL ou ESP_ERR_INVALID_RESPONSE, ou as leituras RT propagam regularmente ESP_FAIL para o seu código.

Passo 1 — Pesquisa no barramento

Primeiro, confirme que o módulo está mesmo presente no barramento. O ESP-IDF v5.x fornece i2c_master_probe() precisamente para isto:

C
#include "driver/i2c_master.h"
#include "esp_log.h"

static const char *TAG = "i2c_scan";

void bus_scan(i2c_master_bus_handle_t bus) {
    ESP_LOGI(TAG, "Scanning...");
    for (uint8_t addr = 0x08; addr <= 0x77; addr++) {
        if (i2c_master_probe(bus, addr, /*xfer_timeout_ms=*/100) == ESP_OK) {
            ESP_LOGI(TAG, "Found 0x%02X", addr);
        }
    }
}

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 (ver 04 · Cablagem para os valores GPIO predefinidos de cada chip).

  • Ambas as linhas têm um pull-up para 3.3 V (a placa do módulo tem 4.7 kΩ integrados — para um único módulo não são necessários externos).

  • O pino de alimentação do módulo tem de facto 5 V (4.5–5.5 V).

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

  • flags.enable_internal_pullup = true na sua i2c_master_bus_config_t (se não houver pull-ups externos).

Se o módulo for encontrado mas num endereço inesperado — alguém o reendereçou anteriormente na bancada. Atualize o segundo argumento de rbamp_new:

C
rbamp_new(bus, 0x52, &dev);   /* address from the bus scan */

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

Se a varredura do barramento encontrar o módulo mas rbamp_read_voltage(dev, 0, &v) devolver periodicamente ESP_FAIL — este é um padrão de referência documentado: o driver i2c_master do ESP-IDF v5 tem particularidades ao trabalhar com o rbAmp no firmware atual (NACKs frequentes a 100 kHz).

A mitigação já está incorporada no componente (CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=3 por defeito, 50 kHz via CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000), mas sob carga intensa o orçamento de retentativas pode esgotar-se.

O que fazer através de idf.py menuconfig → Component config → rbAmp client:

  1. Confirme o padrão de 50 kHz:
Text
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000
  1. Aumente o número de repetições para carga pesada:
Text
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=5
  1. Se for necessário — aumente o timeout:
Text
CONFIG_RBAMP_I2C_TIMEOUT_MS=200
  1. Ative o nível DEBUG para a etiqueta rbamp para diagnóstico:
Text
CONFIG_RBAMP_LOG_LEVEL_DEBUG=y

Também pode fazê-lo em tempo de execução — esp_log_level_set("rbamp", ESP_LOG_DEBUG).

Nota

Sobre os contadores de retentativa/sanidade. O componente exporta os getters públicos rbamp_retry_exhaustion_count(dev) e rbamp_sanity_reject_count(dev) — são equivalentes multiplataforma de dev.retryExhaustionCount() / dev.sanityRejectCount() da biblioteca Arduino. O padrão canónico de instantâneo + diferença para monitorização em produção está descrito na secção "Monitorizar os contadores" abaixo.

Frota: um módulo acabou em excluded após rbamp_fleet_scan

O que vê: rbamp_fleet_scan(fleet, ...) correu e devolveu ESP_OK, mas rbamp_fleet_count(fleet) é inferior ao número de módulos que ligou fisicamente. rbamp_fleet_excluded_count(fleet)

Nota

0; percorra rbamp_fleet_excluded_addr(fleet, i) — cada endereço excluído significa "foi detetado um módulo mas NÃO foi acrescentado à frota — suspeita-se de conflito".

Causa. O detetor de conflitos trabalha com dois sinais independentes:

  • consistência de identidade: HW_VARIANT ↔ mapa de bits de CAPABILITY são inconsistentes — sinal de que dois módulos físicos diferentes estão a responder num só endereço (a resposta "funde-se" parcialmente).
  • valor ao vivo: no mesmo endereço observam-se leituras "ao vivo" incompatíveis — por exemplo, um LABEL diferente ou uma variante a oscilar.

Se pelo menos um dos sinais disparar, o endereço é excluído da frota, e a biblioteca NÃO se baseia nas leituras desse módulo. Se ambos os sinais estiverem calmos mas os módulos estiverem configurados de forma idêntica (mesma variante, mesmo CT_MODEL, mesmo LABEL), o detetor não os consegue distinguir — este é um caso fisicamente indetetável (ver abaixo sobre disciplina).

Segurança

⚠ A deteção é de melhor esforço. É impossível garantir que a frota apanha dois módulos idênticos no mesmo endereço — e é exatamente por isso que existe a disciplina de provisionamento (ver a secção seguinte).

O que fazer.

  1. Desligue fisicamente todos os módulos exceto um.
  2. Ligue os restantes um de cada vez, chamando rbamp_fleet_scan de novo após cada um. O módulo após cuja ligação aparece um excluded está em conflito com um já ligado.

  3. Reprovisione o módulo em conflito para um endereço livre através de rbamp_provision(bus, new_address, ...) (exige que seja o único em 0x50 — ver a disciplina de provisionamento abaixo).

  4. Após o reendereçamento, repita rbamp_fleet_scan — excluded_count deve ser 0.

Frota: rbamp_fleet_scan devolveu ESP_ERR_INVALID_STATE + frota vazia

O que vê: rbamp_fleet_scan devolveu ESP_ERR_INVALID_STATE, e rbamp_fleet_count(fleet) é 0. Nenhum módulo foi acrescentado à frota, mesmo estando fisicamente ligados.

Causa. Vigia de canário de tier 2 — a biblioteca fez uma verificação do barramento de "há resposta num endereço que não deve responder" (o canário). Se o canário recebeu um ACK, o barramento não está num estado normal: ou há ruído elétrico a produzir ACKs espúrios, ou todos os endereços estão "presos" em consequência de um bloqueio, ou há um erro de topologia (vários módulos com o mesmo código ao mesmo tempo, com SDA/SCL retidos a zero). Nesse estado não se pode confiar em nenhum resultado de varrimento — por isso a frota fica vazia; é melhor abortar do que fazer uma inicialização sabidamente incorreta.

O que fazer.

  1. Desligue e volte a ligar todo o barramento (corte a alimentação dos módulos durante alguns segundos e reinicie o ESP32). Isto limpa os estados bloqueados.

  2. Ligue os módulos estritamente um de cada vez, executando rbamp_fleet_scan (arranque de um só módulo) após cada um e verificando o retorno:

  3. ESP_OK + count=1 + excluded=0 → o barramento está limpo, módulo OK.

  4. ESP_ERR_INVALID_STATE persiste → verifique os pull-ups (ver a secção i2c-hang acima — é obrigatória uma resistência externa de 4.7 kΩ em SDA/SCL).

  5. Quando o arranque de cada módulo individual passar, junte-os todos ao barramento de uma vez e volte a correr rbamp_fleet_scan. Se voltar a obter INVALID_STATE, o problema está na eletrónica do barramento (comprimento, interferência, um pull-up em falta), e não nos módulos individuais.

Frota: rbamp_provision devolveu um erro

O que vê: a chamada rbamp_provision(bus, desired_address, save_config, &out) não terminou com ESP_OK. Conforme o código devolvido:

esp_err_t O que aconteceu O que fazer
ESP_ERR_NOT_FOUND Ninguém respondeu em 0x50 (predefinição de fábrica) Confirme que o módulo virgem está fisicamente ligado e alimentado (VCC); verifique a cablagem I²C (ver "O módulo não responde por I²C").
ESP_ERR_INVALID_STATE Foi detetado um conflito em 0x50 ou o endereço pretendido já está ocupado Há mais de um módulo virgem no barramento ou o endereço pretendido já está ocupado por outro módulo. Desligue todos os módulos "extra" (ver abaixo).
ESP_ERR_TIMEOUT O comando de commit de endereço foi executado, mas o módulo não apareceu no novo endereço dentro da janela de arranque Desligue e volte a ligar o módulo e tente de novo. Se voltar a acontecer — provavelmente uma operação de flash incompleta (a energia caiu durante CMD_SAVE_USER_CONFIG ou CMD_COMMIT_ADDR, por isso o bloco de flash pode estar parcialmente escrito). No arranque seguinte o módulo devolve REG_ERROR = 0xFB (ERR_FLASH_PARAMS_BAD), carrega as predefinições de fábrica e reaparece em 0x50. Volte a provisionar do zero; se também falhar, envie-o para assistência.
ESP_ERR_INVALID_ARG desired_addr está fora do intervalo válido 0x08..0x77 Use um endereço válido.
Segurança

⚠ Disciplina de provisionamento — DEVE ser um virgem de cada vez.

A causa mais comum de INVALID_STATE durante o provisionamento é haver mais de um módulo no barramento com o endereço de fábrica 0x50. Distingui-los por I²C é fisicamente impossível (drenos abertos em AND-cabladas — ambos os módulos dão ACK de forma idêntica, e a releitura dos dados vem "fundida").

Por isso a regra é estrita (um MUST normativo, não uma recomendação): no momento da chamada a rbamp_provision tem de haver exatamente um módulo em 0x50 (novo, ou reposto para as predefinições de fábrica através de uma ferramenta de bancada separada). Nada de "tenho a certeza de que estes dois módulos são diferentes — vou separá-los agora" — não funciona; a colisão aparecerá mais tarde, quando já achar que a frota está limpa.

Caminho de recuperação em caso de suspeita de violação da disciplina: 1. Desligue e volte a ligar todos os módulos. 2. Desligue fisicamente todos menos o módulo "virgem" (aquele que quer reendereçar). 3. Chame rbamp_provision no barramento com um único módulo. 4. Acrescente os restantes módulos um de cada vez, provisionando cada um separadamente.

A corrente lê zero numa carga em funcionamento

O que vê: rbamp_read_current(dev, 0, &i) devolve ESP_OK mas i = 0.000 (ou um valor muito pequeno), mesmo havendo um consumidor real ligado (chaleira, candeeiro, ferro). rbamp_read_power_factor(dev, 0, &pf) 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 CT estão configurados:
C
esp_err_t err = rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013);
if (err != ESP_OK) {
    ESP_LOGE(TAG, "set_sensor_class: %s", rbamp_err_to_str(err));
}
err = rbamp_set_ct_model(dev, 3);   /* or your model */
if (err != ESP_OK) {
    ESP_LOGE(TAG, "set_ct_model: %s", rbamp_err_to_str(err));
}

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.

Nota

Armadilha sobre RBAMP_SENSOR_UNSET. Se chamar por engano rbamp_set_sensor_class(dev, RBAMP_SENSOR_UNSET) — a função devolve ESP_OK, mas repõe efetivamente a configuração de classe. Um rbamp_set_ct_model*() posterior passará a devolver ESP_ERR_INVALID_STATE. A correção é chamar de novo rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013) e depois rbamp_set_ct_model() outra vez.

  1. Verifique se o modelo de TC corresponde à carga. Uma pinça TC grande (por exemplo, SCT-013-100, 100 A) numa carga pequena (uma lâmpada de 50 W = ~0.2 A) produz um sinal no limite do ruído de fundo, e as leituras serão zero. Escolha o modelo de TC mais pequeno que cubra a sua corrente máxima prevista. 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, considere um padrão de CT duplo: 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 escolhe o valor por um limiar. O padrão é discutido em 03 · Seleção do sensor de corrente, secção "Topologia de CT duplo".

  1. Verifique a orientação da pinça. A seta no corpo da pinça tem de apontar no sentido do fluxo da corrente em direção à carga. Se a pinça estiver "ao contrário", rbamp_read_current() dá o valor correto em termos absolutos, mas rbamp_read_power() dá um valor negativo numa carga de consumo. Confirmação: rbamp_read_power_factor() mostrará exatamente −1.0 numa carga resistiva (em vez de +1.0). A correção: ou volte a montar fisicamente a pinça (desencaixe, rode-a para a seta ficar no sentido certo, encaixe de novo), ou inverta o sinal do lado do master.

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

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

  • Está a circular corrente — meça com um multímetro (pinça DC / pinça amperimétrica AC) no mesmo fio.

  • A pinça está intacta — na ligação da pinça deve haver uma tensão AC proporcional à corrente (alguns milivolts para cargas domésticas).

  • Está a prender o fio certo — o condutor de fase (linha), e só esse condutor (nunca o cabo inteiro).

As leituras saltam ou devolvem ESP_FAIL

O que vê: rbamp_read_voltage(dev, ...) ou rbamp_read_current(dev, ...) devolvem periodicamente ESP_FAIL. O valor em *out é indefinido após um erro.

ESP_FAIL do componente 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 float NaN / Inf / |x| > 10000 chegou do barramento (um valor claramente não físico).

A API do ESP-IDF não distingue estes casos por códigos esp_err_t separados (ao contrário dos RB_ERR_NACK / RB_ERR_NON_PHYSICAL do Arduino) — ambos devolvem ESP_FAIL. Pode distingui-los pelos contadores de diagnóstico (ver a secção "Monitorizar os contadores" abaixo). Ambos os sintomas são tratados da mesma forma:

  1. Confirme o padrão de 50 kHz + aumente a retentativa para 5 através do Kconfig — veja a secção anterior.

  2. Reduza a densidade de carga no barramento — se o seu ciclo fizer muitas leituras de um byte, experimente rbamp_read_all() (uma transação I²C em vez de ~13).

  3. Verifique CONFIG_RBAMP_I2C_TIMEOUT_MS — se o dispositivo responder mais lentamente do que o habitual (cabo longo, mau contacto), aumente o timeout.

  4. Ative o registo DEBUG através de CONFIG_RBAMP_LOG_LEVEL_DEBUG=y ou esp_log_level_set("rbamp", ESP_LOG_DEBUG) — o componente imprimirá os detalhes do ciclo de retentativas e das rejeições de sanidade com a etiqueta "rbamp".

Monitorizar os contadores

O componente expõe dois contadores monótonos públicos para a monitorização da saúde do barramento em produção:

C
uint32_t rbamp_retry_exhaustion_count(rbamp_handle_t dev);
uint32_t rbamp_sanity_reject_count(rbamp_handle_t dev);

retry_exhaustion_count incrementa quando uma transação de um byte esgotou o orçamento CONFIG_RBAMP_NACK_RETRY_ATTEMPTS e devolveu ESP_FAIL. sanity_reject_count incrementa quando o filtro de sanidade descarta um float (!isfinite(x) || |x| > 10000).

O padrão canónico é instantâneo + diferença uma vez a cada 60 segundos, para obter uma "taxa de eventos por minuto":

C
uint32_t prev_retry  = rbamp_retry_exhaustion_count(dev);
uint32_t prev_sanity = rbamp_sanity_reject_count(dev);
/* ...60 s of normal operation (do N rbamp_read_* calls)... */
uint32_t now_retry  = rbamp_retry_exhaustion_count(dev);
uint32_t now_sanity = rbamp_sanity_reject_count(dev);
uint32_t retry_delta  = now_retry  - prev_retry;
uint32_t sanity_delta = now_sanity - prev_sanity;
if (retry_delta > THRESHOLD || sanity_delta > THRESHOLD) {
    ESP_LOGW(TAG, "bus health: retry+%u sanity+%u per minute",
             retry_delta, sanity_delta);
}

Os limiares de alarme dependem da carga de trabalho. Para um padrão de teste de resistência denso (como o SoakMonitor do Arduino — ~70 bytes por ciclo, uma vez a cada 5 minutos):

  • retry_delta > 1/hora — ruído benigno, pode ser ignorado.
  • retry_delta consistentemente > 5/hora — vale a pena investigar (maus contactos, capacitância do barramento, deriva térmica das pull-ups).

  • sanity_delta > 0 em regime estacionário — quase sempre sinal de interferência eletromagnética no barramento ou de uma regressão do firmware.

Os contadores só aumentam (nunca são repostos) — para os repor é preciso recriar o handle via rbamp_del(dev) + rbamp_new(...). Isto é intencional, para não perder o histórico em corridas entre "reposição" e "leitura para o registador".

Nota

Multiplataforma, estes contadores têm a mesma semântica dos dev.retryExhaustionCount() / dev.sanityRejectCount() da biblioteca Arduino — os mesmos nomes (snake_case vs camelCase), os mesmos limiares funcionam da mesma forma.

O fator de potência parece errado

O que vê: rbamp_read_power_factor(dev, 0, &pf) devolve ESP_OK, mas pf 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 do 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

PF é definido como P / (U × I). Com corrente zero, I=0 a conta é indefinida. O valor devolvido depende do firmware (pode ser 0 ou um valor de substituição perto de zero) — isto é normal enquanto a corrente for realmente zero. Quando aparecer corrente, aparece um PF válido. O filtro de sanidade do componente não rejeita este valor (por isso o equivalente de sanityRejectCount no IDF não incrementa) — é uma medida válida de uma grandeza indefinida, não um artefacto de ligação.

PF estritamente −1.0 numa carga puramente de consumo

A pinça está montada "ao contrário" — a seta aponta contra o sentido da corrente, em direção à carga. Correção: ou volte a montar a pinça corretamente, ou trate o sinal do lado do master (p = -p; pf = -pf; se souber que a carga não pode ser um inversor fotovoltaico).

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

  • Causa possível: a pinça de CT está num fio de uma fase diferente daquela à qual a entrada U do módulo está ligada. Num quadro de distribuição com várias fases é fácil prender a 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 a que a entrada U e o CT estejam na mesma fase.

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

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

O que vê: rbamp_read_period_snapshot(dev, ...) devolve ESP_ERR_INVALID_RESPONSE, ou *out.valid == false. Isto significa que o módulo não terminou a integração do período anterior quando chegou a leitura seguinte.

O componente protege contra a dupla contagem de Wh: numa leitura desatualizada, regista um carimbo temporal mestre (esp_timer_get_time()), 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 de 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 (rbamp_probe(dev) == ESP_OK) {
    ESP_LOGI(TAG, "alive");
}
  1. Verifique o flag diretamente — rbamp_is_period_valid() faz uma leitura de um byte sem efeitos secundários:
C
bool valid;
if (rbamp_is_period_valid(dev, &valid) == ESP_OK && valid) {
    /* avg_p[] can be read */
}
  1. Verifique a versão do firmware — rbamp_firmware_version(dev) >= 0x02 mostra menos leituras desatualizadas do que 0x01. O firmware canónico atual é 0x04 (v1.3); 0x01=v1.0, 0x02=v1.1, 0x03=v1.2.

Caso especial — despertar de deep-sleep

Se usar um padrão de deep-sleep, o padrão rbamp_read_period_snapshot() logo após rbamp_begin() estará sempre desatualizado (ou dará valores próximos de zero) — begin() faz um instantâneo aproximado que repõe o acumulador do firmware. O padrão canónico usa skip_latch=true + o carimbo temporal guardado em RTC pelo próprio mestre — ver 06 · Exemplos, Cenário 9.

A contabilização de Wh desvia-se de uma referência

O que vê: rbamp_energy_wh(dev, 0) após várias horas / dias de funcionamento diverge da leitura do contador da concessionária ou de um contador de referência (Kill-A-Watt, etc.).

Primeiro descarte o trivial

  1. Calibração do sensor de corrente: confirme que rbamp_set_sensor_class() e rbamp_set_ct_model() foram chamadas com o modelo de CT correto (ver 03 · Seleção do sensor de corrente). Sem isto, a corrente RMS é calculada com um patamar predefinido e o valor da potência fica sistematicamente enviesado.

  2. Instantâneos desatualizados descartados: se rbamp_energy_wh() estiver consistentemente abaixo da referência, podem ser intervalos perdidos — o instantâneo chegou desatualizado, o componente protegeu contra dupla contagem, mas a medição do intervalo perdeu-se. Verifique a cadência (ver acima).

  3. Deriva do relógio do master: esp_timer_get_time() é fiável por si. Mas se o master entrar em deep sleep sem guardar a RTC, o intervalo entre o instantâneo anterior e o seguinte perde-se. Use o padrão RTC_DATA_ATTR do Cenário 9 para cenários de deep-sleep.

Precisão do acumulador

O acumulador de Wh dentro do handle é guardado como double de 64 bits.

Se compilou o componente com CONFIG_RBAMP_DISABLE_ENERGY=y, o armazenamento de energia e a API são removidos por completo do binário. Nesse caso tem de manter o seu próprio contador de Wh no código do utilizador.

snap.latch_ms — diagnóstico, não para energia

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

O projeto ESP32 bloqueia ao fim de alguns minutos

O que vê: um projeto ESP32 arranca normalmente e depois entra num bloqueio / ciclo de reinícios / timeout de WDT ao fim de 1–30 minutos.

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

O que vê concretamente: um projeto ESP32 (clássico v1.0, IDF v5.4.1, novo driver i2c_master) consulta o rbAmp sem problemas durante vários minutos e depois "morre", ficando parado a meio de uma chamada rbamp_*_read_* ou de rbamp_fleet_poll_all. O task-WDT (se estiver ativo) apanha o bloqueio; caso contrário, o projeto simplesmente deixa de responder. O backtrace descodificado termina em i2c_ll_is_bus_busy (ficheiro i2c_master.c:526, espera de barramento ocupado antes do envio).

O que está a acontecer: num barramento marginal (pull-ups fracos, pistas longas, EMI, interferência das transições de passagem por zero) SDA/SCL podem "prender-se" momentaneamente num estado indeterminado. Antes de cada transação, o i2c_master do IDF fica a rodar no ciclo de espera i2c_ll_is_bus_busy à espera que o barramento se liberte — esta espera NÃO é limitada pelo parâmetro xfer_timeout_ms. Se o barramento ocupado durar mais do que a espera consegue correr sem servir outras tarefas, a tarefa IDLE do FreeRTOS não recebe CPU e a aplicação inteira bloqueia.

Isto não é um "artefacto só de depurador". Validado em bancada: no mesmo equipamento 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 (execuções de 5 e 25 minutos, 0 reinícios)

A correlação é clara — uma correção da integridade do barramento elimina o bloqueio por completo. A lógica da biblioteca não tem culpa: a mecânica por módulo (fleet_poll_all, MISS/dessincronização, verificações de fugas) manteve-se limpa em todas as execuções até ao bloqueio.

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 pull-ups de 4.7 kΩ integrados nos módulos, em paralelo, ficam fortes demais. Num barramento assim, corte os integrados em todos os módulos menos um (ou em todos — e então confie apenas nos externos). Ver 04 · Cablagem, secção "Barramento multi-módulo — topologia principal".

  2. Não corra um build de produção com o NRST do depurador ligado. Numa sessão de depuração a linha de reposição pode manter SDA/SCL num estado indeterminado ao desligar/ligar, provocando um bloqueio do barramento na transação seguinte. Num build de campo (sem depurador) este fator desaparece.

  3. WDT de tarefa ao nível da aplicação na tarefa de sondagem — defesa em profundidade. Se, por alguma razão, os pull-ups continuarem marginais, ou surgir outra causa de bloqueio, o WDT reinicia o projeto e, se houver um supervisor presente (por exemplo, um bootloader de rolamento da aplicação ou um supervisor tipo systemd), volta a arrancar. Numa prova de resistência de bancada de mais de uma hora, o WDT apanhou e recuperou os 12 bloqueios na configuração sem pull-up externo.

C
#include "esp_task_wdt.h"

void app_main(void) {
    /* Layer 3 setup — defense-in-depth. */
    esp_task_wdt_config_t wdt_cfg = {
        .timeout_ms = 10000,           /* 10 s with plenty of margin */
        .idle_core_mask = 0,
        .trigger_panic = true,         /* on timeout — panic+reboot */
    };
    ESP_ERROR_CHECK(esp_task_wdt_reconfigure(&wdt_cfg));
    ESP_ERROR_CHECK(esp_task_wdt_add(NULL));   /* this task is under the WDT */

    /* ... bus / fleet init ... */

    while (1) {
        rbamp_fleet_poll_all(fleet, snaps, status, RBAMP_FLEET_MAX_MODULES, &n_ok);
        /* ... processing ... */
        esp_task_wdt_reset();            /* "I'm alive" — every cycle */
        vTaskDelay(pdMS_TO_TICKS(200));
    }
}

O que NÃO fazer: não tente contornar o problema com um xfer_timeout_ms maior — não limita a espera de barramento ocupado, que é um caminho de código diferente no driver. A correção é a integridade do barramento (camada 1) + o supervisor (camada 3).

Timeout do watchdog ao ligar ao WiFi

Causa: um ciclo de espera de ligação WiFi sem limite dentro de um manipulador de evento aciona o task-WDT após ~5 s (predefinido).

Correção: use um padrão orientado a eventos em vez de espera ativa. O driver WiFi do ESP-IDF emite os eventos WIFI_EVENT_STA_DISCONNECTED e IP_EVENT_STA_GOT_IP — reaja a eles via esp_event_handler_register() em vez de sondar num ciclo.

Padrão mínimo:

C
static EventGroupHandle_t wifi_event_group;
#define WIFI_CONNECTED_BIT BIT0
#define WIFI_FAIL_BIT      BIT1

static void wifi_event_handler(void *arg, esp_event_base_t event_base,
                                int32_t event_id, void *event_data) {
    if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_DISCONNECTED) {
        esp_wifi_connect();   /* auto-reconnect */
    } else if (event_base == IP_EVENT && event_id == IP_EVENT_STA_GOT_IP) {
        xEventGroupSetBits(wifi_event_group, WIFI_CONNECTED_BIT);
    }
}

/* In app_main, wait for the event with a timeout: */
EventBits_t bits = xEventGroupWaitBits(
    wifi_event_group, WIFI_CONNECTED_BIT | WIFI_FAIL_BIT,
    pdFALSE, pdFALSE, pdMS_TO_TICKS(30000));
if (!(bits & WIFI_CONNECTED_BIT)) {
    esp_restart();
}

O broker MQTT desliga-se a cada ~15 s

Causa: na maioria dos casos não é o keepalive. O session.keepalive por omissão em esp_mqtt_client_config_t é 120 s, e disable_keepalive tem por omissão false (ou seja, o keepalive está ativo). Reescrever explicitamente estes campos com os mesmos valores não muda nada — se a ligação cair a cada 15 s, a causa real está na rede (um NAT/firewall intermédio a deixar cair TCP inativo) ou numa queda de WiFi.

Correção: registe MQTT_EVENT_DISCONNECTED e volte a ligar explicitamente. esp_mqtt_client_start() lança a sua própria tarefa internamente; não precisa de acionar um mqtt.loop() separado — basta voltar a ligar no evento.

C
static void mqtt_event_handler(void *arg, esp_event_base_t base,
                               int32_t event_id, void *event_data) {
    if (event_id == MQTT_EVENT_DISCONNECTED) {
        ESP_LOGW("mqtt", "disconnected — reconnecting on timeout");
        /* esp-mqtt reconnects automatically with backoff;
         * this handler is the place to clean up application state
         * (retained flags, discovery payload caches). */
    }
}

const esp_mqtt_client_config_t cfg = {
    .broker.address.uri = "mqtt://192.168.1.10:1883",
    /* leave keepalive at the default — 120 s;
     * for aggressive NATs, lower it to 30 s: */
    /* .session.keepalive = 30, */
};
esp_mqtt_client_handle_t client = esp_mqtt_client_init(&cfg);
esp_mqtt_client_register_event(client, ESP_EVENT_ANY_ID,
                                mqtt_event_handler, NULL);
esp_mqtt_client_start(client);

Se as desconexões coincidirem no tempo com quedas de WiFi, a causa real está no WiFi (RSSI, um canal congestionado), e não no MQTT. Verifique o payload de MQTT_EVENT_ERROR e os registos de WiFi antes de mexer no keepalive.

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

Causa: o heap do ESP32 é insuficiente para o handshake TLS (~30 kB necessários). Muitas vezes combinado com WiFi + MQTT + buffers, deixando < 20 kB.

Fix:

  • Use WiFi.mode(WIFI_MODE_STA) (não STA+AP).
  • Desative o BLE se não precisar dele: CONFIG_BT_ENABLED=n no sdkconfig.

  • Reduza os tamanhos dos buffers MQTT em esp_mqtt_client_config_t.

  • Passar para o ESP32-S2 (sem Bluetooth — mais ~30 kB de heap disponíveis).

Se esp_get_free_heap_size() mostrar < 25 kB antes de esp_mqtt_client_start() ou esp_http_client_perform(), o handshake TLS muito provavelmente falha.

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

Cânone v1.3 (confirmado em HW): REG_ERROR (0x02) é resultado da última escrita, NÃO pegajoso. Em cada escrita de registo o firmware define reg_error = ERR_OK; uma escrita não relacionada seguinte 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 após uma operação (se o resultado DESTA operação específica importar):

C
esp_err_t err = rbamp_save_user_config(dev);
uint8_t dev_err;
rbamp_read_last_error(dev, &dev_err);   /* IMMEDIATELY, before the next write */

Padrão 2 — monitorização de erros duradoura (canónico para execuções prolongadas):

C
uint8_t event_flags;
rbamp_read_event_flags(dev, &event_flags);
if (event_flags & RBAMP_EVENT_ERROR) {
    uint8_t last_err;
    rbamp_read_last_error(dev, &last_err);   /* what was the last rejected */
    /* handle the error */
    rbamp_clear_error(dev);                  /* clears REG_ERROR ... */
    rbamp_clear_event_flags(dev, RBAMP_EVENT_ERROR);  /* ... then the sticky bit */
}
Segurança

⚠ INVERSÃO da documentação anterior "pegajosa" (canónico v1.3 A3). REG_ERROR é o resultado da última escrita, não é pegajoso. A durabilidade é assegurada pelo EVENT bit3.

⚠ o bit3 é um canal assíncrono, não serve para validar escritas de forma síncrona: numa escrita rejeitada, o bit3 é ativado com atraso em relação ao momento em que a transação I²C devolve o controlo. 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 (uma captura pontual de REG_ERROR imediatamente após a operação) ou o código de retorno do setter. O bit3 destina-se à monitorização prolongada de factos assíncronos (tempo de execução, caminho de comandos), não à validação de uma operação que acabou de executar.

Ressalva: DEV_ERR_CLONE (0xF9) NÃO é limpo por CMD_CLEAR_ERROR — é uma sentinela anticlone (só reinício ou reposição de fábrica).

Módulo com flash nova 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 inicializada → carregados os valores de fábrica. Isto é NORMAL num módulo virgem, não é fatal.

Solução: configure sensor_class + ct_model + (opcionalmente) address e, em seguida, CMD_SAVE_USER_CONFIG. Após um SAVE bem-sucedido → REG_ERROR = 0x00, bit3 limpo.

rbamp_set_sensor_class / rbamp_set_ct_model* devolve ESP_ERR_INVALID_STATE

O que vê: uma das chamadas de configuração devolve ESP_ERR_INVALID_STATE.

ESP_ERR_INVALID_STATE neste grupo de funções é um código-guarda para três causas distintas. Pode distingui-las pela linha ESP_LOGW que o componente imprime com a etiqueta "rbamp" imediatamente antes de devolver:

Linha de registo (ESP_LOGW, TAG="rbamp") Causa Solução
set_ct_model_ch refused: sensor class is UNSET (call rbamp_set_sensor_class first) Pré-condição: a classe do sensor tem de estar definida antes de escrever o modelo de CT Chame rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013) antes de rbamp_set_ct_model*().
set_ct_model_ch refused: bind sequence error (call rbamp_set_sensor_class first to reset batch) O registo interno de lotes do componente está dessincronizado com o estado de preparação do firmware No firmware v1.3 a ordem de associação dos canais é arbitrária (Fix-A pure staging — ver 03 · Seleção do sensor de corrente). Chame de novo rbamp_set_sensor_class() para repor o registo do lote, depois associe os canais em qualquer ordem. A formulação "ordem descendente obrigatória" de mensagens de registo mais antigas refere-se ao comportamento anterior à v1.3 e já não está em vigor.

Há também o caso de um handle inicializado mas em que rbamp_begin() ainda não foi chamado — isto devolve ESP_ERR_INVALID_STATE sem linha ESP_LOGW (o handle continua "frio"). Solução: chame rbamp_begin(dev) após rbamp_new() e antes de qualquer rbamp_set_*.

Nota

O padrão de desambiguação pelo registo é uma construção padrão do ESP-IDF: compare-o com o esp_driver_i2c, que devolve ESP_ERR_TIMEOUT tanto para um timeout de ACK como para um timeout de barramento ocupado, distinguindo-os pelo registo. Se vir ESP_ERR_INVALID_STATE sem causa clara, aumente o nível de registo através de esp_log_level_set("rbamp", ESP_LOG_WARN) (ou _DEBUG) e repita a chamada: o componente indicará qual dos três casos é. rbamp_err_to_str(ESP_ERR_INVALID_STATE) devolve uma descrição genérica: "Sequência de chamadas errada (verifique o registo: modo de fábrica / classe de sensor UNSET / lote de associação dessincronizado)".

rbamp_set_sensor_class / rbamp_set_ct_model* devolve ESP_ERR_INVALID_ARG

O que vê: a chamada devolve ESP_ERR_INVALID_ARG.

Possíveis causas:

  1. Código de modelo inválido para a classe — os códigos válidos dependem da classe de sensor: SCT013 aceita {1, 2, 3, 4, 5, 6, 7} (ver a tabela em 03 · Seleção do sensor de corrente); WIRED_CT aceita 1–10 e 12. Um código desconhecido para a classe devolve ESP_ERR_INVALID_ARG.

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

  3. Um valor inválido de rbamp_sensor_class_t — uma classe acima de 3 devolve ESP_ERR_INVALID_ARG. Os módulos fornecidos calibrados em conjunto com o seu próprio sensor (RBAMP_SENSOR_WIRED_CT, RBAMP_SENSOR_BUILTIN_CT) recusam uma alteração de classe ou de modelo (ESP_ERR_INVALID_STATE); para a pinça de encaixe SCT-013 use RBAMP_SENSOR_SCT013.

  4. dev == NULL ou out == NULL — confirme que rbamp_new() teve êxito (devolveu ESP_OK).

rbamp_commit_address_change devolve ESP_ERR_TIMEOUT

Se prepare passar mas commit devolver ESP_ERR_TIMEOUT, a janela de "armação" expirou (5 segundos após prepare). rbamp_probe() não ajuda aqui (o módulo responde; o problema está na máquina de estados). A correção: chame de novo rbamp_prepare_address_change() e de imediato — na mesma iteração de app_main, sem chamadas de rede entre elas — chame rbamp_commit_address_change(). WiFi / MQTT / qualquer E/S bloqueante entre prepare e commit é a principal causa de a janela expirar.

Para mais sobre os métodos públicos com aviso, veja 09 · Referência da API, secção "Configuração do sensor".

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

O que vê: rbamp_read_* devolve periodicamente ESP_FAIL / ESP_ERR_INVALID_RESPONSE, mas apenas enquanto uma carga com relé/indutiva está a comutar ativamente na mesma montagem. Em regime estacionário as leituras são fiáveis.

Causa (C.12 confirmada em HW): 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 de hardware). O barramento recupera sozinho, não há bloqueio, nenhum módulo se perde — mas a leitura de corrente falha.

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

C
esp_err_t robust_read_voltage(rbamp_handle_t dev, float *v) {
    for (int attempt = 0; attempt < 5; attempt++) {
        esp_err_t err = rbamp_read_voltage(dev, 0, v);
        if (err == ESP_OK) return ESP_OK;
        vTaskDelay(pdMS_TO_TICKS(20));   // short pause before retry
    }
    return ESP_FAIL;
}
Segurança

⚠ Um bus_reset do lado do mestre não basta por si: quando uma falha de EMI se sobrepõe à janela de retentativa do driver, é preciso uma retentativa explícita ao nível da aplicação, com uma pausa.

Alternativa: se o master vir eventos de comutação de relé — atrase as leituras cerca de 50-100 ms após a comutação.

Reinício por task-WDT sob EMI / carga elevada

O que vê: o ESP32 reinicia inesperadamente com o motivo TASK_WDT. Acontece sobretudo durante eventos de EMI (comutação de relés, transitórios indutivos).

Causa: sob leituras lentas por EMI (ciclos de repetição de NACK + reposição do barramento) o driver i2c_master do ESP-IDF pode prolongar uma transação até ~100 ms ou mais. Se uma tarefa executar um ciclo apertado de leitura em rajada sem ceder, dá timeout do task-WDT.

Solução — ceder na leitura em rajada:

C
// WRONG — no yield, under EMI → WDT reboot
for (int i = 0; i < N_METERS; i++) {
    rbamp_read_period_snapshot(meters[i], &snaps[i], 0, true);
}

// CORRECT — yield every N reads (or every iteration)
for (int i = 0; i < N_METERS; i++) {
    rbamp_read_period_snapshot(meters[i], &snaps[i], 0, true);
    vTaskDelay(1);   // yield + WDT feed
}

Alternativa: esp_task_wdt_reset() explicitamente, se a tarefa for monitorizada pelo WDT.

Tabela-resumo dos códigos de erro

As funções rbamp_* devolvem valores esp_err_t padrão. rbamp_err_to_str(err) devolve uma string legível.

Código Quando Onde procurar
ESP_OK (0) sucesso —
ESP_FAIL (-1) NACK após repetição; ou o filtro de sanidade rejeitou o valor secção "O módulo não responde por I²C"
ESP_ERR_INVALID_ARG (0x102) dev == NULL, channel/phase fora do intervalo, um cls não reconhecido, um valor que o módulo rejeita verifique os argumentos da chamada
ESP_ERR_TIMEOUT (0x107) rbamp_wait_ready expirou (módulo sem resposta) OU expirou a janela de 5 s entre prepare_address_change e commit_address_change para wait_ready — através de rbamp_probe(); para commit — rearmar: prepare + commit seguidos, sem E/S bloqueante entre eles
ESP_ERR_INVALID_STATE (0x103) pré-condição: set_ct_model* antes de set_sensor_class a secção set_* acima
ESP_ERR_NOT_SUPPORTED (0x106) a função não está disponível no SKU atual (p. ex., a API de tensão numa variante I*) verifique rbamp_line(dev) e rbamp_variant(dev)
ESP_ERR_INVALID_RESPONSE (0x108) instantâneo de período desatualizado; ou REG_VERSION = 0/0xFF em rbamp_begin Secção "Os instantâneos de período estão sempre desatualizados" / "O módulo não responde"
ESP_ERR_NO_MEM (0x101) falha ao alocar memória para o handle verifique o orçamento de heap (esp_get_free_heap_size())

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

Para depuração profunda, quando o componente já não consegue dizer o que se passa no fio, capture SDA + SCL com um analisador lógico (Saleae, DSLogic Plus, 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 código (rbamp_read_voltage(), 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 incremento automático de endereço) são suportadas.

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

Quando contactar o suporte

Se já seguiu a secção relevante acima e o problema persistir, abra um issue:

github.com/rb-amp/rbamp-esp-idf/issues

No problema, inclua:

  • SoC alvo (ESP32 / S2 / S3 / C2 / C3 / C6 / H2) + versão do ESP-IDF (saída de idf.py --version).

  • Versão do componente rbamp (por exemplo, 1.1.0).

  • Versão de firmware do módulo — rbamp_firmware_version(dev) nos registos.

  • Um projeto IDF mínimo que reproduz o problema (~30 LOC em main/main.c).

  • Os valores esp_err_t + rbamp_err_to_str(err) no momento da falha, a partir dos registos sob a etiqueta rbamp.

  • Kconfig relevante: CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ, CONFIG_RBAMP_NACK_RETRY_ATTEMPTS, CONFIG_RBAMP_LOG_LEVEL_*.

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


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