03 · Selección del sensor de corriente
rbAmp mide la corriente mediante una pinza de CT externa (transformador de corriente) y la tensión mediante un transformador de tensión integrado (en los SKU UI*). Este capítulo explica cómo elegir la pinza para su carga y cómo indicar al módulo, mediante YAML, qué modelo está instalado.
Familia del sensor (sensor_class:)
La revisión de hardware del módulo determina qué familia de sensores de corriente es compatible. En los SKU actuales solo hay una disponible:
| Clase | Valor YAML | Estado |
|---|---|---|
| SCT-013 (CT de núcleo partido) | SCT_013 |
Disponible ahora, por defecto |
| WIRED_CT (módulo con su propia CT cableada ajustada) | WIRED_CT |
Emparejado de fábrica: calibrado junto con su sensor |
| BUILTIN_CT (módulo con sensor integrado) | BUILTIN_CT |
Emparejado de fábrica: calibrado junto con su sensor |
La clase se fija una sola vez y se guarda en la flash del módulo:
rbamp:
id: meter1
sensor_class: SCT_013 # defaults to SCT_013, can be omitted
En firmware v1.2 o posterior, este valor se convierte en requisito previo para escribir el modelo de CT: el módulo rechazará la escritura si no se ha definido la clase. El componente nunca escribe una clase que el módulo ya tiene.
Guardas de escritura: lectura-comparación-escritura (v1.3+) y protección de fábrica (v1.8.1+)
Al arrancar el componente lee la clase de sensor actual del módulo y la compara con el valor solicitado en el YAML. Si coinciden, no se produce la escritura en flash (una escritura de clase en el módulo también borraría los modelos de canal, así que un valor sin cambios nunca se reescribe). Esto significa que:
-
El bloque YAML puede conservar
sensor_class: SCT_013indefinidamente: un reinicio posterior no provoca un borrado de flash (~0 ms en lugar de ~700 ms). -
El consejo antiguo de «eliminar
sensor_class:del YAML tras el primer arranque» ya no es válido: la configuración es idempotente.
El mismo comportamiento se aplica a ct_model: / ct_models: (vea más abajo).
Módulos emparejados de fábrica (WIRED_CT / BUILTIN_CT). Un módulo suministrado junto con su propio sensor ajustado se calibra como pareja con ese sensor. El componente protege esa calibración: un cambio de sensor_class: o ct_model: desde el YAML en un módulo así se rechaza con una línea de log explícita (la escritura sustituiría la calibración individual por un ajuste genérico). Deje ambas claves fuera del YAML para estos módulos. Para pinzas SCT-013 (SCT_013, el valor por defecto) las claves funcionan como se describe más abajo.
Elegir el modelo SCT-013
El módulo acepta cualquiera de los siete modelos de la serie SCT-013. Su salida eléctrica difiere, así que el módulo necesita saber cuál está instalado: los coeficientes de fábrica se cargan para el modelo concreto.
¿Qué modelo tengo? Lea la potencia nominal en la etiqueta del cuerpo de la pinza: SCT-013-030 significa 30 A, así que escriba ct_model: SCT_013_030. Use el modelo cuya potencia nominal coincida con la etiqueta, no el que «parezca más cercano» a su carga.
| Código | Nombre en YAML | Corriente nominal | Carga típica | Máximo a 230 V | estado v1.3 |
|---|---|---|---|---|---|
| 1 | SCT_013_005 |
5 A | Iluminación LED, aparatos individuales, portátiles | ~1.15 kW | producción |
| 2 | SCT_013_010 |
10 A | PC de sobremesa, pequeño equipo de aire acondicionado, circuito único | ~2.3 kW | producción |
| 6 | SCT_013_020 |
20 A | Calentadores de agua, ramales medios, ~3-5 kW | ~4.6 kW | producción |
| 3 | SCT_013_030 |
30 A | Medición de toda la vivienda con un consumo típico | ~6.9 kW | producción (SKU predeterminado) |
| 4 | SCT_013_050 |
50 A | Carga de vehículo eléctrico, equipo de aire acondicionado grande, placa de inducción | ~11.5 kW | producción |
| 7 | SCT_013_060 |
60 A | Submedidor industrial, ramales grandes | ~13.8 kW | producción |
| 5 | SCT_013_100 |
100 A | Entrada principal de servicio, alimentaciones grandes | ~23 kW | producción |
SCT_013_060 (60 A) y SCT_013_100 (100 A) se aceptan; elija la pinza cuya potencia nominal se ajuste a su corriente máxima.
La resistencia de carga ya está instalada en la placa del módulo: no hace falta añadir resistencias externas entre los cables de salida de la pinza.
Árbol de selección
Regla general: elija la pinza con la potencia nominal más baja cuyo valor máximo medible cubra la carga máxima con un margen de ~30 %. Una potencia nominal sobredimensionada para una carga pequeña reduce la amplitud de la señal frente al ruido: la precisión cae. Una pinza con potencia nominal inferior al pico saturará el núcleo magnético y dará lecturas muy erróneas.
Validación de CT por clase (nuevo en v1.3)
El validador del esquema _validate_ct_model_per_class rechaza las combinaciones no válidas de sensor_class: × ct_model: en la fase esphome config, antes de la grabación y el arranque. Los conjuntos permitidos no son contiguos: es un canon explícito, no un error:
| sensor_class | Códigos permitidos | Nombres YAML | Comportamiento ante una discrepancia |
|---|---|---|---|
SCT_013 |
{1, 2, 3, 4, 5, 6, 7} | SCT_013_005/010/030/050/100/020/060 |
cv.Invalid con una pista |
WIRED_CT |
{1–10, 12} | WIRED_CT_ |
cv.Invalid |
BUILTIN_CT |
{} (ninguno) | — | cv.Invalid (se rechaza cualquier ct_model) |
UNSET |
{} | — | cv.Invalid (clase no definida) |
Specifically:
-
SCT_013no contiguo: los códigos aceptados son{1, 2, 3, 4, 5, 6, 7}(SCT_013_005,_010,_030,_050,_100,_020,_060); el orden de los códigos no es el orden de los rangos. -
WIRED_CTes la clase de módulos suministrados con su propia CT cableada; el esquema acepta los códigos 1/2/3 para ella. El módulo está calibrado de fábrica con ese sensor, así que el componente se niega a cambiar la clase o el modelo (vea la nota de emparejado de fábrica más arriba). -
BUILTIN_CTes la clase de los módulos con sensor integrado;ct_model:no es necesario ni lo acepta el esquema. DeclararBUILTIN_CTsin el hardware correspondiente no tiene sentido.
Si el YAML se cuela por el validador (esquema antiguo + firmware nuevo, anulación manual), el firmware devuelve REG_ERROR = 0xFE DEV_ERR_PARAM: el módulo no escribirá un código no soportado; devuelve DEV_ERR_PARAM y los espejos se quedan con el valor anterior.
Cómo identificar el módulo
Hay dos claves en el YAML: elige una de las dos según tenga la misma pinza en todos los canales o pinzas distintas. La transición sintáctica va de un valor escalar a una lista YAML (array):
Paso 1: una pinza para todos los canales (ct_model:, escalar)
Si tiene una UI1 (un canal de corriente) o una UI3 con pinzas idénticas en los tres canales, una sola línea:
rbamp:
id: meter1
ct_model: SCT_013_030 # ← scalar value, one model for all channels
Es el caso más habitual. La mayoría de las instalaciones empiezan con un único modelo de pinza y nunca pasan de este nivel.
Paso 2: distintas pinzas en distintos canales (ct_models:, lista)
Si tiene un UI2 / UI3 y quiere poner pinzas distintas en los canales (por ejemplo, una pequeña en una línea de modo en espera y una grande en la acometida) — sustituya ct_model: por ct_models: (con una s final) y use una lista YAML entre corchetes:
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.
Aquí es donde más se equivoca la gente al modificar sistemas multicanal. Recuerde: ct_model: (sin s) es un valor escalar para un único modelo; ct_models: (con s) es una lista de valores entre corchetes, uno por canal. Solo se aplican tantas entradas como canales tenga el módulo (1 para UI1, 2 para UI2, 3 para UI3); las entradas adicionales se ignoran con una advertencia.
Los modelos por canal solo los guardan los módulos que los conservan tras un corte de alimentación. Si el módulo conectado no los conserva, el componente lo rechaza de forma explícita (advertencia, claves ignoradas) en lugar de escribir un valor que se revertiría en silencio: use aquí el ct_model: único.
⚠ Mutuamente excluyentes. Declarar a la vez ct_model: Y ct_models: es un error de validación del esquema (cv.Invalid). Use solo una de las dos.
Instalación UI3 con pinzas de distinto tamaño
El escenario canónico para una vivienda con generación propia o con tipos de carga mixtos:
- Canal 0: consumidores pequeños (iluminación LED, modo en espera, electrónica). Una pinza SCT_013_005 (5 A) da la máxima resolución a corriente baja.
- Canal 1: cargas principales (vitrocerámica, calentador de agua). Una pinza SCT_013_030 (30 A) cubre el pico doméstico típico.
- Canal 2 — un ramal de potencia media (calentador de agua, ~3-5 kW). Una pinza SCT_013_020 (20 A) es el punto óptimo entre precisión y margen para un submedidor típico.
En un único bloque YAML rbamp: basta con 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
El propio componente asigna el modelo exacto a cada canal al arrancar.
Qué hace la clave por dentro
En firmware v1.2+, escribir ct_model: / ct_models: carga de forma atómica los coeficientes de fábrica (suelo de ruido y ganancia) del modelo elegido en la RAM del módulo y los guarda en flash. No hacen falta pasos de calibración adicionales por parte del usuario: el módulo sale de fábrica con todas las tablas de coeficientes necesarias.
En firmware anterior el valor se guarda como marcador de modelo.
Lectura-comparación-escritura (v1.3+) — por qué el arranque ahora es «instantáneo»
Al arrancar, el componente v1.3 lee los REG_CT_MODEL_CH0/1/2 actuales (reflejan 0x51-0x53) y los compara con los valores pedidos en el YAML. Si coinciden, la escritura en flash se omite por completo.
| Escenario de arranque | v0.4.0 (siempre escribe) | v1.3 (lectura-comparación-escritura) |
|---|---|---|
| Configuración ya aplicada (las copias coinciden) | ~700 ms × N canales de borrado de flash | 0 ms (solo lectura de confirmación por I²C) |
| Configuración cambiada (un modelo) | ~700 ms | ~700 ms (solo delta) |
| UI3 con tres modelos distintos (instalación en frío) | ~2.8 s de apagón | ~2.1 s (3 × 700 ms + verificación) |
| UI3 con los mismos modelos (arranque en caliente) | ~2.8 s de apagón cada vez | ~0 ms |
En la práctica: mantenga ct_model: / ct_models: en el YAML de forma permanente: la configuración es idempotente y no desgastará la memoria flash en arranques repetidos.
Cambiar la potencia nominal de la SCT mantiene la precisión
En un módulo STD ct_model es solo una etiqueta y no fija ninguna ganancia. El resto de esta sección describe los módulos BASIC.
Cada módulo SCT se calibra de fábrica con el SCT-013-030. Cuando selecciona otra potencia nominal (ct_model: SCT_013_010, por ejemplo), la corriente, la potencia y la energía siguen siendo precisas: se conserva la calibración unitaria de fábrica:
-
En firmware de módulo hasta la 1.4.19, el componente completa la escritura del modelo con el reinicio del módulo que exige el procedimiento (guardar, reiniciar, volver a identificar) y escala la corriente, la potencia activa y reactiva y la energía al sensor seleccionado a partir de la ganancia que el módulo aplica realmente. El reinicio aparece en el registro y es normal; los sensores pueden saltarse un ciclo. Un reinicio posterior del módulo (propio o externo) se detecta y el escalado se recalcula automáticamente.
-
En firmware más reciente (1.4.20+) el propio módulo realiza el cambio; el componente lo detecta y deja las lecturas sin tocar (escritura de modelo simple, sin reinicio).
-
La tensión y el factor de potencia no se ven afectados.
- Si la ganancia que aplica el módulo difiere del valor esperado en más de ±5 %, el componente registra una advertencia y no escala.
No hace falta cambiar el YAML para nada de esto.
Vinculación multicanal
El componente vincula los canales uno a uno; el orden no importa. Los modelos mezclados en un módulo (por ejemplo los códigos [1, 3, 6] en un módulo de tres canales) se conservan cada uno en su propio canal.
El propio componente alimenta el watchdog (App.feed_wdt()) durante cada ventana de escritura en flash; el presupuesto típico de setup() de ESPHome de 15 s no se supera ni siquiera en una instalación en frío de UI3.
Verificación de la instalación
Tras el primer arranque, compruebe las lecturas con una carga puramente resistiva: una bombilla incandescente, un hervidor, una resistencia calefactora. Una carga resistiva da una forma de señal conocida:
- El factor de potencia (
power_factor) debe estar cerca de 1.00 (de forma estable > 0.95). - La potencia activa (
power) debe ser positiva y estable. - La corriente RMS (
current) debe coincidir conP / Ucon una precisión razonable.
Si las lecturas no cuadran:
currentconstantemente ~0 con la carga en marcha → revise la polaridad y que la pinza rodee un único conductor (véase más abajo)powernegativa de forma constante → invierta la pinza en el conductor (la flecha en sentido contrario)power_factor~0.5..0.7 en una bombilla incandescente → puede haber una carga reactiva cerca o la pinza puede estar mal instalada
El diagnóstico orientado a síntomas detallado está en 10_troubleshooting.md.
Polaridad de la pinza de CT
El cuerpo de la pinza lleva una flecha que indica el sentido de la energía «normal» (consumo, hacia la carga). Con una instalación correcta (la flecha apuntando en el sentido de la corriente hacia la carga):
P_real > 0: consumo.P_real < 0: exportación (solo STANDARD (STD)).
Si la potencia activa es negativa con una carga en marcha, dé la vuelta físicamente a la pinza sobre el conductor. No corrija la polaridad por software: enmascara errores de dirección en las automatizaciones posteriores.
La pinza debe cerrarse por completo alrededor de un único conductor. No pase L y N por la misma pinza: sus campos magnéticos se cancelan y el sensor leerá cerca de cero.
Canal de tensión
Los SKU UI* incluyen un transformador de tensión integrado. El devanado primario se conecta a L y N de la red a través de los bloques de terminales del módulo, y el módulo lo mide internamente.
La configuración de fábrica del transformador está fijada por la revisión de la placa: el usuario no tiene nada que configurar. El sensor voltage funciona de inmediato.
Los SKU solo de corriente (I1 / I2 / I3) no tienen canal de tensión. La ranura voltage devuelve 0 en ellos y no debe declararse junto con power: o energy: (el validador del esquema comprueba esta dependencia).
Módulos multicanal
En UI2 / UI3 cada canal es un circuito de medida independiente y separado, no un núcleo magnético compartido. Esto le permite:
- Ponga un único modelo de CT en todos los canales (
ct_model:): la configuración típica para cargas uniformes. - Asigne distintos modelos a distintos canales (
ct_models:) para optimizar la precisión en instalaciones mixtas (véase arriba). - Dedique un canal al consumo y otro a la inyección solar: la polaridad de cada canal se fija de forma independiente según el sentido físico de la pinza.
Qué sigue
- 04_hardware.md: cableado físico, selección de GPIO, el bus de varios módulos
- 05_quickstart.md — primera ejecución en 5 minutos con una pinza ya configurada
- 10_troubleshooting.md — diagnóstico de instalación por síntomas
Fuente e incidencias: rb-amp/rbamp-esphome · esta página en el repositorio: docs/03_sensor_selection.md (v1.9.1)