rbAmp
PT
Loja
Docs
Atualizado · Editar no GitHub (Edit on GitHub)

10 · Resolução de problemas

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

Um guia de depuração orientado por sintomas para o componente rbamp no ESPHome. Cada entrada segue a mesma estrutura: o que vê no registo, o que significa, como diagnosticar e uma correção concreta.

Contents:

  1. I2C / hardware
  2. Qualidade dos dados
  3. Energia e persistência
  4. Integração com o Home Assistant
  5. Compilação e toolchain
  6. Identidade / Capacidade / Erro (v1.3)

1. I²C / hardware

Probe failed at 0x50 — sem resposta

O que vê no registo:

Text
[E][rbamp:xxx]: Probe failed at 0x50 — no response. Check wiring/address.
[E][component:xxx]: Component rbamp was marked as failed.

O componente chama então mark_failed() e deixa de fazer mais chamadas a update(). Todos os sensores associados ficam "Unknown" no Home Assistant.

O que significa:

O ESP32 enviou a fase de endereço para 0x50 (ou outro endereço de address:) e não recebeu ACK. O módulo está ausente, sem alimentação ou noutro endereço.

Como diagnosticar:

  1. Confirme que scan: true está definido no bloco YAML i2c:. Reinicie o ESP32 e observe:

    Text
    [I][i2c.arduino:069]: Found i2c device at address 0x50
    

    Se o scan encontrou o dispositivo, a chave address: no seu bloco rbamp: está errada — atualize-a.

  2. Meça a alimentação no pino VCC do módulo com um multímetro: tem de estar entre 4.5 e 5.5 V (5 V nominal, ver 04_hardware.md). Zero ou abaixo de 4.5 V significa que a alimentação está em falta ou é marginal.

  3. Verifique a continuidade de SDA e SCL desde o GPIO do ESP32 até ao conector do módulo. Um fio em falta ou trocado é a causa mais comum em montagens novas.

  4. Verifique as resistências de pull-up em SDA e SCL (4.7 kΩ para 3.3 V). Sem pull-ups o barramento fica em nível baixo e cada fase de endereço parece um NACK.

  5. Se fez recentemente uma alteração de endereço (a chave new_address:), o módulo pode estar agora no novo endereço. Adicione scan: true, encontre o dispositivo, atualize address: em conformidade e remova new_address:.

Correção: corrija a cablagem / alimentação e atualize address: se o módulo tiver mudado. Se o módulo não responder após uma alteração de endereço, veja "Endereço alterado mas módulo sem resposta" abaixo.


Bloco RT não pronto — publicação ignorada

O que vê:

Text
[D][rbamp:xxx]: RT block not ready (STATUS=0x00) — skipping live publish

O que significa: o registo de estado indicou que o módulo não está pronto. Isto acontece quando o módulo ainda não confirmou o primeiro bloco de valores instantâneos após o arranque, está a meio de uma escrita em flash ou está num reset suave.

Como diagnosticar:

  1. Se a entrada aparecer uma vez no arranque (nos primeiros 30 s após ligar) e depois desaparecer, isto é normal. O módulo precisa de um ciclo de commit (~100 ms) para definir o bit READY após ligar. O instantâneo de arranque em setup() também produz um ciclo saltado.

  2. Se as mensagens continuarem a fluir após o aquecimento, o módulo pode estar bloqueado. Verifique entradas ct_model: / ct_models: repetidas (por exemplo, uma chave deixada no YAML que é escrita em cada arranque, produzindo uma janela permanente de escrita na flash).

  3. Se a mensagem aparecer ocasionalmente (uma vez a cada poucos ciclos), é uma variabilidade normal ligada a NACK. O ciclo de repetição apanha a maioria dos transitórios; por vezes a leitura de estado ainda falha, o que desencadeia esta entrada DEBUG.

Fix:

  • Os saltos de aquecimento no arranque são esperados; aguarde dois ciclos update_interval completos.
  • Se ct_model: / ct_models: estiver definido no YAML, deixe-o: em cada arranque a escrita repetida é idempotente (o módulo não escreve se o valor já estiver na flash). Se as pausas de aquecimento o incomodarem, comente a chave após uma primeira execução bem-sucedida.
  • Se o módulo permanecer não pronto durante 60+ s, desligue a alimentação do módulo (não do ESP32) para um arranque a frio limpo.

"rbamp took a long time for an operation (XXX ms)"

O que vê:

Text
[W][component:522]: rbamp took a long time for an operation (406 ms), max is 30 ms

O que significa: este aviso dispara quando o update() de algum componente excede o orçamento predefinido de 30 ms do escalonador cooperativo do ESPHome. Para o componente rbamp isto é esperado e inofensivo.

Na v1.3 do firmware, a leitura com auto-incremento é suportada para o bloco de valores instantâneos (o intervalo contíguo que cobre U / I / P / PF / Q para todos os canais declarados). O componente emite uma única leitura em rajada para esse bloco — um fase de endereço seguida de ~36 bytes de dados — o que custa ≈ 8–10 ms de tempo de fio a 50 kHz. A escrita com auto-incremento não é suportada, pelo que as escritas por registo (preparação do modelo CT, classe do sensor, confirmação de endereço) continuam byte a byte. Se a leitura em rajada falhar (NACK a meio, bit de capacidade não definido em firmware antigo), o componente recorre a leituras por registo (4 transações por float, até 36 transações ≈ 90 ms a 50 kHz). Com o trio de retentativas por byte (até 3 × 5 ms de intervalo num ciclo com muitos NACK), o caminho de fallback no pior caso fica normalmente entre 300 e 450 ms — o que produz este aviso quando aparece.

