02 · Niveles de módulo
Qué es una línea de módulos
Compruebe la etiqueta de su módulo; dev.line() indica la línea tras begin().
rbAmp se presenta en líneas de módulos: BASIC y ESTÁNDAR (STD). Una línea de módulos es una combinación completa de revisión de hardware y firmware, no un indicador de software. Cambiar de línea de módulos requiere un cambio físico de SKU, no una actualización de firmware.
Desde la perspectiva de la biblioteca y de su código: una sola clase RbAmp sirve para ambas líneas de producto. begin() detecta si un módulo es BASIC o STANDARD (STD) y enruta internamente cada llamada; los métodos comunes (readVoltage(), readCurrent(), readPower(), readPeriodSnapshot(), energy() …) funcionan en ambas. La línea STD añade llamadas propias: potencia reactiva y aparente, lecturas de bloque por canal, contadores de energía de vida con signo; consulte 09 · Referencia de API.
Estado actual
Los niveles BASIC y la línea STANDARD (STD) son líneas de módulos comercializadas; esta biblioteca admite ambas (STANDARD (STD) desde la biblioteca 1.6.0, véase el README).
| Nivel | Envío |
|---|---|
| BASIC | ✅ sí |
| STANDARD (STD) | ✅ sí (biblioteca 1.6.0+) |
BASIC: nivel de entrada para medición de consumo doméstico
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 mecánico de disco clásico: la cuenta solo avanza; 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 |
|---|---|---|
dev.readPower(ch) |
potencia RT instantánea, actualizada cada ~100 ms | con signo: un valor negativo se ve en tiempo real (exportación) |
PERIOD_AVG_P_W (dentro de readPeriodSnapshot) |
potencia media durante el periodo | cada media de P de una ventana de 100 ms se recorta a max(P, 0) antes de sumarse al acumulador de período |
dev.energy().wh(ch) |
Wh acumulados por la biblioteca | monótono: solo consumo; la exportación no se cuenta |
Dicho de otro modo: el usuario ve la exportación en la lectura RT, pero no aparece en el contador de Wh de la biblioteca en BASIC.
Casos de uso típicos
-
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)
Si necesita registrar la exportación a la red por separado en un módulo BASIC, hágalo en el lado del maestro. La potencia RT dev.readPower(0) tiene signo, así que:
double consume_wh = 0.0;
double export_wh = 0.0;
uint32_t t_prev_ms = millis();
void loop() {
// Sample RT power at 10 Hz — matches the firmware-commit cadence
// (100 ms per channel). Faster gives empty repeat reads; slower
// loses resolution on abrupt load transitions.
//
// delay() blocks the loop — incompatible with concurrent work
// (LCD refresh, MQTT, networking). For sketches with other tasks,
// replace it with a non-blocking millis() / scheduler pattern.
delay(100);
uint32_t t_now_ms = millis();
float dt_s = (t_now_ms - t_prev_ms) / 1000.0f;
t_prev_ms = t_now_ms;
float p = dev.readPower(0);
if (isnan(p)) return;
double dwh = (double)p * dt_s / 3600.0;
if (p >= 0) consume_wh += dwh;
else export_wh += -dwh;
}
Hay un ejemplo completo y funcional en 06_examples.md (el escenario BidirectionalEnergy) y en examples/06_BidirectionalEnergy/.
STANDARD (STD): línea bidireccional
Los módulos STANDARD (STD) son una línea de módulos comercializada. La biblioteca los detecta en begin() (dev.line() == RbAmpLine::Std) y usa el mismo cableado y la misma API común que BASIC (véase 04 · Cableado).
Lo que añade la línea STD
En un módulo STD con contadores de energía persistentes, la API de período/instantánea y la energía provienen de los propios contadores del módulo (los firmwares STD anteriores usan sus bancos de instantáneas); el modelo de CT en STD es solo una etiqueta y no fija ninguna ganancia.
-
Energía con signo: importación y exportación se contabilizan por separado. En módulos que conservan contadores de energía de vida persistidos,
dev.energy()yreadPeriodSnapshot()toman las cifras propias del módulo (wh_net= importación − exportación), ystdReadEnergy()devuelve los contadores en bruto (Wh, mWh y, en las imágenes que los proporcionan, µWh / µvarh). -
Más magnitudes (en BASIC, esta biblioteca no expone la potencia reactiva):
readReactivePower(ch),readApparentPower(ch),stdReadChannel(ch)(I / P / Q / S / PF / pico en una sola ráfaga) y, cuando está habilitado, valores basados en armónicos (THD, factor de potencia de desplazamiento). -
Módulos multicanal / multitensión: el número de canales lo informa el módulo;
stdReadVoltage(v), totales por fase constdReadTotals(k). -
Diagnóstico y servicio:
stdReadHealth(), reloj del módulo, historial y registro de eventos, identificación por UID, actualización de firmware por I²C.
Todo ello figura llamada a llamada en 09 · Referencia de la API § API de la línea STD.
Algunas funciones STD dependen de la versión de imagen del módulo: los contadores de energía de microresolución, la corriente de arranque para la energía, los ángulos de fase de tensión y la secuencia de fases necesitan una versión de imagen de al menos 0x0001007B (dev.stdReadImageVersion()); con una imagen anterior se notifican como «no disponible». Las llamadas exclusivas de STD en un módulo BASIC devuelven RB_ERR_NOT_IMPLEMENTED.
Casos de uso típicos
- Viviendas con generación solar en tejado
- Hogares con aerogeneradores
- Sistemas de almacenamiento con baterías
- Cargas regenerativas
- Carga de VE vehículo-a-red (V2G)
Cómo detectar la línea en tiempo de ejecución
if (!dev.begin()) { /* see dev.errorString() */ }
// Product line, detected by begin(): BASIC or STANDARD (STD)
RbAmpLine line = dev.line(); // RbAmpLine::Basic / RbAmpLine::Std
// Firmware version — opaque byte
uint8_t fw = dev.firmwareVersion();
// Presence of a voltage sensor (UI* variants vs I*-only)
bool voltage_hw = dev.hasVoltageHw();
// Number of current channels
uint8_t channels = dev.channels();
// Full SKU — variant byte (REG_HW_VARIANT)
RbAmpVariant variant = dev.readVariant(); // UI1, UI2, UI3, I1, I2, I3, UI5, UI7 …
: line() indica si es BASIC o ESTÁNDAR (STD). Los demás indicadores (versión de firmware, número de canales, sensor de tensión, SKU) describen el hardware. La etiqueta de SKU de la carcasa del módulo sigue siendo la fuente de referencia del producto.
Dónde se señalan en la documentación los elementos que dependen del nivel
En todo el texto de la biblioteca y en la documentación canónica, las funciones que dependen del nivel se marcan explícitamente, por ejemplo:
— esto no está disponible en un módulo BASIC.
O, al contrario, comportamiento exclusivo de BASIC:
: el contador dev.energy().wh(ch) es monótono: la exportación a la red no se cuenta. Para la medición bidireccional, véase el ejemplo BidirectionalEnergy o use un módulo STANDARD (STD).
Lo que viene después
-
03 · Selección de sensor de corriente: qué SCT-013 para cada tarea
-
04 · Cableado — detalles de hardware
-
06 · Ejemplos — escenarios para BASIC, incluida la medición bidireccional en el lado del maestro
-
09 · Referencia de la API: la API pública completa
Fuente y incidencias: rb-amp/rbamp-arduino · esta página en el repositorio: docs/02_tiers.md (v1.6.2)