rbAmp
ES
Tienda
Docs
Actualizado el · Editar en GitHub [Edit on GitHub]

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

Las líneas de módulos BASIC y STANDARD (STD) una al lado de la otra.

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)

Cómo se produce la energía en un módulo BASIC (integrada en el master) y en un módulo STANDARD (STD) (contadores en el dispositivo).
Si necesita registrar la exportación a la red por separado en un módulo BASIC,hágalo en el lado del master. La potencia RTrbamp_read_power(dev, 0, &p)tiene signo, así que:

C
#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()), y rbamp_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

Diagrama de flujo para saber si tiene un módulo BASIC o STANDARD (STD).
La línea de producto la detecta por ustedrbamp_begin():

C
/* 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 */
}
Nota

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

Solo STD

— esta función no está disponible en el módulo BASIC (ESP_ERR_NOT_SUPPORTED).

O, al contrario, comportamiento exclusivo de BASIC:

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


Código fuente y incidencias: rb-amp/rbamp-esp-idf · esta página en el repositorio: docs/02_tiers.md (v1.7.3)