02 · Inicialización y arranque
rbAmp empieza a medir de inmediato tras el encendido. El maestro solo necesita:
- Inicie su bus I²C (inicialización estándar de
Wire/ HAL). - Espere ~250 ms, o sondee
DATA_VALID = 1en el registro0xCE. - Opcionalmente, lea la versión del firmware desde
0x03como comprobación de cordura. - Datos listos para leer.
No hace falta comando de inicio ni configuración a nivel de registro en el chip. La calibración de fábrica se carga automáticamente al arrancar, así que el módulo emite valores en unidades físicas correctas desde la primera lectura.
Importante para los módulos BASIC de la serie SCT usados con sensores SCT-013: tras la primera instalación, debe escribir el modelo del sensor en el registro de modelo. El módulo necesita el modelo para aplicar el coeficiente mV-por-amperio correcto. El código del modelo se guarda en flash y sobrevive a los reinicios. En firmware anterior a 1.4.20 (bit 12 de CAPABILITY a 0) el escalado aplicado vuelve al valor de fábrica tras un reinicio del módulo: un master que haya seleccionado un modelo distinto del de fábrica debe volver a confirmarlo tras cada reinicio detectado del módulo (vea Qué persiste tras un reinicio y la regla de detección de reinicio en period-metering.md); desde el firmware 1.4.20 el cambio de modelo sobrevive a un reinicio. En imágenes anteriores a 1.4.20, la energía será errónea tras cualquier reinicio del módulo a menos que se vuelva a confirmar CT_MODEL. Las bibliotecas cliente gestionan ambos casos por usted. Los detalles están en la sección Configuración de la clase del sensor y del modelo de CT más abajo.
Los módulos BASIC de la serie CT se suministran en pareja con sus sensores, preconfigurados y calibrados de fábrica para ese sensor; arrancan sin inicialización.
En las bibliotecas cliente: 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 |
Funciones auxiliares (C neutral respecto a la plataforma)
Todos los ejemplos siguientes usan tres funciones auxiliares fáciles de implementar en cualquier plataforma:
// Read one byte from a slave register.
uint8_t rb_read_u8(uint8_t addr, uint8_t reg);
// Read a little-endian float32 (4 bytes from reg, reg+1, reg+2, reg+3).
// rbAmp supports READ auto-increment — both per-byte access and a single
// 4-byte burst-read are valid. The helpers below show per-byte for clarity;
// production code often uses burst-read for atomicity guarantees (see ch 11).
float rb_read_float_le(uint8_t addr, uint8_t reg);
// Write one byte to a slave register.
void rb_write_u8(uint8_t addr, uint8_t reg, uint8_t val);
Puesta en marcha con Arduino (Wire.h)
Funciones auxiliares
#include
uint8_t rb_read_u8(uint8_t addr, uint8_t reg) {
Wire.beginTransmission(addr);
Wire.write(reg);
Wire.endTransmission(false); // repeated start, do not release bus
Wire.requestFrom(addr, (uint8_t)1);
return Wire.read();
}
float rb_read_float_le(uint8_t addr, uint8_t reg) {
uint8_t buf[4];
for (int i = 0; i < 4; i++) {
buf[i] = rb_read_u8(addr, reg + i);
}
float f;
memcpy(&f, buf, 4); // little-endian host (AVR, ESP32, ARM)
return f;
}
void rb_write_u8(uint8_t addr, uint8_t reg, uint8_t val) {
Wire.beginTransmission(addr);
Wire.write(reg);
Wire.write(val);
Wire.endTransmission();
}
Prueba de humo (un solo módulo)
#include
#define RB_ADDR 0x50
void setup() {
Serial.begin(115200);
Wire.begin();
Wire.setClock(50000);
delay(300); // wait for module boot
// Wait DATA_VALID bit
while ((rb_read_u8(RB_ADDR, 0xCE) & 0x01) == 0) {
Serial.println("waiting for DATA_VALID...");
delay(50);
}
uint8_t ver = rb_read_u8(RB_ADDR, 0x03);
Serial.printf("rbAmp ready, version 0x%02X\n", ver);
}
void loop() {
float u_rms = rb_read_float_le(RB_ADDR, 0x86);
float i_rms = rb_read_float_le(RB_ADDR, 0x8E);
float p = rb_read_float_le(RB_ADDR, 0xA6);
float pf = rb_read_float_le(RB_ADDR, 0xB2);
Serial.printf("U=%.1f V I=%.3f A P=%.1f W PF=%.3f\n",
u_rms, i_rms, p, pf);
delay(1000);
}
Use una carga de al menos ~1 % de la potencia nominal del sensor. Por debajo de ese valor lecturas son ruidosas y no se garantiza la clase. (Una lámpara de 60 W es solo el 0.9 % de una pinza de 30 A; véase la tabla de características). Con una pinza de 30 A, un hervidor de 2 kW es una buena carga de prueba de humo. En los módulos BASIC de la serie SCT con sensor SCT-013, configure la clase de sensor y el modelo de CT antes de la prueba de humo (véase Configuración de la clase de sensor y del modelo de CT); sin el modelo, las lecturas de corriente no tienen sentido.
Salida esperada (un hervidor de 2 kW a 230 V, pinza de 30 A):
rbAmp ready, version 0x04
U=229.8 V I=8.72 A P=2004 W PF=0.999
U=230.1 V I=8.73 A P=2008 W PF=0.999
...
Puesta en marcha con STM32 HAL (C)
#include "stm32f1xx_hal.h"
extern I2C_HandleTypeDef hi2c1;
#define RB_ADDR_8BIT (0x50 << 1) // HAL expects 8-bit address format
uint8_t rb_read_u8(uint8_t reg) {
uint8_t v;
HAL_I2C_Mem_Read(&hi2c1, RB_ADDR_8BIT, reg, I2C_MEMADD_SIZE_8BIT, &v, 1, 100);
return v;
}
float rb_read_float_le(uint8_t reg) {
uint8_t buf[4];
for (int i = 0; i < 4; i++) {
HAL_I2C_Mem_Read(&hi2c1, RB_ADDR_8BIT, reg + i, I2C_MEMADD_SIZE_8BIT,
&buf[i], 1, 100);
}
float f;
memcpy(&f, buf, 4);
return f;
}
void main_app(void) {
while ((rb_read_u8(0xCE) & 0x01) == 0) HAL_Delay(50);
uint8_t ver = rb_read_u8(0x03);
printf("rbAmp version: 0x%02X\n", ver);
while (1) {
float u = rb_read_float_le(0x86);
float i = rb_read_float_le(0x8E);
float p = rb_read_float_le(0xA6);
printf("U=%.1f V I=%.3f A P=%.1f W\n", u, i, p);
HAL_Delay(1000);
}
}
Módulos de la serie CT: arranque sin configuración
Un módulo de la serie CT se entrega con cada canal de corriente ya configurado: la clase del sensor, el calibre y la calibración se escriben en fábrica para la pinza que viene con ese canal. No se necesita ninguna escritura de inicialización: el host solo lee.
⚠ No escriba la clase del sensor ni el modelo del sensor en un módulo de la serie CT. - Escribir el modelo en un canal sustituye la calibración de fábrica de ese canal por un preajuste genérico: el error actual pasa a ser de −2…+3 % y el umbral de corriente baja es incorrecto. - Escribir la clase borra el modelo de todos los canales.
En firmware 1.4.22 y posteriores, un módulo de la serie CT rechaza las escrituras de clase y modelo en funcionamiento normal con ERR_PARAM (0xFE); las bibliotecas cliente las rechazan en todos los firmwares.
El canal y su pinza forman un par. Cada pinza lleva la etiqueta del canal al que pertenece. No mueva una pinza a otro canal ni conecte otra pinza a un canal: la calibración solo vale para el emparejamiento de fábrica. Los calibres son fijos; no hay calibre que elegir.
Secuencia de arranque
- Conecte las pinzas (con la flecha hacia la carga; vea hardware-connection.md) y alimente el módulo.
- Lea la clase (
SENSOR_CLASS,0x25):2= serie de pinzas CT. - Lea el modelo aplicado en cada canal (
0x51..0x53, un registro por canal; UI5/UI7 canales 3 y siguientes: a través de la ventana de acceso a canales, campoCT_MODEL) y asócielo con el calibre:
| Código de modelo | 0x06 |
0x07 |
0x08 |
0x09 |
0x0A |
0x0B |
0x0D |
|---|---|---|---|---|---|---|---|
| Calibre | 1 A | 5 A | 10 A | 20 A | 30 A | 50 A | 100 A |
Use el calibre para ajustar los rangos de visualización y validar las lecturas; el módulo ya informa en amperios.
- Sondee como en cualquier módulo BASIC: ventana de medición de 100 ms, pin de datos listo o lectura periódica (vea realtime-polling.md); medición de período como en period-metering.md.
No se requiere nada más: no hay selección de sensor, ni paso de ganancia, ni comando de guardado. El módulo conserva su configuración tras los reinicios.
Sustitución de una pinza o de un módulo
La calibración pertenece al par. Una pinza o un canal no pueden sustituirse en campo: un módulo que necesite una pinza nueva se devuelve al servicio de fábrica para volver a emparejarlo.
Configuración de la clase del sensor y del modelo de CT
Necesario solo para los módulos BASIC de la serie SCT usados con sensores SCT-013. Los módulos BASIC de la serie CT se suministran en pareja con sus sensores: todo viene preajustado y calibrado en fábrica para ese sensor concreto, y arrancan sin inicialización; omita esta sección.
Dos registros describen el sensor externo: SENSOR_CLASS (la familia: pinzas SCT-013, la serie de pinzas CT cableadas, CT integrado) y CT_MODEL (el código de modelo concreto dentro de esa familia). En v1.3 el modelo se escribe con un esquema de solo preparación: escribir CT_MODEL no lo aplica por sí solo; un comando dedicado por canal confirma el valor preparado.
Registros
| Nombre | Dirección | Tipo | Notas |
|---|---|---|---|
SENSOR_CLASS |
0x25 |
u8 RW | 0 = Sin definir, 1 = SCT_013, 2 = WIRED_CT (la serie de pinzas CT), 3 = BUILTIN_CT (sensor integrado, calibración de fábrica por unidad: sin código de modelo). Cambiar la clase restablece CT_MODEL a 0. |
CT_MODEL |
0x05 |
u8 RW | Código del modelo de CT: solo registro de staging. La escritura pura no lo aplica. |
Elección de un sensor
Compre uno de los modelos SCT-013 de salida de tensión de la tabla de abajo (conector de 3.5 mm), no una variante de salida de corriente. Elija la pinza de calibre más pequeño que esté por encima de su mayor corriente prevista; para la clase indicada la carga no debe quedar por debajo de aproximadamente el 1 % del calibre (vea la tabla de precisión).
Códigos de modelo de CT: familia SCT-013 (SENSOR_CLASS = 1)
| Código | Sensor | Corriente nominal | Inicio de saturación RMS | Límite de pico |
|---|---|---|---|---|
0x00 |
no establecido (por defecto en módulos BASIC de la serie SCT de fábrica sin usar) | — | — | — |
0x01 |
SCT-013-005 | 5 A | 5.8 A | 8.2 A |
0x02 |
SCT-013-010 | 10 A | 11.6 A | 16.4 A |
0x03 |
SCT-013-030 | 30 A | 34.8 A | 49.2 A |
0x04 |
SCT-013-050 | 50 A | 58 A | 82 A |
0x05 |
SCT-013-100 | 100 A | 116 A | 164 A |
0x06 |
SCT-013-020 | 20 A | 23.2 A | 32.8 A |
0x07 |
SCT-013-060 | 60 A | 69.6 A | 98.4 A |
Los códigos 0x06 y 0x07 no son monótonos por calificación: se añadieron tras el conjunto original 0x01..0x05. Elija siempre por la calificación que necesite, no por el orden de los códigos.
Semántica de los límites: la corriente nominal y el inicio de saturación RMS suponen una carga sinusoidal; el inicio de saturación medido es ≈ 1.16 × el calibre. El límite de pico (≈ 1.64 × calibre) es el techo real: una carga distorsionada (factor de cresta alto) empieza a saturar en pico / factor de cresta, por debajo de las cifras RMS. Manténgase en el calibre o por debajo para la precisión especificada: las lecturas se saturan hacia el 115–120 % del calibre.
Las cifras por calibre (umbral detectable y legible, clase, tolerancia del sensor, punto de saturación) están en la tabla de precisión de overview.md. Cambiar el modelo del sensor consiste en escribir el código del modelo en el módulo; no hace falta nada más ni ningún paso de recalibración.
Códigos de modelo de CT: serie de pinzas CT cableadas (SENSOR_CLASS = 2)
Los módulos de la serie CT se suministran como conjunto calibrado en fábrica con su propia pinza: la clase y el modelo ya están establecidos y forman parte de la calibración; vea Módulos de la serie CT: arranque sin configuración. No los escriba. La tabla de abajo es de referencia para leer el modelo aplicado; en un módulo de la serie CT el usuario no selecciona nada.
| Código | Pinza | Corriente nominal | Ventana |
|---|---|---|---|
0x01..0x05 |
preajustes heredados de CT cableado | — | — |
0x06 |
Pinza CT, 1 A | 1 A | 6 mm |
0x07 |
Pinza CT, 5 A | 5 A | 6 mm |
0x08 |
Pinza CT, 10 A | 10 A | 6 mm |
0x09 |
Pinza CT, 20 A | 20 A | 10 mm |
0x0A |
Pinza CT, 30 A | 30 A | 10 mm |
0x0B |
Pinza CT, 50 A | 50 A | 10 mm |
0x0D |
Pinza CT, 100 A | 100 A | 16 mm |
El tamaño de la ventana depende del calibre nominal (6 mm para 1–10 A, 10 mm para 20–50 A, 16 mm para 100 A) y no afecta a la calibración.
Comandos
| Nombre | Código de operación | Efecto | Espere |
|---|---|---|---|
CMD_SET_CT_MODEL_CH0 |
0x28 |
Vincule el valor CT_MODEL en staging al canal 0 |
~5 ms |
CMD_SET_CT_MODEL_CH1 |
0x29 |
Enlace al canal 1 (UI2/UI3/I2/I3) | ~5 ms |
CMD_SET_CT_MODEL_CH2 |
0x2A |
Vincule al canal 2 (UI3/I3) | ~5 ms |
CMD_SAVE_USER_CONFIG |
0x32 |
Persiste el bloque de configuración de usuario (clase de sensor, modelo de CT, dirección, etiqueta) en la flash | ~700 ms |
Procedimiento
- Conecte la(s) pinza(s) CT a la(s) toma(s) del módulo (flecha hacia la carga; véase hardware-connection.md).
-
Configure la clase de sensor(una vez, si aún no está fijado):
C++rb_write_u8(0x50, 0x25, 0x01); // SCT_013 -
Para cada canal el módulo expone:
- Prepare el código de modelo de CT en
CT_MODEL:C++rb_write_u8(0x50, 0x05, 0x03); // example: SCT-013-030 - Vincúlelo al canal correspondiente con el
CMD_SET_CT_MODEL_CHn:C++rb_write_u8(0x50, 0x01, 0x28); // CMD_SET_CT_MODEL_CH0 delay(5); - Repita para ch1 / ch2 si la variante los tiene (los canales son independientes: puede mezclar códigos de modelo por canal).
-
Persistiren flash con
CMD_SAVE_USER_CONFIG:C++rb_write_u8(0x50, 0x01, 0x32); delay(700); // flash erase/write -
Listo, con una salvedad en firmware anterior a 1.4.20 (
CAPABILITYbit 12 a 0): allí el código del modelo guardado sobrevive a los reinicios, pero el escalado aplicado no (véase Qué persiste tras un reinicio más abajo). Si seleccionó un modelo distinto del de fábrica, repita el paso 3 (staging + commit) tras cada reinicio de módulo detectado;CMD_SAVE_USER_CONFIGno necesita repetirse. Desde el firmware 1.4.20, el cambio de modelo sobrevive a los reinicios.
: en v1.3 puede llamar a CMD_SET_CT_MODEL_CH0/1/2 en cualquier orden. No hace falta ningún rodeo de orden descendente (era un artefacto interno de firmwares anteriores).
Comportamiento con las bibliotecas cliente actuales
Las bibliotecas cliente de rbAmp (Arduino, ESP-IDF, ESPHome, Python) envuelven este procedimiento y añaden:
-
Reescribir el mismo valor se omite. Escribir la clase del sensor o el modelo de CT con el valor que el módulo ya tiene no genera escritura en el bus ni ciclo de flash; llamar al establecedor en cada arranque es seguro.
-
Los módulos emparejados en fábrica no aceptan cambios de clase ni de modelo. En los modelos que se suministran como conjunto calibrado en fábrica con su propio sensor de corriente (serie CT), la clase y el modelo del sensor forman parte de la calibración: el módulo (firmware 1.4.22 y posteriores) rechaza la escritura con
ERR_PARAM (0xFE)en funcionamiento normal, y las bibliotecas la rechazan antes de enviarla en todos los firmwares. Volver a emparejar un sensor de repuesto es un servicio de fábrica. -
Límites por modelo. Para cada modelo de CT las bibliotecas exponen su corriente nominal, el nivel RMS donde empieza la saturación y el límite de pico: úselos para validar las lecturas frente al sensor conectado.
Verificación
Tras el enlace, el modelo de CT aplicado de cada canal se refleja en 0x51..0x53 (espejos de solo verificación). NO son el registro de preparación 0x05:
uint8_t ch0 = rb_read_u8(0x50, 0x51); // applied on ch0
uint8_t ch1 = rb_read_u8(0x50, 0x52); // applied on ch1
uint8_t ch2 = rb_read_u8(0x50, 0x53); // applied on ch2
Serial.printf("Applied: ch0=0x%02X ch1=0x%02X ch2=0x%02X\n", ch0, ch1, ch2);
⚠ La lectura de vuelta no equivale a persistencia. Una lectura correcta de 0x51..0x53 confirma que el valor está vivo en RAM, no que haya sobrevivido a la flash. Para verificar la persistencia, ejecute CMD_RESET (o corte la alimentación) y vuelva a leer tras la ventana de arranque. El patrón completo está en period-metering.md.
Al poner en marcha un módulo nuevo, haga una comprobación de coherencia con una carga resistiva conocida (por ejemplo, una lámpara incandescente de 100 W): I_rms ≈ 100 W / U_rms ≈ 0.43 A y P_real ≈ 100 W. Si las lecturas están muy desviadas, probablemente el código de modelo es incorrecto.
Qué persiste tras un reinicio
CMD_SAVE_USER_CONFIG guarda en flash el bloque de configuración de usuario, pero no todo lo que el master establece se vuelve a aplicar en el siguiente arranque. En firmware anterior a 1.4.20 (bit 12 de CAPABILITY a 0):
| Elemento | ¿Sobrevive a un reinicio? |
|---|---|
| Dirección I²C | sí |
| Etiqueta del módulo | sí |
| Clase de sensor + código del modelo de CT (legible de vuelta) | sí |
| Escalado aplicado por modelo | antes del fw 1.4.20: no; vuelve al valor de fábrica. Desde la 1.4.20 (CAPABILITY bit 12 a 1): sí |
FLEET_CONFIG (activación de GC) + GROUP_ID |
sí (mediante CMD_SAVE_USER_CONFIG; surte efecto tras el reinicio) |
| configuración solo en RAM (umbrales de evento, configuración de resumen) | no |
La consecuencia en esas imágenes: un módulo que se cambió a un modelo distinto del que salió de fábrica devuelve tras un reinicio el código de modelo guardado, pero mide con el escalado de fábrica hasta que el modelo se confirma de nuevo. La regla para cualquier master (y para un hub que gestione una flota, indexada por UID de módulo) es:
-
Detecte el reinicio:
UPTIME_S/ bit de eventoRESET_OCCURRED, vea period-metering.md → Detección de un reinicio del módulo. -
Vuelva a preparar y a confirmar el modelo de CT en todos los canales (
CT_MODEL+CMD_SET_CT_MODEL_CHn), y después vuelva a aplicar cualquier configuración solo de RAM.
Las bibliotecas cliente implementan exactamente esto en su ruta de reanudación. Desde el firmware 1.4.20 (bit 12 de CAPABILITY, SCT_RATING_SELF) el cambio de modelo conserva la calibración de la unidad y sobrevive a los reinicios: el paso 2 ya no es necesario para el modelo CT; la configuración solo en RAM sigue necesitando reinicialización. Los módulos que funcionan con su modelo de fábrica (incluidos todos los módulos de la serie CT emparejados en fábrica) no se ven afectados en ninguna imagen: el escalado de fábrica es el correcto.
— 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 |
Flujo de trabajo con un solo módulo
- Cablee el módulo según hardware-connection.md.
- Para los módulos BASIC de la serie SCT, escriba el modelo del sensor una sola vez (sección anterior).
- Grabe el master con el boceto de prueba de funcionamiento.
- Abra el monitor serie: debería ver U/I/P cada segundo.
- Si las lecturas parecen incorrectas, véase troubleshooting.md.
Configuración de varios módulos
Escenario: tres módulos rbAmp en un único bus para monitorizar distintas zonas de una vivienda (acometida principal, calentador de agua, aire acondicionado).
Paso 1: direcciones
Recién salidos de fábrica, los tres módulos llevan la dirección 0x50. Hay que readdresarlos uno a uno. Conecte solo un módulo al bus hasta terminar el cambio de dirección.
Paso 2: prueba de funcionamiento con un módulo
Use la sección anterior. Confirme que un módulo funciona correctamente.
Paso 3: cambie la dirección (y, si hace falta, el modelo de CT)
Use el procedimiento de cambio de dirección que se describe a continuación. Si los módulos usan sensores SCT-013 distintos, establezca el modelo de CT en cada uno antes de cambiarles la dirección.
Paso 4: bucle de sondeo multimódulo
#include
const uint8_t modules[] = {0x50, 0x51, 0x52}; // main, boiler, AC
const char* labels[] = {"MAIN", "BOIL", "AC "};
const int N = sizeof(modules) / sizeof(modules[0]);
void setup() {
Serial.begin(115200);
Wire.begin();
Wire.setClock(50000);
delay(300);
for (int i = 0; i < N; i++) {
Wire.beginTransmission(modules[i]);
uint8_t rc = Wire.endTransmission();
Serial.printf("Module %s (0x%02X): %s\n",
labels[i], modules[i], rc == 0 ? "OK" : "MISSING");
}
}
void loop() {
for (int i = 0; i < N; i++) {
float u = rb_read_float_le(modules[i], 0x86);
float p = rb_read_float_le(modules[i], 0xA6);
Serial.printf("[%s] U=%.1f P=%.1f W\n", labels[i], u, p);
}
Serial.println();
delay(1000);
}
Salida esperada:
Module MAIN (0x50): OK
Module BOIL (0x51): OK
Module AC (0x52): OK
[MAIN] U=229.8 P=850.3 W
[BOIL] U=229.7 P=1850.0 W
[AC ] U=229.9 P=0.0 W
...
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmpFleet::scan(match_product, added) / RbAmpFleet::pollAll(snaps, status, capacity, n_ok) |
descubra los módulos del bus; léalos todos en una sola pasada |
| ESP-IDF | rbamp_fleet_scan() / rbamp_fleet_poll_all() |
descubra los módulos del bus; léalos todos en una sola pasada |
| Python | fleet.scan(match_product=True) / fleet.poll_all() |
descubra los módulos del bus; léalos todos en una sola pasada |
| ESPHome | rbamp: (list) |
un bloque rbamp: por módulo, cada uno con su propio id y address |
Cambio de dirección
La dirección de fábrica 0x50 se guarda en el bloque de configuración de usuario en flash. v1.3 usa una secuencia de confirmación en dos fases para dificultar los cambios accidentales de dirección: una dirección candidata entra primero en un registro de preparación en RAM, debe armarse con un byte magic y solo entonces se confirma en flash mediante un comando explícito. Un reinicio vuelve a enumerar el módulo en la nueva dirección.
Registros y comandos
| Nombre | Dirección / opcode | Tipo | Finalidad |
|---|---|---|---|
REG_I2C_ADDRESS |
0x30 |
u8 RW | Staging para la dirección candidata (0x08..0x77). Una regla: antes del reinicio, 0x30 devuelve el candidato en staging; tras el arranque lee la dirección activa. |
ADDR_COMMIT_MAGIC |
0x31 |
u8 W | Arme la confirmación con 0xA5. Se consume (se borra) en el intento de confirmación. |
CMD_COMMIT_ADDR |
opcode 0x30 escrito en REG_COMMAND (0x01) |
comando | Valida la dirección preparada frente al magic y la persiste en flash. |
CMD_RESET |
código de operación 0x01 escrito en REG_COMMAND (0x01) |
comando | Reinicio suave. El módulo vuelve a enumerarse en la nueva dirección tras ~300 ms. |
Procedimiento
- Conecte un solo módulo (todavía en
0x50) al bus. -
Prepare la nueva dirección:
C++rb_write_u8(0x50, 0x30, 0x51); // candidate address → RAM staging -
Arme el commit:
C++rb_write_u8(0x50, 0x31, 0xA5); // ADDR_COMMIT_MAGIC -
Problema
CMD_COMMIT_ADDR(opcode0x30):C++rb_write_u8(0x50, 0x01, 0x30); -
Espere≥ 700 mspara el borrado y la escritura de la flash:
C++delay(700); -
Problema
CMD_RESET(opcode0x01) —CMD_COMMIT_ADDRhaceno auto-reset:C++rb_write_u8(0x50, 0x01, 0x01); -
Espere ~300 ms a la ventana de arranque. No emita comandos durante esta ventana.
-
Compruebe que el módulo responde con ACK en la nueva dirección:
C++uint8_t ver = rb_read_u8(0x51, 0x03); // VERSION should be 0x04 on v1.3 if (ver == 0x04) Serial.println("Address change OK"); -
Marque la placa con la nueva dirección usando un lápiz de cera o una etiqueta, para identificar físicamente el módulo.
Notas importantes
- Ambas etapas son obligatorias. Escribir el candidato en
0x30por sí solo no hace nada persistente: solo queda en RAM y se pierde en el siguiente reinicio. El par magia-y-confirmación es lo que realmente reescribe la flash. - La dirección de staging debe estar en el rango
0x08..0x77(I²C válido de 7 bits). Las escrituras fuera de rango se rechazan conERR_PARAM; el módulo conserva su dirección actual. - Direcciones I²C reservadas:
0x00(llamada general, véase abajo),0x01..0x07(CBus reservado),0x78..0x7F(reservado de 10 bits). No las use. - Una regla de lectura de vuelta: antes del reinicio,
0x30devuelve el candidato en staging; tras el arranque lee la dirección activa. - El magic armado caduca tras 5 s sin confirmación (capítulo 11, §6.1): arme de nuevo si ha esperado demasiado.
- Recordatorio de espacios de nombres: el mismo valor de byte puede ser una dirección y un opcode:
| Byte | Como dirección de registro | Como opcode (escrito en 0x01) |
|---|---|---|
0x27 |
FLEET_CONFIG |
CMD_LATCH_PERIOD |
0x28 |
GROUP_ID |
CMD_SET_CT_MODEL_CH0 |
0x30 |
REG_I2C_ADDRESS |
CMD_COMMIT_ADDR |
Ejemplo completo de cambio de dirección
#include
bool change_address(uint8_t old_addr, uint8_t new_addr) {
if (new_addr < 0x08 || new_addr > 0x77) {
Serial.println("ERROR: invalid address");
return false;
}
Serial.printf("Changing 0x%02X -> 0x%02X\n", old_addr, new_addr);
rb_write_u8(old_addr, 0x30, new_addr); // 1. stage candidate
rb_write_u8(old_addr, 0x31, 0xA5); // 2. arm magic
rb_write_u8(old_addr, 0x01, 0x30); // 3. CMD_COMMIT_ADDR
delay(700); // 4. flash erase/write
rb_write_u8(old_addr, 0x01, 0x01); // 5. CMD_RESET (mandatory)
delay(300); // 6. boot window
Wire.beginTransmission(new_addr);
if (Wire.endTransmission() == 0) {
Serial.printf("OK, module now at 0x%02X\n", new_addr);
return true;
}
Serial.printf("FAIL: module not found at 0x%02X\n", new_addr);
return false;
}
void setup() {
Serial.begin(115200);
Wire.begin();
delay(300);
change_address(0x50, 0x51);
}
— 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 |
Llamada general (difusión en la dirección 0x00)
El protocolo I²C reserva la dirección 0x00 (llamada general): las tramas enviadas a esta dirección las reciben simultáneamente todos los esclavos del bus. rbAmp puede tomar su instantánea de periodo con una trama de llamada general, pero solo después de activar explícitamente la función en el módulo.
Activación voluntaria (por defecto DESACTIVADA)
La recepción de instantáneas por llamada general está desactivada de forma predeterminada: un módulo nuevo responderá NACK a la trama de llamada general, lo que el maestro detecta como error grave y recurre automáticamente a la instantánea secuencial módulo a módulo. Para activar GC en un módulo:
- Ponga a 1 el bit 0 de
FLEET_CONFIG:C++rb_write_u8(0x50, 0x27, 0x01); // bit0 = GC_ENABLE
Nota sobre el valor 0x27: es la dirección de registro de FLEET_CONFIG. El mismo valor de byte 0x27 es también el opcode de comando de CMD_LATCH_PERIOD (espacio de nombres distinto: los opcodes van a REG_COMMAND en 0x01). La coincidencia es puramente cosmética; a nivel de cable nunca se confunden dirección y opcode.
-
(Opcional) ponga
GROUP_IDpara dividir la flota en grupos —0x00acepta todos los llamados:C++rb_write_u8(0x50, 0x28, 0x00); // all-call -
Persist:
C++rb_write_u8(0x50, 0x01, 0x32); // CMD_SAVE_USER_CONFIG delay(700); -
Reinicie y compruebe que el bit se ha grabado:
C++rb_write_u8(0x50, 0x01, 0x01); // CMD_RESET delay(300); uint8_t cfg = rb_read_u8(0x50, 0x27); if (cfg & 0x01) Serial.println("GC enabled");
Formato de la trama GC
Las tramas de instantánea GC tienen una estructura fija de magic y opcode:
addr 0x00 | A5 27
A5: magic de la trama (el esclavo rechaza cualquier otro byte).27: opcode (CMD_LATCH_PERIOD).: grupo de destino (0x00= llamada a todos; si no, debe coincidir con elGROUP_IDdel módulo).: contador de ticks de 16 bits del lado del maestro, replicado en el registroGC_TICK (0x59)de cada módulo para detectar tramas perdidas.
Por diseño, las tramas GC transportan solo el comando de instantánea: los códigos destructivos (SAVE_*, COMMIT_ADDR, FACTORY_RESET) no se atienden por llamada general.
Ejemplo de instantánea de difusión (tras habilitar)
// All modules with GC enabled take their snapshots at once.
Wire.beginTransmission(0x00);
Wire.write(0xA5); // frame magic
Wire.write(0x27); // CMD_LATCH_PERIOD opcode
Wire.write(0x00); // group_id = all-call
Wire.write(tick & 0xFF); // tick_lo
Wire.write((tick >> 8) & 0xFF); // tick_hi
uint8_t rc = Wire.endTransmission();
if (rc != 0) {
// NACK at GC level → no module on the bus has GC enabled.
// Fall back to per-module sequential snapshot.
}
Tras la difusión, cada módulo actualiza su instantánea de forma independiente. Después, el maestro lee cada módulo por su dirección individual. Comprobación testigo (recomendada): tras ~50 ms de asentamiento, lea V03_PERIOD_VALID (0x07) en cada módulo esperado: 1 confirma que la instantánea se registró; 0 recurre a la instantánea por módulo solo en ese módulo.
Aplicación: sincronización precisa de periodos para el equilibrio de energía entre varios módulos (p. ej. mains_input − solar_output), donde el instante de la instantánea debe ser idéntico en todos los módulos.
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::enableGc(enable) / RbAmpFleet::gcLatch(group, tick, settle_ms) |
active la llamada general en un módulo; envíe la trama de instantánea a toda la flota |
| ESP-IDF | rbamp_enable_gc() / rbamp_fleet_gclatch() |
active la llamada general en un módulo; envíe la trama de instantánea a toda la flota |
| Python | dev.enable_gc(enable=True) / fleet.gc_latch(group, tick, settle_ms) |
active la llamada general en un módulo; envíe la trama de instantánea a toda la flota |
| ESPHome | fleet_gc_enable: / group_id: |
Opciones YAML para la activación de llamada general y el identificador de grupo |
Flujo recomendado de despliegue de varios módulos
Step 1: Unbox all modules — every module is on address 0x50.
Step 2: For each module, one at a time:
a) Connect only this module to the bus.
b) If it is a BASIC SCT-series module: set SENSOR_CLASS (0x25), stage CT_MODEL (0x05),
issue CMD_SET_CT_MODEL_CHn for each channel, then CMD_SAVE_USER_CONFIG.
c) On images before fw 1.4.20 (`CAPABILITY` bit 12 clear): after any later reset of this
module, re-stage and re-commit CT_MODEL on each channel (see the persistence table above).
d) Run change_address(0x50, ).
e) Verify the module responds at the new address.
f) Physically mark the module (label with 0x51, 0x52, ...).
g) Disconnect and move to the next module.
Step 3: After readdressing all modules, connect them in parallel.
With four or more modules (or a longer bus), cut the built-in
pull-up jumpers on all but one (see hardware-connection.md → I2C pull-ups).
Step 4: At master boot, run a scan loop and verify every readdressed
module responds at its expected address.
¿BASIC o STD?
La línea STD de rbAmp responde en el mismo bus, pero usa un mapa de registros distinto de 16 bits. Antes de aplicar la detección BASIC de abajo, puede diferenciarlos: envíe el puntero de 16 bits 0x00 0x00 y lea 2 bytes; un módulo STD devuelve el par ASCII 'S','T' (0x53 0x54); un módulo BASIC no (trata los bytes como escrituras de registros de 8 bits y devuelve sus datos normales). Los módulos STD tienen su propia documentación de referencia.
No necesita hacer esto usted mismo si usa una biblioteca cliente. Las bibliotecas (Arduino, ESP-IDF, Python, ESPHome) ya detectan la línea de módulos y gestionan los distintos tamaños de registro: no tiene que preocuparse de si el mapa de registros es de 8 o de 16 bits.
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::line() / RbAmp::begin() |
línea detectada en begin(); léala de vuelta desde el valor en caché |
| ESP-IDF | rbamp_line() / rbamp_begin() |
línea detectada en begin; léala de vuelta desde el valor en caché |
| Python | dev.is_std / dev.begin() |
línea detectada en begin(); léala de vuelta desde la propiedad |
| ESPHome | — | no expuesto: la detección es automática, no hay nada que configurar en YAML |
Detección automática de la variante del módulo
⚠ No detecte la variante sondeando un NACK en las lecturas de registros. El firmware nunca responde NACK a las lecturas de registros: las direcciones no asignadas devuelven 0x00 (vea el capítulo 11, §5.2). Una comprobación basada en NACK siempre informa de «canal presente».
Use el par canónico HW_VARIANT (0x55) + CAPABILITY (0x57/0x58):
struct VariantInfo {
uint8_t hw_variant; // 1=UI1, 2=UI2, 3=UI3, 4=I1, 5=I2, 6=I3
uint8_t n_current; // 1..3
bool has_voltage; // true on UI*, false on I*
};
VariantInfo detect_variant(uint8_t addr) {
VariantInfo v = {0, 0, false};
uint8_t product = rb_read_u8(addr, 0x54); // PRODUCT_ID
if (product != 0x01) return v; // not an rbAmp sensor
v.hw_variant = rb_read_u8(addr, 0x55); // HW_VARIANT
uint8_t hw = v.hw_variant;
v.n_current = (hw == 1 || hw == 4) ? 1
: (hw == 2 || hw == 5) ? 2
: (hw == 3 || hw == 6) ? 3 : 0;
uint8_t cap_hi = rb_read_u8(addr, 0x58); // CAPABILITY high byte
v.has_voltage = (cap_hi & 0x01) != 0; // bit 8 of u16 = voltage-HW
return v;
}
HW_VARIANT 1..3 son variantes UI (has_voltage == true); 4..6 son variantes solo de corriente (has_voltage == false). Una discrepancia entre la familia de HW_VARIANT y CAPABILITY.bit8 indica un módulo defectuoso o mal grabado.
AC_FREQ (0x20) funciona en todas las variantes: la señal de cruce por cero procede de un pin dedicado independiente del front-end de tensión.
— la misma tarea sin acceso a registros:
| Biblioteca | Llamada | Qué hace |
|---|---|---|
| Arduino | RbAmp::readVariant() / RbAmp::readCapability(out) |
lea la variante de hardware y el mapa de capacidades |
| ESP-IDF | rbamp_read_variant() / rbamp_read_capability() |
lea la variante de hardware y el mapa de capacidades |
| Python | dev.read_variant() / dev.read_capability() |
lea la variante de hardware y el mapa de capacidades |
| ESPHome | get_variant_str() / get_capability_hex() |
cadena de variante y mapa de capacidades de la superficie de identidad |
Siguiente
- realtime-polling.md: sondeo en tiempo real en detalle (ventana de 100 ms, DRDY)
- period-metering.md: acumulación de energía por tarifas