rbAmp
ES
Tienda
Docs
Actualizado · Editar en GitHub [Edit on GitHub]

04 · Cableado

Este capítulo trata de la conexión física del módulo rbAmp a un host compatible con Arduino: la disposición de pines del lado de baja tensión, los requisitos de alimentación, la compatibilidad de niveles I²C, la longitud del bus y los esquemas de conexión de placas Arduino concretas (UNO, Mega, ESP32, ESP8266, STM32duino, RP2040).

El lado de baja tensión (alimentación + I²C + DRDY opcional) está aislado de los terminales de red. Los terminales de red y el cableado del lado del TC están conectados a la red: vea la advertencia en «Cableado del lado de red» más abajo.

Pinout del lado de baja tensión

El módulo funciona con lógica I²C de 3.3 V y tolera 5 V en las líneas de señal. Todos los pines de baja tensión están totalmente aislados galvánicamente de la red.

Pin Señal Función
VCC +5 V (4.5..5.5 V) Alimentación del módulo; mínimo 4.5 V para un funcionamiento correcto
GND Tierra Compartido con el maestro: obligatorio
SDA SDA I²C Datos I²C
SCL SCL de I²C Reloj I²C
DRDY Datos listos (opcional) Drenador abierto, pulso BAJO de ~10 µs cada ~100 ms

La cabecera de baja tensión del módulo rbAmp: VCC, GND, SDA, SCL y el pin DRDY opcional con lo que necesita cada uno.

Potencia

Parámetros de VCC

  • Tensión nominal: 5 V CC
  • Rango admisible: 4.5..5.5 V
  • Corriente de alimentación: ~15 mA típicos, ~25 mA de pico durante las escrituras en flash
  • Rizado: < 50 mV pico a pico (para la precisión de medida)

El módulo lleva un regulador integrado, un filtro RC, condensadores cerámicos y una perla de ferrita: no hace falta ningún filtrado adicional por parte del usuario. El módulo puede alimentarse desde el raíl +5V de cualquier placa Arduino (UNO, ESP32 DevKitC, etc.).

Compatibilidad de niveles I²C

  • SDA / SCL funcionan con lógica de 3.3 V (las pull-ups integradas llevan las líneas a 3.3 V).

  • Las líneas toleran 5 V: un maestro de 5 V (Arduino UNO / Nano) lee ALTO (~3.3 V) correctamente y puede manejar el bus sin conversor de nivel.

  • Para un bus que funciona enteramente a niveles de 5 V: desactive las resistencias de pull-up integradas (véase más abajo) y añada pull-ups externas a +5 V en el lado del maestro.

Comportamiento al encendido

  • Arranque en frío: ~250 ms hasta el primer resultado válido.
  • Tras un reinicio (por software o por caída de tensión): ~250 ms para recuperarse.
  • Hasta el primer resultado válido, los registros se leen como 0 y DATA_VALID = 0.

La biblioteca espera a que el módulo esté listo dentro de dev.begin(): su código simplemente llama a begin() y continúa.

Aislamiento

El lado de baja tensión (I²C, alimentación, DRDY) está aislado de los terminales de red. Trate los terminales de red y el cableado del lado del TC como si estuvieran con tensión.

  • El GND del módulo no está conectado a la línea de red ni al neutro.
  • No toque los terminales L/N ni el conductor de la pinza mientras el circuito esté energizado.
Seguridad

⚠ No abra la carcasa del módulo: anula la calibración de fábrica.

Resistencias pull-up integradas

Importante: cada módulo rbAmp incluye resistencias de pull-up de 4.7 kΩ integradas en SDA y SCL a 3.3 V. Para un único módulo en el bus no se necesitan pull-ups externas: conecte el maestro directamente.

Cuándo desactivar las pull-ups integradas

Si el bus tiene varios módulos rbAmp (u otros dispositivos I²C con sus propias resistencias de pull-up), conectarlos en paralelo produce una resistencia efectiva demasiado baja, lo que:

  • Aumenta el consumo del bus
  • Puede superar la corriente máxima de sumidero de la etapa de salida del maestro I²C (típicamente ≤ 3 mA a lógica de 3.3 V)

  • Añade capacidad capacitiva en un bus largo aportando poco a la inmunidad al ruido