A estabilização do instantâneo (set_timeout("rbamp_period", 50, ...)) é não bloqueante — update() cede o controlo ao agendador enquanto decorrem os 50 ms. O aviso reflete o tempo de relógio de parede de toda a leitura bloqueante de valores instantâneos, não uma falta de Wi-Fi ou de API.

Não é necessária nenhuma ação do utilizador. O aviso é cosmético; os sensores do HA atualizam-se corretamente. Em módulos v1.3 saudáveis, o caminho de leitura em rajada fica normalmente abaixo de 30 ms e o aviso nem chega a disparar.

Se o aviso disparar em todos os ciclos: o barramento está a forçar a recuperação por registo (firmware legado sem a capacidade de leitura em rajada, ou pull-ups marginais que produzem NACKs a meio da rajada). Verifique a versão da firmware (Firmware version: 0x04 no registo de arranque = v1.3) e a topologia de pull-up (um único par de 4.7 kΩ para 3.3 V limpos).


Falha ao ler o instantâneo do período

O que vê:

Text
[W][rbamp:xxx]: Failed to read PERIOD_AVG_P[0]
[W][rbamp:xxx]: Failed to read PERIOD_AVG_P[1]

O que significa: após o comando de instantâneo e a espera de 50 ms, o componente não conseguiu ler o registo de potência média do período para o canal N após três tentativas. O acumulador de energia desse canal não é atualizado neste ciclo.

As causas mais comuns:

  1. Interrupção de escrita na flash. O módulo está a escrever um modelo de CT (acionado por ct_model: ou ct_models: no arranque) ou a guardar um novo endereço. A janela é de ~700 ms; se a estabilização de 50 ms do snapshot cair dentro dela, a leitura expira.
  2. Instantâneo perdido sob polling intenso. Sob polling I²C intenso e consecutivo, o lado do módulo pode perder um instantâneo. O instantâneo fica vazio, mas a flag de validade será 0 — o componente salta a integração com a mensagem "Period snapshot not yet valid; keeping previous integration window". O aviso só dispara quando a flag de validade está definida mas a leitura do registo falhou.
  3. Esgotamento de NACK transitório. Todas as três retentativas falharam em pelo menos um dos quatro bytes do float. Raro a 50 kHz (< 1% dos ciclos); mais frequente a 100 kHz.

O que acontece à energia: num aviso, last_latch_ms_ não é atualizado. No ciclo bem-sucedido seguinte, dt_ms cobre tanto a janela perdida como a nova — a energia recupera, assumindo uma carga aproximadamente estável no intervalo. Esta é uma pequena imprecisão aceitável.

Fix:

  • Remova as chaves de alteração de endereço (new_address:) do YAML após o primeiro arranque bem-sucedido.
  • Se o aviso disparar mais de uma vez por hora, verifique a velocidade do barramento (recomenda-se 50kHz) e as resistências de pull-up (4.7 kΩ).
  • Se o aviso disparar em todos os ciclos, verifique se há conflito com outro dispositivo no barramento.

Endereço alterado, mas o módulo não responde

O que vê:

Text
[E][rbamp:xxx]: Address change applied but slave not responding at 0x51 —
    check wiring and try power-cycling the rbAmp.
[E][component:xxx]: Component rbamp was marked as failed.

O que significa: o fluxo de alteração de endereço executou todos os passos (escrever o novo endereço, guardar na flash, reset suave, trocar o endereço I²C interno do componente), mas o módulo não respondeu no novo endereço na primeira verificação.

Possíveis causas:

  1. O endereço foi escrito e guardado, mas o módulo entrou num estado incorreto (corrupção dos parâmetros da flash, uma falha de energia durante a janela de escrita de 700 ms).
  2. No firmware legado (v1.0-v1.2): o módulo não estava em modo de provisionamento de fábrica no momento da tentativa. No firmware v1.3+ esta causa não se aplica (o commit em duas fases está pronto para produção). Se a própria leitura do estado do modo falhou (NACK), o componente executa a escrita de forma especulativa, com um aviso no log.
  3. Um problema de ligação que já existia antes da alteração de endereço (a sondagem do endereço antigo só teve êxito por coincidência numa das três tentativas).

Procedimento de recuperação:

  1. O módulo está num endereço desconhecido. Use um YAML de teste com i2c: scan: true e um corte de alimentação — descubra em que endereço o módulo responde.
  2. Se o módulo for encontrado no novo endereço (por exemplo 0x51), atualize o YAML para address: 0x51, remova new_address: e volte a gravar. O próximo arranque será limpo.
  3. Se o módulo não responder em nenhum endereço, a escrita na flash pode ter corrompido os parâmetros. A recuperação exige intervenção física: consulte a documentação do módulo ou o seu fornecedor.

Contexto: o fluxo de alteração de endereço na firmware v1.3 é um commit em duas fases — o mestre escreve o novo endereço num registo de preparação e depois emite CMD_COMMIT_ADDR para o tornar persistente. A janela de escrita de 700 ms é o apagamento + programação da flash da página de configuração do utilizador. Ver 09 · Referência da API.


i2c_master bloqueado — ciclo de arranque do ESP32 ou bloco RT nunca publica

O que vê:

Text
[I][i2c.idf:xxx]: Performing I2C bus reset...
[E][i2c.idf:xxx]: i2c_master_send_buf failed: ESP_ERR_TIMEOUT
[E][rbamp:xxx]: Probe failed at 0x50 — no response. Check wiring/address.
[E][component:xxx]: Component rbamp was marked as failed.

