Referencia del protocolo de cable rbAmp (v1.3)
rbAmp es un módulo compacto para medir parámetros de red de corriente alterna por interfaz I²C. El módulo se comporta como un esclavo I²C estándar con un mapa de registros fijo (página 0, 0x00..0xFF). Este documento describe el protocolo de cable a nivel de registros, comandos y secuencias.
: integradores de terceros y avanzados que escriben sus propios drivers I²C para el módulo rbAmp sin usar bibliotecas cliente (Arduino / ESP-IDF / Python / ESPHome).
Alcance: protocolo de hilos canónico del módulo rbAmp en la versión v1.3: mapa de registros, secuencias de protocolo, garantías de comportamiento. Es la documentación de referencia completa a nivel de contrato de hilos.
Versión: "v1.3" es la versión del protocolo de hilos (el registro VERSION 0x03 devuelve 0x04), no la versión de este documento. Es el protocolo de todo el firmware actual de módulos BASIC (1.4.x); los módulos STANDARD (STD) usan un mapa de registros distinto: vea la referencia técnica de STD.
NO incluido en el alcance: integración con una biblioteca, sistema operativo o framework concreto; consulte la documentación de esa biblioteca.
1 · Introducción
1.1 Gama de SKU
Las variantes del módulo (SCT-UI1 … SCT-I3, con sus canales de tensión y de corriente) se listan en overview.md → Variantes del módulo.
Las variantes I (I1/I2/I3) no tienen hardware de tensión: los registros U_RMS, U_PEAK y P devuelven 0.0. La frecuencia (AC_FREQ) está disponible en todas las variantes (con origen en cruce por cero).
La calibración es de fábrica. El maestro del consumidor NO configura el suelo de ruido (NF), la ganancia, la compensación de fase ni ningún otro parámetro de fábrica: todos ellos son calibración de fábrica grabada en el módulo (véase §4.0, rangos reservados). En los módulos BASIC de la serie SCT (usados con sensores SCT-013) el usuario escribe solo SENSOR_CLASS + CT_MODEL (véase §6.2); el módulo aplica todo lo demás automáticamente desde la tabla de presets. Los módulos BASIC de la serie CT y los STANDARD (STD) se suministran emparejados con sus sensores, preconfigurados y calibrados de fábrica: no se escribe nada.
1.2 Versionado
| Campo | Valor |
|---|---|
protocol_version |
1.3 |
schema_version |
2 |
Registro VERSION (0x03) |
0x04 para la v1.3 |
| Contrato de la página 0 | congelado en la publicación de la v1.3 |
2 · Conceptos básicos del protocolo de bus
2.0 Potencia y alimentación
| Parámetro | Valor |
|---|---|
VCC nominal |
+5 V |
Rango de VCC |
4.5..5.5 V |
| Consumo de corriente típico | ~15 mA |
| Consumo de corriente máximo (instantánea + escritura en flash) | ~25 mA |
| Corriente de irrupción al arrancar | ≤ 50 mA a 5 ms |
| Secuencia | VCC puede aplicarse simultáneamente con I²C; las pull-ups (3.3 V) se permiten antes de aplicar VCC |
| Aislamiento | el módulo es todo de baja tensión: la pinza se acopla magnéticamente y la toma de tensión de UI está aislada galvánicamente |
Cuatro cables son obligatorios en el lado de baja tensión: VCC, GND, SDA, SCL. DRDY (drenador abierto) es opcional. Véase §2.3 para las pull-ups y la guía con varios módulos.
2.1 Parámetros I²C
- Dirección por defecto:
0x50(7 bits). - Rango de direcciones permitido:
0x08..0x77(límites reservados estándar de I²C). - Niveles lógicos: 3.3 V (tolerante a 5 V en las pull-ups a 3.3 V).
- Pull-ups de la placa: 4.7 kΩ en SDA/SCL a 3.3 V (módulo).
- Estiramiento de reloj: el módulo NO usa el estiramiento de SCL como mecanismo rutinario de control de flujo. Entre transacciones el master debe respetar un hueco entre transacciones ≥ 100 µs (
tBUF). Las transacciones seguidas sin hueco (START repetido sintBUF) están permitidas pero se desaconsejan: algunas pilas de host (i2c_master de ESP-IDF) muestran una tasa de NACK elevada. Vea la sección §5 de aceptación y EMI por separado.
2.2 Velocidad del bus
| Velocidad | Aplicabilidad | Nota |
|---|---|---|
| 50 kHz | recomendado en masters ESP32 y ESP8266 | El driver I²C de ESP-IDF muestra una tasa de NACK de ~20 % a 100 kHz: es una limitación del driver del host, no del módulo; 50 kHz + 3 reintentos da una tasa de error < 0.8 %. |
| 100 kHz | recomendado en otros masters | también viable en ESP32/ESP8266 con reintento 3× a nivel de aplicación. |
| 400 kHz | no recomendado | la velocidad es elección del usuario. |
2.3 Bus de varios módulos
Varios módulos rbAmp pueden compartir un mismo bus:
- Hasta ~16 módulos (limitado por la capacitancia total del bus ≤ 400 pF a 100 kHz).
- Pull-ups: con 2–3 módulos en un bus de hasta 15 cm, deje las pull-up de la placa como están; con cuatro o más, o en un bus más largo, las pull-up de 4.7 kΩ en paralelo sobrecargan el sumidero. Corte las pull-up de la placa en todos los módulos excepto uno (o use un buffer I²C PCA9515/9615).
- Longitud: hasta 0.15 m con cable simple → 100 kHz; 0.15–1 m con par trenzado (SDA+GND y SCL+GND en pares separados) → 100 kHz; > 1 m: buffer I²C; > 3 m: bus diferencial (PCA9615 / LTC4332).
2.4 Presupuesto de sondeo del bus
A 50 kHz, una transacción de lectura de un registro dura ≈ 200–400 µs. El bloque RT completo de un canal (U + I + P + PF, 4 floats = 16 bytes en ráfaga) dura ≈ 5–8 ms por canal.
| Configuración | Bus por ciclo | Frecuencia máxima de sondeo |
|---|---|---|
| 1× UI1, bloque RT | ~5 ms | 100+ Hz (pero el módulo actualiza a 10 Hz) |
| 5× UI1, bloque RT | ~25 ms | 10 Hz |
| 16× I3, RT + período | ~400 ms | no puede seguir el ritmo: lee aproximadamente cada 4.ª ventana de 100 ms |
Regla práctica: a 50 kHz los límites cómodos son 8–10× I3 o 15–16× UI1 al sondear cada dos ventanas (5 Hz); divida el número de módulos a la mitad para sondear cada ventana (10 Hz).
3 · Modelo de variantes
3.1 HW_VARIANT (registro 0x55, u8, solo lectura)
Byte de SKU de referencia:
| Valor | SKU | N_I | Hardware de tensión |
|---|---|---|---|
0x01 |
UI1 | 1 | sí |
0x02 |
UI2 | 2 | sí |
0x03 |
UI3 | 3 | sí |
0x04 |
I1 | 1 | no |
0x05 |
I2 | 2 | no |
0x06 |
I3 | 3 | no |
0x07 |
UI5 | 5 | sí |
0x08 |
UI7 | 7 | sí |
Cualquier otro valor → el dispositivo no se identifica como rbAmp.
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::readVariant() |
lea la variante de hardware (SKU) |
| ESP-IDF | rbamp_read_variant() |
lea la variante de hardware (SKU) |
| Python | dev.read_variant() |
lea la variante de hardware (SKU) |
| ESPHome | get_variant_str() |
lea la variante de hardware (SKU) |
3.2 CAPABILITY (registros 0x57/0x58, u16 LE, solo lectura)
Mapa de bits de detección de funciones. Es la forma canónica de detectar las funciones soportadas, sin comparar números de versión.
| bit | Indicador | Significado |
|---|---|---|
| 0 | EXT_ADDRESSING | direccionamiento extendido de 16 bits (prefijo 0xFF) |
| 1 | GC_LATCH | Se admite la instantánea por llamada general |
| 2 | GC_GROUP_FILTER | el filtro GROUP_ID está activo |
| 3 | DIGEST | el bloque de resumen (0x70..0x85) está expuesto |
| 4 | EVENTS | EVENT_FLAGS está soportado |
| 5 | UID_ARBITRATION | Arbitraje de direcciones basado en UID (sin comandos públicos) |
| 6 | SEAL | reservado: no implementado |
| 7 | TWO_PHASE_ADDR | cambio de dirección con commit en dos fases |
| 8 | ZC_PHASE_OFFSET = hardware de tensión | el módulo tiene un canal U |
| 9 | SAVE_USER_CONFIG | CMD_SAVE_USER_CONFIG está disponible |
| 10 | CLEAR_ERROR | CMD_CLEAR_ERROR está disponible |
| 11 | IAP | programación en aplicación (solo niveles F4) |
| 12 | SCT_RATING_SELF | fw 1.4.20+: un cambio de modelo de SCT mantiene la calibración de la unidad y sobrevive a un reinicio; las bibliotecas omiten su propia corrección de potencia nominal |
3.2.1 Detección de funciones
Detecte cada función por su bit individual: nunca compare el registro completo con una constante esperada, porque el mapa de bits crece con el firmware (p. ej., el bit 12 apareció en el fw 1.4.20), y la comparación del valor completo falla en módulos más nuevos.
3.2.2 Disposición de bytes de CAPABILITY u16 LE
CAPABILITY ocupa 2 bytes en las direcciones 0x57 (byte bajo) y 0x58 (byte alto), little-endian:
register layout (byte-addressed):
0x57 0x58
┌──────┬──────┐
│ LO │ HI │
└──────┴──────┘
bits bits
0-7 8-15
full u16 = (read_u8(0x58) << 8) | read_u8(0x57)
Asignación de bits:
- el byte
0x57(LO) contiene los bits 0..7: EXT_ADDRESSING, GC_LATCH, GC_GROUP_FILTER, DIGEST, EVENTS, UID_ARBITRATION, SEAL, TWO_PHASE_ADDR. - el byte
0x58(HI) contiene los bits 8..15: ZC_PHASE_OFFSET (= hardware de tensión), SAVE_USER_CONFIG, CLEAR_ERROR, IAP, SCT_RATING_SELF (bit 12, fw 1.4.20+), bits 13-15 reservados.
3.2.3 Receta canónica de has_voltage
cap_hi = read_u8(0x58) # high byte holds bits 8..15
has_voltage = bool(cap_hi & 0x01) # bit 8 of the u16 = bit 0 of byte 0x58
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::readCapability(out) / RbAmp::hasVoltageHw() |
lea el mapa de funciones de 16 bits; compruebe si hay un canal de tensión |
| ESP-IDF | rbamp_read_capability() / rbamp_has_voltage() |
lea el mapa de funciones de 16 bits; compruebe si hay un canal de tensión |
| Python | dev.read_capability() / dev.has_voltage() |
lea el mapa de funciones de 16 bits; compruebe si hay un canal de tensión |
| ESPHome | get_capability_hex() |
lea el mapa de bits de capacidades |
3.3 Tabla de perfiles de variante: invariante
| SKU | HW_VARIANT (0x55) | N_I | hardware de tensión | bit 8 de CAPABILITY (hardware de tensión) |
|---|---|---|---|---|
| UI1 | 1 | 1 | sí | bit 8 a 1 |
| UI2 | 2 | 2 | sí | bit 8 a 1 |
| UI3 | 3 | 3 | sí | bit 8 a 1 |
| I1 | 4 | 1 | no | bit 8 a 0 |
| I2 | 5 | 2 | no | bit 8 a 0 |
| I3 | 6 | 3 | no | bit 8 a 0 |
| UI5 | 7 | 5 | sí | bit 8 a 1 |
| UI7 | 8 | 7 | sí | bit 8 a 1 |
Coherencia HW_VARIANT ⟷ CAPABILITY: HW_VARIANT 1..3 y 7..8 (UI) → bit 8 a 1; HW_VARIANT 4..6 (I) → bit 8 a 0. Una discrepancia indica una anomalía de hardware o de firmware (dispositivo defectuoso o grabación errónea).
3.4 SENSOR_CLASS ≠ discriminador de variante
⚠ SENSOR_CLASS (0x25) NO es un discriminador de variante. Es un registro de configuración de usuario (selector de clase de sensor CT: Unset/Sct013/WiredCT/BuiltinCT) y no refleja la variante de hardware. Para detectar la variante use solo HW_VARIANT (0x55) + CAPABILITY (0x57/0x58).
3.5 PRODUCT_ID (0x54, u8, solo lectura)
Discriminador de familia de producto:
| Valor | Familia |
|---|---|
0x01 |
sensor rbAmp (este documento) |
0x02 |
rbDimmer (mapa de registros distinto; no cubierto por este documento) |
El maestro DEBE leer PRODUCT_ID antes de interpretar cualquier registro específico de la familia.
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::readProductId() |
lea el byte del identificador de familia |
| ESP-IDF | rbamp_read_product_id() |
lea el byte del identificador de familia |
| Python | dev.read_product_id() |
lea el byte del identificador de familia |
| ESPHome | — | no expuesto |
3.6 Algoritmo de detección canónico
if not i2c_addr_acks(addr):
return NO_DEVICE
product = read_u8(addr, 0x54)
if product != 0x01:
return NOT_RBAMP_SENSOR
hw = read_u8(addr, 0x55)
if 1 <= hw <= 8:
cap_hi = read_u8(addr, 0x58)
has_voltage = bool(cap_hi & 0x01)
return {sku: SKU[hw], N_I: N_I_TABLE[hw], has_voltage: has_voltage}
return UNKNOWN_DEVICE
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::begin() / RbAmp::readVariant() |
sondee el módulo y detecte su línea; lea la variante |
| ESP-IDF | rbamp_begin() / rbamp_read_variant() |
sondee el módulo y detecte su línea; lea la variante |
| Python | dev.begin() / dev.read_variant() |
sondee el módulo y detecte su línea; lea la variante |
| ESPHome | rbamp: address: / get_variant_str() |
dirección del módulo establecida en YAML; la variante como texto |
4 · Mapa de registros (producción v1.3)
Filtro aplicado: build: production(excluidos los registros de compilación de calibración). Los registros de calibración de fábrica (NF, GAIN, PHASE) sonno documentado— pertenecen al banco de fábrica, no a la superficie de uso del consumidor.
4.0 Rangos reservados (internos)
Los siguientes rangos están reservados para uso interno o de fábrica y no se describen en este documento. Las lecturas devuelven datos sin relevancia para la lógica de consumidor o 0x00 en direcciones inexistentes (vea §5.2). Las escrituras en estas direcciones se descartan en silencio o se responden con ERR_PARAM:
0x04: indicador de modo interno (controlado de fábrica, no configurable por el consumidor).0x06,0x26: parámetros de calibración internos (banco de fábrica).0x08..0x0F: vista de depuración de la LUT (diagnóstico de fábrica).0x1B..0x1F: página 0 reservada (0x18..0x1Ason diagnóstico de producción, vea §4.2).0x36..0x3B,0x40..0x45: página 0 reservada (0x32+0x3C..0x3Fson la ventana de acceso por canal, véase §4.14).0x4F,0x50: reservados (prerreserva del bloque de identidad).0xE4..0xEB,0xF0..0xFF: calibración de fábrica (NF, GAIN); escrituras restringidas a fábrica.
Nota sobre 0xD0..0xE3: en la compilación de producción este rango lo ocupa el bloque V03 Q (véase §4.12). En el firmware de calibración aparte (no distribuido al consumidor) el mismo rango se superpone con el bloque de calibración (build:cal). El maestro del consumidor ve solo la superposición de producción: el bloque Q.
Los integradores de 3.ª parte deben ignorar estos rangos.
4.1 Bloque de control (0x00..0x07)
| Dir. | Nombre | Tamaño | Tipo | Acceso | Persistencia | Notas |
|---|---|---|---|---|---|---|
0x00 |
STATUS |
1 | u8 | r | ram | bit0=LISTO, bit1=ERROR (espejo de REG_ERROR != 0), bit2=EVENTOS_PENDIENTES (espejo de EVENT_FLAGS != 0) |
0x01 |
COMMAND |
1 | u8 | w | ram | Escriba un opcode CMD_* (vea §5.2) |
0x02 |
ERROR |
1 | u8 | r | ram | resultado de la última escritura; 0x00 = OK; 0xFA..0xFF clases de error. Se borra con CMD_CLEAR_ERROR. Véase §5.3 |
0x03 |
VERSION |
1 | u8 | r | rom | Versión del protocolo. 0x04 = v1.3 |
0x05 |
CT_MODEL |
1 | u8 | lectura/escritura | user_config | Código de SKU de SCT-013 (staging puro en la v1.3, véase §6.2) |
0x07 |
V03_PERIOD_VALID |
1 | u8 | r | ram | Lo activa CMD_LATCH_PERIOD: 1 = reciente, 0 = vacía/caducada. NO se borra al leer. Véanse §6.3.3 (testigo) y §7.5 (conservación ante instantánea fallida) |
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::waitReady(timeout_ms) / RbAmp::readLastError() |
espere el indicador de listo; lea el código de error del dispositivo |
| ESP-IDF | rbamp_wait_ready() / rbamp_read_last_error() |
espere el indicador de listo; lea el código de error del dispositivo |
| Python | dev.wait_ready(timeout_ms=1000) / dev.read_last_error() |
espere el indicador de listo (lanza excepción si hay tiempo de espera); lea el código de error del dispositivo |
| ESPHome | comprobación de disponibilidad de update() / get_last_error_str() |
las lecturas se publican una vez que el módulo informa de que está listo; el código de error en texto |
4.2 Diagnóstico: medias de entrada en bruto y ventana de captura (0x10..0x1C)
| Dir. | Nombre | Tamaño | Tipo | Acceso | Persistencia | Notas |
|---|---|---|---|---|---|---|
0x10 |
ADC_MEAN_U |
2 | u16 LE | r | ram | Media de entrada bruta, canal U (~2048 centrado) |
0x12 |
ADC_MEAN_I0 |
2 | u16 LE | r | ram | Media de entrada en bruto, I0 |
0x14 |
ADC_MEAN_I1 |
2 | u16 LE | r | ram | Media de entrada en bruto, I1 (UI2/I2/I3/UI3) |
0x16 |
ADC_MEAN_I2 |
2 | u16 LE | r | ram | Media de entrada bruta, I2 (UI3/I3) |
0x18 |
CAPTURE_STATUS |
1 | u8 | r | ram | Captura de muestras brutas: bit0=listo |
0x19 |
CAPTURE_PAGE |
1 | u8 | lectura/escritura | ram | Página 0..15 → 16 muestras I0 en bruto en CAPTURE_WINDOW |
0x1A |
CAPTURE_WINDOW |
32 | bytes | r | ram | 16×u16 LE, códigos I0 previos a LUT. Lectura en ráfaga de 32 bytes. |
4.3 Sistema (0x20..0x25)
| Dir. | Nombre | Tamaño | Tipo | Acceso | Persistencia | Notas |
|---|---|---|---|---|---|---|
0x20 |
AC_FREQ |
1 | u8 | r | ram | Con origen en cruce por cero. Entero de 50 o 60 Hz. El cruce por cero está activo en todas las variantes (incluidas las I*) |
0x21 |
AC_PERIOD |
2 | u16 LE | r | ram | Semiperiodo de red, µs |
0x23 |
CALIBRATION |
1 | u8 | r | ram | Byte heredado de estado de calibración |
0x24 |
TOPOLOGY |
1 | u8 | r | rom | Número de canales de corriente (= V03_N_I): 1, 2 o 3; 5 = UI5, 7 = UI7 |
0x25 |
SENSOR_CLASS |
1 | u8 | lectura/escritura | user_config | 0 = UNSET, 1 = SCT_013, 2 = WIRED_CT (serie de pinzas CT, modelos 1..13: 1..5 heredados; emparejadas de fábrica en SKU CT- ; en firmware 1.4.22 y posteriores el módulo rechaza las escrituras de clase y modelo en funcionamiento normal con ERR_PARAM (0xFE); las bibliotecas cliente las rechazan en todos los firmwares), 3 = BUILTIN_CT (calibración de fábrica por unidad; el código de modelo no se usa). Un cambio de clase restablece CT_MODEL = 0. No es un discriminador de variante (véase §3.4) |
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::setSensorClass(cls) / RbAmp::readSensorClass(out) |
configure la clase de sensor; léala de vuelta |
| ESP-IDF | rbamp_set_sensor_class() / rbamp_read_sensor_class() |
configure la clase de sensor; léala de vuelta |
| Python | dev.set_sensor_class(cls) / dev.read_sensor_class() |
configure la clase de sensor; léala de vuelta |
| ESPHome | sensor_class: |
Opción YAML que fija la clase de sensor |
4.4 Configuración de flota (0x27..0x2F)
| Dir. | Nombre | Tamaño | Tipo | Acceso | Persistencia | Notas |
|---|---|---|---|---|---|---|
0x27 |
FLEET_CONFIG |
1 | u8 | lectura/escritura | user_config | bit0 = GC_ENABLE (recepción de instantáneas por llamada general; surte efecto tras el reinicio). Los bits 1-7 están reservados |
0x28 |
GROUP_ID |
1 | u8 | lectura/escritura | user_config | Filtro de grupo de la instantánea GC. 0 = responder a todas las llamadas. El byte de grupo de la trama GC debe coincidir o ser 0x00 |
0x29 |
DIGEST_CONFIG |
1 | u8 | lectura/escritura | ram | Máscara de composición de la ventana del digest (vea §4.9); escribir un bit no soportado → ERR_PARAM. Por defecto 0x00 (digest desactivado) tras el reinicio; reescríbalo en cada inicialización |
0x2A |
EVENT_FLAGS |
1 | u8 | w1c | ram | Indicadores de evento persistentes (vea §5.3, modelo de errores). Por defecto 0x00 tras el reinicio (pero el bit5 RESET_OCCURRED se activa al arrancar) |
0x2B |
EVENT_MASK |
1 | u8 | lectura/escritura | ram | Qué bits de EVENT_FLAGS mantienen DRDY en BAJO de forma fija |
0x2C |
THRESH_I_HI |
2 | u16 LE | lectura/escritura | ram | Umbral de corriente → EVENT_FLAGS.THRESH_I. Unidades: 0.01 A. 0xFFFF = desactivado |
0x2E |
THRESH_P_HI |
2 | u16 LE | lectura/escritura | ram | Umbral de potencia → EVENT_FLAGS.THRESH_P. Unidades: W. 0xFFFF = desactivado |
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::enableGc(enable) / RbAmp::setEventThresholds(i_amps, p_watts) |
active la llamada general en un módulo; fije los umbrales de corriente y de potencia |
| ESP-IDF | rbamp_enable_gc() / rbamp_set_event_thresholds() |
active la llamada general en un módulo; fije los umbrales de corriente y de potencia |
| Python | dev.enable_gc(enable=True) / dev.read_event_flags() |
habilite General Call en un módulo; lea los indicadores de evento (sin establecedor de umbral de dispositivo) |
| ESPHome | fleet_gc_enable: / group_id: |
Opciones YAML para la activación de llamada general y el identificador de grupo |
4.5 Dirección (0x30..0x31)
| Dir. | Nombre | Tamaño | Tipo | Acceso | Persistencia | Notas |
|---|---|---|---|---|---|---|
0x30 |
I2C_ADDRESS |
1 | u8 | lectura/escritura | user_config | Commit en dos fases: escriba la dirección candidata 0x08..0x77 en el staging de RAM; arme ADDR_COMMIT_MAGIC; después CMD_COMMIT_ADDR; se aplica tras el reinicio. Al arrancar se lee de vuelta la dirección activa (v1.3, corrección 4) |
0x31 |
ADDR_COMMIT_MAGIC |
1 | u8 | w | ram | Escriba 0xA5 para armar CMD_COMMIT_ADDR. Se consume (se borra) en el intento de commit. Las lecturas devuelven 0x00 |
Véase §6.1 para la secuencia.
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::prepareAddressChange(new_addr) / RbAmp::readActiveAddress(out) |
prepare y arme la nueva dirección; lea la dirección activa |
| ESP-IDF | rbamp_prepare_address_change() / rbamp_read_active_address() |
prepare y arme la nueva dirección; lea la dirección activa |
| Python | dev.prepare_address_change(new_addr) / dev.commit_address_change() |
prepare y arme la nueva dirección, luego confírmela |
| ESPHome | new_address: |
cambio de dirección puntual al arrancar; elimine la opción después |
4.6 Salud / diagnóstico (0x46..0x4F)
| Dir. | Nombre | Tamaño | Tipo | Acceso | Persistencia | Notas |
|---|---|---|---|---|---|---|
0x46 |
UPTIME_S |
4 | u32 LE | r | ram | Contador de tiempo activo propio del módulo (nominalmente segundos desde el arranque): solo detector de reinicios. En firmware hasta la 1.4.21 va más lento que el tiempo de pared (medido 0.58–0.80×), así que nunca lo use como reloj. Detección de reinicio para un master: el valor disminuyó, o es menor que el tiempo transcurrido desde la instantánea anterior del master |
0x4A |
RESET_CAUSE |
1 | u8 | r | ram | Indicadores del motivo de reinicio (bit0=PIN, bit1=POR/BOR, bit2=SW, bit3=IWDG, bit4=WWDG, bit5=LPWR). Solo para registro: el tratamiento del reinicio es el mismo sea cual sea la causa |
0x4B |
I2C_ERR_COUNT |
2 | u16 LE | r | ram | Errores de bus (BERR+OVR) desde el arranque, con saturación |
0x4D |
I2C_REINIT_COUNT |
1 | u8 | r | ram | Número de reinicializaciones de recuperación de BUSY del periférico I²C, con saturación |
0x4E |
ZC_OFFSET |
2 | u16 LE | r | ram | µs desde el flanco STOP de la última instantánea GC hasta el siguiente cruce por cero de tensión; se usa para la compensación de fase U/I en el cálculo de potencia. Está forzado por firmware a 0xFFFF en variantes solo de corriente (sin front-end de tensión → sin cruce por cero de tensión). No es la fuente de cruce por cero de la frecuencia de red: AC_FREQ (0x20) se deriva de un pin dedicado de cruce por cero y está disponible en todas las variantes. |
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | — | Los registros de salud de BASIC no están expuestos (solo la línea STD) |
| ESP-IDF | rbamp_read_uptime_s() |
lea el tiempo activo del módulo en segundos |
| Python | — | Los registros de salud de BASIC no están expuestos (solo la línea STD) |
| ESPHome | — | sin entidad de tiempo activo ni de salud |
4.7 Espejos de verificación del modelo de CT (0x51..0x53)
Espejos de solo lectura del preset de modelo de CT aplicado por canal. El protocolo de escritura no cambia (véase §6.2): esto es solo una lectura de vuelta para verificación.
| Dir. | Nombre | Tamaño | Tipo | Acceso | Persistencia | Notas |
|---|---|---|---|---|---|---|
0x51 |
CT_MODEL_CH0 |
1 | u8 | r | user_config | Preset del modelo de CT aplicado en ch0 (espejo de verificación) |
0x52 |
CT_MODEL_CH1 |
1 | u8 | r | user_config | Preset del modelo de CT aplicado en ch1 |
0x53 |
CT_MODEL_CH2 |
1 | u8 | r | user_config | Preajuste de modelo de CT aplicado en ch2 |
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::readCTModelCh(channel, out) |
lea el modelo de CT realmente aplicado en un canal |
| ESP-IDF | rbamp_read_ct_model_ch() |
lea el modelo de CT realmente aplicado en un canal |
| Python | dev.read_ct_model_ch(ch) |
lea el modelo de CT realmente aplicado en un canal |
| ESPHome | registro de arranque ct_model[0]: matches |
líneas de registro que confirman que se aplicaron la clase de sensor y el modelo |
4.8 Identidad (0x54..0x6F)
| Dir. | Nombre | Tamaño | Tipo | Acceso | Persistencia | Notas |
|---|---|---|---|---|---|---|
0x54 |
PRODUCT_ID |
1 | u8 | r | rom | Familia: 0x01 = sensor rbAmp. El maestro lo lee antes de cualquier registro específico de la familia |
0x55 |
HW_VARIANT |
1 | u8 | r | rom | Vea §3.1 |
0x56 |
FW_TIER |
1 | u8 | r | rom | bits 0-1: 0=BASIC, 1=STANDARD (2 = no implementado); bit 2=bidireccional; bit 3=calibrado con LUT |
0x57 |
CAPABILITY |
2 | u16 LE | r | rom | Vea §3.2 |
0x59 |
GC_TICK |
2 | u16 LE | r | ram | Tick del master desde la última trama GC aceptada; 0xFFFF = nunca recibida |
0x5C |
UID |
12 | bytes | r | rom | UID de chip de 96 bits. Una lectura en ráfaga. |
0x68 |
LABEL |
8 | bytes | lectura/escritura | user_config | Etiqueta de ubicación del usuario (ASCII, relleno con ceros). Vacío = sin asignar. Escriba byte a byte (véase §5.1) |
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::readProductId() / RbAmp::readUid(uid) |
lea el identificador de familia; lea el UID de 96 bits |
| ESP-IDF | rbamp_read_product_id() / rbamp_read_uid() |
lea el identificador de familia; lea el UID de 96 bits |
| Python | dev.read_product_id() / dev.read_uid() |
lea el identificador de familia; lea el UID de 96 bits |
| ESPHome | get_uid_hex() / get_variant_str() |
el UID en hexadecimal; la variante como texto |
4.9 Ventana de resumen (0x70..0x85)
DIGEST es una ventana de sondeo compacta, servida por una única lectura en ráfaga. Su composición se elige con DIGEST_CONFIG (0x29); una escritura que active un bit no soportado se rechaza con ERR_PARAM:
bit de DIGEST_CONFIG |
Contenido | Formato |
|---|---|---|
| bit 0 | I_RMS[N] |
u16 por canal, 0.01 A |
| bit 1 | U_RMS |
u16, 0.1 V (solo hardware de tensión) |
| bit 2 | P_REAL[N] |
i16 por canal, 1 W (solo has_power) |
| bit 3 | PF[N] |
u8 por canal, 0..100 (solo has_power) |
| Dir. | Nombre | Tamaño | Tipo | Acceso | Persistencia | Notas |
|---|---|---|---|---|---|---|
0x70 |
DIGEST |
22 | bytes | r | ram | Estructura: [STATUS_MIRROR u8][SEQ u8] + campos habilitados por máscara. La carga máxima (máscara completa de UI3) es 19 B + 2 B de cabecera = 21 B usados; 1 B de cola sin usar (lee 0x00). SEQ se incrementa en cada commit RT, con vuelta de 255→0. Atómico mediante congelación de lectura (véase §5.4). |
La estructura es dinámica según DIGEST_CONFIG: cada bit activo añade sus campos en un orden fijo: I_RMS[N] → U_RMS → P[N] → PF[N]. Los bits desactivados no dejan relleno: los campos se desplazan hacia delante. El maestro debe analizar con la misma máscara que escribió en DIGEST_CONFIG. Una lectura en ráfaga de 22 bytes es segura (la cola es 0x00 siempre que la carga total sea < 22 bytes). La cola de un byte es siempre 0x00 (reservada).
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | — | ventana de resumen no expuesta |
| ESP-IDF | rbamp_set_digest_fields() / rbamp_read_digest() |
elija los campos del digest; léalos en una sola transacción (BASIC) |
| Python | — | ventana de resumen no expuesta |
| ESPHome | — | ventana de resumen no expuesta |
4.10 Bloque de tiempo real V03 (0x86..0xBD)
Todos float32 LE (IEEE 754 de precisión simple, orden de bytes little-endian estándar). La disposición byte a byte está congelada desde v1.2. Cada registro es de acceso r, persistencia ram, grupo v03_rt. Atómico mediante congelación de lectura (vea §5.4): una lectura en ráfaga de 56 bytes (0x86..0xBD) está garantizada como contigua (sin instantánea partida).
| Dir. | Nombre | Tamaño | Tipo | Acceso | Persistencia | Unidades | Notas |
|---|---|---|---|---|---|---|---|
0x86 |
V03_U_RMS |
4 | float32 LE | r | ram | V | 0.0 en variantes I |
0x8A |
V03_U_PEAK |
4 | float32 LE | r | ram | V | |
0x8E |
V03_I0_RMS |
4 | float32 LE | r | ram | A | |
0x92 |
V03_I1_RMS |
4 | float32 LE | r | ram | A | 0.0 si la variante carece de ch1 |
0x96 |
V03_I2_RMS |
4 | float32 LE | r | ram | A | 0.0 si la variante carece de ch2 |
| ⛔ | STOP: el RMS plano por canal termina en el canal 2. | La fila siguiente (0x9A) es V03_I0_PEAK, NO V03_I3_RMS. NO extrapole el patrón del paso 4 más allá del canal 2: obtendrá números plausibles pero silenciosamente erróneos (pico, no RMS; canal 0, no canal 3). Los canales 3 y superiores (UI5/UI7) se acceden solo a través de la ventana de acceso por canal: véase §4.14. |
|||||
0x9A |
V03_I0_PEAK |
4 | float32 LE | r | ram | A | |
0x9E |
V03_I1_PEAK |
4 | float32 LE | r | ram | A | |
0xA2 |
V03_I2_PEAK |
4 | float32 LE | r | ram | A | |
0xA6 |
V03_P0_REAL |
4 | float32 LE | r | ram | W | 0.0 en variantes I (sin cálculo de potencia) |
0xAA |
V03_P1_REAL |
4 | float32 LE | r | ram | W | |
0xAE |
V03_P2_REAL |
4 | float32 LE | r | ram | W | |
0xB2 |
V03_PF0 |
4 | float32 LE | r | ram | – | rango −1..+1 |
0xB6 |
V03_PF1 |
4 | float32 LE | r | ram | – | |
0xBA |
V03_PF2 |
4 | float32 LE | r | ram | – |
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::readAll(snapshot) / RbAmp::channels() |
lea el bloque de tiempo real completo; número de canales de corriente |
| ESP-IDF | rbamp_read_all() / rbamp_channels() |
lea el bloque de tiempo real completo; número de canales de corriente |
| Python | dev.read_all() / dev.channels |
lea el bloque de tiempo real completo; número de canales de corriente |
| ESPHome | voltage / power |
Sensores YAML para los valores en tiempo real |
4.11 Bloque de periodo V03 (0xBE..0xCF)
Una instantánea de periodo tomada con CMD_LATCH_PERIOD. Diseño irregular (legado histórico de la v1.2, congelado en la v1.3): avg_p de ch1/ch2 está aquí, mientras que el avg_p de ch0 está en §4.12 en la dirección 0xDC (la primitiva de energía heredada no se reubicó, para no romper la API de los integradores existentes). Lógicamente, estos tres valores pertenecen al mismo grupo.
| Dir. | Nombre | Tamaño | Tipo | Acceso | Persistencia | Unidades | Notas |
|---|---|---|---|---|---|---|---|
0xBE |
V03_PERIOD_COMMIT_CNT |
4 | u32 LE | r | ram | – | Commits RT en el periodo cerrado. Un commit = 0.1 s desde la v1.2 (0.2 s antes); cuenta × la longitud del commit es la medida propia del módulo de la longitud de la ventana (véase §7.4) |
0xC2 |
V03_PERIOD_AVG_P_CH1 |
4 | float32 LE | r | ram | W | P media de la instantánea del canal 1 (UI2, UI3) |
0xC6 |
V03_PERIOD_AVG_P_CH2 |
4 | float32 LE | r | ram | W | P media de la instantánea del canal 2 (UI3) |
0xCA |
V03_PERIOD_MS |
4 | u32 LE | r | ram | ms | Duración del período actual |
0xCE |
V03_STATUS |
1 | u8 | r | ram | – | bit 0 = válido (resultado de la confirmación RT). NO se borra al leer. El master sondea STATUS (0x00) para esperar el listo. El alias DATA_VALID se usa a veces para este registro en capítulos de tutorial: misma dirección, misma semántica. |
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::readPeriodAvgPower(ch) / RbAmp::readPeriodSnapshot() |
lea la potencia media de período; tome y lea una instantánea de período completa |
| ESP-IDF | rbamp_read_period_avg_power() / rbamp_read_period_snapshot() |
lea la potencia media de período; tome y lea una instantánea de período completa |
| Python | dev.read_period_avg_power(ch) / dev.read_period_snapshot() |
lea la potencia media de período; tome y lea una instantánea de período completa |
| ESPHome | update_interval: / latch_interval: |
Opciones YAML para el periodo y la cadencia de la instantánea |
4.12 V03 Q + período ch0 (0xD0..0xE3, compilación de producción)
| Dir. | Nombre | Tamaño | Tipo | Acceso | Persistencia | Unidades | Notas |
|---|---|---|---|---|---|---|---|
0xD0 |
V03_Q0_REAC |
4 | float32 LE | r | ram | VAr | Potencia reactiva canal 0 = √(S² − P²), S = U_rms × I_rms: sin signo (≥ 0), incluye la potencia de distorsión; 0 en variantes solo I; ruidosa cerca de FP ≈ 1. Precisión no especificada |
0xD4 |
V03_Q1_REAC |
4 | float32 LE | r | ram | VAr | |
0xD8 |
V03_Q2_REAC |
4 | float32 LE | r | ram | VAr | |
0xDC |
V03_PERIOD_AVG_P |
4 | float32 LE | r | ram | W | Primitiva de energía de PRODUCCIÓN: instantánea de P media del canal 0, ≥ 0 (pinza unidireccional de BASIC). Agrupada lógicamente con V03_PERIOD_AVG_P_CH1/CH2 (§4.11); la disposición heredada se conserva por compatibilidad |
0xE0 |
V03_PERIOD_MAX_P |
4 | float32 LE | r | ram | W | Máximo de P del canal 0 en la instantánea de este período |
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::readPeriodAvgPower(ch) / RbAmp::readPeriodMaxPower() |
lea la potencia media y máxima del periodo |
| ESP-IDF | rbamp_read_period_avg_power() / rbamp_read_period_max_power() |
lea la potencia media y máxima del periodo |
| Python | dev.read_period_avg_power(ch) / dev.read_period_max_power() |
lea la potencia media y máxima del periodo |
| ESPHome | reactive_power / update_interval: |
sensor de potencia reactiva; cada actualización cierra el periodo y lee los promedios |
4.13 dt diagnóstico del lado del chip (0xEC)
| Dir. | Nombre | Tamaño | Tipo | Acceso | Persistencia | Unidades | Notas |
|---|---|---|---|---|---|---|---|
0xEC |
V03_PERIOD_LATCH_MS |
4 | u32 LE | r | ram | ms | dt del chip entre las dos instantáneas más recientes. Temporizador de diagnóstico del módulo: puede leerse corto bajo carga; use el reloj del maestro para la energía. Véase §7.4 |
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::readPeriodLatchMs() |
lea la longitud de periodo del lado del módulo (solo diagnóstico) |
| ESP-IDF | rbamp_read_period_latch_ms() |
lea la longitud de periodo del lado del módulo (solo diagnóstico) |
| Python | dev.read_period_latch_ms() |
lea la longitud de periodo del lado del módulo (solo diagnóstico) |
| ESPHome | — | no expuesto |
4.14 Ventana de acceso a canales (0x32 + 0x3C..0x3F)
Se aplica a los módulos UI5 (5 canales) y UI7 (7 canales). En UI1/UI2/UI3 e I1/I2/I3 también está disponible: una ruta unificada si la prefiere a los registros planos de §4.10.
Los canales 3..6 no tienen registros planos por canal (había espacio para 8 bytes en el espacio de direcciones de 8 bits, y un diseño plano necesitaría ~88). En su lugar se expone una ventana de selección y lectura:
| Dir. | Nombre | Tamaño | Tipo | Acceso | Persistencia | Notas |
|---|---|---|---|---|---|---|
0x32 |
REG_CHANNEL_SELECT |
1 | u8 | lectura/escritura | ram | Esto es una dirección de registro, NO el opcode de comando CMD_SAVE_USER_CONFIG; coinciden numéricamente. Cite siempre 0x32 indicando si se refiere al espacio de registros o de comandos. Codificado como (field << 4) \| channel. El nibble channel va de 0..15 (reservado para hasta 16 canales); el máximo físico por SKU es channels() (7 en UI7). Un selector cuyo índice de canal sea >= channels() se acepta sin ERR_PARAM; la ventana de datos entonces lee 0 y las escrituras en ella se ignoran. field según la tabla siguiente. Escribir el selector copia el valor pedido en REG_CHANNEL_DATA. |
0x3C..0x3F |
REG_CHANNEL_DATA |
4 | float32 LE | r | ram | Búfer de datos para la selección. float32 LE para todos los campos públicos. |
Códigos de campo (nibble alto en 0x32):
| Código | Campo | Tipo | Acceso | Significado |
|---|---|---|---|---|
0 |
CHFIELD_I_RMS |
float32 LE | r | Corriente RMS en vivo del canal seleccionado (unidades A) |
1 |
CHFIELD_I_PEAK |
float32 LE | r | Corriente de pico en vivo (unidades A) |
2 |
CHFIELD_P_REAL |
float32 LE | r | Potencia real instantánea (unidades W) |
3 |
CHFIELD_PF |
float32 LE | r | Factor de potencia en vivo (−1..+1) |
4..12 |
(reserved) | – | – | No documentado para código de usuario; no dependa de sus valores ni de sus códigos. |
13 |
CHFIELD_PERIOD_AVG_P |
float32 LE | r | Potencia real media de la instantánea (W). Para los canales 3 y siguientes este es el ÚNICO campo de período/energía: los V03_PERIOD_AVG_P* planos (§4.11/§4.12) solo cubren ch0..ch2. |
14 |
(reserved) | – | – | Reservado para firmware futuro; no dependa de él. |
15 |
CHFIELD_CT_MODEL |
u8 en 0x3C (los bytes 0x3D..0x3F se leen como relleno de ceros) |
lectura/escritura | Firmware ≥ 1.4.18. Código del modelo de CT por canal para el canal seleccionado (0..N-1). La lectura devuelve el modelo aplicado en el canal. La escritura solo va a RAM y se aplica de inmediato: el escalado del canal se conmuta al preset del modelo seleccionado en la misma transacción; no hace falta comando de confirmación aparte ni CMD_SET_CT_MODEL_CH*. Las escrituras se hacen byte a byte según la regla del protocolo (§5.1). Un par (SENSOR_CLASS, código) desconocido devuelve ERR_PARAM (0xFE) y el canal conserva su modelo anterior: no hay estado parcial. Los canales de las variantes superiores (ch3 y siguientes) ya NO heredan el modelo global: cada canal debe configurarse explícitamente mediante el campo 15. Persistencia: CMD_SAVE_USER_CONFIG (opcode 0x32 en REG_COMMAND, sin restricción) guarda los modelos de todos los canales en la página flash de configuración de usuario con un solo comando. Una escritura sin un CMD_SAVE_USER_CONFIG posterior se pierde al reiniciar. El conjunto de pares (clase, código) aceptados lo define la tabla de modelos de su versión de firmware; el módulo confirma de forma autorizada un código: escríbalo, léalo de vuelta y compruebe REG_ERROR. En módulos con firmware v1.4.0, escribir este campo devuelve ERR_PARAM; use en su lugar los comandos por canal y el staging plano de REG_CT_MODEL. |
Las cuatro trampas: léalas antes de escribir código
- ⛔ El RMS plano por canal termina en el canal 2. Las filas
V03_I0_RMS(0x8E) →V03_I1_RMS(0x92) →V03_I2_RMS(0x96) avanzan con paso 4, y0x9Acontinúa el paso, pero0x9AesV03_I0_PEAK, noV03_I3_RMS. Extrapolar el patrón devuelve en silencio el pico del canal 0 en lugar del RMS del canal 3. El firmware no puede detectar el error; el valor parece plausible. Los canales 3 y siguientes solo están en la ventana de acceso a canales. - Vuelva a seleccionar antes de cada lectura.
REG_CHANNEL_DATAes una instantánea tomada en el momento de la escritura del selector, no una vista en vivo. Sondear0x3C..0x3Fen un bucle sin volver a escribir0x32devuelve un valor congelado para siempre. Cada lectura nueva requiere una nueva escritura en0x32. 0x32dirección de registro ≠0x32opcode de comando.CMD_SAVE_USER_CONFIGusa el opcode0x32escrito enREG_COMMAND(0x01): es un espacio de direcciones distinto del deREG_CHANNEL_SELECT(que está en la dirección de registro0x32). Nunca cite0x32sin indicar de qué espacio se trata.- Para los canales 3 y siguientes, el período y la energía provienen solo del campo
13(CHFIELD_PERIOD_AVG_P). Los registrosV03_PERIOD_AVG_P*(0xC2/0xC6/0xDC) solo cubren los canales 0/1/2. No existe unV03_PERIOD_AVG_P_CH3plano: lea el campo 13 a través de la ventana.
Ejemplo a nivel de trama: lectura de la corriente RMS del canal 3
# select field=0 (I_RMS), channel=3 → (0 << 4) | 3 = 0x03
write_u8(REG_CHANNEL_SELECT=0x32, 0x03)
# read 4 bytes at REG_CHANNEL_DATA — float32 LE
bytes = read(0x3C, 4)
i3_rms = unpack_float32_le(bytes) # amperes
Para la corriente de pico del canal 4: selector = (1 << 4) | 4 = 0x14, luego lea 0x3C..0x3F. Para la potencia media de período del canal 5: selector = (13 << 4) | 5 = 0xD5, luego lea 0x3C..0x3F.
Ejemplo a nivel de trama: lectura de la corriente RMS en TODOS los canales de un módulo UI7
Combina ambas vías en un bucle: bloque RT plano para ch 0..2, ventana de acceso por canal para ch 3..6.
# --- Discover physical channel count -----------------------------
N = read_u8(TOPOLOGY=0x24) # 5 on UI5, 7 on UI7
# --- ch 0..2 via flat block (single 12-byte burst) ---------------
bytes = read(V03_I0_RMS=0x8E, 12)
i0 = unpack_float32_le(bytes[0:4])
i1 = unpack_float32_le(bytes[4:8])
i2 = unpack_float32_le(bytes[8:12])
# --- ch 3..N-1 via channel access window (re-select per read) ----
i_rms = [i0, i1, i2]
for ch in range(3, N):
write_u8(REG_CHANNEL_SELECT=0x32, (0 << 4) | ch) # field 0 = I_RMS
i_rms.append(unpack_float32_le(read(REG_CHANNEL_DATA=0x3C, 4)))
# i_rms is now length-N: RMS current for every physical channel of the module.
El mismo patrón se extiende a I_PEAK (campo 1), P_REAL (campo 2), PF (campo 3) y a la instantánea PERIOD_AVG_P (campo 13): bloque plano para ch0..ch2, ventana para ch3 y superiores. El campo 13 es la ÚNICA fuente de periodo/energía para ch3 y superiores: el bloque plano no tiene V03_PERIOD_AVG_P_CH3..6.
Para la configuración del modelo de CT por canal en cualquier canal (0..N-1), use el campo de ventana 15 (CHFIELD_CT_MODEL): escriba (15 << 4) | ch en 0x32 y luego escriba el código del modelo como un byte en 0x3C. Guarde los modelos de todos los canales con un único CMD_SAVE_USER_CONFIG (código de operación 0x32 en REG_COMMAND (0x01), sin restricción).
Recomendación para nuevas integraciones
La ventana cubre los canales 0..6: puede usarla como vía unificada para todos los canales en lugar de bifurcar entre registros planos (ch0..ch2) y ventana (ch3..ch6). En flotas que mezclan SKU junior (UI1/UI2/UI3) y senior (UI5/UI7) esto elimina una bifurcación en el código. La latencia es una escritura pequeña adicional por lectura (frente a una lectura en ráfaga directa del bloque plano).
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::readCurrent(ch) / RbAmp::channels() |
lea cualquier canal por índice; número de canales |
| ESP-IDF | rbamp_read_channel() / rbamp_read_all_channels() |
lea un canal por índice, incluidos los canales 3 y superiores; lea todos los canales |
| Python | dev.current[ch] / dev.channels |
índice sobre los canales válidos; número de canales |
| ESPHome | current_N: |
ranuras de sensor por canal para hasta siete canales de corriente |
5 · Protocolo de hilos
5.1 Asimetría LECTURA / ESCRITURA
Comportamiento canónico por diseño:
| Dirección | Autoincremento | Patrón |
|---|---|---|
| LECTURA (lectura en ráfaga de N bytes) | ✅ SÍ | read(addr, N) devuelve N bytes consecutivos a partir de addr. |
| ESCRITURA (registros de varios bytes) | ❌ NO | Un registro multibyte se escribe byte a byte: una transacción de un solo byte por dirección. Una escritura en ráfaga pierde los bytes 1..N-1 y solo acepta el primero. |
Registros multibyte escribibles afectados (escritura byte a byte)
LABEL(0x68-0x6F, 8 bytes)THRESH_I_HI(0x2C, 2 bytes u16 LE)THRESH_P_HI(0x2E, 2 bytes u16 LE)
Orden de bytes en la ESCRITURA de varios bytes: el byte de la dirección inferior es el byte bajo (LE). Por ejemplo, para escribir THRESH_I_HI = 0x1234 (4660 en decimal):
# CORRECT: low byte first (LE)
write(addr=0x2C, value=0x34) # LO byte
write(addr=0x2D, value=0x12) # HI byte
Ejemplo INCORRECTO / CORRECTO (pseudocódigo)
# WRONG — only 'M' (first byte) is accepted, the rest are dropped
write(addr=0x50, reg=0x68, data=b"MyMeter1") # 8-byte burst
# CORRECT — byte-at-a-time loop
label = b"MyMeter1"
for i, byte in enumerate(label):
write(addr=0x50, reg=0x68 + i, data=byte)
Excepción: trama de difusión General Call
La trama de difusión GC (dirección de llamada general 0x00 + carga de 5 bytes) es una vía de protocolo de cable separada, no una escritura de registro. La asimetría lectura/escritura de §5.1 no se aplica a GC. Véase §6.3.
5.2 Comportamiento de los registros no asignados
Cualquier lectura de una dirección no asignada devuelve 0x00. El firmware nunca responde NACK a las lecturas de registros. Es por diseño (corrección de bloqueo).
Implicación para la detección: la detección de un dispositivo ausente debe hacerse mediante el ACK de la trama de dirección I²C, no mediante sondeos de registros.
5.3 Modelo de errores
v1.3 canónico:
REG_ERROR (0x02)es el resultado de la última escritura, NO persistente. En cada escritura de registro el firmware fijareg_error = ERR_OK; cualquier escritura posterior no relacionada borra el error anterior.EVENT_FLAGS (0x2A) bit 3es la señal duradera (pegajosa W1C), activada en cualquier escritura o comando rechazado.
Códigos de error
| Código | Nombre | Gravedad |
|---|---|---|
0x00 |
OK | – |
0xF9 |
CLONE |
reservada: no se activa |
0xFA |
LUT_BAD |
error |
0xFB |
FLASH_PARAMS_BAD |
error (vea §6.5 grabado nuevo) |
0xFC |
NOT_READY |
error |
0xFD |
SENSOR_OVERFLOW |
error |
0xFE |
PARAM |
error (escritura rechazada: argumento no válido / opcode desconocido / enumeración fuera de rango; activa EVENT.bit3. En imágenes muy tempranas, 1.2–1.4.3, los opcodes desconocidos se ignoraban en silencio) |
0xFF |
UNHANDLED |
error |
Estructura de EVENT_FLAGS (0x2A) (W1C persistente)
| bit | Nombre | Notas |
|---|---|---|
| 0 | PERIOD_READY |
instantánea de periodo disponible |
| 1 | THRESH_I |
I_rms superó THRESH_I_HI |
| 2 | THRESH_P |
La suma de P superó THRESH_P_HI |
| 3 | ERROR |
REG_ERROR != 0 (señal de error persistente) |
| 4 | CONFIG_CHANGED |
clase/modelo/dirección/etiqueta modificados |
| 5 | RESET_OCCURRED |
el módulo se ha reiniciado (se activa al arrancar hasta W1C). El maestro debe reinicializar la configuración en RAM. |
Patrones de error canónicos
Patrón 1: captura puntual tras la operación (resultado de exactamente esa operación):
write target_reg(...)
err = read_u8(0x02) # IMMEDIATELY after the operation, before the next write
Patrón 2: monitorización duradera (canónico para un master de ejecución prolongada):
event_flags = read_u8(0x2A)
if event_flags & (1 << 3): # ERROR bit
last_err = read_u8(0x02)
# handle
write_u8(0x2A, 1 << 3) # W1C clear bit 3
# or CMD_CLEAR_ERROR
⚠ advertencia sobre el bit 3 asíncrono
Un rechazo de escritura activa EVENT_FLAGS.bit3 de forma asíncrona, dentro de una ventana de medida (~100 ms desde la v1.2; 200 ms en imágenes anteriores a la v1.2) tras la operación, no de inmediato. No sondee el bit 3 justo después de una escritura: espere ≥ 200 ms (cubre todas las imágenes), o use el Patrón 1 (captura inmediata de REG_ERROR) para el resultado de una operación concreta, y reserve el sondeo del bit 3 para la monitorización de larga duración.
Centinela anticlón
DEV_ERR_CLONE (0xF9) está reservado: nunca se activa. El código se mantiene por compatibilidad futura.
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::readLastError() / RbAmp::hasError(out) |
lea el código de error de la última escritura; lea el indicador de error duradero |
| ESP-IDF | rbamp_read_last_error() / rbamp_has_error() |
lea el código de error de la última escritura; lea el indicador de error duradero |
| Python | dev.read_last_error() / dev.has_error() |
lea el código de error de la última escritura; lea el indicador de error duradero |
| ESPHome | get_last_error_str() / get_event_flags() |
el código de error como texto; los indicadores de evento |
5.4 Atomicidad / semántica de congelación de lectura
5.4.1 Congelación de lectura presente (atómica, NO partida)
Estos bloques están protegidos por una congelación de lectura en el firmware. Una lectura en ráfaga es atómica respecto al commit RT:
- Bloque RMS / P / FP V03 (0x86..0xBD): el bloque completo en coma flotante.
- Bloque de resumen (0x70..0x85).
Las lecturas en ráfaga de estos rangos son seguras: no hay muestra partida entre dos confirmaciones consecutivas.
5.4.2 Sin congelación en la lectura: se recomienda read-twice-agree
Estos registros se actualizan de forma asíncrona, sin congelación durante la lectura. Las lecturas de un solo byte son tolerantes, pero el valor puede cambiar entre transacciones:
GC_TICK (0x59): contador de ticks GC.I2C_ADDRESS (0x30): espejo de staging en RAM.CT_MODEL_CH0/1/2 (0x51..0x53): espejos de verificación.
Patrón para lecturas fiables:
val1 = read_u8(addr)
val2 = read_u8(addr)
if val1 == val2:
return val1 # stable
else:
retry # value changed between reads
5.4.3 Semántica de la pinza de ruido (NF)
I_RMS = 0x00000000 significa «señal por debajo del nivel de ruido» (el firmware calcula rms_corr² = max(0, raw² − nf²)), NO «sin datos» / «error». Es una medición válida para escenarios sin carga o con carga muy baja.
El código del maestro no debe interpretar I_RMS = 0.0 como error ni como ausencia de datos.
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::readAll(snapshot) |
lea todo el bloque de tiempo real en una sola llamada |
| ESP-IDF | rbamp_read_all() |
lea todo el bloque de tiempo real en una sola llamada |
| Python | dev.read_all() |
lea todo el bloque de tiempo real en una sola llamada |
| ESPHome | lectura en ráfaga del bloque instantáneo | el componente lee el bloque instantáneo en una sola ráfaga por actualización |
6 · Secuencias del protocolo
6.0 Cronología del arranque en frío
Tras el POR (reinicio de encendido) o un reinicio completo, el módulo pasa por las siguientes fases:
| Tiempo desde el POR | Estado |
|---|---|
| 0 ms | POR: todos los registros en estado de reinicio, SCL/SDA en tercer estado |
| ~10 ms | Responde en el bus (el módulo hace ACK de su dirección) |
| ~50 ms | Primera confirmación RT (el bloque RT en 0x86 y siguientes contiene datos válidos; STATUS.bit0 = 1) |
| ~60-80 ms | Primer V03_STATUS.bit0 válido (la cadena RT ha completado un periodo completo de red) |
| ~100 ms | El primer CMD_LATCH_PERIOD puede devolver V03_PERIOD_VALID = 1 (la instantánea requiere al menos 1 período de red de acumulación; unos 200 ms en imágenes anteriores a la v1.2) |
| ~250 ms | Todas las mediciones estables (típico) |
Arranque en frío completo hasta la primera medición válida ≈ 250 ms (típico). Tras un CMD_RESET blando la cronología es idéntica (se ejecuta la máquina de estados de reinicio completa).
Secuencia de inicialización del maestro:
1. wait ~50 ms after VCC stable
2. probe slave address (read PRODUCT_ID = 0x54); retry up to 300 ms on NACK
3. read identity (HW_VARIANT 0x55, CAPABILITY 0x57/0x58); validate
4. check REG_ERROR (0x02):
- 0x00 — normal boot
- 0xFB — fresh flash, provisioning required (§6.5)
- other — see §6.7 error-state recovery
5. configure (SENSOR_CLASS, CT_MODEL, FLEET_CONFIG, etc.)
6. poll STATUS (0x00) until bit0 = 1 (READY) — usually immediate after step 5
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::begin() / RbAmp::waitReady(timeout_ms) |
sondee el módulo y espere el indicador de listo |
| ESP-IDF | rbamp_begin() / rbamp_wait_ready() |
sondee el módulo y espere el indicador de listo |
| Python | dev.begin() / dev.wait_ready(timeout_ms=1000) |
sondee el módulo y espere el indicador de listo |
| ESPHome | rbamp: address: |
dirección del módulo fijada en YAML; el componente sondea el módulo al iniciar |
6.1 Cambio de dirección: commit en dos fases (apto para producción)
Protocolo de cable (canónico v1.3):
1. write candidate_addr (1 byte) → REG_I2C_ADDRESS (0x30) # RAM staging, not persisted
2. write 0xA5 → REG_ADDR_COMMIT_MAGIC (0x31) # arm commit
3. issue CMD_COMMIT_ADDR (opcode 0x30 in REG_COMMAND) # persists into flash
4. wait ~700 ms (flash write completion; see §6.6 settle)
5. issue CMD_RESET (opcode 0x01) # module resets
6. wait ~300 ms boot-to-responsive
7. verify: bus-probe the new address (ACK = success)
: CMD_COMMIT_ADDR NO reinicia el módulo automáticamente; se requiere un CMD_RESET explícito en el paso 5. Si el maestro omite el reinicio explícito, la nueva dirección queda guardada en flash, pero la antigua sigue activa hasta el siguiente reinicio externo (corte de alimentación, pin de reinicio hardware, IWDG).
Guarantees:
- El cambio de dirección funciona en modo producción (no está restringido de fábrica).
REG_I2C_ADDRESS (0x30)al arrancar lee la dirección activa (canónico v1.3). Hasta el reinicio tras la preparación devuelve el candidato.- La dirección queda excluida del espacio de nombres de
CMD_SAVE_GAINS/CMD_SAVE_USER_CONFIG: solo se persiste medianteCMD_COMMIT_ADDR.
Tiempos de la ventana de arranque para la verificación:
- Mínimo 300 ms desde el arranque hasta estar operativo.
- Ventana de reintento en la nueva dirección: ~1 s en total (si un NACK persiste tras 1-2 reintentos, puede hacer falta un retardo adicional de arranque).
- Una vez que la nueva dirección responde ACK, opcionalmente verifique leyendo
0x30(que ahora refleja la nueva dirección activa) para confirmarla.
Modos de fallo:
ADDR_COMMIT_MAGICno armado →CMD_COMMIT_ADDR→REG_ERROR = ERR_PARAM (0xFE).- Candidata fuera de rango (< 0x08 o > 0x77) →
ERR_PARAM. - Tras 5 s sin confirmación, el magic se borra; el paso
preparedebe repetirse.
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::prepareAddressChange(new_addr) / RbAmp::commitAddressChange() |
prepare y arme la nueva dirección, luego confírmela |
| ESP-IDF | rbamp_prepare_address_change() / rbamp_commit_address_change() |
prepare y arme la nueva dirección, luego confírmela |
| Python | dev.prepare_address_change(new_addr) / dev.commit_address_change() |
prepare y arme la nueva dirección, luego confírmela |
| ESPHome | new_address: |
cambio de dirección puntual al arrancar; elimine la opción después |
6.2 Vinculación del modelo de CT: staging puro + CMD por canal
En imágenes anteriores al firmware 1.4.20 (CAPABILITY bit 12 a 0), el escalado aplicado por modelo vuelve al valor de fábrica tras reiniciar el módulo: vuelva a preparar y a confirmar CT_MODEL por canal tras cada reinicio detectado, o la energía será errónea.
v1.3 canónico de solo preparación: escribir REG_CT_MODEL (0x05) ya no aplica automáticamente el preajuste a ch0. El enlace ocurre solo mediante CMD_SET_CT_MODEL_CHn.
Protocolo canónico por canal (independiente del orden en la v1.3):
1. write REG_SENSOR_CLASS (0x25) = sct013 # if not already set
2. write REG_CT_MODEL (0x05) = model_code # stages, applies nothing
3. issue CMD_SET_CT_MODEL_CHn (opcode 0x28/0x29/0x2A for ch0/1/2)
# VALIDATES (class, model) + binds to channel n
4. wait 5 ms settle
5. (optional) issue CMD_SAVE_USER_CONFIG (opcode 0x32) for persistence
Independiente del orden: en v1.3 los canales pueden configurarse en cualquier orden: ch0 primero, último o como le convenga. El rodeo de «enlazar ch0 al final» de v1.2 ya no es necesario.
Verificación por lectura de vuelta: tras la vinculación, lea CT_MODEL_CH0/1/2 (0x51..0x53); esos registros reflejan el estado aplicado por canal.
Modos de fallo (la validación de (clase, modelo) ocurre en el paso de enlace CMD_SET_CT_MODEL_CHn, no en la escritura de solo preparación en 0x05):
SENSOR_CLASS = 0(SIN DEFINIR) cuando se emiteCMD_SET_CT_MODEL_CHn→REG_ERROR = ERR_PARAM.CT_MODELfuera de 1..7 (SCT-013-005/-010/-030/-050/-100/-020/-060) enCMD_SET→ERR_PARAM.
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::setSensorClass(cls) / RbAmp::setCTModel(channel, code) |
configure la clase de sensor y el modelo de CT por canal |
| ESP-IDF | rbamp_set_sensor_class() / rbamp_set_ct_model_ch() |
configure la clase de sensor y el modelo de CT por canal |
| Python | dev.set_sensor_class(cls) / dev.set_ct_model_ch(channel, code) |
configure la clase de sensor y el modelo de CT por canal |
| ESPHome | sensor_class: / ct_model: |
Opciones YAML para la clase de sensor y el modelo de CT |
6.3 Instantánea de difusión GC: sincronización de flota por activación voluntaria
Activación voluntaria por módulo mediante REG_FLEET_CONFIG.bit0 (GC_ENABLE). Por defecto desactivada. El cambio surte efecto tras el reinicio (CMD_RESET suave o reinicio completo).
6.3.1 Secuencia de activación (una vez por módulo)
1. write REG_FLEET_CONFIG (0x27) = 0x01 # bit0 = GC_ENABLE
2. issue CMD_SAVE_USER_CONFIG (opcode 0x32, ungated)
3. issue CMD_RESET (opcode 0x01)
4. wait ~300 ms boot
5. verify: read REG_FLEET_CONFIG → bit 0 should be 1
6.3.2 Formato de la trama GC
I²C general-call address 0x00 | A5 27 (5-byte payload)
A5: magic de trama.27: código de operaciónCMD_LATCH_PERIOD.:0x00= llamada a todos; si no, debe coincidir conREG_GROUP_ID (0x28)del dispositivo.: contador de ticks de 16 bits del lado del maestro (para la numeración de ventanas de toda la flota y la detección de tramas perdidas por módulo medianteGC_TICK (0x59)).
Solo instantánea: las tramas GC no llevan opcodes destructivos (SAVE_*, COMMIT_ADDR, FACTORY_RESET, etc.), por diseño.
6.3.3 Detección de modos de fallo: 2 niveles
Nivel 1: NACK de la dirección de llamada general (inmediato, a nivel de bus):
- Si GC está desactivada en toda la flota → el master recibe un error duro (NACK en la dirección
0x00, o el equivalente del controlador). - Se trata de un error duro, NO de un descarte silencioso: el master puede detectarlo y reaccionar.
- Disparo: NACK en GC = «GC no está habilitada en ningún dispositivo de la flota».
Nivel 2: testigo por módulo (tras la estabilización):
- Si no hay NACK (al menos un módulo escucha), el maestro lee
REG_V03_PERIOD_VALID (0x07)de cada esclavo esperado. 1= la instantánea se realizó correctamente en ese módulo.0= GC está desactivada en ese módulo concreto, o el período actual está vacío.
Recurra a la instantánea por dispositivo si el testigo informa 0:
foreach module where witness == 0:
write_cmd(module, CMD_LATCH_PERIOD)
sleep(50 ms)
foreach module: read period snapshot with skip_latch=true
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmpFleet::gcLatch(group, tick, settle_ms) / RbAmpFleet::checkSync() |
envíe la trama de instantánea General Call; compruebe cada módulo |
| ESP-IDF | rbamp_fleet_gclatch() / rbamp_fleet_check_sync() |
envíe la trama de instantánea General Call; compruebe cada módulo |
| Python | fleet.gc_latch(group, tick, settle_ms) / fleet.check_sync(expected_tick) |
envíe la trama de instantánea General Call; compruebe cada módulo |
| ESPHome | fleet_gc_enable: / registro de comprobación de sincronía |
instantánea General Call opcional; línea de registro que confirma que los módulos están sincronizados |
6.4 Sincronización de período: dos estrategias
Estrategia 1: instantánea secuencial + asentamiento compartido (cualquier firmware)
for module in modules:
write_cmd(module, CMD_LATCH_PERIOD)
sleep(50 ms)
for module in modules:
read_period_snapshot(module) # skip_latch=true
Desfase entre módulos: unos 1 ms por módulo a 50 kHz. Con 16 módulos, respecto a un período de 60 segundos, son 0.027 %. Despreciable para la contabilidad tarifaria.
Estabilización tras CMD_LATCH_PERIOD:
- Mínimo 50 ms antes de leer
V03_PERIOD_VALID (0x07)o la instantánea de período; esto cubre la latencia de instantánea en el peor caso (1 período de red @ 50 Hz = 20 ms + confirmación RT + estabilización del periférico I²C). - Opcionalmente, el master puede sondear
STATUS.bit0 (READY)en lugar de dormir un tiempo fijo:READY=1significa que el bloque RT está en un estado coherente, así que la instantánea de período puede leerse en ráfaga con seguridad. - En un módulo recién encendido (< ~100 ms tras el arranque desde v1.2; < 200 ms antes) una instantánea puede devolver
V03_PERIOD_VALID = 0porque aún no se ha acumulado 1 período de red: vea la cronología de arranque en frío, §6.0.
Estrategia 2: instantánea de difusión por General Call (requiere habilitación)
Desfase = 0 (atómico a nivel de bus). Vea §6.3.
Cuándo usar cada uno:
- < 8 módulos: Estrategia 1 (más sencilla, no requiere habilitación).
- ≥ 8 módulos o sincronización estricta: Estrategia 2.
- Un método por módulo:
CMD_LATCH_PERIODdireccionado y la instantánea de difusión GC reinician el mismo acumulador único; mezclarlos en un módulo acorta el periodo en curso. El respaldo por módulo (§6.3.3) es seguro porque solo se dispara en un módulo que la difusión no alcanzó.
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::readPeriodSnapshot(..., skip_latch=true) / RbAmpFleet::gcLatch() |
lectura secuencial tras una instantánea compartida; trama de instantánea por llamada general |
| ESP-IDF | rbamp_read_period_snapshot(..., skip_latch=true) / rbamp_fleet_gclatch() |
lectura secuencial tras una instantánea compartida; trama de instantánea por llamada general |
| Python | instantánea secuencial, skip_latch=True / fleet.gc_latch() |
lectura secuencial tras una instantánea compartida; trama de instantánea por llamada general |
| ESPHome | latch_interval: / fleet_gc_enable: |
cadencia de instantánea separada; instantánea General Call opcional |
6.5 Aprovisionamiento: grabado nuevo + SAVE
Comportamiento de un módulo recién grabado:
- En el primer arranque tras grabar el firmware:
REG_ERROR = 0xFB (FLASH_PARAMS_BAD)+ bit3 deEVENT_FLAGSactivado. - La página de parámetros no está inicializada → se cargan los valores de fábrica.
Esto es NORMAL en un módulo virgen y no es fatal. No aborte el aprovisionamiento por un 0xFB en el primer arranque.
Recovery:
1. configure SENSOR_CLASS + CT_MODEL (per §6.2)
2. (optional) configure FLEET_CONFIG + GROUP_ID + LABEL
3. issue CMD_SAVE_USER_CONFIG (opcode 0x32, ungated)
4. wait ~700 ms (flash write)
5. verify: REG_ERROR = 0x00, EVENT_FLAGS.bit3 cleared
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmpFleet::provision() / RbAmp::saveUserConfig() |
mueva un módulo virgen a su dirección; guarde la configuración de usuario |
| ESP-IDF | rbamp_provision() / rbamp_save_user_config() |
mueva un módulo virgen a su dirección; guarde la configuración de usuario |
| Python | aprovisionamiento de flota / dev.save_user_config() |
aprovisione un módulo virgen, luego añádalo a la flota; guarde la configuración de usuario |
| ESPHome | Flujo de aprovisionamiento / new_address: |
YAML paso a paso para un módulo virgen; cambio de dirección de una sola vez |
6.7 Recuperación de estado de error: árbol de decisión
Si en el arranque o en ejecución STATUS.bit1 (ERROR) = 1, o si está activado el indicador duradero EVENT_FLAGS.bit3 (ERROR), el master lee REG_ERROR (0x02) y decide según el código:
read REG_ERROR (0x02):
0x00 → no error (false signal — clear stale EVENT bit3 via W1C)
action: write 1<<3 → EVENT_FLAGS (W1C clear)
0xF9 → CLONE (reserved)
action: not raised. If ever observed, treat as
vendor-reserved and contact the supplier.
0xFA → LUT_BAD (calibration LUT corrupted)
action: device unusable for measurement. Factory recovery required.
0xFB → FLASH_PARAMS_BAD (params page uninitialized — virgin module)
action: NORMAL for a freshly flashed module. Provision per §6.5
(configure SENSOR_CLASS/CT_MODEL/...; issue CMD_SAVE_USER_CONFIG).
Cleared after a successful SAVE.
0xFC → NOT_READY (transient; module still booting)
action: wait 50 ms, retry. If persistent > 300 ms — power cycle.
0xFD → SENSOR_OVERFLOW (transient; signal saturated)
action: physical overload detected. The chosen CT clamp has
insufficient range for the measured current, or a real overload.
Issue CMD_CLEAR_ERROR (0x31) after the cause is removed.
0xFE → PARAM (last operation rejected — invalid argument / unknown opcode;
EVENT bit3 set. Very early images, 1.2–1.4.3, ignored unknown
opcodes silently)
action: master-side bug — review the last write. Issue CMD_CLEAR_ERROR
after fixing the master logic.
0xFF → UNHANDLED (firmware-side anomaly)
action: open an issue with the vendor; CMD_CLEAR_ERROR attempts to clear.
If persistent after CMD_RESET — the device is suspect.
Flujo general de recuperación ante errores transitorios (0xFC/0xFD/0xFE):
1. capture context (what was the last write? master state?)
2. issue CMD_CLEAR_ERROR (opcode 0x31)
3. wait 5 ms
4. re-read STATUS / REG_ERROR — verify cleared
Para errores persistentes: emita CMD_RESET y recorra la cronología de arranque en frío (§6.0). Si el error persiste tras el reinicio y no es 0xFB (grabado nuevo), contacte con el soporte del fabricante.
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::readLastError() / RbAmp::clearError() |
lea el código de error; bórrelo |
| ESP-IDF | rbamp_read_last_error() / rbamp_clear_error() |
lea el código de error; bórrelo |
| Python | dev.read_last_error() / dev.clear_error() |
lea el código de error; bórrelo |
| ESPHome | write_clear_error() / write_reset() |
borre el error; reinicio suave del módulo |
6.6 Referencia de comandos
Códigos de operación básicos (escritura en REG_COMMAND (0x01))
| Código de operación | Nombre | Estabilización | Restringido | Notas |
|---|---|---|---|---|
0x01 |
RESET |
~300 ms | – | Reinicio blando (HAL_NVIC_SystemReset) |
0x27 |
LATCH_PERIOD |
50 ms | – | Vuelca los contadores RT en la instantánea de periodo |
0x28 |
SET_CT_MODEL_CH0 |
5 ms | – | Vincule el REG_CT_MODEL en staging al canal 0 |
0x29 |
SET_CT_MODEL_CH1 |
5 ms | – | Vincule el REG_CT_MODEL en staging al canal 1 |
0x2A |
SET_CT_MODEL_CH2 |
5 ms | – | Vincule el REG_CT_MODEL en staging al canal 2 |
0x30 |
COMMIT_ADDR |
700 ms | – | Persista I2C_ADDRESS (véase §6.1) |
0x31 |
CLEAR_ERROR |
0 | – | Borre REG_ERROR (solo clases transitorias; CLONE (0xF9) está reservado, no se eleva) |
0x32 |
SAVE_USER_CONFIG |
700 ms | – | Persistir el grupo user_config (apto para producción) |
Los códigos de operación fuera del rango público (uso de fábrica) no están documentados en esta referencia. Un master de consumo no los envía en funcionamiento normal; un código no soportado → REG_ERROR = ERR_PARAM (0xFE).
7 · Semántica
7.0 Resistencia de la flash y comportamiento al reiniciar
Recordatorio: antes del firmware 1.4.20, un reinicio también devuelve el escalado del modelo de CT aplicado al valor de fábrica (CAPABILITY bit 12 a 0); véase §6.2.
Resistencia de la flash: ~10 000 ciclos por página (típico, especificación del fabricante). Cada CMD_SAVE_USER_CONFIG o CMD_COMMIT_ADDR es un ciclo de borrado y escritura en la página de parámetros.
⚠ No haga bucles de SAVE/COMMIT en un bucle de ejecución. Con 1 SAVE/s un módulo se quema en unas 3 horas. El aprovisionamiento se hace una vez en la instalación; no se requieren actualizaciones de configuración en tiempo de ejecución (un maestro de consumo rara vez las cambia).
Retención: normalmente 10 años o más a la temperatura de funcionamiento habitual.
Comparación del comportamiento al reiniciar:
| Tipo de reinicio | Conservado | Borrado |
|---|---|---|
CMD_RESET (0x01) |
flash (configuración, dirección, etiqueta, ganancias, NF) | RAM (UPTIME, ZC_OFFSET, EVENT_FLAGS, salvo el bit RESET_OCCURRED bit 5 activado al arrancar; THRESH_*; DIGEST_CONFIG) |
| Pin de ciclo de alimentación / reinicio en caliente | flash | igual que CMD_RESET más cualquier RAM externa retenida en el lado del host |
CMD_FACTORY_RESET (0xAA) (solo en modo fábrica) |
nada | todo: el bloque completo de parámetros, incluida la calibración de fábrica de los canales |
⚠ CMD_FACTORY_RESET no es un «restaurar valores por defecto» de nivel de usuario. Reescribe todo el bloque de parámetros, incluida la calibración de fábrica de los canales, y el módulo lo acepta solo en modo fábrica: es una operación de fabricación, no un paso de servicio. Un módulo BASIC no tiene comando de reinicio de usuario. Para devolver un módulo a un estado conocido, use CMD_RESET (0x01) (reinicio suave: no se toca nada de la flash) y vuelva a aprovisionar la configuración de usuario con CMD_SAVE_USER_CONFIG (0x32).
Patrón de bits de RESET_OCCURRED (canónico):
- Tras un reinicio, al arrancar:
EVENT_FLAGS.bit5 = 1. - El master ve el bit 5 → sabe que el módulo se reinició → debe reinicializar los campos solo en RAM (DIGEST_CONFIG, THRESH_*, EVENT_MASK).
- El maestro borra el bit 5 mediante W1C:
escriba 1<<5 → EVENT_FLAGS.
7.1 Modelo de persistencia
| Comando | Producción | Persiste |
|---|---|---|
CMD_SAVE_USER_CONFIG (0x32) |
✅ OK | i2c_address (mediante dos fases), ct_model, sensor_class, fleet_config, group_id, label |
CMD_COMMIT_ADDR (0x30) |
✅ OK (armado con magic) | i2c_address |
CMD_RESET (0x01) |
✅ OK | — (reinicio suave) |
CMD_LATCH_PERIOD (0x27) |
✅ OK | — (toma la instantánea del periodo) |
CMD_CLEAR_ERROR (0x31) |
✅ OK | — (borra REG_ERROR) |
CMD_SAVE_GAINS (0x26) |
❌ BLOQUEADO en producción (rechazado: REG_ERROR = 0xFE; el reinicio lo revierte) |
calibración de fábrica |
CMD_FACTORY_RESET (0xAA) |
❌ BLOQUEADO en producción | — |
7.2 Lectura de vuelta ≠ persistencia
⚠ La protección de producción acepta la escritura en RAM (una lectura posterior devuelve el valor escrito), pero el guardado en flash puede ser rechazado. Tras el reinicio el valor vuelve a su estado previo a la escritura.
La única forma válida de confirmar la persistencia es CMD_RESET + espera de arranque + nueva lectura:
1. write target_reg(...)
2. issue CMD_RESET (0x01)
3. wait ~300 ms boot
4. re-read target_reg
5. assert read == written # only now is persistence confirmed
La dirección es una excepción (canónico v1.3): REG_I2C_ADDRESS (0x30) al arrancar lee la dirección activa. Tras la preparación devuelve el candidato; tras el reinicio muestra el valor realmente persistido.
7.3 Advertencia sobre la referencia de tensión única
El módulo usa un canal de tensión U para calcular P en todos los canales de corriente. Si una pinza CT está en un cable de otra fase (cuadro de distribución polifásico), las lecturas de P de ese canal serán erróneas (desfase arbitrario entre U e I). I_RMS sigue siendo correcto.
La medición polifásica (L1/L2/L3 simultáneamente) es un modelo aparte con su propia especificación.
7.4 Integración de energía en el master: referencia del reloj de pared
⚠ V03_PERIOD_LATCH_MS (0xEC) es un temporizador de diagnóstico del módulo; puede leerse corto bajo carga: use el reloj del maestro para la energía.
Integración canónica de energía en el master:
# CORRECT — master wall-clock
t_now = master_clock()
dt_s = (t_now - t_prev_latch) / time_unit
energy_wh[ch] += avg_p[ch] * dt_s / 3600
t_prev_latch = t_now
# WRONG — the module diagnostic timer may read short under load
dt_chip_s = read_u32(0xEC) / 1000.0
energy_wh[ch] += avg_p[ch] * dt_chip_s / 3600 # systematically under-reported
La medida del módulo sobre la ventana cerrada es V03_PERIOD_COMMIT_CNT (0xBE) multiplicado por la duración de la confirmación. Cuenta confirmaciones RT completas y no se ve afectada por la inanición del temporizador que hace que V03_PERIOD_LATCH_MS se lea corto. Una confirmación = 0.1 s desde v1.2; las imágenes anteriores usaban 0.2 s. Para saber cuál aplica sin tabla de versiones: el cociente V03_PERIOD_LATCH_MS / V03_PERIOD_COMMIT_CNT sale cercano a 100 o cercano a 200. Úselo para comprobaciones cruzadas; el reloj de pared del master sigue siendo la referencia para la contabilidad tarifaria.
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::energyWh(ch) |
total de Wh acumulado de un canal |
| ESP-IDF | rbamp_energy_wh() |
total de Wh acumulado de un canal |
| Python | dev.energy.wh(ch) |
total de Wh acumulado de un canal |
| ESPHome | energy |
Contador de Wh por canal |
7.5 Conservación del periodo tras una instantánea fallida
El firmware CONSERVA el acumulador de periodo ante una instantánea vacía. Cuando g_period_count == 0 (una instantánea sin periodo legible):
REG_V03_PERIOD_VALID = 0(señal caducada).period_start_msse conserva → la siguiente instantánea correcta cubre el intervalo completo previsto por el master.
Implicación: el maestro no pierde datos con una instantánea desactualizada. Patrón para la integración en el maestro:
issue snapshot
if PERIOD_VALID == 1:
integrate(avg_p, master_dt)
reset_master_clock
# else: skip integration (FW will automatically recover on the next success)
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::readPeriodSnapshot() / RbAmp::isPeriodValid() |
tome una instantánea de período e integre solo si es válida; compruebe el bit de listo |
| ESP-IDF | rbamp_read_period_snapshot() / rbamp_is_period_valid() |
tome una instantánea de período e integre solo si es válida; compruebe el bit de listo |
| Python | dev.read_period_snapshot() / RbAmpStaleError |
tome una instantánea de período; se eleva cuando la instantánea no está lista, la siguiente cubre el intervalo completo |
| ESPHome | Instantánea de período no válida | se registra cuando el indicador de validez es 0; la primera instantánea tras el arranque se descarta |
7.6 Tolerancia a la deriva del reloj
Canon: la base de tiempos interna del módulo puede leerse corta bajo carga, hasta un 30 %: esto es normal, es una propiedad de la base de tiempos del módulo, por diseño. Medido en hardware con carga de producción.
Aceptación: el chip es correcto con una deriva ≤ 30 %.
⚠ El umbral heredado del 3 % es ERRÓNEO. Ese umbral rechazaría en masa chips sanos.
7.7 Resistencia a EMI y transitorios de conmutación
Las lecturas durante la conmutación activa de relés (EMI de 5 A) fallan ~67 % de las veces (medido en hardware). Las lecturas en régimen permanente son fiables. El bus se recupera solo, no se produce bloqueo y no se pierden módulos.
Patrón del master: reintento a nivel de aplicación (obligatorio al conmutar cargas inductivas):
for attempt in range(5):
result = read_register(...)
if result is OK:
return result
sleep(20 ms)
raise IOError("read failed after retries")
El bus_reset solo en el maestro no basta cuando un pico de EMI se solapa con la ventana de reintentos del driver.
7.8 Resumen de limitaciones conocidas
Lista consolidada de características conocidas que el master debe tener en cuenta:
| Tema | Comportamiento | Véase |
|---|---|---|
| Deriva del temporizador del chip | Puede leerse corto bajo carga, hasta un 30 % (márgenes de aceptación) | §7.4, §7.6 |
| Conmutación de relés (EMI) | ~67 % de tasa de fallo de lectura durante la conmutación; el bus se recupera solo | §7.7 |
EVENT.bit3 latencia asíncrona |
hasta una ventana (~100 ms; 200 ms antes de la v1.2) desde el rechazo de la escritura hasta que se activa el bit 3 | §5.3 |
V03_PERIOD_LATCH_MS (0xEC) |
Temporizador de diagnóstico del módulo; puede leerse corto bajo carga. El maestro usa su propio reloj de pared | §4.13, §7.4 |
Semántica de REG_ERROR (0x02) |
Resultado de la última escritura (no persistente); bit 3 de EVENT = señal duradera | §5.3 |
I_RMS = 0.0 |
Por debajo del suelo de ruido (medida válida), NO es «sin datos» | §5.4.3 |
U_RMS/U_PEAK/P en variantes I |
Se lee como 0.0 (válido solo si el bit 8 de CAPABILITY = 1) |
§4.10, §7.3 |
| ESCRITURA de varios bytes | Sin autoincremento; hace falta un bucle byte a byte | §5.1 |
| Verificación del cambio de dirección | Mediante un escaneo del bus en la nueva dirección; 0x30 también es fiable tras el reinicio |
§6.1 |
| Arranque tras la primera grabación de flash | REG_ERROR = 0xFB es normal; SAVE lo borra |
§6.5 |
| GC por defecto | DESACTIVADA (opcional por módulo); NACK en GC = «no habilitada» | §6.3 |
| Resistencia de la flash | ~10 000 ciclos por página; no haga bucles de SAVE | §7.0 |
8 · Ejemplos de trazas del cable
8.1 Detección: lea PRODUCT_ID + HW_VARIANT + CAPABILITY
# I²C operations on default slave addr 0x50
S 0xA0 W 0x54 Sr 0xA1 R [PRODUCT_ID] P # read 0x54
S 0xA0 W 0x55 Sr 0xA1 R [HW_VARIANT] P # read 0x55
S 0xA0 W 0x57 Sr 0xA1 R [CAP_lo][CAP_hi] P # burst-read 0x57..0x58 (auto-increment)
Donde S=inicio, Sr=inicio repetido, P=parada, W=bit de escritura, R=bit de lectura, 0xA0=dirección de esclavo 0x50 << 1.
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::readVariant() / RbAmp::readCapability(out) |
lea la variante de hardware; lea el mapa de capacidades |
| ESP-IDF | rbamp_read_variant() / rbamp_read_capability() |
lea la variante de hardware; lea el mapa de capacidades |
| Python | dev.read_variant() / dev.read_capability() |
lea la variante de hardware; lea el mapa de capacidades |
| ESPHome | get_variant_str() / get_capability_hex() |
la variante en texto; el mapa de capacidades en hexadecimal |
8.2 Lectura en ráfaga del bloque RT (variante UI, todos los canales)
# Read all of V03 RMS + P + PF (0x86..0xBD) — 56 bytes, atomic via read-freeze
S 0xA0 W 0x86 Sr 0xA1 R [56 bytes] P
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::readAll(snapshot) |
lea todo el bloque de tiempo real en una sola llamada |
| ESP-IDF | rbamp_read_all() |
lea todo el bloque de tiempo real en una sola llamada |
| Python | dev.read_all() |
lea todo el bloque de tiempo real en una sola llamada |
| ESPHome | lectura en ráfaga del bloque instantáneo | el componente lee el bloque instantáneo en una sola ráfaga por actualización |
8.3 ESCRITURA de varios bytes: LABEL byte a byte
# WRONG: burst-write — only 'M' is accepted
S 0xA0 W 0x68 'M' 'y' 'M' 'e' 't' 'e' 'r' '1' P
# CORRECT: byte-at-a-time loop
S 0xA0 W 0x68 'M' P
S 0xA0 W 0x69 'y' P
S 0xA0 W 0x6A 'M' P
S 0xA0 W 0x6B 'e' P
S 0xA0 W 0x6C 't' P
S 0xA0 W 0x6D 'e' P
S 0xA0 W 0x6E 'r' P
S 0xA0 W 0x6F '1' P
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::writeLabel(label) / RbAmp::readLabel(out) |
escriba la etiqueta de 8 bytes (solo BASIC); léala de vuelta |
| ESP-IDF | rbamp_write_label() / rbamp_read_label() |
escriba la etiqueta de 8 caracteres; léala de vuelta |
| Python | dev.set_label(label) / dev.read_label() |
escriba la etiqueta de 8 bytes; léala de vuelta |
| ESPHome | — | opción de etiqueta no documentada |
8.4 Instantánea de difusión GC + respaldo por testigo
# Send GC frame: A5 27
S 0x00 W 0xA5 0x27 0x00 0x2A 0x00 P
# Wait 50 ms settle
# Witness check for every expected module
foreach module in [0x50, 0x51, 0x52]:
S (module<<1)|W 0x07 Sr (module<<1)|R [VALID] P
if VALID != 1:
# Fall back to per-device snapshot
S (module<<1)|W 0x01 0x27 P # CMD_LATCH_PERIOD
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmpFleet::gcLatch(group, tick, settle_ms) / RbAmpFleet::checkSync() |
envíe la trama de instantánea General Call; compruebe cada módulo |
| ESP-IDF | rbamp_fleet_gclatch() / rbamp_fleet_check_sync() |
envíe la trama de instantánea General Call; compruebe cada módulo |
| Python | fleet.gc_latch(group, tick, settle_ms) / fleet.check_sync(expected_tick) |
envíe la trama de instantánea General Call; compruebe cada módulo |
| ESPHome | fleet_gc_enable: / registro de comprobación de sincronía |
instantánea General Call opcional; línea de registro que confirma que los módulos están sincronizados |
8.5 Cambio de dirección en 5 pasos
# 1. Stage candidate addr (0x51) → REG_I2C_ADDRESS
S 0xA0 W 0x30 0x51 P
# 2. Arm magic → ADDR_COMMIT_MAGIC
S 0xA0 W 0x31 0xA5 P
# 3. Issue CMD_COMMIT_ADDR (opcode 0x30) → REG_COMMAND
S 0xA0 W 0x01 0x30 P
# 4. Wait 700 ms flash write
# 5. Issue CMD_RESET (opcode 0x01) → REG_COMMAND
S 0xA0 W 0x01 0x01 P
# Wait ~300 ms boot
# Verify: probe the new addr
S 0xA2 W 0x55 Sr 0xA3 R [HW_VARIANT] P # 0xA2 = 0x51 << 1
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::prepareAddressChange(new_addr) / RbAmp::commitAddressChange() |
prepare y arme la nueva dirección, luego confírmela |
| ESP-IDF | rbamp_prepare_address_change() / rbamp_commit_address_change() |
prepare y arme la nueva dirección, luego confírmela |
| Python | dev.prepare_address_change(new_addr) / dev.commit_address_change() |
prepare y arme la nueva dirección, luego confírmela |
| ESPHome | new_address: |
cambio de dirección puntual al arrancar; elimine la opción después |
8.6 Aprovisionamiento tras grabado nuevo
# 1. Check fresh-flash state
S 0xA0 W 0x02 Sr 0xA1 R [0xFB] P # ERR_FLASH_PARAMS_BAD — normal
# 2. Configure sensor_class
S 0xA0 W 0x25 0x01 P # SCT_013
# 3. Stage CT model + bind ch0
S 0xA0 W 0x05 0x03 P # SCT-013-030
S 0xA0 W 0x01 0x28 P # CMD_SET_CT_MODEL_CH0
# Wait 5 ms
# 4. Save user_config
S 0xA0 W 0x01 0x32 P # CMD_SAVE_USER_CONFIG
# Wait 700 ms
# 5. Verify: REG_ERROR should be 0x00 (read IMMEDIATELY before the next write)
S 0xA0 W 0x02 Sr 0xA1 R [0x00] P
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::configureChannels(cls, models, n) / RbAmp::saveUserConfig() |
establezca la clase y los modelos de todos los canales; guarde la configuración de usuario |
| ESP-IDF | rbamp_configure_channels() / rbamp_save_user_config() |
establezca la clase y los modelos de todos los canales; guarde la configuración de usuario |
| Python | dev.configure_channels(cls, models) / dev.save_user_config() |
establezca la clase y los modelos de todos los canales; guarde la configuración de usuario |
| ESPHome | sensor_class: / ct_model: |
Opciones YAML para la clase de sensor y el modelo de CT |
8.7 Ida y vuelta de DIGEST: configurar + leer
# 1. Configure digest mask: I_RMS + U_RMS + P_REAL (bits 0+1+2 = 0x07)
S 0xA0 W 0x29 0x07 P
# 2. Wait one RT-commit cycle (~100 ms from v1.2; waiting 200 ms covers all images; or poll STATUS.bit0)
# 3. Burst-read the digest window (22 bytes)
S 0xA0 W 0x70 Sr 0xA1 R [22 bytes] P
# Parse the layout per DIGEST_CONFIG = 0x07 on UI1 (N_I = 1):
# byte[0] = STATUS_MIRROR
# byte[1] = SEQ
# byte[2..3] = I_RMS[0] u16 (0.01 A units)
# byte[4..5] = U_RMS u16 (0.1 V units)
# byte[6..7] = P[0] i16 (1 W units)
# byte[8..21] = unused (0x00)
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | — | ventana de resumen no expuesta |
| ESP-IDF | rbamp_set_digest_fields() / rbamp_read_digest() |
elija los campos del digest; léalos en una sola transacción (BASIC) |
| Python | — | ventana de resumen no expuesta |
| ESPHome | — | ventana de resumen no expuesta |
8.8 Flujo de eventos de umbral: escribir umbral → disparo → borrado W1C
# 1. Write current threshold = 30 A (0x0BB8 in 0.01 A units → 2 bytes LE)
S 0xA0 W 0x2C 0xB8 P # LO byte
S 0xA0 W 0x2D 0x0B P # HI byte
# 2. Unmask THRESH_I event (bit 1) → DRDY solid-LOW on trip
S 0xA0 W 0x2B 0x02 P # EVENT_MASK = bit 1 only
# 3. (runtime) The master polls EVENT_FLAGS
S 0xA0 W 0x2A Sr 0xA1 R [event_flags] P
# event_flags == 0x02 → threshold tripped
# 4. (optional) Read context — REG_ERROR, RT block, etc.
# 5. Clear EVENT_FLAGS.bit1 via W1C
S 0xA0 W 0x2A 0x02 P
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::setEventThresholds(i_amps, p_watts) / RbAmp::readEventFlags(out) |
establezca los umbrales de corriente y potencia; lea y limpie los indicadores de evento |
| ESP-IDF | rbamp_set_event_thresholds() / rbamp_read_event_flags() |
establezca los umbrales de corriente y potencia; lea y limpie los indicadores de evento |
| Python | dev.read_event_flags() |
lea y borre los indicadores de evento (no hay función de fijar el umbral en el dispositivo) |
| ESPHome | Alarmas de umbral en YAML / get_event_flags() |
automatizaciones por umbral sobre valores de sensor; los indicadores de evento |
8.9 Ráfaga de diagnóstico de captura bruta (CAPTURE_*)
CMD_CAPTURE_RAW (0x38) y los registros CAPTURE_* son una facilidad de diagnóstico: no hacen falta en funcionamiento normal; úselos solo cuando el proveedor lo pida para capturar muestras brutas.
# 1. Arm raw-capture
S 0xA0 W 0x01 0x38 P # CMD_CAPTURE_RAW (opcode 0x38)
# Wait ~80 ms (3 DMA-TC cycles)
# 2. Check ready
S 0xA0 W 0x18 Sr 0xA1 R [status & 0x01] P # bit 0 = ready
# 3. Select page 0 (16 raw I0 samples → CAPTURE_WINDOW)
S 0xA0 W 0x19 0x00 P
# 4. Burst-read CAPTURE_WINDOW (32 bytes = 16×u16 LE samples)
S 0xA0 W 0x1A Sr 0xA1 R [32 bytes] P
# Repeat steps 3-4 for pages 1..15 (256 samples total ≈ 1.3 mains periods)
8.10 Lectura de vuelta del espejo de verificación del modelo de CT (comprobación tras la vinculación)
# After the §6.2 sequence — verify the applied state per channel via 0x51..0x53 (burst):
S 0xA0 W 0x51 Sr 0xA1 R [model_ch0][model_ch1][model_ch2] P
# Expected on UI2 mixed-CT (e.g. ch0=SCT-013-005, ch1=SCT-013-030):
# byte[0] = 0x01 # SCT-013-005 applied on ch0
# byte[1] = 0x03 # SCT-013-030 applied on ch1
# byte[2] = 0x00 # unused (UI2 N_I=2)
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::readCTModelCh(channel, out) |
lea el modelo de CT realmente aplicado en un canal |
| ESP-IDF | rbamp_read_ct_model_ch() |
lea el modelo de CT realmente aplicado en un canal |
| Python | dev.read_ct_model_ch(ch) |
lea el modelo de CT realmente aplicado en un canal |
| ESPHome | registro de arranque ct_model[0]: matches |
líneas de registro que confirman que se aplicaron la clase de sensor y el modelo |
9 · Aceptación / tolerancia
| Parámetro | Umbral | Fuente |
|---|---|---|
| Deriva de reloj del chip frente al reloj de pared del master | ≤ 30 % | validado en banco |
| Tasa de fallos de lectura por conmutación de relés (EMI) | hasta ~67 % durante la conmutación | validado en banco |
| Tasa de NACK del bus (I²C de Linux/ESP a 100 kHz sin reintentos) | hasta ~20 % | característica del lado del host |
| Tasa de NACK del bus a 50 kHz + 3 reintentos | < 0.8 % | validado en banco |
Valor de REG_ERROR en el arranque tras grabar la flash por primera vez |
0xFB (FLASH_PARAMS_BAD) |
NORMAL en un módulo virgen |
| Arranque en frío hasta la primera medición válida | ~250 ms | típico |
10 · Registro de cambios
1.3.0 (2026-06-15): primera publicación pública.
Firmware de referencia: protocol_version = 1.3, schema_version = 2. Contrato de la página 0 congelado.
Cambios principales de la v1.3 frente a versiones internas anteriores
- Staging puro de CT_MODEL:
REG_CT_MODEL (0x05)ya no se aplica automáticamente a ch0 al escribir. La vinculación se hace solo medianteCMD_SET_CT_MODEL_CHn(independiente del orden). - Commit en dos fases de la dirección (apto para producción):
I2C_ADDRESSse persiste medianteADDR_COMMIT_MAGIC+CMD_COMMIT_ADDR.REG_I2C_ADDRESSlee la dirección activa al arrancar. - REG_ERROR = resultado de la última escritura (no persistente).
EVENT_FLAGS.bit3es la señal duradera (W1C persistente; se activa en una ventana, ~100 ms, tras el rechazo de la escritura). - Opcodes desconocidos / enumeraciones fuera de rango → rechazados:
REG_ERROR = ERR_PARAM (0xFE)+EVENT.bit3. Las imágenes muy tempranas (1.2–1.4.3) ignoraban en silencio los opcodes desconocidos. - Aprovisionamiento tras la primera grabación de flash:
ERR_FLASH_PARAMS_BAD (0xFB)en un módulo virgen → se borra medianteCMD_SAVE_USER_CONFIG. - Instantánea de difusión GC: activación voluntaria por módulo mediante
FLEET_CONFIG.bit0(por defecto DESACTIVADA; surte efecto tras el reinicio). NACK con la función desactivada = error grave, no silencioso. - Asimetría lectura/escritura por diseño: la LECTURA admite autoincremento ✅; la ESCRITURA exige byte a byte ❌ (confirmado en hardware).
- Registro CAPABILITY (0x57/0x58 u16 LE): mapa de bits de funciones; detecte las funciones bit a bit (§3.2), nunca comparando el valor completo; bit 12 = SCT_RATING_SELF (fw 1.4.20+).
- Atomicidad: el bloque RMS V03 y el Digest tienen congelación de lectura (lectura en ráfaga atómica); los espejos GC_TICK / I2C_ADDRESS / CT_MODEL_CHn se leen dos veces y deben coincidir.
- Semántica de la pinza NF:
I_RMS = 0.0significa «por debajo del nivel de ruido», una medición válida. - AC_FREQ con origen en cruce por cero en todas las variantes (incluidas las solo I).
- La integración de energía del master debe usar su propio reloj de pared, no
V03_PERIOD_LATCH_MS (0xEC)(temporizador de diagnóstico del módulo, que puede leerse corto bajo carga).