Solución: en la cara inferior de la placa, junto a las resistencias de pull-up, hay puentes de soldadura (serigrafía Pull-Up). Córtelos con una cuchilla afilada para desactivar una pull-up:

  • Deje las resistencias de pull-up activadas en un solo módulo (o muévalas a un único punto cerca del maestro).

  • Corte los puentes de los módulos restantes.

  • Si el maestro ya tiene pull-ups en su placa, corte los puentes de todos los módulos rbAmp.

Regla general

módulos rbAmp en el bus Pull-ups
1 Déjelo como está (sirve la de 4.7 kΩ integrada)
2 Deje una activa y corte la otra
3 Corte en todos los módulos y coloque un par externo de 2.7…3.3 kΩ cerca del maestro
4…6 Corte en todos los módulos, coloque un par externo de 2.2…2.7 kΩ cerca del maestro
7…16 Corte en todos los módulos, coloque un par externo de 1.5…2.2 kΩ cerca del maestro; compruebe la capacidad del bus (≤ 400 pF) y reduzca la velocidad del bus si es necesario

Los valores externos son valores recomendados (calculados a partir de la especificación I²C: corriente de sumidero ≤ 3 mA a 3.3 V, capacidad del bus ≤ 400 pF). Conecte las resistencias de pull-up externas a 3.3 V (el nivel lógico del bus), no a la alimentación de 5 V VCC.

En caso de duda

: mida la resistencia entre SDA y VCC con los dispositivos sin alimentar. Debe estar en el rango de 1.5..4.7 kΩ. Si es menor, hay demasiadas pull-ups activas en paralelo.

Cuántos módulos hay en el bus y qué pull-ups I²C se conservan: mantenga los pares integrados para uno a tres módulos en un bus de hasta 15 cm; a partir de cuatro módulos, o en un bus más largo, córtelos todos y use un único par externo.

Parámetros del bus I²C

  • Dirección por defecto: 0x50 (7 bits)
  • Rango de direcciones: 0x08..0x77 (reasignado mediante confirmación de dirección en dos fases, apto para producción)
  • Velocidad: UNO / Mega / STM32 / RP2040 a 100 kHz; ESP32 / ESP8266 a 50 kHz. No use 400 kHz.
  • Autoincremento de puntero: solo en lecturas. Una lectura en ráfaga de + N bytes devuelve N bytes consecutivos a partir de addr. Las escrituras NO autoincrementan: una escritura en ráfaga descarta los bytes 1..N y solo se aplica el primero. Los registros multibyte se escriben byte a byte en transacciones separadas de un byte. Véase 09 · Referencia de la API: «Escrituras multibyte».

Longitud del bus

El I²C es un bus corto (~15 cm por defecto). Muchos usuarios conectan los módulos con cables de puente de baja calidad, que captan mucho ruido y pierden numerosas transferencias; de ahí el límite corto. Topologías recomendadas para rbAmp:

Cable Longitud máxima Velocidad
JST estándar / 4 conductores planos hasta 0.15 m 100 kHz
Par trenzado UTP (cat-5/5e/6): SDA+GND y SCL+GND en pares separados hasta 1 m 100 kHz
Par trenzado + buffer I²C (PCA9515 / TCA9617) hasta 3 m 100 kHz
Bus diferencial (PCA9615 / LTC4332) hasta 100 m 100 kHz
Seguridad

Para longitudes superiores a 0.15 m, el par trenzado es obligatorio: SDA y SCL deben ir en pares distintos, cada uno con su propia masa (por ejemplo, azul + azul-blanco para SDA, verde + verde-blanco para SCL). SDA y SCL en un mismo par crean una capacidad de acoplamiento cruzado que distorsiona los flancos.

⚠ Dentro de un armario eléctrico, apantalle el cable I2C. Los campos magnéticos intensos cerca de conductores de red, contactores y transformadores inducen ruido en un cable sin apantallar. Mantenga el cable lo más corto posible y alejado del cableado de red.

Cableado del lado de red (sensores)

Seguridad

⚠ La tensión de red puede matar. Desconecte y bloquee el circuito antes de conectar los terminales L/N o colocar la pinza; que un profesional cualificado haga el cableado de red y cualquier trabajo dentro de un cuadro. Pince UN solo conductor (L): nunca el cable completo (L+N se anulan hasta ~0). Proteja la derivación de L según la normativa local.