No pior caso, um timeout do watchdog de tarefa reinicia o ESP32 após vários minutos de imersão (sob carga, não na primeira ligação). Pode parecer que "o módulo funcionou durante uma hora e depois parou".

O que significa: o driver i2c_master do ESP-IDF v5 tem um problema conhecido: num barramento marginal (tempo de subida lento, pull-up fraco, rajada de EMI) o i2c_ll_is_bus_busy interno entra em ciclo infinito, à espera de uma condição STOP que nunca chega. No ESPHome 2025.x este ciclo pode consumir o orçamento do watchdog da aplicação e provocar um reinício. Este é um problema canónico do ESP-IDF, não específico do rbAmp.

Mitigação em três camadas (todas ativas no componente por predefinição, mais as recomendações de hardware):

  1. Software: a disciplina NACK incorporada — 50 kHz por predefinição + 3× repetição por byte com intervalo de 5 ms + o filtro de sanidade IP-009 std::isfinite(). Já presente no componente desde a v0.2+. A correção de robustez do stop-handler foi entregue na firmware v1.1/v1.3, mas 50 kHz continua recomendado em mestres ESP-IDF porque a interação de temporização do driver persiste.

  2. Hardware: um pull-up externo de 4.7 kΩ em SDA + SCL (um único par de pull-up externo, com os jumpers do módulo cortados — ver §Barramento com vários módulos). Os pull-ups internos do ESP32 (~50 kΩ) são fracos — num barramento longo ou com uma alimentação marginal não chegam. Pull-ups de 4.7 kΩ para 3.3 V limpos são obrigatórios numa implementação de produção.

  3. Hardware: não mantenha o depurador / o reset OTA ativo durante transações I²C. Um RESET ativado a meio de uma transação deixa o barramento bloqueado (o escravo continua a conduzir o SDA), o que é exatamente o que provoca o ciclo infinito de barramento ocupado.

Taxa de bloqueio observada num teste de imersão de 24 horas:

Camada Taxa de bloqueios Nota
Apenas software (sem pull-up externo) ~1× por 10 minutos o watchdog da ponte dispara e recupera por reinício, mas o Wh perde uma janela
Software + pull-up externo de 4.7kΩ ~1× por 24 horas Caso de rajada de EMI; recuperação automática
Software + pull-up externo + reinício limpo 0 bloqueia durante um teste de 24 h alvo de produção

Gravidade = tempo de medição (imersão de duração completa), não a primeira ligação. Na primeira ligação a disciplina NACK apanha 99%+ através do triplo de repetições — bloqueios reais só começam após horas de imersão limpa. Para a referência completa da disciplina, ver 09 · Referência da API.

Se a recuperação falhar

: como último recurso, configure wdt: (núcleo do esphome) com app_wdt_timeout_seconds: aumentado (predefinido 5 s; defina 10–15 s). Isto dá tempo à recuperação do componente sem reinício.


2. Qualidade dos dados

A tensão oscila — 228 V / 502 V / 1.96 V misturados

O que vê:

Text
[D][sensor:xxx]: 'Mains Voltage': Sending state 502.730 V
[D][sensor:xxx]: 'Mains Voltage': Sending state 1.964 V
[D][sensor:xxx]: 'Mains Voltage': Sending state 228.365 V
[D][sensor:xxx]: 'Mains Voltage': Sending state 502.730 V

No Home Assistant o gráfico de tensão é um dente de serra entre ~228 V, ~2 V e ~503 V. A corrente pode mostrar simultaneamente 0 A ou −2 A.

O que significa: surgem valores "fantasma" a partir de uma fuga no buffer do driver i2c_master do ESP-IDF em condições de NACK a 100 kHz. Isto deve ser eliminado pela configuração predefinida da versão atual do componente. Se o sintoma aparecer:

  • O bloco i2c: tem frequency: 100kHz — altere-o para 50kHz.
  • A versão do componente é anterior a 2026-05-24 — atualize-a.

Fix:

YAML
i2c:
  sda: GPIO21
  scl: GPIO22
  frequency: 50kHz   # required for reliable operation
  scan: true

Para mais sobre o mecanismo de disciplina de NACK (50 kHz por predefinição + repetição por byte + filtro de sanidade para NaN/Inf), veja 09 · Referência da API.

Nota

Compatibilidade com framework: type: — o problema de valores fantasma por NACK manifesta-se apenas sob o driver i2c_master do ESP-IDF. Com framework: type: arduino (o padrão), usa-se a pilha Wire do framework Arduino, que se comporta de outra forma sob NACK e não reproduz este sintoma. Isto significa que:

  • Se o YAML tiver esp32: framework: type: arduino, pode, em teoria, manter frequency: 100kHz sem picos fantasma visíveis, mas o ciclo de repetição por byte do componente continua a correr sobre o Wire e os NACK periódicos a 100 kHz mantêm-se — apenas sem os valores fantasma. Para gráficos estáveis no HA recomendamos 50 kHz, independentemente do framework.
  • Se o YAML tiver esp32: framework: type: esp-idf, então frequency: 50kHz é obrigatório. Esta é a configuração em que o driver i2c_master mostra mais vivamente o sintoma fantasma.

O próprio componente não escolhe a framework — funciona sobre ambas. Esta é apenas uma decisão no seu YAML.


A corrente está permanentemente a 0 A sob carga

O que vê:

Text
[D][sensor:xxx]: 'Mains Current': Sending state 0.000 A

A potência é 0 W, a energia não cresce, mas a tensão lê corretamente (por exemplo 228 V).

