rbAmp
IT
Negozio
Docs
Aggiornato il · Modifica su GitHub

02 · Linee di moduli

I moduli rbAmp si presentano in linee di moduli: BASIC e STANDARD (STD). Una linea è un pacchetto completo di revisione hardware e firmware, non un flag software. Il passaggio tra linee richiede un cambio fisico di SKU, non un aggiornamento firmware.

Che cosa è una linea di moduli

Le linee di moduli BASE e STANDARD (STD) affiancate.

Dal punto di vista del componente e del codice utente: un solo handle e una sola API rbamp_* servono entrambe le linee di moduli in produzione. rbamp_begin() rileva se il modulo dietro l'handle è BASE o STD (rbamp_line()), e le chiamate che esistono solo su una delle due restituiscono ESP_ERR_NOT_SUPPORTED sull'altra. Le differenze appaiono nei valori che il modulo restituisce, nelle grandezze extra che il modulo STD misura, e nel modo in cui il firmware tratta i dati (in particolare — l'esportazione verso la rete).

Stato attuale

I moduli BASIC e STANDARD (STD) sono in produzione e sono entrambi supportati da questo componente (versione 1.7.3).

Linea di moduli Stato in questo componente
BASIC ✅ in consegna — RBAMP_LINE_BASIC
STANDARD (STD) ✅ in consegna — RBAMP_LINE_STD

BASE — linea di moduli di misura dei consumi di base

Hardware

Un percorso analogico a basso costo adatto ai carichi domestici tipici. Il modulo include un front-end analogico isolato, un regolatore di alimentazione a bordo e una calibrazione di fabbrica memorizzata in flash.

Comportamento del firmware

La logica di un classico contatore a disco meccanico — il conteggio va solo in avanti, l'immissione in rete non viene sottratta.

I tre "livelli" dei valori di potenza attiva si comportano in modo diverso:

Segnale Significato Comportamento su BASIC
rbamp_read_power(dev, ch, &p) potenza RT istantanea, aggiornata ogni ~100 ms con segno — un valore negativo è visibile in tempo reale (esportazione)
snap.avg_p[ch] (dentro rbamp_read_period_snapshot) potenza media sul periodo ciascuna finestra media-P di 100 ms viene limitata a max(P, 0) prima di essere aggiunta all'accumulatore di periodo
rbamp_energy_wh(dev, ch) Wh accumulati dal componente monotono — solo consumo, l'esportazione non viene conteggiata

In altre parole: l'utente vede l'esportazione nella lettura RT, ma il contatore Wh del componente su BASE non la include.

Applicazioni tipiche

  • Famiglie senza produzione propria (senza pannelli solari, turbine eoliche, sistemi a batteria)

  • Sotto-contatori per carichi puramente consumatori (scaldabagni, motori, elettrodomestici)

  • Monitoraggio dei consumi di un edificio dove la misura bidirezionale non è richiesta

Misura bidirezionale sul BASIC (lato master)

Come si produce l'energia su un modulo BASE (integrata sul master) e su un modulo STANDARD (STD) (contatori on-device).
Se deve tenere traccia separatamente dell'immissione in rete su un modulo BASIC,lo faccia lato master. La potenza RTrbamp_read_power(dev, 0, &p)è firmato, quindi:

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 esempio completo funzionante dello schema è in 06_examples.md, nello scenario «Misura bidirezionale lato master».

STANDARD (STD) — la linea di moduli a misura estesa

I moduli STD sono supportati dalla stessa API rbamp_*; rbamp_begin() li rileva. Oltre a quanto offre il BASIC, un modulo STD fornisce:

  • Energia con segno. Importazione ed esportazione sono grandezze separate, e il modulo conserva contatori di vita persistenti (Wh / varh, più risoluzioni più fini sul firmware più recente). L'esportazione non viene azzerata: l'energia di un periodo è la differenza tra due letture di contatore (rbamp_std_read_energy() / rbamp_std_energy_delta()), e rbamp_energy_wh() riporta un valore netto con segno su tali moduli.

  • Altre grandezze: potenza reattiva e apparente per canale (rbamp_read_reactive_power(), rbamp_read_apparent_power(), rbamp_std_read_channel()), totali per fase e generali, e — una volta attivata l'estrazione delle armoniche — THD e fattore di potenza di spostamento. I moduli trifase riportano anche gli angoli di fase delle tensioni e la sequenza di fase.

  • Meccanismi di periodo: banchi di snapshot (otto periodi indipendenti, temporizzati dal master) sui moduli che li hanno, oppure differenze di contatori sui moduli che conservano l'energia sul dispositivo. Il meccanismo viene scelto in rbamp_begin() (rbamp_std_info_t.period_source).

  • Il modello CT è solo un'etichetta. Su un modulo STD il modello CT è solo un'etichetta e non imposta alcun guadagno.

  • Orologio del modulo, storico sul dispositivo e registro eventi, salute e diagnostica, aggiornamento del firmware via I²C, certificato del dispositivo e attestazione.

Tutto questo è documentato in 09 · Riferimento API, capitolo "Linea STD". Un esempio funzionante è examples/std_meter/ (vedi 06 · Esempi, Scenario 18).

Comportamento diverso da BASIC

Argomento BASIC STD
Esportazione in rbamp_energy_wh() non conteggiata (monotona, solo consumo) con segno — netto di importazione ed esportazione
Potenza reattiva / apparente, THD non disponibile — su BASIC la potenza reattiva non è esposta da questa libreria (ESP_ERR_NOT_SUPPORTED) disponibile
Sorgente del periodo snapshot dell'accumulatore di periodo banchi di snapshot, o differenze dei contatori
Orologio del modulo nessuno lo imposti con rbamp_std_set_time() dopo ogni reset del modulo
rbamp_factory_reset() supportato ESP_ERR_NOT_SUPPORTED
Digest (rbamp_read_digest()) supportato sul firmware con la capacità ESP_ERR_NOT_SUPPORTED
Chiamate di periodo su un modulo senza banchi di snapshot né contatori — ESP_ERR_NOT_SUPPORTED

Applicazioni tipiche

  • Abitazioni con produzione solare sul tetto, turbine eoliche o batterie
  • Carichi rigenerativi, ricarica di veicoli elettrici V2G
  • Impianti che richiedono potenza reattiva, fattore di potenza e armoniche oltre alla potenza attiva

Come rilevare la linea del modulo a runtime

Diagramma di flusso per capire se possiede un modulo BASIC o STANDARD (STD).
La linea di prodotto viene rilevata per lei darbamp_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 da STD. Usi l'etichetta SKU sul contenitore del modulo come fonte di verità per il prodotto esatto.

Dove i dettagli dipendenti dalla linea sono indicati nella documentazione

Nel testo del componente e nella documentazione canonica, i dettagli dipendenti dalla linea sono marcati esplicitamente, per esempio:

Solo STD

— questa funzione non è disponibile sul modulo BASE (ESP_ERR_NOT_SUPPORTED).

Oppure, al contrario, comportamento specifico del BASIC:

BASIC

: il contatore rbamp_energy_wh(dev, ch) è monotono — l'immissione in rete non viene conteggiata. Per la misura bidirezionale, veda lo scenario «Misura bidirezionale lato master» in 06_examples.md, oppure usi un modulo STD.

Cosa c'è dopo


Sorgente e segnalazioni: rb-amp/rbamp-esp-idf · questa pagina nel repo: docs/02_tiers.md (v1.7.3)