Sensor de tensión (variantes UI*)

La placa dispone de terminales L (línea) y N (neutro). La polaridad importa para el signo de la potencia activa:

  • Correcto (L → L, N → N): P > 0 significa consumo (corriente desde la red hacia la carga), P < 0 significa exportación a la red (generación).

  • Invertidos (L y N intercambiados): el signo de P se invierte; el consumo se cuenta como potencia negativa.

Cable y fusible. No hace falta un cable grueso para la conexión de tensión: basta con AWG26–22, porque el sensor de tensión consume muy poca corriente. Un fusible en la línea L es obligatorio, de hasta 0.1 A.

La polaridad correcta es crítica para:

  • Contabilidad correcta en el nivel BASIC (BASIC cuenta solo max(P, 0); con la polaridad invertida el contador de energía se queda en cero).

  • Separación correcta del consumo y la generación en la línea STANDARD (STD).

Comprobación rápida

: con una carga puramente resistiva (hervidor eléctrico, calentador, lámpara incandescente) P > 0 y PF ≈ 1.0. Si P es negativo con una carga consumidora, intercambie L y N en la placa.

Sensor de corriente: pinza TC SCT-013

Las pinzas de CT externas se conectan al módulo mediante un conector jack de 3.5 mm. El conector tiene muesca de orientación: no hay que tomar decisiones de cableado.

Una flecha en el cuerpo de la pinza indica el sentido de la corriente para la orientación «normal». Reglas:

  • Coloque la pinza CT alrededor solo del conductor de línea (L) que va a la carga.
  • La flecha de la pinza debe apuntar en el sentido de la corriente hacia la carga (desde el interruptor hacia la carga).

  • La pinza debe cerrarse por completo, sin hueco entre las mitades del núcleo magnético. Si las mitades no encajan del todo, se pierde precisión.

Seguridad

⚠ No pase L y N a través de una misma pinza a la vez. Sus flujos magnéticos son iguales y opuestos, así que se anulan: el sensor leerá en torno a cero incluso con carga.

Para más información sobre la elección del modelo SCT-013 (5A / 10A / 30A / 50A / 100A) y cómo indicárselo al módulo mediante dev.setCTModel(code), véase 03_sensor_selection.md.

Seguridad

⚠ La polaridad de la pinza de CT importa en BASIC: si la flecha de la pinza apunta lejos de la carga (o si L/N están intercambiados en los terminales), P_real lee negativo con consumo, y el nivel BASIC recorta max(P, 0), así que el contador de Wh se queda en cero. Gire la pinza físicamente sobre el conductor; no la invierta por software.

Conexión del lado de red en un cuadro: pinza CT en el cable L tras el interruptor general, N fuera de la pinza, derivación de L con fusible y N como referencia de tensión.

DATA_READY (DRDY)

Un pin opcional para optimizar el sondeo. Si la aplicación consulta el módulo no más de una vez cada 100 ms, DRDY puede dejarse sin conectar.

Parámetros eléctricos

  • Tipo de salida: drenador abierto (sin pull-up activa a VCC)
  • Nivel de reposo: ALTO (requiere una pull-up en el lado del maestro: la pull-up integrada del MCU o una resistencia externa)

  • Pulso de listo: BAJO durante ~10 µs tras actualizar los registros RT (0x86..0xCF) con datos nuevos

  • Frecuencia de pulsos: ~10 Hz (un pulso por ventana RT de ~100 ms)

La biblioteca puede usar la línea por usted: dev.setDrdyPin(pin) la conecta (pull-up interna, interrupción por flanco de bajada), y dev.waitDataReady() / dev.readAllReady() esperan la siguiente instantánea del módulo; véase 09 · Referencia de API. Varios módulos pueden compartir una línea DRDY (OR cableada); una línea mantenida fija en BAJO significa que un módulo tiene un evento enmascarado pendiente (alarma). Sin línea, las mismas llamadas sondean.

Semántica

Un flanco de bajada en DRDY garantiza que todos los registros RT están sincronizados y publicados (el firmware los actualiza de forma atómica en una ISR antes de bajar el pin). Tras el flanco de bajada, el maestro puede leer 0x86..0xCD sin riesgo de obtener una muestra partida.

