02 · Líneas de módulos
Los módulos rbAmp se presentan en líneas: BASIC y STANDARD (STD). Una línea de módulos es un paquete completo de revisión de hardware y firmware, no una marca de software. Pasar de una línea a otra requiere un cambio físico de SKU, no una actualización de firmware.
Qué es una línea de módulos
Desde la perspectiva del componente y del código del usuario: un manejador y una API rbamp_* sirven a ambas líneas de módulos comercializadas. rbamp_begin() detecta si el módulo tras el manejador es BASIC o STD (rbamp_line()), y las llamadas que existen solo en una de ellas devuelven ESP_ERR_NOT_SUPPORTED en la otra. Las diferencias aparecen en los valores que devuelve el módulo, en las magnitudes adicionales que mide el módulo STD y en cómo trata el firmware los datos (en particular, la exportación a la red).
Estado actual
Los módulos BASIC y STANDARD (STD) se están entregando y ambos los soporta este componente (versión 1.7.3).
| Línea de módulos | Estado en este componente |
|---|---|
| BASIC | ✅ en envío: RBAMP_LINE_BASIC |
| STANDARD (STD) | ✅ en envío: RBAMP_LINE_STD |
BASIC: línea de módulos de medición de consumo de gama de entrada
Hardware
Una ruta analógica de bajo coste adecuada para cargas domésticas típicas. El módulo incluye una front-end analógica aislada, un regulador de potencia a bordo y calibración de fábrica guardada en flash.
Comportamiento del firmware
La lógica de un contador de disco mecánico clásico: el conteo solo avanza, y la exportación a la red no se resta.
Las tres "capas" de valores de potencia activa se comportan de forma distinta:
| Señal | Significado | Comportamiento en BASIC |
|---|---|---|
rbamp_read_power(dev, ch, &p) |
potencia RT instantánea, actualizada cada ~100 ms | con signo: un valor negativo se ve en tiempo real (exportación) |
snap.avg_p[ch] (dentro de rbamp_read_period_snapshot) |
potencia media durante el periodo | cada ventana de 100 ms de P media se limita a max(P, 0) antes de sumarse al acumulador del período |
rbamp_energy_wh(dev, ch) |
Wh acumulados por el componente | monótono: solo consumo; la exportación no se cuenta |
En otras palabras: el usuario ve la exportación en la lectura RT, pero el contador de Wh del componente en BASIC no la incluye.
Aplicaciones típicas
-
Hogares sin generación propia (sin paneles solares, aerogeneradores ni sistemas de baterías)
-
Submedidores para cargas puramente consumidoras (calentadores de agua, motores, electrodomésticos)
-
Monitorización del consumo en edificios donde no se requiere medición bidireccional
Medición bidireccional en BASIC (en el lado del maestro)
rbamp_read_power(dev, 0, &p)tiene signo, así que:
#include "esp_timer.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
static double consume_wh = 0.0;
static double export_wh = 0.0;
void bidirectional_loop(rbamp_handle_t dev) {
int64_t t_prev_us = esp_timer_get_time();
while (1) {
/* Sample RT power at 10 Hz. Slower polling loses resolution
* on sharp load transitions; faster adds little for typical
* mixed loads with an inverter. */
vTaskDelay(pdMS_TO_TICKS(100));
int64_t t_now_us = esp_timer_get_time();
double dt_s = (double)(t_now_us - t_prev_us) / 1e6;
t_prev_us = t_now_us;
float p;
if (rbamp_read_power(dev, 0, &p) != ESP_OK) continue;
double dwh = (double)p * dt_s / 3600.0;
if (p >= 0.0f) consume_wh += dwh;
else export_wh += -dwh;
}
}
Un ejemplo completo y funcional del patrón está en 06_examples.md, en el escenario «Medición bidireccional en el lado del maestro».
STANDARD (STD): la línea de módulos de medición ampliada
Los módulos STD los soporta la misma API rbamp_*; rbamp_begin() los detecta. Además de lo que ofrece BASIC, un módulo STD proporciona:
-
Energía con signo. Importación y exportación son magnitudes separadas, y el módulo guarda contadores de vida persistentes (Wh / varh, y resoluciones más finas en firmware más reciente). La exportación no se descarta: la energía de un periodo es la diferencia entre dos lecturas de contador (
rbamp_std_read_energy()/rbamp_std_energy_delta()), yrbamp_energy_wh()devuelve un valor neto con signo en esos módulos. -
Más magnitudes: potencia reactiva y aparente por canal (
rbamp_read_reactive_power(),rbamp_read_apparent_power(),rbamp_std_read_channel()), totales por fase y generales y, una vez activada la extracción de armónicos, THD y factor de potencia de desplazamiento. Los módulos trifásicos también informan de los ángulos de fase de tensión y de la secuencia de fases. -
Mecanismos de periodo: bancos de instantáneas (ocho independientes, con periodos controlados por el maestro) en los módulos que los tienen, o diferencias de contadores en los módulos que guardan la energía en el dispositivo. El mecanismo se elige en
rbamp_begin()(rbamp_std_info_t.period_source). -
El modelo de CT es solo una etiqueta. En un módulo STD el modelo de CT es solo una etiqueta y no fija ninguna ganancia.
- Reloj del módulo, historial en el dispositivo y registro de eventos, salud y diagnósticos, actualización de firmware por I²C, certificado de dispositivo y atestación.
Todo esto está documentado en 09 · Referencia de la API, capítulo «Línea STD». Un ejemplo de trabajo es examples/std_meter/ (vea 06 · Ejemplos, Escenario 18).
Comportamiento que difiere de BASIC
| Tema | BASIC | STD |
|---|---|---|
Exportación en rbamp_energy_wh() |
no contabilizada (monotónico, solo consumo) | con signo: neto de importación y exportación |
| Potencia reactiva / aparente, THD | no disponible — en BASIC, la potencia reactiva no se expone en esta biblioteca (ESP_ERR_NOT_SUPPORTED) |
disponible |
| Fuente del período | instantánea del acumulador del período | bancos de instantáneas, o diferencias de contadores |
| Reloj del módulo | ninguno | fíjela con rbamp_std_set_time() tras cada reinicio del módulo |
rbamp_factory_reset() |
compatible | ESP_ERR_NOT_SUPPORTED |
Resumen (rbamp_read_digest()) |
compatible con firmware que tenga la capacidad | ESP_ERR_NOT_SUPPORTED |
| Llamadas de período en un módulo sin bancos de instantáneas ni contadores | — | ESP_ERR_NOT_SUPPORTED |
Aplicaciones típicas
- Viviendas con generación solar en tejado, aerogeneradores o baterías
- Cargas regenerativas, carga de vehículos eléctricos V2G
- Instalaciones que necesitan potencia reactiva, factor de potencia y armónicos además de la potencia activa
Cómo detectar la línea del módulo en tiempo de ejecución
rbamp_begin():
/* BASIC or STD — available after rbamp_begin() */
rbamp_line_t line = rbamp_line(dev); /* RBAMP_LINE_BASIC / RBAMP_LINE_STD */
/* Full SKU — cached by rbamp_begin(), no bus traffic */
rbamp_variant_t variant = rbamp_variant(dev); /* UI1 / UI2 / ... / I3 / UI5 / UI7 */
/* Voltage-sensing presence (UI* variants vs I*-only) */
bool voltage_hw = rbamp_has_voltage_hw(dev);
/* Number of current channels (1 / 2 / 3 / 5 / 7) */
uint8_t channels = rbamp_channels(dev);
/* Firmware: BASIC — REG_VERSION byte; STD — register-map version */
uint8_t fw = rbamp_firmware_version(dev);
/* STD only: identity, capabilities and the period mechanism */
rbamp_std_info_t info;
if (rbamp_line(dev) == RBAMP_LINE_STD && rbamp_std_info(dev, &info) == ESP_OK) {
/* info.capabilities, info.n_voltage, info.n_current, info.period_source */
}
: rbamp_line() distingue BASIC de STD. Use la etiqueta SKU de la carcasa del módulo como fuente de verdad para el producto exacto.
Dónde se marcan en la documentación los detalles que dependen de la línea
En el texto del componente y en la documentación canónica, las funciones que dependen de la línea se marcan explícitamente, por ejemplo:
— esta función no está disponible en el módulo BASIC (ESP_ERR_NOT_SUPPORTED).
O, al contrario, comportamiento exclusivo de BASIC:
: el contador rbamp_energy_wh(dev, ch) es monotónico — la exportación a la red no se cuenta. Para medición bidireccional, véase el escenario «Medición bidireccional en el lado del maestro» en 06_examples.md, o use un módulo STD.
Lo que viene después
-
03 · Selección del sensor de corriente — qué SCT-013 para cada uso
-
04 · Cableado: matices de hardware
-
06 · Ejemplos: escenarios para BASIC, incluida la medición bidireccional en el lado del master
-
09 · Referencia de la API: la API pública completa
Código fuente y incidencias: rb-amp/rbamp-esp-idf · esta página en el repositorio: docs/02_tiers.md (v1.7.3)