09 · Referencia de API
La API pública completa del componente rbamp para ESP-IDF. El código fuente es el archivo de cabecera include/rbamp.h con comentarios Doxygen; el gestor de flota multimódulo está en include/rbamp_fleet.h y el tipo acumulador de Wh en include/rbamp_energy.h.
Este capítulo es una referencia: firmas, valores devueltos, efectos secundarios y casos límite. Para ejemplos prácticos vaya a 06 · Ejemplos; para un inicio rápido, vea 05 · Inicio rápido.
Archivo de cabecera
#include "rbamp.h": la cabecera pública principal. Incluye transitivamente esp_err.h para esp_err_t y driver/i2c_master.h para el tipo i2c_master_bus_handle_t. No se necesitan inclusiones adicionales.
La API está envuelta en un bloque extern "C": compatible con llamadores en C y en C++.
Modismos generales
La API sigue los patrones estándar de ESP-IDF:
-
Manejador opaco:
rbamp_handle_t— un typedef parastruct rbamp_obj_t *; el usuario no accede a sus partes internas. Se crea conrbamp_new()y se libera conrbamp_del(). -
Valores devueltos de
esp_err_t:ESP_OKen caso de éxito, uno de los códigosESP_ERR_*en caso de fallo. UseESP_ERROR_CHECK()para el manejo de errores con aborto, o compruebe manualmente. -
Salida por puntero: las funciones que devuelven un valor reciben un puntero a un búfer como último parámetro. Así, una sola llamada puede devolver tanto un
esp_err_tcomo un valor. -
Cadenas de error legibles:
rbamp_err_to_str(err)devuelve un puntero a una cadena estática. Nunca devuelveNULL. -
Un manejador, dos líneas de módulos: el mismo manejador y la misma API escalar sirven a la línea BASIC y a la STD;
rbamp_begin()detecta la línea y enruta cada llamada. Las funciones que existen solo en una línea devuelvenESP_ERR_NOT_SUPPORTEDen la otra (véanserbamp_line_ty Línea STD). -
Los comandos no se reintentan. Una escritura de comando (instantánea, reinicio, guardado, ...) nunca se repite tras un error de transporte: un reintento podría entregar el código de operación dos veces. Las lecturas y escrituras de registros de datos sí mantienen el reintento NACK.
-
Asignación de errores usada en toda la API:
ESP_ERR_NOT_SUPPORTED: la función o la característica no existe en esta línea / firmware / módulo;ESP_ERR_NOT_FOUND: el módulo o el registro no está presente (nadie responde, no hay tal registro de historial, no hay certificado);ESP_ERR_INVALID_STATE: una condición previa o la secuencia de llamadas es incorrecta, o un módulo de sensor emparejado está protegido (vea Códigos de error).
Tipos
rbamp_handle_t
typedef struct rbamp_obj_t *rbamp_handle_t;
Un manejador opaco a un dispositivo esclavo. El usuario no tiene acceso a sus campos. Se crea con rbamp_new() y se libera con rbamp_del().
rbamp_topology_t
typedef enum {
RBAMP_TOPOLOGY_SINGLE = 1, /* 1 current channel (UI1 / I1) */
RBAMP_TOPOLOGY_SPLIT_PHASE = 2, /* 2 current channels (UI2 / I2) */
RBAMP_TOPOLOGY_THREE_PHASE = 3, /* 3 current channels (UI3 / I3) */
RBAMP_TOPOLOGY_FIVE_CH = 5, /* 5 current channels (UI5) */
RBAMP_TOPOLOGY_SEVEN_CH = 7, /* 7 current channels (UI7) */
} rbamp_topology_t;
El valor es el número de canales. rbamp_begin() lo adopta de la variante del módulo; rbamp_new_with_topology() lo fija en su lugar. La enumeración no es contigua a propósito (no existen 4 ni 6): los SKU mayores saltan de 3 a 5 y a 7.
Dos constantes dimensionan sus arrays:
| Macro | Valor | Significado |
|---|---|---|
RBAMP_MAX_CHANNELS |
7 | El mayor número de canales que expone cualquier SKU. Dimensione los arrays de canales con él. |
RBAMP_SNAPSHOT_CHANNELS |
3 | Canales que lleva rbamp_snapshot_t (ch0–2). Los canales 3 y siguientes se leen con rbamp_read_channel() / rbamp_read_all_channels(). |
rbamp_sensor_class_t
typedef enum {
RBAMP_SENSOR_UNSET = 0, /* Factory default */
RBAMP_SENSOR_SCT013 = 1, /* SCT-013 fitted by the user */
RBAMP_SENSOR_WIRED_CT = 2, /* Wired CT shipped with the module, calibrated as a pair */
RBAMP_SENSOR_BUILTIN_CT = 3, /* Built-in CT, calibrated as a pair */
} rbamp_sensor_class_t;
La clase 1 es un módulo al que el usuario acopla una pinza SCT-013 de su elección: el modelo de CT selecciona el tipo de sensor. Las clases 2 y 3 son módulos que se entregan junto con su sensor y se calibran con él. La biblioteca no reescribe la clase ni el modelo de estos módulos: rbamp_set_sensor_class() y rbamp_set_ct_model_ch() devuelven ESP_ERR_INVALID_STATE. Un reemparejamiento de servicio se hace mediante rbamp_set_ct_model_ch_force().
rbamp_variant_t
La variante de hardware, devuelta por rbamp_variant() y rbamp_read_variant():
| Valor | Enumeración | Canales | Tensión / potencia |
|---|---|---|---|
| 0 | RBAMP_VARIANT_UNKNOWN |
— | aún no leído / no publicado |
| 1 | RBAMP_VARIANT_UI1 |
1 | sí |
| 2 | RBAMP_VARIANT_UI2 |
2 | sí |
| 3 | RBAMP_VARIANT_UI3 |
3 | sí |
| 4 | RBAMP_VARIANT_I1 |
1 | no |
| 5 | RBAMP_VARIANT_I2 |
2 | no |
| 6 | RBAMP_VARIANT_I3 |
3 | no |
| 7 | RBAMP_VARIANT_UI5 |
5 | sí |
| 8 | RBAMP_VARIANT_UI7 |
7 | sí |
rbamp_line_t
typedef enum {
RBAMP_LINE_BASIC = 0, /* default until rbamp_begin() has run */
RBAMP_LINE_STD = 1,
} rbamp_line_t;
Un tipo de manejador y una sola API sirven a ambas líneas de módulos. rbamp_begin() descubre la línea a partir del bloque de identidad del módulo y todas las llamadas posteriores se enrutan internamente. Consúltela con rbamp_line(dev). Las llamadas sin equivalente en la línea detectada devuelven ESP_ERR_NOT_SUPPORTED: nunca una lectura de registro equivocada. Lo que solo ofrece la línea STD (potencia reactiva / aparente, THD, contadores de energía con signo, bancos de instantáneas, historial) se recoge en Línea STD.
rbamp_snapshot_t
Devuelto por rbamp_read_all(). Todos los campos están en unidades SI. Los canales no usados (más allá de channels) se rellenan con ceros.
typedef struct {
float voltage; /* V — RMS voltage */
float voltage_peak; /* V — peak voltage */
float current[3]; /* A — RMS current, ch0–2 */
float current_peak[3]; /* A — peak current, ch0–2 */
float power[3]; /* W — active power, ch0–2 (signed) */
float power_factor[3]; /* dimensionless, −1..+1 */
float frequency; /* Hz — mains frequency */
rbamp_topology_t topology;
uint8_t channels; /* the module's channel count: 1, 2, 3, 5 or 7 */
bool has_voltage_hw; /* true if a voltage sensor is present */
uint8_t implausible; /* bitmask of RBAMP_FIELD_* classes set to NaN; 0 = all OK */
} rbamp_snapshot_t;
Los arrays guardan solo los canales 0–2. En un UI5/UI7, channels informa del número completo (5 o 7); lea los canales 3 y superiores con rbamp_read_channel() / rbamp_read_all_channels().
Campos no plausibles. Un único campo fuera de límites no hace fallar toda la instantánea: un campo que supera su límite de cordura por magnitud se fija en NaN y su bit de clase se activa en implausible, mientras el resto sigue siendo utilizable y rbamp_read_all() sigue devolviendo ESP_OK. Compruebe implausible (o isnan() por campo) antes de usar un valor.
| Bit | Significado |
|---|---|
RBAMP_FIELD_VOLTAGE |
tensión / pico de tensión rechazados |
RBAMP_FIELD_CURRENT |
una corriente / pico de corriente rechazados |
RBAMP_FIELD_POWER |
una potencia rechazada |
RBAMP_FIELD_PF |
un power_factor rechazado |
RBAMP_FIELD_FREQUENCY |
frecuencia rechazada |
Los límites son RBAMP_SANITY_LIMIT_V / _I / _P / _PF (500 V, 150 A, 30000 W, 1.5). Solo un fallo real de transporte hace que rbamp_read_all() devuelva un valor distinto de OK.
rbamp_channel_reading_t
Devuelto por rbamp_read_channel() / rbamp_read_all_channels(): un canal, cualquier índice.
typedef struct {
float i_rms; /* A */
float i_peak; /* A */
float p_real; /* W (signed) */
float pf; /* −1..+1 */
uint8_t implausible; /* RBAMP_FIELD_* bits; the flagged field is NaN */
} rbamp_channel_reading_t;
rbamp_period_snapshot_t
Devuelto por rbamp_read_period_snapshot(). Es la primitiva de contabilidad de energía.
typedef struct {
float avg_p[3]; /* W — average active power over the period, ch0–2 */
float max_p; /* W — peak power on channel 0 during the period */
uint32_t latch_ms; /* ms — module-reported duration; DIAGNOSTIC, not for energy */
uint32_t master_dt_ms; /* ms — master wall-clock window since the previous consumed read (CANONICAL) */
bool valid; /* the period was ready at read time */
float avg_p_total; /* W — average active power summed over ALL channels (signed) */
double wh_net; /* Wh — net energy of this period as the library accounted it (signed) */
bool module_restarted; /* the module rebooted inside this period */
uint32_t module_window_ms; /* ms — the module's own length of the closed window (0 on STD) */
uint16_t module_commit_ms; /* ms — length of one module commit as inferred: 100 or 200 (0 on STD) */
uint32_t module_uptime_s; /* s — module uptime read with the snapshot (0 if not published) */
bool window_from_boot; /* the window started at the module's boot */
bool window_long; /* module_window_ms exceeds 6 h */
} rbamp_period_snapshot_t;
| Campo | Notas |
|---|---|
avg_p[3] |
Solo canales 0–2. En un UI5/UI7 el módulo toma la instantánea de potencia media de todos los canales de forma atómica; lea los canales 3 en adelante con rbamp_read_period_avg_power() y sus Wh con rbamp_energy_wh() (el acumulador integra todos los canales). |
max_p |
Un pico global, tomado en el canal 0. |
latch_ms |
Solo diagnóstico: puede leerse corto bajo carga. La ventana de integración de energía es master_dt_ms o module_window_ms. |
master_dt_ms |
La ventana sobre la que integra la energía la biblioteca: el tiempo propio del maestro con esp_timer entre dos lecturas consumidas consecutivas. |
avg_p_total, wh_net |
El período sumado en todos los canales. wh_net es la potencia media × master_dt_ms, o, en módulos que guardan la energía en el dispositivo, la diferencia del contador propio del módulo. |
module_window_ms, module_commit_ms |
La medida del módulo para la ventana cerrada: confirmaciones contadas en el reloj de medición del módulo, 100 ms cada una en el firmware actual y 200 ms en firmware anterior a v1.2; la biblioteca deduce cuál a partir de la misma instantánea. Normalmente contrasta con master_dt_ms. Ambas valen 0 en la línea STD. |
module_restarted |
El módulo se reinició dentro del período. Sus ajustes de RAM (reloj, máscara de eventos, umbrales, campos de digest) deben volver a aplicarse: la biblioteca reaplica los que le corresponden. En un módulo BASIC se fija en la primera instantánea tras rbamp_begin_resume() cuando la ventana empezó en el arranque del módulo. |
module_uptime_s, window_from_boot |
window_from_boot es true cuando la ventana de la instantánea empezó en el arranque del módulo (un reinicio, o la primera instantánea desde el arranque). Siempre es false cuando el firmware no publica el tiempo de actividad (module_uptime_s = 0). |
window_long |
La ventana supera las 6 h: el promedio del módulo pierde precisión en ventanas tan largas; tome instantáneas con más frecuencia. |
⚠ latch_ms es diagnóstico, no sirve para la energía. Es la medida propia del módulo del periodo y puede leerse corta bajo carga. No la use para integrar la energía. El dt canónico para la energía es master_dt_ms (o su propia diferencia de esp_timer_get_time()), o module_window_ms para la primera instantánea tras rbamp_begin_resume().
Bits de evento — rbamp_event_bit_t
Bits del byte EVENT_FLAGS sticky de escritura-1-para-borrar (véase Eventos):
| Enumeración | Significado |
|---|---|
RBAMP_EVENT_PERIOD_READY |
Se tomó una instantánea de período |
RBAMP_EVENT_THRESH_I |
Se superó el umbral de corriente |
RBAMP_EVENT_THRESH_P |
Umbral de potencia superado |
RBAMP_EVENT_ERROR |
Indicador de error persistente (véase Modelo de errores) |
RBAMP_EVENT_CONFIG_CHANGED |
Configuración persistida modificada |
RBAMP_EVENT_RESET_OCCURRED |
El módulo se reinició desde la última limpieza |
RBAMP_EVENT_NVM_FAULT |
Solo STD: fallo del almacén de energía |
rbamp_drdy_event_t
Rellenado por rbamp_wait_data_ready() / rbamp_read_all_ready():
typedef struct {
bool fresh; /* a new snapshot of THIS module is available (true on ESP_OK) */
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: an unmasked event is pending on this module */
uint8_t event_flags; /* EVENT_FLAGS consumed on an alarm (RBAMP_EVENT_*), else 0 */
uint32_t latency_us; /* edge to return, µs (0 when polling) */
} rbamp_drdy_event_t;
Tipos de resumen
typedef enum {
RBAMP_DIGEST_I = ..., /* RMS current per channel */
RBAMP_DIGEST_U = ..., /* RMS voltage (modules with voltage sensing only) */
RBAMP_DIGEST_P = ..., /* real power per channel, whole watts, signed */
RBAMP_DIGEST_PF = ..., /* |power factor| per channel */
} rbamp_digest_field_t;
typedef struct {
uint8_t status; /* STATUS mirror at the moment of the publish */
uint8_t seq; /* window sequence (one step per published window, wraps 255→0) */
uint8_t n_ch; /* channels in the digest: min(module channels, 3) */
uint8_t fields; /* which rbamp_digest_field_t bits were read */
float i_a[3]; /* A; 0 when the field is off */
float u_v; /* V; 0 when off or no voltage sensing */
int16_t p_w[3]; /* W, signed, truncated toward 0 (|P| < 1 W reads 0); 0 when off */
float pf[3]; /* |PF| 0..1; 0 when off */
} rbamp_digest_t;
Tipos de corrección del SCT-013
typedef enum {
RBAMP_SCT_NONE, /* no correction (scale 1) */
RBAMP_SCT_CORRECTED, /* scale applied to this channel */
RBAMP_SCT_UNCALIBRATED, /* after a reset the module applies the raw preset; scale 1, warning logged */
RBAMP_SCT_GAIN_UNEXPECTED,/* applied gain is not that of a 30 A-calibrated module; scale 1, warning logged */
RBAMP_SCT_UNKNOWN_MODEL, /* model code without a known preset; scale 1, warning logged */
RBAMP_SCT_PENDING, /* not evaluated yet (before rbamp_begin); scale 1 */
} rbamp_sct_status_t;
typedef struct {
rbamp_sct_status_t status;
uint8_t model; /* CT model the module reports for the channel */
float scale; /* factor applied to current, power, energy and digest (1.0 unless CORRECTED) */
float gain_applied; /* gain the module applies (0 when not read) */
} rbamp_sct_correction_t;
RBAMP_SCT_NONE se informa en la línea STD, para la clase de sensor 2/3, sin modelo asociado, con el modelo 3 (el sensor de fábrica de 30 A), en un módulo que se corrige solo (vea Corrección de la nominal del SCT-013) y cuando CONFIG_RBAMP_SCT_RATING_CORRECTION está desactivado.
Los tipos de la línea STD (rbamp_std_info_t, rbamp_std_channel_t, ...) se describen junto con sus funciones en Línea STD.
Ciclo de vida
rbamp_new
esp_err_t rbamp_new(i2c_master_bus_handle_t bus,
uint8_t addr,
rbamp_handle_t *out);
Crea un manejador opaco para un dispositivo esclavo. Internamente crea un i2c_master_dev_handle_t mediante i2c_master_bus_add_device().
El número de canales y la presencia de tensión se toman del módulo en rbamp_begin(): un UI1 informa de 1 canal, un UI3 de 3, un UI7 de 7, y así sucesivamente; por eso rbamp_channels(dev) es correcto tras begin, y la API por canal (rbamp_set_ct_model_ch, ...) protege frente a los canales que el módulo no tiene. Solo cuando el módulo no publica su variante (firmware anterior a v1.3) el manejador recurre a RBAMP_TOPOLOGY_THREE_PHASE; la sobredetección es inofensiva ahí: los canales no usados leen 0.0 A. Use rbamp_new_with_topology() para fijar un número de canales con independencia de lo que diga el módulo.
| Parámetro | Descripción |
|---|---|
bus |
Manejador del bus I²C creado mediante i2c_new_master_bus(). |
addr |
Dirección de esclavo de 7 bits. Rango 0x08..0x77, por defecto 0x50. |
out |
Dónde escribir el nuevo manejador. |
Devuelve: ESP_OK en caso de éxito; ESP_ERR_NO_MEM si no pudo reservarse memoria; ESP_ERR_INVALID_ARG si bus == NULL o out == NULL o si addr está fuera de rango; el esp_err_t de i2c_master_bus_add_device() ante un error del driver del bus.
rbamp_new_with_topology
esp_err_t rbamp_new_with_topology(i2c_master_bus_handle_t bus,
uint8_t addr,
rbamp_topology_t topology,
rbamp_handle_t *out);
Igual que rbamp_new, pero con una topología explícita. Fija el número de canales: rbamp_begin() lo mantiene aunque el módulo informe otro (se registra un aviso). La variante y la presencia de tensión siguen al módulo. Solo es necesario para firmware anterior a la v1.3, que no publica su variante, o para exponer deliberadamente menos o más canales de los que tiene el módulo.
rbamp_del
void rbamp_del(rbamp_handle_t dev);
Libera el manejador y elimina del bus el i2c_master_dev_handle_t asociado. Es seguro llamarla con NULL: no hace nada.
rbamp_begin
02 · Inicialización y arranque (initialization) · ¿BASIC o STD? (initialization) · Ciclo de sondeo continuo (recomendado) (period-metering)
esp_err_t rbamp_begin(rbamp_handle_t dev);
Sondea el dispositivo, detecta la línea del módulo, adopta el número de canales y la variante, y cebar una instantánea.
Sequence:
-
Lea
REG_VERSION(0x03). Si el dispositivo no hizo ACK:ESP_FAIL. Si devolvió0x00/0xFF:ESP_ERR_INVALID_RESPONSE. -
Detecte la línea de producto (BASIC / STD) a partir del bloque de identidad del módulo y guárdela en caché (
rbamp_line()). En la línea STD también se guarda en caché la identidad (rbamp_std_info()) y se elige el mecanismo de período. -
Adopta del módulo el número de canales, la variante y la presencia de tensión (salvo que se haya fijado una topología con
rbamp_new_with_topology). -
Evalúe la corrección de la nominal del SCT-013 (vea Corrección de la nominal del SCT-013).
-
Escriba
CMD_LATCH_PERIODcomo cebado y espere 50 ms. La primera instantánea tras el encendido se descarta. (rbamp_begin_resume()omite este paso.) -
Guarde
esp_timer_get_time()para la integración posterior de la energía.
Idempotente, pero no gratuito: cada llamada emite una instantánea de cebado.
Devuelve: ESP_OK en caso de éxito; los códigos de error anteriores en otro caso.
rbamp_begin_resume
esp_err_t rbamp_begin_resume(rbamp_handle_t dev);
rbamp_begin() sin la instantánea de cebado: conserva la ventana que el módulo acumuló mientras el master estuvo ausente. Un módulo BASIC sigue promediando hasta la siguiente instantánea, así que tras un reinicio o una caída del master el módulo conserva toda la ventana desde la última instantánea consumida; rbamp_begin() tomaría una instantánea y la descartaría, esta llamada no.
La primera rbamp_read_period_snapshot() consumida tras integrar la ventana propia del módulo (module_window_ms): wh_net = avg_p_total × module_window_ms, master_dt_ms se iguala a module_window_ms y module_restarted = window_from_boot. Todas las instantáneas posteriores usan el reloj del master como de costumbre. Una primera lectura obsoleta (período no válido, acumulador vacío) se descarta como cualquier otra, y la siguiente lectura válida sigue usando la ventana del módulo.
En firmware que no publica el tiempo de funcionamiento, window_from_boot y module_restarted permanecen en false: la ventana recuperada puede incluir entonces un reinicio del módulo que la biblioteca no puede ver. En los módulos STD la llamada es idéntica a rbamp_begin() (su energía vive en contadores del módulo).
rbamp_begin_event_flags
uint8_t rbamp_begin_event_flags(rbamp_handle_t dev);
Los EVENT_FLAGS tal como los encontró rbamp_begin() (ambas líneas; 0 si no eran legibles). RBAMP_EVENT_RESET_OCCURRED aquí significa que el módulo se había reiniciado antes de que la biblioteca lo viera: vuelva a aplicar sus ajustes de RAM (reloj, máscara de eventos, umbrales). La biblioteca no borra nada al iniciar. Sin tráfico en el bus.
rbamp_probe
esp_err_t rbamp_probe(rbamp_handle_t dev);
Una comprobación ligera de que el módulo responde. Una sola lectura de REG_VERSION sin efectos secundarios.
Devuelve: ESP_OK si el esclavo respondió con ACK e informó de una versión soportada (no 0 ni 0xFF); ESP_FAIL en otro caso.
rbamp_wait_ready
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)
esp_err_t rbamp_wait_ready(rbamp_handle_t dev, uint32_t timeout_ms);
Consulta el indicador de listo del módulo hasta que el bit 0 esté activo. Útil tras el encendido: el módulo puede necesitar hasta 100 ms para la primera ventana RT.
Devuelve: ESP_OK si el bit se ve antes de que expire timeout_ms; ESP_ERR_TIMEOUT en caso contrario.
Getters del estado del manejador
¿BASIC o STD? (initialization) · Corriente multicanal (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.10 Bloque en tiempo real V03 (0x86..0xBD) (api-reference)
uint8_t rbamp_firmware_version(rbamp_handle_t dev);
rbamp_topology_t rbamp_topology (rbamp_handle_t dev);
uint8_t rbamp_channels (rbamp_handle_t dev);
rbamp_variant_t rbamp_variant (rbamp_handle_t dev);
bool rbamp_has_voltage_hw (rbamp_handle_t dev);
uint8_t rbamp_address (rbamp_handle_t dev);
rbamp_line_t rbamp_line (rbamp_handle_t dev);
Todas devuelven valores cacheados sin tocar el bus.
| Función | Devuelve |
|---|---|
rbamp_firmware_version |
El byte REG_VERSION cacheado tras rbamp_begin(): en la línea STD es la versión del mapa de registros, no la versión de la imagen de firmware (vea rbamp_std_read_image_version). 0 antes de rbamp_begin() o si falló. |
rbamp_topology |
La enumeración del número de canales: la informa el módulo tras rbamp_begin(), o la fija rbamp_new_with_topology(); THREE_PHASE antes de begin / en firmware que no publica su variante. |
rbamp_channels |
Número de canales de corriente válidos (1, 2, 3, 5 o 7). |
rbamp_variant |
La variante cacheada por rbamp_begin(); RBAMP_VARIANT_UNKNOWN antes de begin o cuando el módulo no la publica. rbamp_read_variant() vuelve a leer el registro. |
rbamp_has_voltage_hw |
true si se detectó hardware de detección de tensión. |
rbamp_address |
La dirección I²C actual de 7 bits (se actualiza tras rbamp_commit_address_change()). |
rbamp_line |
RBAMP_LINE_BASIC hasta que se ejecute rbamp_begin(), y después la línea detectada. |
rbamp_basic_fw_name
const char *rbamp_basic_fw_name(uint8_t version);
Una búsqueda pura (sin tráfico en el bus): el nombre de firmware legible para el byte REG_VERSION de un BASIC, tal como lo devuelve rbamp_firmware_version(); por ejemplo 0x0D → "1.4.21", 0x0C → "1.4.20", 0x0B → "1.4.19", 0x0A → "1.4.18", 0x07 → "1.4.15-1.4.17", 0x05 → "1.4.4-1.4.14", 0x04 → "1.2-1.4.3", 0x00..0x03 → "<1.2". Cualquier otro byte → NULL (desconocido, o no es un módulo BASIC).
Lecturas en tiempo real (bloque RT, refresco de 100 ms)
Todas las funciones devuelven esp_err_t. En ESP_OK el valor se escribe en el puntero out; ante un error *out no está definido. Por debajo hay una disciplina de reintento y verificación de coherencia para resistir los raros fallos del enlace en la pila I²C de ESP-IDF.
Lecturas por canal
Referencia de registros RT (realtime-polling) · Contabilidad bidireccional (period-metering)
esp_err_t rbamp_read_voltage (rbamp_handle_t dev, uint8_t phase, float *out);
esp_err_t rbamp_read_voltage_peak (rbamp_handle_t dev, uint8_t phase, float *out);
esp_err_t rbamp_read_current (rbamp_handle_t dev, uint8_t ch, float *out);
esp_err_t rbamp_read_current_peak (rbamp_handle_t dev, uint8_t ch, float *out);
esp_err_t rbamp_read_power (rbamp_handle_t dev, uint8_t ch, float *out);
esp_err_t rbamp_read_power_factor (rbamp_handle_t dev, uint8_t ch, float *out);
esp_err_t rbamp_read_frequency (rbamp_handle_t dev, float *out);
| Función | Valor de retorno | Notas |
|---|---|---|
rbamp_read_voltage |
Tensión RMS, V | phase = 0 en la línea BASIC |
rbamp_read_voltage_peak |
Tensión de pico, V | Lee 0 en el módulo STD con mapa 0x34 o anterior: use max_u / min_u de un banco de instantáneas |
rbamp_read_current |
Corriente RMS del canal, A | ch < rbamp_channels(dev); los canales 3 y siguientes (UI5 / UI7) se dirigen por la ventana de canales de forma transparente |
rbamp_read_current_peak |
Pico de corriente en el canal, A | Lee 0 en el módulo STD con mapa 0x34 o anterior: use max_i de un banco de instantáneas |
rbamp_read_power |
Potencia activa, W (con signo) | Negativo = exportación (instalaciones fotovoltaicas / bidireccionales) |
rbamp_read_power_factor |
Factor de potencia | Adimensional, de −1 a +1 |
rbamp_read_frequency |
Frecuencia de red, Hz | 50.0 o 60.0 en una red sana. STD: un valor 0 del módulo (sin red) devuelve ESP_ERR_INVALID_RESPONSE con *out = NaN |
Si ch o phase están fuera de rango, devuelve ESP_ERR_INVALID_ARG.
Lectura única de todo el bloque RT
Referencia de registros RT (realtime-polling) · Sondeo: un solo módulo (realtime-polling) · 4.10 Bloque en tiempo real V03 (0x86..0xBD) (api-reference)
esp_err_t rbamp_read_all(rbamp_handle_t dev, rbamp_snapshot_t *out);
Equivale a llamadas secuenciales a rbamp_read_voltage + rbamp_read_voltage_peak + rbamp_read_current(0..N) + rbamp_read_current_peak(0..N) + rbamp_read_power(0..N) + rbamp_read_power_factor(0..N) + rbamp_read_frequency. Los canales no utilizados (más allá de rbamp_channels(dev)) se rellenan con ceros.
En un módulo con más de tres canales (UI5 / UI7) solo se leen los canales 0–2 en la estructura (RBAMP_SNAPSHOT_CHANNELS = 3); los canales 3 y siguientes no se tocan: léalos con rbamp_read_channel() / rbamp_read_all_channels(). En la línea STD, el bloque de tensión y cada bloque de canal se leen completos (una transacción cada uno).
Un campo que supera su límite de cordura no hace fallar la llamada: se fija en NaN y se marca en snap.implausible, y la llamada sigue devolviendo ESP_OK (véase rbamp_snapshot_t).
Devuelve: ESP_OK en caso de éxito (compruebe implausible); en otro caso, el primer error de transporte subyacente; en ese caso el contenido de out es parcial y no debe usarse.
Potencia reactiva y aparente
esp_err_t rbamp_read_reactive_power(rbamp_handle_t dev, uint8_t ch, float *out);
esp_err_t rbamp_read_apparent_power(rbamp_handle_t dev, uint8_t ch, float *out);
Potencia reactiva del canal ch en var (con signo) y potencia aparente en VA. Estas magnitudes solo existen en la línea STD; en BASIC, esta biblioteca no expone la potencia reactiva, y en un manejador BASIC ambas devuelven ESP_ERR_NOT_SUPPORTED.
Acceso a canales (canales 3 y superiores)
Corriente multicanal (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.14 Ventana de acceso a canales (0x32 + 0x3C..0x3F) (api-reference)
Los canales 0–2 viven en el bloque RT plano. En los SKU mayores (UI5 / UI7) los canales 3 y siguientes solo son accesibles mediante la ventana de canales del módulo. La biblioteca lo gestiona de forma transparente: rbamp_read_current(), rbamp_read_current_peak(), rbamp_read_power() y rbamp_read_power_factor() aceptan cualquier ch en 0..rbamp_channels(dev)-1 y dirigen los canales 3 y siguientes por la ventana. La selección de ventana es un recurso único compartido dentro del módulo, y la selección más la lectura forman una sección atómica: no comparta un manejador entre tareas sin su propio mutex.
esp_err_t rbamp_read_channel (rbamp_handle_t dev, uint8_t ch,
rbamp_channel_reading_t *out);
esp_err_t rbamp_read_all_channels(rbamp_handle_t dev,
rbamp_channel_reading_t *out, uint8_t n);
-
rbamp_read_channellee los cuatro campos RT de un canal en unrbamp_channel_reading_t. Un campo que supera su límite de coherencia esNaN, con su bitRBAMP_FIELD_*activo enimplausible. -
rbamp_read_all_channelsrellenaout[]con todos los canales cargados;nes la capacidad deout(dimensiónelo conRBAMP_MAX_CHANNELS); la llamada rellenamin(n, rbamp_channels(dev))entradas.
Devuelve: ESP_OK (compruebe implausible); ESP_ERR_INVALID_ARG ante un canal incorrecto o NULL; en otro caso, el primer error de transporte.
Son valores en vivo e instantáneos. Un barrido por canales lee ventanas de publicación adyacentes y no es una instantánea simultánea; para energía alineada entre canales, use la ruta de periodo.
rbamp_read_all() en un UI5 / UI7 devuelve los tres primeros canales (RBAMP_SNAPSHOT_CHANNELS = 3) y deja el resto sin tocar; snap.channels sigue informando del número real de canales del módulo.
rbamp_read_commit_seq
esp_err_t rbamp_read_commit_seq(rbamp_handle_t dev, uint8_t *out);
Lee el byte de secuencia del resumen: un uint8_t que se incrementa una vez por ventana de medición (cada 100 ms en el firmware actual, cada 200 ms en imágenes anteriores a v1.2; vuelve de 255 a 0). Léalo antes y después de un barrido de varios registros: un valor sin cambios demuestra que todas las lecturas proceden de una misma confirmación. El resumen no lleva CRC.
Datos listos (DRDY)
01 · Conexión de hardware (hardware-connection) · 03 · Sondeo en tiempo real (realtime-polling) · Sondeo — módulo único (realtime-polling)
DRDYsalida: ALTO en reposo (pull-up del maestro), un pulso de BAJO de ~10 µs cada vez que se publica una instantánea de medición completa (cada 100 ms en toda la familia; imágenes BASIC anteriores a v1.2 e imágenes STD hasta 0x7B: 200 ms). Varios módulos pueden compartir una línea OR cableada. Los módulos BASIC también mantienen la línea firmemente en BAJO mientras hay un evento sin enmascarar pendiente (alarma).
La biblioteca convierte el pulso en una señal de activación para que un lector nunca lea dos veces la misma instantánea, nunca cruce una publicación y sepa cuántas instantáneas se perdieron. En los módulos STD, el contador de publicación indica qué módulo pulsó en una línea compartida. Sin cable DRDY las mismas llamadas funcionan por sondeo del contador del módulo cada CONFIG_RBAMP_DRDY_POLL_MS. Los módulos STD anteriores a la imagen 0x00010075 manejan el pin de otra forma: la biblioteca los trata como si no tuvieran línea DRDY y sondea.
esp_err_t rbamp_set_drdy_gpio (rbamp_handle_t dev, int gpio);
esp_err_t rbamp_wait_data_ready(rbamp_handle_t dev, uint32_t timeout_ms,
rbamp_drdy_event_t *ev);
esp_err_t rbamp_read_all_ready (rbamp_handle_t dev, uint32_t timeout_ms,
rbamp_snapshot_t *out, rbamp_drdy_event_t *ev);
esp_err_t rbamp_read_data_seq (rbamp_handle_t dev, uint16_t *out);
| Función | Descripción |
|---|---|
rbamp_set_drdy_gpio(dev, gpio) |
Conecte la línea DRDY de este módulo, o desconéctela con -1. El GPIO se configura como entrada con pull-up e interrupción por flanco de bajada; varios manejadores pueden compartir un mismo GPIO. Llámela después de rbamp_begin() (el contrato eléctrico de la línea depende del módulo detectado). Devuelve ESP_ERR_NO_MEM si hay más de 4 líneas distintas u 8 manejadores por línea en uso. |
rbamp_wait_data_ready(dev, timeout_ms, ev) |
Bloquea hasta que el módulo publique una instantánea más reciente que la última que devolvió esta llamada (o la última leída mediante rbamp_read_all_ready), como máximo timeout_ms. ev puede ser NULL. |
rbamp_read_all_ready(dev, timeout_ms, out, ev) |
rbamp_wait_data_ready() seguido de rbamp_read_all(): una lectura coherente por cada instantánea publicada, nunca la misma instantánea dos veces. |
rbamp_read_data_seq(dev, &seq) |
La secuencia de instantáneas actual sin esperar. |
Cómo funciona la espera con una línea DRDY. Se activa con el flanco de bajada y comprueba que la secuencia del módulo ha avanzado (un pulso en una línea compartida puede pertenecer a otro módulo; en ese caso la llamada sigue esperando). Si la línea sigue en BAJO 5 ms después del flanco, hay un evento sin enmascarar pendiente en algún módulo de la línea: se leen y limpian los indicadores de todos los módulos conectados a ella (escritura de 1 para borrar, lo que libera la línea; una línea retenida ocultaría los pulsos de los otros módulos). Los indicadores de este módulo llegan en ev con alarm activo; los de los otros módulos se entregan a sus propios manejadores y se notifican en su siguiente espera.
Devuelve (rbamp_wait_data_ready): ESP_OK (instantánea nueva); ESP_ERR_TIMEOUT; ESP_ERR_NOT_SUPPORTED en módulos STD sin contador de publicación (versión del mapa de registros inferior a 0x36).
rbamp_set_drdy_gpio(dev, GPIO_NUM_4);
while (1) {
rbamp_snapshot_t s;
rbamp_drdy_event_t ev;
if (rbamp_read_all_ready(dev, 500, &s, &ev) == ESP_OK) {
if (ev.missed) ESP_LOGW(TAG, "missed %u snapshot(s)", ev.missed);
/* use s — exactly one read per published snapshot */
}
}
Digest BASIC
4.9 Ventana de digest (0x70..0x85) (api-reference) · 8.7 Ida y vuelta de DIGEST: configurar y leer (api-reference)
El digest es un bloque compacto que un módulo BASIC publica con cada ventana. Permite al master leer el resultado de la ventana en una transacción I²C en lugar de una por campo.
esp_err_t rbamp_set_digest_fields(rbamp_handle_t dev, uint8_t fields);
esp_err_t rbamp_read_digest (rbamp_handle_t dev, rbamp_digest_t *out);
-
rbamp_set_digest_fields(dev, fields)elige los campos que el módulo empaqueta en el digest: un OR deRBAMP_DIGEST_I,_U,_P,_PF(no 0). El valor por defecto si nunca se llama es corriente + potencia activa, más tensión en módulos con detección de tensión. La elección se escribe en el módulo en la siguienterbamp_read_digest()(o de inmediato, si el manejador ya está iniciado en un módulo BASIC con la capacidad de digest). El módulo la guarda solo en RAM, así que la biblioteca la vuelve a escribir tras un reinicio detectado del módulo. DevuelveESP_ERR_INVALID_ARGpara 0, para bits desconocidos, o cuando el módulo rechaza un campo que no tiene (tensión en un módulo de solo corriente);ESP_ERR_NOT_SUPPORTEDen la línea STD o en firmware sin la capacidad de digest. -
rbamp_read_digest(dev, &d)lee el estado, la secuencia de ventana y los campos elegidos para los canales 0–2 en una sola transacción. Está pensado para leer cada ventana publicada en DRDY:rbamp_wait_data_ready()y despuésrbamp_read_digest()da la potencia activa con signo de cada ventana con unos pocos bytes de bus. Los canales 3 y siguientes no están en el digest (userbamp_read_channel()). La potencia activa se expresa en vatios enteros: una carga por debajo de 1 W lee 0. DevuelveESP_OK;ESP_ERR_NOT_SUPPORTEDen la línea STD o en firmware BASIC sin la capacidad de digest; errores de transporte.
Contabilidad por periodo
Vea 01 · Visión general para el panorama completo y el Paso 5 de 05 · Inicio rápido para una plantilla mínima.
rbamp_latch_period
esp_err_t rbamp_latch_period(rbamp_handle_t dev);
Escribe CMD_LATCH_PERIOD (0x27) en REG_COMMAND. No espera: el llamador debe dejar 50 ms de asentamiento y comprobar rbamp_is_period_valid() antes de leer.
En la mayoría de los casos, use rbamp_read_period_snapshot(): encapsula toda la secuencia.
rbamp_is_period_valid
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)
esp_err_t rbamp_is_period_valid(rbamp_handle_t dev, bool *out);
Lee el indicador de instantánea lista. *out = true si la última instantánea es reciente.
rbamp_read_period_avg_power
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)
esp_err_t rbamp_read_period_avg_power(rbamp_handle_t dev,
uint8_t ch, float *out);
Potencia activa media en el canal durante el período de la instantánea. Debe llamarse después de rbamp_latch_period() + una espera de 50 ms + una comprobación de validez.
rbamp_read_period_max_power
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)
esp_err_t rbamp_read_period_max_power(rbamp_handle_t dev, float *out);
Potencia instantánea de pico en el canal 0 durante el periodo de la instantánea. ch=0 solo en firmware v1.
rbamp_read_period_latch_ms
13. Deriva del reloj entre módulos en pruebas largas (troubleshooting) · 4.13 dt de diagnóstico en el chip (0xEC) (api-reference)
esp_err_t rbamp_read_period_latch_ms(rbamp_handle_t dev, uint32_t *out);
La duración del periodo tal como la ve el dispositivo, en ms.
El tiempo que informa el módulo puede leerse corto bajo carga. Para la integración de energía use master_dt_ms (o module_window_ms) de rbamp_period_snapshot_t, no este campo.
rbamp_read_period_snapshot
Ciclo de sondeo continuo (recomendado) (period-metering) · Multimódulo — instantánea simultánea (period-metering) · Calibración y precisión (troubleshooting)
esp_err_t rbamp_read_period_snapshot(rbamp_handle_t dev,
rbamp_period_snapshot_t *out,
uint16_t settle_ms,
bool skip_latch);
El punto de entrada recomendado para la contabilidad por periodo. La secuencia completa por dentro:
-
Si
skip_latch == true: se omite la escritura de LATCH (se usa tras una serie manual de comandos de instantánea o una instantánea de difusión para la sincronización de varios módulos). -
En otro caso, escriba
CMD_LATCH_PERIOD. - Capture
esp_timer_get_time()para calcularmaster_dt_ms. vTaskDelay(pdMS_TO_TICKS(settle_ms))— 50 ms por defecto.-
Compruebe el indicador de instantánea lista. Si es 0, establezca
ESP_ERR_INVALID_RESPONSEy registre la marca de tiempo (para que la siguiente instantánea no dupliquedt). -
Lea
avg_p[0..channels-1]+max_p+latch_ms. - Actualice la marca de tiempo y ejecute el integrador de energía para todos los canales (si el componente no se compiló con
CONFIG_RBAMP_DISABLE_ENERGY).
| Parámetro | Descripción |
|---|---|
out |
Estructura de salida. |
settle_ms |
Espere tras la instantánea (se recomiendan 50). |
skip_latch |
Si es true: no escriba LATCH, solo lea (para el patrón de varios módulos). |
Devuelve: ESP_OK si out->valid == true; ESP_ERR_INVALID_RESPONSE si la instantánea está desactualizada (en ese caso la energía no se integra y se mantiene el ancla); ESP_ERR_NOT_SUPPORTED en un módulo STD que no ofrece bancos de instantáneas ni contadores; en otro caso, el esp_err_t de las operaciones de bus. Véase Llamadas de periodo en la línea STD para el comportamiento STD.
La energía se integra sobre master_dt_ms: la ventana propia del maestro entre lecturas consumidas sucesivas. Tras rbamp_begin_resume(), la primera instantánea consumida integra sobre la ventana propia del módulo.
Entre llamadas de instantánea: 60 s es cómodo, 30 s es marginal, y menos de 10 s garantiza lecturas caducadas. El firmware integra el acumulador periódico internamente; llamar a rbamp_read_period_snapshot() más a menudo de lo que el firmware puede preparar el siguiente periodo devolverá siempre una instantánea caducada (ESP_ERR_INVALID_RESPONSE). Para telemetría de alta frecuencia use las funciones RT rbamp_read_power(ch) / rbamp_read_all(): se refrescan a unos 10 Hz.
rbamp_read_uptime_s
Detección de reinicio del módulo (period-metering) · 4.6 Salud / diagnósticos (0x46..0x4F) (api-reference)
esp_err_t rbamp_read_uptime_s(rbamp_handle_t dev, uint32_t *out);
Segundos desde el arranque del módulo. Un valor que disminuye entre dos lecturas significa que el módulo se reinició. En firmware BASIC que no publica el tiempo de funcionamiento, devuelve 0.
Llamadas de período en la línea STD
La misma API de período sirve a ambas líneas, pero lo que ocurre por debajo depende de lo que ofrezca el módulo STD (rbamp_std_info_t.period_source, decidido por rbamp_begin()):
period_source |
Comportamiento de rbamp_read_period_snapshot() |
|---|---|
RBAMP_STD_PERIOD_LATCH |
El módulo tiene bancos de instantáneas. La biblioteca usa el banco 0 (armado por rbamp_begin()): enclava, espera al menos 300 ms aunque settle_ms sea menor (el módulo toma la instantánea en su siguiente límite de ventana de medición), lee el banco y lo convierte en energía sobre master_dt_ms. Con skip_latch el llamador controla los tiempos: enclave, espere ≥ 300 ms y lea. Mantenga el bit 0 activo en rbamp_std_arm_banks(). |
RBAMP_STD_PERIOD_COUNTERS |
Sin bancos de instantáneas, pero con contadores de vida persistentes. No se envía ningún enclavamiento y settle_ms / skip_latch se ignoran: la llamada lee los contadores e informa de la diferencia desde la lectura consumida anterior en avg_p_total / wh_net. No se pierde nada tras un reinicio del módulo (module_restarted lo indica). |
RBAMP_STD_PERIOD_NONE |
Ninguna. Las llamadas de período devuelven ESP_ERR_NOT_SUPPORTED en lugar de informar en silencio de un período no válido. |
Para la ruta de contadores: avg_p[] contiene el periodo de un módulo de un solo canal, las diferencias de contadores por canal en módulos que publican contadores por canal, y NaN en módulos multicanal que no lo hacen; max_p es NaN. En módulos de contadores sin contadores de grano fino, elija un periodo lo bastante largo para que un paso del contador sea una fracción pequeña de él (minutos, no segundos). ESP_ERR_INVALID_RESPONSE reancla la biblioteca (ese periodo se descarta) cuando cambió el contador de generación del módulo (sus contadores se reiniciaron o se adoptaron) o un contador retrocedió.
Otras notas de STD: rbamp_latch_period() enclava el banco 0 (sin operación que devuelve ESP_OK en módulos de contadores); rbamp_is_period_valid() es true en módulos de contadores una vez que la biblioteca tiene un ancla de contador (siempre tras rbamp_begin()); rbamp_read_period_avg_power() devuelve el promedio del último periodo consumido para módulos de contadores de un solo canal y ESP_ERR_NOT_SUPPORTED en los multicanal; rbamp_read_period_max_power() devuelve ESP_ERR_NOT_SUPPORTED en módulos de contadores; rbamp_read_period_snapshot() devuelve ESP_ERR_INVALID_RESPONSE cuando el banco 0 no informa de ventana transcurrida — si un reinicio del módulo borró la máscara de armado del banco, la biblioteca vuelve a armar el banco 0, toma una instantánea de cebado y reinicia el ancla del reloj (esa ventana no se integra; la siguiente vuelve a ser completa).
Función auxiliar en línea
static inline esp_err_t
rbamp_read_period_snapshot_simple(rbamp_handle_t dev,
rbamp_period_snapshot_t *out);
Un envoltorio de conveniencia para los argumentos por defecto: settle_ms=50, skip_latch=false. Úselo para el sondeo periódico habitual.
Contabilidad de energía (acumulador del lado del master)
Algoritmo en el lado del maestro (period-metering) · 7 · Semántica (api-reference)
Si el componente se compila sin CONFIG_RBAMP_DISABLE_ENERGY=y, hay funciones de acceso para el acumulador de Wh dentro del manejador:
double rbamp_energy_wh (rbamp_handle_t dev, uint8_t ch);
void rbamp_energy_reset (rbamp_handle_t dev, uint8_t ch);
void rbamp_energy_reset_all (rbamp_handle_t dev);
void rbamp_energy_disable (rbamp_handle_t dev);
void rbamp_energy_enable (rbamp_handle_t dev);
El acumulador se actualiza automáticamente en cada rbamp_read_period_snapshot() correcta. Tiene signo: un valor negativo significa exportación neta.
| Función | Descripción |
|---|---|
rbamp_energy_wh(dev, ch) |
Total de Wh actual del canal. Si ch está fuera de rango: 0.0. |
rbamp_energy_reset(dev, ch) |
Pone a cero un único canal. |
rbamp_energy_reset_all(dev) |
Pone a cero todos los canales. |
rbamp_energy_disable(dev) |
Desactiva la integración automática. Útil cuando el maestro lleva su propia persistencia de Wh (suspensión profunda — véase 06 · Ejemplos, escenario 9). |
rbamp_energy_enable(dev) |
Vuelve a activar la integración automática. |
rbamp_energy_wh() acepta un índice de canal (0..rbamp_channels(dev)-1, hasta 6 en un UI7) o el selector RBAMP_ENERGY_CH_TOTAL (0xFF) para el total de todos los canales. El valor tiene signo (negativo significa exportación neta) y es 0 si ch está fuera de rango o la energía está desactivada.
Módulos STD sin bancos de instantáneas (vía de contadores): el total es la suma de las diferencias de los contadores propios del módulo: exacto, nada se integra en el host. Los valores por canal proceden de los contadores por canal del módulo cuando los publica; son NaN en módulos multicanal que no los publican, e igualan al total en módulos de un solo canal.
Fórmula de integración:
wh[ch] += snap.avg_p[ch] × master_dt_ms / 1000 / 3600
[W] [milliseconds] → [Wh]
Al compilar con CONFIG_RBAMP_DISABLE_ENERGY=y, tanto las funciones (prototipos y almacenamiento) se eliminan del binario mediante guardas #if: un intento de llamar a rbamp_energy_wh() produce un error del enlazador «unresolved external».
El tipo del acumulador (rbamp_energy.h)
El acumulador que hay tras el manejador vive en una cabecera aparte, rbamp_energy.h. La cabecera lo describe como una API interna: la aplicación normalmente usa los envoltorios rbamp_energy_* de arriba y nunca necesita este. Se lista aquí porque sus símbolos son visibles:
typedef struct {
double wh[RBAMP_ENERGY_MAX_CH]; /* per-channel running total, Wh (signed) */
double wh_total; /* all-channel total, Wh (signed) */
bool enabled; /* false: tick() is a no-op */
} rbamp_energy_t;
void rbamp_energy_init (rbamp_energy_t *e);
void rbamp_energy_tick (rbamp_energy_t *e, const float avg_p[], uint8_t channels,
uint32_t period_ms, bool valid);
double rbamp_energy_wh_get (const rbamp_energy_t *e, uint8_t ch);
void rbamp_energy_add_wh (rbamp_energy_t *e, uint8_t ch, double wh);
void rbamp_energy_reset_ch (rbamp_energy_t *e, uint8_t ch);
void rbamp_energy_reset_all_ch(rbamp_energy_t *e);
static inline void rbamp_energy_set_enabled(rbamp_energy_t *e, bool en);
| Función | Descripción |
|---|---|
rbamp_energy_init |
Ponga los contadores a cero; el acumulador arranca habilitado. |
rbamp_energy_tick |
Integre un período: wh[ch] += avg_p[ch] × period_ms / 1000 / 3600 para hasta RBAMP_ENERGY_MAX_CH (7) canales. Se omite en silencio si valid es false, si period_ms es 0 o si el acumulador está desactivado. period_ms debe ser la ventana de reloj de pared del master (master_dt_ms), no el latch_ms del módulo. |
rbamp_energy_wh_get |
Total acumulado de un canal; 0 si está fuera de rango. |
rbamp_energy_add_wh |
Añade una cantidad ya medida (Wh, con signo) a un canal o, con RBAMP_ENERGY_CH_TOTAL, al total de todos los canales. Se usa cuando el módulo publica por sí mismo contadores de energía. Sin efecto mientras esté desactivado. |
rbamp_energy_reset_ch / rbamp_energy_reset_all_ch |
Pone a cero un canal / todos los canales. |
rbamp_energy_set_enabled |
Active o desactive la integración. Mientras está desactivada, tick() y add_wh() no hacen nada y las lecturas siguen devolviendo el valor congelado. |
Identificación y aprovisionamiento
Estas funciones permiten al master saber exactamente qué está conectado al bus (variante, mapa de bits de capacidades, UID) y preparar un módulo nuevo o recién grabado para su funcionamiento (aprovisionamiento y guardado de la configuración en flash).
rbamp_read_variant
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)
esp_err_t rbamp_read_variant(rbamp_handle_t dev, rbamp_variant_t *out);
Lee el registro de variante y lo traduce al enum rbamp_variant_t (RBAMP_VARIANT_UI1 / _I1 / _I2 / _I3, _UI5, _UI7, ...; se traduce todo código conocido). Para la compatibilidad con código antiguo que lee el byte «en bruto», puede convertirlo de nuevo a uint8_t. El valor cacheado por rbamp_begin() está disponible sin tráfico en el bus como rbamp_variant(). Valores:
| Código | SKU | Canales I | Canal U |
|---|---|---|---|
1 |
UI1 | 1 | sí |
2 |
UI2 | 2 | sí |
3 |
UI3 | 3 | sí |
4 |
I1 | 1 | no |
5 |
I2 | 2 | no |
6 |
I3 | 3 | no |
7 |
UI5 | 5 | sí |
8 |
UI7 | 7 | sí |
El valor es de solo lectura, almacenado en ROM, y solo cambia al volver a grabar el firmware en fábrica.
rbamp_read_capability
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)
esp_err_t rbamp_read_capability(rbamp_handle_t dev, uint16_t *out);
Lee el mapa de funciones de los registros CAPABILITY (0x57/0x58), LE u16. Un indicador señala la presencia de la etapa de tensión: si está desactivado, el módulo no calcula P / PF / Q y los valores de esos registros son 0.0f. Vea la sección «CAPABILITY (0x57/0x58, u16 LE): mapa de detección de funciones» más abajo.
rbamp_has_voltage
bool rbamp_has_voltage(rbamp_handle_t dev);
Una función auxiliar sobre rbamp_read_capability — devuelve true si el módulo tiene un canal U (es decir, (cap >> 8) & 1). Se guarda en caché en el manejador en la primera llamada; las siguientes no realizan ninguna operación I²C.
rbamp_read_product_id
3.5 PRODUCT_ID (0x54, u8, solo lectura) (api-reference) · 4.8 Identidad (0x54..0x6F) (api-reference)
esp_err_t rbamp_read_product_id(rbamp_handle_t dev, uint8_t *out);
Lee PRODUCT_ID (0x54): un identificador de byte de la familia (rbAmp = 0x01). 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 responde en esa misma dirección.
rbamp_read_uid
esp_err_t rbamp_read_uid(rbamp_handle_t dev, uint8_t uid[12]);
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 por módulo y no cambia al volver a grabar el firmware: práctico para registros en serie, comprobaciones anticlonado en el lado del maestro y para identificar un módulo al sustituirlo en una flota desplegada.
rbamp_is_provisioned
esp_err_t rbamp_is_provisioned(rbamp_handle_t dev, bool *out);
Comprueba si el módulo ha pasado por el aprovisionamiento inicial. Técnicamente comprueba REG_ERROR != 0xFB (ERR_FLASH_PARAMS_BAD) en un módulo recién arrancado: 0xFB lo fija el firmware cuando el bloque de configuración de usuario está vacío o corrupto. Un módulo recién salido de fábrica devuelve false: necesita rbamp_save_user_config (o aprovisionamiento mediante la flota) tras la primera configuración del modelo de CT y de la dirección.
En v1.3 este código es normal en un módulo virgen (no es fatal). No aborte el aprovisionamiento por la primera aparición de 0xFB.
Línea STD. Devuelve true cuando el módulo informa de que su página de calibración es válida. Es fiable desde la versión de imagen de módulo 0x00010079; las imágenes anteriores también activan el bit con las ganancias de fábrica, así que «aprovisionado» no puede distinguirse de «sin calibrar» mediante esta llamada (use en su lugar la fuente de calibración de rbamp_std_read_health()). Desde la versión de imagen de módulo 0x0001007A, el bit procede de un marcador que escribe el módulo al guardar la calibración: una unidad calibrada con firmware anterior devuelve false tras la actualización hasta que se ejecute un rbamp_save_gains() en ella (su calibración en sí permanece intacta).
rbamp_save_user_config
6.5 Aprovisionamiento: firmware nuevo + GUARDADO (api-reference) · 8.6 Aprovisionamiento con firmware nuevo (api-reference)
esp_err_t rbamp_save_user_config(rbamp_handle_t dev);
Emite CMD_SAVE_USER_CONFIG (código 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 (ganancia, NF, fase): esos van con CMD_SAVE_GAINS, que está bloqueado en modo de producción.
Bloquea el hilo unos ~700 ms (ciclo de borrado y escritura en flash). Durante la llamada, no intente acceder al módulo desde otras tareas.
Returns:
ESP_OK— configuración guardada, sobrevive a un corte de alimentación.-
ESP_ERR_TIMEOUT: el módulo no respondió a tiempo; es posible que la alimentación cayera durante el ciclo de escritura en flash. Vuelva a verificar con un reinicio y relectura. -
ESP_FAIL— el módulo devolvióREG_ERROR != OKtras el comando. Consulterbamp_read_last_errorpara ver los detalles.
: confirmar que un valor se escribió en flash requiere un reinicio + relectura. Vea la sección Modelo de errores v1.3 más abajo y 03 · Selección del sensor de corriente.
rbamp_read_active_address
esp_err_t rbamp_read_active_address(rbamp_handle_t dev, uint8_t *out);
Lee la dirección I²C activa del módulo. En el arranque este registro es fiable: lee la dirección activa en flash (un módulo redirigido lee su nueva dirección). Tras preparar un candidato con rbamp_prepare_address_change(), repite el candidato hasta la confirmación + reinicio. Sirve para verificar un cambio de dirección en dos fases tras el reinicio posterior a la confirmación. En la línea STD lee la dirección persistida (se aplica en el siguiente reinicio).
Modelo de errores v1.3
Los errores tienen dos canales independientes que funcionan de forma distinta. 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 interna del componente (biblioteca) | REG_ERROR (0x02) + EVENT_FLAGS.bit3 (0x2A) |
| Cuándo se dispara | Antes de la transacción I²C (la biblioteca la intercepta) | Tras aceptar el firmware una escritura y rechazarla |
| Lo que ve el maestro | ESP_ERR_INVALID_ARG desde el setter; REG_ERROR permanece en 0x00 |
REG_ERROR = el código de rechazo inmediato; bit3 se activa unos pocos cientos de milisegundos después de la transacción |
| Persistente | no (solo un código de retorno) | Última escritura de REG_ERROR; bit3 pegajoso W1C |
| Ruta típica | Argumento fuera de los límites permitidos (canal ≥ rbamp_channels(dev), una clase desconocida, ...) |
Escritura de registro en bruto que el componente no valida previamente (una escritura de bajo nivel personalizada); un modelo de CT desconocido, que el propio módulo rechaza |
Canal A — validación en el cliente (setters del componente)
Todos los setters del componente (rbamp_set_sensor_class, rbamp_set_ct_model_ch, rbamp_configure_channels, etc.) comprueban primero los argumentos contra los valores permitidos. Si un argumento está fuera de rango, el setter devuelve ESP_ERR_INVALID_ARG sin realizar ninguna transacción I²C. Por tanto, REG_ERROR en el dispositivo no se toca:
esp_err_t err = rbamp_set_ct_model_ch(dev, /*channel=*/99, /*code=*/3);
/* err == ESP_ERR_INVALID_ARG (lib client-side validation) */
uint8_t reg_err;
rbamp_read_last_error(dev, ®_err);
/* reg_err == 0x00 — REG_ERROR untouched, lib intercepted before I²C */
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 más la comprobación de su propio argumento. REG_ERROR no le dirá nada en este escenario (la siguiente transacción correcta lo pondrá a cero).
Canal B: rechazo en el lado del DUT (asíncrono duradero)
Si una escritura llegó por I²C (la biblioteca no la interceptó porque el argumento parecía válido), pero el firmware la rechazó, entra en juego el segundo canal:
-
REG_ERROR (0x02)contiene de inmediato el código de motivo (por ejemplo,0xFE = ERR_PARAM). Es el resultado de la última escritura: cualquier escritura posterior correcta lo sobrescribe. Debe leerlo justo después de su propia escritura, antes de cualquier otra transacción. -
EVENT_FLAGS.bit3(rbamp_has_error) — sticky de escritura-1-para-borrar. No se activa al instante: en el banco se midió un retraso de unos pocos cientos de milisegundos entre la transacción rechazada y la activación de bit3. Justo después de la escritura bit3 sigue en0; tras 300 ms vale1. Después,bit3se mantiene en cualquier número de lecturas.
Salida de banco (escritura en bruto DIGEST_CONFIG = 0xFF):
raw write 0x29=0xFF → read_last_error → REG_ERROR=0xFE (immediate)
has_error(bit3): immediate=0, +300 ms poll#1=1, poll#2=1
⚠ No use has_error para validar una escritura que acaba de hacer. Para conocer el resultado de esa escritura concreta, solo es fiable rbamp_read_last_error leído inmediatamente después de la escritura, antes de cualquier otra transacción (además del código de retorno del setter, si lo tiene). has_error 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 vuelve a activar el firmware cada pocos cientos de milisegundos a partir del estado actual de REG_ERROR. Por tanto, un clear_event_flags(1<<3) simple no funcionará: bit3 vuelve a activarse de inmediato desde el REG_ERROR que aún no se ha borrado:
state: REG_ERROR=0xFE, bit3=1
clear_event_flags(1<<3) → bit3=1 still (re-latched from REG_ERROR=0xFE)
clear_error + clear_event_flags(1<<3)
→ bit3=0 (cleared cleanly)
El orden correcto: primero rbamp_clear_error() (borra REG_ERROR) y después rbamp_clear_event_flags(1<<3) (borra el latch persistente). Si quiere atomicidad, no debe haber ninguna escritura rechazada entre ambas.
rbamp_read_last_error
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)
esp_err_t rbamp_read_last_error(rbamp_handle_t dev, uint8_t *out);
Lee REG_ERROR (0x02) directamente: el resultado de la última transacción aceptada correctamente por el bus (una escritura o un comando). No es persistente: cualquier escritura correcta posterior lo sobrescribe con su propio resultado.
Se usa en el canal B (rechazo del lado del DUT) para el código de motivo ampliado.
rbamp_has_error
esp_err_t rbamp_has_error(rbamp_handle_t dev, bool *out);
Función auxiliar de conveniencia sobre EVENT_FLAGS.bit3 (ERROR_OCCURRED, registro 0x2A). Devuelve true si bit3 está activo. Es persistente (W1C): no se borra hasta un borrado explícito (con una salvedad: vea la sección «Borrado de un error duradero» más arriba).
Se usa para la monitorización por sondeo de «si algo falló»: por ejemplo, en bucles de larga duración donde escrituras intermedias pudieron sobrescribir REG_ERROR, pero bit3 conserva el hecho de que al menos una fue rechazada.
rbamp_read_event_flags / rbamp_clear_event_flags
8.8 Flujo de eventos de umbral: escribir umbral → disparo → borrado W1C (api-reference)
esp_err_t rbamp_read_event_flags(rbamp_handle_t dev, uint8_t *out);
esp_err_t rbamp_clear_event_flags(rbamp_handle_t dev, uint8_t mask);
EVENT_FLAGS (0x2A): un byte de indicadores persistentes (RBAMP_EVENT_*, vea Bits de evento, incluido RBAMP_EVENT_ERROR = bit3). El borrado es escribir 1 para borrar: escriba una máscara con unos en los bits que quiera poner a cero. Los indicadores funcionan en ambas líneas; en la línea STD necesitan la versión de mapa de registros 0x36 o posterior (ESP_ERR_NOT_SUPPORTED por debajo).
Ayuda a separar causas: puede leer primero todos los indicadores y poner a cero solo los atendidos, dejando los no atendidos para el siguiente ciclo de sondeo.
rbamp_clear_error
Códigos de error (REG_ERROR = 0x02) (troubleshooting) · 6.7 Recuperación del estado de error: árbol de decisión (api-reference)
esp_err_t rbamp_clear_error(rbamp_handle_t dev);
Emite CMD_CLEAR_ERROR (código 0x31): pone a cero REG_ERROR. Es necesario para borrar un error persistente junto con clear_event_flags(1<<3) (véase más arriba). Sin clear_error, un simple clear_event_flags(1<<3) dejará bit3 en 1 tras unos cientos de milisegundos por el rearmado.
Eventos y línea de alarma
4.4 Configuración de flota (0x27..0x2F) (api-reference) · 8.8 Flujo de eventos de umbral: escribir umbral → disparo → borrado W1C (api-reference)
Los eventos son un único modelo en ambas líneas: indicadores persistentes (RBAMP_EVENT_*), con escritura de 1 para borrar. Los indicadores que además están activos en la máscara de eventos mantienen la línea DRDY en BAJO (una alarma) hasta que se borran o se desenmascaran. La máscara y los umbrales residen en la RAM del módulo: vuelva a armarlos tras cada reinicio del módulo (RBAMP_EVENT_RESET_OCCURRED lo indica; vea también rbamp_begin_event_flags()).
esp_err_t rbamp_read_event_mask (rbamp_handle_t dev, uint8_t *out);
esp_err_t rbamp_set_event_mask (rbamp_handle_t dev, uint8_t mask);
esp_err_t rbamp_set_event_thresholds(rbamp_handle_t dev, float i_amps, float p_watts);
| Función | Descripción |
|---|---|
rbamp_read_event_mask |
Qué indicadores mantienen la línea DRDY en BAJO (la clase de alarma). |
rbamp_set_event_mask |
Establezca la máscara (RAM en el módulo; 0 = la línea nunca se mantiene). La escritura se lee de vuelta y se verifica. |
rbamp_set_event_thresholds |
Fije los umbrales (en RAM del módulo): el canal de corriente más alto por encima de i_amps fija RBAMP_EVENT_THRESH_I, y la potencia activa total por encima de p_watts fija RBAMP_EVENT_THRESH_P. Un valor <= 0 o NaN desactiva ese umbral. Devuelve ESP_ERR_NOT_SUPPORTED en un módulo STD con versión de mapa de registros inferior a 0x36. |
La comparación difiere según la línea. La línea STD compara la potencia total absoluta (el sentido no importa). La línea BASIC compara la suma con signo de las potencias de los canales, así que la exportación nunca activa el umbral de potencia; los valores que no caben en la codificación BASIC se tratan como «desactivado». En STD, rbamp_read_event_flags() necesita la versión 0x36 o posterior del mapa de registros (en otro caso, ESP_ERR_NOT_SUPPORTED).
Configuración multicanal
En los módulos multicanal (I2, I3, UI2, UI3, y los mayores UI5 / UI7), cada canal de corriente tiene su propio modelo de sensor CT. La utilidad atómica para la configuración masiva es rbamp_configure_channels.
rbamp_configure_channels
esp_err_t rbamp_configure_channels(rbamp_handle_t dev,
rbamp_sensor_class_t cls,
const uint8_t *models,
uint8_t n);
Parameters:
cls— la clase de sensor, aplicada antes medianterbamp_set_sensor_class().models: un array dencódigos de modelo de CT, uno por canal.n: la longitud del array. Limitado por variante: sines mayor que el número de canales de esta variante (por ejemplo,n=3enI2), la función lo limita al número real de canales; los elementos extra del array se ignoran. Sines menor que el número de canales, los canales que faltan no se tocan (conservan su modelo anterior). Una entrada0enmodelsomite ese canal. La llamada cubre todos los canales del módulo, incluidos los canales 3 y siguientes de un UI5 / UI7.
Internamente, la función realiza:
set_sensor_class(cls)una vez.-
Para cada canal
k < min(n, n_channels): asociamodels[k]; cada asociación se verifica de forma síncrona y se confirma por relectura. -
Un guardado final de configuración del usuario (más el que va dentro de
set_sensor_class): es decir, dos ciclos de borrado + escritura en flash para toda la configuración, en lugar de1 + n. Es la propiedad «favorable a la flash».
Leer antes de escribir. Toda la solicitud se decide antes de la primera escritura. Una clase o un modelo que el módulo ya tiene no se reescribe, así que reaplicar la misma configuración solo cuesta lecturas y ningún ciclo de flash. En un módulo de clase 2 o 3, una solicitud que cambiaría la clase o cualquiera de los modelos pedidos se rechaza de entrada con ESP_ERR_INVALID_STATE y no se escribe nada. En un módulo de clase 1 con firmware anterior (hasta 1.4.19), una configuración que cambie un modelo termina con un reinicio del módulo (véase rbamp_set_ct_model_ch).
Returns:
ESP_OK— configuración aplicada y guardada.-
ESP_ERR_INVALID_ARG—clsomodels[k]no válidos (validación en el paso de vinculación, véase la sección «Modelo de errores» más arriba). -
ESP_ERR_INVALID_STATE: no se pudo asociar un canal, o el módulo está calibrado con su sensor acoplado (clase 2 / 3). -
Otros códigos de ESP-IDF: error de bus, tiempo límite, etc.
rbamp_read_ct_model_ch
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)
esp_err_t rbamp_read_ct_model_ch(rbamp_handle_t dev,
uint8_t channel,
uint8_t *out);
Lee el modelo de sensor de CT realmente aplicado a un canal concreto (0 = sin fijar). Úselo para verificar la vinculación tras rbamp_set_ct_model_ch(). Los canales 0–2 leen los espejos planos (0x51 / 0x52 / 0x53); los canales 3 y superiores (UI5 / UI7) se leen a través de la ventana de canal. Es una lectura desde RAM, no una confirmación de persistencia: para confirmar un guardado en flash, reinicie y vuelva a leer. En la línea STD lee la entrada de mapa del canal.
Gestor de flota — gestión de varios módulos
La API de flota es la superficie de alto nivel principal de la biblioteca. Gestiona una colección de módulos en un bus I²C compartido: descubrimiento, aprovisionamiento, agregación de sondeos, agregación de errores e instantáneas síncronas.
Todas las funciones de flota son seguras para hilos mediante un mutex interno; las llamadas concurrentes desde distintas tareas se serializan. Un único propietario de fleet desde una tarea, más acceso de solo lectura (por ejemplo, _count, _get) desde otras, es aceptable; coordine explícitamente las operaciones complejas de varios pasos.
Ciclo de vida
esp_err_t rbamp_fleet_create(i2c_master_bus_handle_t bus,
rbamp_fleet_t *out);
void rbamp_fleet_destroy(rbamp_fleet_t fleet);
create recibe un bus y devuelve una flota vacía. destroy libera todos los manejadores gestionados y la propia flota: tras la llamada, los punteros de manejador obtenidos con rbamp_fleet_get son inválidos.
Descubrimiento: rbamp_fleet_scan
Configuración multimódulo (initialization) · Sondeo multimódulo: tres estrategias (realtime-polling) · Problemas multimódulo (troubleshooting)
esp_err_t rbamp_fleet_scan(rbamp_fleet_t fleet,
bool match_product,
size_t *added);
Sondea el bus en el rango 0x08..0x77; 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 el detector de conflictos (dos señales independientes; vea 10 · Solución de problemas, sección «Flota: un módulo acabó en excluded»). Las direcciones sospechosas van a la lista
excluded, no a la flota. -
Realiza un centinela de bloqueo de nivel 2: sondea una dirección en la que debe haber garantizado que no responde nadie. Si el centinela recibe un ACK, devuelve
ESP_ERR_INVALID_STATE— el bus está bloqueado y la flota queda vacía (véanse los diagnósticos en el cap. 10).
Tras el éxito, *added contiene el número de módulos añadidos a la flota. excluded_count (véase más abajo) está disponible mediante un getter aparte.
Salida de banco (validada en HW sobre una flota heterogénea UI1+I2+I3 con resistencias pull-up externas de 4.7 kΩ):
rbamp_fleet_scan() → 3 module(s), 0 excluded
module[0] @0x50 channels=1 voltage=yes (UI1 — mains)
module[1] @0x51 channels=2 voltage=no (I2 — sub-meter)
module[2] @0x52 channels=3 voltage=no (I3 — sub-meter)
rbamp_fleet_count() = 3
rbamp_fleet_excluded_count() = 0
En este escenario, un conflicto de dirección acabaría en la lista de excluidos (excluded_count > 0), y un bus bloqueado acabaría en ESP_ERR_INVALID_STATE con una flota vacía (véase 10 · Solución de problemas).
Acceso al módulo
size_t rbamp_fleet_count(rbamp_fleet_t fleet);
rbamp_handle_t rbamp_fleet_get(rbamp_fleet_t fleet, size_t index);
rbamp_handle_t rbamp_fleet_find(rbamp_fleet_t fleet, uint8_t address);
esp_err_t rbamp_fleet_add(rbamp_fleet_t fleet, rbamp_handle_t dev);
size_t rbamp_fleet_excluded_count(rbamp_fleet_t fleet);
esp_err_t rbamp_fleet_excluded_addr(rbamp_fleet_t fleet,
size_t index,
uint8_t *out);
_get devuelve NULL si está fuera de rango; _find devuelve NULL si la dirección no está en la flota (por ejemplo, porque acabó en los excluidos). _add le permite añadir manualmente un manejador creado por separado (por ejemplo, tras un aprovisionamiento manual).
Sondeo — rbamp_fleet_poll_all
Configuración multimódulo (initialization) · Sondeo multimódulo: tres estrategias (realtime-polling)
esp_err_t rbamp_fleet_poll_all(rbamp_fleet_t fleet,
rbamp_snapshot_t *snaps,
rbamp_fleet_poll_t *status,
size_t capacity,
size_t *n_ok);
Sondea todos los módulos de la flota en una sola llamada. Para cada módulo se realiza una lectura RT completa (rbamp_read_all), y el resultado se adjunta al elemento snaps[i] correspondiente. En paralelo, status[i] recibe el resultado por módulo: ESP_OK, ESP_ERR_TIMEOUT (módulo en silencio), ESP_FAIL (rechazo por coherencia), etc.
Tras el retorno, *n_ok es el número de módulos para los que se obtuvo una instantánea válida (status[i] == ESP_OK).
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 solo módulo (un fallo de cableado, una quemadura) no debe dejar sin monitorización a toda la instalación.
Agregación
esp_err_t rbamp_fleet_total_power(rbamp_fleet_t fleet, float *out_w);
esp_err_t rbamp_fleet_total_energy_wh(rbamp_fleet_t fleet, double *out_wh);
esp_err_t rbamp_fleet_poll_errors(rbamp_fleet_t fleet,
uint32_t *error_mask,
size_t *n_errors);
_total_power suma la potencia activa de todos los canales de todos los módulos. En las variantes I no hay potencia activa → aportan 0. En el despliegue canónico (UI1 de red + submedidores I2/I3) el resultado es la potencia activa del módulo de red.
_total_energy_wh suma igualmente los acumuladores de Wh de los manejadores. También funciona correctamente: las variantes I aportan 0, UI1 aporta la energía de la red.
_poll_errors recorre la flota llamando a rbamp_has_error en cada módulo. *error_mask es una máscara de bits de los módulos marcados con EVENT bit3, por su posición en la flota (válida para los primeros 32 módulos); *n_errors es el total de módulos con indicador de error en el momento del sondeo. Cualquiera de los dos punteros puede pasarse como NULL si no se necesita.
Direccionamiento y comprobación de conflictos
esp_err_t rbamp_fleet_assign_address(rbamp_fleet_t fleet,
rbamp_handle_t dev,
uint8_t new_addr);
esp_err_t rbamp_fleet_check_conflict(rbamp_fleet_t fleet,
uint8_t addr,
bool *collision);
_assign_address reasigna un módulo existente de la flota a una nueva dirección: internamente, confirmación en dos fases + reinicio; el manejador de la flota se actualiza automáticamente (las llamadas posteriores siguen funcionando).
_check_conflict — una comprobación de solo lectura y de mejor esfuerzo para una dirección concreta: llámela una vez por cada dirección de interés. Lee la identidad (PRODUCT_ID / HW_VARIANT / CAPABILITY) y la compara con el estado en caché de la flota. Si se detecta una incoherencia (dos dispositivos respondiendo en la misma dirección con bytes «mezclados»; identidad distinta del estado en caché), *collision = true. Para barrer todas las direcciones conocidas, recorra usted la flota: for i in 0..count, check_conflict(fleet, addr, &col). No garantiza detectar módulos idénticos: véase la disciplina de aprovisionamiento.
Aprovisionamiento — rbamp_provision
6.5 Aprovisionamiento: firmware nuevo + GUARDADO (api-reference)
esp_err_t rbamp_provision(i2c_master_bus_handle_t bus,
uint8_t desired_addr,
bool save_config,
rbamp_handle_t *out);
Aprovisiona exactamente un módulo virgen (en la dirección de fábrica 0x50) con la dirección indicada. Internamente:
-
Comprueba que hay respuesta en
0x50(ESP_ERR_NOT_FOUNDsi no la hay). -
Comprueba que no hay nadie todavía en
desired_addr(ESP_ERR_INVALID_STATEsi está ocupada). -
Realiza una confirmación de dirección en dos fases.
-
Reinicia el módulo y espera a que aparezca en
desired_addrdentro de la ventana de arranque (ESP_ERR_TIMEOUTsi no aparece). -
Crea un manejador; si
save_config = true, llama arbamp_save_user_config(persiste en flash). -
Devuelve el manejador listo mediante
*out.
⚠ OBLIGATORIO: exactamente un 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 se pueden distinguir ni con hardware especial. La garantía recae en el operador, no en la biblioteca. Para la recuperación, véase 10 · Solución de problemas, sección «Flota: rbamp_provision devolvió un error».
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)
esp_err_t rbamp_fleet_enable_gc_all(rbamp_fleet_t fleet,
uint8_t group,
size_t *ok_count);
esp_err_t rbamp_fleet_gclatch(rbamp_fleet_t fleet,
uint8_t group,
uint16_t tick,
uint32_t settle_ms);
esp_err_t rbamp_fleet_check_sync(rbamp_fleet_t fleet,
uint16_t expected_tick,
rbamp_fleet_sync_t *status,
size_t status_cap,
size_t *n_missed);
Para una sincronía estrecha de instantáneas (desfase < 1 ms en toda la flota) se usa una instantánea de difusión I²C General-Call.
-
_enable_gc_allponeFLEET_CONFIG.bit0+GROUP_IDen todos los módulos de la flota y emiteCMD_SAVE_USER_CONFIGen cada uno (de forma persistente). Un reinicio de los módulos es obligatorio tras habilitar: se hace automáticamente. Basta con llamarla una vez durante la configuración inicial de la flota.*ok_count(opcional) es el número de módulos en los que la habilitació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 al instante (LATCH_PERIOD).settle_mses la pausa tras la trama (normalmente 50 ms) antes de la verificación. -
_check_syncleeGC_TICK (0x59)en cada módulo y lo guarda enrbamp_fleet_sync_t status[status_cap]. Resultado por módulo:
typedef struct {
uint8_t addr; /* module I²C address */
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 */
} rbamp_fleet_sync_t;
*n_missed es el número de módulos con in_sync = false (o que simplemente no responden). Si todos están in_sync, n_missed == 0.
No los confunda: el rbamp_broadcast_latch por dispositivo (véase la sección «Bus multimódulo» más abajo) es una trama en todo el bus; la sincronización GC de la flota es la misma trama, pero la API de flota añade además una comprobación de testigo (que haya llegado a todos los módulos esperados). Véase también 04 · Cableado sobre las precondiciones de GC.
Configuración de flota por dispositivo
Estas funciones trabajan con un único módulo directamente (sin flota): para los casos en que configura un módulo individual antes de añadirlo a una flota, o necesita un control detallado.
rbamp_enable_gc / rbamp_read_fleet_config
Llamada general (difusión en la dirección 0x00) (inicialización) · 4.4 Configuración de flota (0x27..0x2F) (api-reference)
esp_err_t rbamp_enable_gc(rbamp_handle_t dev, bool enable);
esp_err_t rbamp_read_fleet_config(rbamp_handle_t dev, uint8_t *out);
enable_gc(dev, true) escribe 1 en FLEET_CONFIG.bit0 (0x27): el módulo empezará a aceptar instantáneas GC tras el siguiente CMD_SAVE_USER_CONFIG + reinicio. enable_gc(dev, false) hace lo contrario, borrando el bit (el módulo deja de aceptar GC tras el reinicio). read_fleet_config devuelve el byte de configuración actual: útil para confirmar lo escrito.
rbamp_set_group_id / rbamp_read_group_id
esp_err_t rbamp_set_group_id(rbamp_handle_t dev, uint8_t group_id);
esp_err_t rbamp_read_group_id(rbamp_handle_t dev, uint8_t *out);
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.
rbamp_read_gc_tick
esp_err_t rbamp_read_gc_tick(rbamp_handle_t dev, uint16_t *out);
Lee GC_TICK (0x59): el último valor de marca recibido de una trama GC. Se usa para detectar tramas perdidas (si dos módulos tienen una marca distinta, alguien perdió una trama).
rbamp_read_label / rbamp_write_label
esp_err_t rbamp_read_label(rbamp_handle_t dev, char out[9]);
esp_err_t rbamp_write_label(rbamp_handle_t dev, const char *label);
LABEL (0x68..0x6F) — una cadena de etiqueta de usuario de 8 bytes (ASCII, rellena con ceros). Sirve para identificar módulos en una flota, por ejemplo «RED», «CALDERA», «AC1». read_label devuelve siempre un array de 9 bytes (8 bytes de datos + un \0 final). write_label acepta una cadena terminada en nulo; los bytes sobrantes se truncan.
La escritura se hace byte a byte (sin autoincremento en la escritura; vea «Escrituras de registros» más abajo). Tras escribir, necesita rbamp_save_user_config para que la etiqueta sobreviva a un reinicio.
rbamp_broadcast_latch_group
esp_err_t rbamp_broadcast_latch_group(i2c_master_bus_handle_t bus,
uint8_t group_id,
uint16_t tick);
Envío de bajo nivel de la trama GC A5 27 group tick_lo tick_hi directamente a través del manejador bus (sin flota). Útil si la flota aún no se ha creado, o si quiere controlar manualmente el contador de ticks.
rbamp_reset_counters
esp_err_t rbamp_reset_counters(rbamp_handle_t dev);
Restablece los contadores de diagnóstico del módulo (recuento de errores i2c, recuento de reinicializaciones de periféricos). No afecta a la configuración de usuario ni a la calibración. Se usa en pruebas de banco y en reinicios periódicos de contadores en pruebas de estrés de producción de larga duración.
Configuración del sensor
Una secuencia de dos pasos: primero la clase del sensor, después el modelo. Los dos pasos son obligatorios en un módulo con sensor acoplado por el usuario (clase 1). Los módulos que se entregan con su sensor (clase 2 / 3) llegan configurados y están protegidos frente a reescrituras accidentales: vea las notas de protección de lectura antes de escritura más abajo.
Para una guía detallada de selección de modelo, vea 03 · Selección del sensor de corriente.
rbamp_set_sensor_class
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)
esp_err_t rbamp_set_sensor_class(rbamp_handle_t dev,
rbamp_sensor_class_t cls);
Fija la clase de sensor y la persiste.
Leer antes de escribir. La función primero lee la clase que tiene el módulo. Escribir el valor que ya tiene es una operación nula sin escritura en el bus (ESP_OK): en el módulo cualquier escritura de clase, incluso una sin cambios, borra el modelo de CT y la forma de calibración de cada canal, así que una escritura innecesaria degradaría las lecturas. Un módulo cuya clase es 2 o 3 (calibrado junto con su sensor montado) no se reescribe: ESP_ERR_INVALID_STATE.
Si no, escribe la clase, verifica que el módulo la aceptó y la persiste con el guardado de la configuración de usuario (~700 ms, bloqueante). Fijar la clase también borra los modelos de CT del módulo, así que fije los modelos después.
En firmware v1.2+ una clase fijada es un requisito previo para rbamp_set_ct_model() y rbamp_set_ct_model_ch(): llamar a cualquiera de los dos mientras la clase sigue en RBAMP_SENSOR_UNSET devuelve ESP_ERR_INVALID_STATE. Véase 10 · Solución de problemas, sección «La corriente se lee como cero», para el síntoma de «se escribió UNSET por accidente».
Devuelve: ESP_OK si tiene éxito, o si el módulo ya tiene esta clase; ESP_ERR_INVALID_ARG con dev == NULL, un cls no reconocido, o cuando el módulo rechaza la escritura; ESP_ERR_INVALID_STATE cuando la clase actual del módulo es 2 o 3; códigos de error I²C ante un fallo de enlace.
Línea STD. Escribe la clase como metadatos (la línea STD no tiene tabla de preajustes) y la persiste; se comprueba el veredicto del comando del módulo.
rbamp_set_ct_model
esp_err_t rbamp_set_ct_model(rbamp_handle_t dev, uint8_t code);
La forma de un solo parámetro — fija el modelo de CT solo en el canal 0 (equivale a rbamp_set_ct_model_ch(dev, 0, code); en la línea STD es esa llamada). Bloqueante, ~700 ms cuando escribe.
El conjunto de modelos aceptados para la clase activa es la verdad en tiempo de ejecución del firmware: la biblioteca no mantiene una lista de códigos en el cliente. Un par (clase, modelo) desconocido lo rechaza el módulo y se devuelve como ESP_ERR_INVALID_STATE (o ESP_ERR_INVALID_ARG de la comprobación síncrona de la escritura). Los códigos y nombres de modelo están en el rbamp_sensor_models.h generado (rbamp_sensor_model_lookup()); para la clase 1:
code |
Modelo |
|---|---|
| 1 | SCT-013-005 |
| 2 | SCT-013-010 |
| 3 | SCT-013-030 |
| 4 | SCT-013-050 |
| 5 | SCT-013-100 |
| 6 | SCT-013-020 |
| 7 | SCT-013-060 |
(Los siete códigos SCT-013 son seleccionables; el conjunto aceptado es {1, 2, 3, 4, 5, 6, 7}.)
rbamp_set_sensor_class() debe haberse llamado antes (si no, ESP_ERR_INVALID_STATE, sin escritura). También se aplica la protección de lectura antes de escritura de rbamp_set_ct_model_ch().
Para módulos multicanal use la forma por canal que aparece abajo.
rbamp_set_ct_model_ch
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)
esp_err_t rbamp_set_ct_model_ch(rbamp_handle_t dev,
uint8_t channel, uint8_t code);
La forma por canal. Una llamada pública para cualquier canal; el enrutado es interno: los canales 0–2 preparan el modelo y lo aplican con el comando por canal; los canales 3 y siguientes (UI5 / UI7, firmware v1.4.18+) lo aplican a través de la ventana de canales. En ambos casos el modelo aplicado se confirma por relectura y después se persiste (~700 ms). channel se valida contra el número real de canales del módulo.
El orden de vinculación es arbitrario (canon v1.3). La vinculación de CT es un preparado puro: cada aplicación por canal vincula solo su propio canal, así que los canales pueden configurarse en cualquier orden —ascendente, descendente o intercalado— sin pisarse entre sí:
rbamp_set_ct_model_ch(dev, 0, 1); /* channel 0 = SCT-013-005 */
rbamp_set_ct_model_ch(dev, 1, 3); /* channel 1 = SCT-013-030 */
rbamp_set_ct_model_ch(dev, 2, 6); /* channel 2 = SCT-013-020 */
rbamp_set_ct_model_ch(dev, 4, 3); /* channel 4 (UI5 / UI7) */
Protección de lectura antes de escritura. Aplicar un modelo sustituye la calibración que tenga la unidad para ese canal por el preajuste genérico del modelo, y el módulo lo hace incluso cuando el modelo no cambia. Por tanto:
-
el modelo que ya tiene el canal (véase
rbamp_read_ct_model_ch()) es una operación nula sin escritura en el bus: reaplicar una configuración almacenada en cada reconexión es seguro y no provoca ningún reinicio innecesario del módulo; -
un módulo de clase 2 o 3 devuelve
ESP_ERR_INVALID_STATE;rbamp_set_ct_model_ch_force()es la ruta de servicio.
Reinicio del módulo en firmware antiguo de clase 1. En un módulo BASIC de clase 1 sin la capacidad de autocorrección (firmware hasta 1.4.19), una llamada que sí cambia el modelo termina con un reinicio del módulo (unos segundos, mismo UID verificado): es la única forma de que el módulo vuelva a su ganancia calibrada tras una escritura de modelo. La biblioteca evalúa después la corrección de clasificación (rbamp_sct_correction()) y escala las lecturas a partir de la ganancia que aplica el módulo. El estado en RAM del módulo (campos de resumen, máscara de eventos, umbrales) lo reaplica la biblioteca donde le corresponde; los acumuladores de periodo se reinician, como tras cualquier reinicio del módulo.
Devuelve: ESP_OK; ESP_ERR_INVALID_ARG si dev == NULL o channel >= rbamp_channels(dev); ESP_ERR_NOT_SUPPORTED en firmware anterior a v1.2 (canales 0–2), o en un módulo STD que no persiste un modelo de CT por canal; ESP_ERR_INVALID_STATE si la clase es UNSET, si el módulo rechaza el par (class, model), si el modelo aplicado no supera la confirmación por relectura, o si el módulo es de clase 2 / 3; ESP_FAIL / ESP_ERR_TIMEOUT ante un fallo de transporte.
Línea STD. El modelo de CT es solo de referencia (metadatos del SKU): no fija ninguna ganancia, porque el módulo lleva su propia calibración por canal. En el firmware actual de módulos de un solo canal, solo sobrevive al reinicio el modelo del canal 0.
rbamp_set_ct_model_ch_force
esp_err_t rbamp_set_ct_model_ch_force(rbamp_handle_t dev,
uint8_t channel, uint8_t code);
La ruta de servicio: igual que rbamp_set_ct_model_ch(), pero escribe independientemente de la clase del módulo y del modelo que tenga cargado. Sustituye la calibración emparejada de ese canal por el preajuste genérico del modelo: úsela solo al reemparejar un módulo con un sensor nuevo en servicio, y siga con una calibración.
rbamp_read_sensor_class
esp_err_t rbamp_read_sensor_class(rbamp_handle_t dev, uint8_t *out);
La clase de sensor de corriente del módulo como valor de rbamp_sensor_class_t (BASIC: el registro de clase; STD: el campo de configuración de clase).
Límites de los modelos de sensor
bool rbamp_sensor_model_limits (uint8_t sensor_class, uint8_t code,
float *nominal_a, float *fs_a, float *peak_a);
float rbamp_sensor_model_rated_a(uint8_t sensor_class, uint8_t code);
Consultas puras en el registro de modelos generado (rbamp_sensor_models.h) — sin tráfico de bus.
-
rbamp_sensor_model_limitsrellena (cualquier salida puede serNULL):nominal_a— la corriente RMS nominal, A;fs_a— la corriente RMS a la que una onda senoidal empieza a recortarse, A;peak_a— el techo instantáneo de recorte, A (una carga distorsionada se recorta enpeak_adividido por su factor de cresta).0significa no conocido para ese modelo (códigos heredados de toroide / burden). Devuelvetruesi el par(class, code)está en el registro,falseen otro caso (las salidas valen entonces 0). -
rbamp_sensor_model_rated_aes la abreviatura denominal_a. Es la nominal del sensor, que puede diferir de los amperios del nombre del modelo (la pinza de «5 A» tiene una nominal de 4.6 A). Userbamp_sensor_model_lookup()para obtener el nombre del modelo.
Que un código figure en el registro no significa que el módulo conectado lo acepte: eso es la verdad en tiempo de ejecución.
Corrección de clasificación SCT-013
Un módulo BASIC de clase de sensor 1 se calibra en fábrica con el sensor de 30 A (modelo 3). En firmware hasta 1.4.19, un cambio a otro modelo deja el módulo aplicando la calibración de 30 A tras un reinicio, así que un sensor mayor lee bajo. Un módulo que informa de la capacidad de autocorrección (firmware 1.4.20 y posteriores) se corrige solo y no necesita nada de esto.
En el firmware anterior la biblioteca lee la ganancia que aplica realmente el módulo (en rbamp_begin(), tras una escritura de modelo y tras cada reinicio de módulo detectado) y escala la corriente, el pico de corriente, la potencia activa, la potencia media del período, la energía integrada, el digest y los umbrales de evento a partir de esa ganancia y del modelo seleccionado. La tensión y el factor de potencia no se escalan. El resultado por canal es rbamp_sct_status_t (vea Tipos). Una ganancia que sigue igual al preajuste bruto (el modelo se cambió en este arranque sin reinicio) provoca un reinicio del módulo; una ganancia aplicada inesperada, un modelo desconocido o un preajuste bruto que sobrevive al reinicio dejan las lecturas sin escalar, con un aviso en el registro. CONFIG_RBAMP_SCT_RATING_CORRECTION (activado por defecto) desactiva el mecanismo, y entonces se devuelven los valores brutos del módulo.
esp_err_t rbamp_sct_correction(rbamp_handle_t dev, uint8_t ch,
rbamp_sct_correction_t *out);
esp_err_t rbamp_sct_refresh (rbamp_handle_t dev);
| Función | Descripción |
|---|---|
rbamp_sct_correction(dev, ch, &c) |
La corrección cacheada del canal ch: sin tráfico en el bus. La evalúan rbamp_begin(), rbamp_set_ct_model*() y tras un reinicio detectado del módulo (un RESET_OCCURRED borrado, un RESET pendiente en el digest, un uptime decreciente). ESP_ERR_NOT_SUPPORTED en la línea STD. |
rbamp_sct_refresh(dev) |
Vuelve a leer la clase, los modelos y las ganancias aplicadas, y recalcula las escalas. Emite un reinicio del módulo (y vuelve a sondear el módulo, verificando el mismo UID) cuando la ganancia aplicada de un canal sigue siendo el preajuste bruto de un modelo distinto al de 30 A. Se llama internamente cuando hace falta; se expone para un host que sepa que el módulo se reinició por otros medios. Es una operación nula que devuelve ESP_OK en la línea STD y en un módulo que se autocorrige. |
rbamp_save_gains
esp_err_t rbamp_save_gains(rbamp_handle_t dev);
Una escritura CMD_SAVE_GAINS «pelada», sin cambios de registro que la acompañen.
⚠ Normalmente se llama dentro del componente. Un rbamp_save_gains() aislado solo es apropiado si el llamador escribió manualmente en registros de calibración no públicos mediante acceso al bus en bruto: es una operación fuera de garantía que se salta la tabla de preajustes por SKU. Los valores incorrectos producirán lecturas erróneas de corriente y potencia sin avisos explícitos. Cada llamada realiza un ciclo de borrado y escritura en flash (~700 ms); la resistencia de la flash es finita (~10000 ciclos por página): no la llame en un bucle.
Línea STD. Emite el guardado de la calibración (persiste el bloque de calibración: ganancias, suelos de ruido y THD) y comprueba el veredicto del comando.
rbamp_prepare_address_change / rbamp_commit_address_change
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)
El cambio de la dirección I²C del módulo se hace mediante una confirmación en dos fases en modo de producción. El firmware excluye deliberadamente la dirección del flujo general CMD_SAVE_USER_CONFIG / CMD_SAVE_GAINS: el cambio exige una secuencia explícita armada con código mágico.
esp_err_t rbamp_prepare_address_change(rbamp_handle_t dev,
uint8_t new_addr);
esp_err_t rbamp_commit_address_change(rbamp_handle_t dev);
Protocolo en el cable, por debajo:
-
prepare: valida el rango denew_addr(0x08..0x77, distinto del actual) → escribenew_addrenREG_I2C_ADDRESS(0x30): queda en RAM. -
prepare: escriba0xA5enREG_ADDR_COMMIT_MAGIC(0x31) — esto «arma» la confirmación. La ventana de estado armado es de 5 segundos. -
commit: compruebe la frescura del armado → envíeCMD_COMMIT_ADDR(código 0x30) → guarde en flash →CMD_RESET -
~400 ms de arranque → actualice el campo de dirección interna del manejador.
Tras una commit correcta, todas las llamadas de esta instancia del manejador van dirigidas a la nueva dirección. La operación funciona en modo de producción (no está bloqueada), lo que permite el intercambio en campo de módulos de repuesto de producción.
⚠ Si la ventana de armado (5 s) ha caducado — commit devuelve ESP_ERR_TIMEOUT, la marca de armado se borra y debe empezar de nuevo con prepare.
Línea STD. El cambio de dirección es síncrono y el manejador solo cambia cuando un módulo responde en la nueva dirección: vea rbamp_commit_address_change en la línea STD. Si falla, el manejador conserva la dirección anterior (ESP_ERR_NOT_FOUND).
⚠ La persistencia solo se confirma tras un reinicio. Antes del reinicio, rbamp_read_* puede devolver los valores nuevos desde RAM, pero la escritura en flash podría no haber terminado. El propio componente realiza un CMD_RESET + espera de arranque dentro de commit, así que tras un retorno correcto el estado queda garantizado como persistido.
⚠ 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 en esta instancia del manejador se dirigen a la nueva dirección de forma transparente, pero cualquier OTRO master 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 manualmente.
rbamp_factory_reset
esp_err_t rbamp_factory_reset(rbamp_handle_t dev);
El comando CMD_FACTORY_RESET (0xAA) + una 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 los valores de fábrica: rbamp_sensor_class_t pasa a RBAMP_SENSOR_UNSET y REG_CT_MODEL a 0. Cualquier ajuste aplicado antes con rbamp_set_sensor_class() / rbamp_set_ct_model*() desaparece. El siguiente usuario DEBE volver a aplicar rbamp_set_sensor_class() y rbamp_set_ct_model*() antes de que la contabilidad vuelva a estar operativa. No es un «reinicio suave»: para un reinicio suave use rbamp_reset(). rbamp_factory_reset() se reserva para recuperarse de un estado conocido como defectuoso o para entregar el módulo a otro usuario o instalación.
Línea STD. No existe un comando de restablecimiento de fábrica: rbamp_factory_reset() devuelve ESP_ERR_NOT_SUPPORTED.
rbamp_reset
esp_err_t rbamp_reset(rbamp_handle_t dev);
El comando CMD_RESET (0x01) + una espera de 100 ms. Un reinicio suave del dispositivo sin perder los parámetros de flash.
Bus con varios módulos
rbamp_broadcast_latch
esp_err_t rbamp_broadcast_latch(i2c_master_bus_handle_t bus,
uint32_t timeout_ms);
En firmware v1.3 (REG_VERSION = 0x04) esta es la ruta canónica de sincronización de flota una vez habilitado General-Call en toda la flota mediante rbamp_fleet_enable_gc_all(). La trama General-Call de 5 bytes A5 27 hace que todos los módulos tomen su instantánea en el grupo correspondiente en el mismo instante del cable, lo que da una sincronización estrecha entre subcontadores. La función solo toma el bus: transmite la trama (ESP_OK significa que el driver del host no dio error — General Call es solo escritura, ningún módulo responde con ACK; ESP_ERR_INVALID_ARG si el bus es NULL). Los módulos sin soporte de General-Call, o con él desactivado, simplemente ignoran la trama: verifíquelo con el testigo por módulo (más abajo) y use el respaldo secuencial si no tomaron la instantánea. rbamp_broadcast_latch_group(bus, group, tick, timeout_ms) es lo mismo con un filtro de grupo explícito y un tick de flota.
Alternativa secuencial (firmware heredado, o cuando GC se dejó desactivado): una serie de rbamp_latch_period() en cada dispositivo, una pausa común de 50 ms y una rbamp_read_period_snapshot(skip_latch=true) por dispositivo: vea 06 · Ejemplos, escenario «Monitorización de varios módulos».
Línea STD
La línea de módulos STD habla un modelo de registros distinto tras el mismo manejador. rbamp_begin() lo detecta; la API escalar de los capítulos anteriores funciona sin cambios en ambas líneas (rbamp_read_current, _power, _voltage, rbamp_read_period_snapshot, rbamp_energy_wh, las llamadas de configuración, …). Las funciones de este capítulo son las adiciones exclusivas de STD: canales completos en una sola ráfaga, las magnitudes que solo mide esta línea (potencia reactiva / aparente, THD, contadores de energía con signo), bancos de instantáneas, el reloj del módulo, historial, estado y actualización de firmware. Toda función rbamp_std_* devuelve ESP_ERR_NOT_SUPPORTED en un manejador BASIC.
Muchas funciones necesitan una versión mínima del mapa de registros del módulo (se indica como «mapa 0x35+» y similares más abajo). El control de funciones se basa en las capacidades y la versión de mapa que informa el módulo (rbamp_std_info()), nunca en suposiciones; cuando un módulo es demasiado antiguo, la función devuelve ESP_ERR_NOT_SUPPORTED, en la mayoría de casos sin tráfico en el bus. Un ejemplo de trabajo es examples/std_meter/.
Identidad y descubrimiento
typedef struct {
uint8_t map_version;
uint16_t capabilities; /* RBAMP_STD_CAP_* bitmap */
uint8_t status; /* RBAMP_STD_ST_* bits at begin() time */
uint8_t n_voltage; /* populated voltage channels */
uint8_t n_current; /* populated current channels */
uint8_t variant; /* raw RBAMP_STD_VARIANT_* byte */
uint32_t active_bank; /* running firmware bank, 0 without OTA capability */
uint32_t ota_bank_size; /* flash bank size, 0 if none */
rbamp_std_period_source_t period_source;
} rbamp_std_info_t;
typedef struct {
uint8_t i2c_addr;
uint8_t map_version;
uint16_t capabilities;
uint8_t variant;
uint8_t n_voltage, n_current;
uint8_t uid[12]; /* chip UID — the identity; addresses can change */
uint32_t fw_version; /* running image version (map 0x35+; 0 if unknown) */
uint32_t board_id; /* map 0x36+; 0 below */
} rbamp_std_identity_t;
| Función | Descripción |
|---|---|
rbamp_std_info(dev, &info) |
La identidad cacheada por rbamp_begin(): sin tráfico en el bus. Devuelve ESP_ERR_NOT_SUPPORTED en un manejador BASIC o antes de rbamp_begin(). El control de canales se basa en n_voltage / n_current: los registros de canales más allá de esos números no están especificados y la biblioteca se niega a leerlos. |
rbamp_std_identify(dev, &id) |
Todo lo que un master necesita para reconocer el módulo tras un manejador (de dos a cuatro lecturas cortas). |
rbamp_std_probe(bus, addr, &id) |
Sondea una dirección en un bus sin manejador — el bloque básico de un escaneo. Rápido: sin reintentos; un NACK es la respuesta. ESP_OK con id rellenado; ESP_ERR_NOT_FOUND si nada confirma; ESP_ERR_INVALID_RESPONSE si responde algo que no es un módulo STD (un módulo BASIC, otro chip). |
rbamp_std_read_image_version(dev, &v) |
La versión de la imagen de firmware en ejecución (u32, por ejemplo 0x00010072). Distinta de rbamp_firmware_version(), que es la versión del mapa de registros de esta línea. 0 si el módulo no puede indicarla. |
rbamp_std_read_board_id(dev, &id) |
Identificador de placa de la imagen en ejecución (mapa 0x36+): una palabra que codifica el hardware para el que se compiló la imagen. Una imagen de firmware solo se acepta si su palabra de placa coincide (vea rbamp_std_ota_board_ok). |
rbamp_std_locate(dev) |
Haga parpadear los LED del módulo durante unos 10 s para que una persona pueda localizarlo. |
rbamp_std_set_address_by_uid(bus, shared_addr, uid, new_addr, restart_ms) |
Asigne a un módulo con una dirección compartida su propia dirección, seleccionado por UID (mapa 0x36+). Pueden estar varios módulos en shared_addr (p. ej., la dirección de fábrica); solo el cuyo UID coincide toma new_addr, la persiste y se reinicia; los demás ignoran el comando. No necesita manejador. Tras el reinicio, la biblioteca sondea new_addr y comprueba allí el UID. restart_ms 0 = 1500 ms. ESP_ERR_NOT_FOUND si nadie responde en new_addr; ESP_ERR_INVALID_RESPONSE si un módulo responde allí pero su UID es distinto. |
Cómo un módulo STD entrega la energía del período
typedef enum {
RBAMP_STD_PERIOD_NONE = 0,
RBAMP_STD_PERIOD_LATCH = 1,
RBAMP_STD_PERIOD_COUNTERS = 2,
} rbamp_std_period_source_t;
Lo decide rbamp_begin() a partir de las capacidades del módulo y lo expone en rbamp_std_info_t.period_source:
-
LATCH— el módulo tiene bancos de instantáneas. Un periodo va de instantánea a instantánea en el banco 0; los promedios y la energía por canal salen del banco. Véase Bancos de instantáneas. -
COUNTERS— sin bancos de instantáneas, pero con contadores de vida persistentes. Un periodo es la diferencia entre dos lecturas de contador, tomadas según la programación del maestro; no hay comando de instantánea, nada que armar, y nada se pierde tras un reinicio del módulo. Véase Contadores de energía de vida. -
NONE: ninguno de los dos; las llamadas de período y energía devuelvenESP_ERR_NOT_SUPPORTED.
Bloques en tiempo real
typedef struct {
float i_rms; /* A */
float i_peak; /* A — reads 0 on module map 0x34 and earlier */
float p, q, s; /* W (signed), var (signed), VA */
float pf; /* −1..+1 */
float thd_i; /* % — 0 while harmonics are off */
float pf1; /* displacement power factor — 0 while harmonics are off */
float q1; /* fundamental reactive power, var — 0 while harmonics are off */
int64_t e_import_mws; /* raw signed import accumulator, mW·samples (>= 0) */
int64_t e_export_mws; /* raw signed export accumulator, mW·samples (<= 0) */
uint8_t implausible; /* RBAMP_FIELD_* bits set to NaN */
} rbamp_std_channel_t;
typedef struct {
float u_rms, u_peak, thd_u; /* V, V (0 on map 0x34 and earlier), % */
uint8_t implausible;
float angle_deg; /* phase angle against voltage input 0, (−180, 180]; input 0 reads 0 */
bool angle_valid; /* the module publishes the angle for this input */
} rbamp_std_voltage_t;
| Función | Descripción |
|---|---|
rbamp_std_read_channel(dev, ch, &c) |
Un bloque de canal de corriente (I / P / Q / S / PF / pico / acumuladores de energía / armónicos) en una sola ráfaga; ch es 0..rbamp_channels(dev)-1. Los campos son tan coherentes como los publica el módulo (por ventana de publicación); para una instantánea multicampo estrictamente atómica use la instantánea de periodo. Un campo que supera un límite de cordura es NaN con su bit RBAMP_FIELD_* activo en implausible. |
rbamp_std_read_totals(dev, k, &c) |
Un bloque agregado: k = 0 el total general (suma de todos los canales de corriente), k = 1..3 los totales por fase A/B/C (solo módulos polifásicos). Los totales por fase se publican desde el mapa 0x36; en un módulo monofásico k = 1 es igual al canal 0 y k = 2/3 leen 0; por debajo de 0x36 devuelven ESP_ERR_NOT_SUPPORTED (k = 0 siempre funciona). Los campos de energía (e_import_mws / e_export_mws) no se rellenan en los bloques agregados y leen 0: la energía viene de los contadores persistentes (rbamp_std_read_energy). |
rbamp_std_read_voltage(dev, v, &u) |
Un bloque de canal de tensión (RMS / pico / THD / ángulo de fase) en una sola ráfaga; v es 0..n_voltage-1. angle_deg / angle_valid los publican los módulos trifásicos con versión de imagen de módulo 0x0001007A o posterior; en otro caso angle_valid es false y el resto del bloque no se ve afectado. En un módulo trifásico con secuencia directa, la entrada 1 lee unos −120° y la entrada 2 unos +120°. |
rbamp_std_read_phase_seq(dev, &seq) |
El orden de las entradas de tensión, que el módulo deduce de los ángulos: RBAMP_STD_PHASE_SEQ_NA (menos de tres entradas, o una entrada demasiado baja), _FORWARD (L1-L2-L3), _REVERSE (L1-L3-L2), _ABNORMAL (sin patrón de 120°, p. ej. dos entradas cableadas a la misma fase). Devuelve ESP_ERR_NOT_SUPPORTED (y *seq = NA) en una versión de imagen de módulo anterior a 0x0001007A, sin tráfico de bus. |
thd_i, pf1, q1 y thd_u leen 0 salvo que esté habilitada la extracción de armónicos — véase Configuración. e_import_mws / e_export_mws son los acumuladores brutos del módulo en mW·muestras; el módulo no tiene reloj, así que convertir a Wh requiere el número de muestras y su propia medición del periodo (use la ruta de instantáneas o los contadores de vida). Para monitorizar, integre p en su intervalo de sondeo.
rbamp_read_all() en un módulo STD lee el bloque de tensión y cada bloque de canal completo (una transacción cada uno), en lugar de campo a campo. rbamp_read_frequency() en un módulo STD devuelve ESP_ERR_INVALID_RESPONSE con *out = NaN cuando el módulo publica 0 (sin red eléctrica); entonces rbamp_read_all() genera RBAMP_FIELD_FREQUENCY. rbamp_read_voltage_peak() / rbamp_read_current_peak() devuelven 0 en el mapa de módulo 0x34 y anteriores: use max_u / min_u / max_i de un banco de instantáneas para el pico en un período.
Salud
typedef struct {
uint8_t status; /* RBAMP_STD_ST_* bits: cal_ok / sensor_ok / mains_ok / locked / time_valid */
uint32_t frame_count; /* sensor frame counter — must grow between polls */
uint32_t crc_errors; /* sensor frame CRC error counter */
bool time_valid; /* the module clock is set; false after every module reset */
bool nvm_fault; /* energy store fault or corrupt (details in lta_status) */
uint8_t lta_status; /* life-time energy store: 0 ok · 1 new · 2 fault · 3 corrupt (service) */
uint8_t lta_src; /* counters loaded from: 0 none · 1 NVM · 2 backup domain · 3 legacy · 4 rollback anchor */
uint8_t cal_src; /* calibration in use: 0 defaults · 1 flash · 2 EEPROM · 3 stored cal is for another range */
uint32_t lost_frames; /* sensor frames lost since boot — should stay flat */
uint16_t ring_drop; /* acquisition ring overruns since boot — should stay flat */
uint32_t uptime_s; /* seconds since the module booted */
bool maint; /* maintenance mode active */
uint8_t group_status; /* per-channel energy store: 0 ok · 1 new · 2 fault · 3 restarted at 0 */
uint16_t legal_noen; /* metering-relevant operations executed outside maintenance mode */
uint8_t reset_cause; /* image 0x76+: cause of THIS boot, RBAMP_STD_RST_* bits; 0 below */
uint16_t boot_count; /* image 0x76+: persisted boot counter (low 16 bits); 0 below */
} rbamp_std_health_t;
rbamp_std_read_health(dev, &h) lee el estado en vivo. Considere válidas las lecturas cuando status tiene RBAMP_STD_ST_SENSOR_OK y frame_count aumenta entre dos sondeos. Los campos posteriores a crc_errors existen en módulos con mapa 0x35 o superior, y leen cero / false en los anteriores.
Alerta si: nvm_fault o lta_status >= 2 (almacén de energía); cal_src == 3 (la calibración almacenada es de otro rango, se usan valores por defecto, cal_ok también a cero); lost_frames / ring_drop en aumento; time_valid en false (ajuste el reloj); uptime_s decreciente (el módulo se reinició). reset_cause contiene los bits RBAMP_STD_RST_* (pin, alimentación, software = reinicio / activación / cambio de dirección, perros guardianes, bajo consumo, byte de opciones); el bit de pin acompaña a la mayoría de reinicios internos, así que juzgue por los demás bits.
Configuración
typedef struct {
uint8_t sensor_class; /* rbamp_sensor_class_t value; 0 = unset. Persisted. */
uint8_t ct_model; /* CT model reference for channel 0 (metadata, sets no gain). Persisted. */
uint8_t tier; /* 0 or 1. 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) */
uint16_t start_ua; /* starting current for energy, µA (0 = off); 0 when start_ua_supported is false */
bool start_ua_supported; /* the module has the starting-current setting */
} rbamp_std_config_t;
| Función | Descripción |
|---|---|
rbamp_std_read_config(dev, &cfg) |
El bloque de configuración (una ráfaga, más el registro de corriente de arranque donde el módulo lo tenga). |
rbamp_std_set_harmonics(dev, enable) |
Active o desactive la extracción de armónicos de base (THD, PF de desplazamiento, Q1). Desactivado por defecto en el nivel regular (ahorra CPU del módulo); los campos de armónicos leen 0 mientras está desactivado. Solo RAM: vuelve a desactivado al reiniciar el módulo. Se lee de vuelta y se confirma. ESP_ERR_NOT_SUPPORTED sin la capacidad de THD. |
rbamp_std_cal_thd_floor(dev) |
Calibra el umbral de THD de la cadena de sensores: captura el THD bruto suavizado actual como umbral, lo persiste y lo aplica en vivo. Precondición: red limpia y SIN carga en la CT — el valor capturado se resta de todas las lecturas posteriores de THD. Bloquea durante el asentamiento de la persistencia; el veredicto llega del registro de errores del módulo (mapa 0x34+). ESP_ERR_NOT_SUPPORTED sin la capacidad THD. |
rbamp_std_get_start_current(dev, &ua) |
La corriente de arranque para energía, en µA (0 = desactivada). Por debajo de esta corriente de canal, el módulo no cuenta energía para ese canal (importación o exportación, total general y por canal); las lecturas en sí no se ven afectadas. ESP_ERR_NOT_SUPPORTED sin tráfico de bus en un módulo sin este ajuste (versión de imagen de módulo anterior a 0x0001007B). |
rbamp_std_set_start_current(dev, ua) |
Configúrelo: 0 = desactivado; en otro caso, un valor del conjunto de pasos que acepta el módulo. Se aplica de inmediato; rbamp_save_user_config() lo persiste. Se lee de vuelta y se confirma. ESP_ERR_INVALID_ARG para un valor fuera del conjunto aceptado: no se escribe nada; ESP_ERR_NOT_SUPPORTED como arriba; ESP_ERR_INVALID_STATE si el módulo no aceptó el valor. |
Las llamadas de configuración escalares (rbamp_set_sensor_class, rbamp_set_ct_model_ch, rbamp_configure_channels, rbamp_save_user_config, rbamp_save_gains, rbamp_prepare_address_change / rbamp_commit_address_change, rbamp_reset) funcionan en ambas líneas; cada una tiene una nota de «línea STD» en su sección. Dos diferencias que conviene conocer: rbamp_factory_reset() devuelve ESP_ERR_NOT_SUPPORTED (no existe ese comando en esta línea), y rbamp_save_gains() persiste el bloque de calibración.
rbamp_commit_address_change() en la línea STD es síncrono: el guardado de la configuración espera al módulo y lee el veredicto (una dirección fuera de rango → ESP_ERR_INVALID_ARG; el límite de frecuencia de escritura en flash del módulo → ESP_ERR_NOT_FINISHED: prepare de nuevo y reintente tras unos 5 s; en ambos casos no cambia nada), luego reinicia el módulo y cambia el manejador solo cuando un módulo responde en la nueva dirección (en unos 3 s). Si nadie responde allí, ESP_ERR_NOT_FOUND y el manejador conserva la dirección anterior. rbamp_read_active_address() lee la dirección persistida.
Contadores de energía de vida
Para un módulo que guarda contadores de energía persistentes en el dispositivo (RBAMP_STD_CAP_ONDEVICE_ENERGY).
typedef struct {
int64_t act_import_wh, act_export_wh, act_net_wh; /* Wh; net = import − export */
int64_t rea_import_varh, rea_export_varh; /* varh */
uint32_t generation; /* changes when the counters were reset or adopted */
uint32_t uptime_s; /* module uptime */
int64_t act_import_mwh, act_export_mwh, act_net_mwh;/* mWh (map 0x36+) */
uint8_t channels; /* valid entries in the per-channel arrays (map 0x36+) */
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, fine_reactive;
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];
} rbamp_std_energy_t;
Los contadores son de unidades enteras, monótonos y persistidos ante cortes de alimentación. La importación y la exportación son magnitudes separadas. La energía de un período es la diferencia de dos lecturas.
-
generationcambia cuando los contadores se pusieron a cero o se adoptaron en el módulo: nunca tome una diferencia a través de ese cambio. -
Un
uptime_sdecreciente significa que el módulo se reinició. Los contadores están persistidos, así que la diferencia sigue siendo válida, pero se pierden el reloj del módulo y los ajustes de RAM. -
Tras un corte de alimentación, un contador puede reanudarse ligeramente por debajo de su última lectura (una fracción de segundo de energía);
rbamp_std_energy_delta()fija esa diferencia en 0 y conserva el intervalo. -
Los campos
*_uwh/*_uvarhsiempre se rellenan, así que puede usarlos en cualquier módulo: un módulo que publica contadores de resolución µ (versión de imagen de módulo0x0001007Ao posterior; la reactiva desde0x0001007B) los entrega en la misma instantánea yfine/fine_reactiveson true; en módulos anteriores son los contadores gruesos escalados yfinees false. -
channels > 0(mapa 0x36+): el canalces el canal de corrientec; en un módulo trifásico, la fasec.
rbamp_std_energy_t gana campos entre versiones del componente. Si lo guarda (NVS, archivo), almacene los campos individuales que necesite en su propio formato fijo, no la estructura como un blob en bruto.
| Función | Descripción |
|---|---|
rbamp_std_read_energy(dev, &e) |
Lea los contadores. Cada bloque decodificado es una transacción (el módulo lo sirve desde una instantánea coherente). ESP_ERR_NOT_SUPPORTED salvo que el módulo informe de la capacidad de energía en el dispositivo; ESP_ERR_INVALID_RESPONSE si el bloque se lee como no programado. |
rbamp_std_energy_delta(&prev, &now, &delta, &restarted) |
Energía entre dos lecturas, aplicando las reglas de continuidad. delta = now − prev por contador (magnitudes de importación / exportación, neto, reactiva; generation y uptime_s se copian de now); restarted es true si uptime_s bajó. Cualquiera de las salidas puede ser NULL. Un contador que bajó se fija en una diferencia de 0, también por canal y en todas las resoluciones; cada campo neto es la diferencia de importación menos la diferencia de exportación. Las diferencias por canal se producen cuando ambas lecturas tienen el mismo número de canales; en otro caso delta->channels es 0. ESP_ERR_INVALID_STATE si la generación cambia: no contabilice ese intervalo; empiece de nuevo desde now. |
Bancos de instantáneas
El módulo mantiene 8 bancos independientes (solo en módulos con la capacidad de multi-instantánea, period_source == RBAMP_STD_PERIOD_LATCH). Un banco acumula mientras su bit esté activo en la máscara de armado; rbamp_std_latch() toma la instantánea y lo reinicia en el siguiente límite de ventana de medición del módulo. Un periodo es, por tanto, el intervalo entre dos instantáneas del mismo banco, medido con el reloj del maestro (el módulo no tiene reloj). El banco 0 es también el que usan rbamp_read_period_snapshot() y rbamp_energy_wh(). Las tres llamadas a bancos devuelven ESP_ERR_NOT_SUPPORTED sin tráfico de bus en cualquier otro módulo: use allí rbamp_std_read_energy() / rbamp_std_energy_delta().
Uso típico: arme los bancos una vez y, por banco, según su propio horario, rbamp_std_latch(bank) → espere ≥ 300 ms (límite superior seguro de una ventana de medida en cualquier imagen) → rbamp_std_read_latch() → rbamp_std_latch_wh() con el dt medido por el master desde la instantánea anterior.
typedef struct {
float p_avg, q_avg, s_avg; /* average P / Q / S over the period */
float max_p, max_i, max_u, min_u;/* peaks in the period */
int64_t e_import_mws, e_export_mws;/* energy, mW·samples */
uint32_t nsamp; /* sensor samples in the period */
uint32_t win_count; /* measurement windows in the period (0 = not armed / nothing elapsed) */
uint8_t channels; /* valid entries in the per-channel arrays */
uint8_t 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];
} rbamp_std_latch_t;
| Función | Descripción |
|---|---|
rbamp_std_arm_banks(dev, mask) |
Fije 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). El bit 0 debe permanecer activo si usa rbamp_read_period_snapshot(). La máscara está en RAM del módulo: cualquier reinicio del módulo la borra, y tomar una instantánea de un banco no armado devuelve una instantánea vacía. La biblioteca vuelve a armar el banco 0 por sí misma (en rbamp_begin(), tras sus propios reinicios y cuando una instantánea de periodo llega vacía). Para sus propios bancos, rbamp_std_read_latch() detecta el armado perdido, vuelve a armar y toma una instantánea de cebado. |
rbamp_std_latch(dev, bank) |
Solicita una instantánea + reinicio de bank en el siguiente límite de ventana. No espera: léala ≥ 300 ms después. |
rbamp_std_read_latch(dev, bank, &l) |
Lee la última instantánea del bank indicado (una ráfaga: totales + energía por canal de cada canal cargado). ESP_ERR_INVALID_RESPONSE si el módulo nunca enclavó este banco (los demás campos quedan a cero). ESP_ERR_INVALID_STATE si la instantánea está vacía porque un reinicio del módulo desarmó el banco: la biblioteca lo ha rearmado y tomado una instantánea de cebado — descarte este periodo y reinicie su ancla de dt. Lea un banco al menos una ventana de medición después de enclavarlo; win_count == 0 significa que no estaba armado o que no transcurrió ninguna ventana. |
rbamp_std_latch_wh(&l, dt_ms, ch, &wh_import, &wh_export) |
Convierte los buckets de energía de una instantánea a Wh sobre el periodo medido por el maestro dt_ms (el tiempo de reloj del maestro entre la instantánea anterior y esta del banco). ch es un índice de canal o RBAMP_STD_TOTAL (0xFF) para los totales del banco. Wh = E[mW·muestras] / 1000 / 3600 × (dt / nsamp): el número de muestras y el dt del maestro normalizan el resultado. Importación ≥ 0, exportación ≤ 0; cualquiera de las salidas puede ser NULL. ESP_ERR_INVALID_STATE si nsamp es 0. |
Reloj, comandos y servicio
El módulo guarda su reloj en RAM: es inválido tras cada reinicio del módulo. Sin un reloj válido, el módulo no registra historial.
| Función | Descripción |
|---|---|
rbamp_std_set_time(dev, unix_epoch) |
Ajusta el reloj del módulo (segundos Unix) y espera a que termine. Llámelo tras rbamp_begin() y siempre que rbamp_std_health_t.time_valid sea false (o un período informe module_restarted). El primer ajuste tras un reinicio cierra el intervalo de historial en curso sin arrastrarlo. ESP_ERR_INVALID_ARG si el módulo rechaza la época (anterior a 2020); ESP_ERR_INVALID_STATE si el reloj no llegó a ser válido; ESP_ERR_NOT_SUPPORTED por debajo del mapa 0x35. |
rbamp_std_read_time(dev, &epoch, &valid) |
Lee el reloj del módulo y si es válido. |
rbamp_std_command(dev, opcode, settle_ms, timeout_ms) |
Escriba un código de operación de comando y espere a su finalización: primero espera a que el módulo esté libre (un comando escrito mientras está ocupado se descarta), duerme settle_ms, espera a que BUSY se borre y después lee el veredicto. timeout_ms 0 = 1 s. Veredictos: ESP_ERR_INVALID_ARG (parámetro incorrecto), ESP_ERR_NOT_SUPPORTED (comando desconocido), ESP_ERR_INVALID_CRC (comprobación de valor), ESP_ERR_NOT_FINISHED (escritura en flash limitada en frecuencia: reintente tras unos 5 s), ESP_ERR_NOT_ALLOWED (clave o puerta de mantenimiento), ESP_ERR_TIMEOUT (sigue ocupado). |
rbamp_std_wait_idle(dev, timeout_ms) |
Espera hasta que el módulo termine el comando que está ejecutando. Todo comando emitido a través de esta biblioteca ya espera; use esto solo alrededor de comandos que escriba usted mismo en el registro de comandos: un comando escrito mientras el módulo está BUSY se descarta. Devuelve de inmediato en módulos sin registro de estado de comando. |
rbamp_std_hist_flush(dev) |
Escriba ahora los acumuladores de energía en flash (también lo implica un reinicio o una confirmación de firmware). |
Una escritura de comando nunca se reintenta ante un error de transporte (un reintento podría entregar el código de operación dos veces); las lecturas y escrituras de registros de datos sí mantienen el reintento.
Historial y registro de eventos
El módulo guarda el último registro de 15 minutos en RAM (se pierde al reiniciar el módulo; es un indicador en tiempo real, no un historial) y un anillo horario en flash que sobrevive a los reinicios y es el anillo del que debe recuperar los datos; ambos se escriben solo mientras el reloj del módulo es válido. Un registro de eventos que nunca se borra guarda los cambios relevantes para la medición. Cada registro HORARIO incluye los contadores de vida absolutos al final del periodo: la energía total del periodo es la diferencia entre dos registros consecutivos (los reinicios y los huecos siguen siendo visibles). Recuperación tras una caída del maestro: recorra back desde 0 (el más reciente) hasta llegar a las marcas de tiempo que ya tiene.
typedef enum {
RBAMP_STD_HIST_MIN15 = 0, /* 15-minute records (RAM, lost at module reset) */
RBAMP_STD_HIST_HOUR = 1, /* hourly records (flash ring) */
RBAMP_STD_HIST_EVENTS = 2, /* event log — read with rbamp_std_event_read */
} rbamp_std_hist_period_t;
typedef struct {
uint16_t count; /* records available (0 while the ring is being cleared) */
uint16_t capacity; /* ring depth */
uint16_t record_size; /* bytes per record */
uint32_t oldest_ts, newest_ts; /* unix */
} rbamp_std_hist_info_t;
typedef struct {
uint32_t ts; /* period start, unix */
uint16_t flags; /* RBAMP_STD_HF_* bits */
uint16_t n; /* samples (MIN15) or 15-minute children (HOUR: 4 = complete) */
bool from_ram; /* record came from the RAM ring (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 counters ABSOLUTE at period end */
uint8_t phases; /* valid entries in the per-phase arrays */
double ph_import_wh[3], ph_export_wh[3]; /* per-phase energy OF THIS PERIOD, Wh */
} rbamp_std_hist_record_t;
typedef struct {
uint32_t ts; /* unix time (0 = clock was not set) */
uint32_t uptime_s; /* module uptime at the event */
uint8_t type; /* RBAMP_STD_EV_* */
uint8_t flags; /* RBAMP_STD_EVF_* (maintenance mode was active) */
uint16_t boot; /* boot counter (low 16 bits) */
uint32_t a_before, a_after; /* type-specific values before / after the change */
uint64_t e_before_wh, e_after_wh; /* grand import counter before / after, Wh */
} rbamp_std_event_t;
| Función | Descripción |
|---|---|
rbamp_std_hist_info(dev, period, &info) |
Estado de anillo de un período del historial (también lo selecciona en el módulo). |
rbamp_std_hist_read(dev, period, back, &rec) |
Obtiene y decodifica el registro back (0 = el más reciente) de MIN15 u HOUR. ESP_ERR_NOT_FOUND si no existe tal registro. Tome la energía de un periodo a partir de dos registros consecutivos solo si sus marcas de tiempo difieren exactamente en un periodo y ninguno lleva el indicador RBAMP_STD_HF_LTA_JUMP. |
rbamp_std_hist_read_raw(dev, period, back, rec, &flags) |
El mismo registro sin decodificar: rec (un búfer de RBAMP_STD_REG_HIST_REC_SIZE; la longitud significativa es record_size) recibe los bytes del registro del módulo, y flags los indicadores del registro. |
rbamp_std_event_read(dev, back, &ev) |
Obtiene y decodifica la entrada back del registro de eventos (0 = la más reciente). ESP_ERR_NOT_FOUND si no hay ninguna. Los tipos de evento son las constantes generadas RBAMP_STD_EV_* (reinicio / adopción del contador de vida útil, guardado de calibración, confirmación de firmware, borrado del historial, ...). |
Autenticidad
Un módulo aprovisionado lleva un certificado de dispositivo firmado con la clave del fabricante y responde a un desafío con una firma digital mediante la clave del dispositivo nombrada en ese certificado. La biblioteca obtiene ambos; verificarlos es tarea de la aplicación (con la biblioteca de firma que elija).
typedef struct {
uint8_t raw[RBAMP_STD_REG_SEC_CERT_SIZE]; /* certificate bytes as read */
uint8_t state; /* the module's own check: 0 none · 1 ok · 2 bad · 3 not checked yet (shortly after boot) */
uint8_t version, variant, hw_rev;
uint8_t uid[12]; /* chip UID the certificate was issued for (compare with rbamp_read_uid) */
uint32_t batch, issued; /* production batch; issue time, unix */
uint8_t device_pubkey[32];
uint32_t mfr_key_id;
} rbamp_std_certificate_t;
typedef struct {
uint8_t signature[64]; /* signature over the attested message */
uint8_t data[24]; /* attested data exactly as signed */
uint32_t fw_version, generation; /* from data */
int64_t e_import_wh, e_export_wh; /* from data: life-time import / export, Wh */
} rbamp_std_attestation_t;
| Función | Descripción |
|---|---|
rbamp_std_read_certificate(dev, &cert) |
Lea el certificado del dispositivo. ESP_ERR_NOT_FOUND si el módulo no tiene ninguno (sin aprovisionar; state se rellena igualmente); ESP_ERR_NOT_SUPPORTED por debajo del mapa 0x35. |
rbamp_std_attest(dev, challenge, &att) |
Desafíe al módulo con 32 bytes aleatorios de su elección (guarde su copia: el módulo sobrescribe el área del desafío con la firma) y obtenga la respuesta firmada (unos 60 ms). Los datos certificados vinculan la versión del firmware y los contadores de vida útil a la clave del dispositivo. ESP_ERR_NOT_FOUND si el módulo no tiene clave de dispositivo; ESP_ERR_INVALID_STATE si el módulo no informó de que la certificación estaba completa. |
Actualización de firmware (OTA)
Una actualización en dos fases por I²C. Todas las funciones de este apartado devuelven ESP_ERR_NOT_SUPPORTED salvo que el módulo informe de la capacidad OTA (mapa 0x33 o posterior). Cada comando se completa de forma síncrona dentro de la biblioteca (espera al estado de comando del módulo, no a un retardo fijo).
Secuencia: rbamp_std_ota_begin → rbamp_std_ota_write_page × N (páginas de 256 bytes; las páginas en blanco 0xFF pueden omitirse) → rbamp_std_ota_commit (verifica y arma el intercambio, sin reiniciar) → rbamp_std_ota_activate (reinicia en la nueva imagen cuando usted lo decida). El módulo queda fuera del bus unos segundos y después ejecuta una prueba de unos 10 s antes de confirmar la imagen. Tras cada página la sesión debe seguir abierta; si no, la llamada falla con ESP_ERR_INVALID_STATE (reinicie desde begin). Una imagen defectuosa la revierte el propio módulo; la calibración se conserva.
Solo se aceptan imágenes preparadas por el fabricante. Las imágenes de versión las produce la herramienta del fabricante del módulo (firmadas y, cuando se exige, cifradas); el módulo rechaza cabeceras generadas en el host en la confirmación. Por tanto, rbamp_std_ota_write_image() (imagen generada en el host, sin firmar) devuelve ESP_ERR_NOT_SUPPORTED antes de tocar el módulo y se conserva solo por compatibilidad ABI.
| Función | Descripción |
|---|---|
rbamp_std_ota_status(dev, &st) |
El estado OTA del módulo (RBAMP_STD_OTA_IDLE / READY / OK / ERR / DOWNGRADE). |
rbamp_std_ota_begin(dev, timeout_ms) |
Borre la imagen inactiva y espere a que el módulo informe de LISTO. timeout_ms 0 = por defecto (5 s). ESP_ERR_TIMEOUT si no se llegó a LISTO. |
rbamp_std_ota_write_page(dev, page_idx, page) |
Escribe una página de 256 bytes en el índice page_idx (desplazamiento / 256 dentro del banco). ESP_ERR_INVALID_STATE si el módulo marca un error de escritura. |
rbamp_std_ota_commit(dev, timeout_ms) |
Verifica la imagen escrita y arma el intercambio de bancos. timeout_ms 0 = por defecto (3 s). ESP_OK armado · ESP_ERR_INVALID_CRC imagen defectuosa (CRC / cabecera) · ESP_ERR_INVALID_MAC autenticación fallida · ESP_ERR_INVALID_VERSION imagen anterior a la que se ejecuta · ESP_ERR_TIMEOUT. |
rbamp_std_ota_diag(dev, &reason) |
Motivo por el que el módulo rechazó la última página o confirmación: el byte de motivo de sus diagnósticos OTA (0 = ninguno). rbamp_std_ota_commit() ya asigna el motivo al código de error indicado arriba y registra su nombre; llame a esta función cuando necesite el código en sí. |
rbamp_std_ota_activate(dev) |
Reinicie en la imagen armada, espere a que el módulo vuelva (unos 4 s), vuelva a descubrirlo y manténgalo durante la ventana de prueba y confirme: cambió el banco en ejecución, la imagen en ejecución es la versión preparada, el intercambio ya no está pendiente. Bloquea unos 10 s en total — no reinicie ni corte la alimentación del módulo en ese intervalo (el cargador de arranque revierte una imagen no confirmada). El manejador sigue siendo válido y rbamp_std_info() refleja el nuevo firmware. ESP_ERR_INVALID_STATE si no había nada armado, si el módulo volvió con la imagen anterior (reversión) o si el intercambio sigue pendiente tras la prueba. |
rbamp_std_ota_staged_version(dev, &v) |
Versión de la imagen armada (confirmada, pero no activada); 0 cuando no hay nada armado (mapa 0x35+). |
rbamp_std_ota_abort(dev) |
Cierre una sesión de actualización y desarme una imagen armada; el módulo sigue ejecutando lo que ejecuta (mapa 0x35+). |
rbamp_std_ota_board_ok(dev, image_board_word) |
Comprobación previa antes de transmitir una imagen preparada: la palabra de placa de la imagen (entregada junto al archivo de imagen por la herramienta del fabricante) debe coincidir con el identificador de placa del módulo. ESP_OK si coincide; ESP_ERR_INVALID_ARG si no (se registra); ESP_ERR_NOT_SUPPORTED por debajo del mapa 0x36. |
rbamp_std_ota_write_prepared(dev, image, size, cb, ctx) |
Transmite una imagen de banco preparada tal cual: inicio, páginas en orden ascendente (la página 0 se envía siempre; las demás páginas de 0xFF completas se omiten), confirmación. La biblioteca no modifica nada. No activa. size debe ser igual al tamaño de banco que informa el módulo (rbamp_std_info_t.ota_bank_size); en otro caso, ESP_ERR_INVALID_SIZE y no se escribe nada. cb(done, total, ctx) es un callback opcional de progreso (rbamp_std_ota_progress_cb_t). |
rbamp_std_ota_write_prepared_pair(dev, bank_a, size_a, bank_b, size_b, cb, ctx) |
Igual que antes, con ambas imágenes de banco: la biblioteca pregunta al módulo qué banco está en ejecución y transmite el otro. ESP_ERR_NOT_SUPPORTED en los módulos que no informan del banco en ejecución (mapa inferior a 0x35): en ese caso use rbamp_std_ota_write_prepared() y elija usted según active_bank. |
rbamp_std_crc32(data, len) |
CRC-32 (compatible con zlib): la suma de verificación que el módulo comprueba al confirmar. |
rbamp_std_ota_make_header(out, version, len, crc32) |
Construye la cabecera de imagen en little-endian. Disponible solo cuando el archivo de registros generado define las constantes de la cabecera; se mantiene por compatibilidad ABI. |
Diagnóstico
rbamp_err_to_str
const char *rbamp_err_to_str(esp_err_t err);
Devuelve un puntero a una cadena estática con una descripción legible del código de error. Nunca devuelve NULL. Usa esp_err_to_name() estándar para los códigos del sistema, y amplía las descripciones para las semánticas específicas de rbamp (por ejemplo, lo que significa ESP_ERR_INVALID_STATE en el contexto de set_ct_model_ch sin set_sensor_class).
Uso típico:
esp_err_t err = rbamp_read_period_snapshot(dev, &snap, 50, false);
if (err != ESP_OK) {
ESP_LOGE(TAG, "snapshot failed: %s", rbamp_err_to_str(err));
}
rbamp_retry_exhaustion_count / rbamp_sanity_reject_count / rbamp_reset_counters
uint32_t rbamp_retry_exhaustion_count(rbamp_handle_t dev);
uint32_t rbamp_sanity_reject_count (rbamp_handle_t dev);
void rbamp_reset_counters (rbamp_handle_t dev);
Getters públicos de dos contadores de diagnóstico (ambos devuelven 0 con un manejador NULL):
-
rbamp_retry_exhaustion_count(dev): contador monótono de eventos de «presupuesto de reintentos agotado». Cada incremento = una transacción de un byte que, trasCONFIG_RBAMP_NACK_RETRY_ATTEMPTSintentos, nunca recibió un ACK del dispositivo. -
rbamp_sanity_reject_count(dev)— un contador monótono de rechazos del filtro de cordura en las lecturas de float (NaN, Inf o un valor absoluto por encima del límite de cada magnitud —RBAMP_SANITY_LIMIT_V/_I/_P/_PF). Cada incremento = un float que llegó por el bus, se juzgó que no se parecía a un valor físico y se descartó; la lectura devuelveESP_ERR_INVALID_RESPONSE.
rbamp_reset_counters(dev) pone a cero ambos contadores de este manejador (operación nula para NULL). Está pensada para escenarios de prueba que necesitan una línea base limpia. Para la supervisión en producción, prefiera el patrón canónico de «tasa en un intervalo»: instantánea y diferencia, robusto frente a ventanas de reinicio perdidas:
uint32_t prev = rbamp_retry_exhaustion_count(dev);
/* ...60 s of normal operation... */
uint32_t delta = rbamp_retry_exhaustion_count(dev) - prev;
if (delta > THRESHOLD) { /* alert */ }
Estos nombres coinciden con la biblioteca Arduino en todas las plataformas (dev.retryExhaustionCount() / dev.sanityRejectCount(): la misma semántica, en snake_case). Para cargas prácticas y umbrales de alarma, véase 10 · Solución de problemas, sección «Monitorización de contadores».
Registro mediante esp_log
El componente registra con la etiqueta "rbamp". El nivel de registro se compila mediante Kconfig: esp_log_level_set("rbamp", ...) en tiempo de ejecución funciona, pero está limitado desde arriba por el nivel de compilación.
esp_log_level_set("rbamp", ESP_LOG_DEBUG); /* for debugging */
Códigos de error
Las funciones rbamp_* devuelven valores esp_err_t estándar. Los códigos concretos y su significado en el contexto de rbamp:
| Código | Cuándo | Dónde buscar |
|---|---|---|
ESP_OK (0) |
Éxito | — |
ESP_FAIL (-1) |
La transacción I²C falló tras los reintentos | cableado, alimentación, velocidad del bus: sección «El módulo no responde por I²C» en 10 · Solución de problemas |
ESP_ERR_INVALID_ARG (0x102) |
Argumento no válido: dev == NULL, channel o phase fuera de rango, un cls no reconocido, o un valor que el módulo rechaza (modelo de CT desconocido, corriente de arranque fuera del conjunto aceptado, un reloj anterior a 2020) |
compruebe los argumentos de la llamada |
ESP_ERR_TIMEOUT (0x107) |
rbamp_wait_ready / rbamp_wait_data_ready expiraron; expiró la ventana de rbamp_commit_address_change (5 s); un comando STD o un estado OTA no se completó |
compruebe la respuesta mediante rbamp_probe() |
ESP_ERR_INVALID_STATE (0x103) |
Una precondición o una secuencia de llamadas es incorrecta: set_ct_model* antes de set_sensor_class; el módulo es de clase 2 / 3 (calibrado con su sensor: use rbamp_set_ct_model_ch_force() para el servicio); el módulo rechazó el par (clase, modelo); la confirmación de dirección no está armada; el banco de instantáneas STD se rearmó tras un reinicio del módulo (descarte este periodo); el contador de la generación STD cambió (rbamp_std_energy_delta); sesión OTA no abierta |
sección "rbamp_set_* devuelve ESP_ERR_INVALID_STATE" en 10 · Solución de problemas |
ESP_ERR_NOT_SUPPORTED (0x106) |
La función o la característica no existe en esta línea / firmware / módulo: cualquier llamada rbamp_std_* sobre un manejador BASIC, potencia reactiva / aparente en BASIC, rbamp_read_digest en STD o sin la capacidad de digest, llamadas de período en un módulo STD sin bancos de instantáneas ni contadores, rbamp_factory_reset en STD, una versión del mapa de registros demasiado antigua, OTA sin la capacidad |
compruebe rbamp_line(dev), rbamp_std_info() y rbamp_variant(dev) |
ESP_ERR_NOT_FOUND |
Nada presente: rbamp_std_probe — nada responde en la dirección; no hay tal registro de historial / eventos; ni certificado ni clave del dispositivo; confirmación de dirección — nada responde en la nueva dirección (el manejador conserva la anterior) |
compruebe el cableado y la dirección; retroceda back solo hasta rbamp_std_hist_info().count |
ESP_ERR_INVALID_RESPONSE (0x108) |
Instantánea de periodo desactualizada (indicador de listo = 0) o periodo omitido (contadores STD reanclados, banco rearmado); REG_VERSION = 0/0xFF en rbamp_begin; un float no superó el filtro de cordura; frecuencia de red STD 0 (sin red); rbamp_std_probe — responde algo que no es un módulo STD |
sección «Las instantáneas de periodo siempre están desactualizadas» / «No se puede salir de rbamp_begin» en 10 · Solución de problemas |
ESP_ERR_NO_MEM (0x101) |
No se pudo reservar memoria para el manejador; más de 4 líneas DRDY / 8 manejadores por línea | compruebe el presupuesto de memoria heap |
ESP_ERR_NOT_FINISHED |
STD: la escritura en flash del módulo está limitada en frecuencia | reintente tras unos 5 s |
ESP_ERR_INVALID_CRC, ESP_ERR_INVALID_MAC, ESP_ERR_INVALID_VERSION, ESP_ERR_INVALID_SIZE, ESP_ERR_NOT_ALLOWED |
Veredictos de comando / OTA STD: falló una comprobación de valor o de imagen, falló la autenticación, la imagen es más antigua que la que está en ejecución, la imagen no cabe en el banco, el módulo rechazó la operación (véase rbamp_std_command, rbamp_std_ota_commit) |
rbamp_std_ota_diag() para conocer el motivo |
Todos los códigos devueltos pueden imprimirse de forma legible mediante rbamp_err_to_str().
Configuración en tiempo de compilación (Kconfig)
Los siguientes símbolos CONFIG_RBAMP_* están disponibles en idf.py menuconfig → Configuración de componentes [Component config] → cliente rbAmp:
| Símbolo | Tipo | Rango / opción | Predeterminado | Finalidad |
|---|---|---|---|---|
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ |
int | 50000–1000000 Hz | 50000 | Frecuencia de SCL. 50 kHz es la exigencia del firmware actual en ESP32. |
CONFIG_RBAMP_I2C_TIMEOUT_MS |
int | 10–1000 ms | 100 | Tiempo de espera de i2c_master_transmit/receive. Debe ser lo bastante largo para absorber la latencia previa a la lectura del módulo. |
CONFIG_RBAMP_I2C_SCL_WAIT_US |
int | 2000–60000 µs | 10000 | Tolerancia de estiramiento del reloj SCL: cuánto tiempo deja el periférico I²C que el módulo mantenga SCL en bajo antes de abandonar la transacción. El valor por defecto del driver es 2 ms; un módulo estira SCL más tiempo mientras borra un sector de flash durante una actualización de firmware, y cada estiramiento así terminaría en una línea de registro «I2C hardware timeout» y un reintento. 10 ms cubre el borrado del sector. El ESP32 original no puede esperar más de unos 13 ms (contador hardware de 20 bits); el componente recorta el valor a ese límite en ese objetivo. |
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS |
int | 1–10 | 3 | Intentos por lectura de un byte. |
CONFIG_RBAMP_NACK_RETRY_GAP_MS |
int | 1–100 ms | 5 | Pausa entre intentos de reintento. |
CONFIG_RBAMP_BUS_RESET_ON_RETRY_EXHAUSTION |
bool | n/y | n | Cuando fallan todos los reintentos NACK de una transacción, llame una vez a i2c_master_bus_reset() antes del último intento. El driver de IDF ya reinicia su máquina de estados tras cada transacción fallida, y el reinicio explícito no toma ningún bloqueo del bus: con varias tareas compartiendo el bus puede interrumpir una transacción de otra tarea (en ESP32 genera un STOP en los pines, que el manejador de interrupciones del driver puede confundir con el fin de una lectura). Déjelo desactivado salvo que el maestro sea de una sola tarea y el bus se quede bloqueado tras errores del driver. |
CONFIG_RBAMP_SCT_RATING_CORRECTION |
bool | n/y | y | Corrección de las lecturas de la SCT-013 en el firmware BASIC hasta 1.4.19, que mantiene la calibración de 30 A tras cambiar el usuario el canal a otro modelo. La biblioteca escala la corriente, la potencia, la potencia de periodo, la energía y el resumen al modelo seleccionado (rbamp_sct_correction() informa del resultado por canal). Un módulo que se corrige por sí mismo (firmware 1.4.20 y posteriores) no se ve afectado. Desactívelo para leer los valores brutos del módulo. Véase Corrección de la clasificación de la SCT-013. |
CONFIG_RBAMP_DRDY_POLL_MS |
int | 5–50 ms | 20 | Cuando un manejador no tiene GPIO DRDY, rbamp_wait_data_ready() sondea el contador de publicación del módulo (STD) o la secuencia de confirmación (BASIC) con este intervalo. El módulo publica cada 100 ms (imágenes antiguas: 200 ms). |
CONFIG_RBAMP_DISABLE_ENERGY |
bool | n/y | n | Elimina por completo el acumulador de Wh de la compilación (almacenamiento y API). |
CONFIG_RBAMP_LOG_LEVEL_* |
elección | NONE / ERROR / WARN / INFO / DEBUG | INFO | LOG_LOCAL_LEVEL en tiempo de compilación para la etiqueta rbamp. Controla si las cadenas de registro se compilan en el binario; es independiente de CONFIG_LOG_DEFAULT_LEVEL. |
Un sdkconfig.defaults de ejemplo para un caso típico de producción:
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=3
CONFIG_RBAMP_NACK_RETRY_GAP_MS=5
CONFIG_RBAMP_I2C_TIMEOUT_MS=100
CONFIG_RBAMP_LOG_LEVEL_INFO=y
# leave CONFIG_RBAMP_DISABLE_ENERGY disabled (default n)
Para una prueba de banco bajo carga intensa:
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=5
CONFIG_RBAMP_I2C_TIMEOUT_MS=200
CONFIG_RBAMP_LOG_LEVEL_DEBUG=y
Constantes de tiempo de estabilización
El componente usa internamente las siguientes pausas de asentamiento al ejecutar comandos (para un usuario que trabaja sobre la API en bruto mediante i2c_master_transmit_receive y quiere respetar los mismos tiempos):
La biblioteca exporta un pequeño conjunto de constantes de tiempo de asentamiento (ms) para los usuarios de la API en bruto que envían comandos directamente al dispositivo y deben esperar a que termine de procesarlos antes de leer los registros afectados. Las funciones envolventes del componente (rbamp_save_gains, rbamp_factory_reset, rbamp_set_ct_model_ch, etc.) mantienen internamente la pausa correcta; estas constantes solo son necesarias si omite las funciones envolventes.
| Macro | Finalidad | ms |
|---|---|---|
RBAMP_SETTLE_MS_LATCH_PERIOD |
Tras CMD_LATCH_PERIOD |
50 |
RBAMP_SETTLE_MS_RESET |
Tras CMD_RESET |
100 |
RBAMP_SETTLE_MS_SAVE_GAINS |
Tras CMD_SAVE_GAINS (borrado y escritura de flash) |
700 |
RBAMP_SETTLE_MS_FACTORY_RESET |
Tras CMD_FACTORY_RESET |
1500 |
RBAMP_SETTLE_MS_SET_CT_MODEL_CH0 |
Tras CMD_SET_CT_MODEL_CH0 |
5 |
RBAMP_SETTLE_MS_SET_CT_MODEL_CH1 |
Tras CMD_SET_CT_MODEL_CH1 |
5 |
RBAMP_SETTLE_MS_SET_CT_MODEL_CH2 |
Tras CMD_SET_CT_MODEL_CH2 |
5 |
La fuente de verdad es el bloque @defgroup rbamp_settle_ms de include/rbamp.h. Las cifras son los mínimos de especificación del protocolo rbAmp: no puede ir más corto, pero sí más largo.
Detalles del protocolo de bus
Lecturas de registros — autoincremento
Una lectura en ráfaga devuelve N bytes consecutivos a partir de addr. Ejemplo: una única transacción i2c_master_transmit_receive(slave, {0x86}, 1, buf, 16, ...) lee 16 bytes desde 0x86 (U_RMS + U_PEAK + I_RMS + I_PEAK en UI1).
Escrituras de registros: byte a byte (NO autoincrementa)
llegansolo el primer byte— los bytes 1..N se descartan.
Un registro de varios bytes se escribe byte a byte — una transacción I²C independiente de un solo byte por dirección:
/* WRONG — data loss */
uint8_t label[8] = "MyMeter1";
uint8_t buf[9] = { 0x68, 'M', 'y', 'M', 'e', 't', 'e', 'r', '1' };
i2c_master_transmit(slave, buf, 9, 100); /* only 'M' lands */
/* CORRECT — byte-at-a-time loop */
for (int i = 0; i < 8; i++) {
uint8_t tx[2] = { 0x68 + i, label[i] };
i2c_master_transmit(slave, tx, 2, 100);
}
Afecta a los registros escribibles de varios bytes: LABEL (0x68-0x6F), U_GAIN / I_GAIN (f32, restringidos a fábrica), NF (u16), THRESH (u16). Las lecturas admiten ráfagas (el autoincremento funciona en LECTURA).
Lectura de registros no asignados
Cualquier lectura de una dirección no asignada devuelve 0x00. El firmware nunca responde con NACK en las lecturas de registros. La detección de un dispositivo ausente debe hacerse mediante el ACK de la trama de dirección I²C, no mediante sondeo de registros.
Detección de variante
El byte de SKU autorizado es el registro 0x55 (guardado en caché como rbamp_variant()):
| 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) |
0x08 |
UI7 (7× I + U) |
rbamp_topology() es auxiliar; devuelve solo el número de canales (1/2/3/5/7) y no distingue la presencia de U.
⚠ REG_SENSOR_CLASS (0x25) NO es un discriminador de variante (se aprovisiona por configuración del usuario). El invariante de variante = HW_VARIANT (0x55) + CAPABILITY (0x57/0x58), ambos de solo lectura.
CAPABILITY (0x57/0x58, u16 LE) — mapa de detección de funciones
Un mapa de las capacidades del dispositivo (por ejemplo: presencia de la etapa de tensión, instantánea GC soportada, bloque de digest, indicadores de evento, cambio de dirección en dos fases). Es la forma canónica de detectar funciones (en lugar de comparar versiones numéricas). Compruebe cada indicador con las funciones auxiliares; el conjunto de indicadores crece con el firmware del módulo.
has_voltage (sin leer HW_VARIANT):
/* Option 1 — the cached helper (no bus traffic after rbamp_begin). */
bool has_voltage = rbamp_has_voltage(dev);
/* Option 2 — read the full 16-bit CAPABILITY (LE). */
uint16_t cap;
rbamp_read_capability(dev, ∩);
bool has_voltage_2 = (cap & RBAMP_CAP_ZC_PHASE_OFFSET) != 0; /* voltage front-end flag */
Ambas opciones son equivalentes.
Coherencia HW_VARIANT ⟷ CAPABILITY: HW_VARIANT 1..3 (UI) → indicador de la etapa de entrada de tensión activado; HW_VARIANT 4..6 (I) → indicador desactivado. Una incoherencia = una anomalía de hardware.
Atomicidad / congelación de lectura (B1)
- Bloque RMS en coma flotante V03 (0x86+: U_RMS, U_PEAK, I_RMS, I_PEAK, P, PF, frecuencia): congelación de lectura presente, la lectura en ráfaga es atómica.
- Bloque digest (0x70-0x85) — congelación de lectura presente.
- GC_TICK (0x59) / espejo de dirección (0x30) / espejos de modelo de CT (0x51-0x53): sin congelación de lectura; para una lectura fiable use el patrón leer dos veces y comprobar que coinciden (lea dos veces y considere válido el valor solo si ambas lecturas coinciden).
Semántica de pinza NF
I_RMS = 0x00000000 significa «señal por debajo del suelo de ruido» (el firmware calcula rms_corr² = max(0, raw² − nf²)), NO «sin datos» / «error». Es una medición válida para escenarios sin carga.
Registros solo de tensión en variantes solo de corriente
U_RMS, U_PEAK en I1/I2/I3 se leen como 0. Solo son válidos cuando el indicador de etapa de tensión de CAPABILITY está activo. REG_AC_FREQ procede de la detección de cruce por cero y está disponible en todas las variantes (incluidas las I*).
Instantánea por difusión General-Call (sincronización multimódulo)
Opción por módulo mediante bit0 del registro REG_FLEET_CONFIG (0x27) — GC_ENABLE. Desactivado por defecto. Se habilita con CMD_SAVE_USER_CONFIG + CMD_RESET (suave o duro). Tras un reinicio, el módulo escucha la trama de difusión en la dirección general-call de I²C 0x00:
addr=0x00 | A5 27
A5: magic.27: el código de operaciónCMD_LATCH_PERIOD.—0x00= llamada general, en otro caso debe coincidir conREG_GROUP_ID(0x28).: contador de período de 16 bits (sincronización del master).
La trama solo dispara la instantánea de periodo; nunca lleva códigos de operación destructivos.
Detección del modo de fallo (dos niveles, validado en HW C.10):
- NACK de la dirección general (GC) (inmediato, a nivel de bus): si GC está desactivado en toda la flota,
i2c_master_transmita0x00devuelveESP_FAIL/ESP_ERR_INVALID_STATE. Es un error duro, no un descarte silencioso. La biblioteca interpreta el NACK como «GC no habilitado» (exige las condiciones previas de habilitar y reiniciar). - Testigo por módulo (tras el asentamiento): si no hubo ningún NACK, el maestro lee
REG_V03_PERIOD_VALID (0x07)en cada esclavo esperado:1= la instantánea tuvo éxito,0= GC desactivado en este módulo concreto, o el periodo está vacío.
Enlaces
- 05 · Inicio rápido — su primer proyecto funcionando
- 06 · Ejemplos — escenarios de trabajo
-
10 · Solución de problemas — interpretación de errores y resolución de problemas habituales
-
El archivo de cabecera fuente con comentarios Doxygen:
include/rbamp.h
Apéndice: por dentro
Trasladado desde el capítulo de Visión general: comparación a nivel de registro, arquitectura y diagramas de interacción.
Sin el componente (acceso directo mediante i2c_master_transmit_receive)
// Read U_RMS — a single 4-byte burst-read (the firmware supports
// address auto-increment on read).
i2c_master_dev_handle_t slave;
i2c_master_bus_add_device(bus, &(i2c_device_config_t){
.device_address = 0x50, .scl_speed_hz = 50000,
}, &slave);
uint8_t reg = 0x86, buf[4] = { 0 };
if (i2c_master_transmit_receive(slave, ®, 1, buf, 4,
/*xfer_timeout_ms=*/100) != ESP_OK) {
return; // handle the error
}
float u_rms;
memcpy(&u_rms, buf, sizeof(float));
Con el componente
float u_rms;
ESP_ERROR_CHECK(rbamp_read_voltage(dev, 0, &u_rms));
Lectura de un período sin el componente
// Snapshot + 50 ms settle + ready-flag check + burst-read avg_p
uint8_t latch_cmd[2] = { 0x01, 0x27 }; // REG_COMMAND, CMD_LATCH_PERIOD
ESP_ERROR_CHECK(i2c_master_transmit(slave, latch_cmd, 2, /*xfer_timeout_ms=*/100));
int64_t t_latch_us = esp_timer_get_time();
vTaskDelay(pdMS_TO_TICKS(50)); // settle
uint8_t valid_reg = 0x07, valid_byte = 0;
i2c_master_transmit_receive(slave, &valid_reg, 1, &valid_byte, 1, /*xfer_timeout_ms=*/100);
if ((valid_byte & 0x01) == 0) {
// snapshot is stale — t_latch_us STILL must be recorded,
// otherwise the next snapshot will count Wh over two periods
return;
}
// burst-read 4 bytes of avg_p (auto-increment), then assemble the float
// and integrate Wh:
// double dt_s = (esp_timer_get_time() - t_prev_latch_us) / 1e6;
// E_Wh += avg_p * dt_s / 3600.0;
Lectura de un periodo — con el componente
rbamp_period_snapshot_t snap;
if (rbamp_read_period_snapshot(dev, &snap, 50, false) == ESP_OK && snap.valid) {
// snap.avg_p[0] is populated,
// rbamp_energy_wh(dev, 0) has increased by avg_p × master_dt_ms/1000/3600,
// master_dt_ms = master wall-clock dt between snapshots (canonical for energy).
// snap.latch_ms (0xEC) — diagnostic module timer, NOT for energy.
}
Internamente, el componente garantiza:
-
Un asentamiento de 50 ms tras
CMD_LATCH_PERIOD(configurable con el parámetrosettle_ms), lectura correcta de la instantánea (instantánea atómica en el lado del módulo). -
Una comprobación del indicador
REG_V03_PERIOD_VALIDantes de leer (el camposnap.valid). -
Registrar la hora según el reloj del master incluso ante una instantánea obsoleta (protege frente al doble cómputo de Wh en el siguiente período).
-
Acumulación de Wh por canal en doble precisión (el tipo
doubledentro del manejador). -
Carga automática de los coeficientes de calibración al seleccionar el sensor de corriente con
rbamp_set_sensor_class()+rbamp_set_ct_model(): el usuario no necesita conocer los registros internos de calibración.
Cuándo usar el componente y cuándo el acceso directo al bus
| Tarea | Componente | Acceso directo mediante i2c_master_* |
|---|---|---|
| Lectura de U / I / P / FP / frecuencia | ✅ | solo para depuración con analizador lógico |
| Contabilidad de energía por periodo | ✅ | solo si el Wh se guarda fuera del componente (p. ej., en una base de datos del lado del maestro) |
| Varios módulos en un mismo bus | ✅ (instantánea secuencial + asentamiento compartido, véase 06_examples.md) | — |
| Contabilidad bidireccional en BASIC | ✅ (mediante lecturas RT: vea 06_examples.md) | la alternativa es su propio bucle de lecturas RT y la integración manual |
| Adaptación a otra plataforma | n/a | ✅ — véase 09 · Referencia de API para los detalles del protocolo de cable |
| Límite duro de RAM | rara vez importa (~85 bytes por manejador) | ✅ si incluso esos ~85 bytes son críticos |
Para todas las tareas típicas de las primeras filas, el componente es la opción adecuada.
Arquitectura
Diagramas de interacción
El flujo de rbamp_begin()
La primera instantánea es un cebado (el módulo devuelve lo acumulado desde el encendido, que no sirve para la contabilidad tarifaria). El propio componente registra que esta instantánea debe descartarse: el código del usuario nunca la ve.
Flujo rbamp_read_period_snapshot(dev, &snap, 50, false)
La instantánea atómica en el lado del módulo garantiza que cada medición de un periodo caiga en exactamente una instantánea: sin duplicados ni pérdidas en el límite del periodo.
Correspondencia con la API de registros directa
Tabla para quienes migran desde su propio código de acceso directo:
API directa (i2c_master_transmit_receive) |
Equivalente mediante el componente |
|---|---|
Lectura manual de 4 bytes + memcpy |
rbamp_read_voltage(dev, 0, &v) / rbamp_read_power(dev, ch, &p) |
tx([0x01, 0x27]); vTaskDelay(50) |
rbamp_latch_period(dev); vTaskDelay(pdMS_TO_TICKS(50)) (o bien rbamp_read_period_snapshot() directamente) |
Comprobación de read_u8(0x07) & 1 |
el campo snap.valid tras rbamp_read_period_snapshot() |
Fórmula manual E_Wh += avg_p * dt_s / 3600 |
rbamp_energy_wh(dev, 0) — se actualiza automáticamente |
| Configuración manual del sensor de corriente mediante la API de registros directa | rbamp_set_sensor_class(dev, cls) + rbamp_set_ct_model(dev, code): los preajustes de fábrica se cargan automáticamente |
Código fuente y incidencias: rb-amp/rbamp-esp-idf · esta página en el repositorio: docs/09_api_reference.md (v1.7.3)