Uso en Arduino

  • Interrupción externa (attachInterrupt en el flanco de bajada): despierta al maestro y dispara una lectura.

  • Pull-up: INPUT_PULLUP en el MCU, o una resistencia externa de 10 kΩ a 3.3 V. En UNO / Nano (AVR) use una resistencia externa de 10 kΩ a 3.3 V: la pull-up integrada (~40 kΩ) es demasiado débil para líneas DRDY largas.

C++
const int PIN_DRDY = 15;
volatile bool data_ready = false;

#if defined(ESP32) || defined(ESP_PLATFORM)
void IRAM_ATTR on_drdy() { data_ready = true; }   // ESP32 — ISR in IRAM
#else
void on_drdy() { data_ready = true; }             // AVR / STM32duino / RP2040 / SAMD
#endif

void setup() {
    Wire.begin();
    while (!dev.begin()) { delay(500); }

    // Raise the pull-up + attach the ISR AFTER dev.begin() — this
    // guarantees the module is already ready and the pull-up edge will not
    // cause a spurious interrupt before the first RT window is captured.
    // INPUT_PULLUP is fine for most cases; for long
    // lines or AVR hosts add an external 10 kΩ to 3.3 V.
    pinMode(PIN_DRDY, INPUT_PULLUP);
    attachInterrupt(digitalPinToInterrupt(PIN_DRDY), on_drdy, FALLING);
}

void loop() {
    if (!data_ready) return;     // sleep until the next RT window
    data_ready = false;
    float p = dev.readPower(0);
    // ...integration / transmit...
}

DRDY es opcional: el sondeo a cualquier frecuencia ≤ 10 Hz funciona sin él. La biblioteca no depende de DRDY; setDrdyPin() / waitDataReady() son auxiliares opcionales.

Conexión a distintos hosts Arduino

El módulo funciona con cualquier placa compatible con Arduino a través del Wire estándar. A continuación figuran los pines por defecto estándar de las variantes más habituales.

Arduino UNO / Nano (lógica de 5 V)

rbAmp Pin de Arduino
VCC +5V
GND GND
SDA A4
SCL A5
DRDY (opc.) cualquier digital, p. ej. D2
C++
#include 
#include 

RbAmp dev(Wire, 0x50);

void setup() {
    Wire.begin();          // SDA=A4, SCL=A5 by default
    Wire.setClock(100000); // 100 kHz — no 50 kHz clamp needed on AVR
    while (!dev.begin()) { delay(500); }
}

La UNO es un host de 5 V, no hace falta traductor de nivel (las líneas SDA/SCL del módulo toleran 5 V). Las pull-ups integradas del módulo llevan las líneas a 3.3 V, que un maestro de 5 V lee correctamente como ALTO.

Arduino Mega 2560 (lógica de 5 V)

rbAmp Pin Mega
VCC +5V
GND GND
SDA D20
SCL D21
DRDY (opc.) cualquier digital, p. ej. D18 (admite interrupciones)

Idéntico a la UNO en el código; solo cambian los pines físicos. No hace falta traductor de nivel.

ESP32 / ESP32-S3 / ESP32-C3 (lógica de 3.3 V)

rbAmp Pin ESP32 DevKitC
VCC +5V (alimentado desde USB-5V en la DevKitC)
GND GND
SDA GPIO21
SCL GPIO22
DRDY (opc.) cualquier GPIO libre, p. ej. GPIO4
C++
#include 
#include 

RbAmp dev(Wire, 0x50);

void setup() {
    Wire.begin(21, 22);    // SDA=21, SCL=22 (or Wire.begin() with board defaults)
    Wire.setClock(50000);  // ESP32: 50 kHz
    while (!dev.begin()) { delay(500); }
}

El ESP32 es un host de 3.3 V; conexión directa al módulo. La alimentación VCC se toma del pin +5V de la DevKitC (que va directamente a USB-5V).

Nota

Pinza de 50 kHz para ESP32: el patrón recomendado. En lugar de una llamada explícita Wire.setClock(50000), defina la macro opcional antes del include: begin() aplicará la pinza internamente:

C++
#define RBAMP_ESP32_CLAMP_HZ 50000
#include 

La macro es opcional (no activa por defecto), para que las llamadas explícitas del usuario a Wire.setClock() (por ejemplo, cuando una OLED comparte el bus) se conserven. Ambas formas funcionan: elija la que se lea mejor en su sketch.

