rbAmp
ES
Tienda
Docs
Actualizado

02 · Inicialización y arranque

rbAmp empieza a medir de inmediato tras el encendido. El maestro solo necesita:

  1. Inicie su bus I²C (inicialización estándar de Wire / HAL).
  2. Espere ~250 ms, o sondee DATA_VALID = 1 en el registro 0xCE.
  3. Opcionalmente, lea la versión del firmware desde 0x03 como comprobación de cordura.
  4. 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.

La secuencia desde el encendido hasta la primera lectura válida.

Nota

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:

C
// 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

C++
#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)

C++
#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):

Text
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)

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.

Seguridad

⚠ 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

  1. Conecte las pinzas (con la flecha hacia la carga; vea hardware-connection.md) y alimente el módulo.
  2. Lea la clase (SENSOR_CLASS, 0x25): 2 = serie de pinzas CT.
  3. 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, campo CT_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.

  1. 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

Nota

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
Nota

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
Nota

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

  1. Conecte la(s) pinza(s) CT a la(s) toma(s) del módulo (flecha hacia la carga; véase hardware-connection.md).
  2. Configure la clase de sensor(una vez, si aún no está fijado):

    C++
    rb_write_u8(0x50, 0x25, 0x01);    // SCT_013
    

  3. Para cada canal el módulo expone:

  4. Prepare el código de modelo de CT enCT_MODEL:
    C++
    rb_write_u8(0x50, 0x05, 0x03);    // example: SCT-013-030
    
  5. Vincúlelo al canal correspondiente con elCMD_SET_CT_MODEL_CHn:
    C++
    rb_write_u8(0x50, 0x01, 0x28);    // CMD_SET_CT_MODEL_CH0
    delay(5);
    
  6. Repita para ch1 / ch2 si la variante los tiene (los canales son independientes: puede mezclar códigos de modelo por canal).
  7. Persistiren flash conCMD_SAVE_USER_CONFIG:

    C++
    rb_write_u8(0x50, 0x01, 0x32);
    delay(700);                          // flash erase/write
    

  8. Listo, con una salvedad en firmware anterior a 1.4.20 (CAPABILITY bit 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_CONFIG no necesita repetirse. Desde el firmware 1.4.20, el cambio de modelo sobrevive a los reinicios.

Independencia del orden de canales

: 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:

C++
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);
Seguridad

⚠ 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:

  1. Detecte el reinicio: UPTIME_S / bit de evento RESET_OCCURRED, vea period-metering.md → Detección de un reinicio del módulo.

  2. 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.

En las bibliotecas cliente

— 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

  1. Cablee el módulo según hardware-connection.md.
  2. Para los módulos BASIC de la serie SCT, escriba el modelo del sensor una sola vez (sección anterior).
  3. Grabe el master con el boceto de prueba de funcionamiento.
  4. Abra el monitor serie: debería ver U/I/P cada segundo.
  5. 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

C++
#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:

Text
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
...
En las bibliotecas cliente

— 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.

El cambio de dirección en dos fases: prepare la dirección candidata, armela, confírmela y luego reinicie.

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

  1. Conecte un solo módulo (todavía en 0x50) al bus.
  2. Prepare la nueva dirección:

    C++
    rb_write_u8(0x50, 0x30, 0x51);    // candidate address → RAM staging
    

  3. Arme el commit:

    C++
    rb_write_u8(0x50, 0x31, 0xA5);    // ADDR_COMMIT_MAGIC
    

  4. ProblemaCMD_COMMIT_ADDR (opcode 0x30):

    C++
    rb_write_u8(0x50, 0x01, 0x30);
    

  5. Espere≥ 700 mspara el borrado y la escritura de la flash:

    C++
    delay(700);
    

  6. ProblemaCMD_RESET (opcode 0x01) — CMD_COMMIT_ADDRhaceno auto-reset:

    C++
    rb_write_u8(0x50, 0x01, 0x01);
    

  7. Espere ~300 ms a la ventana de arranque. No emita comandos durante esta ventana.

  8. 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");
    

  9. 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 0x30 por 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 con ERR_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, 0x30 devuelve 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

C++
#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);
}
En las bibliotecas cliente

— 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:

  1. Ponga a 1 el bit 0 deFLEET_CONFIG:
    C++
    rb_write_u8(0x50, 0x27, 0x01);    // bit0 = GC_ENABLE
    
Nota

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.

  1. (Opcional) pongaGROUP_IDpara dividir la flota en grupos —0x00acepta todos los llamados:

    C++
    rb_write_u8(0x50, 0x28, 0x00);    // all-call
    

  2. Persist:

    C++
    rb_write_u8(0x50, 0x01, 0x32);    // CMD_SAVE_USER_CONFIG
    delay(700);
    

  3. 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:

Disposición de bytes de la trama de instantánea General Call.

Text
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 el GROUP_ID del módulo).
  • : contador de ticks de 16 bits del lado del maestro, replicado en el registro GC_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)

C++
// 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.

En las bibliotecas cliente

— 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
Text
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.

Cómo distinguir en tiempo de ejecución un módulo BASIC de un módulo STD.

En las bibliotecas cliente

— 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

Seguridad

⚠ 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):

C++
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.

En las bibliotecas cliente

— 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