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
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)
rbamp_read_power(dev, 0, &p)è firmato, quindi:
#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()), erbamp_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
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 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:
— questa funzione non è disponibile sul modulo BASE (ESP_ERR_NOT_SUPPORTED).
Oppure, al contrario, comportamento specifico del 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
-
03 · Scelta del sensore di corrente — quale SCT-013 per quale lavoro
-
04 · Cablaggio — particolarità hardware
-
06 · Esempi — scenari per BASE, incluse le misure bidirezionali lato master
-
09 · Riferimento API — l'API pubblica completa
Sorgente e segnalazioni: rb-amp/rbamp-esp-idf · questa pagina nel repo: docs/02_tiers.md (v1.7.3)