Si su placa ESP32 no expone un pin de 5 V (algunos módulos compactos ESP32-S3 / C3 solo tienen Vin o no tienen 5 V), alimente rbAmp desde una fuente externa de 5 V (por ejemplo, un cargador USB + adaptador), con la masa GND compartida con el ESP32.

Una nota aparte sobre el reinicio del módulo:

Nota

Para un reinicio por software del módulo, use dev.reset(): la biblioteca envía el comando y el módulo se reinicia en ~100 ms. Si necesita un reinicio duro (por ejemplo, para recuperarse de un estado de bloqueo), corte la alimentación de VCC (desconéctela durante 1 segundo o más).

ESP8266 (Wemos D1 mini / NodeMCU, lógica de 3.3 V)

rbAmp Pin ESP8266 (NodeMCU)
VCC Vin o +5V
GND GND
SDA D2 (GPIO4)
SCL D1 (GPIO5)
DRDY (opc.) D5 (GPIO14)
C++
#include 
#include 

RbAmp dev(Wire, 0x50);

void setup() {
    Wire.begin(D2, D1);      // SDA=GPIO4, SCL=GPIO5
    Wire.setClock(50000);    // ESP8266 software I²C: 50 kHz for consistency with ESP32
    while (!dev.begin()) { delay(500); }
}

El ESP8266 es un host de 3.3 V, conexión directa.

STM32duino (placa de desarrollo STM32F1 F103 / Black Pill F411, lógica de 3.3 V)

rbAmp Pin STM32 (placa de desarrollo STM32F1)
VCC +5V
GND GND
SDA PB7 (I²C1_SDA)
SCL PB6 (I²C1_SCL)
DRDY (opc.) cualquier GPIO con EXTI, p. ej. PA0
C++
#include 
#include 

RbAmp dev(Wire, 0x50);

void setup() {
    Wire.begin();           // SDA=PB7, SCL=PB6 by default for I²C1
    Wire.setClock(100000);  // the STM32 HAL I²C needs no 50 kHz clamp
    while (!dev.begin()) { delay(500); }
}

STM32duino admite varias instancias de Wire (Wire1, Wire2 para un segundo I²C). Si el bus principal está ocupado, use el segundo periférico I²C.

RP2040 / SAMD (Raspberry Pi Pico, arduino-pico)

rbAmp Pin RP2040 (Pico)
VCC VBUS (5 V desde USB) o +5V
GND GND
SDA GP4
SCL GP5
DRDY (opc.) cualquier GP
C++
#include 
#include 

RbAmp dev(Wire, 0x50);

void setup() {
    Wire.setSDA(4);
    Wire.setSCL(5);
    Wire.begin();
    Wire.setClock(100000);  // the RP2040 hardware I²C needs no 50 kHz clamp
    while (!dev.begin()) { delay(500); }
}

El RP2040 es un host de 3.3 V con conexión directa. En placas SAMD (Arduino Zero, MKR), Wire.begin() con valores por defecto funciona igual; los pines concretos dependen de la placa.

Nota

Pico mediante VSYS (batería / alimentación externa): el pin VBUS solo tiene tensión cuando se alimenta por USB. Si la Pico funciona con una batería o una fuente externa a través de VSYS, VBUS no llevará nada. Alimente con 5 V desde una fuente externa directamente al VCC del módulo, con el GND compartido con la Pico.

Esquema de cableado de referencia (ESP32 + un módulo)

Esquema de conexión de una placa ESP32 a un único módulo rbAmp, con la pinza CT en el cable L.

En esta configuración:

  • NO se necesitan resistencias de pull-up externas en I²C (vienen integradas en el módulo).
  • DRDY es opcional; como en la imagen, use una resistencia externa de pull-up de 10 kΩ a 3.3 V (INPUT_PULLUP en el pin del ESP32 también funciona con cables cortos).
  • El conector del TC de la pinza SCT-013 está completamente insertado.
  • La pinza está completamente cerrada sobre el cable L, con la flecha hacia la carga.

Esquema de cableado de referencia (Arduino UNO + un módulo)

Esquema de cableado de referencia de un Arduino UNO con un único módulo rbAmp, con la pinza de CT en el cable L.