O que significa: uma de duas causas típicas:

Causa 1 — ct_model: não está definido ou não corresponde à pinça física. No firmware v1.2+ o módulo usa os coeficientes de fábrica do modelo selecionado no YAML. Se ct_model: não estiver definido, ou estiver definido como, por exemplo, SCT_013_050 com uma SCT-013-005 real, a gama de medição fica tão superior ao sinal físico que o módulo não consegue resolvê-lo e reporta zero.

Causa 2 — a pinça está instalada incorretamente no condutor (ver a polaridade em 03_sensor_selection.md e envolver apenas um condutor).

Como diagnosticar:

  1. Confirme que a pinça está fisicamente instalada num condutor com corrente e que o condutor transporta mesmo corrente (use um amperímetro de pinça como referência, se tiver um).
  2. Abra o YAML e verifique se ct_model: (ou ct_models: para UI3) corresponde ao modelo da pinça física.
  3. Se ct_model: estiver definido na firmware v1.2+ mas sensor_class: estiver omitido ou com um valor diferente de SCT_013, o módulo recusa a escrita do modelo. O registo de arranque mostra um aviso a apontar para a pré-condição em falta.

Fix:

YAML
rbamp:
  id: meter1
  sensor_class: SCT_013       # default; required on v1.2+ before ct_model
  ct_model: SCT_013_005       # match the physical clamp

Após o arranque, o módulo escreve o modelo na flash uma vez (~700 ms) e carrega os coeficientes de fábrica. A publicação seguinte de valores instantâneos já dá a corrente correta.

Precisão de medição de corrente pequena no UI2 / UI3 — o padrão de CT duplo. Se quiser alta resolução em cargas pequenas (iluminação, stand-by) e uma gama ampla para picos (chaleira, máquina de lavar) ao mesmo tempo, use dois canais de corrente na mesma fase em simultâneo, com pinças diferentes:

YAML
rbamp:
  id: home_meter
  sensor_class: SCT_013
  ct_models: [SCT_013_005, SCT_013_030, SCT_013_050]
  # CH0 — SCT-013-005 for resolving idle loads (~5..50 W)
  # CH1 — SCT-013-030 for the main household load (~50..7000 W)
  # CH2 — SCT-013-050 for the peak (EV-charging headroom up to 11.5 kW)
  # For peaks above 50 A use SCT_013_060 (60 A) or SCT_013_100 (100 A) on that channel

As três pinças envolvem o mesmo condutor de fase L. A SCT-013-005 dá ~10× mais resolução em correntes pequenas do que a SCT-013-030, mas satura a ~5 A. A SCT-013-030 cobre o "meio" da gama útil; a SCT-013-050 apanha picos até ~11.5 kW sem saturar. No lado do HA, um sensor de modelo seleciona a medição "ativa" por limiar:

YAML do Home Assistant (não ESPHome) — vai para a configuração do Home Assistant, não para o YAML do nó.

YAML
# configuration.yaml — select the active channel by range
template:
  - sensor:
      - name: "Mains Current (active)"
        unit_of_measurement: "A"
        device_class: current
        state_class: measurement
        state: >
          {% set i0 = states('sensor.rbamp_ch0_current') | float(0) %}
          {% set i1 = states('sensor.rbamp_ch1_current') | float(0) %}
          {% set i2 = states('sensor.rbamp_ch2_current') | float(0) %}
          {% if i2 > 25 %}{{ i2 }}
          {% elif i1 > 4 %}{{ i1 }}
          {% else %}{{ i0 }}
          {% endif %}

Isto cobre a gama do menor ao maior calibre nominal das três pinças (5 A … 50 A). Compromisso: três pinças de CT no mesmo condutor são fisicamente volumosas, e cada uma ocupa um canal do módulo (no UI3 isso é o módulo inteiro). Para a maioria das implementações uma única pinça com calibre adequado à carga cobre 99% dos cenários — o padrão duplo/triplo de CT só é necessário quando é preciso uma ampla gama dinâmica.


Instantâneo do período inválido — a energia não cresce

O que vê:

Text
[D][rbamp:xxx]: Period snapshot not yet valid; keeping previous integration window

O sensor energy no Home Assistant mostra um valor constante (ou fica em 0 Wh após o arranque), apesar de a potência ser lida corretamente.

O que significa: a flag de validade do instantâneo do período estava a 0 quando o componente a verificou 50 ms após o comando de instantâneo. O módulo ainda não confirmou um instantâneo de período válido.

Causas normais:

  1. Primeiro snapshot após o arranque. O snapshot de arranque em setup() descarta sempre o seu resultado — o acumulador do módulo é reposto no primeiro comando de snapshot. O segundo snapshot (um update_interval após o arranque) é o primeiro que integra. A energia começa a acumular após o primeiro update_interval completo desde o arranque.
  2. Arranque a frio do módulo. O módulo precisa de pelo menos um ciclo de confirmação de ~100 ms para que haja dados no acumulador de período. Se o primeiro snapshot ocorrer antes, o indicador de validade é 0.
  3. Instantâneo perdido sob carga intensa de polling. Sob carga I²C intensa, o lado do módulo pode perder um instantâneo. O instantâneo fica vazio; o instantâneo seguinte deve ter sucesso.

Se a entrada disparar em todos os ciclos update() indefinidamente (não apenas nas duas primeiras vezes), o módulo pode estar num estado em que o acumulador de período nunca é confirmado. Desligar e ligar a alimentação do módulo limpa este estado.


3. Energia e persistência

Contador de energia repõe-se a 0 após um reinício

Módulos STANDARD (STD).

