03 · Seleção do sensor de corrente
O rbAmp mede a corrente através de uma pinça de CT externa (transformador de corrente) e a tensão através de um transformador de tensão incorporado (nos SKUs UI*). Este capítulo explica como escolher a pinça para a sua carga e como indicar ao módulo, via YAML, qual o modelo instalado.
Família do sensor (sensor_class:)
A revisão de hardware do módulo determina a família de sensores de corrente suportada. Nos SKUs atuais só existe uma:
| Classe | Valor YAML | Estado |
|---|---|---|
| SCT-013 (CT de núcleo dividido) | SCT_013 |
Disponível agora, predefinido |
| WIRED_CT (módulo com a sua própria pinça com fio ajustada) | WIRED_CT |
Fornecido em par: calibrado juntamente com o seu sensor |
| BUILTIN_CT (módulo com sensor integrado) | BUILTIN_CT |
Fornecido em par: calibrado juntamente com o seu sensor |
A classe é definida uma vez e guardada na flash do módulo:
rbamp:
id: meter1
sensor_class: SCT_013 # defaults to SCT_013, can be omitted
Na firmware v1.2+, este valor torna-se uma pré-condição para escrever o modelo CT: o módulo recusará se a classe não estiver definida. O componente nunca escreve uma classe que o módulo já tem.
Proteções de escrita: leitura-comparação-escrita (v1.3+) e proteção de fábrica (v1.8.1+)
No arranque o componente lê a classe de sensor de corrente do módulo e compara-a com o valor pedido no YAML. Se coincidirem, a escrita na flash não acontece (uma escrita de classe no módulo também limparia os modelos de canal, pelo que um valor inalterado nunca é reescrito). Isto significa que:
-
O bloco YAML pode manter
sensor_class: SCT_013para sempre — um arranque repetido não dispara um apagamento da flash (~0 ms em vez de ~700 ms). -
O antigo conselho de "remover
sensor_class:do YAML após o primeiro arranque" está obsoleto — a configuração é idempotente.
O mesmo comportamento aplica-se a ct_model: / ct_models: (ver abaixo).
Módulos fornecidos em par de fábrica (WIRED_CT / BUILTIN_CT). Um módulo fornecido juntamente com o seu próprio sensor ajustado é calibrado como par com esse sensor. O componente protege essa calibração: uma alteração de sensor_class: ou de ct_model: a partir do YAML num módulo destes é recusada com uma linha explícita de log (a escrita substituiria a calibração individual por uma definição genérica). Deixe ambas as chaves fora do YAML nestes módulos. Para pinças SCT-013 (SCT_013, o padrão) as chaves funcionam como descrito abaixo.
Escolher o modelo SCT-013
O módulo aceita qualquer um dos sete modelos da série SCT-013. A saída elétrica de cada um difere, por isso o módulo precisa de saber qual está instalado — os coeficientes de fábrica são carregados para o modelo específico.
Qual é o meu modelo? Leia o calibre na etiqueta do corpo da pinça: SCT-013-030 significa 30 A, por isso escreve ct_model: SCT_013_030. Use o modelo cujo calibre corresponde à etiqueta, não o que "parece mais próximo" da sua carga.
| Código | Nome YAML | Calibre nominal | Carga típica | Máximo a 230 V | Estado da v1.3 |
|---|---|---|---|---|---|
| 1 | SCT_013_005 |
5 A | Iluminação LED, aparelhos individuais, portáteis | ~1.15 kW | produção |
| 2 | SCT_013_010 |
10 A | Computadores de secretária, ar condicionado pequeno, circuito único | ~2.3 kW | produção |
| 6 | SCT_013_020 |
20 A | Esquentadores, ramais médios, ~3-5 kW | ~4.6 kW | produção |
| 3 | SCT_013_030 |
30 A | Medição de toda a casa com consumo típico | ~6.9 kW | produção (SKU predefinido) |
| 4 | SCT_013_050 |
50 A | Carregamento de VE, grande ar condicionado, placa de indução | ~11.5 kW | produção |
| 7 | SCT_013_060 |
60 A | Subcontador industrial, ramais grandes | ~13.8 kW | produção |
| 5 | SCT_013_100 |
100 A | Entrada principal de serviço, alimentações de grande porte | ~23 kW | produção |
SCT_013_060 (60 A) e SCT_013_100 (100 A) são aceites; escolha a pinça cujo calibre corresponda à sua corrente máxima.
A resistência de carga (burden) já está instalada na placa do módulo — não é preciso acrescentar resistências externas entre os cabos de saída da pinça.
Árvore de seleção
Regra geral: escolha a pinça com o calibre mais baixo cujo valor máximo mensurável cubra a carga de pico com uma margem de ~30%. Um calibre sobredimensionado numa carga pequena reduz a amplitude do sinal em relação ao ruído — a precisão cai. Uma pinça com calibre abaixo do pico satura o núcleo magnético e dá leituras grosseiramente erradas.
Validação de CT por classe (novo na v1.3)
O validador de esquema _validate_ct_model_per_class rejeita combinações inválidas de sensor_class: × ct_model: na fase esphome config, antes da gravação e do arranque. Os conjuntos permitidos não são contíguos — isto é cânone explícito, não um erro:
| sensor_class | Códigos permitidos | Nomes no YAML | Comportamento em caso de incompatibilidade |
|---|---|---|---|
SCT_013 |
{1, 2, 3, 4, 5, 6, 7} | SCT_013_005/010/030/050/100/020/060 |
cv.Invalid com uma sugestão |
WIRED_CT |
{1–10, 12} | WIRED_CT_ |
cv.Invalid |
BUILTIN_CT |
{} (nenhum) | — | cv.Invalid (qualquer ct_model é rejeitado) |
UNSET |
{} | — | cv.Invalid (classe não definida) |
Specifically:
-
SCT_013não contíguo: os códigos aceites são{1, 2, 3, 4, 5, 6, 7}(SCT_013_005,_010,_030,_050,_100,_020,_060); a ordem dos códigos não é a ordem dos calibres. -
WIRED_CTé a classe dos módulos fornecidos com a sua própria pinça CT com fio; o esquema aceita os códigos 1/2/3 para ela. O módulo é calibrado de fábrica com esse sensor, por isso o componente recusa alterar classe ou modelo nele (ver a nota de fornecimento em par de fábrica acima). -
BUILTIN_CTé a classe dos módulos com sensor incorporado;ct_model:não é necessário nem aceite pelo esquema. DeclararBUILTIN_CTsem o hardware correspondente não tem utilidade.
Se o YAML passar pelo validador (esquema antigo + firmware novo, sobreposição manual), o firmware devolve REG_ERROR = 0xFE DEV_ERR_PARAM — o módulo não escreve um código não suportado: devolve DEV_ERR_PARAM e os espelhos mantêm o valor anterior.
Como identificar o módulo
Existem duas chaves no YAML — escolhe-se uma das duas conforme tenha a mesma pinça em todos os canais ou pinças diferentes. A transição sintática é de um valor escalar para uma lista YAML (array):
Passo 1 — uma pinça para todos os canais (ct_model:, escalar)
Se tiver uma UI1 (um canal de corrente único) ou uma UI3 com pinças idênticas nos três canais — uma linha:
rbamp:
id: meter1
ct_model: SCT_013_030 # ← scalar value, one model for all channels
Este é o caso mais comum. A maioria das implementações começa com um único modelo de pinça e nunca passa desta linha.
Passo 2 — pinças diferentes em canais diferentes (ct_models:, lista)
Se tiver um UI2 / UI3 e quiser pinças diferentes nos canais (por exemplo uma pinça pequena numa linha de stand-by, uma grande na alimentação principal) — substitua ct_model: por ct_models: (com um s final) e use uma lista YAML entre parênteses retos:
rbamp:
id: meter_ui3
ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
# ↑ ↑ ↑
# channel 0 channel 1 channel 2
#
# This is a standard YAML list (1..16 elements; only as many as the module has channels are applied).
# Order matters: the position in the list = the channel index.
# Mixed codes such as [1, 3, 6] are each kept on their own channel.
É aqui que as pessoas mais tropeçam ao modificar sistemas multi-canal. Lembre-se: ct_model: (sem s) é um valor escalar para um único modelo; ct_models: (com s) é uma lista de valores entre parênteses retos, um por canal. São aplicadas apenas tantas entradas quantos os canais do módulo (1 para UI1, 2 para UI2, 3 para UI3); entradas extra são ignoradas com um aviso.
Os modelos por canal são guardados apenas por módulos que os mantêm através de um corte de energia. Se o módulo ligado não o fizer, o componente recusa de forma ruidosa (aviso, chaves ignoradas) em vez de escrever um valor que reverteria silenciosamente — use aí o ct_model: único.
⚠ Mutuamente exclusivas. Declarar ao mesmo tempo ct_model: E ct_models: é um erro de validação do esquema (cv.Invalid). Use apenas uma das duas.
Uma instalação UI3 com pinças de tamanhos diferentes
O cenário canónico para uma casa com geração própria ou com tipos de carga mistos:
- Canal 0 — pequenos consumos (iluminação LED, modo stand-by, eletrónica). Uma pinça SCT_013_005 (5 A) dá resolução máxima a baixa corrente.
- Canal 1 — cargas principais (placa de indução, esquentador). Uma pinça SCT_013_030 (30 A) cobre o pico doméstico típico.
- Canal 2 — um ramal de potência média (esquentador, ~3-5 kW). Uma pinça SCT_013_020 (20 A) é o ponto ideal entre precisão e margem para um subcontador típico.
Num único bloco YAML rbamp: basta declarar:
rbamp:
id: home_meter
ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
sensor:
- platform: rbamp
rbamp_id: home_meter
voltage:
name: "Mains Voltage"
current:
name: "Lighting Current" # SCT_013_005, channel 0
current_1:
name: "Appliances Current" # SCT_013_030, channel 1
current_2:
name: "Boiler Current" # SCT_013_020, channel 2
# ...power_0/_1/_2, energy_0/_1/_2 likewise
O próprio componente atribui o modelo exato a cada canal no arranque.
O que a chave faz por baixo do capô
Na firmware v1.2+, escrever ct_model: / ct_models: carrega de forma atómica os coeficientes de fábrica (ruído de fundo + ganho) do modelo escolhido para a RAM do módulo e guarda-os na flash. Do lado do utilizador não são necessários passos de calibração adicionais — o módulo sai de fábrica com todas as tabelas de coeficientes necessárias.
Em firmware anterior o valor é guardado como marcador de modelo.
Leitura-comparação-escrita (v1.3+) — porque é que o arranque agora é "instantâneo"
No arranque, o componente v1.3 lê os atuais REG_CT_MODEL_CH0/1/2 (espelhos de 0x51-0x53) e compara-os com os valores pedidos no YAML. Se coincidirem, a escrita em flash é ignorada por completo.
| Cenário de arranque | v0.4.0 (escrita sempre) | v1.3 (leitura-comparação-escrita) |
|---|---|---|
| Configuração já aplicada (os espelhos coincidem) | ~700 ms × N canais de apagamento de flash | 0 ms (apenas leitura de retorno I²C) |
| Configuração alterada (um modelo) | ~700 ms | ~700 ms (apenas delta) |
| UI3 com três modelos diferentes (instalação a frio) | ~2.8 s de falha de energia | ~2.1 s (3 × 700 ms + verificação) |
| UI3 com os mesmos modelos (arranque a quente) | ~2.8 s de interrupção de cada vez | ~0 ms |
Na prática: mantenha ct_model: / ct_models: no YAML para sempre — a configuração é idempotente e não desgasta a flash em arranques repetidos.
Trocar o calibre SCT mantém a precisão
Num módulo STD o ct_model é apenas um rótulo e não define ganho. O resto desta secção descreve módulos BASIC.
Cada módulo SCT é calibrado de fábrica com o SCT-013-030. Ao selecionar outro calibre (ct_model: SCT_013_010, por exemplo), a corrente, a potência e a energia continuam precisas — a calibração de fábrica por unidade é preservada:
-
Na firmware do módulo até 1.4.19 o componente conclui a escrita do modelo com o reinício do módulo que o procedimento exige (guardar, reiniciar, identificar de novo) e escala a corrente, a potência ativa/reativa e a energia para o sensor selecionado a partir do ganho que o módulo aplica de facto. O reinício aparece no registo e é normal; os sensores podem saltar um ciclo. Um reinício posterior do módulo (seu ou externo) é detetado e a escala é recalculada automaticamente.
-
Na firmware mais recente (1.4.20+) o próprio módulo faz a comutação; o componente deteta-o e deixa as leituras intactas (escrita simples de modelo, sem reinício).
-
A tensão e o fator de potência não são afetados.
- Se o ganho aplicado pelo módulo diferir do valor esperado em mais de ±5 %, o componente regista um aviso e não escala.
Não é necessária nenhuma alteração ao YAML para nada disto.
Vinculação multi-canal
O componente associa os canais um a um; a ordem não importa. Modelos mistos num mesmo módulo (por exemplo os códigos [1, 3, 6] num módulo de três canais) ficam cada um no seu canal.
O próprio componente alimenta o watchdog (App.feed_wdt()) durante cada janela de escrita na flash — o orçamento típico de setup() do ESPHome, de 15 s, não é ultrapassado nem numa instalação a frio do UI3.
Verificar a instalação
Após o primeiro arranque, verifique as leituras com uma carga puramente resistiva — uma lâmpada incandescente, uma chaleira, um elemento de aquecimento. Uma carga resistiva dá uma forma de sinal conhecida:
- O fator de potência (
power_factor) deve estar próximo de 1.00 (de forma estável > 0.95). - A potência ativa (
power) deve ser positiva e estável. - A corrente RMS (
current) deve corresponder aP / Ucom uma precisão razoável.
Se as leituras não batem certo:
currentconstante ~0 com a carga em funcionamento → verifique a polaridade e se a pinça envolve um único condutor (ver abaixo)powernegativa de forma constante → inverta a pinça no condutor (seta no sentido contrário)power_factor~0.5..0.7 numa lâmpada incandescente → pode haver uma carga reativa por perto ou a pinça pode estar mal instalada
Diagnósticos detalhados orientados por sintomas estão em 10_troubleshooting.md.
Polaridade da pinça de CT
O corpo da pinça tem uma seta a indicar a direção do fluxo de energia "normal" (consumo, em direção à carga). Com a instalação correta (a seta apontando no sentido da corrente para a carga):
P_real > 0— consumo.P_real < 0— exportação (apenas STANDARD (STD)).
Se a potência ativa for negativa com um consumidor em funcionamento — vire fisicamente a pinça no condutor. Não corrija a polaridade por software: isso mascara erros de direção nas automações a jusante.
A pinça tem de fechar completamente à volta de um único condutor. Não passe L e N pela mesma pinça — os campos magnéticos anulam-se e o sensor lerá quase zero.
Canal de tensão
Os SKUs UI* contêm um transformador de tensão incorporado. O enrolamento primário liga-se a L e N da rede através dos blocos de terminais do módulo, e o módulo mede-o internamente.
A configuração de fábrica do transformador é fixa na revisão da placa — o utilizador não tem nada para configurar. O sensor voltage está pronto a funcionar logo de início.
Os SKUs apenas de corrente (I1 / I2 / I3) não têm canal de tensão. O slot voltage devolve 0 nestes e não pode ser declarado em conjunto com power: ou energy: (o validador do esquema verifica esta dependência).
Módulos multicanal
Nos UI2 / UI3 cada canal é um circuito de medição separado e independente, não um núcleo magnético partilhado. Isto permite-lhe:
- Aplique um único modelo de pinça a todos os canais (
ct_model:) — a configuração típica para cargas uniformes. - Coloque modelos diferentes em canais diferentes (
ct_models:) — para otimizar a precisão em instalações mistas (ver acima). - Dedique um canal ao consumo e outro à exportação solar — a polaridade de cada canal é definida de forma independente pela direção física da pinça.
Próximos passos
- 04_hardware.md — ligação física, seleção de GPIO, o barramento multi-módulo
- 05_quickstart.md — primeira execução em 5 minutos com uma pinça já configurada
- 10_troubleshooting.md — diagnóstico de instalação orientado por sintomas
Origem e problemas: rb-amp/rbamp-esphome · esta página no repositório: docs/03_sensor_selection.md (v1.9.1)