En esta configuración:

  • NO se necesitan resistencias de pull-up externas en I²C.
  • La UNO trabaja con lógica de 5 V; las líneas SDA/SCL del módulo toleran 5 V, no hace falta traductor de nivel.
  • DRDY tiene un nivel de 3.3 V: en la UNO una entrada TTL lo lee como ALTO (VIH_TTL ≥ 2.0 V, 3.3 V > 2.0 V). Se recomienda una pull-up de DRDY específicamente a 3.3 V por seguridad: si los circuitos de protección internos del pin DRDY no toleran 5 V (por separado de las líneas I²C, cuya tolerancia a 5 V está confirmada), una pull-up a 5 V crearía una pequeña corriente de fuga a través de los diodos ESD hacia el raíl de 3.3 V del módulo. A 3.3 V nunca hay problema.

Modelos polifásicos y la línea STANDARD (STD)

Las referencias multicanal y multifase mantienen la misma disposición de baja tensión (VCC / GND / SDA / SCL / DRDY). Solo cambia el lado de red: más terminales L y más conectores de toma de TC.

Los módulos ESTÁNDAR (STD) usan el mismo cableado I²C que los módulos BASIC: las mismas cuatro líneas de señal y las mismas reglas de pull-up y de bus que arriba. En la conexión no cambia nada; dev.begin() detecta qué línea está conectada (dev.line()), y el mismo boceto sirve para ambas. Notas:

  • Las llamadas que existen solo en la línea STD (la familia std*, potencia reactiva y aparente) devuelven RB_ERR_NOT_IMPLEMENTED en un módulo BASIC (en BASIC, esta biblioteca no expone la potencia reactiva).

  • Algunas funciones STD dependen de la versión de imagen del módulo: los contadores de energía de microresolución, la corriente de arranque para la energía, los ángulos de fase de tensión y la secuencia de fases necesitan una imagen de al menos 0x0001007B (dev.stdReadImageVersion()). Con una imagen anterior se notifican como «no disponibles».

  • El número de canales de tensión y de corriente lo proporciona el módulo (dev.stdInfo()); la biblioteca expone hasta RBAMP_MAX_CHANNELS (7) canales de corriente.

Bus multimódulo: la topología principal

El caso de uso canónico de la biblioteca son varios módulos rbAmp en un mismo bus I²C, gestionados por un único Arduino / ESP32 mediante RbAmpFleet. Todas las reglas y optimizaciones siguientes están pensadas para exactamente esta topología; un módulo individual es un caso particular (el mismo handle, pero las llamadas de flota se reducen a triviales).

Varios módulos rbAmp en un mismo bus I²C con las pull-ups integradas desconectadas y un par de pull-ups externas en el maestro, más las opciones de DRDY.

Despliegues típicos

Escenario Configuración Número de módulos
Canon del 80 %: acometida de la vivienda + submedidores 1× UI1 (alimentación, energía de red) + 3-6× UI1/I1 (cargas) 4-7
Subpanel con desglose de corriente 1× UI1 (alimentación) + 1-2× I2/I3 (corriente por circuito) 3-5
Submedición industrial 1× UI1 (alimentación) + N× I2/I3 (por máquina, desglose de corriente) hasta ~16

Límites eléctricos

  • Número de módulos: hasta ~16 (capacidad total del bus ≤ 400 pF a 100 kHz; a 50 kHz hay más margen).
  • Pull-ups para el bus de la flota (importante): cada módulo trae 4.7 kΩ integradas. En un bus multimódulo, N pull-ups trabajan en paralelo → el sumidero se sobrecarga y el bus no puede bajar a BAJO. A partir de 4 módulos (o antes en un bus de más de 15 cm), corte las pull-ups integradas en todos los módulos excepto en uno; con 2–3 módulos en un bus de hasta 15 cm, déjelas como están, ese caso está medido (o córtelas en todos y deje solo las externas (2.7…3.3 kΩ para 3 módulos, menores para buses más grandes; véase la tabla de arriba) a 3.3 V en un único punto del bus, recomendado para tiradas largas / ruido / ESP32 como maestro).
  • Las resistencias de pull-up internas del ESP32 (~45 kΩ) son demasiado débiles para un bus multimódulo con longitudes reales: se necesitan resistencias de pull-up externas (valores: véase la tabla anterior). Forma parte de la mitigación en tres capas contra el bloqueo del bus en un bus marginal: véase 10 · Solución de problemas, la sección «El proyecto ESP32 se bloquea».