A energia vem dos próprios contadores do módulo e é adicionalmente guardada na flash (NVS) do ESP32, pelo que um reinício do ESP32 ou do módulo não a repõe e os totais não regridem. Se um sensor de um módulo STANDARD continuar a começar em 0, a causa é um apagamento da NVS (apagamento da flash, tabela de partições alterada) e uma reposição do contador no módulo ao mesmo tempo. Os sensores de total geral (energy_total, energy_exported_total, energy_net, reactive_energy*) usam o seu próprio slot NVS, separado dos slots energy por canal, pelo que uma atualização do componente não limpa os valores por canal.

O que vê no painel de Energia do HA: uma queda brusca para 0 Wh, depois acumulação normal a partir de 0. O histórico antigo de Wh fica preservado nas estatísticas de longo prazo do HA, mas a "leitura atual do contador" parece reposta.

O que significa: a restauração a partir da NVS não encontrou dados ou carregou dados inválidos. Causas possíveis:

  1. Incremento da versão de layout da NVS. A chave NVS deriva do ID do componente, em XOR com uma constante de versão de layout. Se a estrutura mudou (com uma atualização do componente), a chave do slot NVS muda e os dados antigos deixam de ser encontrados. A restauração começa silenciosamente em 0.
  2. Fragmentação ou corrupção da NVS. A partição NVS do ESP32 usa nivelamento de desgaste da flash. Em implementações muito antigas ou após muitas gravações, a fragmentação pode fazer com que uma gravação falhe. O log mostra: [W][rbamp:xxx]: Failed to save Wh totals to NVS — will retry next cycle.
  3. Alteração da disposição das partições. Gravar um partitions.csv novo que altere o tamanho ou a posição da partição nvs invalida todos os valores guardados.
  4. Primeiro arranque após uma reposição de fábrica ou apagamento total da flash. Esperado: a NVS está vazia, o acumulador começa em 0.

Como diagnosticar:

Procure no log de arranque:

Text
[C][rbamp:xxx]: No saved energy state — starting from 0 Wh

Se estiver presente, a restauração não encontrou nada. Também:

Text
[C][rbamp:xxx]: Restored Wh from NVS: total[0.310, 0.000, 0.000] export[...]

Se o valor restaurado for notavelmente inferior ao esperado, a última gravação NVS de 5 minutos pode ter sido ignorada (perda no pior caso: ≈ 5 Wh com uma média de 60 W).

Fix:

  • Numa atualização do componente que altere o layout de NVS, os totais antigos não se restauram automaticamente. As estatísticas de longo prazo do HA mantêm o histórico mesmo que a "leitura atual" volte a zero.
  • Para preservar Wh através de uma limpeza forçada da NVS, leia os valores atuais dos sensores nas Ferramentas de Desenvolvimento do HA (Developer Tools) antes da limpeza e registe-os. Não há forma de injetar um valor inicial no componente.

A energia no HA não corresponde a um contador de referência

O que vê: o sensor energy no HA lê visivelmente menos (por exemplo 10–20%) do que um contador inteligente de referência ou o contador da distribuidora no mesmo período.

O que significa: nos módulos BASIC o componente integra a potência média do período entre comandos de instantâneo, medidos no tempo do lado do ESP32. Nos módulos STANDARD acumula os contadores de energia do próprio módulo.

Se a energia estiver baixa, verifique entre estas:

  1. Carácter da carga. O registo de potência média do período é, de facto, potência média no tempo sobre um período fechado, não um valor instantâneo. Uma carga pulsada (motor, compressor) com um tempo de ligação curto dentro do período de 60 segundos fica, em média, abaixo da sua potência de pico.
  2. Colocação da pinça e calibração da carga (burden). Se o modelo de CT de fábrica (ct_model:) não corresponder à realidade, as gamas dos coeficientes ficam deslocadas. Verifique se o ct_model: no YAML corresponde à pinça física no condutor.
  3. Nível de firmware BASIC. No SKU BASIC, as amostras de P por janela são limitadas a 0 antes da integração. Se a carga tiver uma componente regenerativa (por exemplo um motor de bomba com força contraeletromotriz), o BASIC subcontabiliza.

4. Integração com o Home Assistant

O HA mostra "Unavailable" para todos os sensores rbamp

O que vê no HA: todas as entidades sensor.rbamp_* mostram "Unavailable".

Causas e correções:

  1. ESP32 offline. Execute esphome logs --device — se não conseguir ligar-se, o ESP32 está offline. Verifique as credenciais WiFi e o AP de recurvo, se estiver configurado.
  2. Ligação à API perdida. A API nativa do ESPHome (porta 6053) pode estar bloqueada por uma firewall. Verifique se o ESP32 é alcançável pelo IP:

    Shell
    ping 
    

    Se o ping funcionar mas o HA continuar a mostrar indisponível, a integração ESPHome no HA tem de ser removida e voltar a ser adicionada (Definições → Integrações → ESPHome → Eliminar, e depois redescobrir).

  3. Incompatibilidade da chave de encriptação da API. Se api: encryption: key: estiver configurado no YAML, a integração do HA tem de conhecer a mesma chave. Uma incompatibilidade faz o HA tratar o dispositivo como offline. Remova e volte a adicionar a integração depois de atualizar a chave.

  4. O mDNS não funciona na sua topologia de rede. Se o ESP32 estiver numa VLAN diferente do HA, o mDNS em multicast pode não atravessar a fronteira. Adicione o dispositivo por IP manualmente na integração ESPHome.

Falha a gravação OTA

O que vê:

Text
ERROR Error resolving IP address: ...
# or
ERROR Upload Failed

