03 · Seleção do sensor de corrente
Este capítulo responde a duas perguntas:
- Que sensor de corrente escolher para uma dada carga.
- Como indicar ao módulo rbAmp a sua escolha para que a calibração de fábrica dessa combinação seja carregada automaticamente.
A ligação física do sensor (orientação da pinça, verificação da polaridade L/N) está descrita em 04_hardware.md. Este capítulo trata de escolher o modelo e das chamadas à API.
Classe do sensor
Os módulos rbAmp trabalham com pinças TC da família SCT-013. Tem de indicar a classe do sensor ao módulo uma vez, com rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013), antes de escolher um modelo de pinça TC específico com rbamp_set_ct_model().
Escolher o modelo SCT-013
A família SCT-013 tem sete modelos que diferem na corrente máxima do circuito primário. Os sete códigos {1, 2, 3, 4, 5, 6, 7} são todos suportados.
code |
Modelo | Gama de corrente | Estado | Utilização típica |
|---|---|---|---|---|
| 1 | SCT-013-005 | 0…5 A | ✅ caracterizado | Cargas pequenas — candeeiros, eletrónica de baixa potência, um interruptor simples |
| 2 | SCT-013-010 | 0…10 A | ✅ caracterizado | Um único aparelho de média potência — frigorífico, máquina de lavar roupa, ar condicionado até 2 kW |
| 3 | SCT-013-030 | 0…30 A | ✅ caracterizado | Entrada de serviço de uma habitação de dimensão média — até ~7 kW |
| 4 | SCT-013-050 | 0…50 A | ✅ caracterizado | Entrada de serviço grande — aquecimento elétrico, carregador de VE, casa com cargas de pico |
| 5 | SCT-013-100 | 0…100 A | ✅ caracterizado | Entrada de serviço principal de uma casa ou pequeno escritório |
| 6 | SCT-013-020 | 0…20 A | ✅ caracterizado | Entrada de serviço média — eletrodomésticos de 3–4 kW, equipamento doméstico pesado |
| 7 | SCT-013-060 | 0…60 A | ✅ caracterizado | Subcontador industrial |
Códigos aceites — {1, 2, 3, 4, 5, 6, 7}. Um código fora deste conjunto (por exemplo 0 ou 8) passado a rbamp_set_ct_model_ch devolve ESP_ERR_INVALID_ARG + REG_ERROR = 0xFE (ERR_PARAM). Ver 09 · Referência da API, secção "Modelo de erros v1.3", para os detalhes de como o componente devolve este erro.
Como escolher o modelo certo
A regra básica:
-
Determine a corrente máxima que pode circular no circuito (com base na maior carga + 30 % de margem).
-
Escolha a pinça de menor calibre acima deste valor.
- Não sobredimensione em mais de 5×. Uma pinça SCT-013-100 num circuito com máximo de 5 A funciona, mas dá baixa resolução e um erro grande nos valores típicos.
Margem
Uma pinça SCT-013 funciona sem saturação dentro da sua gama nominal. Picos breves (arranque do compressor, carga indutiva) podem ultrapassar o calibre em 5–7× — isto é normal, a pinça suporta-o fisicamente, mas a medição torna-se não linear acima do calibre.
Se a sua carga tiver um pico de corrente acima do calibre da pinça, escolha o calibre imediatamente acima. Por exemplo, para uma máquina de lavar com corrente de arranque de 12 A (enquanto a corrente em funcionamento é de 2–3 A): 12 A × 1.3 = 15.6 A, por isso a menor pinça classificada acima disso é a SCT-013-020 (código 6) — melhor do que uma SCT-013-005.
Como indicar a sua escolha ao módulo
Duas chamadas são obrigatórias, pela ordem correta — primeiro rbamp_set_sensor_class(), depois rbamp_set_ct_model(). Se chamar rbamp_set_ct_model() antes de rbamp_set_sensor_class(), o componente devolve ESP_ERR_INVALID_STATE e a predefinição NÃO é carregada.
Um modelo de CT é um predefinido funcional, não uma etiqueta. Escrever o modelo de CT aplica de imediato a linha de base de NF, o ganho e o fator de forma à cadeia de medição do módulo; as leituras de corrente mudam. Alterar sensor_class repõe o modelo de CT em 0 (predefinido) e obriga a defini-lo de novo.
#include "driver/i2c_master.h"
#include "rbamp.h"
void setup_sensor(rbamp_handle_t dev) {
/* Step 1: select the sensor family.
* MANDATORY before rbamp_set_ct_model(). */
esp_err_t err = rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013);
if (err != ESP_OK) {
ESP_LOGE("app", "set_sensor_class: %s", rbamp_err_to_str(err));
return;
}
/* Step 2: select the model within the family.
* 1 = SCT-013-005, 2 = SCT-013-010, 3 = SCT-013-030,
* 4 = SCT-013-050, 5 = SCT-013-100, 6 = SCT-013-020, 7 = SCT-013-060. */
err = rbamp_set_ct_model(dev, 3); /* e.g. SCT-013-030 */
if (err != ESP_OK) {
/* Possible causes:
* ESP_ERR_INVALID_STATE — rbamp_set_sensor_class() was not called
* before rbamp_set_ct_model()
* ESP_ERR_INVALID_ARG — code not in {1,2,3,4,5,6,7}
* ESP_FAIL — communication error (NACK after retry)
*/
ESP_LOGE("app", "set_ct_model: %s", rbamp_err_to_str(err));
return;
}
}
O componente não chama deliberadamente rbamp_set_sensor_class() por si. Se este passo for saltado, rbamp_set_ct_model() devolve ESP_ERR_INVALID_STATE sem escrever na flash. Isto é feito para manter o comportamento previsível e explícito — sem "magia" na API pública.
Após estas duas chamadas:
-
O módulo guarda ambos os valores na flash — a definição sobrevive a um reinício, a um corte de energia e a uma nova gravação do firmware.
-
Os coeficientes de calibração para esta combinação específica (classe do sensor + modelo) são carregados da tabela de predefinições de fábrica. Não precisa de tocar em nenhum registo de calibração manual.
-
A chamada seguinte
rbamp_read_current(dev, 0, &i)já devolve um valor em ampere com a escala correta.
Tempo total para as duas chamadas é de cerca de 1.4 segundos (duas operações de escrita na flash × ~700 ms cada, limitadas pelo tempo de apagamento da página da flash). Isto é feito uma vez na primeira instalação; a definição fica guardada na flash e nunca se repete.
Se já selecionou o sensor no primeiro arranque e está apenas a reiniciar o ESP32, não precisa de repetir as chamadas rbamp_set_sensor_class() e rbamp_set_ct_model() — o módulo lembra-se da escolha anterior. Mas também não faz mal repeti-las: chamar de novo com o mesmo valor apenas reescreve o mesmo byte.
Verificar a configuração
Uma verificação simples de sanidade após rbamp_set_ct_model():
#include
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_log.h"
static const char *TAG = "rbamp_check";
void sanity_check(rbamp_handle_t dev) {
ESP_LOGI(TAG, "Ready. Connect a purely resistive load "
"(e.g. an incandescent lamp).");
ESP_LOGI(TAG, "Expect a stable PF ~= 1.0 and positive P.");
while (1) {
float u = NAN, i = NAN, p = NAN, pf = NAN;
rbamp_read_voltage(dev, 0, &u);
rbamp_read_current(dev, 0, &i);
rbamp_read_power(dev, 0, &p);
rbamp_read_power_factor(dev, 0, &pf);
ESP_LOGI(TAG, "U=%.1f V I=%.2f A P=%.1f W PF=%.2f",
(double)u, (double)i, (double)p, (double)pf);
vTaskDelay(pdMS_TO_TICKS(2000));
}
}
Numa carga puramente resistiva (lâmpada incandescente, chaleira elétrica, elemento de aquecimento) deve esperar:
U≈ 220–240 V (para uma rede de 230 V)I≈ corresponde à potência da carga (P / U)P> 0 e estávelPF≈ 1.0 (nitidamente positivo)
Se algo não bater certo, veja 10_troubleshooting.md.
Módulos com vários canais de corrente
Gama de SKUs — o que serve a tarefa
| SKU | Canais I | Canal-U | Utilização típica |
|---|---|---|---|
| UI1 | 1 | sim | Uma única carga com cálculo completo de potência (P, PF, Q, Wh) — o contador de rede típico |
| UI2 | 2 | sim | Duas cargas independentes numa fase com potência por canal (1 U + 2 I) |
| UI3 | 3 | sim | Três cargas numa fase com potência por canal (1 U + 3 I) |
| I1 | 1 | não | Submedidor sem cálculo de potência (apenas corrente) — quando a medição da rede é feita por um UI1 separado |
| I2 | 2 | não | Subcontador de corrente de dois canais — repartição por circuito |
| I3 | 3 | não | Subcontador de corrente de três canais — repartição por circuito / topologia de duplo TC |
O que mede cada canal
- Canal U (apenas UI): U_rms, U_peak, frequência. Um* por módulo (ligado à fase de entrada).
- I-channels:
- em variantes UI — cada canal fornece I_rms, I_pico, P (potência ativa), PF, avg_p sobre o período.
- nas variantes I — apenas corrente (I_rms, I_peak). A potência ativa e o PF não são calculados — exigem tensão, que a variante I não tem. Os registos
power[]/power_factor[]nas variantes I devolvem 0. - Multifásico vs multiponto: o módulo NÃO distingue a que fase está ligado cada canal I. Essa semântica fica do lado do master.
Modelo de TC por canal — calibração independente por canal
Nos módulos multicanal (I2, I3) cada canal de corrente tem uma escolha independente de modelo SCT-013. Pode ligar, por exemplo, um SCT-013-005 ao canal 0 (uma única tomada), um SCT-013-030 ao canal 1 (a linha do fogão elétrico) e um SCT-013-020 ao canal 2 (um esquentador ou caldeira).
A API para a seleção por canal é rbamp_set_ct_model_ch(dev, channel, code):
rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013); /* once for all */
/* v1.3: channel binding order is arbitrary. */
rbamp_set_ct_model_ch(dev, 0, 1); /* channel 0: SCT-013-005 */
rbamp_set_ct_model_ch(dev, 1, 3); /* channel 1: SCT-013-030 */
rbamp_set_ct_model_ch(dev, 2, 6); /* channel 2: SCT-013-020 */
✅ A ordem de associação é arbitrária (canónico v1.3). Escrever REG_CT_MODEL (0x05) prepara o valor mas não o aplica automaticamente a nenhum canal. A aplicação faz-se apenas através de CMD_SET_CT_MODEL_CHn por canal, que pega no valor preparado atual e o escreve no seu próprio canal. Os canais podem ser configurados em qualquer ordem (ch0 primeiro, por último, intercalados — não faz diferença); não há sobreposições. Qualquer referência a "ascendente / descendente / associar ch0 por último" em documentos e código mais antigos refere-se ao comportamento anterior à v1.3 — pode ser removida.
Cada canal é associado em dois passos: (1) escrever o modelo em REG_CT_MODEL (preparação), (2) CMD_SET_CT_MODEL_CHn (associação). A validação (classe, modelo) é feita pelo firmware no passo de associação.
Se vários canais receberem o mesmo modelo, pode chamar com o mesmo código — a aplicação repetida é idempotente:
rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013);
rbamp_set_ct_model_ch(dev, 0, 1);
rbamp_set_ct_model_ch(dev, 1, 1);
rbamp_set_ct_model_ch(dev, 2, 1);
Uma alternativa para o caso típico I2/I3 é rbamp_configure_channels(dev, class, models[], n): uma única operação configura a classe + todos os canais + grava tudo na flash com um CMD_SAVE_USER_CONFIG final (amigável para a flash — um ciclo de apagamento em vez de N). Veja o capítulo 09 · Referência da API, secção "Configuração multicanal".
A forma de um só parâmetro rbamp_set_ct_model(dev, code) é uma forma de conveniência para SKUs de canal único (aplicada ao canal 0). Em módulos multicanal é equivalente a rbamp_set_ct_model_ch(dev, 0, code).
Configuração avançada: duas pinças de calibres diferentes num só fio
⚙ Um padrão adicional, não um básico. Esta secção descreve uma técnica opcional para melhorar a resolução a correntes baixas. Para a maioria das instalações, uma única pinça dimensionada para a gama de carga é suficiente. Use CT duplo apenas se tiver um requisito específico de precisão para correntes < 1 A.
Quando se aplica
- Módulos multicanal I2 / I3 (hardware atual).
-
O mesmo fio tem de ser medido tanto para cargas pequenas (≤ 1 A) como para eventos de pico (≥ 5 A) com a mesma qualidade.
-
Um exemplo típico: a entrada de serviço de um apartamento, onde há 50–100 W de stand-by durante o dia e a corrente de arranque de uma chaleira ou fogão elétrico de 3+ kW à noite.
A ideia
Duas pinças SCT-013 de classificações diferentes instaladas no mesmo fio:
-
Canal 0 — a pinça pequena (p. ex. SCT-013-005, 5 A): vê correntes pequenas com melhor resolução e um patamar de ruído mais baixo.
-
Canal 1 — a pinça grande (p. ex. SCT-013-030 ou superior): suporta correntes acima do ponto de sobrecarga da pinça pequena sem saturar.
O próprio master escolhe o canal a usar consoante o valor da corrente — enquanto a pinça pequena está na sua zona linear, a leitura é mais precisa; quando é excedida, passa para a grande.
Configuração
A classe do sensor uma vez, depois os modelos por canal em qualquer ordem (v1.3 pura preparação, a ordem não importa):
rbamp_set_sensor_class(dev, RBAMP_SENSOR_SCT013); /* once */
rbamp_set_ct_model_ch(dev, 0, 1); /* ch0 = SCT-013-005 (0..5 A) — small clamp */
rbamp_set_ct_model_ch(dev, 1, 3); /* ch1 = SCT-013-030 (0..30 A) — large clamp */
Estado final: ch0 = SCT-013-005, ch1 = SCT-013-030. ✓
Uma alternativa através de rbamp_configure_channels() — uma operação em vez de duas:
uint8_t models[2] = { 1, 3 }; /* ch0=5A, ch1=30A */
rbamp_configure_channels(dev, RBAMP_SENSOR_SCT013, models, 2);
Lógica de agregação do lado do mestre
O modelo mais simples é ligar com um limiar:
float read_combined_current(rbamp_handle_t dev) {
float i_low = NAN;
float i_high = NAN;
esp_err_t err_low = rbamp_read_current(dev, 0, &i_low); /* small */
esp_err_t err_high = rbamp_read_current(dev, 1, &i_high); /* large */
/* While the small clamp is far from saturation, it gives better
* accuracy at small currents. Switch to the large one as it
* approaches the overload point.
*
* The 4.5 A threshold for the SCT-013-005 is an example value;
* figures for low-current dual-CT use are not published. */
if (err_low == ESP_OK && i_low < 4.5f) {
return i_low;
}
return (err_high == ESP_OK) ? i_high : NAN;
}
Duas pinças no mesmo fio são fisicamente possíveis na maioria dos cabos de calibre doméstico, mas exigem algum espaço no quadro.
⚙ Valores de CT duplo. Os valores para o uso de CT duplo a correntes baixas (comportamento perto do limiar, divergência das duas pinças na gama sobreposta) não são publicados. Trate o CT duplo como um padrão-piloto; em aplicações críticas, é preferível uma única pinça dimensionada para a gama superior de carga.
Módulos multicanal — I2 e I3 (apenas corrente)
Os módulos só de corrente para a topologia multicanal são o I2 (dois canais de corrente) e o I3 (três canais de corrente). Ambos os módulos não têm canal U, por isso o cálculo de P / PF / Q no lado do módulo é impossível — fornecem corrente por canal (I_rms, I_peak em cada canal) e mais nada.
UI2 e UI3 acrescentam o canal U (1 U + 2 I / 1 U + 3 I), por isso a potência por canal é calculada no módulo. Quando só é preciso uma decomposição de corrente, use I2/I3 como sub-medidores de corrente juntamente com um UI1 separado na entrada de serviço, que fornece a energia da rede + tensão.
Leitura de canais (I2 / I3)
float i0, i1, i2;
rbamp_read_current(dev, 0, &i0); /* ch0 */
rbamp_read_current(dev, 1, &i1); /* ch1 */
rbamp_read_current(dev, 2, &i2); /* ch2 — I3 only */
/* On an I variant rbamp_read_power(...) returns 0 — this is by design. */
float p_dummy; rbamp_read_power(dev, 0, &p_dummy); /* = 0.0f */
Se precisar de potência ativa em cada linha secundária, coloque um UI1 na entrada de serviço e divida a sua potência total proporcionalmente à corrente de cada canal I[k] dos I2/I3. Esta é a implementação doméstica típica:
/* Pseudo-pattern: UI1 on mains, I3 on 3 sub-lines */
float p_mains_total, i0, i1, i2;
rbamp_read_power(mains_ui1, 0, &p_mains_total);
rbamp_read_current(loads_i3, 0, &i0);
rbamp_read_current(loads_i3, 1, &i1);
rbamp_read_current(loads_i3, 2, &i2);
float i_sum = i0 + i1 + i2;
if (i_sum > 0.01f) {
float p0 = p_mains_total * i0 / i_sum; /* approximation */
/* ... */
}
Esta é uma aproximação: dividir por corrente funciona quando o fator de potência é aproximadamente o mesmo em todas as cargas. Para uma contabilização precisa da potência por carga, use uma variante UI (UI1 / UI2 / UI3 / UI5 / UI7) em cada linha.
Aplicações de I2 / I3
-
Submedição de corrente: repartição da corrente por circuito, um ponto de instalação no quadro em vez de um módulo separado por linha.
-
Desagregação em conjunto com um UI1: o UI1 fornece a energia / potência da rede, e os I2/I3 decompõem o consumo por ramal (ver capítulo 06, cenário 1).
-
Monitorização de corrente sem contabilização de potência: controlo de sobrecarga, deteção de ligar/desligar carga, o perfil I(t).
-
CT duplo + um terceiro canal (I3): uma pinça grande no canal 0 para uma gama ampla, uma pequena no canal 1 para precisão com correntes baixas, o terceiro canal para uma linha auxiliar separada. Veja a secção "Configuração avançada: duas pinças de calibres diferentes" acima.
Cálculo de potência do lado do mestre:
float i;
rbamp_read_current(dev, ch, &i);
/* If the voltage is known (from a UI module upstream or fixed) */
const float U_nominal = 230.0f;
float p_estimated = U_nominal * i; /* without PF — guaranteed overestimate */
Para uma contabilização de potência precisa, use um módulo UI (com um canal U).
Abordagens para melhorar a sensibilidade com correntes baixas
Se a sua carga tiver uma grande gama dinâmica (p. ex. 1 W de stand-by de um router vs um esquentador de 2000 W na mesma tomada), uma única pinça dimensionada para o limite superior perde as correntes baixas no ruído.
Três estratégias, por ordem crescente de complexidade:
-
Dimensione a pinça para o máximo, não "com margem". O erro mais comum é colocar uma SCT-013-100 (100 A) numa tomada doméstica com um consumo típico de 0.5–10 A. O sinal está na parte inferior, entre 1 e 10 % da gama do sensor — onde o ruído se torna comparável ao sinal. Para o cenário doméstico (tomada de 16 A) a SCT-013-030 é a ideal; para ligar um único aparelho (≤ 5 A), a SCT-013-005.
-
Topologia dupla-TC (requer um SKU I2/I3 — dois canais de corrente num módulo): uma pinça pequena para o intervalo inferior + uma grande para o superior, com o master a selecionar por limiar. Veja a secção "Topologia dupla-TC" acima — o padrão é um piloto; os valores para uso de baixa corrente em dupla-TC não estão publicados.
-
Patamar de ruído (lado da fábrica): a calibração do módulo já o contempla. Do lado do utilizador, não é preciso fazer nada além de
setSensorClass()+setCTModel(). Não são publicados valores concretos de precisão a correntes baixas.
Modo de produção vs. modo de fábrica (referência de persistência)
O módulo rbAmp funciona em dois modos que diferem em exatamente o que é guardado na flash. O modo atual é lido do registo de estado do módulo correspondente.
| Comando (opcode) | Produção | Persiste |
|---|---|---|
CMD_SAVE_USER_CONFIG (0x32) |
✅ OK | ct_model / sensor_class / fleet_config / group_id / label |
CMD_COMMIT_ADDR (0x30, armado por magic) |
✅ OK | Endereço I²C (ver 04 · Ligação — alteração do endereço) |
CMD_RESET (0x01) |
✅ OK | — (reinício por software) |
CMD_LATCH_PERIOD (0x27) |
✅ OK | — (instantâneo de período) |
CMD_CLEAR_ERROR |
✅ OK | — |
CMD_SAVE_GAINS |
❌ BLOQUEADO em produção (devolve ERR_PARAM) | ganhos / NF / fase (calibração de fábrica) |
CMD_FACTORY_RESET |
❌ BLOQUEADO em produção | — |
No modo de produção, as escritas da calibração de fábrica (CMD_SAVE_GAINS, CMD_FACTORY_RESET) são rejeitadas pelo firmware — isto protege contra o apagamento acidental dos coeficientes de fábrica. Colocar o modo de fábrica é uma operação do fabricante; os utilizadores finais não precisam dela.
A proteção de produção aceita uma escrita na RAM (uma leitura posterior devolve o valor escrito), mas a gravação na flash pode ser rejeitada. Após um reinício o valor reverte ao estado anterior à escrita. A única forma válida de confirmar a persistência é reiniciar o módulo via CMD_RESET e ler de novo:
rbamp_set_ct_model(dev, code);
rbamp_reset(dev); // CMD_RESET 0x01, works in production
vTaskDelay(pdMS_TO_TICKS(400)); // boot complete
uint8_t check; rbamp_read_ct_model(dev, 0, ✓);
assert(check == code); // ONLY now is persistence confirmed
Referência cruzada: 09 · Referência da API — detalhes sobre opcodes específicos; 10 · Diagnóstico — o que fazer se a persistência não for confirmada.
O que vem a seguir
-
04 · Ligação — ligação física da pinça, orientação da seta, polaridade L/N
-
05 · Arranque rápido — o projeto completo de primeira luz
-
06 · Exemplos — cenários de funcionamento para diferentes cargas
-
10 · Diagnóstico — o que fazer se as leituras forem estranhas (PF negativo, I instável, etc.)
Fonte e problemas: rb-amp/rbamp-esp-idf · esta página no repositório: docs/03_sensor_selection.md (v1.7.3)