Direccionamiento: aprovisionamiento y cambio en campo (apto para producción)

La dirección de fábrica por defecto es 0x50. Todo módulo nuevo o de sustitución pasa por aprovisionamiento (una vez): reasignación de 0x50 a una dirección operativa + guardado opcional de la configuración (modelos de CT, group_id, etiqueta) en flash. No se requiere el modo de fábrica: el cambio de dirección funciona directamente en producción mediante commit de dirección en dos fases.

El aprovisionamiento direcciona un módulo virgen cada vez: conecte un módulo en 0x50, ejecute la llamada de aprovisionamiento, verifique en la nueva dirección y después conecte el siguiente.

C++
RbAmp* dev = nullptr;
if (RbAmpFleet::provision(Wire, /*desired=*/0x52, /*save=*/true, dev)) {
    fleet.add(dev);   // ready handle, now in the fleet
}

Una sola llamada explora 0x50, realiza la confirmación de dirección en dos fases, reinicia, busca el módulo en la nueva dirección dentro de la ventana de arranque y (opcionalmente) emite SAVE_USER_CONFIG para persistir. Devuelve false ante una infracción de la disciplina (véase abajo) o un fallo de transporte.

Método 2: prepare/commitAddressChange de bajo nivel (forma manual)

C++
dev.prepareAddressChange(0x52);   // candidate in RAM
dev.commitAddressChange();        // arms 0xA5 + COMMIT_ADDR + reset
delay(300);                        // boot window

El mismo mecanismo de dos fases que en provision(), sin el envoltorio de flota. Se usa cuando no se ha creado RbAmpFleet.

Protocolo de bus por dentro (como referencia)

Text
1. write candidate_addr → REG_I2C_ADDRESS (0x30, in RAM)
2. write 0xA5 → REG_ADDR_COMMIT_MAGIC (0x31, armed)
3. issue CMD_COMMIT_ADDR (opcode 0x30 in REG_COMMAND)
4. wait ~700 ms (flash erase + write)
5. issue CMD_RESET (opcode 0x01) — CMD_COMMIT_ADDR does not auto-reset
6. wait ~300 ms; the module responds at the new address
Seguridad

✅ REG_I2C_ADDRESS (0x30) lee la dirección activa al arrancar (v1.3 addr-boot-sync). Tras el reinicio posterior a la confirmación, leer 0x30 muestra la nueva dirección activa. El comportamiento de eco de la preparación persiste hasta CMD_COMMIT_ADDR + reinicio.

⚠ Disciplina de aprovisionamiento: DEBE haber un único módulo virgen cada vez.

La causa más habitual de los fallos de aprovisionamiento es tener más de un módulo con la dirección de fábrica 0x50 en el bus. Es físicamente imposible distinguirlos por I²C (bus de drenador abierto: ambos módulos responden ACK de forma idéntica, y los datos leídos aparecen «pegados»).

Así que la regla es estricta (un MUST normativo, no una recomendación): en el momento de llamar a RbAmpFleet::provision() (o prepareAddressChange()), debe haber exactamente un módulo en 0x50 (uno nuevo o uno devuelto a los valores de fábrica mediante una herramienta de banco aparte). Nada de «estoy seguro de que estos dos módulos son distintos; los separo ahora»: no funcionará, y la colisión aparece después, cuando ya crea que la flota está limpia.

Ruta de recuperación si sospecha una violación de la disciplina: 1. Apague y encienda todos los módulos. 2. Desconecte físicamente todos menos un módulo «virgen». 3. Llame a RbAmpFleet::provision() en el bus con un único módulo. 4. Añada los módulos restantes de uno en uno, aprovisionando cada uno por separado.

Presupuesto de potencia del bus

A 50 kHz, una transacción de lectura ≈ 200-400 µs. Un bloque RT completo de un canal (U + I + P + FP) ≈ 5-8 ms por canal.

Configuración Bus por ciclo A 50 kHz Frecuencia máxima de sondeo
1× UI1, bloque RT ~5 ms < 5 ms 100+ Hz (pero el módulo actualiza a 10 Hz)
1× UI3, bloque RT + periodo ~25 ms ~25 ms hasta 10 Hz
5× UI1, bloque RT ~25 ms ~25 ms hasta 10 Hz
16× UI3, RT + período ~400 ms 400 ms > 100 ms no puede seguir el ritmo del módulo (10 Hz); como mucho ~2 Hz
Nota