Causas comuns:

  1. O endereço IP mudou. O ESP32 obteve uma nova concessão DHCP. Verifique a tabela DHCP do router, encontre o dispositivo pelo MAC e atribua um IP estático, ou use a chave YAML wifi: use_address:.
  2. O ESP32 está em modo de segurança. Após três arranques falhados seguidos, o ESPHome entra em modo de segurança (sem componentes personalizados, apenas Wi-Fi + OTA). A atualização OTA em modo de segurança funciona, mas o dispositivo executa um firmware reduzido. A marca em esphome logs:

    Text
    [I][safe_mode:xxx]: Entering safe mode
    

    Force um arranque limpo: mantenha premido o botão BOOT ao ligar, ou adicione safe_mode: num_attempts: 10 para alargar o limiar.

  3. A porta 3232 (OTA) está bloqueada. O protocolo OTA usa TCP 3232. Verifique se nenhuma regra de firewall bloqueia essa porta entre a máquina que executa esphome run (ou o servidor do HA) e o IP do ESP32.

  4. Um firmware grande após adicionar o rbamp. O primeiro OTA após adicionar um componente externo pode exceder o tamanho da partição OTA no layout predefinido de 4 MB do ESP32. Verifique os avisos de tamanho binário na saída de esphome compile e mude para um layout com uma partição OTA maior, se necessário.

OTA logo após o provisionamento de new_address: não carrega

Sintoma: após um primeiro arranque bem-sucedido com a chave new_address: (o log mostra Address change SUCCESS, new address 0x51), o OTA seguinte falha com um erro de compilação ou um aviso em tempo de execução address 0x50 NACK.

O que aconteceu: o módulo está agora no novo endereço (0x51), mas o YAML continua a apontar para o antigo (address: 0x50). No próximo update() o componente tenta 0x50, não obtém resposta e regista NACK constantes. O OTA em si não falha aqui — é apenas um sintoma adjacente: vê uma sucessão de erros rbamp em esphome logs e conclui que o dispositivo está avariado.

Recuperação em 3 passos:

  1. Edite o YAML:

    YAML
    rbamp:
      id: meter1
      address: 0x51        # new address — set instead of 0x50
      # new_address: 0x51  # ← REMOVE this line. Do not comment it out,
      #                       delete it entirely, otherwise the component
      #                       tries to provision again and logs a warning
      update_interval: 60s
      ct_model: SCT_013_030
    
  2. Execute esphome run (via CLI) ou Compile + Upload (via add-on do HA). O nó recebe o novo binário por OTA sobre Wi-Fi.

  3. Abra esphome logs e confirme que a mensagem de arranque dump_config mostra o endereço correto e que update() corre sem NACK.

Regra — new_address: é uma operação de provisionamento única. Assim que o módulo tiver passado para o novo endereço e o tiver guardado na flash, a chave tem de ser removida do YAML. Caso contrário, em cada arranque o componente tentará provisionar de novo (na v1.2+ o módulo ignora a escrita repetida, mas o aviso permanece no log e polui o notify do HA).

Se o módulo não responder em nenhum endereço depois da alteração, veja "Endereço alterado, mas o módulo não responde" acima.


5. Compilação e toolchain

Erro de compilação: 'esphome/core/component.h' file not found

O que vê no VS Code / clangd: sublinhados vermelhos em toda a rbamp.h e rbamp.cpp. Pop-up:

Text
'esphome/core/component.h' file not found

O que significa: o clangd (o IntelliSense C++ do VS Code) não tem acesso aos caminhos de include do ESPHome + PlatformIO. O sistema de compilação resolve-os corretamente durante esphome compile; o clangd não.

Isto não é um erro de compilação. Se esphome compile example/ui1.yaml passar sem erros, o código está correto.

