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:
-
Ao nível do barramento — o módulo não responde por I²C; as leituras devolvem
ESP_FAILouESP_ERR_INVALID_RESPONSE. -
Nível de dados — o módulo responde, mas os números estão errados: zeros, valores estranhos, sinal errado.
-
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.
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:
#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 = truena suai2c_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:
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:
- Confirme o padrão de 50 kHz:
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000
- Aumente o número de repetições para carga pesada:
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=5
- Se for necessário — aumente o timeout:
CONFIG_RBAMP_I2C_TIMEOUT_MS=200
- Ative o nível DEBUG para a etiqueta
rbamppara diagnóstico:
CONFIG_RBAMP_LOG_LEVEL_DEBUG=y
Também pode fazê-lo em tempo de execução — esp_log_level_set("rbamp", ESP_LOG_DEBUG).
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)
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
LABELdiferente 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).
⚠ 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.
- Desligue fisicamente todos os módulos exceto um.
-
Ligue os restantes um de cada vez, chamando
rbamp_fleet_scande novo após cada um. O módulo após cuja ligação aparece umexcludedestá em conflito com um já ligado. -
Reprovisione o módulo em conflito para um endereço livre através de
rbamp_provision(bus, new_address, ...)(exige que seja o único em0x50— ver a disciplina de provisionamento abaixo). -
Após o reendereçamento, repita
rbamp_fleet_scan—excluded_countdeve ser0.
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.
-
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.
-
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: -
ESP_OK+count=1+excluded=0→ o barramento está limpo, módulo OK. -
ESP_ERR_INVALID_STATEpersiste → verifique os pull-ups (ver a secção i2c-hang acima — é obrigatória uma resistência externa de 4.7 kΩ em SDA/SCL). -
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 obterINVALID_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. |
⚠ 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
- Verifique se a classe do sensor e o modelo de CT estão configurados:
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.
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.
- 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".
- 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, masrbamp_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| > 10000chegou 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:
-
Confirme o padrão de 50 kHz + aumente a retentativa para 5 através do Kconfig — veja a secção anterior.
-
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). -
Verifique
CONFIG_RBAMP_I2C_TIMEOUT_MS— se o dispositivo responder mais lentamente do que o habitual (cabo longo, mau contacto), aumente o timeout. -
Ative o registo DEBUG através de
CONFIG_RBAMP_LOG_LEVEL_DEBUG=youesp_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:
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":
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_deltaconsistentemente > 5/hora — vale a pena investigar (maus contactos, capacitância do barramento, deriva térmica das pull-ups). -
sanity_delta > 0em 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".
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
-
Verifique a cadência: 60 s entre instantâneos é confortável; 30 s é marginal; < 10 s garante instantâneos obsoletos.
-
Verifique a capacidade de resposta do módulo entre instantâneos:
if (rbamp_probe(dev) == ESP_OK) {
ESP_LOGI(TAG, "alive");
}
- Verifique o flag diretamente —
rbamp_is_period_valid()faz uma leitura de um byte sem efeitos secundários:
bool valid;
if (rbamp_is_period_valid(dev, &valid) == ESP_OK && valid) {
/* avg_p[] can be read */
}
- Verifique a versão do firmware —
rbamp_firmware_version(dev) >= 0x02mostra 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
-
Calibração do sensor de corrente: confirme que
rbamp_set_sensor_class()erbamp_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. -
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). -
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):
-
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".
-
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.
-
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.
#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:
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.
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ãoSTA+AP). -
Desative o BLE se não precisar dele:
CONFIG_BT_ENABLED=nno 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):
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):
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 */
}
⚠ 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_*.
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:
-
Código de modelo inválido para a classe — os códigos válidos dependem da classe de sensor:
SCT013aceita{1, 2, 3, 4, 5, 6, 7}(ver a tabela em 03 · Seleção do sensor de corrente);WIRED_CTaceita1–10e12. Um código desconhecido para a classe devolveESP_ERR_INVALID_ARG. -
Índice de canal inválido na forma por canal
rbamp_set_ct_model_ch(dev, channel, code)— tem de ser <rbamp_channels(dev). -
Um valor inválido de
rbamp_sensor_class_t— uma classe acima de3devolveESP_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 useRBAMP_SENSOR_SCT013. -
dev == NULLouout == NULL— confirme querbamp_new()teve êxito (devolveuESP_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:
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;
}
⚠ 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:
// 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 etiquetarbamp. -
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.
Ligações
- 05 · Arranque rápido — o seu primeiro projeto a funcionar
-
09 · Referência da API — API completa + avisos sobre os métodos públicos com WARNING + secção Kconfig
-
03 · Seleção do sensor de corrente — tabela de modelos SCT-013, topologia de CT duplo para uma gama dinâmica ampla, abordagens para melhorar a sensibilidade a correntes baixas
Fonte e problemas: rb-amp/rbamp-esp-idf · esta página no repositório: docs/10_troubleshooting.md (v1.7.3)