Las cifras son estimaciones (200-400 µs por transacción según el MCU). Son estimaciones y dependen del MCU del host.

Regla: a 50 kHz los límites cómodos son 8-10× UI3 o 15-16× UI1 con sondeo a 5 Hz (cada segunda ventana de módulo), y aproximadamente la mitad a los 10 Hz completos.

Sincronización de periodos

Sincronización de periodos entre módulos: instantánea secuencial con un pequeño desfase frente a una única trama General-Call en la dirección 0x00.

Para la medición tarifaria, todos los módulos deben tomar su instantánea sobre el mismo intervalo. Dos estrategias:

Estrategia 1: instantánea secuencial + estabilización común (cualquier firmware):

C++
RbAmp meters[N];   // array of initialized modules

void period_cycle() {
    // Phase 1: sequential snapshot
    for (auto& m : meters) m.latchPeriod();

    // Phase 2: common settle (≥ 50 ms)
    delay(50);

    // Phase 3: read the snapshots with skip_latch=true
    for (auto& m : meters) {
        RbAmpSnapshot snap;
        m.readPeriodSnapshot(snap, /*skip_latch=*/true);
    }
}

Desviación entre módulos: 16 módulos × ~1 ms/instantánea = ~16 ms en un período de 60 s. Despreciable para los totales de energía.

Estrategia 2 — instantánea por difusión General-Call (requiere activación):

Todos los módulos toman su instantánea con una única trama I²C en la dirección 0x00:

Text
addr=0x00 | A5 27      (5 bytes)

Desviación = 0 (atómica). Preconfiguración (una vez en cada módulo de la flota):

  1. Establezca REG_FLEET_CONFIG.bit0 = 1 mediante CMD_SAVE_USER_CONFIG.
  2. CMD_RESET — la recepción GC se activa al arrancar.
  3. Tras el reinicio, el maestro envía la trama de 5 bytes en 0x00.
  4. Testigo: para cada módulo esperado, lea REG_V03_PERIOD_VALID (0x07). Si !=1, recurra a la estrategia 1.

Cuál usar:

  • < 8 módulos: estrategia 1 (más sencilla, no requiere habilitación).
  • ≥ 8 módulos o sincronización estrecha: estrategia 2.

Filtrado por grupo GC (bus multiusuario)

REG_GROUP_ID (0x28) permite tener varios dominios GC en un mismo bus:

  • group = 0x00 → all-call (todos los módulos con GC habilitado toman una instantánea).
  • group = N → solo los módulos con REG_GROUP_ID = N toman una instantánea.

Caso de uso: separar grupos tarifarios (día y noche) en un bus compartido.

Modos de fallo

Síntoma Causa Qué hacer
i2c bus scan muestra varios módulos en una misma dirección tras añadir uno en campo Un módulo nuevo en 0x50 entra en conflicto con uno ya direccionado Reasigne el nuevo módulo por separado antes de añadirlo
Un módulo responde NACK con más frecuencia que los demás Fallo de cable / caída de VCC Compruebe VCC bajo carga
Los Wh de un módulo divergen de forma constante El reloj propio del módulo difiere del del maestro La energía se integra con el reloj del maestro; compárela con master_dt_ms, no con latch_ms
Tras un marco GC, un módulo no toma la instantánea FLEET_CONFIG.bit0 = 0 o grupo no coincidente Compruebe REG_FLEET_CONFIG y REG_GROUP_ID

Notas de diseño del bus

  • Estiramiento de reloj: la instantánea del módulo lo pausa solo durante microsegundos; SCL no se estira de forma significativa. Para el Raspberry Pi BCM283x (error hardware conocido en el estiramiento): la precaución estándar es 50 kHz + reintento.
  • Longitud con más de 4 módulos: considere un buffer I²C (PCA9515) a partir de 8 módulos + longitud > 1 m.

Escenarios multimódulo detallados: en 06 · Ejemplos.

Lo que viene después


Fuente y incidencias: rb-amp/rbamp-arduino · esta página en el repositorio: docs/04_hardware.md (v1.6.2)