Se quiser remover os sublinhados vermelhos: crie um ficheiro .clangd na diretoria do componente, a apontar para os caminhos de include gerados no resultado de compilação do ESPHome (.esphome/build//src/). Isto é cosmético e opcional.


O PlatformIO falha com 0xC0000001D (EXCEPTION_ILLEGAL_INSTRUCTION)

O que vê:

Text
Error: Failed to install Python dependencies (exit code: 3221225501)

(0xC0000001D = 3221225501 em decimal)

O que significa: o PlatformIO 6.1.19+ usa o binário Rust uv para instalar as dependências Python no seu penv interno. Em alguns CPUs Intel portáteis recentes o uv falha com EXCEPTION_ILLEGAL_INSTRUCTION devido a uma incompatibilidade de conjunto de instruções. Isto afeta o passo penv_setup.py install numa instalação nova do PlatformIO.

Solução alternativa (pré-instalar todas as dependências com pip, contornando o uv):

Text
# Step 1: install the ESP32 platform's Python dependencies directly
& "$env:USERPROFILE\.platformio\penv\Scripts\python.exe" -m pip install `
    "littlefs-python>=0.16.0" "fatfs-ng>=0.1.14" "pyyaml>=6.0.2" `
    "rich-click>=1.8.6" "zopfli>=0.2.2" "intelhex>=2.3.0" "rich>=14.0.0" `
    "cryptography>=45.0.3" "certifi>=2025.8.3" "ecdsa>=0.19.1" `
    "bitstring>=4.3.1" "reedsolo>=1.5.3,<1.8" "esp-idf-size>=2.0.0" `
    "esp-coredump>=1.14.0" "pyelftools>=0.32"

# Step 2: bootstrap the nested ESP-IDF venv (see the next entry)
& "$env:USERPROFILE\.platformio\penv\.espidf-5.5.4\Scripts\python.exe" `
    -m ensurepip --default-pip
& "$env:USERPROFILE\.platformio\penv\.espidf-5.5.4\Scripts\python.exe" `
    -m pip install -r `
    "$env:USERPROFILE\.platformio\packages\framework-espidf\tools\requirements\requirements.core.txt"

Depois de instalados estes pacotes, get_packages_to_install() em penv_setup.py devolve vazio e a instalação pip via uv não é chamada. As execuções seguintes de esphome compile funcionam normalmente.

A solução alternativa tem de ser reaplicada depois de uma instalação nova do PlatformIO ou depois de limpar a cache ~/.platformio.


venv do ESP-IDF: sem o módulo idf_component_manager

O que vê:

Text
ModuleNotFoundError: No module named 'idf_component_manager'

Aparece na primeira esphome compile numa máquina onde o PlatformIO descarregou o framework ESP-IDF mas não executou o bootstrap completo dos seus requisitos.

O que significa: o framework ESP-IDF do PlatformIO está instalado no venv aninhado ~/.platformio/penv/.espidf-5.5.4/ (o número da versão pode diferir). Esse venv precisa de requirements.core.txt do pacote do framework. Quando a solução alternativa com uv acima for aplicada, o passo 2 instala o pip no venv e instala os requisitos.

Se o erro aparecer depois de aplicar a solução alternativa do uv, mas o passo 2 tiver sido omitido:

Text
# Find the IDF venv (the version number may differ):
ls "$env:USERPROFILE\.platformio\penv\" | Where-Object { $_.Name -like ".espidf-*" }

# Bootstrap pip into the IDF venv:
& "$env:USERPROFILE\.platformio\penv\.espidf-5.5.4\Scripts\python.exe" `
    -m ensurepip --default-pip

# Install the IDF core requirements:
& "$env:USERPROFILE\.platformio\penv\.espidf-5.5.4\Scripts\python.exe" `
    -m pip install -r `
    "$env:USERPROFILE\.platformio\packages\framework-espidf\tools\requirements\requirements.core.txt"

Substitua pelo número da sua versão do IDF no lugar de 5.5.4 (verifique em ~/.platformio/penv/).


esphome compile falha: get_object_id_hash não encontrado

O que vê:

Text
error: 'class esphome::rbamp::RbAmpComponent' has no member named 'get_object_id_hash'

O que significa: uma versão antiga do rbamp.cpp chamava this->get_object_id_hash() para semear o slot NVS. Este método foi removido do PollingComponent no ESPHome 2025.x.

Correção: atualize o componente para a versão atual. O código moderno usa geração de hash compatível com o ESPHome 2025.x e posteriores.


ESPHome demasiado antigo — set_i2c_address não encontrado

O que vê:

Text
error: 'class esphome::i2c::I2CDevice' has no member named 'set_i2c_address'

O que significa: o fluxo de alteração de endereço new_address: chama i2c::I2CDevice::set_i2c_address(), que uma versão mais antiga do ESPHome não tem.

Correção: atualize para o ESPHome 2025.3.0 ou posterior. O add-on ESPHome do HA acompanha automaticamente a versão atual — é o caminho de instalação recomendado.

Shell
# If using a local Python venv:
pip install --upgrade esphome

6. Identidade / capacidade / erro (v1.3)

Esta secção explica o que significam os valores individuais das entidades de identidade (um text_sensor de modelo via lambda:), o mapa de bits de capacidades e os códigos REG_ERROR acrescentados na v1.3.

As leituras de identidade devolvem "UNK" / "UNREADABLE"

O que vê (text_sensor template):

YAML
text_sensor:
  - platform: template
    name: "Meter variant"
    lambda: 'return id(my_meter).get_variant_str();'  # → "UNK" in HA
Text
[D][rbamp:xxx]: get_variant_str(): REG_HW_VARIANT read failed (NACK) — returning UNK

O que significa:

  • "UNK" — o componente não conseguiu ler o REG_HW_VARIANT (0x55) após todas as repetições. Causas: o módulo tem firmware legado (v1.0–v1.1, antes da deteção de variante), ou um barramento I²C marginal com esgotamento de NACK neste registo específico.

  • "UNREADABLE" — a leitura devolveu um valor fora de 0x55..0x5A, além do intervalo de códigos de variante válidos. Isto indica corrupção da firmware ou colisão de registo bruto (por exemplo, um buffer obsoleto).

Fix:

  • Se a firmware for inferior à v1.2, a deteção de variante não está disponível. O text_sensor continua a publicar; use uma sugestão do lado do YAML através de topology: ou reinicialize através de um modelo do HA.

  • Se a firmware for v1.3+ e o barramento for marginal, veja i2c_master bloqueado.

Mapa de bits de CAPACIDADE = 0x0000

O que vê:

YAML
text_sensor:
  - platform: template
    name: "Meter capability"
    lambda: 'return id(my_meter).get_capability_hex();'  # → "0x0000"

O que significa: o registo de capacidades não existe nesta firmware — lê-se como 0 (o comportamento padrão de "registo não implementado" na firmware rbAmp). Isto é firmware legado v1.0–v1.2.

Comportamento do componente: todas as funcionalidades condicionadas por capacidade (GC da frota, commit de endereço em duas fases, save_user_config, clear_error) recuam automaticamente para o caminho legado:

  • fleet_gc_enable: true → aviso + ignorar (não anunciado pelo firmware)
  • new_address: → fallback monofásico, requer o modo de provisionamento de fábrica
  • clear_error() → fallback de opcode do fornecedor (melhor esforço)

Zero regressões: as implementações v0.4.0 existentes continuam a funcionar sem alterações ao YAML ou ao comportamento. Este é o cânone C5 — o condicionamento por capacidade nunca quebra o legado.

last_error_str() mostra "ERR_PARAM" depois de uma alteração de ct_model: ou sensor_class:

O que vê:

Text
[W][rbamp:xxx]: REG_ERROR after CT_MODEL write: 0xFE (DEV_ERR_PARAM)

get_last_error_str() → "ERR_PARAM".

O que significa: o firmware rejeitou o valor escrito. Os desencadeadores mais comuns:

  1. Um código fora do conjunto aceite — para SCT_013 os códigos aceites são {1, 2, 3, 4, 5, 6, 7}.

  2. Modelo de CT fora do conjunto permitido da classe — por exemplo WIRED_CT_1 com sensor_class: SCT_013. Ver tabela por classe em 03_sensor_selection.md.

  3. Código 0 (UNSET) — tentativa de limpar o modelo CT com 0. Não suportado; use dev.factoryReset() para uma reposição completa.

Recuperação: chame id(my_meter).write_clear_error(); através de um serviço YAML ou via lambda: em on_boot: para limpar REG_ERROR + EVENT_FLAGS bit3. Depois pode tentar de novo com um valor correto.

YAML
api:
  services:
    - service: my_meter_clear_error
      then:
        - lambda: 'id(my_meter).write_clear_error();'

A alteração de ct_model: / sensor_class: é recusada (linha de registo, sem escrita)

O que vê:

Text
[W][rbamp:xxx]: ct_model refused: module is calibrated with its fitted sensor (class N) — ...
[W][rbamp:xxx]: sensor_class refused: module is calibrated with its fitted sensor (class N); ...

O que significa: o módulo foi calibrado em par com o seu próprio sensor (WIRED_CT / BUILTIN_CT). Escrever uma classe ou modelo genérico substituiria essa calibração individual, por isso o componente recusa. Isto é a guarda de escrita, não uma falha. Um valor igual também nunca é escrito (nada é registado a nível de aviso para isso).

Correção: remova sensor_class: / ct_model: / ct_models: do YAML desse módulo. Só se quiser deliberadamente a predefinição genérica, defina ct_model_force: true juntamente com o modelo, grave uma vez e remova as duas linhas depois (o esquema rejeita ct_model_force: sem uma chave de modelo).

ct_models: não suportado por este dispositivo (módulo STANDARD)

O que vê:

Text
[W][rbamp:xxx]: ct_models: (per-channel) not supported by this device — it does not advertise persistent per-channel model storage ... Use the global `ct_model:` key. (Keys ignored.)

O que significa: o módulo não consegue manter modelos por canal através de um corte de energia, por isso escrevê-los reverteria silenciosamente. O componente recusa em vez de perder o valor.

Correção: use a chave única ct_model: para todos os canais.

Alterar ct_model: reinicia o módulo uma vez

Em módulos SCT com firmware até 1.4.19, a troca para outro calibre conclui-se com um reinício do módulo (guardar, repor, reidentificar). O log mostra o reinício e, depois, que a corrente/potência/energia estão escaladas para o novo calibre; os sensores podem saltar um update() entretanto. Faz parte do fluxo normal. O firmware 1.4.20 e posteriores realiza a troca no próprio módulo e não há reinício. Se o log indicar que o ganho aplicado está fora do intervalo esperado, o componente não escala; verifique se ct_model: corresponde à pinça instalada fisicamente.

Os sensores de total geral / ângulo nunca publicam

O que vê (registo de arranque):

Text
[W][rbamp:xxx]: energy_total/energy_net/reactive_energy sensors need on-device energy counters, which this device does not advertise — they will never publish. Per-channel `energy:` keys still work ...
[W][rbamp:xxx]: voltage_angle_*/phase_sequence sensors need a newer device firmware — they will never publish on this device

O que significa: o módulo ligado (ou a sua firmware) não fornece estes valores. As chaves validam, mas nada é publicado.

Correção: use os sensores energy: por canal, ou atualize a firmware do módulo.

start_current_ua: ignorado

[W][rbamp:xxx]: start_current_ua: not supported by this device firmware — key ignored — o módulo conta energia a qualquer corrente. A chave só tem efeito nos módulos STANDARD com contadores de energia no dispositivo. Valores diferentes de 0 ou de 10..2540 em passos de 10 são rejeitados em esphome config.

update_interval rejeitado

update_interval abaixo de 1s é rejeitado pelo esquema em esphome config. latch_interval não pode ser inferior a update_interval.

EVENT_FLAGS bit3 (ERR_LATCH) — comportamento de re-latch

O que vê: depois de clear_error(), alguns centenas de milissegundos mais tarde o bit3 em EVENT_FLAGS fica definido de novo (re-latch persistente).

O que significa: o canal de erro durável da firmware volta a fixar o bit3 depois de uma limpeza se a condição de erro original não tiver sido resolvida. Isto é intencional — o mestre pode perder a primeira limpeza e não deve assumir que o erro desapareceu para sempre se o parâmetro continuar errado.

Correção: a recuperação completa exige dois passos:

  1. Elimine a causa (substitua o código de modelo CT errado, corrija o YAML).
  2. write_clear_error() — esta chamada limpa REG_ERROR e o bit3 de EVENT_FLAGS numa única operação.

Se o bit3 continuar a voltar a ser ativado, o parâmetro continua errado; releia get_last_error_str() para descobrir exatamente o que o firmware está a rejeitar.


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