09 · Referencia de API
La API pública de la biblioteca RbAmp para Arduino desde la v1.6.1. Una sola clase sirve a ambas líneas de producto de módulos, BASIC y STANDARD (STD): begin() detecta la línea y cada llamada se enruta internamente. Las llamadas que existen solo en una de las líneas están marcadas; una llamada sin equivalente en la línea detectada falla con RB_ERR_NOT_IMPLEMENTED. Fuente de verdad: los archivos de cabecera src/RbAmp.h, src/RbAmpSnapshot.h, src/RbAmpEnergy.h, src/RbAmpSensorModels.h, src/RbAmpRegisters.h (los dos últimos se generan automáticamente y no deben editarse a mano).
Este capítulo es una referencia: firmas, valores de retorno, efectos secundarios, casos límite. Para ejemplos prácticos, véase 06 · Ejemplos; para el inicio rápido, véase 05 · Inicio rápido.
Archivos de cabecera
| Incluir | Qué aporta |
|---|---|
|
Todos los tipos públicos (incluye el resto) |
|
RbAmpSnapshot, RbAmpPeriodSnapshot, RbAmpTopology, RbAmpVariant, RbAmpLine, RbAmpSensorClass, RbAmpSctRating, RbAmpDrdyEvent y las estructuras RbAmpStd* de la línea STD |
|
RbAmpEnergy |
|
Registro generado de modelos de sensor: los códigos de modelo RBAMP_CT_* y rbamp_sensor_model_lookup() |
|
Constantes de protocolo generadas automáticamente: RB_OK, RB_ERR_*, SETTLE_MS_* |
Un sketch de usuario normalmente solo necesita #include ; el resto se incluye de forma transitiva.
¿En qué línea funciona una llamada?
| Grupo | BASIC | STD |
|---|---|---|
Ciclo de vida, lecturas en tiempo real (readVoltage … readAll), medición por período, energy() |
sí | sí |
readReactivePower(), readApparentPower() |
no (RB_ERR_NOT_IMPLEMENTED) |
sí |
Métodos establecedores de clase de sensor / modelo de CT, saveUserConfig(), cambio de dirección, reset() |
sí | sí (el modelo de CT es una etiqueta en STD, véase abajo) |
factoryReset(), ayudantes de llamada general, ayudantes de etiqueta, readCapability(), readCommitSeq(), readPeriodLatchMs() |
sí | no (RB_ERR_NOT_IMPLEMENTED) |
Línea de datos listos y eventos (setDrdyPin(), waitDataReady(), setEventMask() …) |
sí | sí (depende de la imagen del módulo, véase más abajo) |
Llamadas std* (API de la línea STD) |
no (RB_ERR_NOT_IMPLEMENTED) |
sí |
Corrección de calibre SCT-013 (sctRating*()) |
sí (clase SCT-013, firmware BASIC anterior) | nunca aplicado (escala 1) |
Algunas funciones STD dependen de la versión de imagen del módulo: los contadores de microenergía, 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 (stdReadImageVersion()). En una imagen anterior, la biblioteca las notifica como «no disponibles» (un flag valid en false, un valor derivado o RB_ERR_NOT_IMPLEMENTED), nunca como un número erróneo.
Clase RbAmp
El cliente principal. Una instancia por dispositivo esclavo en el bus I²C. Varias instancias pueden compartir un único bus TwoWire para sondear varios módulos.
Constructor
explicit RbAmp(TwoWire& bus,
uint8_t addr = 0x50,
RbAmpTopology hint = RbAmpTopology::Single) noexcept;
| Parámetro | Descripción |
|---|---|
bus |
Referencia al bus TwoWire (normalmente Wire). El código llamador debe ejecutar bus.begin() ANTES de begin(). |
addr |
Dirección de esclavo de 7 bits. Rango 0x08..0x77, por defecto 0x50. |
hint |
Indicación de topología: el número de canales de corriente (1/2/3). En firmware anterior a v1.3, begin() no puede determinar la variante de forma fiable, así que la indicación se usa como alternativa para las referencias multicanal. Por defecto es Single, la opción segura, que no provoca lecturas espurias de canales ausentes. En módulos multicanal con firmware anterior a v1.3, pase la indicación correspondiente explícitamente. |
El constructor no genera tráfico I²C.
Métodos de ciclo de vida
bool begin() noexcept
02 · Inicialización y arranque (initialization) · ¿BASIC o STD? (initialization) · Ciclo de sondeo continuo (recomendado) (period-metering)
Sondee el dispositivo, detecte su línea de producto y su variante, y cebe la instantánea.
Sequence:
-
Primero la identificación STD. Si el módulo responde como STD, los números de canales proceden del propio módulo, el banco de instantáneas 0 se arma y se prepara, y
begin()retorna: se omiten los pasos BASIC siguientes. -
Lea
REG_VERSION(0x03). Si el dispositivo no hizo ACK:falseconRB_ERR_NACK. Si devolvió0x00/0xFF:falseconRB_ERR_VERSION. -
Guarde en caché la topología: el byte de variante del módulo en el firmware que lo expone; si no, la
hintdel constructor. Después,topology()/channels()devuelven valores válidos sin tocar el bus. El número de canales nunca superaRBAMP_MAX_CHANNELS(7); los canales por encima no se exponen y direccionarlos devuelveRB_ERR_PARAM. -
Lea
U_rmspara determinar si hay un sensor de tensión (umbral 1.0 V). -
Escriba
CMD_LATCH_PERIODcomo cebado + espere 50 ms. La primera instantánea tras el encendido se descarta (no se entrega al código del usuario, porque mezcla datos previos al encendido). -
Guarde
millis()para la posterior integración de energía. - En un módulo BASIC con la clase SCT-013, lea la corrección de calibre por canal (véase Corrección de calibre SCT-013). Si el módulo está en un estado que requiere un reinicio para aplicar la ganancia correcta,
begin()lo reinicia una vez.
Idempotente: es seguro volver a llamarla.
Devuelve: true si tiene éxito; false en otro caso: consulte lastError() para los detalles.
bool probe() noexcept
Una comprobación ligera de que el módulo responde. Una sola lectura de REG_VERSION sin efectos secundarios.
Devuelve: true si el esclavo hizo ACK e informó una versión admitida (ni 0 ni 0xFF).
bool waitReady(uint32_t timeout_ms = 1000) noexcept
02 · Inicialización y arranque (initialization) · 3. DATA_VALID (0xCE) nunca pasa a 1 (troubleshooting) · 4 · Mapa de registros (producción v1.3) (api-reference)
Consulta el flag de listo del módulo hasta que el bit 0 esté activo. Útil tras el encendido: el módulo puede necesitar hasta una ventana de medida (100 ms) para confirmar sus primeros datos.
Devuelve: true si el bit se vio antes de que transcurrieran timeout_ms; false con RB_ERR_TIMEOUT en caso contrario.
uint8_t firmwareVersion() noexcept
Devuelve: el byte REG_VERSION (0x03). Valores BASIC conocidos: 0x01 = v1.0, 0x02 = v1.1, 0x03 = v1.2, 0x04 = v1.3. El firmware BASIC posterior informa valores más altos. 0 o 0xFF indican un error de I²C (véase lastError()).
RbAmpLine line() const noexcept
Devuelve: la línea de producto detectada por begin(): RbAmpLine::Basic (el valor hasta que se ejecuta begin()) o RbAmpLine::Std. Sin acceso al bus.
RbAmpTopology topology() const noexcept
Devuelve: la topología en caché. Sin acceso al bus.
uint8_t channels() const noexcept
Corriente multicanal (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.10 Bloque de tiempo real V03 (0x86..0xBD) (api-reference) · 4.14 Ventana de acceso a canales (0x32 + 0x3C..0x3F) (api-reference)
Devuelve: el número de canales de corriente, 1..RBAMP_MAX_CHANNELS (7). En la línea STD el número es el que informa el módulo, limitado a RBAMP_MAX_CHANNELS.
bool hasVoltageHw() const noexcept
Devuelve: true si se detectó un sensor de tensión en begin(). En caché, sin tráfico.
uint8_t address() const noexcept
Devuelve: la dirección I²C activa de 7 bits. Se actualiza tras un commitAddressChange() correcto.
uint8_t rawTopology() noexcept
Lectura directa de REG_TOPOLOGY (0x24). A diferencia de topology(), esta función realiza una transacción I²C.
Returns:
1/2/3—SINGLE/SPLIT_PHASE/THREE_PHASE.0xFF— error de I²C.
Para la detección completa de la referencia SKU use readVariant() (lee REG_HW_VARIANT 0x55); véase Identificación y aprovisionamiento.
Lecturas en tiempo real (bloque RT, refresco de 100 ms)
Todos los métodos devuelven float. En caso de error devuelven NAN y establecen lastError(). Internamente se usa un reintento y un filtro de cordura para resistir las perturbaciones poco frecuentes del enlace en ESP-IDF (véanse los contadores de diagnóstico más abajo). El módulo publica valores nuevos una vez por ventana de medida: 100 ms (firmware BASIC anterior a v1.2 e imágenes STD hasta 0x7B: 200 ms).
float readVoltage(uint8_t phase = 0) noexcept
Tensión eficaz instantánea. phase es 0 en la línea BASIC; en la línea STD va de 0 .. n_voltage-1 (véase stdInfo()). Una fase fuera de rango devuelve NAN con RB_ERR_PARAM.
float readVoltagePeak(uint8_t phase = 0) noexcept
Tensión de pico en la ventana RT. Misma regla de phase.
float readCurrent(uint8_t ch = 0) noexcept
Corriente multicanal (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.14 Ventana de acceso a canales (0x32 + 0x3C..0x3F) (api-reference)
Corriente RMS instantánea en un canal. ch debe ser < channels(); de lo contrario, NAN con RB_ERR_PARAM. Incluye cualquier canal igual o superior a RBAMP_MAX_CHANNELS (7).
float readCurrentPeak(uint8_t ch = 0) noexcept
Corriente de pico en un canal durante la ventana RT.
float readPower(uint8_t ch = 0) noexcept
Referencia de registros RT (realtime-polling) · Contabilidad bidireccional (period-metering)
Potencia activa instantánea en un canal. Con signo: un valor negativo significa exportación (la carga devuelve potencia a la red; relevante en instalaciones fotovoltaicas o bidireccionales).
float readPowerFactor(uint8_t ch = 0) noexcept
Factor de potencia en un canal. Adimensional, rango −1..+1.
float readReactivePower(uint8_t ch = 0) noexcept: solo STD
Potencia reactiva en un canal, en var, con signo. En BASIC, esta biblioteca no expone la potencia reactiva: la llamada devuelve NAN con RB_ERR_NOT_IMPLEMENTED.
float readApparentPower(uint8_t ch = 0) noexcept — solo STD
Potencia aparente en un canal, en VA. En un módulo BASIC devuelve NAN con RB_ERR_NOT_IMPLEMENTED.
float readFrequency() noexcept
Frecuencia de la red, en Hz.
bool readAll(RbAmpSnapshot& out) noexcept
Referencia de registros RT (realtime-polling) · Sondeo: un solo módulo (realtime-polling) · 4.10 Bloque en tiempo real V03 (0x86..0xBD) (api-reference)
El bloque RT completo en una sola llamada, en una estructura RbAmpSnapshot. Equivale a las llamadas secuenciales de readVoltage() + readVoltagePeak()
readCurrent(0..N)+readCurrentPeak(0..N)+readPower(0..N)+readPowerFactor(0..N)+readFrequency(). Los canales no utilizados (más allá dechannels()) se rellenan con ceros.
Un campo único que se lee pero no supera el filtro físico de coherencia se pone a NAN y se marca en out.implausible (bits RBAMP_FIELD_*); el resto de la instantánea sigue siendo utilizable.
Devuelve: true salvo que una lectura de transporte haya fallado; en ese caso false y lastError() conserva el código del primer error.
Medición por periodos
Consulte 01 · Visión general para el panorama completo y el paso 5 de 05 · Inicio rápido para una plantilla mínima.
bool latchPeriod() noexcept
Escribe CMD_LATCH_PERIOD (0x27) en REG_COMMAND. No espera: el llamador debe observar por sí mismo el asentamiento de 50 ms y comprobar isPeriodValid() antes de leer.
Para la mayoría de tareas use readPeriodSnapshot(): encapsula toda la secuencia.
Devuelve: true si la escritura es correcta.
bool isPeriodValid() noexcept
04 · Medición por periodos y contabilidad por tarifa (period-metering) · Calibración y precisión (troubleshooting) · 7.5 Conservación del periodo tras una instantánea fallida (api-reference)
Lee el bit de listo de la instantánea. true si la última instantánea está actualizada y lista para leer.
float readPeriodAvgPower(uint8_t ch = 0) noexcept
Registros de instantánea de período (period-metering) · 4.11 Bloque de período V03 (0xBE..0xCF) (api-reference) · 4.12 V03 Q + período ch0 (0xD0..0xE3, compilación de producción) (api-reference)
Potencia activa media en un canal durante el período cerrado. Debe llamarse tras latchPeriod() + 50 ms de estabilización + comprobación de validez.
float readPeriodMaxPower() noexcept
Registros de instantánea de período (period-metering) · 4.12 V03 Q + período ch0 (0xD0..0xE3, compilación de producción) (api-reference)
Potencia instantánea de pico en el canal 0 durante el periodo cerrado.
uint32_t readPeriodLatchMs() noexcept
13. Deriva del reloj entre módulos en pruebas largas (troubleshooting) · 4.13 dt de diagnóstico en el chip (0xEC) (api-reference)
Duración del período desde el punto de vista del dispositivo, en ms.
latch_ms es un temporizador de diagnóstico del módulo; no lo use para la energía: use el reloj del maestro (master_dt_ms de RbAmpPeriodSnapshot).
bool readPeriodSnapshot(RbAmpPeriodSnapshot& out, uint16_t settle_ms = 50, bool skip_latch = false) noexcept
Ciclo de sondeo continuo (recomendado) (period-metering) · Multimódulo — instantánea simultánea (period-metering) · Calibración y precisión (troubleshooting)
El punto de entrada recomendado para la medición por período. La secuencia completa por dentro:
-
Si
skip_latch == true, se omite la escritura del comando de instantánea (se aplica trasbroadcastLatch()o una serie manual de comandos de instantánea). -
En otro caso, escriba
CMD_LATCH_PERIOD. - Capture
millis()para calcularmaster_dt_ms. -
delay(settle_ms)— 50 ms por defecto según la especificación del protocolo. -
Compruebe el flag de listo de la instantánea. Si es 0, establezca
RB_ERR_STALEy registre la marca de tiempo (para que la siguiente instantánea no duplique pordt). -
Lea
avg_p[0..channels-1]+max_p+latch_ms. - Actualice la marca de tiempo y llame a
energy().tick(out, channels_)para la integración automática de Wh.
| Parámetro | Descripción |
|---|---|
out |
Estructura de salida. |
settle_ms |
Espera tras el comando de instantánea; 50 por defecto. |
skip_latch |
Si es true, no envíe el comando de instantánea; solo lea (para una escena multicartuchos sincronizada). |
Devuelve: true si out.valid == true; false si la lectura falló o la instantánea está obsoleta.
En la línea STD, el asentamiento tras una instantánea se eleva a al menos 300 ms (el módulo atiende la instantánea en el siguiente límite de ventana de medida), latch_ms es 0 y master_dt_ms es el periodo. En un módulo STD que conserva contadores de energía de vida persistidos en lugar de bancos de instantáneas, el periodo es la diferencia de dos lecturas de contador según la programación del maestro; avg_p_total, wh_net y module_restarted de la instantánea se rellenan allí.
Medición de energía (acumulador en el lado del maestro)
RbAmpEnergy& energy() noexcept
const RbAmpEnergy& energy() const noexcept
Acceso al acumulador de Wh por canal propiedad de esta instancia de RbAmp. El acumulador se actualiza automáticamente en cada readPeriodSnapshot() correcto. Para más detalles véase la sección «clase RbAmpEnergy» más abajo.
double energyWh(uint8_t ch = 0) const noexcept
Algoritmo en el lado del maestro (period-metering) · 7 · Semántica (api-reference)
El total de energía acumulado de un canal, igual que energy().wh(ch), salvo en un módulo STD que conserva contadores persistidos pero no publica desglose por canal (más de un canal, mapa de registros anterior): una petición por canal devuelve NaN en ese caso, en lugar de un 0 que se leería como «nada consumido». Use RBAMP_ENERGY_CH_TOTAL como ch para el total de todos los canales.
Configuración del sensor
Una secuencia de dos pasos: primero la clase de sensor, después el modelo. Ambos pasos son obligatorios en el firmware BASIC v1.2 y posteriores.
Para una guía detallada de selección de modelo, consulte 03 · Selección del sensor de corriente.
Modelo de CT: una preconfiguración funcional en BASIC, una etiqueta en STD. En un módulo BASIC, escribir el modelo de CT aplica de inmediato la preconfiguración correspondiente: las lecturas de corriente cambian. Cambiar el RbAmpSensorClass pone a 0 los modelos de CT de los canales en el módulo. En un módulo STD el modelo es solo una referencia (etiqueta del sensor): no fija ninguna ganancia, porque el módulo se calibra por canal.
Leer antes de escribir. Los métodos establecedores leen primero el módulo. Escribir una clase o un modelo que el módulo ya tiene es una operación nula (true, sin escritura en el bus ni ciclo de flash), así que una configuración guardada puede volver a aplicarse en cada arranque sin tocar la calibración del módulo. Un módulo de clase WiredCT o BuiltinCT (suministrado y calibrado junto con su sensor) no se reconfigura: el método establecedor devuelve false con RB_ERR_MODE y no escribe nada. setCTModelChForce() es la vía de servicio.
Establecer un modelo de CT reinicia el módulo. En el firmware BASIC hasta la versión 1.4.19 con la clase SCT-013, setCTModel() (ambas formas) y configureChannels() reinician el módulo tras guardar para que el nuevo modelo surta efecto (en total alrededor de un segundo, de forma bloqueante), y después releen la corrección de calibre. No las llame en un bucle ni espere lecturas durante ese tiempo.
bool setSensorClass(RbAmpSensorClass cls) noexcept
Configuración de la clase de sensor y del modelo de CT (inicialización) · 4.3 Sistema (0x20..0x25) (api-reference) · 6.2 Vinculación del modelo de CT — preparación pura + CMD por canal (api-reference)
Establezca la clase del sensor de corriente con un guardado en flash.
Secuencia: leer la clase de corriente actual del módulo (leer antes de escribir) → escribir REG_SENSOR_CLASS (0x25) → CMD_SAVE_USER_CONFIG (0x32) → esperar 700 ms (borrado de flash). Bloqueante. Apto para producción: SAVE_USER_CONFIG no está restringido.
Debe llamarse antes que setCTModel(). En caso contrario, setCTModel() devuelve false con RB_ERR_PARAM. Además, pone a 0 los modelos de CT en el dispositivo, así que configure los modelos después. En la línea STD la clase son metadatos, se persiste con el guardado de configuración del módulo, y se aplican las mismas reglas de leer antes de escribir.
| Argumento | Significado |
|---|---|
RbAmpSensorClass::Sct013 |
Pinza SCT-013 de la serie instalada por el usuario; el modelo selecciona el tipo de sensor |
RbAmpSensorClass::WiredCT |
TC cableado que se suministra con el módulo y se calibra junto con él; los métodos establecedores no lo reescriben |
RbAmpSensorClass::BuiltinCT |
pinza integrada, calibrada junto con el módulo: los setters no la reescriben |
Devuelve: true si tiene éxito, o si el módulo ya tiene cls. false con RB_ERR_MODE cuando el módulo es de clase WiredCT / BuiltinCT.
bool readSensorClass(uint8_t& out) noexcept
Lee la clase de sensor de corriente del módulo (un valor de RbAmpSensorClass; 0 = sin asignar). Funciona en ambas líneas.
Devuelve: true si tiene éxito.
bool setCTModel(uint8_t code) noexcept
La forma de un solo parámetro: establece el modelo de pinza de CT solo en el canal 0. Cómoda para SKU de un canal (UI1/I1); en los multicanal equivale a setCTModel(0, code).
Secuencia: escriba REG_CT_MODEL (0x05) → CMD_SET_CT_MODEL_CH0 (código de operación 0x28) → asentamiento de 5 ms → CMD_SAVE_USER_CONFIG (código de operación 0x32) → 700 ms. Apto para producción: usa la ruta de guardado de configuración de usuario, sin restricción de modo de fábrica.
Nombre el modelo con el define RBAMP_CT_* generado (de RbAmpSensorModels.h), por ejemplo RBAMP_CT_SCT013_030:
| Definir | code |
Modelo |
|---|---|---|
RBAMP_CT_SCT013_005 |
1 | SCT-013-005 |
RBAMP_CT_SCT013_010 |
2 | SCT-013-010 |
RBAMP_CT_SCT013_030 |
3 | SCT-013-030 |
RBAMP_CT_SCT013_050 |
4 | SCT-013-050 |
RBAMP_CT_SCT013_100 |
5 | SCT-013-100 |
RBAMP_CT_SCT013_020 |
6 | SCT-013-020 |
RBAMP_CT_SCT013_060 |
7 | SCT-013-060 |
Un code que no está en el registro para la clase del módulo → false con RB_ERR_PARAM y sin escritura. Un código que está en el registro pero que el módulo no acepta es rechazado por el módulo con RB_ERR_PARAM; el canal conserva su modelo anterior. Para el conjunto completo de aceptación por clase, véase 03 · Selección de sensor de corriente.
Para módulos multicanal use la forma por canal que aparece abajo.
bool setCTModel(RbAmpCTModel model) noexcept
Sobrecarga con enumeración tipada para los siete códigos SCT-013 (RbAmpCTModel::Sct013_030 …). Equivale a setCTModel(static_cast. Se mantiene por compatibilidad con versiones anteriores; el código nuevo pasa un define RBAMP_CT_* generado a la forma uint8_t, que es la única manera de nombrar un CT cableado.
bool setCTModel(uint8_t channel, uint8_t code) noexcept
Configuración de la clase de sensor y del modelo de CT (initialization) · 6.2 Asociación del modelo de CT: preparación pura + CMD por canal (api-reference)
La forma por canal. Establece el modelo de pinza de CT en un canal concreto, 0 .. channels()-1 (los canales 3 y superiores son los del SKU superior; requieren firmware BASIC v1.4.18 o posterior).
Por debajo: escriba REG_CT_MODEL (0x05) → comando CMD_SET_CT_MODEL_CH0/1/2 (código de operación 0x28/0x29/0x2A) según channel → asentamiento de 5 ms → CMD_SAVE_USER_CONFIG (código de operación 0x32) → 700 ms. Apto para producción: la ruta de guardado de configuración de usuario es el canal de persistencia de producción para ct_model / sensor_class / CT por canal. Los canales 3 y superiores se vinculan a través de la ventana de canales y se leen de vuelta; un modelo que el módulo rechaza se notifica como RB_ERR_PARAM. En firmware anterior a v1.2 la llamada devuelve RB_ERR_VERSION.
El orden de las llamadas es arbitrario en la v1.3. Escribir REG_CT_MODEL (0x05) solo prepara un valor: no se aplica automáticamente al canal 0. La aplicación ocurre exclusivamente mediante el opcode por canal CMD_SET_CT_MODEL_CHn (0x28 / 0x29 / 0x2A), que copia el valor preparado en su propio canal. Por tanto, los canales pueden configurarse en cualquier orden (ascendente, descendente o intercalado) sin sobrescritura:
dev.setCTModel(0, RBAMP_CT_SCT013_005); // channel 0
dev.setCTModel(1, RBAMP_CT_SCT013_030); // channel 1
dev.setCTModel(2, RBAMP_CT_SCT013_020); // channel 2
Tras una vinculación multicanal, confirme el resultado con readCTModelCh(). Para una configuración de todos los canales por lotes y con un solo guardado, use preferentemente configureChannels().
Guarda RB_ERR_PARAM sobre la precondición de setSensorClass(), igual que en la forma de un solo parámetro. Un canal igual o superior a channels() (y por tanto cualquier canal más allá de RBAMP_MAX_CHANNELS) → RB_ERR_PARAM. La lectura antes de escribir y la negativa RB_ERR_MODE se aplican como se describió arriba. En la línea STD el modelo es una etiqueta escrita en la entrada del canal, leída de vuelta y persistida con el guardado de configuración del módulo; sin efecto secundario en el canal 0.
Devuelve: true si tiene éxito, o si el canal ya contenía code.
bool setCTModel(uint8_t channel, RbAmpCTModel model) noexcept
Sobrecarga tipada de la forma por canal (solo códigos SCT-013).
bool setCTModelChForce(uint8_t channel, uint8_t code) noexcept
Vía de servicio. Igual que setCTModel(channel, code), pero escribe independientemente de la clase del módulo y del modelo que tenga el canal en ese momento. Sustituye la calibración emparejada de ese canal por la preconfiguración genérica del modelo: úselo solo al reemparejar un módulo con un nuevo sensor en servicio, y siga con una calibración. Un código ausente del registro se sigue rechazando (RB_ERR_PARAM, sin escritura).
Devuelve: true si tiene éxito.
bool readCTModelCh(uint8_t channel, uint8_t& out) noexcept
4.7 Espejos de verificación del modelo de CT (0x51..0x53) (api-reference) · 8.10 Relectura del espejo de verificación del modelo de CT (comprobación posterior a la vinculación) (api-reference)
Lee el modelo de CT realmente aplicado a un canal (el espejo de verificación de la preconfiguración asociada). Úselo para confirmar que la asociación se aplicó. out = 0 significa sin asignar.
Devuelve: true si tiene éxito.
Registro de sensores — sensorModel() / sensorModelRatedA()
Búsquedas puras en el registro generado (RbAmpSensorModels.h). Sin tráfico en el bus. Que un código esté en el registro no significa que el módulo conectado lo acepte: lo decide el módulo en el momento de la escritura.
static const rbamp_sensor_model_info_t* RbAmp::sensorModel(uint8_t cls, uint8_t code) noexcept;
static const rbamp_sensor_model_info_t* RbAmp::sensorModel(RbAmpSensorClass cls, uint8_t code) noexcept;
static float RbAmp::sensorModelRatedA(uint8_t cls, uint8_t code) noexcept;
static float RbAmp::sensorModelRatedA(RbAmpSensorClass cls, uint8_t code) noexcept;
sensorModel() devuelve la entrada del registro o nullptr si (class, code) no está en el registro. La entrada (rbamp_sensor_model_info_t) contiene sensor_class, code, name, descriptor, status (caracterizado / reservado / heredado) y los límites actuales nominal_a (corriente RMS nominal), fs_a (corriente RMS al inicio del recorte para una senoidal) y peak_a (techo instantáneo de recorte). 0 en un límite = desconocido para ese modelo.
sensorModelRatedA() devuelve la corriente RMS nominal en amperios (0 = desconocida). Abarca la familia SCT-013 y los modelos de pinza que tienen valor nominal; los códigos heredados de toroide / carga devuelven 0.
float rated = RbAmp::sensorModelRatedA(RbAmpSensorClass::Sct013, RBAMP_CT_SCT013_030);
const rbamp_sensor_model_info_t* m = RbAmp::sensorModel(RbAmpSensorClass::Sct013, RBAMP_CT_SCT013_030);
if (m) Serial.println(m->descriptor);
Corrección de clasificación SCT-013
En el firmware BASIC hasta la versión 1.4.19, un módulo de clase SCT-013 se calibra con el SCT-013-030 y, tras un reinicio, aplica esa ganancia calibrada sea cual sea el modelo que muestre cada canal. La biblioteca compensa esto: begin() lee el modelo y la ganancia aplicada de cada canal y establece una escala por canal. La escala se aplica a readCurrent(), readCurrentPeak(), readPower(), readAll(), readPeriodAvgPower(), readPeriodMaxPower() y readPeriodSnapshot(), y, por tanto, a la energía derivada de ellos. El factor de potencia y la tensión no se modifican. Los límites de verosimilitud y setEventThresholds() se expresan en amperios y vatios reales.
Por tanto, cambiar la clasificación SCT-013 (por ejemplo, de 030 a 050) corrige automáticamente la corriente, la potencia y la energía; no cambia U ni PF. El firmware 1.4.20 y posteriores se corrige solo: la escala se mantiene en 1 y una escritura de modelo no necesita reinicio. Los módulos STD y las clases de CT cableadas o integradas nunca se escalan.
bool sctRatingRefresh() noexcept
Vuelve a leer el estado de clasificación de cada canal desde el módulo. La biblioteca ya lo hace tras readEventFlags() cuando informa EVENT_RESET_OCCURRED; llámelo usted mismo tras un reinicio del módulo que detecte de otra forma.
Devuelve: true cuando se pudo leer el módulo.
bool sctRating(uint8_t channel, RbAmpSctRating& out) noexcept
Estado de un canal: model, applied_gain, noise_floor, scale y status.
Devuelve: true si channel es válido.
RbAmpSctRatingStatus |
Significado |
|---|---|
NotApplicable |
línea STD, una clase distinta de SCT-013, firmware que se corrige a sí mismo o sin modelo establecido: escala 1 |
Native |
el canal muestra el modelo con el que se calibró el módulo (030): nada que corregir, escala 1 |
Corrected |
otro modelo SCT-013 con firmware BASIC anterior: las lecturas quedan escaladas |
Uncalibrated |
el módulo aplica un preajuste genérico sin ajuste propio: solo corrección nominal |
UnexpectedGain |
la ganancia aplicada no es la que espera la corrección: no se asume nada, escala 1 |
Unknown |
no se pudo leer el estado: escala 1 |
float sctRatingScale(uint8_t channel) const noexcept
El factor aplicado a las lecturas de corriente / potencia de ese canal (1.0 cuando no hay corrección, y para un índice de canal más allá de RBAMP_MAX_CHANNELS).
static float sctPresetGain(uint8_t model) noexcept
Valor de ganancia preestablecido de la biblioteca para un código de modelo SCT-013; 0 si se desconoce. Sobre todo útil para diagnóstico.
bool configureChannels(RbAmpSensorClass cls, const uint8_t* models, uint8_t n) noexcept
Véase Configuración multicanal.
bool saveGains() noexcept: solo en modo fábrica en BASIC
Una escritura CMD_SAVE_GAINS (0x26) «desnuda»: la vía de persistencia de fábrica para los coeficientes de calibración (ganancias / suelo de ruido / fase).
⚠ Solo de fábrica en BASIC. BLOQUEADO en producción. En un módulo BASIC de producción, CMD_SAVE_GAINS es rechazado por el firmware: la llamada devuelve false, REG_ERROR se establece en DEV_ERR_PARAM (0xFE) y el siguiente reinicio revierte cualquier escritura solo en RAM. Para toda la persistencia orientada al usuario (clase de sensor, modelo de CT por canal, dirección, configuración de flota, etiqueta) use saveUserConfig() (CMD_SAVE_USER_CONFIG, código de operación 0x32): esa es la ruta de persistencia apta para producción. El código de usuario en un despliegue no debería llamar a saveGains().
Línea STD: saveGains() emite el guardado de calibración del módulo, espera a que el módulo informe de que el comando ha terminado y comprueba su veredicto. El módulo escribe su almacén como máximo una vez cada 5 s; un guardado dentro de esa ventana se reintenta una vez tras 5 s.
Devuelve: true ante un comando correcto (en producción BASIC: siempre false con RB_ERR_MODE).
bool prepareAddressChange(uint8_t new_addr) noexcept
Cambio de dirección (inicialización) · 4.5 Dirección (0x30..0x31) (api-reference) · 6.1 Cambio de dirección — commit en dos fases (apto para producción) (api-reference)
Paso 1 de 2 para cambiar la dirección I²C del módulo. Apto para producción en el firmware actual (confirmación en dos fases de la v1.3, sin control de modo de fábrica para la dirección).
Secuencia: valide el rango de new_addr (0x08..0x77, ≠ actual) → escriba el candidato en REG_I2C_ADDRESS (0x30) en RAM → escriba el número mágico 0xA5 en REG_ADDR_COMMIT_MAGIC (0x31) — armado. El llamador debe invocar commitAddressChange() en los 5 segundos siguientes; de lo contrario, el armado caduca.
Devuelve: true si el armado fue correcto.
bool commitAddressChange() noexcept
Cambio de dirección (initialization) · 6.1 Cambio de dirección: confirmación en dos fases (apto para producción) (api-reference) · 8.5 Cambio de dirección en 5 pasos (api-reference)
Paso 2 de 2. Debe llamarse en los 5 segundos siguientes a prepareAddressChange().
Secuencia: comprobar la vigencia del estado armado mágico → CMD_COMMIT_ADDR (opcode 0x30) → persistir en flash → CMD_RESET (0x01) → ~300 ms desde el arranque hasta estar operativo → actualizar el campo de dirección interno. Después de esto, todas las llamadas de esta instancia usan la nueva dirección.
⚠ Reenumeración tras la confirmación. Tras una confirmación correcta, el dispositivo se reinicia y se reenumera en la NUEVA dirección. Las llamadas posteriores a esta instancia de RbAmp usan la nueva dirección de forma transparente, pero cualquier OTRO maestro del bus (un script de Python, un componente ESP-IDF en otro MCU, una sonda de depuración) seguirá creyendo que el dispositivo está en la dirección antigua hasta que su estado interno se actualice a mano.
⚠ Ruta de verificación (v1.3): tras el reinicio, REG_I2C_ADDRESS (0x30) lee la dirección activa. Un escaneo del bus en la nueva dirección también sirve para confirmar la aplicación.
El cambio de dirección es una operación de producción (no solo de fábrica). La dirección I²C: la ruta documentada es la reconfiguración desde el banco de fábrica (fuera del alcance de la biblioteca).
Una nota adicional para commitAddressChange():
⚠ Reinicio y reenumeración tras la confirmación. Tras una confirmación correcta, el dispositivo se reinicia y se reenumera en la NUEVA dirección. Las llamadas posteriores a esta instancia de RbAmp usan la nueva dirección de forma transparente, pero cualquier OTRO maestro del bus (un script de Python, un componente ESP-IDF, una sonda de depuración) seguirá creyendo que el dispositivo está en la dirección antigua hasta que su estado interno se actualice a mano.
Si la ventana de armado ha caducado, commitAddressChange() devuelve false con RB_ERR_TIMEOUT y borra el indicador de armado: hará falta un nuevo prepareAddressChange().
Devuelve: true si tiene éxito.
Línea STD: el campo de dirección se escribe y se guarda (la llamada espera a que termine el guardado; una dirección rechazada devuelve RB_ERR_PARAM y el módulo conserva su dirección), y después el módulo se reinicia. La instancia cambia a la nueva dirección solo cuando el módulo responde allí (hasta 3 s). Si vuelve a aparecer en la dirección ANTIGUA, la instancia se queda allí y se devuelve RB_ERR_NOT_READY.
bool factoryReset() noexcept
El comando CMD_FACTORY_RESET (0xAA) + espera de 1500 ms.
⚠ Operación destructiva. Borra TODOS los parámetros de flash (modelo de CT, clase de sensor, coeficientes de calibración, dirección I²C). El módulo vuelve a sus valores de fábrica: RbAmpSensorClass pasa a Unset y REG_CT_MODEL a 0. Cualquier ajuste aplicado antes mediante setSensorClass() / setCTModel() se pierde. El siguiente usuario DEBE volver a aplicar setSensorClass() y setCTModel() antes de que la medición funcione de nuevo. No es un «reinicio suave»; para uno suave use reset(). factoryReset() se reserva para recuperarse de un estado conocido como defectuoso o para entregar el módulo a otro usuario o a otra instalación.
Devuelve: true si la escritura del comando fue correcta.
Línea STD: no tiene equivalente; la llamada devuelve false con RB_ERR_NOT_IMPLEMENTED.
bool reset() noexcept
El comando CMD_RESET (0x01) + esperar 100 ms. Un reinicio suave del dispositivo sin perder los parámetros de flash.
Devuelve: true si la escritura del comando fue correcta.
Línea STD: espera primero a cualquier comando en curso (un módulo nunca se reinicia a mitad de un guardado), después espera en silencio (hasta 3 s) a que el módulo vuelva a responder y rearma la ruta de periodo.
Bus multimódulo (estático)
static bool broadcastLatch(TwoWire& bus) noexcept
Envía una instantánea por difusión I²C General-Call (A5 27 00 tick_lo tick_hi a la dirección 0x00): todos los módulos con GC habilitado toman la instantánea de período a la vez. En firmware v1.3, GC se admite como capacidad opt-in: habilitación por módulo mediante REG_FLEET_CONFIG.bit0 (desactivada por defecto); el mapa de capacidades del módulo indica si admite la instantánea General-Call. General-Call es una función de la línea BASIC (las funciones de General-Call y de etiqueta devuelven RB_ERR_NOT_IMPLEMENTED en una instancia STD).
Semántica de retorno:
-
Firmware v1.3, GC activada en al menos un módulo: devuelve
true, la flota toma su instantánea de forma sincronizada (desfase < 1 ms entre módulos). -
Firmware v1.3, GC desactivada en todos los módulos:
Wire.endTransmission()a0x00recibe NACK a nivel de bus y devuelvefalse. Solución: active la GC en cada módulo conenableGc(true)(escribeFLEET_CONFIG.bit0+SAVE_USER_CONFIG+ reinicio), o useRbAmpFleet::enableGcAll(). -
Firmware heredado sin soporte de General-Call: devuelve
falsesin tocar el bus. Recurra a una serie secuencial delatchPeriod()en cada dispositivo: véase 06 · Ejemplos, sección de bus multimódulo.
Diagnóstico
int8_t lastError() const noexcept
Devuelve: el código del último error: RB_OK (0) o uno de los valores RB_ERR_* (negativos). La tabla completa está en la sección «Códigos de error» de abajo + 10 · Solución de problemas.
static const char* errorString(int8_t code) noexcept
Devuelve: una cadena constante con una descripción legible del código de error. Nunca devuelve NULL.
void setLogStream(Stream* stream) noexcept
Un destino de diagnóstico opcional. Si se configura, la biblioteca registra brevemente los resultados de probe(), las instantáneas obsoletas y los rechazos de modo. Pase nullptr para desactivarlo. Desactivado por defecto.
Uso típico:
dev.setLogStream(&Serial);
uint32_t retryExhaustionCount() const noexcept
Cuántas veces desde el encendido (o desde el último resetCounters()) se agotó el bucle de reintentos durante una lectura de un solo byte. El valor en régimen estacionario es 0. Un valor distinto de cero indica problemas de enlace (véase 10 · Solución de problemas).
uint32_t sanityRejectCount() const noexcept
Cuántos valores float en bruto rechazó el filtro de cordura (!isfinite(x) || |x| > 10000). En régimen estacionario: 0. Un valor distinto de cero tras la mitigación por reintentos suele indicar un artefacto poco frecuente de la pila I²C de ESP-IDF que sobrevivió a la capa de reintentos.
void resetCounters() noexcept
Pone a cero ambos contadores. Úselo al inicio de una prueba de resistencia o de una ventana de regresión para medir solo los eventos dentro de la ventana.
const char* errorString() const noexcept
Atajo de instancia para errorString(lastError()). Nunca devuelve NULL.
bool readCommitSeq(uint8_t& out) noexcept: solo BASIC
Lee el byte de secuencia de confirmación del módulo. El módulo lo incrementa una vez por ventana de medida publicada (100 ms en firmware v1.2+, 200 ms antes), con vuelta de 255→0. Muéstrelo antes y después de una lectura de varios registros para detectar que los valores publicados avanzaron a mitad de la lectura. Es solo un indicador de cambio; no hay CRC. En una instancia STD la llamada falla con RB_ERR_NOT_IMPLEMENTED (use readDataSeq()).
Devuelve: true si tiene éxito.
Identificación y aprovisionamiento (v1.3)
Estos métodos permiten al maestro entender exactamente qué está conectado al bus (variante, mapa de bits de capacidades, UID, etiqueta) y preparar un módulo nuevo o recién flasheado para su funcionamiento (aprovisionamiento + guardado de la configuración en flash).
RbAmpVariant readVariant() noexcept
Autodetección de la variante del módulo (initialization) · Referencia del protocolo de cable de rbAmp (v1.3) (api-reference) · 3.6 Algoritmo de detección canónico (api-reference)
Lee el registro HW_VARIANT (0x55) del módulo y devuelve un RbAmpVariant:
| Valor | SKU | Canales I | Canal U |
|---|---|---|---|
UI1 (1) |
UI1 | 1 | sí |
UI2 (2) |
UI2 | 2 | sí |
UI3 (3) |
UI3 | 3 | sí |
I1 (4) |
I1 | 1 | no |
I2 (5) |
I2 | 2 | no |
I3 (6) |
I3 | 3 | no |
UI5 (7) |
UI5 (SKU superior) | 5 | sí |
UI7 (8) |
UI7 (referencia SKU superior) | 7 | sí |
Unknown (0) |
no identificado (firmware v1.0/v1.1, fallo de I²C o no es un rbAmp) | — | — |
La autodetección de variante mediante readVariant() es la vía recomendada. La indicación de topología del constructor se mantiene como alternativa para firmware anterior a v1.2 (donde HW_VARIANT no está disponible). Indicación por defecto = RbAmpTopology::Single: segura, no provoca lecturas espurias de canales ausentes en UI1/I1.
bool readCapability(uint16_t& out) noexcept: solo BASIC
Autodetección de la variante del módulo (inicialización) · 3.2 CAPABILITY (registros 0x57/0x58, u16 LE, solo lectura) (api-reference) · 8 · Ejemplos de traza de bus (api-reference)
Lee el mapa de funciones de 16 bits del módulo. Ramifique según las constantes de capacidad con nombre de RbAmpRegistersV2.h (espacio de nombres rbamp::v2), nunca según heurísticas de versión de firmware. Entre otras cosas, el mapa indica si el módulo tiene etapa de entrada de tensión (si no la tiene, no calcula P / PF / energía y esos valores se leen como 0) y si admite la instantánea por difusión General-Call (véase broadcastLatch()). En una instancia STD la llamada devuelve false con RB_ERR_NOT_IMPLEMENTED; use stdInfo() en ese caso.
uint8_t readProductId() noexcept
3.5 PRODUCT_ID (0x54, u8, solo lectura) (api-reference) · 4.8 Identidad (0x54..0x6F) (api-reference)
Lee PRODUCT_ID (0x54): el identificador de byte de la familia (sensor rbAmp = 0x01, rbDimmer = 0x02; 0 si falla). Lo usa el escáner de flota para confirmar que el dispositivo en una dirección es realmente un rbAmp y no otro esclavo I²C que casualmente respondió en esa misma dirección. Una instancia STD informa la familia del sensor.
bool readUid(uint8_t uid[12]) noexcept
Lee el identificador único de 96 bits del MCU desde UID (0x5C..0x67) en una sola operación en ráfaga. El UID es único para cada módulo y no cambia al volver a grabar: es práctico para los registros serie, las comprobaciones anticlonación en el lado del maestro y la identificación al sustituir un módulo en una flota desplegada. Funciona en ambas líneas.
bool readLabel(char out[9]) noexcept — solo BASIC
Lee la etiqueta de usuario de 8 bytes desde LABEL (0x68..0x6F). ASCII, con relleno de ceros; el resultado siempre termina en nulo (un array de 9 bytes = 8 bytes de datos + el \0 final). Una etiqueta vacía = sin asignar.
bool writeLabel(const char* label) noexcept: solo BASIC
Escribe la etiqueta de 8 bytes. Acepta una cadena terminada en nulo: los bytes sobrantes se truncan y los que faltan se rellenan con ceros. La escritura es byte a byte en escrituras de varios bytes (el protocolo de cable de rbAmp autoincrementa en las lecturas de registros en modo ráfaga, pero no en las escrituras; véase Detalles del protocolo de bus más abajo; la biblioteca hace el bucle de bytes automáticamente). Tras la escritura necesita dev.saveUserConfig() para que la etiqueta sobreviva a un reinicio.
Un módulo recién salido de fábrica puede informar el error 0xFB (DEV_ERR_FLASH_PARAMS_BAD) en su primer arranque: el bloque de configuración de usuario todavía está vacío. Es normal (no es fatal); saveUserConfig() lo borra. No aborte el aprovisionamiento por ver un 0xFB la primera vez.
bool saveUserConfig() noexcept
6.5 Aprovisionamiento: firmware nuevo + GUARDADO (api-reference) · 8.6 Aprovisionamiento con firmware nuevo (api-reference)
Emite CMD_SAVE_USER_CONFIG (opcode 0x32): guarda el bloque de configuración de usuario en flash: SENSOR_CLASS, CT_MODEL por canal, I2C_ADDRESS, FLEET_CONFIG, GROUP_ID, LABEL. No guarda los parámetros de calibración de fábrica: estos están en un CMD_SAVE_GAINS aparte, bloqueado en modo producción.
Bloquea el hilo durante ~700 ms (ciclo de borrado y escritura de la flash). Mientras dure la llamada, no intente acceder al módulo desde otras tareas.
Línea STD: emite el guardado de configuración del módulo (clase, referencia de CT, nivel, dirección I²C; la calibración se conserva), espera a que el módulo informe de que el comando ha terminado (sin pausa fija) y comprueba su veredicto: un campo no válido (por ejemplo, una dirección fuera de rango) devuelve RB_ERR_PARAM. Un guardado dentro del límite de frecuencia de almacenamiento de 5 s del módulo se reintenta una vez tras 5 s.
: confirmar que un valor se escribió en flash exige un reinicio + una nueva lectura. Véase la sección «modelo de errores v1.3» más abajo.
Modelo de errores v1.3: dos canales independientes
Los errores tienen dos canales independientes que funcionan de formas distintas. Entender la diferencia es fundamental para interpretar correctamente el estado del módulo.
| Canal A: lado cliente, síncrono | Canal B — lado del DUT, asíncrono y duradero | |
|---|---|---|
| Dónde reside | Validación dentro de la biblioteca (biblioteca Arduino) | REG_ERROR (0x02) + EVENT_FLAGS.bit3 (0x2A) |
| Cuándo se dispara | Antes de la transacción I²C (la biblioteca la detiene) | Tras aceptar el firmware la escritura y rechazarla |
| Lo que ve el maestro | el setter devuelve false + lastError() == RB_ERR_PARAM; REG_ERROR en el dispositivo se mantiene en 0x00 |
REG_ERROR = el código de fallo de inmediato; bit3 se activa unos cientos de milisegundos después de la transacción |
| Persistente | no (solo un valor bool de retorno) | Última escritura de REG_ERROR; bit3 pegajoso W1C |
| Ruta típica | Un argumento fuera de los límites permitidos (canal ∉ {0,1,2}, código ∉ el conjunto caracterizado, sensor_class fuera de la enumeración) | Una escritura de registro en bruto que la biblioteca no valida previamente (uso de bajo nivel de writeReg() con una máscara no válida) |
Canal A: validación en el cliente (setters de la biblioteca)
Todos los setters de la biblioteca (setSensorClass, setCTModel, setCTModel(ch, code), configureChannels, etc.) comprueban primero los argumentos frente a los valores permitidos. Si un argumento queda fuera de rango, el setter devuelve false y establece lastError() == RB_ERR_PARAM, sin realizar ninguna transacción I²C. En consecuencia, REG_ERROR del dispositivo no se toca:
if (!dev.setCTModel(/*ch=*/99, /*code=*/3)) { // client-side guard
Serial.print(F("rejected: "));
Serial.println(dev.lastError()); // RB_ERR_PARAM (lib cached)
uint8_t reg_err = dev.readLastError(); // device REG_ERROR byte
Serial.println(reg_err, HEX); // 0x00 — REG_ERROR untouched
}
lastError() frente a readLastError(): dos canales distintos, no sinónimos. lastError() devuelve el código RB_ERR_* en caché del lado de la biblioteca de la llamada anterior, sin ninguna operación I²C. readLastError() hace una única lectura por cable del registro REG_ERROR (0x02) del dispositivo: el resultado de la última escritura desde el lado del firmware. En el canal A (arriba), lastError() = RB_ERR_PARAM mientras readLastError() = 0x00 (la biblioteca nunca llegó al cable: REG_ERROR no se tocó). En el canal B (abajo) ambos mostrarán un código, pero de forma distinta: lastError(), la semántica en caché de la última llamada de la biblioteca; readLastError(), el valor exacto del byte REG_ERROR en este momento.
Esto significa que, si quiere saber exactamente por qué un setter rechazó la operación, la fuente fiable es el código de retorno de la función + lastError(). En este escenario, REG_ERROR del dispositivo no le dirá nada.
Canal B: rechazo en el lado del DUT (asíncrono duradero)
Si la escritura se realizó por I²C (la biblioteca no la detuvo porque el argumento parecía válido), pero el firmware la rechazó, entra en acción el segundo canal:
-
readLastError()devuelve de inmediato el código de causa (por ejemplo,0xFE = DEV_ERR_PARAM). Es el resultado de la última escritura: cualquier escritura correcta siguiente lo sobrescribe. Debe leerlo de inmediato tras su escritura, antes de cualquier otra transacción. -
hasError(out): el indicador W1C persistenteEVENT_FLAGS.bit3. No se activa al instante: en el banco se midió un retardo de unos cientos de milisegundos entre la transacción fallida y la activación de bit3. Justo tras la escritura bit3 sigue enfalse; tras 300 ms pasa atrue. Después,bit3se mantiene en cualquier número de lecturas.
⚠ No use hasError() para validar una escritura que acaba de hacer. Para el resultado de esta escritura concreta solo es fiable readLastError(), leído inmediatamente después de la escritura y antes de cualquier otra transacción (además del código de retorno del método establecedor, si lo tiene). hasError() es un canal asíncrono para la monitorización por sondeo de «si algo falló entre dos comprobaciones», no para la validación síncrona.
Borrado de un error duradero: borre ambos (REG_ERROR y bit3)
bit3 lo recoge el firmware cada pocos cientos de milisegundos a partir del estado actual de REG_ERROR. Por tanto, un simple clearEventFlags(1 << 3) no funcionará: bit3 se volverá a activar de inmediato desde el REG_ERROR aún no borrado. El orden correcto: primero clearError() (borra REG_ERROR), después clearEventFlags(1 << 3) (borra el latch pegajoso). Si necesita atomicidad, no debe haber ninguna escritura rechazada entre ambos.
uint8_t readLastError() noexcept
3. DATA_VALID (0xCE) nunca pasa a 1 (troubleshooting) · Códigos de error (REG_ERROR = 0x02) (troubleshooting) · 4 · Mapa de registros (producción v1.3) (api-reference)
Lee directamente el registro REG_ERROR (0x02) del dispositivo (una sola lectura por cable; devuelve 0x00 si está bien, 0xFA..0xFF para una clase de error, y 0xFF si falló la propia lectura I²C): el resultado de la última transacción aceptada correctamente por el bus (una escritura o un comando). No es persistente: cualquier escritura correcta siguiente lo sobrescribe con su propio resultado. Se usa en el Canal B (rechazo en el lado del DUT) para el código de motivo extendido. En la línea STD, el veredicto del comando ya se traduce a lastError() (véase la API de la línea STD).
No confundir con lastError(): se trata de un método distinto, que devuelve el RB_ERR_* en caché de la biblioteca de la llamada anterior sin ninguna operación I²C. Véase el aviso en el Canal A de arriba.
bool hasError(bool& out) noexcept
Un auxiliar práctico sobre EVENT_FLAGS.bit3. Devuelve true en out si bit3 está activo. Pegajoso (W1C); no se borra hasta un borrado explícito (con una advertencia: véase la sección «Borrado de un error duradero» de arriba).
bool readEventFlags(uint8_t& out) noexcept / bool clearEventFlags(uint8_t mask) noexcept
8.8 Flujo de eventos de umbral: escribir umbral → disparo → borrado W1C (api-reference)
EVENT_FLAGS (0x2A): un byte de indicadores persistentes; los bits concretos se describen en la especificación (incluido ERROR_OCCURRED bit3). El borrado es escribir-1-para-borrar: escriba una máscara con unos en los bits que quiera restablecer.
bool clearError() noexcept
Códigos de error (REG_ERROR = 0x02) (troubleshooting) · 6.7 Recuperación del estado de error: árbol de decisión (api-reference)
Emite CMD_CLEAR_ERROR (opcode 0x31): pone a cero REG_ERROR. Necesario para borrar un error duradero, junto con clearEventFlags(1 << 3) (véase arriba). Sin clearError(), un simple clearEventFlags(1 << 3) dejará bit3 en true tras unos cientos de milisegundos por el rearmado.
Configuración multicanal (v1.3)
En módulos multicanal, cada canal de corriente tiene su propio modelo de sensor de CT. La utilidad atómica para la configuración en bloque es configureChannels().
bool configureChannels(RbAmpSensorClass cls, const uint8_t* models, uint8_t n) noexcept
Parameters:
-
cls: la clase de sensor, aplicada primero. ConRbAmpSensorClass::Sct013se vinculan los modelos; una petición de vincular modelos bajoWiredCT/BuiltinCTse rechaza de entrada (false,RB_ERR_MODE, sin escribir nada). -
models: un array dencódigos de modelo de CT (definesRBAMP_CT_*generados), uno por canal.0deja intacto el modelo existente de ese canal. -
n: la longitud del array. Se limita achannels(): los elementos extra del array se ignoran. Sines menor, los canales que faltan no se tocan (conservan su modelo anterior).
Internamente, la función realiza:
setSensorClass(cls)una sola vez.- Para cada canal
k < min(n, channels): prepararREG_CT_MODEL = models[k]+CMD_SET_CT_MODEL_CHk. - Un único guardado al final: un solo ciclo de borrado y escritura en flash para toda la configuración en lugar de uno por canal (unos 3× menos ciclos de desgaste con tres canales).
Se aplica la regla de leer antes de escribir: una clase o un modelo que el módulo ya tiene no se reescribe, así que volver a aplicar la misma configuración solo cuesta lecturas y ningún ciclo de flash. En firmware BASIC hasta la 1.4.19 con la clase SCT-013, el módulo se reinicia tras el guardado (véase Configuración del sensor).
Return:
true: la configuración se aplicó y se guardó (o ya estaba vigente).-
false+lastError() == RB_ERR_PARAM: unclsno válido o unmodels[k]que no está en el registro (validación en el cliente, véase «Modelo de errores» arriba); el lote se aborta. -
false+RB_ERR_MODE: el módulo es de una clase con emparejamiento de fábrica. false+ otros códigos: error de bus, timeout, etc.
Códigos aceptados para SCT_013: {1, 2, 3, 4, 5, 6, 7} (SCT-013-005, -010, -030, -050, -100, -020, -060). Detalles: 03 · Selección de sensor de corriente.
bool readCTModelCh(uint8_t ch, uint8_t& out) noexcept
Lee el modelo de sensor de CT aplicado (espejo de verificación) en un canal concreto. Es una relectura desde la RAM, no una confirmación de persistencia: para confirmar un guardado en flash use dev.reset() + una relectura del espejo.
Línea de datos listos y eventos
Ambas líneas. La salida DRDY del módulo es de drenador abierto, en reposo ALTA (pull-up del host), y pulsa a BAJO cada vez que se publica una instantánea completa nueva, una vez por ventana de medida (100 ms). Varios módulos pueden compartir una línea (OR cableada). Un módulo cuyo evento enmascarado está pendiente mantiene la línea fija en BAJO (nivel de alarma) hasta que se borran los flags. En la línea STD el bloque de eventos existe en los módulos cuya imagen lo proporciona; en BASIC, desde el firmware v1.3. Detalles de hardware: 04 · Cableado.
bool setDrdyPin(int pin) noexcept
01 · Conexión de hardware (hardware-connection) · 03 · Sondeo en tiempo real (realtime-polling)
Conecte la línea DRDY de este módulo (o desconéctela con pin < 0). Configura el pin como entrada con la pull-up interna y una interrupción por flanco de bajada; la ISR solo cuenta y marca el tiempo del flanco, sin tráfico de bus. Hasta 4 líneas distintas y 8 módulos por línea. Un módulo STD cuya imagen no admite el contrato de datos listos se niega con RB_ERR_NOT_IMPLEMENTED; waitDataReady() entonces sondea la secuencia. Sin línea, waitDataReady() también sondea.
bool waitDataReady(uint32_t timeout_ms, RbAmpDrdyEvent* ev = nullptr) noexcept
01 · Conexión de hardware (hardware-connection) · 03 · Sondeo en tiempo real (realtime-polling)
Bloquea hasta que este módulo publique una nueva instantánea (o una alarma), como máximo timeout_ms (0 = una comprobación no bloqueante).
Con línea: espera el flanco y después confirma que es de este módulo por su número de secuencia de instantánea (un pulso de otro módulo en una línea compartida se ignora). Si la línea sigue en BAJO poco después del flanco, algún módulo de la línea tiene una alarma activa: se leen y limpian los indicadores de cada módulo con capacidad de alarma de la línea; los del módulo actual se devuelven en ev, y los de los demás se guardan en sus instancias y se notifican en su siguiente espera. Sin línea, sondea la secuencia cada RBAMP_DRDY_POLL_MS (por defecto 20 ms; defínalo antes de incluir la biblioteca para cambiarlo).
Devuelve: true con ev rellenado; false con RB_ERR_TIMEOUT si no llegó nada, RB_ERR_NOT_IMPLEMENTED en un módulo STD cuya imagen no tiene contador de publicación.
bool readAllReady(uint32_t timeout_ms, RbAmpSnapshot& out, RbAmpDrdyEvent* ev = nullptr) noexcept
waitDataReady() seguido de readAll(), de modo que toda la lectura cae dentro de una única ventana de publicación: la instantánea nunca se lee dos veces ni cruza una publicación.
bool readDataSeq(uint16_t& out) noexcept
La secuencia de instantáneas del módulo: el contador de publicación en STD, el byte de secuencia de confirmación en BASIC. Solo sirve para detectar cambios.
uint8_t beginEventFlags() const noexcept
Los flags de evento tal como los encontró begin(), antes de que la biblioteca escribiera nada. EVENT_RESET_OCCURRED ahí indica que el módulo se reinició antes de que esta instancia lo encontrara. Sin acceso al bus.
bool readEventMask(uint8_t& out) noexcept / bool setEventMask(uint8_t mask) noexcept
Lee / establece qué bits de evento mantienen DRDY en BAJO (bits rbamp::v2::EVENT_*). setEventMask() verifica releyendo. La máscara reside en la RAM del módulo: vuelva a aplicarla tras un reinicio del módulo (EVENT_RESET_OCCURRED lo indica).
bool setEventThresholds(float i_amps, float p_watts) noexcept
4.4 Configuración de flota (0x27..0x2F) (api-reference) · 8.8 Flujo de eventos de umbral: escribir umbral → disparo → borrado W1C (api-reference)
Establezca los umbrales de corriente / potencia que gobiernan EVENT_THRESH_I / EVENT_THRESH_P; un valor <= 0 desactiva ese umbral. Reside en la RAM del módulo.
-
BASIC compara la corriente máxima de canal y la suma con signo de las potencias de los canales: la exportación nunca lo dispara.
-
STD compara la corriente de cualquier canal y la magnitud de la potencia total: independiente de la dirección.
Los eventos de umbral quedan enclavados a nivel en el módulo (se vuelven a fijar en cada ventana mientras la condición se mantenga): levante el umbral antes de esperar una línea en calma.
readEventFlags() / clearEventFlags() / hasError() se describen en Modelo de errores.
RbAmpDrdyEvent
struct RbAmpDrdyEvent {
bool fresh; // a new snapshot of THIS module is available
bool by_edge; // woken by the DRDY edge (false = found by polling)
uint16_t seq; // snapshot sequence now
uint16_t missed; // snapshots published since the previous call that were not read
bool alarm; // the line was held LOW (masked event pending on this module)
uint8_t event_flags; // event flags consumed from this module on an alarm, else 0
uint32_t latency_us; // edge to return, µs (0 when polling)
};
RbAmp dev(Wire, 0x50);
...
dev.setDrdyPin(15); // optional: omit to poll
dev.setEventThresholds(0, 3000); // power threshold, W
dev.setEventMask(rbamp::v2::EVENT_THRESH_P);
RbAmpSnapshot snap;
RbAmpDrdyEvent ev;
if (dev.readAllReady(500, snap, &ev)) {
if (ev.alarm) { /* ev.event_flags holds the cleared flags */ }
// use snap
}
Resumen de funciones
Los resúmenes de funciones que aparecen más abajo se trasladaron aquí desde el README.
- Configuración de la pinza de corriente:
setSensorClass(class)elige la familia (SCT-013 que usted instala; las pinzas integradas o cableadas se suministran calibradas con su sensor y no se reconfiguran), y despuéssetCTModel(code), o bienconfigureChannels(class, models[], n)para un módulo multicanal en una sola llamada. Los setters leen antes de escribir: una clase o un modelo que el módulo ya tiene no cuesta ninguna escritura en el bus ni un ciclo de flash, así que volver a aplicar una configuración almacenada en cada arranque es seguro. El conjunto de códigos SCT-013 aceptados es{1=005A, 2=010A, 3=030A, 4=050A, 5=100A, 6=020A, 7=060A}. Los coeficientes de calibración se cargan automáticamente desde la tabla de valores de fábrica. Los módulos BASIC hasta el firmware 1.4.19 están calibrados para el SCT-013-030: cuando selecciona otro modelo SCT-013, la biblioteca reinicia el módulo tras el guardado y, desde entonces, escala las lecturas de corriente y potencia en relación con la ganancia que aplica el módulo (véasesctRating()); el factor de potencia y la tensión no se ven afectados, y un módulo que informa el bit de capacidad de autocorrección (firmware 1.4.20+) no necesita nada. - Gestor
RbAmpFleet: para varios módulos en un bus:scan()los descubre y los adopta (con detección de colisiones),pollAll()los lee en una sola pasada,totalPower()/totalEnergyWh()agregan, y la ruta General-Call (enableGcAll()→gcLatch(tick)→checkSync()) toma la instantánea de período de todos los módulos a la vez con detección de tramas perdidas por módulo.provision()/assignAddress()incorporan al bus, en direcciones distintas, los módulos recién salidos de fábrica. - Ambas líneas de producto, una sola API:
begin()detecta si un módulo habla el modelo de registros BASIC (8 bits) o STD (16 bits, punto fijo) y enruta internamente cada llamada;line()le indica cuál es. En un módulo STD funcionan las mismas llamadasreadVoltage(phase)/readCurrent(ch)/readPower(ch)/readPeriodSnapshot(); el número de canales lo proporciona el módulo (los módulos trifásicos son simplemente N > 1), y los extras exclusivos de STD se exponen comoreadReactivePower(ch)/readApparentPower(ch),stdReadChannel(ch)(una ráfaga: I / P / Q / S / FP / pico / energía con signo / armónicos),stdReadVoltage(v),stdReadHealth()y ocho bancos de instantáneas temporizados por el maestro (stdArmBanks()→stdLatch(bank)→stdReadLatch(bank)→stdLatchWh()). Los módulos que conservan contadores de energía de vida persistidos en lugar de bancos de instantáneas se atienden con las mismas llamadasreadPeriodSnapshot()/energy()(un periodo es la diferencia de dos lecturas de contador;stdReadEnergy()devuelve los contadores en bruto), además del reloj del módulo (stdSetTime()), el historial y el registro de eventos (stdHistRead(),stdEventRead()), la identidad (stdIdentify(),RbAmp::stdProbe()), la puesta en servicio por UID (RbAmp::stdSetAddressByUid()) y la actualización de firmware por I2C (stdOtaWritePreparedImage(), imágenes preparadas en el equipo de compilación del fabricante). Cada comando espera a que el módulo informe de que ha terminado antes de leer el veredicto, y los bloques de varios bytes se leen en una sola transacción para que los contadores nunca se partan. Los módulos que publican contadores de microresolución rellenan los campos*_uwh/*_uvarhdeRbAmpStdEnergy(fine == true; en otros casos se derivan de los contadores gruesos, de modo que los campos siempre son utilizables), aceptan una corriente de arranque por debajo de la cual un canal no cuenta energía (stdSetEnergyStartCurrent()), y devuelven los ángulos de fase de tensión (angle_degenstdReadVoltage()) y la secuencia de fases (stdReadPhaseSequence()). Si su sketch persisteRbAmpStdEnergy(NVS, EEPROM, archivo), guarde los campos individuales que necesita en su propio formato fijo, no la estructura como blob en bruto: la estructura gana campos entre versiones de la biblioteca y un blob antiguo no coincidirá con el nuevo tamaño. - Línea de datos listos y eventos:
setDrdyPin(pin)escucha la salida DRDY del módulo;waitDataReady()/readAllReady()retornan justo cuando el módulo publica una instantánea nueva (varios módulos pueden compartir una línea), y un módulo que mantiene la línea señala un evento enmascarado (setEventMask(),setEventThresholds()) que la espera lee y limpia por usted. Sin línea, las mismas llamadas sondean.
API de la línea STD
La línea STANDARD (STD) la detecta begin() (dev.line() == RbAmpLine::Std). La API escalar de arriba (readVoltage(), readCurrent(), readPower(), readReactivePower(), readApparentPower(), readAll(), readPeriodSnapshot(), energy(), los setters de configuración, reset(), el cambio de dirección) funciona en ambas líneas. Las llamadas std* de abajo añaden lecturas de bloques completos y las funciones que solo tiene la línea STD.
- Cada llamada
std*falla conRB_ERR_NOT_IMPLEMENTEDen una instancia BASIC. -
La disponibilidad de funciones depende de la imagen del módulo: compruebe
stdReadImageVersion()y los flagsvalid/finede las estructuras devueltas. Una función que el módulo no tiene se notifica como «no disponible»; nunca devuelve un valor inventado. -
begin()hace la detección de línea y el descubrimiento de canales. Los ayudantes internos correspondientes no forman parte de la API pública; llame abegin(),readAll()yreadPeriodSnapshot(). -
Cada comando espera a que el módulo informe que ha terminado y después comprueba su veredicto. Un valor rechazado devuelve
RB_ERR_PARAMy deja el módulo sin cambios. -
Las primitivas de 8 bits se niegan en una instancia STD, de modo que una ruta exclusiva de BASIC nunca puede ejecutar una transacción sobre el registro equivocado en un módulo STD.
if (dev.begin() && dev.line() == RbAmpLine::Std) {
RbAmpStdChannel c;
if (dev.stdReadChannel(0, c)) {
Serial.printf("P=%.1f W Q=%.1f var S=%.1f VA PF=%.2f\n", c.p, c.q, c.s, c.pf);
}
}
Fuente de energía y versión mínima de la biblioteca
readPeriodSnapshot() y energy() toman su período de una de dos fuentes, elegida una vez por begin() a partir de los bits de capacidad del módulo e informada en stdInfo().period_source:
| El módulo informa | period_source |
El período y la energía provienen de |
|---|---|---|
| contadores de energía persistentes (bit 13), con o sin bancos | Counters |
los contadores del módulo (un periodo es la diferencia de dos lecturas) |
| solo bancos de instantáneas (bit 8) | Latch |
banco 0 |
| ninguno | None |
las llamadas se rechazan con RB_ERR_NOT_IMPLEMENTED |
La imagen STD en serie 0x7E informa de ambos bits. Necesita la biblioteca 1.6.2 o posterior para tomar su energía de los contadores del módulo. La biblioteca 1.6.1 y anteriores leen el periodo del banco 0 en esa imagen, es decir, la energía integrada en el host en lugar de los contadores propios del módulo; actualice la biblioteca para obtener los valores basados en contadores. Los bancos siguen disponibles en 0x7E mediante las llamadas de Bancos de instantáneas de periodo.
Identidad
bool stdInfo(RbAmpStdInfo& out) noexcept
Identidad en caché de begin(): sin tráfico de bus. Falla con RB_ERR_NOT_IMPLEMENTED en una instancia BASIC o antes de begin().
struct RbAmpStdInfo {
uint8_t map_version; // register-map version
uint16_t capabilities; // feature bitmap of the module
uint8_t status; // status bits at begin() time (live: stdReadHealth())
uint8_t n_voltage; // populated voltage channels
uint8_t n_current; // populated current channels (the library exposes up to RBAMP_MAX_CHANNELS)
uint8_t variant; // raw variant byte (also mapped into readVariant())
uint32_t active_bank; // running firmware bank (firmware update), 0 if none
uint32_t ota_bank_size; // firmware bank size the module reports, 0 if none
RbAmpStdPeriodSource period_source; // which period / energy mechanism this module offers
};
RbAmpStdPeriodSource: Latch (el módulo tiene bancos de instantáneas; el banco 0 sirve a readPeriodSnapshot()), Counters (sin bancos de instantáneas, pero con contadores de energía de vida persistidos: un periodo es la diferencia de dos lecturas de contador; las llamadas a bancos se rechazan sin tráfico de bus) o None (las llamadas de periodo / energía fallan con RB_ERR_NOT_IMPLEMENTED).
bool stdIdentify(RbAmpStdIdentity& out) noexcept
Identidad de este módulo: los datos de begin() en caché más el UID, la versión de imagen en ejecución y el id de placa (los dos últimos cuando el módulo los informa; en caso contrario, 0).
struct RbAmpStdIdentity {
uint8_t i2c_addr; // 7-bit address the module answered on
uint8_t map_version;
uint16_t capabilities;
uint8_t variant;
uint8_t n_voltage, n_current;
uint8_t uid[12]; // chip UID — the module's identity in a database
uint32_t fw_version; // running image version (0 if unknown)
uint32_t board_id; // board id (0 if unknown)
};
static int8_t stdProbe(TwoWire& bus, uint8_t addr, RbAmpStdIdentity& out) noexcept
Identifica lo que responde en addr sin una instancia (escaneo del bus). Un intento por lectura, sin capa de reintentos: un NACK es la respuesta.
Devuelve: RB_OK; RB_ERR_NACK si nadie responde en esa dirección; RB_ERR_VERSION si lo que hay no es un módulo STD; RB_ERR_PARAM si la dirección está fuera de 0x08..0x77; RB_ERR_IO si falla una lectura posterior.
bool stdReadImageVersion(uint32_t& out) noexcept
La versión de imagen en ejecución (no la versión del mapa de registros); 0 si el módulo no informa ninguna. Úsela para ver si está presente una función que requiere una imagen reciente (energía de microresolución, corriente de arranque, ángulos de tensión y secuencia de fases necesitan una imagen de al menos 0x0001007B).
bool stdReadBoardId(uint32_t& out) noexcept
Id. de placa de la imagen en ejecución.
Lecturas por bloques
bool stdReadChannel(uint8_t ch, RbAmpStdChannel& out) noexcept
Un canal de corriente (0 .. channels()-1) en una sola ráfaga: I, P, Q, S, PF, pico, acumuladores de energía firmados en bruto y campos de armónicos.
bool stdReadTotals(uint8_t k, RbAmpStdChannel& out) noexcept
Un bloque agregado: k = 0 total general (todos los canales de corriente), k = 1..3 totales por fase A / B / C (en un módulo monofásico, k = 1 equivale al canal 0 y k = 2, 3 leen 0). Solo I / P / Q / S / PF / pico: en módulos con contadores de vida útil, los campos de energía leen 0 aquí; la energía proviene de stdReadEnergy().
struct RbAmpStdChannel {
float i_rms, i_peak; // A
float p; // W, signed
float q; // var, signed
float s; // VA
float pf; // power factor, −1..+1
float thd_i; // current THD, % — 0 unless harmonics are enabled
float pf1; // displacement power factor — 0 unless harmonics are enabled
float q1; // fundamental reactive power, var — 0 unless harmonics are enabled
int64_t e_import_mws; // raw import energy accumulator (>= 0), see stdLatchWh()
int64_t e_export_mws; // raw export energy accumulator (<= 0)
uint8_t implausible; // RBAMP_FIELD_* bits of fields set to NaN by the sanity filter
};
Para la monitorización, integre p usted mismo o use stdReadEnergy(); los acumuladores en bruto existen para la vía de bancos de instantáneas.
bool stdReadVoltage(uint8_t v, RbAmpStdVoltage& out) noexcept
Un canal de tensión (0 .. n_voltage-1).
struct RbAmpStdVoltage {
float u_rms, u_peak; // V
float thd_u; // voltage THD, % — 0 unless harmonics are enabled
float angle_deg; // phase angle vs voltage 0, degrees; 0 when angle_valid is false
bool angle_valid; // false on older images, when the input is too low to measure, and on single-voltage modules for v > 0
uint8_t implausible;
};
bool stdReadPhaseSequence(RbAmpStdPhaseSeq& out) noexcept
Secuencia de fases de un módulo de tres tensiones, derivada por el módulo a partir de los ángulos de tensión. Devuelve true con NotAvailable (y sin tráfico en el bus) en una imagen que no la publica; el propio módulo informa NotAvailable con menos de tres entradas de tensión o cuando una entrada es demasiado baja para medirla.
RbAmpStdPhaseSeq: NotAvailable, Forward (L1-L2-L3), Reverse (L1-L3-L2), Abnormal (sin patrón trifásico, p. ej. dos entradas en una misma fase).
bool stdReadHealth(RbAmpStdHealth& out) noexcept
Estado de salud del módulo en vivo. Considere válidas las lecturas cuando status tenga el bit de sensor OK y frame_count aumente entre dos consultas.
struct RbAmpStdHealth {
uint8_t status; // status bits: cal_ok / sensor_ok / mains_ok / time_valid / nvm_fault / maint
uint32_t frame_count; // sensor frame counter — must grow between polls (liveness)
uint32_t crc_errors; // sensor frame error counter
bool time_valid; // the module clock was set since its last restart — see stdSetTime()
bool nvm_fault; // energy store unusable
bool maint; // maintenance mode
uint8_t lta_status; // life-time energy store: 0 ok · 1 new · 2 fault · 3 corrupt (service)
uint8_t lta_src; // where the life-time counters were restored from
uint8_t cal_src; // 0 built-in defaults · 1 flash · 2 EEPROM · 3 stored calibration is for another firmware
uint8_t group_status; // per-channel energy store: 0 ok · 1 new · 2 fault · 3 restarted at 0
uint16_t legal_noen, ring_drop; // module diagnostics (ring_drop should stay 0)
uint32_t lost_frames; // should stay flat
uint32_t uptime_s; // seconds since the module's last restart
uint8_t reset_cause; // cause of this boot (image-dependent; 0 below)
uint16_t boot_count; // persisted boot counter, low 16 bits — a master that missed a restart sees it step
};
Los campos marcados como «dependientes de la imagen» o documentados para mapas de registros más recientes se leen como 0 / false en módulos que no los proporcionan. cal_ok puede leer 0 en una unidad calibrada con una imagen anterior hasta que saveGains() se haya ejecutado una vez; las lecturas en sí no se ven afectadas.
Bancos de instantáneas de período
Un módulo STD que informa bancos de instantáneas (bit de capacidad 8) mantiene ocho períodos independientes con temporización del maestro. Uso típico: arme una vez los bancos que necesite; después, por banco y según su propio horario: stdLatch(bank) → espere al menos 300 ms → stdReadLatch(bank, snap) → stdLatchWh(snap, dt, ...) con el dt medido por el maestro desde la instantánea anterior de ese banco. Los bancos son una herramienta propia: están disponibles con independencia de la fuente de energía del módulo (véase Fuente de energía y versión mínima de la biblioteca). En un módulo sin bancos, stdArmBanks(), stdLatch() y stdReadLatch() se niegan con RB_ERR_NOT_IMPLEMENTED y no escriben nada. El banco 0 sirve a readPeriodSnapshot() y energy() solo en un módulo que tiene bancos y no tiene contadores persistentes.
bool stdArmBanks(uint8_t mask) noexcept
Establezca la máscara de acumulación: el bit b = el banco b acumula (los bancos recién armados empiezan limpios; los bancos desarmados se congelan y conservan su última instantánea). Mantenga el bit 0 activo si usa readPeriodSnapshot(). La máscara reside en la RAM del módulo y se pierde en un reinicio; la biblioteca rearma un banco cuando una lectura encuentra una instantánea vacía en un banco desarmado (véase stdReadLatch()).
bool stdLatch(uint8_t bank) noexcept
Solicite una instantánea y un reinicio de bank en el próximo límite de ventana del módulo. No espera; léalo al menos 300 ms después.
bool stdReadLatch(uint8_t bank, RbAmpStdLatch& out) noexcept
Lee la última instantánea de bank en una sola ráfaga (totales y energía por canal de todos los canales con datos).
Devuelve: false con RB_ERR_STALE si el módulo nunca ha tomado una instantánea de este banco (out.valid == false), o si la instantánea está vacía (win_count == 0) porque el banco perdió su armado tras un reinicio del módulo. En este último caso la biblioteca rearma el banco y toma una instantánea de cebado: descarte este período y reinicie su propio ancla de dt (el intervalo de corte no aporta datos).
struct RbAmpStdLatch {
float p_avg, q_avg, s_avg; // average W / var / VA over the period
float max_p, max_i; // peak power (W) and peak RMS current (A)
float max_u, min_u; // peak / minimum RMS voltage (V)
int64_t e_import_mws, e_export_mws; // raw energy accumulators over the period
uint32_t nsamp; // conversion divisor used by stdLatchWh()
uint32_t win_count; // measurement windows in the period (0 = not armed / nothing elapsed)
uint8_t channels, bank;
bool valid; // the bank has EVER been snapshotted (not a freshness signal)
float p_avg_ch[RBAMP_MAX_CHANNELS];
int64_t e_import_ch_mws[RBAMP_MAX_CHANNELS], e_export_ch_mws[RBAMP_MAX_CHANNELS];
};
static bool stdLatchWh(const RbAmpStdLatch& snap, uint32_t dt_ms, uint8_t ch, double& wh_import, double& wh_export) noexcept
Convierte los acumuladores de energía en bruto de una instantánea a Wh sobre el periodo medido por el maestro dt_ms (reloj de pared entre la instantánea anterior y esta del banco). ch es un índice de canal, o RBAMP_STD_TOTAL para los totales del banco. wh_import es >= 0, wh_export es <= 0.
Devuelve: false si ch está fuera de rango o no se acumuló nada.
Contadores de energía de vida
Los módulos que conservan contadores de energía persistentes los mantienen tras un corte de alimentación; son monótonos, con una división de importación / exportación con signo.
bool stdReadEnergy(RbAmpStdEnergy& out) noexcept
Lea los contadores de energía de vida del módulo. Cada bloque se lee en una sola transacción, así que un contador de 64 bits no puede partirse entre dos publicaciones.
Devuelve: false con RB_ERR_NOT_IMPLEMENTED cuando el módulo no conserva energía en el dispositivo; RB_ERR_NOT_READY si el bloque no está programado.
struct RbAmpStdEnergy {
int64_t act_import_wh, act_export_wh, act_net_wh; // active energy, Wh (export is a magnitude)
int64_t rea_import_varh, rea_export_varh; // reactive energy, varh
uint32_t generation; // steps when the counters were reset or adopted — never take a delta across a change
uint32_t uptime_s; // module uptime at the reading (a drop = the module restarted)
int64_t act_import_mwh, act_export_mwh, act_net_mwh; // mWh (0 on modules without them)
uint8_t channels; // valid entries in the per-channel arrays (0 on modules without them)
uint8_t group_status; // per-channel store: 0 ok · 1 new · 2 fault · 3 restarted at 0
int64_t ch_import_mwh[RBAMP_MAX_CHANNELS], ch_export_mwh[RBAMP_MAX_CHANNELS];
bool fine; // true: the µWh / µvarh fields are the module's own micro-resolution counters
int64_t act_import_uwh, act_export_uwh, act_net_uwh; // µWh
int64_t rea_import_uvarh, rea_export_uvarh; // µvarh
int64_t ch_import_uwh[RBAMP_MAX_CHANNELS], ch_export_uwh[RBAMP_MAX_CHANNELS];
};
Los campos *_uwh / *_uvarh siempre están rellenos, de modo que puede usarlos en cualquier módulo: cuando fine == true son los contadores propios de microresolución del módulo (imagen 0x0001007B o posterior); en otro caso se derivan de los contadores más gruesos y avanzan en esas unidades. Si su sketch persiste RbAmpStdEnergy, guarde los campos individuales que necesita en su propio formato fijo, no la estructura como blob en bruto: la estructura gana campos entre versiones de la biblioteca.
static bool stdEnergyDelta(const RbAmpStdEnergy& prev, const RbAmpStdEnergy& now, RbAmpStdEnergy* delta, bool* module_restarted) noexcept
Energía entre dos lecturas: now − prev, limitando cada contador a 0 (un contador puede reanudarse ligeramente por debajo de la última lectura tras un reinicio del módulo); el neto se recalcula como importación − exportación de los deltas limitados. delta y module_restarted pueden ser nullptr; delta->fine es true solo cuando ambas lecturas eran correctas; *module_restarted es true cuando el tiempo de funcionamiento de now es menor que el de prev.
Devuelve: false cuando generation cambió entre las lecturas (reinicio de vida útil o adopción): no contabilice ese intervalo.
bool stdSetEnergyStartCurrent(uint16_t ua) noexcept
Establece la corriente de arranque para el cómputo de energía, en µA: por debajo de esta corriente del canal, el módulo no cuenta energía para el canal (importación o exportación, total y por canal). Sin carga, la potencia medida es ruido de cualquier signo y, de otro modo, se colaría en ambos contadores. Las lecturas (I / P / Q) no se ven afectadas. Se aplica de inmediato, con verificación por lectura; persista con saveUserConfig(). 0 lo desactiva; en otro caso el valor debe ser múltiplo de 10 µA dentro del rango que acepta el módulo; cualquier otro valor devuelve RB_ERR_PARAM sin escritura en el bus.
Devuelve: false con RB_ERR_NOT_IMPLEMENTED cuando el módulo no tiene corriente de arranque (sin energía de microresolución, o con una imagen anterior).
bool stdReadEnergyStartCurrent(uint16_t& ua) noexcept
La corriente de arranque actual para el cómputo de energía, en µA (0 = desactivada).
Configuración
bool stdReadConfig(RbAmpStdConfig& out) noexcept
El bloque de configuración en una sola ráfaga.
struct RbAmpStdConfig {
uint8_t sensor_class; // RbAmpSensorClass value, 0 = unset. Persisted.
uint8_t ct_model; // CT model reference for channel 0 (label only, sets no gain). Persisted.
uint8_t tier; // module tier code. Persisted.
uint8_t i2c_addr; // persisted 7-bit address (applies on reset)
uint16_t rate_ms; // report-rate hint, ms (RAM only)
bool harmonics; // base-harmonics extraction enabled (RAM only)
};
bool stdSetHarmonics(bool enable) noexcept
Activa / desactiva la extracción de armónicos de base (THD, factor de potencia de desplazamiento, potencia reactiva fundamental). Solo en RAM (no se persiste), con verificación por relectura. Requiere la capacidad THD del módulo; si no, RB_ERR_NOT_IMPLEMENTED.
bool stdCalThdFloor() noexcept
Capture el THD bruto sin carga como suelo del sensor y guárdelo (unos 700 ms). Ejecútelo con red limpia y sin carga; después, las lecturas de THD se corrigen con el suelo del sensor. Requiere la capacidad de THD.
Reloj
El reloj del módulo se pierde en cada reinicio del módulo. Ajústelo tras begin() y siempre que RbAmpStdHealth::time_valid sea false; sin él el módulo no registra historial.
bool stdSetTime(uint32_t unix_epoch) noexcept
Establece el reloj del módulo (época Unix, UTC). Devuelve false con RB_ERR_PARAM si el módulo rechaza la época (anterior a 2020), y RB_ERR_NOT_READY si la aceptó pero no informó el reloj como válido en 300 ms.
bool stdReadTime(uint32_t& unix_epoch, bool& valid) noexcept
El reloj del módulo y si se ajustó desde el último reinicio del módulo.
Comandos y puesta en servicio
bool stdCommand(uint8_t opcode, uint32_t settle_ms, uint32_t timeout_ms = 0) noexcept
Emite cualquier comando del módulo y espera su veredicto: espera a que el módulo esté inactivo (un comando escrito mientras está ocupado se descarta), escribe el código de operación, sondea el estado del comando hasta que el módulo informa de que ha terminado y después lee el veredicto. settle_ms solo limita el primer sondeo. timeout_ms = 0 significa 1000 ms; nunca menos de 1000.
Devuelve: false con el veredicto traducido a un código de error: PARAM, NOT_IMPLEMENTED (comando desconocido), CHECKSUM (comprobación del valor), MODE (clave / puerta), NOT_READY (límite de frecuencia / reintento), TIMEOUT, IO (error de almacenamiento del módulo).
bool stdWaitIdle(uint32_t timeout_ms = 0) noexcept
Espere hasta que el módulo informe que no hay ningún comando en curso (0 = 1000 ms).
bool stdLocate() noexcept
Haga parpadear los LEDs del módulo durante unos 10 s: para encontrarlo en un armario.
static int8_t stdSetAddressByUid(TwoWire& bus, uint8_t shared_addr, const uint8_t uid[12], uint8_t new_addr, uint32_t restart_ms = 0) noexcept
Asigne a un módulo entre varios en una dirección compartida su propia dirección, seleccionado por UID (puesta en servicio). Es solo escritura en la dirección compartida (varios módulos pueden responder, así que no se lee allí). El módulo direccionado guarda la nueva dirección y se reinicia; después la llamada sondea la nueva dirección y comprueba el UID. Vuelva a ejecutar begin() en una instancia vinculada a la nueva dirección. restart_ms = 0 significa 1500 ms.
Devuelve: RB_OK; RB_ERR_PARAM si la dirección está fuera de rango; RB_ERR_NACK si ningún módulo confirmó en la dirección compartida; RB_ERR_NOT_READY si nada responde después en la nueva dirección; RB_ERR_VERSION si el módulo que hay allí no es el direccionado (el UID no coincide).
Historial y registro de eventos
Los registros existen solo para periodos durante los cuales el reloj del módulo era válido (véase stdSetTime()).
enum class RbAmpStdHistPeriod : uint8_t {
Min15 = 0, // 15-minute energy records — RAM only (the last record survives no restart)
Hour = 1, // hourly energy records — persistent ring (the one to backfill from)
Events = 2, // event log (read with stdEventRead())
};
bool stdHistInfo(RbAmpStdHistPeriod period, RbAmpStdHistInfo& out) noexcept
Resumen del anillo: count, capacity, record_size, oldest_ts, newest_ts (hora Unix). Los registros se recuperan del más reciente al más antiguo mediante un índice back.
bool stdHistRead(RbAmpStdHistPeriod period, uint16_t back, RbAmpStdHistRecord& out) noexcept
Lee y decodifica un registro de período de energía (Min15 u Hour; back = 0 es el más reciente). Devuelve false con RB_ERR_NOT_READY cuando no existe ese registro (anillo vacío o back más allá de él); RB_ERR_PARAM para el anillo de eventos (use stdEventRead()).
struct RbAmpStdHistRecord {
uint32_t ts; // Unix time at the end of the period
uint16_t flags; // partial / power-up / clock / life-time-jump bits
uint16_t n; // measurement windows in the period
bool from_ram; // served from RAM (not yet persisted)
float v_rms, i_total, p_avg, q_avg, s_avg, pf;
float p_min, p_max, i_min, i_max;
uint64_t e_import_wh, e_export_wh; // life-time ABSOLUTE counters at the end of the period
uint8_t phases; // valid entries in the per-phase arrays (0..3)
double ph_import_wh[3], ph_export_wh[3]; // THIS period's energy per phase
};
Tome la energía de un período a partir de dos registros horarios consecutivos solo cuando sus marcas de tiempo difieran exactamente en un período y ninguno lleve el indicador de salto de vida útil.
bool stdHistReadRaw(RbAmpStdHistPeriod period, uint16_t back, uint8_t rec[rbamp_std::REG_HIST_REC_SIZE], uint8_t* flags) noexcept
Lee un registro sin decodificar de cualquier anillo en rec; flags (opcional) recibe los indicadores del registro del módulo.
bool stdEventRead(uint16_t back, RbAmpStdEvent& out) noexcept
Lee y decodifica un registro del registro de eventos (back = 0 es el más reciente); RB_ERR_NOT_READY = no existe tal registro.
struct RbAmpStdEvent {
uint32_t ts; // Unix time (0 if the clock was not set)
uint32_t uptime_s; // module uptime at the event
uint8_t type; // record type
uint8_t flags;
uint16_t boot; // boot counter at the event
uint32_t a_before, a_after; // event-specific values
uint64_t e_before_wh, e_after_wh; // life-time energy before / after, Wh
};
bool stdHistFlush() noexcept
Pida al módulo que escriba ahora sus acumuladores de energía en su almacenamiento.
Actualización de firmware por I²C
Una actualización en dos fases: stdOtaBegin() → stdOtaWritePage() por cada página → stdOtaCommit() (verifica la imagen y arma el intercambio; sin reinicio) → stdOtaActivate() (reinicia en la nueva imagen cuando usted decida). En la práctica use stdOtaWritePreparedImage(), que hace begin + páginas + commit en una sola llamada, y después stdOtaActivate(). Los módulos aceptan solo imágenes preparadas por el fabricante; una imagen mala la revierte el propio módulo y la calibración se conserva. Cada paso espera a que el módulo informe que el comando ha terminado (sin pausas fijas). Todas las llamadas fallan con RB_ERR_NOT_IMPLEMENTED salvo que el módulo informe la capacidad de actualización.
typedef void (*RbAmpOtaProgress)(uint32_t done, uint32_t total, void* ctx);
| Llamada | Descripción |
|---|---|
bool stdOtaStatus(uint8_t& out) |
El estado de actualización del módulo (rbamp_std::OTA_IDLE / READY / OK / ERR / DOWNGRADE). |
bool stdOtaBegin(uint32_t timeout_ms = 0) |
Borra el banco inactivo y espera a que el módulo informe que está listo. 0 = por defecto (5 s). false con RB_ERR_TIMEOUT si no se alcanza. |
bool stdOtaWritePage(uint32_t page_idx, const uint8_t* page) |
Escribe una página de 256 bytes en el índice page_idx. false con RB_ERR_CHECKSUM si la carga útil llegó corrupta (reenvíe la misma página); RB_ERR_IO si el módulo no pudo con la página; RB_ERR_NOT_READY si la sesión ya no está abierta. En los dos últimos casos reinicie desde stdOtaBegin() (véase stdOtaDiag()). |
bool stdOtaCommit(uint32_t timeout_ms = 0) |
Verifica la imagen escrita y arma el intercambio de bancos. 0 = por defecto (3 s). RB_ERR_CHECKSUM si la imagen es incorrecta, RB_ERR_VERSION si la imagen es anterior a la que está en ejecución (rechazada), RB_ERR_TIMEOUT. |
bool stdOtaActivate() |
Reinicia en la imagen armada, espera a que el módulo vuelva, lo redescubre, confirma que el banco en ejecución cambió y espera a que la nueva imagen se confirme a sí misma. Bloquea durante toda la secuencia (unos 12 s). La instancia sigue vinculada y stdInfo() refleja el nuevo firmware. false con RB_ERR_NOT_READY si no había nada armado, si el módulo volvió al banco anterior o si nunca confirmó la nueva imagen; RB_ERR_VERSION si la imagen que se ejecuta después no es la preparada (con reversión). |
static uint32_t stdCrc32(const uint8_t* data, size_t len) |
CRC-32 (compatible con zlib): la suma de comprobación por página que verifica el módulo. |
bool stdOtaWritePreparedImage(const uint8_t* image, size_t len, RbAmpOtaProgress cb = nullptr, void* ctx = nullptr) |
Transmite una imagen de banco preparada (begin + páginas + commit; sin activate). len debe coincidir con el tamaño de banco del módulo; si no, RB_ERR_PARAM. Las páginas van en orden ascendente, las páginas en blanco se omiten, y una página que el módulo informa como corrupta se reenvía una vez. |
bool stdOtaWritePreparedImage(Stream& image, size_t len, RbAmpOtaProgress cb = nullptr, void* ctx = nullptr) |
Forma de flujo: una página mantenida en RAM. |
bool stdOtaWritePreparedImage(const uint8_t* bank_a, const uint8_t* bank_b, size_t len, RbAmpOtaProgress cb = nullptr, void* ctx = nullptr) |
Proporcione ambas imágenes por banco; la biblioteca elige la del banco que no está en ejecución. RB_ERR_NOT_IMPLEMENTED si el módulo no informa de su banco en ejecución. |
bool stdOtaActiveBank(uint8_t& out) |
Id. del banco activo: 0 = A, 1 = B. |
bool stdOtaStagedVersion(uint32_t& out) |
Versión de la imagen armada (confirmada, pero aún no activada); 0 cuando no hay nada armado. |
bool stdOtaDiag(uint8_t& reason, uint8_t& hal_status) |
El motivo del último fallo de actualización informado por el módulo, más un byte de estado de bajo nivel. Léalo tras un fallo de confirmación o de escritura de página. |
bool stdOtaAbort() |
Cierre la sesión de actualización / desarme una imagen armada sin reiniciar. |
bool stdOtaBoardOk(uint32_t image_board_word) |
Rechaza una imagen compilada para otra placa antes de enviarla: compara el id de placa del módulo con la palabra de placa de la imagen (del manifiesto de la imagen). Una discrepancia devuelve RB_ERR_PARAM; RB_ERR_NOT_IMPLEMENTED en los módulos que no informan un id de placa. |
bool stdOtaWriteImage(const uint8_t* image, size_t len, uint32_t version, RbAmpOtaProgress cb = nullptr, void* ctx = nullptr) y la forma Stream& |
Se conserva solo por compatibilidad con el código fuente: devuelve false con RB_ERR_NOT_IMPLEMENTED sin tocar el módulo. Use stdOtaWritePreparedImage(). |
RbAmpFleet: gestión de varios módulos
La clase RbAmpFleet es la principal superficie de alto nivel de la biblioteca v1.3. Gestiona una colección de módulos en un bus I²C compartido: descubrimiento, aprovisionamiento, agregación de sondeos, agregación de errores y instantáneas síncronas mediante difusión General-Call.
Una flota se asocia a un único bus TwoWire (normalmente Wire); cada módulo adoptado es un handle RbAmp propio. El límite flexible de módulos es RBAMP_FLEET_MAX_MODULES = 16.
Ciclo de vida
RbAmpFleet(TwoWire& bus);
~RbAmpFleet(); // releases all adopted handles
Tras ~RbAmpFleet(), cualquier puntero de handle obtenido mediante get(idx) es no válido.
Descubrimiento: scan()
Configuración multimódulo (initialization) · Sondeo multimódulo: tres estrategias (realtime-polling) · Problemas multimódulo (troubleshooting)
bool scan(bool match_product, size_t& added);
Sondea el bus en el rango 0x08..0x77, y para cada dirección que responde con ACK:
-
Comprueba la identidad (
PRODUCT_ID,HW_VARIANT,CAPABILITY). Simatch_product = true, exige que coincida con el PRODUCT_ID de rbAmp. -
Ejecuta un detector de conflictos sobre dos señales independientes (consistencia de identidad + valor en vivo). Las direcciones sospechosas van a la lista
excluded, no a la flota. -
Realiza una prueba de centinela de bloqueo de nivel 2: sondea una dirección en la que, con seguridad, no debería haber nadie. Si el centinela recibe un ACK, devuelve
false: el bus está bloqueado, y la flota queda vacía (véase el diagnóstico en el cap. 10).
Tras el éxito, added contiene el número de módulos añadidos a la flota. excludedCount() (véase abajo) está disponible mediante un getter aparte.
Acceso al módulo
size_t count() const noexcept;
RbAmp* get(size_t index) noexcept;
RbAmp* find(uint8_t address) noexcept;
bool add(RbAmp* dev) noexcept;
size_t excludedCount() const noexcept;
int excludedAddr(size_t i) const noexcept;
get devuelve nullptr si está fuera de rango; find devuelve nullptr si la dirección no está en la flota (por ejemplo, porque quedó excluida). add permite añadir manualmente un handle creado por separado (por ejemplo, tras un aprovisionamiento manual).
Sondeo: pollAll()
Configuración multimódulo (initialization) · Sondeo multimódulo: tres estrategias (realtime-polling)
bool pollAll(RbAmpSnapshot* snaps,
RbAmpFleetPoll* status,
size_t capacity,
size_t& n_ok);
Sondea todos los módulos de la flota en una sola llamada. Para cada módulo realiza una lectura RT completa (readAll()) y asigna el resultado al elemento snaps[i] correspondiente. En paralelo, status[i] recibe el resultado de cada módulo (ok=true/false + addr + channels).
Al volver, n_ok es el número de módulos de los que se obtuvo una instantánea válida.
Resistente a MISS: un módulo silencioso no cancela el sondeo de los demás. Esto importa en una flota de producción: perder un módulo (un cable roto, una quemadura) no debe dejar sin monitorización a todo el conjunto.
Agregación
bool totalPower(float& out_w) noexcept;
bool totalEnergyWh(double& out_wh) noexcept;
bool pollErrors(uint32_t& error_mask, size_t& n_errors) noexcept;
totalPower suma la potencia activa de todos los canales de todos los módulos. Las variantes I no tienen potencia activa, así que aportan 0. En el despliegue canónico (UI1 de red + medidores secundarios I2/I3), el resultado es la potencia activa del módulo de red.
totalEnergyWh suma también los acumuladores de Wh de los handles. También funciona correctamente: las variantes I dan 0, UI1 da la energía por carga.
pollErrors recorre la flota llamando a hasError() en cada módulo; error_mask es una máscara de bits de los módulos marcados con EVENT bit3 según su posición (significativa para los primeros 32 módulos); n_errors es el número total de módulos con el indicador de error en el momento del sondeo.
Direccionamiento y comprobación de conflictos
bool assignAddress(RbAmp* dev, uint8_t new_addr);
bool checkConflict(uint8_t addr, bool& collision) noexcept;
assignAddress reasigna a un nuevo address un módulo existente de la flota: internamente, un commit en dos fases + reinicio; el handle de la flota se actualiza automáticamente (las llamadas posteriores siguen funcionando).
checkConflict: una comprobación de solo lectura y de mejor esfuerzo para una dirección concreta: lee la identidad (PRODUCT_ID / HW_VARIANT / CAPABILITY) y la compara con el estado en caché de la flota. Si se detecta una incoherencia: collision = true. Para recorrer todas las direcciones conocidas, itere sobre la flota: for (size_t i = 0; i < fleet.count(); ++i) + checkConflict(fleet.get(i)->address(), col). No garantiza detectar módulos idénticos: véase la disciplina de aprovisionamiento.
Aprovisionamiento: provision() (estático)
6.5 Aprovisionamiento: firmware nuevo + GUARDADO (api-reference)
static bool provision(TwoWire& bus,
uint8_t desired_addr,
bool save_config,
RbAmp*& out_dev);
Recibe un TwoWire& (normalmente Wire) y out_dev como parámetro de salida. Si tiene éxito, out_dev pertenece al llamador: normalmente se pasa directamente a fleet.add(out_dev):
Aprovisiona exactamente un módulo virgen (de fábrica en 0x50) en la dirección indicada. Internamente:
- Comprueba que hay respuesta en
0x50. - Comprueba que nadie está todavía en
desired_addr. - Realiza el commit de dirección en dos fases.
-
Reinicia el módulo y espera a que aparezca en
desired_addrdentro de la ventana de arranque. -
Crea el handle; si
save_config = true, llama asaveUserConfig()(persiste en flash). -
Devuelve el handle listo mediante
out.
⚠ OBLIGATORIO: exactamente un módulo virgen en el bus en el momento de la llamada. Dos módulos en 0x50 a la vez son físicamente indistinguibles por I²C; no pueden diferenciarse ni con hardware especial. La garantía recae en el operador, no en la biblioteca. Para la recuperación, consulte 10 · Solución de problemas, la sección «Flota: fallo de aprovisionamiento».
Sincronización GC de la flota: instantáneas síncronas en toda la flota
General Call (difusión en la dirección 0x00) (initialization) · Multimódulo: instantánea simultánea (period-metering) · 6.3 Instantánea por difusión GC: sincronización de flota opcional (api-reference)
bool enableGcAll(uint8_t group, size_t& ok_count);
bool gcLatch(uint8_t group, uint16_t tick, uint16_t settle_ms);
bool checkSync(uint16_t expected_tick,
RbAmpFleetSync* status,
size_t status_cap,
size_t& n_missed);
Para una sincronización estrecha de instantáneas en toda la flota se usa una instantánea de difusión I²C General-Call.
-
enableGcAllestableceFLEET_CONFIG.bit0+GROUP_IDen todos los módulos de la flota y emiteCMD_SAVE_USER_CONFIGen cada uno (persistente). Es obligatorio reiniciar los módulos tras activar; esto se hace automáticamente.ok_countes el número de módulos en los que la activación tuvo éxito. -
gcLatchenvía la trama GCA5 27 group tick_lo tick_hia la dirección0x00: todos los módulos con GC habilitado y ungroupcoincidente toman la instantánea (comandoLATCH_PERIOD) de forma inmediata.settle_mses la pausa tras la trama (normalmente 50 ms) antes de la verificación. -
checkSyncleeGC_TICK (0x59)de cada módulo enRbAmpFleetSync status[status_cap]. El resultado por módulo:
struct RbAmpFleetSync {
uint8_t addr; // I²C address of the module
uint16_t gc_tick; // REG_GC_TICK; 0xFFFF = never received a GC
bool in_sync; // true if gc_tick == expected_tick
bool reachable; // false if the read NACKed / timed out
};
n_missed es el número de módulos con in_sync = false (o simplemente sin respuesta). Si todos están en in_sync, n_missed == 0.
Configuración de flota por dispositivo (v1.3)
Estos métodos trabajan con un único módulo directamente (sin flota): para casos en los que configura un módulo individual antes de añadirlo a una flota, o necesita un control fino.
bool enableGc(bool enable) noexcept / bool readFleetConfig(uint8_t& out) noexcept
Llamada general (difusión en la dirección 0x00) (inicialización) · 4.4 Configuración de flota (0x27..0x2F) (api-reference)
enableGc(true) escribe 1 en FLEET_CONFIG.bit0 (0x27), guarda en flash y reinicia: el módulo empezará a aceptar instantáneas GC tras el arranque. enableGc(false) borra el bit de forma simétrica. Bloquea unos 1 segundo (estabilización de SAVE_USER_CONFIG + estabilización del reinicio). readFleetConfig devuelve el byte de configuración actual, útil para confirmar la lectura.
bool setGroupId(uint8_t group) noexcept / bool readGroupId(uint8_t& out) noexcept
GROUP_ID (0x28): el filtro de tramas GC: el módulo solo reacciona a tramas GC con un group_id coincidente. Por defecto = 0x00 (difusión, reacciona a cualquiera). Se usa en buses multiinquilino, por ejemplo un grupo «fase A» y un grupo «fase B» en un mismo bus compartido.
bool readGcTick(uint16_t& out) noexcept
Lee GC_TICK (0x59): el último valor de tick recibido de una trama GC. Sirve para detectar tramas perdidas (si dos módulos tienen ticks distintos, alguien perdió una trama). 0xFFFF = el módulo nunca ha recibido una trama GC desde el arranque.
static bool broadcastLatchGroup(TwoWire& bus, uint8_t group, uint16_t tick) noexcept
Un envío de bajo nivel de la trama GC A5 27 group tick_lo tick_hi directamente mediante bus (sin flota). Útil si la flota aún no está creada, o si quiere control manual del contador de ticks.
bool readActiveAddress(uint8_t& out) noexcept
Lee REG_I2C_ADDRESS (0x30): la dirección activa (en ejecución) del módulo. En v1.3, al arrancar lee la dirección activa, no un candidato preparado. En la línea STD devuelve el campo de dirección persistido (que se aplica al reiniciar). Útil para confirmar mediante lectura tras commitAddressChange().
Clase RbAmpEnergy
Un acumulador de Wh por canal. Pertenece a RbAmp y se accede mediante dev.energy(). El usuario normalmente no lo crea directamente.
Métodos públicos
double wh(uint8_t ch = 0) const noexcept;
El total actual de Wh de un canal, o de todos los canales con RBAMP_ENERGY_CH_TOTAL. Con signo: un valor negativo significa exportación neta. Si ch está fuera de rango, devuelve 0.0. (En un módulo STD sin contadores por canal use RbAmp::energyWh() para obtener NaN en lugar de un 0 engañoso.)
void addWh(uint8_t ch, double wh) noexcept;
Suma una energía con signo a un canal o al total de todos los canales. La biblioteca lo usa en la ruta de contadores STD; también está disponible para el código de usuario que integra la energía por sí mismo.
void reset(uint8_t ch = 0) noexcept;
void resetAll() noexcept;
Pone a cero un canal (o el total con RBAMP_ENERGY_CH_TOTAL) o todos los canales.
void disable() noexcept;
void enable() noexcept;
bool isEnabled() const noexcept;
Activa/desactiva la integración automática. Mientras la integración está desactivada, readPeriodSnapshot() sigue funcionando pero no avanza el acumulador: útil si el maestro mantiene su propio almacenamiento persistente de Wh.
uint32_t droppedDtCount() const noexcept;
void resetDroppedDtCount() noexcept;
Diagnóstico: cuántos ticks de integración se descartaron porque el período del maestro superaba el límite de coherencia de una hora.
El tick() interno
void tick(const RbAmpPeriodSnapshot& snap, uint8_t channels) noexcept;
Se llama automáticamente desde RbAmp::readPeriodSnapshot() si tiene éxito. El código del usuario no la llama directamente. Es idempotente: las instantáneas con valid == false se ignoran.
La fórmula de integración:
wh[ch] += snap.avg_p[ch] × snap.master_dt_ms / 1000 / 3600
[W] [milliseconds] → [Wh]
Precisión
Depende de la plataforma; para más detalles consulte 04 · Hardware:
-
ESP32 / ESP8266 / STM32duino / SAMD / RP2040: un acumulador
doublede 64 bits. -
Arduino AVR clásico (Uno, Mega, Nano): la cadena de herramientas define
doublecomofloatde 32 bits. En instalaciones de larga duración, reinicie periódicamente el acumulador (por ejemplo, una vez al día).
Estructuras y enumeraciones POD
Las estructuras de la línea STD (RbAmpStd*) se describen junto con las llamadas que las devuelven en la API de la línea STD.
RbAmpSnapshot
Devuelto por readAll(). Todos los campos en unidades SI. Los canales no utilizados (más allá de channels) se rellenan con ceros.
#define RBAMP_MAX_CHANNELS 7 // override before including to shrink the arrays
struct RbAmpSnapshot {
float voltage; // V — RMS voltage
float voltage_peak; // V — peak voltage
float current[RBAMP_MAX_CHANNELS]; // A — RMS current per channel
float current_peak[RBAMP_MAX_CHANNELS]; // A — peak current per channel
float power[RBAMP_MAX_CHANNELS]; // W — active power per channel (signed)
float power_factor[RBAMP_MAX_CHANNELS]; // dimensionless, −1..+1
float frequency; // Hz — grid frequency
RbAmpTopology topology; // Single / SplitPhase / ThreePhase / Five / Seven
uint8_t channels; // 1..RBAMP_MAX_CHANNELS — number of valid channels
bool has_voltage_hw; // true if a voltage sensor is present
uint8_t implausible; // RBAMP_FIELD_* bits of fields set to NaN by the sanity filter
};
Bits de implausible: RBAMP_FIELD_VOLTAGE, RBAMP_FIELD_CURRENT, RBAMP_FIELD_POWER, RBAMP_FIELD_PF, RBAMP_FIELD_FREQUENCY.
RbAmpPeriodSnapshot
Devuelto por readPeriodSnapshot(). La primitiva de medición de energía.
struct RbAmpPeriodSnapshot {
float avg_p[RBAMP_MAX_CHANNELS]; // W — average active power over the period
float max_p; // W — peak instantaneous power on channel 0
uint32_t latch_ms; // ms — period duration (device's view, diagnostic; 0 on STD)
uint32_t master_dt_ms; // ms — master wall-clock dt since the last snapshot
bool valid; // true if the snapshot ready flag was set
float avg_p_total; // W — average active power over the period, all channels
double wh_net; // Wh — net energy of this period (import − export)
bool module_restarted; // the module restarted inside this period (STD counter path only)
};
latch_ms es un temporizador de diagnóstico del módulo; no lo use para la energía: use el reloj del maestro (master_dt_ms).
RbAmpTopology
enum class RbAmpTopology : uint8_t {
Single = 1, // 1 current channel (UI1 / I1)
SplitPhase = 2, // 2 current channels (UI2 / I2)
ThreePhase = 3, // 3 current channels (UI3 / I3)
Five = 5, // 5 current channels (UI5) — senior SKU
Seven = 7, // 7 current channels (UI7) — senior SKU
};
RbAmpLine
enum class RbAmpLine : uint8_t {
Basic = 0, // 8-bit register map (the default until begin() runs)
Std = 1, // STANDARD (STD) line: 16-bit register map
};
RbAmpVariant
Unknown, UI1, UI2, UI3, I1, I2, I3, UI5, UI7 — véase readVariant().
RbAmpSensorClass
enum class RbAmpSensorClass : uint8_t {
Unset = 0, // Factory default; setCTModel() will refuse
Sct013 = 1, // SCT-013 series clamp fitted by the user
WiredCT = 2, // Wired CT shipped with the module and calibrated together with it
BuiltinCT = 3, // Built-in CT, calibrated together with the module
};
WiredCT y BuiltinCT describen módulos que se suministran y se calibran junto con su sensor. Los setters nunca reescriben estos módulos (devuelven false con RB_ERR_MODE); setCTModelChForce() es la vía de servicio.
RbAmpCTModel
Enumeración congelada de compatibilidad hacia atrás para los siete códigos SCT-013 (Sct013_005 … Sct013_060). El código nuevo pasa a las sobrecargas uint8_t un define RBAMP_CT_* generado.
RbAmpSctRating y RbAmpSctRatingStatus
Véase Corrección de clasificación SCT-013.
RbAmpDrdyEvent
Véase Línea de datos listos y eventos.
Códigos de error (espacio de nombres rbamp)
Definido en RbAmpRegisters.h, devuelto por lastError().
namespace rbamp {
constexpr int8_t RB_OK = 0;
constexpr int8_t RB_ERR_IO = -1; // I²C transport error
constexpr int8_t RB_ERR_NACK = -2; // retry exhausted, slave not responding
constexpr int8_t RB_ERR_TIMEOUT = -3; // timeout (waitReady / waitDataReady / commit-addr window expired)
constexpr int8_t RB_ERR_NOT_READY = -4; // module not ready / no such record / nothing armed
constexpr int8_t RB_ERR_STALE = -5; // period snapshot not ready
constexpr int8_t RB_ERR_PARAM = -6; // invalid channel / address / precondition; the module rejected a value
constexpr int8_t RB_ERR_MODE = -7; // not allowed in the module's current mode (factory-paired class, factory-only command)
constexpr int8_t RB_ERR_CHECKSUM = -8; // value check failed — checksum / signature / range
constexpr int8_t RB_ERR_VERSION = -9; // unsupported firmware / image version
constexpr int8_t RB_ERR_NOT_IMPLEMENTED = -10; // no counterpart on this line or on this module image
constexpr int8_t RB_ERR_NON_PHYSICAL = -11; // float rejected by the sanity filter
}
Recetas de diagnóstico para cada código: 10 · Solución de problemas.
Recetas de diagnóstico para cada código: 10 · Solución de problemas.
Configuración en tiempo de compilación
Defina ANTES de #include para cambiar los valores por defecto:
#define RBAMP_NACK_RETRY_ATTEMPTS 5 // number of retry attempts per byte
#define RBAMP_NACK_RETRY_GAP_MS 5 // pause between attempts, ms
#include
Valores por defecto de la plataforma:
#if defined(ARDUINO_ARCH_ESP32) || defined(ESP_PLATFORM)
# define RBAMP_NACK_RETRY_ATTEMPTS 3
#else
# define RBAMP_NACK_RETRY_ATTEMPTS 1
#endif
#define RBAMP_NACK_RETRY_GAP_MS 5
Para más información sobre la capa de resiliencia: 10 · Solución de problemas.
Constantes de tiempo de estabilización
Definidos en RbAmpRegisters.h. La biblioteca los usa internamente; se exportan para quienes quieran respetar la misma temporización durante el acceso directo al bus:
constexpr uint16_t SETTLE_MS_LATCH_PERIOD = 50; // after CMD_LATCH_PERIOD
constexpr uint16_t SETTLE_MS_SAVE_GAINS = 700; // after CMD_SAVE_GAINS (flash write)
constexpr uint16_t SETTLE_MS_RESET = 300; // after CMD_RESET
constexpr uint16_t SETTLE_MS_FACTORY_RESET = 1500; // after CMD_FACTORY_RESET
Detalles del protocolo de bus
Esta sección describe el protocolo de registros de 8 bits de la línea BASIC. La línea STD usa un puntero de registro de 16 bits con lecturas en ráfaga con autoincremento; la biblioteca lo gestiona internamente (begin() detecta la línea) y el cableado físico es el mismo bus I²C. El código de aplicación nunca necesita los detalles del cable STD: use las llamadas de la API de la línea STD.
Lecturas de registros — autoincremento
Una lectura en ráfaga devuelve N bytes consecutivos a partir de addr. Las funciones de la biblioteca usan ráfagas siempre que es posible (una transacción I²C = 4 bytes de float).
Escrituras de registros: byte a byte (NO autoincrementa)
⚠ Las escrituras NO se autoincrementan. Una ESCRITURA en ráfaga solo deja escrito el primer byte: los bytes 1..N se descartan.
Un registro de varios bytes se escribe un byte cada vez: una transacción I²C de un solo byte independiente por dirección:
// WRONG — data loss
uint8_t label[8] = "MyMeter1";
Wire.beginTransmission(addr);
Wire.write(0x68); // start of LABEL
Wire.write(label, 8); // burst — only 'M' lands
Wire.endTransmission();
// CORRECT — byte-at-a-time loop
for (int i = 0; i < 8; i++) {
Wire.beginTransmission(addr);
Wire.write(0x68 + i);
Wire.write(label[i]);
Wire.endTransmission();
}
Afecta a los registros escribibles de varios bytes: LABEL (0x68-0x6F), U_GAIN/I_GAIN (f32, restringido a fábrica), NF (u16), THRESH (u16). Las lecturas en ráfaga son válidas.
Excepción: la trama de difusión GC (5 bytes A5 27 g tl th a la dirección 0x00) es una ruta de protocolo de cable separada (recepción de llamada general, no una escritura de registro), enviada como una única transacción. Véase el escenario 12 en 06 · Ejemplos.
Lectura de registros no asignados
Cualquier lectura de una dirección no mapeada devuelve 0x00. El firmware nunca responde con NACK a las lecturas de registros. La detección de ausencia del dispositivo se hace por el ACK de la trama de dirección I²C, no sondeando registros.
Detección de variante
El byte de SKU autorizado es REG_HW_VARIANT (0x55) (el método readVariant()):
| valor | SKU |
|---|---|
0x01 |
UI1 (1× I + U) |
0x02 |
UI2 (2× I + U) |
0x03 |
UI3 (3× I + U) |
0x04 |
I1 (1× I, sin U) |
0x05 |
I2 (2× I, sin U) |
0x06 |
I3 (3× I, sin U) |
0x07 |
UI5 (5× I + U, SKU superior) |
0x08 |
UI7 (7× I + U, SKU superior) |
REG_TOPOLOGY (0x24) es auxiliar (solo indica el número de canales; no distingue la presencia de U). En la línea STD la biblioteca lee la identidad desde el mapa de 16 bits del propio módulo durante begin() y asigna la variante a readVariant().
Instantánea por difusión General-Call (sincronización multimódulo)
Opt-in por módulo mediante REG_FLEET_CONFIG.bit0: GC_ENABLE. Desactivado por defecto. Se activa mediante CMD_SAVE_USER_CONFIG + CMD_RESET (suave o duro). Tras el reinicio, el módulo escucha una trama de difusión en la dirección 0x00:
addr=0x00 | A5 27
A5: magia;27: opcodeCMD_LATCH_PERIOD.:0x00= all-call; en otro caso debe coincidir conREG_GROUP_ID (0x28).: el contador de período de sincronización del maestro, de 16 bits.
La trama solo toma la instantánea; los códigos de operación destructivos no se transmiten por GC.
Detección del modo de fallo (dos niveles):
- NACK de la dirección GC (de inmediato a nivel de bus): si la GC está desactivada en toda la flota,
Wire.endTransmission()a0x00devuelve un código distinto de cero (NACK). Es un error duro, no un descarte silencioso. La biblioteca lo trata como «GC no habilitada» (requiere las condiciones previas de activación + reinicio). - Testigo por módulo (tras el asentamiento): si no se produjo ningún NACK, lea
REG_V03_PERIOD_VALID (0x07)en cada módulo esperado.1= la instantánea tuvo éxito;0= GC desactivada en este módulo o el periodo está vacío;!=1→ recurra a un latch por dispositivo.
Referencias
- 05 · Inicio rápido: su primer boceto funcional
- 06 · Ejemplos — escenarios de trabajo
-
10 · Solución de problemas — interpretación de errores y resolución de problemas habituales
-
Archivo fuente con comentarios Doxygen:
src/RbAmp.h
Fuente y incidencias: rb-amp/rbamp-arduino · esta página en el repositorio: docs/09_api_reference.md (v1.6.2)