rbAmp
ES
Tienda
Docs
Actualizado · Editar en GitHub

02 · Niveles de módulo

Las líneas de módulos BASIC y STANDARD (STD) lado a lado: energía en el maestro para BASIC, en el módulo para STD.

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)

Contabilidad de energía en BASIC (consumo en el módulo, exportación integrada en el maestro) y en STANDARD (STD) (contadores de importación, exportación y neto en el módulo).

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:

C++
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() y readPeriodSnapshot() toman las cifras propias del módulo (wh_net = importación − exportación), y stdReadEnergy() 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 con stdReadTotals(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.

Dependencia de la imagen.

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

Cómo saber qué línea de módulos tiene: lea la etiqueta o llame a line() tras begin().

C++
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 …
Nota

: 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:

solo STANDARD (STD)

— esto no está disponible en un módulo BASIC.

O, al contrario, comportamiento exclusivo de BASIC:

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


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