rbAmp
IT
Negozio
Docs
Aggiornato il · Modifica su GitHub

09 · Riferimento API

L'API pubblica completa del componente rbamp per ESP-IDF. La fonte è il file di intestazione include/rbamp.h con i commenti Doxygen; il gestore multimodulo è in include/rbamp_fleet.h e il tipo accumulatore Wh in include/rbamp_energy.h.

Questo capitolo è un riferimento: firme, valori di ritorno, effetti collaterali, casi limite. Per esempi funzionanti vada a 06 · Esempi; per un avvio rapido, vedi 05 · Avvio rapido.

File di intestazione

#include "rbamp.h" — l'intestazione pubblica principale. Include in modo transitivo esp_err.h per esp_err_t e driver/i2c_master.h per il tipo i2c_master_bus_handle_t. Non servono altri include.

L'API è racchiusa in un blocco extern "C" — compatibile sia con chiamanti C sia C++.

Idiomi generali

L'API segue i normali schemi di ESP-IDF:

  • Handle opaco: rbamp_handle_t — un typedef per struct rbamp_obj_t *; l'utente non accede alle sue parti interne. Creato con rbamp_new(), liberato con rbamp_del().

  • Valori di ritorno esp_err_t — ESP_OK in caso di successo, uno dei codici ESP_ERR_* in caso di errore. Usi ESP_ERROR_CHECK() per la gestione con interruzione in caso di errore, oppure verifichi manualmente.

  • Output tramite puntatore: le funzioni che restituiscono un valore prendono un puntatore a un buffer come ultimo parametro. Questo permette a una sola chiamata di restituire sia un esp_err_t sia un valore.

  • Stringhe di errore leggibili: rbamp_err_to_str(err) restituisce un puntatore a una stringa statica. Non restituisce mai NULL.

  • Un handle, due linee di moduli: lo stesso handle e la stessa API scalare servono sia la linea BASIC sia la linea STD; rbamp_begin() rileva la linea e instrada ogni chiamata. Le funzioni che esistono su una sola linea restituiscono ESP_ERR_NOT_SUPPORTED sull'altra (vedi rbamp_line_t e Linea STD).

  • I comandi non vengono ritentati. Una scrittura di comando (snapshot, reset, salvataggio, ...) non viene mai ripetuta dopo un errore di trasporto — un ritentativo potrebbe consegnare l'opcode due volte. Le letture e le scritture dei registri dati mantengono il ritentativo su NACK.

  • Mappatura degli errori usata in tutta l'API: ESP_ERR_NOT_SUPPORTED — la funzione o la funzionalità non esiste su questa linea / firmware / modulo; ESP_ERR_NOT_FOUND — il modulo o il record non è presente (nessuno risponde, nessun record di storico, nessun certificato); ESP_ERR_INVALID_STATE — una precondizione o una sequenza di chiamate è errata, oppure un modulo con sensore accoppiato è protetto (vedi Codici di errore).

Tipi

rbamp_handle_t

C
typedef struct rbamp_obj_t *rbamp_handle_t;

Un handle opaco per un dispositivo slave. L'utente non ha accesso ai suoi campi. Creato con rbamp_new(), liberato con rbamp_del().

rbamp_topology_t

C
typedef enum {
    RBAMP_TOPOLOGY_SINGLE      = 1,  /* 1 current channel (UI1 / I1) */
    RBAMP_TOPOLOGY_SPLIT_PHASE = 2,  /* 2 current channels (UI2 / I2) */
    RBAMP_TOPOLOGY_THREE_PHASE = 3,  /* 3 current channels (UI3 / I3) */
    RBAMP_TOPOLOGY_FIVE_CH     = 5,  /* 5 current channels (UI5)      */
    RBAMP_TOPOLOGY_SEVEN_CH    = 7,  /* 7 current channels (UI7)      */
} rbamp_topology_t;

Il valore è il numero di canali. rbamp_begin() lo adotta dalla variante del modulo; rbamp_new_with_topology() lo fissa. L'enumerazione è volutamente non contigua (non esistono 4 o 6): gli SKU più grandi passano da 3 → 5 → 7.

Due costanti dimensionano i suoi array:

Macro Valore Significato
RBAMP_MAX_CHANNELS 7 Il numero di canali più alto che qualsiasi SKU espone. Dimensioni gli array dei canali con questo valore.
RBAMP_SNAPSHOT_CHANNELS 3 Canali trasportati da rbamp_snapshot_t (ch0–2). I canali 3+ si leggono con rbamp_read_channel() / rbamp_read_all_channels().

rbamp_sensor_class_t

C
typedef enum {
    RBAMP_SENSOR_UNSET      = 0,  /* Factory default */
    RBAMP_SENSOR_SCT013     = 1,  /* SCT-013 fitted by the user */
    RBAMP_SENSOR_WIRED_CT   = 2,  /* Wired CT shipped with the module, calibrated as a pair */
    RBAMP_SENSOR_BUILTIN_CT = 3,  /* Built-in CT, calibrated as a pair */
} rbamp_sensor_class_t;

La classe 1 è un modulo a cui l'utente applica una SCT-013 di sua scelta — il modello CT seleziona il tipo di sensore. Le classi 2 e 3 sono moduli forniti insieme al proprio sensore e calibrati con esso. La libreria non riscrive la classe né il modello di tali moduli: rbamp_set_sensor_class() e rbamp_set_ct_model_ch() restituiscono ESP_ERR_INVALID_STATE. Un riabbinamento in assistenza passa per rbamp_set_ct_model_ch_force().

rbamp_variant_t

La variante hardware di build, restituita da rbamp_variant() e rbamp_read_variant():

Valore Enumerazione Canali Tensione / potenza
0 RBAMP_VARIANT_UNKNOWN — non ancora letto / non pubblicato
1 RBAMP_VARIANT_UI1 1 sì
2 RBAMP_VARIANT_UI2 2 sì
3 RBAMP_VARIANT_UI3 3 sì
4 RBAMP_VARIANT_I1 1 no
5 RBAMP_VARIANT_I2 2 no
6 RBAMP_VARIANT_I3 3 no
7 RBAMP_VARIANT_UI5 5 sì
8 RBAMP_VARIANT_UI7 7 sì

rbamp_line_t

C
typedef enum {
    RBAMP_LINE_BASIC = 0,  /* default until rbamp_begin() has run */
    RBAMP_LINE_STD   = 1,
} rbamp_line_t;

Un unico tipo di handle e un'unica API servono entrambe le linee di moduli. rbamp_begin() ricava la linea dal blocco di identità del modulo e ogni chiamata successiva viene instradata internamente. La si interroga con rbamp_line(dev). Le chiamate senza controparte sulla linea rilevata restituiscono ESP_ERR_NOT_SUPPORTED — mai una lettura di registro sbagliata. Ciò che offre solo la linea STD (potenza reattiva / apparente, THD, contatori di energia con segno, banchi di snapshot, storico) è raccolto in Linea STD.

rbamp_snapshot_t

Restituito da rbamp_read_all(). Tutti i campi sono in unità SI. I canali inutilizzati (oltre channels) sono riempiti di zeri.

C
typedef struct {
    float voltage;          /* V — RMS voltage */
    float voltage_peak;     /* V — peak voltage */
    float current[3];       /* A — RMS current, ch0–2 */
    float current_peak[3];  /* A — peak current, ch0–2 */
    float power[3];         /* W — active power, ch0–2 (signed) */
    float power_factor[3];  /* dimensionless, −1..+1 */
    float frequency;        /* Hz — mains frequency */
    rbamp_topology_t topology;
    uint8_t channels;       /* the module's channel count: 1, 2, 3, 5 or 7 */
    bool has_voltage_hw;    /* true if a voltage sensor is present */
    uint8_t implausible;    /* bitmask of RBAMP_FIELD_* classes set to NaN; 0 = all OK */
} rbamp_snapshot_t;

Gli array contengono solo i canali 0–2. Su una UI5/UI7 channels riporta il numero pieno (5 o 7); legga i canali 3+ con rbamp_read_channel() / rbamp_read_all_channels().

Campi non plausibili. Un singolo campo fuori limite non fa fallire l'intero snapshot: un campo che supera il suo limite di plausibilità per grandezza viene impostato a NaN e il suo bit di classe viene alzato in implausible, mentre il resto resta utilizzabile e rbamp_read_all() restituisce comunque ESP_OK. Verifichi implausible (oppure isnan() per campo) prima di usare un valore.

Bit Significato
RBAMP_FIELD_VOLTAGE voltage / voltage_peak rifiutata
RBAMP_FIELD_CURRENT una current / current_peak rifiutata
RBAMP_FIELD_POWER una potenza rifiutata
RBAMP_FIELD_PF un power_factor rifiutato
RBAMP_FIELD_FREQUENCY frequenza rifiutata

I limiti sono RBAMP_SANITY_LIMIT_V / _I / _P / _PF (500 V, 150 A, 30000 W, 1.5). Solo un guasto reale di trasporto fa restituire a rbamp_read_all() un valore diverso da OK.

rbamp_channel_reading_t

Restituito da rbamp_read_channel() / rbamp_read_all_channels() — un canale, qualsiasi indice.

C
typedef struct {
    float   i_rms;        /* A */
    float   i_peak;       /* A */
    float   p_real;       /* W (signed) */
    float   pf;           /* −1..+1 */
    uint8_t implausible;  /* RBAMP_FIELD_* bits; the flagged field is NaN */
} rbamp_channel_reading_t;

rbamp_period_snapshot_t

Restituito da rbamp_read_period_snapshot(). La primitiva di contabilizzazione dell'energia.

C
typedef struct {
    float    avg_p[3];          /* W — average active power over the period, ch0–2 */
    float    max_p;             /* W — peak power on channel 0 during the period */
    uint32_t latch_ms;          /* ms — module-reported duration; DIAGNOSTIC, not for energy */
    uint32_t master_dt_ms;      /* ms — master wall-clock window since the previous consumed read (CANONICAL) */
    bool     valid;             /* the period was ready at read time */
    float    avg_p_total;       /* W — average active power summed over ALL channels (signed) */
    double   wh_net;            /* Wh — net energy of this period as the library accounted it (signed) */
    bool     module_restarted;  /* the module rebooted inside this period */
    uint32_t module_window_ms;  /* ms — the module's own length of the closed window (0 on STD) */
    uint16_t module_commit_ms;  /* ms — length of one module commit as inferred: 100 or 200 (0 on STD) */
    uint32_t module_uptime_s;   /* s — module uptime read with the snapshot (0 if not published) */
    bool     window_from_boot;  /* the window started at the module's boot */
    bool     window_long;       /* module_window_ms exceeds 6 h */
} rbamp_period_snapshot_t;
Campo Note
avg_p[3] Solo canali 0–2. Su una UI5/UI7 il modulo esegue lo snapshot della potenza media per tutti i canali in modo atomico; legga i canali 3+ con rbamp_read_period_avg_power() e il loro Wh con rbamp_energy_wh() (l'accumulatore integra ogni canale).
max_p Un picco globale, rilevato sul canale 0.
latch_ms Solo diagnostica; può risultare corta sotto carico. La finestra di integrazione dell'energia è master_dt_ms o module_window_ms.
master_dt_ms La finestra su cui la libreria integra l'energia: il tempo esp_timer proprio del master tra due letture consumate consecutive.
avg_p_total, wh_net Il periodo sommato su tutti i canali. wh_net è la potenza media × master_dt_ms, oppure — sui moduli che tengono l'energia sul dispositivo — la differenza del contatore del modulo.
module_window_ms, module_commit_ms La misura del modulo sulla finestra chiusa: commit contati sul clock di misura del modulo, 100 ms ciascuno sul firmware attuale e 200 ms sul firmware più vecchio della v1.2 — la libreria deduce quale dallo stesso snapshot. Normalmente confronta con master_dt_ms. Entrambi sono 0 sulla linea STD.
module_restarted Il modulo si è riavviato all'interno del periodo. Le sue impostazioni RAM (clock, maschera di eventi, soglie, campi del digest) vanno riapplicate — la libreria riapplica quelle di cui è responsabile. Su un modulo BASE viene impostato al primo snapshot dopo rbamp_begin_resume() quando la finestra è iniziata all'avvio del modulo.
module_uptime_s, window_from_boot window_from_boot è vero quando la finestra dello snapshot è iniziata all'avvio del modulo (un riavvio, o il primo snapshot dall'avvio). È sempre falso quando il firmware non pubblica l'uptime (module_uptime_s = 0).
window_long La finestra supera le 6 h: la media del modulo perde precisione su finestre molto lunghe — faccia snapshot più spesso.
Sicurezza

⚠ latch_ms è diagnostico, non serve per l'energia. È la misura del periodo fornita dal modulo stesso e può risultare breve sotto carico. Non lo usi per l'integrazione dell'energia. Il dt canonico per l'energia è master_dt_ms (oppure il suo delta esp_timer_get_time()), oppure module_window_ms per il primo snapshot dopo rbamp_begin_resume().

Bit degli eventi — rbamp_event_bit_t

Bit del byte EVENT_FLAGS persistente, scrivibile-1-per-azzerare (vedi Eventi):

Enumerazione Significato
RBAMP_EVENT_PERIOD_READY È stato preso uno snapshot di periodo
RBAMP_EVENT_THRESH_I Soglia di corrente superata
RBAMP_EVENT_THRESH_P Soglia di potenza superata
RBAMP_EVENT_ERROR Indicatore di errore persistente (vedi Modello di errore)
RBAMP_EVENT_CONFIG_CHANGED Configurazione persistita modificata
RBAMP_EVENT_RESET_OCCURRED Il reset del modulo dall'ultima cancellazione
RBAMP_EVENT_NVM_FAULT Solo STD: guasto dell'accumulatore di energia

rbamp_drdy_event_t

Riempito da rbamp_wait_data_ready() / rbamp_read_all_ready():

C
typedef struct {
    bool     fresh;        /* a new snapshot of THIS module is available (true on ESP_OK) */
    bool     by_edge;      /* woken by the DRDY edge (false = found by polling) */
    uint16_t seq;          /* snapshot sequence now */
    uint16_t missed;       /* snapshots published since the previous call that were not read */
    bool     alarm;        /* the line was held LOW: an unmasked event is pending on this module */
    uint8_t  event_flags;  /* EVENT_FLAGS consumed on an alarm (RBAMP_EVENT_*), else 0 */
    uint32_t latency_us;   /* edge to return, µs (0 when polling) */
} rbamp_drdy_event_t;

Tipi di digest

C
typedef enum {
    RBAMP_DIGEST_I  = ..., /* RMS current per channel */
    RBAMP_DIGEST_U  = ..., /* RMS voltage (modules with voltage sensing only) */
    RBAMP_DIGEST_P  = ..., /* real power per channel, whole watts, signed */
    RBAMP_DIGEST_PF = ..., /* |power factor| per channel */
} rbamp_digest_field_t;

typedef struct {
    uint8_t status;     /* STATUS mirror at the moment of the publish */
    uint8_t seq;        /* window sequence (one step per published window, wraps 255→0) */
    uint8_t n_ch;       /* channels in the digest: min(module channels, 3) */
    uint8_t fields;     /* which rbamp_digest_field_t bits were read */
    float   i_a[3];     /* A; 0 when the field is off */
    float   u_v;        /* V; 0 when off or no voltage sensing */
    int16_t p_w[3];     /* W, signed, truncated toward 0 (|P| < 1 W reads 0); 0 when off */
    float   pf[3];      /* |PF| 0..1; 0 when off */
} rbamp_digest_t;

Tipi di correzione SCT-013

C
typedef enum {
    RBAMP_SCT_NONE,           /* no correction (scale 1) */
    RBAMP_SCT_CORRECTED,      /* scale applied to this channel */
    RBAMP_SCT_UNCALIBRATED,   /* after a reset the module applies the raw preset; scale 1, warning logged */
    RBAMP_SCT_GAIN_UNEXPECTED,/* applied gain is not that of a 30 A-calibrated module; scale 1, warning logged */
    RBAMP_SCT_UNKNOWN_MODEL,  /* model code without a known preset; scale 1, warning logged */
    RBAMP_SCT_PENDING,        /* not evaluated yet (before rbamp_begin); scale 1 */
} rbamp_sct_status_t;

typedef struct {
    rbamp_sct_status_t status;
    uint8_t model;        /* CT model the module reports for the channel */
    float   scale;        /* factor applied to current, power, energy and digest (1.0 unless CORRECTED) */
    float   gain_applied; /* gain the module applies (0 when not read) */
} rbamp_sct_correction_t;

RBAMP_SCT_NONE è riportato sulla linea STD, per classe di sensore 2/3, senza modello associato, con modello 3 (il sensore di fabbrica da 30 A), su un modulo che si corregge da solo (vedi correzione del valore nominale SCT-013) e quando CONFIG_RBAMP_SCT_RATING_CORRECTION è disattivato.

I tipi della linea STD (rbamp_std_info_t, rbamp_std_channel_t, ...) sono descritti insieme alle loro funzioni in Linea STD.

Ciclo di vita

rbamp_new

C
esp_err_t rbamp_new(i2c_master_bus_handle_t bus,
                    uint8_t addr,
                    rbamp_handle_t *out);

Crea un handle opaco per un dispositivo slave. Internamente crea un i2c_master_dev_handle_t tramite i2c_master_bus_add_device().

Il numero di canali e la presenza di tensione sono ricavati dal modulo in rbamp_begin(): una UI1 riporta 1 canale, una UI3 ne riporta 3, una UI7 ne riporta 7, e così via, quindi rbamp_channels(dev) è corretto subito dopo begin, e l'API per canale (rbamp_set_ct_model_ch, ...) protegge dai canali che il modulo non ha. Solo quando il modulo non pubblica la propria variante (firmware precedente alla v1.3) l'handle ricade su RBAMP_TOPOLOGY_THREE_PHASE; lì una sovrastima è innocua — i canali inutilizzati leggono 0.0 A. Usi rbamp_new_with_topology() per fissare un conteggio indipendentemente da quanto dice il modulo.

Parametro Descrizione
bus Handle del bus I²C creato tramite i2c_new_master_bus().
addr Indirizzo slave a 7 bit. Intervallo 0x08..0x77, predefinito 0x50.
out Dove scrivere il nuovo handle.

Ritorna: ESP_OK in caso di successo; ESP_ERR_NO_MEM se la memoria non può essere allocata; ESP_ERR_INVALID_ARG se bus == NULL o out == NULL o addr è fuori intervallo; l'esp_err_t di i2c_master_bus_add_device() su un errore del driver del bus.

rbamp_new_with_topology

C
esp_err_t rbamp_new_with_topology(i2c_master_bus_handle_t bus,
                                  uint8_t addr,
                                  rbamp_topology_t topology,
                                  rbamp_handle_t *out);

Come rbamp_new, ma con una topologia esplicita. Fissa il numero di canali: rbamp_begin() lo mantiene anche quando il modulo ne riporta un altro (viene registrato un avviso). La variante e la presenza della tensione seguono ancora il modulo. Serve solo per firmware più vecchi della v1.3 che non pubblicano la propria variante, o per esporre deliberatamente meno o più canali di quelli che il modulo ha.

rbamp_del

C
void rbamp_del(rbamp_handle_t dev);

Libera l'handle e rimuove il relativo i2c_master_dev_handle_t dal bus. Sicuro da chiamare con NULL — è un no-op.

rbamp_begin

C
esp_err_t rbamp_begin(rbamp_handle_t dev);

Sonda il dispositivo, riconosce la linea del modulo, adotta il numero di canali e la variante, e prepara uno snapshot.

Sequence:

  1. Legge REG_VERSION (0x03). Se il dispositivo non ha dato ACK — ESP_FAIL. Se ha restituito 0x00 / 0xFF — ESP_ERR_INVALID_RESPONSE.

  2. Rilevi la linea di prodotto (BASE / STD) dal blocco di identità del modulo e la memorizzi (rbamp_line()). Sulla linea STD anche l'identità viene memorizzata (rbamp_std_info()) e viene scelto il meccanismo di periodo.

  3. Adotta dal modulo il numero di canali, la variante e la presenza della tensione (a meno che una topologia non sia stata fissata con rbamp_new_with_topology).

  4. Valuti la correzione del valore nominale SCT-013 (vedi correzione del valore nominale SCT-013).

  5. Scriva CMD_LATCH_PERIOD come innesco + attenda 50 ms. Il primo snapshot dopo l'accensione viene scartato. (rbamp_begin_resume() salta questo passo.)

  6. Salvi esp_timer_get_time() per la successiva integrazione dell'energia.

Idempotente ma non gratuito: ogni chiamata esegue uno snapshot primer.

Ritorna: ESP_OK in caso di successo; altrimenti i codici di errore sopra.

rbamp_begin_resume

C
esp_err_t rbamp_begin_resume(rbamp_handle_t dev);

rbamp_begin() senza lo snapshot primer — mantiene la finestra che il modulo ha accumulato mentre il master era assente. Un modulo BASE continua a mediare fino allo snapshot successivo, quindi dopo un riavvio o un'interruzione del master il modulo conserva ancora l'intera finestra dall'ultimo snapshot consumato; rbamp_begin() farebbe uno snapshot e lo scarterebbe, questa chiamata no.

La prima rbamp_read_period_snapshot() consumata dopo che ha integrato sulla finestra propria del modulo (module_window_ms): wh_net = avg_p_total × module_window_ms, master_dt_ms è impostato uguale a module_window_ms e module_restarted = window_from_boot. Tutti gli snapshot successivi usano il clock master come di consueto. Una prima lettura stantia (periodo non valido, accumulatore vuoto) viene scartata come le altre, e la lettura valida successiva usa ancora la finestra del modulo.

Su firmware che non pubblica l'uptime, window_from_boot e module_restarted restano falsi: la finestra recuperata potrebbe includere un riavvio del modulo che la libreria non può vedere. Sui moduli STD la chiamata è identica a rbamp_begin() (la loro energia vive nei contatori del modulo).

rbamp_begin_event_flags

C
uint8_t rbamp_begin_event_flags(rbamp_handle_t dev);

I EVENT_FLAGS così come rbamp_begin() li ha trovati (entrambe le linee; 0 se non leggibili). RBAMP_EVENT_RESET_OCCURRED qui significa che il modulo si era riavviato prima che la libreria lo incontrasse — riapplichi le sue impostazioni RAM (clock, maschera di eventi, soglie). La libreria non azzera nulla all'avvio. Nessun traffico sul bus.

rbamp_probe

C
esp_err_t rbamp_probe(rbamp_handle_t dev);

Un controllo leggero di attività. Una singola lettura di REG_VERSION senza effetti collaterali.

Restituisce: ESP_OK se lo slave ha dato ACK e riportato una versione supportata (non 0 e non 0xFF); ESP_FAIL altrimenti.

rbamp_wait_ready

C
esp_err_t rbamp_wait_ready(rbamp_handle_t dev, uint32_t timeout_ms);

Interroga il flag di pronto del modulo finché il bit 0 non è impostato. Utile dopo l'accensione — il modulo può richiedere fino a 100 ms per la prima finestra RT.

Ritorna: ESP_OK se il bit viene visto prima della scadenza di timeout_ms; altrimenti ESP_ERR_TIMEOUT.

Getter dello stato dell'handle

C
uint8_t          rbamp_firmware_version(rbamp_handle_t dev);
rbamp_topology_t rbamp_topology         (rbamp_handle_t dev);
uint8_t          rbamp_channels         (rbamp_handle_t dev);
rbamp_variant_t  rbamp_variant          (rbamp_handle_t dev);
bool             rbamp_has_voltage_hw   (rbamp_handle_t dev);
uint8_t          rbamp_address          (rbamp_handle_t dev);
rbamp_line_t     rbamp_line             (rbamp_handle_t dev);

Restituiscono tutti valori in cache senza toccare il bus.

Funzione Valori restituiti
rbamp_firmware_version Il byte REG_VERSION memorizzato dopo rbamp_begin() — sulla linea STD è la versione della mappa dei registri, non la versione dell'immagine firmware (vedi rbamp_std_read_image_version). 0 prima di rbamp_begin() o se è fallito.
rbamp_topology L'enumerazione del numero di canali — dal modulo dopo rbamp_begin(), oppure come fissata da rbamp_new_with_topology(); THREE_PHASE prima di begin / sul firmware che non pubblica la propria variante.
rbamp_channels Numero di canali di corrente validi (1, 2, 3, 5 o 7).
rbamp_variant La variante memorizzata da rbamp_begin(); RBAMP_VARIANT_UNKNOWN prima di begin o quando il modulo non la pubblica. rbamp_read_variant() rilegge il registro.
rbamp_has_voltage_hw true se è stato rilevato l'hardware di misura della tensione.
rbamp_address L'indirizzo I²C attuale a 7 bit (si aggiorna dopo rbamp_commit_address_change()).
rbamp_line RBAMP_LINE_BASIC finché rbamp_begin() non è stata eseguita, poi la linea rilevata.

rbamp_basic_fw_name

C
const char *rbamp_basic_fw_name(uint8_t version);

Una pura ricerca (nessun traffico sul bus): il nome umano del firmware per il byte REG_VERSION di un BASE come restituito da rbamp_firmware_version() — per esempio 0x0D → "1.4.21", 0x0C → "1.4.20", 0x0B → "1.4.19", 0x0A → "1.4.18", 0x07 → "1.4.15-1.4.17", 0x05 → "1.4.4-1.4.14", 0x04 → "1.2-1.4.3", 0x00..0x03 → "<1.2". Ogni altro byte → NULL (sconosciuto, oppure non un modulo BASE).

Letture in tempo reale (blocco RT, aggiornamento ogni 100 ms)

Tutte le funzioni restituiscono esp_err_t. Con ESP_OK il valore viene scritto nel puntatore out; in caso di errore *out è indefinito. Sotto il cofano c'è una disciplina di retry+sanità per la resilienza contro i rari glitch del link nello stack I²C di ESP-IDF.

Letture per canale

C
esp_err_t rbamp_read_voltage      (rbamp_handle_t dev, uint8_t phase, float *out);
esp_err_t rbamp_read_voltage_peak (rbamp_handle_t dev, uint8_t phase, float *out);
esp_err_t rbamp_read_current      (rbamp_handle_t dev, uint8_t ch,    float *out);
esp_err_t rbamp_read_current_peak (rbamp_handle_t dev, uint8_t ch,    float *out);
esp_err_t rbamp_read_power        (rbamp_handle_t dev, uint8_t ch,    float *out);
esp_err_t rbamp_read_power_factor (rbamp_handle_t dev, uint8_t ch,    float *out);
esp_err_t rbamp_read_frequency    (rbamp_handle_t dev,                float *out);
Funzione Valore di ritorno Note
rbamp_read_voltage Tensione RMS, V phase = 0 sulla linea BASIC
rbamp_read_voltage_peak Tensione di picco, V Legge 0 sulla mappa del modulo STD 0x34 e precedenti — usi max_u / min_u di un banco di snapshot
rbamp_read_current Corrente RMS sul canale, A ch < rbamp_channels(dev); i canali 3+ (UI5 / UI7) sono instradati attraverso la finestra dei canali in modo trasparente
rbamp_read_current_peak Corrente di picco sul canale, A Legge 0 sulla mappa del modulo STD 0x34 e precedenti — usi max_i di un banco di snapshot
rbamp_read_power Potenza attiva, W (con segno) Negativo = esportazione (installazioni FV / bidirezionali)
rbamp_read_power_factor Fattore di potenza Adimensionale, da −1 a +1
rbamp_read_frequency Frequenza di rete, Hz 50.0 o 60.0 su una rete sana. STD: un valore del modulo di 0 (nessuna rete) restituisce ESP_ERR_INVALID_RESPONSE con *out = NaN

Se ch o phase sono fuori intervallo, restituisce ESP_ERR_INVALID_ARG.

Lettura istantanea dell'intero blocco RT

C
esp_err_t rbamp_read_all(rbamp_handle_t dev, rbamp_snapshot_t *out);

Equivalente a rbamp_read_voltage + rbamp_read_voltage_peak + rbamp_read_current(0..N) + rbamp_read_current_peak(0..N) + rbamp_read_power(0..N) + rbamp_read_power_factor(0..N) + rbamp_read_frequency eseguite in sequenza. I canali inutilizzati (oltre rbamp_channels(dev)) vengono riempiti con zeri.

Su un modulo con più di tre canali (UI5 / UI7) vengono letti nella struttura solo i canali 0–2 (RBAMP_SNAPSHOT_CHANNELS = 3); i canali 3+ non vengono toccati — si leggono con rbamp_read_channel() / rbamp_read_all_channels(). Sulla linea STD il blocco di tensione e ciascun blocco di canale vengono letti interi (una transazione ciascuno).

Un campo che supera il proprio limite di plausibilità non fa fallire la chiamata: viene impostato a NaN e segnalato in snap.implausible, e la chiamata restituisce comunque ESP_OK (vedi rbamp_snapshot_t).

Ritorna: ESP_OK in caso di successo (verifichi implausible); altrimenti il primo errore di trasporto — nel qual caso il contenuto di out è parziale e non va usato.

Potenza reattiva e apparente

C
esp_err_t rbamp_read_reactive_power(rbamp_handle_t dev, uint8_t ch, float *out);
esp_err_t rbamp_read_apparent_power(rbamp_handle_t dev, uint8_t ch, float *out);

Potenza reattiva del canale ch in var (con segno) e potenza apparente in VA. Queste grandezze esistono solo sulla linea STD; su BASIC la potenza reattiva non è esposta da questa libreria, e su un handle BASIC entrambe restituiscono ESP_ERR_NOT_SUPPORTED.

Accesso ai canali (canali 3 e oltre)

I canali 0–2 risiedono nel blocco RT piatto. Sulle versioni più grandi (UI5 / UI7) i canali 3+ sono raggiungibili solo tramite la finestra dei canali del modulo. La libreria gestisce questo in modo trasparente: rbamp_read_current(), rbamp_read_current_peak(), rbamp_read_power() e rbamp_read_power_factor() accettano qualsiasi ch in 0..rbamp_channels(dev)-1 e instradano i canali 3+ attraverso la finestra. La selezione della finestra è una risorsa condivisa singola nel modulo, e selezione + lettura formano una sezione atomica — non condivida un handle tra task senza un proprio mutex.

C
esp_err_t rbamp_read_channel     (rbamp_handle_t dev, uint8_t ch,
                                  rbamp_channel_reading_t *out);
esp_err_t rbamp_read_all_channels(rbamp_handle_t dev,
                                  rbamp_channel_reading_t *out, uint8_t n);
  • rbamp_read_channel legge tutti e quattro i campi RT di un canale in un rbamp_channel_reading_t. Un campo che supera il suo limite di sanità è NaN con il suo bit RBAMP_FIELD_* in implausible.

  • rbamp_read_all_channels riempie out[] con ogni canale popolato; n è la capacità di out (la dimensioni con RBAMP_MAX_CHANNELS), la chiamata riempie min(n, rbamp_channels(dev)) voci.

Restituisce: ESP_OK (verifichi implausible); ESP_ERR_INVALID_ARG su un canale errato o NULL; altrimenti il primo errore di trasporto.

Sono valori in tempo reale, istantanei. Una scansione dei canali legge finestre di pubblicazione adiacenti e non è uno snapshot simultaneo — per l'energia allineata tra canali usi il percorso di periodo.

Nota

rbamp_read_all() su un UI5 / UI7 restituisce i primi tre canali (RBAMP_SNAPSHOT_CHANNELS = 3) e lascia il resto intatto; snap.channels riporta ancora il numero reale di canali del modulo.

rbamp_read_commit_seq

C
esp_err_t rbamp_read_commit_seq(rbamp_handle_t dev, uint8_t *out);

Legge il byte di sequenza del digest: un uint8_t che si incrementa una volta per finestra di misura (ogni 100 ms con il firmware attuale, 200 ms sulle immagini precedenti alla v1.2; torna da 255 a 0). Lo legga prima e dopo una scansione di più registri — un valore invariato dimostra che tutte le letture provengono dallo stesso commit. Il digest non porta CRC.

Data-ready (DRDY)

Tempistica della finestra in tempo reale di 100 ms, dell'impulso di dati pronti e della lettura atomica del blocco.
Ogni modulo pilota un open-drain opzionaleDRDYuscita: ALTO a riposo (pull-up del master), un impulso BASSO di ~10 µs ogni volta che viene pubblicato uno snapshot di misura completo (ogni 100 ms su tutta la famiglia; immagini BASIC precedenti alla v1.2 e immagini STD fino a 0x7B: 200 ms). Più moduli possono condividere una linea wired-OR. I moduli BASIC tengono anche la linea stabilmente BASSA mentre un evento non mascherato è in attesa (allarme).

La libreria trasforma l'impulso in un risveglio, così un lettore non legge mai lo stesso snapshot due volte, non attraversa mai una pubblicazione e sa quanti snapshot ha mancato. Sui moduli STD il contatore di pubblicazione indica quale modulo ha generato l'impulso su una linea condivisa. Senza un filo DRDY le stesse chiamate funzionano per polling del contatore del modulo ogni CONFIG_RBAMP_DRDY_POLL_MS. I moduli STD più vecchi dell'immagine 0x00010075 pilotano il pin in modo diverso: la libreria li tratta come privi di linea DRDY e fa polling.

C
esp_err_t rbamp_set_drdy_gpio  (rbamp_handle_t dev, int gpio);
esp_err_t rbamp_wait_data_ready(rbamp_handle_t dev, uint32_t timeout_ms,
                                rbamp_drdy_event_t *ev);
esp_err_t rbamp_read_all_ready (rbamp_handle_t dev, uint32_t timeout_ms,
                                rbamp_snapshot_t *out, rbamp_drdy_event_t *ev);
esp_err_t rbamp_read_data_seq  (rbamp_handle_t dev, uint16_t *out);
Funzione Descrizione
rbamp_set_drdy_gpio(dev, gpio) Colleghi la linea DRDY di questo modulo, oppure la scolleghi con -1. Il GPIO viene configurato come ingresso con pull-up e interrupt sul fronte di discesa; qualsiasi numero di handle può condividere un GPIO. Lo chiami dopo rbamp_begin() (il contratto elettrico della linea dipende dal modulo rilevato). Restituisce ESP_ERR_NO_MEM se sono in uso più di 4 linee distinte o più di 8 handle per linea.
rbamp_wait_data_ready(dev, timeout_ms, ev) Blocca finché il modulo non ha pubblicato uno snapshot più recente dell'ultimo restituito da questa chiamata (o dell'ultima lettura tramite rbamp_read_all_ready), al massimo per timeout_ms. ev può essere NULL.
rbamp_read_all_ready(dev, timeout_ms, out, ev) rbamp_wait_data_ready() seguito da rbamp_read_all(): una lettura coerente per ogni snapshot pubblicato, mai lo stesso snapshot due volte.
rbamp_read_data_seq(dev, &seq) La sequenza di snapshot corrente senza attendere.

Come funziona l'attesa con una linea DRDY. Si attiva sul fronte di discesa, poi verifica che la sequenza del modulo sia avanzata (un impulso su una linea condivisa può appartenere a un altro modulo — la chiamata continua ad attendere). Se la linea è ancora BASSA 5 ms dopo il fronte, un evento non mascherato è in attesa su qualche modulo della linea: vengono letti e azzerati i flag di ogni modulo collegato (scrittura-1-per-azzerare, che rilascia la linea — una linea tenuta bassa nasconderebbe gli impulsi degli altri moduli). I flag di questo modulo tornano in ev con alarm impostato; i flag degli altri moduli vengono passati ai rispettivi handle e segnalati alla successiva attesa.

Ritorna (rbamp_wait_data_ready): ESP_OK (snapshot fresco); ESP_ERR_TIMEOUT; ESP_ERR_NOT_SUPPORTED sui moduli STD senza contatore di pubblicazione (versione della mappa dei registri sotto 0x36).

C
rbamp_set_drdy_gpio(dev, GPIO_NUM_4);
while (1) {
    rbamp_snapshot_t s;
    rbamp_drdy_event_t ev;
    if (rbamp_read_all_ready(dev, 500, &s, &ev) == ESP_OK) {
        if (ev.missed) ESP_LOGW(TAG, "missed %u snapshot(s)", ev.missed);
        /* use s — exactly one read per published snapshot */
    }
}

Digest BASE

Il digest è un blocco compatto che un modulo BASE pubblica con ogni finestra. Permette al master di leggere il risultato della finestra in una sola transazione I²C invece di una per campo.

C
esp_err_t rbamp_set_digest_fields(rbamp_handle_t dev, uint8_t fields);
esp_err_t rbamp_read_digest      (rbamp_handle_t dev, rbamp_digest_t *out);
  • rbamp_set_digest_fields(dev, fields) sceglie i campi che il modulo impacchetta nel digest: un OR di RBAMP_DIGEST_I, _U, _P, _PF (non 0). Il default se mai chiamata è corrente + potenza reale, più tensione sui moduli con rilevamento di tensione. La scelta viene scritta nel modulo alla successiva rbamp_read_digest() (o subito, se l'handle è già avviato su un modulo BASE con la capacità digest). Il modulo la tiene solo in RAM, quindi la libreria la riscrive dopo un riavvio del modulo rilevato. Ritorna ESP_ERR_INVALID_ARG per 0, per bit sconosciuti, o quando il modulo rifiuta un campo che non ha (tensione su un modulo solo corrente); ESP_ERR_NOT_SUPPORTED sulla linea STD o su firmware senza la capacità digest.

  • rbamp_read_digest(dev, &d) legge stato, sequenza di finestra e i campi scelti per i canali 0–2 in una sola transazione. Pensata per leggere ogni finestra pubblicata su DRDY: rbamp_wait_data_ready() poi rbamp_read_digest() dà la potenza reale con segno di ciascuna finestra per pochi byte di bus. I canali 3+ non sono nel digest (usi rbamp_read_channel()). La potenza reale è in watt interi — un carico sotto 1 W legge 0. Ritorna ESP_OK; ESP_ERR_NOT_SUPPORTED sulla linea STD o su firmware BASE senza la capacità digest; errori di trasporto.

Contabilità per periodo

Vedi 01 · Panoramica per il quadro generale e 05 · Avvio rapido Passo 5 per un modello minimo.

rbamp_latch_period

C
esp_err_t rbamp_latch_period(rbamp_handle_t dev);

Scrive CMD_LATCH_PERIOD (0x27) in REG_COMMAND. Non attende — il chiamante deve concedere un assestamento di 50 ms e verificare rbamp_is_period_valid() prima di leggere.

Per la maggior parte dei casi d'uso, usi rbamp_read_period_snapshot() — incapsula l'intera sequenza.

rbamp_is_period_valid

C
esp_err_t rbamp_is_period_valid(rbamp_handle_t dev, bool *out);

Legge il bit di snapshot pronto. *out = true se l'ultimo snapshot è fresco.

rbamp_read_period_avg_power

C
esp_err_t rbamp_read_period_avg_power(rbamp_handle_t dev,
                                      uint8_t ch, float *out);

Potenza attiva media sul canale nel periodo dello snapshot. Va chiamata dopo rbamp_latch_period() + un assestamento di 50 ms + un controllo di validità.

rbamp_read_period_max_power

C
esp_err_t rbamp_read_period_max_power(rbamp_handle_t dev, float *out);

Potenza istantanea di picco sul canale 0 durante il periodo dello snapshot. ch=0 solo sul firmware v1.

rbamp_read_period_latch_ms

C
esp_err_t rbamp_read_period_latch_ms(rbamp_handle_t dev, uint32_t *out);

La durata del periodo come la vede il dispositivo, in ms.

Valore diagnostico.

La durata riportata dal modulo può risultare corta sotto carico. Per l'integrazione dell'energia usi master_dt_ms (o module_window_ms) da rbamp_period_snapshot_t, non questo campo.

rbamp_read_period_snapshot

C
esp_err_t rbamp_read_period_snapshot(rbamp_handle_t dev,
                                     rbamp_period_snapshot_t *out,
                                     uint16_t settle_ms,
                                     bool skip_latch);

Il punto d'ingresso consigliato per la contabilità per periodo. La sequenza completa sotto il cofano:

  1. Se skip_latch == true — salta la scrittura di LATCH (usata dopo una serie manuale di comandi di snapshot o uno snapshot broadcast per la sincronia multi-modulo).

  2. Altrimenti — scrivere CMD_LATCH_PERIOD.

  3. Acquisisca esp_timer_get_time() per calcolare master_dt_ms.
  4. vTaskDelay(pdMS_TO_TICKS(settle_ms)) — 50 ms per impostazione predefinita.
  5. Verifichi il flag di snapshot pronto. Se è 0 — imposti ESP_ERR_INVALID_RESPONSE e registri il timestamp (così lo snapshot successivo non conta due volte dt).

  6. Legga avg_p[0..channels-1] + max_p + latch_ms.

  7. Aggiorna il timestamp e invoca l'integratore di energia per tutti i canali (se il componente non è compilato con CONFIG_RBAMP_DISABLE_ENERGY).
Parametro Descrizione
out Struttura di output.
settle_ms Attenda dopo lo snapshot (consigliati 50).
skip_latch Se true — non scriva LATCH, legga soltanto (per il pattern multi-modulo).

Restituisce: ESP_OK se out->valid == true; ESP_ERR_INVALID_RESPONSE se lo snapshot è obsoleto (in caso di dato obsoleto l'energia non viene integrata e l'ancoraggio viene mantenuto); ESP_ERR_NOT_SUPPORTED su un modulo STD che non offre né banchi di snapshot né contatori; altrimenti l'esp_err_t delle operazioni sul bus. Per il comportamento STD veda Chiamate di periodo sulla linea STD.

L'energia si integra su master_dt_ms — la finestra propria del master tra letture consumate successive. Dopo rbamp_begin_resume() il primo snapshot consumato si integra invece sulla finestra propria del modulo.

Cadenza consigliata.

Tra una chiamata di snapshot e l'altra: 60 s sono comodi, 30 s sono marginali, < 10 s garantiscono letture obsolete. Il firmware integra internamente l'accumulatore periodico; chiamare rbamp_read_period_snapshot() più spesso di quanto il firmware riesca a preparare il periodo successivo restituirà sempre uno snapshot obsoleto (ESP_ERR_INVALID_RESPONSE). Per la telemetria ad alta frequenza usi le funzioni RT rbamp_read_power(ch) / rbamp_read_all() — si aggiornano a ~10 Hz.

rbamp_read_uptime_s

C
esp_err_t rbamp_read_uptime_s(rbamp_handle_t dev, uint32_t *out);

Secondi dall'avvio del modulo. Un valore in calo tra due letture significa che il modulo si è riavviato. Sul firmware BASE che non pubblica l'uptime legge 0.

Chiamate di periodo sulla linea STD

La stessa API di periodo serve entrambe le linee, ma ciò che accade sotto dipende da ciò che il modulo STD offre (rbamp_std_info_t.period_source, deciso da rbamp_begin()):

period_source Comportamento di rbamp_read_period_snapshot()
RBAMP_STD_PERIOD_LATCH Il modulo ha banchi di snapshot. La libreria usa il banco 0 (armato da rbamp_begin()): fa il latch, attende almeno 300 ms indipendentemente da un settle_ms più piccolo (il modulo fa lo snapshot al confine successivo della sua finestra di misura), legge il banco e lo converte in energia sul master_dt_ms. Con skip_latch il chiamante gestisce i tempi: latch, attesa ≥ 300 ms, poi lettura. Mantenga il bit 0 impostato in rbamp_std_arm_banks().
RBAMP_STD_PERIOD_COUNTERS Nessun banco di snapshot, ma contatori di vita persistenti. Non viene inviato alcun latch e settle_ms / skip_latch vengono ignorati: la chiamata legge i contatori e riporta la differenza dall'ultima lettura consumata in avg_p_total / wh_net. Nulla va perso al riavvio del modulo (module_restarted lo segnala).
RBAMP_STD_PERIOD_NONE Nessuno dei due. Le chiamate di periodo restituiscono ESP_ERR_NOT_SUPPORTED invece di riportare silenziosamente un periodo non valido.

Per il percorso a contatori: avg_p[] contiene il periodo per un modulo a canale singolo, le differenze dei contatori per canale sui moduli che pubblicano contatori per canale, e NaN sui moduli multicanale che non li pubblicano; max_p è NaN. Sui moduli a contatore senza contatori a grana fine scelga un periodo abbastanza lungo che un passo di contatore sia una piccola frazione di esso (minuti, non secondi). ESP_ERR_INVALID_RESPONSE riancora la libreria (quel periodo viene scartato) quando il contatore di generazione del modulo è cambiato (i suoi contatori sono stati azzerati o adottati) o un contatore è tornato indietro.

Altre note STD: rbamp_latch_period() fa il latch del banco 0 (operazione nulla che restituisce ESP_OK sui moduli a contatore); rbamp_is_period_valid() è vero sui moduli a contatore una volta che la libreria possiede un ancoraggio di contatore (sempre dopo rbamp_begin()); rbamp_read_period_avg_power() restituisce la media dell'ultimo periodo consumato per i moduli a contatore a canale singolo e ESP_ERR_NOT_SUPPORTED su quelli multicanale; rbamp_read_period_max_power() restituisce ESP_ERR_NOT_SUPPORTED sui moduli a contatore; rbamp_read_period_snapshot() restituisce ESP_ERR_INVALID_RESPONSE quando il banco 0 non segnala alcuna finestra trascorsa — se un reset del modulo ha azzerato la maschera di armatura del banco, la libreria riarma il banco 0, esegue uno snapshot di innesco e riavvia l'ancoraggio dell'orologio (quella finestra non viene integrata, la successiva torna intera).

Funzione di supporto inline

C
static inline esp_err_t
rbamp_read_period_snapshot_simple(rbamp_handle_t dev,
                                  rbamp_period_snapshot_t *out);

Un wrapper di comodo per gli argomenti predefiniti: settle_ms=50, skip_latch=false. Lo usi per il normale polling periodico.

Contabilizzazione dell'energia (accumulatore lato master)

Se il componente è compilato senza CONFIG_RBAMP_DISABLE_ENERGY=y, sono disponibili funzioni di accesso al contatore Wh interno all'handle:

C
double rbamp_energy_wh        (rbamp_handle_t dev, uint8_t ch);
void   rbamp_energy_reset     (rbamp_handle_t dev, uint8_t ch);
void   rbamp_energy_reset_all (rbamp_handle_t dev);
void   rbamp_energy_disable   (rbamp_handle_t dev);
void   rbamp_energy_enable    (rbamp_handle_t dev);

L'accumulatore viene aggiornato automaticamente a ogni rbamp_read_period_snapshot() riuscita. È con segno — un valore negativo significa esportazione netta.

Funzione Descrizione
rbamp_energy_wh(dev, ch) Totale Wh corrente sul canale. Se ch è fuori intervallo — 0.0.
rbamp_energy_reset(dev, ch) Azzera un singolo canale.
rbamp_energy_reset_all(dev) Azzera tutti i canali.
rbamp_energy_disable(dev) Disattiva l'integrazione automatica. Utile quando il master mantiene una propria persistenza del Wh (deep-sleep — vedi 06 · Esempi Scenario 9).
rbamp_energy_enable(dev) Riattivi l'integrazione automatica.

rbamp_energy_wh() accetta un indice di canale (0..rbamp_channels(dev)-1, fino a 6 su un UI7) oppure il selettore RBAMP_ENERGY_CH_TOTAL (0xFF) per il totale di tutti i canali. Il valore è con segno — negativo significa esportazione netta — ed è 0 se ch è fuori intervallo o l'energia è disabilitata.

Moduli STD senza banchi di snapshot (percorso dei contatori): il totale è la somma delle differenze dei contatori del modulo — esatto, nulla viene integrato sull'host. I valori per canale provengono dai contatori per canale del modulo dove li pubblica, sono NaN sui moduli multi-canale che non li pubblicano, e coincidono con il totale sui moduli a canale singolo.

Formula di integrazione:

Text
wh[ch] += snap.avg_p[ch] × master_dt_ms / 1000 / 3600
         [W]              [milliseconds]              → [Wh]

Compilando con CONFIG_RBAMP_DISABLE_ENERGY=y, sia le funzioni (prototipi e storage) vengono rimosse dal binario tramite guardie #if — un tentativo di chiamare rbamp_energy_wh() produce un errore del linker "unresolved external".

Il tipo dell'accumulatore (rbamp_energy.h)

L'accumulatore dietro l'handle si trova in un file di intestazione separato, rbamp_energy.h. L'intestazione lo descrive come API interna — l'applicazione normalmente usa i wrapper rbamp_energy_* qui sopra e non ha bisogno di questo. È elencato qui perché i simboli sono visibili:

C
typedef struct {
    double wh[RBAMP_ENERGY_MAX_CH];  /* per-channel running total, Wh (signed) */
    double wh_total;                 /* all-channel total, Wh (signed) */
    bool   enabled;                  /* false: tick() is a no-op */
} rbamp_energy_t;

void   rbamp_energy_init      (rbamp_energy_t *e);
void   rbamp_energy_tick      (rbamp_energy_t *e, const float avg_p[], uint8_t channels,
                               uint32_t period_ms, bool valid);
double rbamp_energy_wh_get    (const rbamp_energy_t *e, uint8_t ch);
void   rbamp_energy_add_wh    (rbamp_energy_t *e, uint8_t ch, double wh);
void   rbamp_energy_reset_ch  (rbamp_energy_t *e, uint8_t ch);
void   rbamp_energy_reset_all_ch(rbamp_energy_t *e);
static inline void rbamp_energy_set_enabled(rbamp_energy_t *e, bool en);
Funzione Descrizione
rbamp_energy_init Azzera i contatori; l'accumulatore parte già abilitato.
rbamp_energy_tick Integri un periodo: wh[ch] += avg_p[ch] × period_ms / 1000 / 3600 per fino a RBAMP_ENERGY_MAX_CH (7) canali. Saltato in silenzio se valid è falso, period_ms è 0 o l'accumulatore è disabilitato. period_ms deve essere il tempo di parete del master (master_dt_ms), non latch_ms del modulo.
rbamp_energy_wh_get Totale parziale di un canale; 0 se fuori intervallo.
rbamp_energy_add_wh Aggiunge un importo già misurato (Wh, con segno) a un canale oppure, con RBAMP_ENERGY_CH_TOTAL, al totale di tutti i canali. Usato quando il modulo pubblica da sé i contatori di energia. Non fa nulla mentre è disattivato.
rbamp_energy_reset_ch / rbamp_energy_reset_all_ch Azzera un canale / tutti i canali.
rbamp_energy_set_enabled Abilita o disabilita l'integrazione. Mentre è disabilitata tick() e add_wh() non fanno nulla e le letture continuano a restituire il valore congelato.

Identificazione e messa in servizio

Queste funzioni permettono al master di sapere cosa esattamente è collegato al bus (variante, mappa dei bit di capacità, UID) e di preparare un modulo nuovo o appena flashato per il funzionamento (provisioning + salvataggio della configurazione in flash).

rbamp_read_variant

C
esp_err_t rbamp_read_variant(rbamp_handle_t dev, rbamp_variant_t *out);

Legge il registro di variante e lo mappa nell'enum rbamp_variant_t (RBAMP_VARIANT_UI1 / _I1 / _I2 / _I3, _UI5, _UI7, ...; ogni codice noto viene mappato). Per la compatibilità con il codice più vecchio che legge il byte "grezzo", può riconvertirlo a uint8_t. Il valore memorizzato da rbamp_begin() è disponibile senza traffico sul bus come rbamp_variant(). Valori:

Codice SKU canali I Canale U
1 UI1 1 sì
2 UI2 2 sì
3 UI3 3 sì
4 I1 1 no
5 I2 2 no
6 I3 3 no
7 UI5 5 sì
8 UI7 7 sì

Il valore è di sola lettura, memorizzato in ROM, modificato solo dal reflash in fabbrica.

rbamp_read_capability

C
esp_err_t rbamp_read_capability(rbamp_handle_t dev, uint16_t *out);

Legge la mappa delle funzionalità dai registri CAPABILITY (0x57/0x58), LE u16. Un flag indica la presenza di un front-end di tensione: se è basso, il modulo non calcola P / PF / Q e i valori di quei registri sono 0.0f. Vedi la sezione «CAPABILITY (0x57/0x58, u16 LE) — mappa di rilevamento delle funzionalità» sotto.

rbamp_has_voltage

C
bool rbamp_has_voltage(rbamp_handle_t dev);

Una funzione di supporto sopra rbamp_read_capability — restituisce true se il modulo ha un canale U (cioè (cap >> 8) & 1). Viene memorizzata nell'handle alla prima chiamata; le chiamate successive non eseguono alcuna operazione I²C.

rbamp_read_product_id

C
esp_err_t rbamp_read_product_id(rbamp_handle_t dev, uint8_t *out);

Legge PRODUCT_ID (0x54) — un identificativo a byte della famiglia (rbAmp = 0x01). Usato dallo scanner di flotta per confermare che il dispositivo a un indirizzo sia davvero un rbAmp, e non un altro slave I²C che per caso risponde su quell'indirizzo.

rbamp_read_uid

C
esp_err_t rbamp_read_uid(rbamp_handle_t dev, uint8_t uid[12]);

Legge l'identificatore unico MCU a 96 bit da UID (0x5C..0x67) in un'unica operazione in burst. L'UID è garantito unico per modulo e non cambia con il reflash — comodo per i log seriali, per i controlli anti-clonazione lato master e per l'identificazione quando si sostituisce un modulo in una flotta installata.

rbamp_is_provisioned

C
esp_err_t rbamp_is_provisioned(rbamp_handle_t dev, bool *out);

Verifica se il modulo ha superato la messa in servizio iniziale. Tecnicamente controlla REG_ERROR != 0xFB (ERR_FLASH_PARAMS_BAD) su un modulo appena avviato — 0xFB viene impostato dal firmware quando il blocco di configurazione utente è vuoto / corrotto. Un modulo appena uscito di fabbrica restituisce false — serve rbamp_save_user_config (oppure la messa in servizio tramite la flotta) dopo la prima impostazione di modello CT e indirizzo.

Nota

Nella v1.3 questo codice è normale per un modulo vergine (non fatale). Non interrompa la messa in servizio alla prima comparsa di 0xFB.

Linea STD. Restituisce true quando il modulo segnala la propria pagina di calibrazione come valida. Affidabile dalla versione di immagine del modulo 0x00010079; le immagini più vecchie impostano il bit anche con i guadagni di fabbrica, quindi «messo in servizio» non si distingue da «non calibrato» con questa chiamata (usi invece la fonte di calibrazione in rbamp_std_read_health()). Dalla versione di immagine del modulo 0x0001007A il bit deriva da un marcatore che il modulo scrive quando la calibrazione viene salvata: un'unità calibrata con un firmware precedente risulta false dopo l'aggiornamento, finché non si esegue una volta rbamp_save_gains() su di essa (la sua calibrazione è integra).

rbamp_save_user_config

C
esp_err_t rbamp_save_user_config(rbamp_handle_t dev);

Emette CMD_SAVE_USER_CONFIG (opcode 0x32) — salva il blocco di configurazione utente in flash: SENSOR_CLASS, CT_MODEL per canale, I2C_ADDRESS, FLEET_CONFIG, GROUP_ID, LABEL. Non salva i parametri di calibrazione di fabbrica (guadagno, NF, fase) — quelli sono sotto il CMD_SAVE_GAINS separato, che è bloccato in modalità produzione.

Blocca il thread per ~700 ms (ciclo di cancellazione e scrittura della flash). Durante la chiamata non tenti di accedere al modulo da altri task.

Returns:

  • ESP_OK — configurazione salvata, sopravvive a una interruzione di alimentazione.
  • ESP_ERR_TIMEOUT — il modulo non ha risposto in tempo; l'alimentazione potrebbe essere caduta durante il ciclo di flash. Verifichi di nuovo con reset + rilettura.

  • ESP_FAIL — il modulo ha restituito REG_ERROR != OK dopo il comando. Verifichi rbamp_read_last_error per i dettagli.

Rilettura ≠ persistenza

: la conferma che un valore è stato scritto in flash richiede un riavvio + rilettura. Vedi la sezione Modello di errore v1.3 sotto e 03 · Selezione del sensore di corrente.

rbamp_read_active_address

C
esp_err_t rbamp_read_active_address(rbamp_handle_t dev, uint8_t *out);

Legge l'indirizzo I²C attivo del modulo. All'avvio questo registro è veritiero — legge l'indirizzo attivo in flash (un modulo reindirizzato legge il suo nuovo indirizzo). Dopo aver predisposto un candidato con rbamp_prepare_address_change() ripete il candidato fino al commit + reset. Utile per verificare un cambio di indirizzo in due fasi dopo il riavvio successivo al commit. Sulla linea STD legge l'indirizzo persistito (applicato al reset successivo).

Modello di errore v1.3

Gli errori hanno due canali indipendenti che funzionano in modi diversi. Capire la differenza è fondamentale per interpretare correttamente lo stato del modulo.

Canale A — lato client, sincrono Canale B — lato DUT, asincrono durevole
Dove risiede Validazione all'interno del componente (lib) REG_ERROR (0x02) + EVENT_FLAGS.bit3 (0x2A)
Quando scatta Prima della transazione I²C (la libreria intercetta) Dopo che il firmware accetta una scrittura e la rifiuta
Cosa vede il master ESP_ERR_INVALID_ARG dal setter; REG_ERROR resta 0x00 REG_ERROR = il codice di rifiuto immediato; bit3 si attiva alcune centinaia di millisecondi dopo la transazione
Persistente no (solo un codice di ritorno) Ultima scrittura di REG_ERROR; bit3 sticky W1C
Percorso tipico Argomento fuori dai limiti consentiti (canale ≥ rbamp_channels(dev), classe sconosciuta, ...) Scrittura di registro grezza che il componente non pre-valida (una scrittura di basso livello personalizzata); un codice modello CT sconosciuto, che il modulo stesso rifiuta

Canale A — validazione lato client (setter del componente)

Tutti i setter del componente (rbamp_set_sensor_class, rbamp_set_ct_model_ch, rbamp_configure_channels, ecc.) prima verificano gli argomenti rispetto ai valori ammessi. Se un argomento è fuori intervallo, il setter restituisce ESP_ERR_INVALID_ARG senza eseguire alcuna transazione I²C. Di conseguenza REG_ERROR sul dispositivo non viene toccato:

C
esp_err_t err = rbamp_set_ct_model_ch(dev, /*channel=*/99, /*code=*/3);
/* err == ESP_ERR_INVALID_ARG  (lib client-side validation) */

uint8_t reg_err;
rbamp_read_last_error(dev, ®_err);
/* reg_err == 0x00 — REG_ERROR untouched, lib intercepted before I²C */

Ciò significa: se vuole sapere esattamente perché un setter ha rifiutato, la fonte affidabile è il codice di ritorno della funzione + la verifica del proprio argomento. REG_ERROR non le dirà nulla in questo scenario (la transazione riuscita successiva lo imposta).

Canale B — rifiuto lato DUT (asincrono durevole)

Se una scrittura è passata per I²C (la libreria non l'ha intercettata perché l'argomento sembrava valido), ma il firmware l'ha rifiutata, entra in gioco il secondo canale:

  • REG_ERROR (0x02) contiene immediatamente il codice di motivo (per esempio 0xFE = ERR_PARAM). È l'esito dell'ultima scrittura: ogni scrittura successiva riuscita lo sovrascrive. Deve leggerlo subito dopo la propria scrittura, prima di qualsiasi altra transazione.

  • EVENT_FLAGS.bit3 (rbamp_has_error) — sticky W1C. Non si imposta istantaneamente: al banco si è misurato un ritardo di alcune centinaia di millisecondi tra la transazione rifiutata e l'impostazione del bit3. Subito dopo la scrittura il bit3 è ancora 0; dopo 300 ms è 1. Da allora bit3 resta fermo attraverso qualsiasi numero di letture.

Output su banco (scrittura grezza DIGEST_CONFIG = 0xFF):

Text
raw write 0x29=0xFF → read_last_error → REG_ERROR=0xFE (immediate)
has_error(bit3):     immediate=0, +300 ms poll#1=1, poll#2=1
Sicurezza

⚠ Non usi has_error per convalidare una scrittura appena eseguita. Per l'esito di quella specifica scrittura, è affidabile solo rbamp_read_last_error letto immediatamente dopo la scrittura, prima di qualsiasi altra transazione (oltre al codice di ritorno del setter, se ne ha uno). has_error è un canale asincrono per il monitoraggio a interrogazione del tipo «si è verificato un guasto tra due controlli», non per la convalida sincrona.

Cancellare un errore durevole — cancellare entrambi (REG_ERROR e bit3)

bit3 viene riaggiornato dal firmware ogni poche centinaia di millisecondi a partire dallo stato attuale di REG_ERROR. Quindi un semplice clear_event_flags(1<<3) non funziona — bit3 viene subito riimpostato dal REG_ERROR non ancora azzerato:

Text
state: REG_ERROR=0xFE, bit3=1

clear_event_flags(1<<3)          → bit3=1 still (re-latched from REG_ERROR=0xFE)

clear_error  +  clear_event_flags(1<<3)
                                  → bit3=0 (cleared cleanly)

L'ordine corretto: prima rbamp_clear_error() (cancella REG_ERROR), poi rbamp_clear_event_flags(1<<3) (cancella il latch sticky). Se vuole l'atomicità, non deve esserci alcuna scrittura rifiutata tra le due.

rbamp_read_last_error

C
esp_err_t rbamp_read_last_error(rbamp_handle_t dev, uint8_t *out);

Legge REG_ERROR (0x02) direttamente — l'esito dell'ultima transazione accettata con successo dal bus (una scrittura o un comando). Non è sticky: ogni scrittura successiva riuscita lo sovrascrive con il proprio esito.

Usato nel Canale B (rifiuto lato DUT) per il codice di motivo esteso.

rbamp_has_error

C
esp_err_t rbamp_has_error(rbamp_handle_t dev, bool *out);

Una funzione di supporto sopra EVENT_FLAGS.bit3 (ERROR_OCCURRED, registro 0x2A). Restituisce true se bit3 è impostato. Sticky W1C; non si cancella finché non lo si cancella esplicitamente (con una riserva — vedi la sezione "Cancellazione di un errore durevole" sopra).

Usato per il monitoraggio a interrogazione di «si è verificato un guasto» — per esempio nei cicli di lunga durata in cui scritture intermedie potrebbero aver sovrascritto REG_ERROR, ma il bit3 conserva il fatto che almeno una di esse è stata rifiutata.

rbamp_read_event_flags / rbamp_clear_event_flags

C
esp_err_t rbamp_read_event_flags(rbamp_handle_t dev, uint8_t *out);
esp_err_t rbamp_clear_event_flags(rbamp_handle_t dev, uint8_t mask);

EVENT_FLAGS (0x2A) — un byte di flag sticky (RBAMP_EVENT_*, vedi Bit di evento, incluso RBAMP_EVENT_ERROR = bit3). La cancellazione è scrittura-1-per-cancellare: scriva una maschera con uno nei bit che vuole azzerare. I flag funzionano su entrambe le linee; sulla linea STD richiedono la versione della mappa dei registri 0x36 o successiva (ESP_ERR_NOT_SUPPORTED sotto).

Aiuta a separare le cause: può leggere prima tutti i flag, poi azzerare solo quelli gestiti, lasciando quelli non gestiti per il ciclo di polling successivo.

rbamp_clear_error

C
esp_err_t rbamp_clear_error(rbamp_handle_t dev);

Emette CMD_CLEAR_ERROR (opcode 0x31) — azzera REG_ERROR. Necessario per cancellare un errore persistente insieme a clear_event_flags(1<<3) (vedi sopra). Senza clear_error, un semplice clear_event_flags(1<<3) lascerà il bit3 a 1 dopo alcune centinaia di millisecondi a causa del riaggancio.

Eventi e linea di allarme

Gli eventi sono un unico modello su entrambe le linee: flag sticky (RBAMP_EVENT_*), scrittura-1-per-cancellare. I flag impostati anche nella maschera degli eventi tengono BASSA la linea DRDY (un allarme) finché non vengono cancellati o smascherati. La maschera e le soglie risiedono nella RAM del modulo — riarmile dopo ogni reset del modulo (RBAMP_EVENT_RESET_OCCURRED lo segnala; vedi anche rbamp_begin_event_flags()).

C
esp_err_t rbamp_read_event_mask     (rbamp_handle_t dev, uint8_t *out);
esp_err_t rbamp_set_event_mask      (rbamp_handle_t dev, uint8_t mask);
esp_err_t rbamp_set_event_thresholds(rbamp_handle_t dev, float i_amps, float p_watts);
Funzione Descrizione
rbamp_read_event_mask Quali flag tengono BASSA la linea DRDY (la classe di allarme).
rbamp_set_event_mask Imposti la maschera (RAM sul modulo; 0 = la linea non viene mai trattenuta). La scrittura viene riletta e verificata.
rbamp_set_event_thresholds Imposti le soglie (RAM del modulo): il canale di corrente più alto oltre i_amps imposta RBAMP_EVENT_THRESH_I, la potenza attiva totale oltre p_watts imposta RBAMP_EVENT_THRESH_P. Un valore <= 0 oppure NaN disattiva quella soglia. Restituisce ESP_ERR_NOT_SUPPORTED su un modulo STD con versione di mappa registri inferiore a 0x36.

Il confronto differisce per linea. La linea STD confronta la potenza totale assoluta (la direzione non conta). La linea BASIC confronta la somma con segno delle potenze dei canali, quindi l'esportazione non fa scattare mai la soglia di potenza; i valori oltre ciò che la codifica BASIC può contenere sono trattati come «disattivati». Su STD, rbamp_read_event_flags() richiede la versione della mappa registri 0x36 o successiva (altrimenti ESP_ERR_NOT_SUPPORTED).

Configurazione multicanale

Sui moduli multicanale (I2, I3, UI2, UI3, e i più grandi UI5 / UI7), ogni canale di corrente ha il proprio modello di sensore CT. L'utility atomica per la configurazione in blocco è rbamp_configure_channels.

rbamp_configure_channels

C
esp_err_t rbamp_configure_channels(rbamp_handle_t dev,
                                   rbamp_sensor_class_t cls,
                                   const uint8_t *models,
                                   uint8_t n);

Parameters:

  • cls — la classe del sensore, applicata per prima tramite rbamp_set_sensor_class().
  • models — un array di n codici di modello CT, uno per canale.
  • n — la lunghezza dell'array. Limitato alla variante: se n è maggiore del numero di canali su questa variante (per esempio n=3 su I2), la funzione limita al numero effettivo di canali; gli elementi extra dell'array vengono ignorati. Se n è minore del numero di canali, i canali mancanti restano intatti (mantengono il loro modello precedente). Una voce 0 in models salta quel canale. La chiamata copre tutti i canali del modulo, inclusi i canali 3+ su un UI5 / UI7.

Internamente la funzione esegue:

  1. set_sensor_class(cls) una volta.
  2. Per ogni canale k < min(n, n_channels): associa models[k]; ogni associazione è verificata in modo sincrono e confermata in rilettura.

  3. Un salvataggio finale della configurazione utente (oltre a quello dentro set_sensor_class) — cioè due cicli di cancellazione + scrittura della flash per l'intera configurazione, invece di 1 + n. È la proprietà "favorevole alla flash".

Lettura prima della scrittura. L'intera richiesta viene decisa prima della prima scrittura. Una classe o un modello che il modulo già possiede non viene riscritto, quindi ri-applicare la stessa configurazione costa solo letture e nessun ciclo di flash. Su un modulo di classe 2 o 3 una richiesta che cambierebbe la classe o un modello richiesto viene rifiutata subito con ESP_ERR_INVALID_STATE e non viene scritto nulla. Su un modulo di classe 1 con firmware più vecchio (fino alla 1.4.19) una configurazione che cambia un modello termina con un riavvio del modulo (vedi rbamp_set_ct_model_ch).

Returns:

  • ESP_OK — configurazione applicata e salvata.
  • ESP_ERR_INVALID_ARG — cls o models[k] non validi (validazione al passo di associazione, vedi la sezione «Modello di errore» qui sopra).

  • ESP_ERR_INVALID_STATE — un canale non ha potuto essere associato, oppure il modulo è calibrato con il sensore montato (classe 2 / 3).

  • Altri codici ESP-IDF — errore di bus, timeout, ecc.

rbamp_read_ct_model_ch

C
esp_err_t rbamp_read_ct_model_ch(rbamp_handle_t dev,
                                 uint8_t channel,
                                 uint8_t *out);

Legge il modello del sensore CT effettivamente applicato a un canale specifico (0 = non impostato). Lo usi per verificare l'associazione dopo rbamp_set_ct_model_ch(). I canali 0–2 leggono gli specchi piatti (0x51 / 0x52 / 0x53); i canali 3+ (UI5 / UI7) leggono tramite la finestra di canale. È una rilettura dalla RAM, non una conferma di persistenza — per confermare un salvataggio in flash usi un riavvio + rilettura. Sulla linea STD legge la voce di mappa del canale.

Gestore di flotta — gestione di più moduli

L'API della Flotta è la superficie di alto livello principale della libreria. Gestisce una raccolta di moduli su un bus I²C condiviso: rilevamento, provisioning, aggregazione dei poll, aggregazione degli errori, snapshot sincroni.

Tutte le funzioni di flotta sono thread-safe tramite un mutex interno; le chiamate concorrenti da task diversi vengono serializzate. Un unico proprietario di fleet da un task più accessi in sola lettura (per esempio _count, _get) dagli altri è accettabile, ma coordini esplicitamente le operazioni complesse a più passi.

Ciclo di vita

C
esp_err_t rbamp_fleet_create(i2c_master_bus_handle_t bus,
                             rbamp_fleet_t *out);
void      rbamp_fleet_destroy(rbamp_fleet_t fleet);

create riceve un bus e restituisce una flotta vuota. destroy libera tutti gli handle gestiti e la flotta stessa — dopo la chiamata, i puntatori agli handle ottenuti tramite rbamp_fleet_get sono non validi.

Scoperta — rbamp_fleet_scan

C
esp_err_t rbamp_fleet_scan(rbamp_fleet_t fleet,
                           bool match_product,
                           size_t *added);

Sonda il bus nell'intervallo 0x08..0x77; per ogni indirizzo che risponde con ACK:

  1. Verifica l'identità (PRODUCT_ID, HW_VARIANT, CAPABILITY). Se match_product = true, richiede una corrispondenza con il PRODUCT_ID di rbAmp.

  2. Esegue il rilevatore di conflitti (due segnali indipendenti; vedi 10 · Risoluzione dei problemi, sezione "Flotta: un modulo è finito in excluded"). Gli indirizzi sospetti finiscono nella lista excluded, non nella flotta.

  3. Esegue un canarino di blocco di Livello 2: sonda un indirizzo dove non dovrebbe esserci nessuno. Se il canarino riceve un ACK, restituisce ESP_ERR_INVALID_STATE — il bus è bloccato, la flotta resta vuota (vedi la diagnostica al cap. 10).

Dopo il successo, *added contiene il numero di moduli aggiunti alla flotta. excluded_count (vedi sotto) è disponibile tramite un getter separato.

Output da banco (validato su HW su una flotta eterogenea UI1+I2+I3 con pull-up esterne da 4.7 kΩ):

Text
rbamp_fleet_scan() → 3 module(s), 0 excluded
  module[0] @0x50  channels=1  voltage=yes   (UI1 — mains)
  module[1] @0x51  channels=2  voltage=no    (I2 — sub-meter)
  module[2] @0x52  channels=3  voltage=no    (I3 — sub-meter)
rbamp_fleet_count()          = 3
rbamp_fleet_excluded_count() = 0

In questo scenario un conflitto di indirizzo finirebbe nell'elenco degli esclusi (excluded_count > 0), e un bus bloccato finirebbe in ESP_ERR_INVALID_STATE con una flotta vuota (vedi 10 · Risoluzione dei problemi).

Accesso al modulo

C
size_t          rbamp_fleet_count(rbamp_fleet_t fleet);
rbamp_handle_t  rbamp_fleet_get(rbamp_fleet_t fleet, size_t index);
rbamp_handle_t  rbamp_fleet_find(rbamp_fleet_t fleet, uint8_t address);
esp_err_t       rbamp_fleet_add(rbamp_fleet_t fleet, rbamp_handle_t dev);

size_t          rbamp_fleet_excluded_count(rbamp_fleet_t fleet);
esp_err_t       rbamp_fleet_excluded_addr(rbamp_fleet_t fleet,
                                          size_t index,
                                          uint8_t *out);

_get restituisce NULL fuori intervallo; _find restituisce NULL se l'indirizzo non è nella flotta (per esempio perché è finito tra gli esclusi). _add permette di aggiungere manualmente un handle creato a parte (per esempio dopo una messa in servizio manuale).

Polling — rbamp_fleet_poll_all

C
esp_err_t rbamp_fleet_poll_all(rbamp_fleet_t fleet,
                               rbamp_snapshot_t *snaps,
                               rbamp_fleet_poll_t *status,
                               size_t capacity,
                               size_t *n_ok);

Interroga tutti i moduli della flotta in una sola chiamata. Per ogni modulo viene eseguita una lettura RT completa (rbamp_read_all), con il risultato allegato all'elemento snaps[i] corrispondente. In parallelo, status[i] riceve l'esito per modulo: ESP_OK, ESP_ERR_TIMEOUT (modulo silenzioso), ESP_FAIL (rifiuto di sanità), ecc.

Al ritorno, *n_ok è il numero di moduli per i quali è stato ottenuto uno snapshot valido (status[i] == ESP_OK).

Resiliente ai MISS: un modulo silenzioso non annulla il polling degli altri. Conta per una flotta di produzione — perdere un singolo modulo (un guasto di cablaggio, una bruciatura) non deve far cadere l'intero monitoraggio.

Aggregazione

C
esp_err_t rbamp_fleet_total_power(rbamp_fleet_t fleet, float *out_w);
esp_err_t rbamp_fleet_total_energy_wh(rbamp_fleet_t fleet, double *out_wh);
esp_err_t rbamp_fleet_poll_errors(rbamp_fleet_t fleet,
                                  uint32_t *error_mask,
                                  size_t *n_errors);

_total_power somma la potenza attiva su tutti i canali di tutti i moduli. Sulle varianti I non c'è potenza attiva → contribuiscono con 0. Nel deployment canonico (UI1 di rete + sotto-contatori I2/I3) il risultato è la potenza attiva del modulo di rete.

_total_energy_wh somma allo stesso modo gli accumulatori Wh degli handle. Funziona anche correttamente: le varianti I contribuiscono con 0, UI1 contribuisce con l'energia di rete.

_poll_errors scorre la flotta chiamando rbamp_has_error su ciascun modulo. *error_mask è una maschera di bit dei moduli segnalati con EVENT bit3, per posizione nella flotta (significativa per i primi 32 moduli); *n_errors è il numero totale di moduli con flag di errore al momento del poll. Entrambi i puntatori possono essere passati come NULL se non servono.

Indirizzamento e controllo dei conflitti

C
esp_err_t rbamp_fleet_assign_address(rbamp_fleet_t fleet,
                                     rbamp_handle_t dev,
                                     uint8_t new_addr);
esp_err_t rbamp_fleet_check_conflict(rbamp_fleet_t fleet,
                                     uint8_t addr,
                                     bool *collision);

_assign_address riassegna un modulo esistente della flotta a un nuovo indirizzo: internamente — commit in due fasi + reset; l'handle nella flotta viene aggiornato automaticamente (le chiamate successive continuano a funzionare).

_check_conflict — un controllo in sola lettura, a titolo di massima, per un indirizzo specifico: lo chiami una volta per ogni indirizzo di interesse. Legge l'identità (PRODUCT_ID / HW_VARIANT / CAPABILITY) e la confronta con lo stato in cache della flotta. Se rileva un'incoerenza (due dispositivi che rispondono allo stesso indirizzo con byte «fusi»; identità diversa dallo stato in cache) — *collision = true. Per scandire tutti gli indirizzi noti, scorra lei la flotta: for i in 0..count, check_conflict(fleet, addr, &col). Non garantisce di individuare moduli identici — vedi la disciplina di messa in servizio.

Messa in servizio — rbamp_provision

C
esp_err_t rbamp_provision(i2c_master_bus_handle_t bus,
                          uint8_t desired_addr,
                          bool save_config,
                          rbamp_handle_t *out);

Mette in servizio esattamente un modulo vergine (all'indirizzo di fabbrica 0x50) sull'indirizzo specificato. Internamente:

  1. Verifica che ci sia una risposta a 0x50 (ESP_ERR_NOT_FOUND se no).

  2. Verifica che nessuno sia ancora presente su desired_addr (ESP_ERR_INVALID_STATE se occupato).

  3. Esegue un commit dell'indirizzo in due fasi.

  4. Esegue un reset del modulo e attende che ricompaia a desired_addr nella finestra di avvio (ESP_ERR_TIMEOUT se non compare).

  5. Crea un handle; se save_config = true — chiama rbamp_save_user_config (persiste in flash).

  6. Restituisce l'handle pronto tramite *out.

Sicurezza

⚠ OBBLIGATORIO: esattamente un solo modulo vergine sul bus nel momento della chiamata. Due moduli su 0x50 contemporaneamente sono fisicamente indistinguibili su I²C — non si distinguono neppure con hardware speciale. La garanzia è in capo all'operatore, non alla libreria. Per il ripristino, vedi 10 · Risoluzione dei problemi, sezione «Flotta: rbamp_provision ha restituito un errore».

Sincronizzazione GC della flotta — snapshot sincroni su tutta la flotta

C
esp_err_t rbamp_fleet_enable_gc_all(rbamp_fleet_t fleet,
                                    uint8_t group,
                                    size_t *ok_count);
esp_err_t rbamp_fleet_gclatch(rbamp_fleet_t fleet,
                              uint8_t group,
                              uint16_t tick,
                              uint32_t settle_ms);
esp_err_t rbamp_fleet_check_sync(rbamp_fleet_t fleet,
                                 uint16_t expected_tick,
                                 rbamp_fleet_sync_t *status,
                                 size_t status_cap,
                                 size_t *n_missed);

Per una sincronia stretta degli snapshot (sfasamento < 1 ms su tutta la flotta) si usa un broadcast snapshot I²C General-Call.

  1. _enable_gc_all imposta FLEET_CONFIG.bit0 + GROUP_ID su tutti i moduli della flotta ed esegue CMD_SAVE_USER_CONFIG su ciascuno (in modo persistente). Un riavvio dei moduli è obbligatorio dopo l'abilitazione — viene eseguito automaticamente. Basta chiamarlo una volta durante la configurazione iniziale della flotta. *ok_count (facoltativo) è il numero di moduli per i quali l'abilitazione è riuscita.

  2. _gclatch invia il frame GC A5 27 group tick_lo tick_hi all'indirizzo 0x00 — tutti i moduli con GC abilitato e un group corrispondente fanno immediatamente lo snapshot (LATCH_PERIOD). settle_ms è la pausa dopo il frame (tipicamente 50 ms) prima della verifica.

  3. _check_sync legge GC_TICK (0x59) su ogni modulo in rbamp_fleet_sync_t status[status_cap]. Il risultato per modulo:

C
typedef struct {
    uint8_t  addr;        /* module I²C address */
    uint16_t gc_tick;     /* REG_GC_TICK; 0xFFFF = never received a GC */
    bool     in_sync;     /* true if gc_tick == expected_tick */
    bool     reachable;   /* false if the read NACKed / timed out */
} rbamp_fleet_sync_t;

*n_missed è il numero di moduli con in_sync = false (o semplicemente che non rispondono). Se tutti sono in_sync, n_missed == 0.

Sicurezza

Non li confonda: il rbamp_broadcast_latch per dispositivo (vedi la sezione «Bus multimodulo» più sotto) è un frame sull'intero bus; la sincronizzazione GC della flotta è lo stesso frame, ma l'API di flotta aggiunge un controllo di testimonianza (che sia arrivato su tutti i moduli attesi). Veda anche 04 · Cablaggio per le precondizioni GC.

Configurazione della flotta per dispositivo

Queste funzioni lavorano con un singolo modulo direttamente (senza flotta) — per i casi in cui configura un singolo modulo prima di aggiungerlo a una flotta, oppure vuole un controllo fine.

rbamp_enable_gc / rbamp_read_fleet_config

C
esp_err_t rbamp_enable_gc(rbamp_handle_t dev, bool enable);
esp_err_t rbamp_read_fleet_config(rbamp_handle_t dev, uint8_t *out);

enable_gc(dev, true) scrive 1 in FLEET_CONFIG.bit0 (0x27) — il modulo inizierà ad accettare snapshot GC dopo il successivo CMD_SAVE_USER_CONFIG + reset. enable_gc(dev, false) fa il contrario azzerando il bit (il modulo smette di accettare GC dopo il reset). read_fleet_config restituisce il byte di configurazione attuale — utile per la conferma in rilettura.

rbamp_set_group_id / rbamp_read_group_id

C
esp_err_t rbamp_set_group_id(rbamp_handle_t dev, uint8_t group_id);
esp_err_t rbamp_read_group_id(rbamp_handle_t dev, uint8_t *out);

GROUP_ID (0x28) — il filtro dei frame GC: il modulo reagisce solo ai frame GC con un group_id corrispondente. Valore predefinito = 0x00 (broadcast, reagisce a qualsiasi). Usato per bus multi-utente — per esempio un gruppo "fase A" e un gruppo "fase B" su un unico bus condiviso.

rbamp_read_gc_tick

C
esp_err_t rbamp_read_gc_tick(rbamp_handle_t dev, uint16_t *out);

Legge GC_TICK (0x59) — l'ultimo valore di tick ricevuto da un frame GC. Usato per rilevare frame persi (se due moduli hanno tick diversi, qualcuno ha perso un frame).

rbamp_read_label / rbamp_write_label

C
esp_err_t rbamp_read_label(rbamp_handle_t dev, char out[9]);
esp_err_t rbamp_write_label(rbamp_handle_t dev, const char *label);

LABEL (0x68..0x6F) — una stringa etichetta utente di 8 byte (ASCII, con riempimento di zeri). Aiuta a identificare i moduli in una flotta — per esempio «MAINS», «BOILER», «AC1». read_label restituisce sempre un array di 9 byte (8 byte di dati più un \0 terminatore). write_label accetta una stringa terminata da null — i byte in più vengono troncati.

Nota

La scrittura avviene byte per byte (nessun auto-incremento in scrittura — vedi "Scritture nei registri" più sotto). Dopo la scrittura, serve rbamp_save_user_config perché l'etichetta sopravviva a un reset.

rbamp_broadcast_latch_group

C
esp_err_t rbamp_broadcast_latch_group(i2c_master_bus_handle_t bus,
                                      uint8_t group_id,
                                      uint16_t tick);

Un invio a basso livello del frame GC A5 27 group tick_lo tick_hi direttamente attraverso l'handle bus (senza flotta). Utile se la flotta non è ancora stata creata, o se vuole un controllo manuale del contatore dei tick.

rbamp_reset_counters

C
esp_err_t rbamp_reset_counters(rbamp_handle_t dev);

Azzera i contatori diagnostici del modulo (contatore di errori i2c, contatore di reinizializzazioni delle periferiche). Non tocca la configurazione utente né la calibrazione. Usato per i test da banco e per gli azzeramenti periodici dei contatori nei lunghi test di produzione.

Configurazione del sensore

Una sequenza in due passi: prima la classe del sensore, poi il modello. Entrambi i passi sono obbligatori su un modulo con sensore montato dall'utente (classe 1). I moduli forniti con il proprio sensore (classe 2 / 3) arrivano configurati e sono protetti da riscritture accidentali — vedi le note di lettura-prima-della-scrittura più sotto.

Per una guida dettagliata alla scelta del modello, vedi 03 · Selezione del sensore di corrente.

rbamp_set_sensor_class

C
esp_err_t rbamp_set_sensor_class(rbamp_handle_t dev,
                                 rbamp_sensor_class_t cls);

Imposta la classe del sensore e la rende persistente.

Lettura prima della scrittura. La funzione legge prima la classe che il modulo detiene. Scrivere il valore che possiede già è un no-op senza scrittura sul bus (ESP_OK) — sul modulo qualsiasi scrittura di classe, anche invariata, azzera il modello CT e la forma di calibrazione di ogni canale, quindi una scrittura inutile degraderebbe le letture. Un modulo la cui classe è 2 o 3 (calibrato insieme al sensore montato) non viene riscritto: ESP_ERR_INVALID_STATE.

Altrimenti scrive la classe, verifica che il modulo l'abbia accettata e la rende persistente con il salvataggio della configurazione utente (~700 ms, bloccante). Impostare la classe azzera anche i modelli di CT sul modulo, quindi imposti i modelli successivamente.

Sul firmware v1.2+ una classe impostata è un prerequisito per rbamp_set_ct_model() e rbamp_set_ct_model_ch() — chiamarne uno mentre la classe è ancora RBAMP_SENSOR_UNSET restituisce ESP_ERR_INVALID_STATE. Vedi 10 · Risoluzione dei problemi, sezione «La corrente legge zero», per il sintomo «ho scritto UNSET per errore».

Restituisce: ESP_OK in caso di successo, oppure quando il modulo ha già questa classe; ESP_ERR_INVALID_ARG su dev == NULL, un cls non riconosciuto, oppure quando il modulo rifiuta la scrittura; ESP_ERR_INVALID_STATE quando la classe attuale del modulo è 2 o 3; codici di errore I²C in caso di guasto del collegamento.

Linea STD. Scrive la classe come metadato (la linea STD non ha una tabella di preset) e la rende persistente; il verdetto del comando del modulo viene verificato.

rbamp_set_ct_model

C
esp_err_t rbamp_set_ct_model(rbamp_handle_t dev, uint8_t code);

La forma a parametro singolo — imposta il modello di CT solo sul canale 0 (equivale a rbamp_set_ct_model_ch(dev, 0, code); sulla linea STD è quella chiamata). Bloccante, ~700 ms quando scrive.

L'insieme di modelli ammessi per la classe attiva è la verità a runtime del firmware — la libreria non tiene alcun elenco lato client dei codici. Una coppia (classe, modello) sconosciuta viene rifiutata dal modulo e segnalata come ESP_ERR_INVALID_STATE (oppure ESP_ERR_INVALID_ARG dalla verifica sincrona della scrittura). I codici e i nomi dei modelli sono nel file generato rbamp_sensor_models.h (rbamp_sensor_model_lookup()); per la classe 1:

code Modello
1 SCT-013-005
2 SCT-013-010
3 SCT-013-030
4 SCT-013-050
5 SCT-013-100
6 SCT-013-020
7 SCT-013-060

(Tutti e sette i codici SCT-013 sono selezionabili; l'insieme ammesso è {1, 2, 3, 4, 5, 6, 7}.)

Preconditions.

rbamp_set_sensor_class() deve essere stata chiamata per prima (altrimenti ESP_ERR_INVALID_STATE, nessuna scrittura). Si applica anche la guardia di lettura-prima-della-scrittura di rbamp_set_ct_model_ch().

Per i moduli multicanale usi la forma per canale qui sotto.

rbamp_set_ct_model_ch

C
esp_err_t rbamp_set_ct_model_ch(rbamp_handle_t dev,
                                uint8_t channel, uint8_t code);

La forma per canale. Una chiamata pubblica per qualsiasi canale; l'instradamento è interno: i canali 0–2 preparano il modello e lo applicano con il comando per canale, i canali 3+ (UI5 / UI7, firmware v1.4.18+) lo applicano attraverso la finestra dei canali. In entrambi i casi il modello applicato viene confermato in rilettura e poi persistito (~700 ms). channel è validato rispetto al numero effettivo di canali del modulo.

Nota

L'ordine di associazione è arbitrario (canone v1.3). L'associazione CT è pura predisposizione: ogni applicazione per canale associa solo il proprio canale, quindi i canali possono essere configurati in qualsiasi ordine — crescente, decrescente o alternato — senza sovrascriversi a vicenda:

C
rbamp_set_ct_model_ch(dev, 0, 1);  /* channel 0 = SCT-013-005 */
rbamp_set_ct_model_ch(dev, 1, 3);  /* channel 1 = SCT-013-030 */
rbamp_set_ct_model_ch(dev, 2, 6);  /* channel 2 = SCT-013-020 */
rbamp_set_ct_model_ch(dev, 4, 3);  /* channel 4 (UI5 / UI7) */

Guardia di lettura prima della scrittura. Applicare un modello sostituisce qualsiasi calibrazione che l'unità porta per quel canale con il preset generico del modello, e il modulo lo fa anche quando il modello non cambia. Quindi:

  • il modello che il canale detiene già (vedi rbamp_read_ct_model_ch()) è un no-op senza scrittura sul bus — riapplicare una configurazione memorizzata a ogni riconnessione è sicuro e non provoca nessun riavvio inutile del modulo;

  • un modulo di classe 2 o 3 restituisce ESP_ERR_INVALID_STATE; rbamp_set_ct_model_ch_force() è il percorso di assistenza.

Riavvio del modulo sul firmware di classe 1 precedente. Su un modulo BASIC di classe 1 senza la capacità di autocorrezione (firmware fino alla 1.4.19), una chiamata che cambia il modello termina con un riavvio del modulo (circa un secondo, stesso UID verificato): è l'unico modo in cui il modulo torna al proprio guadagno calibrato dopo una scrittura di modello. La libreria valuta quindi la correzione della portata (rbamp_sct_correction()) e scala le letture dal guadagno applicato dal modulo. Lo stato RAM del modulo (campi di digest, maschera degli eventi, soglie) viene riapplicato dalla libreria dove è di sua competenza; gli accumulatori di periodo ripartono, come dopo un qualsiasi reset del modulo.

Ritorna: ESP_OK; ESP_ERR_INVALID_ARG su dev == NULL o channel >= rbamp_channels(dev); ESP_ERR_NOT_SUPPORTED su firmware più vecchio della v1.2 (canali 0–2), o su un modulo STD che non persiste un modello CT per canale; ESP_ERR_INVALID_STATE se la classe è UNSET, il modulo rifiuta la coppia (class, model), il modello applicato fallisce la conferma in rilettura, o il modulo è di classe 2 / 3; ESP_FAIL / ESP_ERR_TIMEOUT su un guasto di trasporto.

Linea STD. Il modello di CT è solo di riferimento (metadato dello SKU): non imposta alcun guadagno — il modulo ha una propria calibrazione per canale. Sul firmware attuale dei moduli a canale singolo sopravvive a un reset solo il modello del canale 0.

rbamp_set_ct_model_ch_force

C
esp_err_t rbamp_set_ct_model_ch_force(rbamp_handle_t dev,
                                      uint8_t channel, uint8_t code);

Il percorso di assistenza: come rbamp_set_ct_model_ch(), ma scrive indipendentemente dalla classe del modulo e dal modello attualmente detenuto. Sostituisce la calibrazione accoppiata di quel canale con il preset generico del modello — lo usi solo quando riassocia un modulo a un nuovo sensore in assistenza, e lo segua con una calibrazione.

rbamp_read_sensor_class

C
esp_err_t rbamp_read_sensor_class(rbamp_handle_t dev, uint8_t *out);

La classe del sensore di corrente del modulo come valore di rbamp_sensor_class_t (BASIC: il registro della classe; STD: il campo di configurazione della classe).

Limiti dei modelli di sensore

C
bool  rbamp_sensor_model_limits (uint8_t sensor_class, uint8_t code,
                                 float *nominal_a, float *fs_a, float *peak_a);
float rbamp_sensor_model_rated_a(uint8_t sensor_class, uint8_t code);

Pure ricerche nel registro dei modelli generato (rbamp_sensor_models.h) — nessun traffico sul bus.

  • rbamp_sensor_model_limits compila (ogni output può essere NULL): nominal_a — la corrente RMS nominale, A; fs_a — la corrente RMS alla quale un'onda sinusoidale inizia a tagliarsi, A; peak_a — il tetto istantaneo di taglio, A (un carico distorto taglia a peak_a diviso il suo fattore di cresta). 0 significa non noto per quel modello (codici legacy a toroide / burden). Restituisce true se la coppia (class, code) è nel registro, false altrimenti (gli output sono allora 0).

  • rbamp_sensor_model_rated_a è l'abbreviazione di nominal_a. È il valore nominale del sensore, che può differire dagli ampere nel nome del modello (la pinza "5 A" ha un valore nominale di 4.6 A). Usi rbamp_sensor_model_lookup() per il nome del modello.

Una corrispondenza nel registro non significa che il modulo connesso accetti il codice — è la verità a runtime.

Correzione della portata SCT-013

Un modulo BASE di classe sensore 1 è calibrato in fabbrica con il sensore da 30 A (modello 3). Sul firmware fino a 1.4.19 un cambio su un altro modello lascia il modulo che applica la calibrazione da 30 A dopo un riavvio, quindi un sensore più grande legge basso. Un modulo che dichiara la capacità di auto-correzione (firmware 1.4.20 e successivi) si corregge da solo e non richiede nulla di tutto questo.

Per il firmware più vecchio la libreria legge il guadagno che il modulo applica davvero — a rbamp_begin(), dopo una scrittura del modello e dopo ogni riavvio del modulo rilevato — e scala corrente, corrente di picco, potenza reale, potenza media di periodo, energia integrata, digest e soglie di evento a partire da quel guadagno e dal modello selezionato. Tensione e fattore di potenza non sono scalati. L'esito per canale è rbamp_sct_status_t (vedi Tipi). Un guadagno che è ancora uguale al preset grezzo (il modello è stato commutato in questo avvio senza riavvio) provoca un riavvio del modulo; un guadagno applicato inatteso, un modello sconosciuto o un preset grezzo che sopravvive al riavvio lasciano le letture non scalate con un avviso nel log. CONFIG_RBAMP_SCT_RATING_CORRECTION (predefinito attivo) disattiva il meccanismo, e vengono restituiti i valori grezzi del modulo.

C
esp_err_t rbamp_sct_correction(rbamp_handle_t dev, uint8_t ch,
                               rbamp_sct_correction_t *out);
esp_err_t rbamp_sct_refresh   (rbamp_handle_t dev);
Funzione Descrizione
rbamp_sct_correction(dev, ch, &c) La correzione memorizzata del canale ch — nessun traffico sul bus. Valutata da rbamp_begin(), da rbamp_set_ct_model*() e dopo un riavvio del modulo rilevato (un RESET_OCCURRED cancellato, un RESET in attesa nel digest, un uptime in calo). ESP_ERR_NOT_SUPPORTED sulla linea STD.
rbamp_sct_refresh(dev) Rilegge ora classe, modelli e guadagni applicati, e ricalcola le scale. Esegue un riavvio del modulo (e riesegue il rilevamento del modulo, UID verificato di nuovo) quando il guadagno applicato di un canale è ancora il preset grezzo di un modello diverso da quello da 30 A. Chiamata internamente dove necessario; esposta per un host che sa che il modulo è stato riavviato con altri mezzi. Non fa nulla e restituisce ESP_OK sulla linea STD e su un modulo che si auto-corregge.

rbamp_save_gains

C
esp_err_t rbamp_save_gains(rbamp_handle_t dev);

Una scrittura CMD_SAVE_GAINS "nuda", senza modifiche di registro associate.

Sicurezza

⚠ Di norma viene chiamato all'interno del componente. Un rbamp_save_gains() nudo è appropriato SOLO se il chiamante ha scritto manualmente nei registri di calibrazione non pubblici tramite accesso grezzo al bus — è un'operazione fuori garanzia, che aggira la tabella dei preset per SKU. Valori errati produrranno letture di corrente/potenza sbagliate senza avvisi espliciti. Ogni chiamata esegue un ciclo di cancellazione e scrittura della flash (~700 ms); la durata della flash è finita (~10000 cicli per pagina) — non lo chiami in un ciclo.

Linea STD. Esegue il salvataggio della calibrazione (persiste il blocco di calibrazione: guadagni, minimi di rumore e THD) e verifica l'esito del comando.

rbamp_prepare_address_change / rbamp_commit_address_change

La modifica dell'indirizzo I²C del modulo avviene tramite un commit in due fasi in modalità produzione. Il firmware esclude deliberatamente l'indirizzo dal normale flusso CMD_SAVE_USER_CONFIG / CMD_SAVE_GAINS — una modifica richiede una sequenza esplicita con armatura magica.

C
esp_err_t rbamp_prepare_address_change(rbamp_handle_t dev,
                                       uint8_t new_addr);
esp_err_t rbamp_commit_address_change(rbamp_handle_t dev);

Protocollo sul filo, sotto il cofano:

  1. prepare: valida l'intervallo di new_addr (0x08..0x77, ≠ attuale) → scrive new_addr in REG_I2C_ADDRESS (0x30) — finisce in RAM.

  2. prepare: scriva 0xA5 in REG_ADDR_COMMIT_MAGIC (0x31) — questo «arma» il commit. La finestra di armatura è di 5 secondi.

  3. commit: verifica la freschezza dell'armatura → invia CMD_COMMIT_ADDR (opcode 0x30) → scrive in flash → CMD_RESET

  4. ~400 ms di avvio → aggiorni il campo di indirizzo interno dell'handle.

Dopo un commit riuscito, tutte le chiamate su questa istanza di handle sono indirizzate al nuovo indirizzo. L'operazione funziona in modalità produzione (non bloccata), il che supporta la sostituzione sul campo dei moduli di ricambio di produzione.

Sicurezza

⚠ Se la finestra di armatura (5 s) è scaduta — commit restituisce ESP_ERR_TIMEOUT, il flag di armatura viene azzerato, e deve ripartire da prepare.

Linea STD. Il cambio di indirizzo è sincrono e l'handle commuta solo dopo che un modulo risponde al nuovo indirizzo — vedi rbamp_commit_address_change sulla linea STD. In caso di errore l'handle mantiene il vecchio indirizzo (ESP_ERR_NOT_FOUND).

⚠ La persistenza è confermata solo dopo un reset. Prima del reset, rbamp_read_* può restituire i nuovi valori dalla RAM, ma la scrittura in flash potrebbe non essere ancora terminata. Il componente esegue da sé un CMD_RESET integrato + attesa di avvio dentro commit, quindi dopo un ritorno positivo lo stato è garantito come persistente.

⚠ Riavvio e nuova enumerazione dopo il commit. Dopo un commit riuscito, il dispositivo si resetta e si rienumera al NUOVO indirizzo. Le chiamate successive su questa istanza di handle sono indirizzate al nuovo indirizzo in modo trasparente — ma qualsiasi ALTRO master sul bus (uno script Python, un componente ESP-IDF su un altro MCU, una sonda di debug) continuerà a credere che il dispositivo sia all'indirizzo vecchio finché il suo stato interno non viene aggiornato manualmente.

rbamp_factory_reset

C
esp_err_t rbamp_factory_reset(rbamp_handle_t dev);

Il comando CMD_FACTORY_RESET (0xAA) + un'attesa di 1500 ms.

Sicurezza

⚠ Operazione distruttiva. Cancella TUTTI i parametri in flash (modello di CT, classe del sensore, coefficienti di calibrazione, indirizzo I²C). Il modulo torna ai valori di fabbrica — rbamp_sensor_class_t diventa RBAMP_SENSOR_UNSET, REG_CT_MODEL diventa 0. Ogni impostazione applicata in precedenza con rbamp_set_sensor_class() / rbamp_set_ct_model*() scompare. Il successivo utente DEVE ri-applicare sia rbamp_set_sensor_class() sia rbamp_set_ct_model*() prima che la contabilità torni operativa. Non è un «riavvio a caldo» — per un riavvio a caldo usi rbamp_reset(). rbamp_factory_reset() è riservato al ripristino da uno stato noto come compromesso o alla consegna del modulo a un altro utente / installazione.

Linea STD. Non esiste un comando di ripristino di fabbrica: rbamp_factory_reset() restituisce ESP_ERR_NOT_SUPPORTED.

rbamp_reset

C
esp_err_t rbamp_reset(rbamp_handle_t dev);

Il comando CMD_RESET (0x01) + un'attesa di 100 ms. Un riavvio a caldo del dispositivo senza perdere i parametri in flash.

Bus multi-modulo

rbamp_broadcast_latch

C
esp_err_t rbamp_broadcast_latch(i2c_master_bus_handle_t bus,
                                uint32_t timeout_ms);

Sul firmware v1.3 (REG_VERSION = 0x04) questo è il percorso canonico di sincronizzazione della flotta, una volta che il General-Call è stato abilitato su tutta la flotta tramite rbamp_fleet_enable_gc_all(). Il frame General-Call da 5 byte A5 27 fa sì che ogni modulo esegua lo snapshot nel gruppo corrispondente nello stesso istante sul filo, dando una sincronizzazione stretta tra i sotto-contatori. La funzione usa solo il bus: trasmette il frame (ESP_OK significa che il driver host non ha dato errori — il General Call è solo in scrittura, nessun modulo risponde con ACK; ESP_ERR_INVALID_ARG su un bus NULL). I moduli senza supporto General-Call, o con esso disabilitato, ignorano semplicemente il frame — lo verifichi con il testimone per modulo (sotto) e usi il ripiego sequenziale se non hanno fatto lo snapshot. rbamp_broadcast_latch_group(bus, group, tick, timeout_ms) è lo stesso con un filtro di gruppo esplicito e un tick di flotta.

Ripiego sequenziale (firmware legacy o quando GC è stato lasciato disabilitato): una serie di rbamp_latch_period() su ciascun dispositivo, un assestamento comune di 50 ms, e per dispositivo rbamp_read_period_snapshot(skip_latch=true) — vedi 06 · Esempi, scenario "Monitoraggio di più moduli".

Linea STD

La linea di moduli STD parla un modello di registri diverso dietro lo stesso handle. rbamp_begin() lo rileva; l'API scalare dei capitoli precedenti funziona invariata su entrambe le linee (rbamp_read_current, _power, _voltage, rbamp_read_period_snapshot, rbamp_energy_wh, le chiamate di configurazione, …). Le funzioni di questo capitolo sono le aggiunte solo-STD: canali interi in una raffica, le grandezze che solo questa linea misura (potenza reattiva / apparente, THD, contatori di energia con segno), banchi di snapshot, l'orologio del modulo, storico, stato di salute, aggiornamento firmware. Ogni funzione rbamp_std_* restituisce ESP_ERR_NOT_SUPPORTED su un handle BASE.

Molte funzioni richiedono una versione minima della mappa dei registri del modulo (indicata come "mappa 0x35+" e simili più sotto). La disponibilità delle funzioni dipende dalle capacità e dalla versione della mappa riportate dal modulo (rbamp_std_info()), mai da supposizioni; quando un modulo è troppo vecchio la funzione restituisce ESP_ERR_NOT_SUPPORTED — nella maggior parte dei casi senza traffico sul bus. Un esempio funzionante è examples/std_meter/.

Identità e discovery

C
typedef struct {
    uint8_t  map_version;
    uint16_t capabilities;      /* RBAMP_STD_CAP_* bitmap */
    uint8_t  status;            /* RBAMP_STD_ST_* bits at begin() time */
    uint8_t  n_voltage;         /* populated voltage channels */
    uint8_t  n_current;         /* populated current channels */
    uint8_t  variant;           /* raw RBAMP_STD_VARIANT_* byte */
    uint32_t active_bank;       /* running firmware bank, 0 without OTA capability */
    uint32_t ota_bank_size;     /* flash bank size, 0 if none */
    rbamp_std_period_source_t period_source;
} rbamp_std_info_t;

typedef struct {
    uint8_t  i2c_addr;
    uint8_t  map_version;
    uint16_t capabilities;
    uint8_t  variant;
    uint8_t  n_voltage, n_current;
    uint8_t  uid[12];           /* chip UID — the identity; addresses can change */
    uint32_t fw_version;        /* running image version (map 0x35+; 0 if unknown) */
    uint32_t board_id;          /* map 0x36+; 0 below */
} rbamp_std_identity_t;
Funzione Descrizione
rbamp_std_info(dev, &info) L'identità memorizzata da rbamp_begin() — nessun traffico sul bus. Restituisce ESP_ERR_NOT_SUPPORTED su un handle BASE o prima di rbamp_begin(). Il controllo dei canali avviene tramite n_voltage / n_current: i registri dei canali oltre questi conteggi non sono specificati e la libreria si rifiuta di leggerli.
rbamp_std_identify(dev, &id) Tutto ciò che un master deve per riconoscere il modulo dietro un handle (da due a quattro letture brevi).
rbamp_std_probe(bus, addr, &id) Sonda un indirizzo su un bus senza handle — il mattone base di una scansione. Veloce: nessun ritentativo, un NACK è la risposta. ESP_OK con id compilato; ESP_ERR_NOT_FOUND se nulla dà ACK; ESP_ERR_INVALID_RESPONSE se risponde qualcosa che non è un modulo STD (un modulo BASIC, un altro chip).
rbamp_std_read_image_version(dev, &v) La versione dell'immagine del firmware in esecuzione (u32, per esempio 0x00010072). Diversa da rbamp_firmware_version(), che è la versione della mappa registri su questa linea. 0 se il modulo non è in grado di dirlo.
rbamp_std_read_board_id(dev, &id) ID scheda dell'immagine in esecuzione (mappa 0x36+): una parola che codifica l'hardware per cui l'immagine è stata costruita. Un'immagine firmware viene accettata solo quando la parola della scheda corrisponde (vedi rbamp_std_ota_board_ok).
rbamp_std_locate(dev) Faccia lampeggiare i LED del modulo per circa 10 s così una persona può trovarlo.
rbamp_std_set_address_by_uid(bus, shared_addr, uid, new_addr, restart_ms) Assegni a un modulo su un indirizzo condiviso un proprio indirizzo, selezionato tramite UID (mappa 0x36+). Più moduli possono stare su shared_addr (es. il predefinito di fabbrica); solo quello il cui UID corrisponde prende new_addr, lo persiste e si riavvia; gli altri ignorano il comando. Non serve alcun handle. Dopo il riavvio la libreria sonda new_addr e verifica lì l'UID. restart_ms 0 = 1500 ms. ESP_ERR_NOT_FOUND se a new_addr non risponde nessuno; ESP_ERR_INVALID_RESPONSE se un modulo risponde lì ma il suo UID è diverso.

Come un modulo STD consegna l'energia di periodo

C
typedef enum {
    RBAMP_STD_PERIOD_NONE     = 0,
    RBAMP_STD_PERIOD_LATCH    = 1,
    RBAMP_STD_PERIOD_COUNTERS = 2,
} rbamp_std_period_source_t;

Stabilito da rbamp_begin() in base alle capacità del modulo ed esposto in rbamp_std_info_t.period_source:

  • LATCH — il modulo ha banchi di snapshot. Un periodo va da snapshot a snapshot sul banco 0; medie ed energia per canale provengono dal banco. Vedi Banchi di snapshot.

  • COUNTERS — nessun banco di snapshot, ma contatori di vita persistenti. Un periodo è la differenza tra due letture di contatore, prese secondo la programmazione del master; non esiste un comando di snapshot, niente da armare, e nulla va perso al riavvio del modulo. Vedi Contatori di energia di vita.

  • NONE — nessuno dei due: le chiamate di periodo ed energia restituiscono ESP_ERR_NOT_SUPPORTED.

Blocchi in tempo reale

C
typedef struct {
    float   i_rms;        /* A */
    float   i_peak;       /* A — reads 0 on module map 0x34 and earlier */
    float   p, q, s;      /* W (signed), var (signed), VA */
    float   pf;           /* −1..+1 */
    float   thd_i;        /* % — 0 while harmonics are off */
    float   pf1;          /* displacement power factor — 0 while harmonics are off */
    float   q1;           /* fundamental reactive power, var — 0 while harmonics are off */
    int64_t e_import_mws; /* raw signed import accumulator, mW·samples (>= 0) */
    int64_t e_export_mws; /* raw signed export accumulator, mW·samples (<= 0) */
    uint8_t implausible;  /* RBAMP_FIELD_* bits set to NaN */
} rbamp_std_channel_t;

typedef struct {
    float   u_rms, u_peak, thd_u;  /* V, V (0 on map 0x34 and earlier), % */
    uint8_t implausible;
    float   angle_deg;             /* phase angle against voltage input 0, (−180, 180]; input 0 reads 0 */
    bool    angle_valid;           /* the module publishes the angle for this input */
} rbamp_std_voltage_t;
Funzione Descrizione
rbamp_std_read_channel(dev, ch, &c) Un blocco di canale di corrente (I / P / Q / S / PF / picco / accumulatori di energia / armoniche) in un'unica raffica; ch va da 0..rbamp_channels(dev)-1. I campi sono coerenti nella misura in cui il modulo li pubblica (per finestra di pubblicazione); per uno snapshot multi-campo strettamente atomico usi lo snapshot di periodo. Un campo che supera un limite di plausibilità è NaN con il suo bit RBAMP_FIELD_* in implausible.
rbamp_std_read_totals(dev, k, &c) Un blocco aggregato: k = 0 il totale generale (somma di tutti i canali di corrente), k = 1..3 i totali per fase A/B/C (solo moduli multi-fase). I totali per fase sono pubblicati dalla mappa 0x36 — su un modulo monofase k = 1 coincide con il canale 0 e k = 2/3 leggono 0; sotto 0x36 restituiscono ESP_ERR_NOT_SUPPORTED (k = 0 funziona sempre). I campi energia (e_import_mws / e_export_mws) non sono compilati per i blocchi aggregati e leggono 0 — l'energia proviene dai contatori persistenti (rbamp_std_read_energy).
rbamp_std_read_voltage(dev, v, &u) Un blocco di canale di tensione (RMS / picco / THD / angolo di fase) in un'unica raffica; v è 0..n_voltage-1. angle_deg / angle_valid sono pubblicati dai moduli trifase con versione di immagine 0x0001007A o successiva; altrimenti angle_valid è false e il resto del blocco non cambia. Su un modulo trifase a sequenza diretta l'ingresso 1 legge circa −120° e l'ingresso 2 circa +120°.
rbamp_std_read_phase_seq(dev, &seq) L'ordine degli ingressi di tensione, ricavato dal modulo dagli angoli: RBAMP_STD_PHASE_SEQ_NA (meno di tre ingressi, oppure un ingresso troppo basso), _FORWARD (L1-L2-L3), _REVERSE (L1-L3-L2), _ABNORMAL (nessuno schema a 120°, per esempio due ingressi collegati alla stessa fase). Restituisce ESP_ERR_NOT_SUPPORTED (e *seq = NA) su una versione di immagine del modulo anteriore a 0x0001007A, senza traffico sul bus.
Nota

thd_i, pf1, q1 e thd_u valgono 0 salvo che l'estrazione delle armoniche sia abilitata — vedi Configurazione. e_import_mws / e_export_mws sono gli accumulatori grezzi del modulo in mW·campioni; il modulo non ha un orologio, quindi la conversione in Wh richiede il numero di campioni e la sua temporizzazione del periodo (usi il percorso degli snapshot o i contatori di vita). Per il monitoraggio, integri p sull'intervallo di polling.

rbamp_read_all() su un modulo STD legge per intero il blocco di tensione e ciascun blocco di canale (una transazione ciascuno) invece di campo per campo. rbamp_read_frequency() su un modulo STD restituisce ESP_ERR_INVALID_RESPONSE con *out = NaN quando il modulo pubblica 0 (nessuna rete); rbamp_read_all() genera allora RBAMP_FIELD_FREQUENCY. rbamp_read_voltage_peak() / rbamp_read_current_peak() leggono 0 sulla mappa 0x34 e precedenti — usi max_u / min_u / max_i di un banco di snapshot per il picco sul periodo.

Salute

C
typedef struct {
    uint8_t  status;        /* RBAMP_STD_ST_* bits: cal_ok / sensor_ok / mains_ok / locked / time_valid */
    uint32_t frame_count;   /* sensor frame counter — must grow between polls */
    uint32_t crc_errors;    /* sensor frame CRC error counter */
    bool     time_valid;    /* the module clock is set; false after every module reset */
    bool     nvm_fault;     /* energy store fault or corrupt (details in lta_status) */
    uint8_t  lta_status;    /* life-time energy store: 0 ok · 1 new · 2 fault · 3 corrupt (service) */
    uint8_t  lta_src;       /* counters loaded from: 0 none · 1 NVM · 2 backup domain · 3 legacy · 4 rollback anchor */
    uint8_t  cal_src;       /* calibration in use: 0 defaults · 1 flash · 2 EEPROM · 3 stored cal is for another range */
    uint32_t lost_frames;   /* sensor frames lost since boot — should stay flat */
    uint16_t ring_drop;     /* acquisition ring overruns since boot — should stay flat */
    uint32_t uptime_s;      /* seconds since the module booted */
    bool     maint;         /* maintenance mode active */
    uint8_t  group_status;  /* per-channel energy store: 0 ok · 1 new · 2 fault · 3 restarted at 0 */
    uint16_t legal_noen;    /* metering-relevant operations executed outside maintenance mode */
    uint8_t  reset_cause;   /* image 0x76+: cause of THIS boot, RBAMP_STD_RST_* bits; 0 below */
    uint16_t boot_count;    /* image 0x76+: persisted boot counter (low 16 bits); 0 below */
} rbamp_std_health_t;

rbamp_std_read_health(dev, &h) legge lo stato di salute in tempo reale. Consideri valide le letture quando status ha RBAMP_STD_ST_SENSOR_OK e frame_count cresce tra due interrogazioni. I campi dopo crc_errors esistono sui moduli con mappa 0x35+ e leggono zero / falso su quelli più vecchi.

Allarme su: nvm_fault oppure lta_status >= 2 (accumulatore di energia); cal_src == 3 (la calibrazione memorizzata è per un altro intervallo, in uso i valori predefiniti, anche cal_ok a zero); lost_frames / ring_drop in crescita; time_valid falso (imposti l'orologio); uptime_s in calo (il modulo si è riavviato). reset_cause porta i bit RBAMP_STD_RST_* (pin, alimentazione, software = reset / attivazione / cambio indirizzo, watchdog, basso consumo, byte di opzione); il bit del pin accompagna la maggior parte dei reset interni, quindi giudichi dagli altri bit.

Configurazione

C
typedef struct {
    uint8_t  sensor_class;  /* rbamp_sensor_class_t value; 0 = unset. Persisted. */
    uint8_t  ct_model;      /* CT model reference for channel 0 (metadata, sets no gain). Persisted. */
    uint8_t  tier;          /* 0 or 1. Persisted. */
    uint8_t  i2c_addr;      /* persisted 7-bit address (applies on reset) */
    uint16_t rate_ms;       /* report-rate hint, ms (RAM only) */
    bool     harmonics;     /* base-harmonics extraction enabled (RAM only) */
    uint16_t start_ua;      /* starting current for energy, µA (0 = off); 0 when start_ua_supported is false */
    bool     start_ua_supported;  /* the module has the starting-current setting */
} rbamp_std_config_t;
Funzione Descrizione
rbamp_std_read_config(dev, &cfg) Il blocco di configurazione (una sola raffica, più il registro della corrente di avvio dove il modulo la prevede).
rbamp_std_set_harmonics(dev, enable) Attiva o disattiva l'estrazione delle armoniche di base (THD, PF di spostamento, Q1). Disattivata di default sul livello regolare (fa risparmiare la CPU del modulo); i campi delle armoniche leggono 0 mentre è disattivata. Solo RAM: torna disattivata a un reset del modulo. Riletta e confermata. ESP_ERR_NOT_SUPPORTED senza la capacità THD.
rbamp_std_cal_thd_floor(dev) Calibra il fondo THD della catena dei sensori: acquisisce il THD grezzo attuale levigato come fondo, lo rende persistente e lo applica subito. Precondizione: rete pulita e NESSUN carico sulla pinza CT — il valore catturato viene sottratto a ogni successiva lettura di THD. Si blocca per l'assestamento della memorizzazione; il verdetto arriva dal registro errori del modulo (mappa 0x34+). ESP_ERR_NOT_SUPPORTED senza la capacità THD.
rbamp_std_get_start_current(dev, &ua) La corrente di avvio per l'energia, in µA (0 = disattivata). Sotto questa corrente di canale il modulo non conta energia per quel canale (importazione o esportazione, totale generale e per canale); le letture in sé non sono influenzate. ESP_ERR_NOT_SUPPORTED senza traffico sul bus su un modulo privo dell'impostazione (versione di immagine precedente a 0x0001007B).
rbamp_std_set_start_current(dev, ua) Imposti: 0 = disattivo, altrimenti un valore dall'insieme di passi accettati dal modulo. Si applica subito; rbamp_save_user_config() lo persiste. Riletto e confermato. ESP_ERR_INVALID_ARG per un valore fuori dall'insieme accettato — non viene scritto nulla; ESP_ERR_NOT_SUPPORTED come sopra; ESP_ERR_INVALID_STATE se il modulo non ha accettato il valore.

Le chiamate di configurazione scalari (rbamp_set_sensor_class, rbamp_set_ct_model_ch, rbamp_configure_channels, rbamp_save_user_config, rbamp_save_gains, rbamp_prepare_address_change / rbamp_commit_address_change, rbamp_reset) funzionano su entrambe le linee; ciascuna ha una nota "linea STD" nella sua sezione. Due differenze da sapere: rbamp_factory_reset() restituisce ESP_ERR_NOT_SUPPORTED (su questa linea non esiste tale comando), e rbamp_save_gains() persiste il blocco di calibrazione.

rbamp_commit_address_change() sulla linea STD è sincrono: il salvataggio della configurazione attende il modulo e legge il verdetto (un indirizzo fuori intervallo → ESP_ERR_INVALID_ARG; il limite di frequenza di scrittura flash del modulo → ESP_ERR_NOT_FINISHED — prepari di nuovo e riprovi dopo circa 5 s; in entrambi i casi nulla cambia), poi riavvia il modulo e commuta l'handle solo dopo che un modulo risponde al nuovo indirizzo (entro circa 3 s). Se lì non risponde nessuno, ESP_ERR_NOT_FOUND e l'handle mantiene il vecchio indirizzo. rbamp_read_active_address() legge l'indirizzo persistito.

Contatori di energia vita

Per un modulo che conserva sul dispositivo i contatori di energia persistenti (RBAMP_STD_CAP_ONDEVICE_ENERGY).

C
typedef struct {
    int64_t  act_import_wh, act_export_wh, act_net_wh;   /* Wh; net = import − export */
    int64_t  rea_import_varh, rea_export_varh;           /* varh */
    uint32_t generation;       /* changes when the counters were reset or adopted */
    uint32_t uptime_s;         /* module uptime */
    int64_t  act_import_mwh, act_export_mwh, act_net_mwh;/* mWh (map 0x36+) */
    uint8_t  channels;         /* valid entries in the per-channel arrays (map 0x36+) */
    uint8_t  group_status;     /* per-channel store: 0 ok · 1 new · 2 fault · 3 restarted at 0 */
    int64_t  ch_import_mwh[RBAMP_MAX_CHANNELS], ch_export_mwh[RBAMP_MAX_CHANNELS];
    bool     fine, fine_reactive;
    int64_t  act_import_uwh, act_export_uwh, act_net_uwh;       /* µWh */
    int64_t  rea_import_uvarh, rea_export_uvarh;                /* µvarh */
    int64_t  ch_import_uwh[RBAMP_MAX_CHANNELS], ch_export_uwh[RBAMP_MAX_CHANNELS];
} rbamp_std_energy_t;

I contatori sono in unità intere, monotoni e persistenti alla perdita di alimentazione. Importazione ed esportazione sono grandezze separate. L'energia di un periodo è la differenza di due letture.

  • generation cambia quando i contatori sono stati azzerati o adottati sul modulo — non calcoli mai una differenza a cavallo.

  • uptime_s in calo significa che il modulo si è riavviato. I contatori sono persistenti, quindi la differenza è ancora valida, ma l'orologio del modulo e le impostazioni RAM sono andate perse.

  • Dopo un'interruzione di corrente un contatore può riprendere leggermente sotto la sua ultima lettura (una frazione di secondo di energia); rbamp_std_energy_delta() porta a 0 una differenza del genere e mantiene l'intervallo.

  • I campi *_uwh / *_uvarh sono sempre compilati, quindi li può usare su ogni modulo: un modulo che pubblica contatori a risoluzione µ (versione immagine modulo 0x0001007A e successive; reattivi da 0x0001007B) li fornisce dallo stesso snapshot e fine / fine_reactive sono veri; sui moduli più vecchi sono i contatori grossolani scalati e fine è falso.

  • channels > 0 (mappa 0x36+): il canale c è il canale di corrente c; su un modulo trifase, la fase c.

Persistenza della struttura.

rbamp_std_energy_t acquisisce campi nelle diverse versioni del componente. Se lo salva (NVS, file), memorizzi i singoli campi che le servono in un proprio formato fisso — non la struct come blob grezzo.

Funzione Descrizione
rbamp_std_read_energy(dev, &e) Legge i contatori. Ogni blocco decodificato è una transazione (il modulo lo serve da uno snapshot coerente). ESP_ERR_NOT_SUPPORTED a meno che il modulo non dichiari la capacità di energia on-device; ESP_ERR_INVALID_RESPONSE se il blocco risulta non programmato.
rbamp_std_energy_delta(&prev, &now, &delta, &restarted) Energia tra due letture con le regole di continuità applicate. delta = now − prev per contatore (grandezze di importazione / esportazione, netto, reattiva; generation e uptime_s copiati da now); restarted è vero se uptime_s è sceso. Ciascuna delle uscite può essere NULL. Un contatore sceso viene limitato a una differenza di 0, anche per canale e a ogni risoluzione; ogni campo netto è la differenza di importazione meno quella di esportazione. Le differenze per canale vengono prodotte quando entrambe le letture hanno lo stesso numero di canali, altrimenti delta->channels è 0. ESP_ERR_INVALID_STATE se la generazione è diversa — non contabilizzi quell'intervallo; ricominci da now.

Banchi di istantanee

Il modulo mantiene 8 banchi indipendenti (solo sui moduli con la capacità multi-snapshot, period_source == RBAMP_STD_PERIOD_LATCH). Un banco accumula mentre il suo bit è impostato nella maschera di armatura; rbamp_std_latch() crea lo snapshot e lo azzera al successivo confine della finestra di misura del modulo. Un periodo è quindi l'intervallo tra due snapshot dello stesso banco, misurato con l'orologio del master (il modulo non ne ha). Il banco 0 è anche quello usato da rbamp_read_period_snapshot() e rbamp_energy_wh(). Le tre chiamate di banco restituiscono ESP_ERR_NOT_SUPPORTED senza traffico sul bus su qualsiasi altro modulo — lì usi rbamp_std_read_energy() / rbamp_std_energy_delta().

Uso tipico: armi i banchi una volta, poi per ogni banco secondo la sua pianificazione rbamp_std_latch(bank) → attenda ≥ 300 ms (limite superiore sicuro di una finestra di misura su ogni immagine) → rbamp_std_read_latch() → rbamp_std_latch_wh() con il dt misurato dal master dall'ultimo snapshot.

C
typedef struct {
    float    p_avg, q_avg, s_avg;       /* average P / Q / S over the period */
    float    max_p, max_i, max_u, min_u;/* peaks in the period */
    int64_t  e_import_mws, e_export_mws;/* energy, mW·samples */
    uint32_t nsamp;                     /* sensor samples in the period */
    uint32_t win_count;                 /* measurement windows in the period (0 = not armed / nothing elapsed) */
    uint8_t  channels;                  /* valid entries in the per-channel arrays */
    uint8_t  bank;
    bool     valid;                     /* the bank has EVER been snapshotted (not a freshness signal) */
    float    p_avg_ch[RBAMP_MAX_CHANNELS];
    int64_t  e_import_ch_mws[RBAMP_MAX_CHANNELS], e_export_ch_mws[RBAMP_MAX_CHANNELS];
} rbamp_std_latch_t;
Funzione Descrizione
rbamp_std_arm_banks(dev, mask) Imposti la maschera di accumulo: bit b = il banco b accumula (i banchi appena armati partono puliti; quelli disarmati si congelano e mantengono l'ultimo snapshot). Il bit 0 deve restare impostato se usa rbamp_read_period_snapshot(). La maschera è RAM sul modulo: qualsiasi reset del modulo la azzera, e lo snapshot di un banco non armato restituisce uno snapshot vuoto. La libreria riarma da sola il banco 0 (in rbamp_begin(), dopo i propri reset e quando uno snapshot di periodo torna vuoto). Per i propri banchi rbamp_std_read_latch() rileva l'armatura persa, riarma e fa uno snapshot di innesco.
rbamp_std_latch(dev, bank) Richiede uno snapshot + reset del bank al prossimo confine di finestra. Non attende — lo legga ≥ 300 ms dopo.
rbamp_std_read_latch(dev, bank, &l) Legge l'ultimo snapshot di bank (una raffica: totali + energia per canale per ogni canale popolato). ESP_ERR_INVALID_RESPONSE se il modulo non ha mai fatto il latch di questo banco (gli altri campi vengono azzerati). ESP_ERR_INVALID_STATE se lo snapshot è vuoto perché il banco è stato disarmato da un reset del modulo — la libreria lo ha riarmato e fatto il latch di innesco: scarti questo periodo e riavvii l'ancoraggio dt. Legga un banco almeno una finestra di misura dopo averne fatto il latch; win_count == 0 significa che non era armato o non è trascorsa alcuna finestra.
rbamp_std_latch_wh(&l, dt_ms, ch, &wh_import, &wh_export) Converte i bucket di energia di uno snapshot in Wh sul periodo dt_ms misurato dal master (l'orologio tra il precedente snapshot del banco e questo). ch è un indice di canale oppure RBAMP_STD_TOTAL (0xFF) per i totali del banco. Wh = E[mW·campioni] / 1000 / 3600 × (dt / nsamp): il numero di campioni e il dt del master normalizzano il risultato. Importazione ≥ 0, esportazione ≤ 0; ciascun output può essere NULL. ESP_ERR_INVALID_STATE se nsamp è 0.

Clock, comandi e servizio

Il modulo tiene il suo clock in RAM: non è valido dopo ogni reset del modulo. Senza un clock valido il modulo non registra storico.

Funzione Descrizione
rbamp_std_set_time(dev, unix_epoch) Imposta l'orologio del modulo (secondi unix) e attende il completamento. Chiamarla dopo rbamp_begin() e ogni volta che rbamp_std_health_t.time_valid è falso (o un periodo riporta module_restarted). Il primo impostamento dopo un reset chiude l'intervallo di storico in corso senza trascinarlo. ESP_ERR_INVALID_ARG se il modulo rifiuta l'epoca (prima del 2020); ESP_ERR_INVALID_STATE se l'orologio non è diventato valido; ESP_ERR_NOT_SUPPORTED sotto la mappa 0x35.
rbamp_std_read_time(dev, &epoch, &valid) Legge l'orologio del modulo e se è valido.
rbamp_std_command(dev, opcode, settle_ms, timeout_ms) Scriva un codice operativo di comando e attenda il suo completamento: attende prima che il modulo sia libero (un comando scritto mentre è occupato viene scartato), dorme per settle_ms, attende che BUSY si azzeri, poi legge il verdetto. timeout_ms 0 = 1 s. Verdetti: ESP_ERR_INVALID_ARG (parametro errato), ESP_ERR_NOT_SUPPORTED (comando sconosciuto), ESP_ERR_INVALID_CRC (controllo del valore), ESP_ERR_NOT_FINISHED (scrittura flash limitata in frequenza — riprovi dopo circa 5 s), ESP_ERR_NOT_ALLOWED (chiave o gate di manutenzione), ESP_ERR_TIMEOUT (ancora occupato).
rbamp_std_wait_idle(dev, timeout_ms) Attende che il modulo finisca il comando in esecuzione. Ogni comando emesso tramite questa libreria attende già; lo usi solo attorno ai comandi che scrive lei stesso nel registro dei comandi — un comando scritto mentre è BUSY viene scartato. Restituisce subito sui moduli privi del registro di stato dei comandi.
rbamp_std_hist_flush(dev) Scriva ora gli accumulatori di energia in flash (lo implicano anche il reset / il commit del firmware).

Un comando non viene mai ritentato su un errore di trasporto (un ritentativo potrebbe consegnare l'opcode due volte); le letture e scritture dei registri dati mantengono il ritentativo.

Cronologia e registro eventi

Il modulo conserva l'ultimo record da 15 minuti in RAM (perso al reset del modulo — un indicatore in tempo reale, non uno storico) e un buffer orario in flash che sopravvive ai reset ed è il buffer da cui recuperare i dati mancanti; entrambi vengono scritti solo quando l'orologio del modulo è valido. Un registro eventi mai cancellato annota le variazioni rilevanti per la misura. Ogni record ORARIO riporta i contatori di vita assoluti alla fine del periodo: l'energia complessiva del periodo è la differenza tra due record consecutivi (reset e lacune restano visibili). Recupero dopo un'interruzione del master: scorra con back a partire da 0 (il più recente) finché non trova i timestamp che già possiede.

C
typedef enum {
    RBAMP_STD_HIST_MIN15  = 0,  /* 15-minute records (RAM, lost at module reset) */
    RBAMP_STD_HIST_HOUR   = 1,  /* hourly records (flash ring) */
    RBAMP_STD_HIST_EVENTS = 2,  /* event log — read with rbamp_std_event_read */
} rbamp_std_hist_period_t;

typedef struct {
    uint16_t count;        /* records available (0 while the ring is being cleared) */
    uint16_t capacity;     /* ring depth */
    uint16_t record_size;  /* bytes per record */
    uint32_t oldest_ts, newest_ts;  /* unix */
} rbamp_std_hist_info_t;

typedef struct {
    uint32_t ts;           /* period start, unix */
    uint16_t flags;        /* RBAMP_STD_HF_* bits */
    uint16_t n;            /* samples (MIN15) or 15-minute children (HOUR: 4 = complete) */
    bool     from_ram;     /* record came from the RAM ring (not yet persisted) */
    float    v_rms, i_total, p_avg, q_avg, s_avg, pf;
    float    p_min, p_max, i_min, i_max;
    uint64_t e_import_wh, e_export_wh;   /* life-time counters ABSOLUTE at period end */
    uint8_t  phases;                     /* valid entries in the per-phase arrays */
    double   ph_import_wh[3], ph_export_wh[3];  /* per-phase energy OF THIS PERIOD, Wh */
} rbamp_std_hist_record_t;

typedef struct {
    uint32_t ts;           /* unix time (0 = clock was not set) */
    uint32_t uptime_s;     /* module uptime at the event */
    uint8_t  type;         /* RBAMP_STD_EV_* */
    uint8_t  flags;        /* RBAMP_STD_EVF_* (maintenance mode was active) */
    uint16_t boot;         /* boot counter (low 16 bits) */
    uint32_t a_before, a_after;        /* type-specific values before / after the change */
    uint64_t e_before_wh, e_after_wh;  /* grand import counter before / after, Wh */
} rbamp_std_event_t;
Funzione Descrizione
rbamp_std_hist_info(dev, period, &info) Stato ad anello di un periodo di storico (seleziona anche quel periodo sul modulo).
rbamp_std_hist_read(dev, period, back, &rec) Recupera e decodifica il record back (0 = il più recente) di MIN15 o HOUR. ESP_ERR_NOT_FOUND se il record non esiste. Ricavi l'energia di un periodo da due record consecutivi solo quando i loro timestamp differiscono esattamente di un periodo e nessuno dei due porta il flag RBAMP_STD_HF_LTA_JUMP.
rbamp_std_hist_read_raw(dev, period, back, rec, &flags) Lo stesso record non decodificato: rec (un buffer RBAMP_STD_REG_HIST_REC_SIZE; la lunghezza significativa è record_size) riceve i byte del record del modulo, flags i flag del record del modulo.
rbamp_std_event_read(dev, back, &ev) Recupera e decodifica la voce del registro eventi back (0 = la più recente). ESP_ERR_NOT_FOUND se non ce n'è. I tipi di evento sono le costanti generate RBAMP_STD_EV_* (reset / adozione del contatore di vita, salvataggio della calibrazione, commit del firmware, cancellazione dello storico, ...).

Autenticità

Un modulo messo in servizio possiede un certificato del dispositivo firmato dalla chiave del produttore e risponde a una sfida con una firma digitale della chiave del dispositivo indicata in quel certificato. La libreria li recupera entrambi; la verifica spetta all'applicazione (con una libreria di firma a sua scelta).

C
typedef struct {
    uint8_t  raw[RBAMP_STD_REG_SEC_CERT_SIZE];  /* certificate bytes as read */
    uint8_t  state;          /* the module's own check: 0 none · 1 ok · 2 bad · 3 not checked yet (shortly after boot) */
    uint8_t  version, variant, hw_rev;
    uint8_t  uid[12];        /* chip UID the certificate was issued for (compare with rbamp_read_uid) */
    uint32_t batch, issued;  /* production batch; issue time, unix */
    uint8_t  device_pubkey[32];
    uint32_t mfr_key_id;
} rbamp_std_certificate_t;

typedef struct {
    uint8_t  signature[64];  /* signature over the attested message */
    uint8_t  data[24];       /* attested data exactly as signed */
    uint32_t fw_version, generation;   /* from data */
    int64_t  e_import_wh, e_export_wh; /* from data: life-time import / export, Wh */
} rbamp_std_attestation_t;
Funzione Descrizione
rbamp_std_read_certificate(dev, &cert) Legge il certificato del dispositivo. ESP_ERR_NOT_FOUND se il modulo non ne ha uno (non messo in servizio; state viene comunque compilato); ESP_ERR_NOT_SUPPORTED sotto la mappa 0x35.
rbamp_std_attest(dev, challenge, &att) Sfidi il modulo con 32 byte casuali di sua scelta (conservi la sua copia — il modulo sovrascrive l'area di sfida con la firma) e recuperi la risposta firmata (circa 60 ms). Il dato attestato lega la versione del firmware e i contatori di vita alla chiave del dispositivo. ESP_ERR_NOT_FOUND se il modulo non ha una chiave del dispositivo; ESP_ERR_INVALID_STATE se il modulo non ha riportato l'attestazione come completata.

Aggiornamento firmware (OTA)

Un aggiornamento in due fasi via I²C. Ogni funzione qui restituisce ESP_ERR_NOT_SUPPORTED a meno che il modulo non segnali la capacità OTA (mappa 0x33 o successiva). Ogni comando si completa in modo sincrono all'interno della libreria (attende lo stato di comando del modulo, non un ritardo fisso).

Sequenza: rbamp_std_ota_begin → rbamp_std_ota_write_page × N (pagine da 256 byte; le pagine vuote 0xFF possono essere saltate) → rbamp_std_ota_commit (verifica e arma lo scambio, senza riavvio) → rbamp_std_ota_activate (riavvia nella nuova immagine quando è pronto). Il modulo è fuori bus per alcuni secondi, poi esegue una prova di circa 10 s prima che l'immagine sia confermata. Dopo ogni pagina la sessione deve restare aperta, altrimenti la chiamata fallisce con ESP_ERR_INVALID_STATE (ripartire da begin). Un'immagine difettosa viene ripristinata dal modulo stesso; la calibrazione sopravvive.

Vengono accettate solo immagini preparate dal fornitore. Le immagini di rilascio sono prodotte dagli strumenti del fornitore del modulo (firmate e, dove richiesto, cifrate); il modulo rifiuta un'intestazione costruita dall'host al commit. rbamp_std_ota_write_image() (immagine costruita sull'host, non firmata) restituisce quindi ESP_ERR_NOT_SUPPORTED prima di toccare il modulo ed è mantenuta solo per compatibilità ABI.

Funzione Descrizione
rbamp_std_ota_status(dev, &st) Lo stato OTA del modulo (RBAMP_STD_OTA_IDLE / READY / OK / ERR / DOWNGRADE).
rbamp_std_ota_begin(dev, timeout_ms) Cancelli il banco inattivo e attenda che il modulo segnali PRONTO. timeout_ms 0 = predefinito (5 s). ESP_ERR_TIMEOUT se PRONTO non è stato raggiunto.
rbamp_std_ota_write_page(dev, page_idx, page) Scrive una pagina da 256 byte all'indice page_idx (offset / 256 nel banco). ESP_ERR_INVALID_STATE se il modulo segnala un errore di scrittura.
rbamp_std_ota_commit(dev, timeout_ms) Verifica l'immagine scritta e arma lo scambio dei banchi. timeout_ms 0 = predefinito (3 s). ESP_OK armato · ESP_ERR_INVALID_CRC immagine difettosa (CRC / intestazione) · ESP_ERR_INVALID_MAC autenticazione fallita · ESP_ERR_INVALID_VERSION immagine più vecchia di quella in esecuzione · ESP_ERR_TIMEOUT.
rbamp_std_ota_diag(dev, &reason) Motivo per cui il modulo ha rifiutato l'ultima pagina o il commit: il byte di motivo della sua diagnostica OTA (0 = nessuno). rbamp_std_ota_commit() associa già il motivo al codice di errore sopra e ne registra il nome; richiami questa funzione quando ha bisogno del codice stesso.
rbamp_std_ota_activate(dev) Riavvio nell'immagine armata, attesa del ritorno del modulo (circa 4 s), nuovo rilevamento, poi attesa durante la finestra di prova e conferma: il banco in esecuzione è cambiato, l'immagine in esecuzione è la versione predisposta, lo scambio non è più in sospeso. Si blocca per circa 10 s in totale — non resetti né tolga l'alimentazione al modulo in quella finestra (il bootloader riporta indietro un'immagine non confermata). L'handle resta valido e rbamp_std_info() riflette il nuovo firmware. ESP_ERR_INVALID_STATE se non era stato armato nulla, se il modulo è tornato sull'immagine precedente (ripristino), o se lo scambio è ancora in sospeso dopo la prova.
rbamp_std_ota_staged_version(dev, &v) Versione dell'immagine armata (impegnata, non ancora attivata); 0 quando non è armato nulla (mappa 0x35+).
rbamp_std_ota_abort(dev) Chiude una sessione di aggiornamento e disarma un'immagine armata; il modulo continua a eseguire ciò che esegue (mappa 0x35+).
rbamp_std_ota_board_ok(dev, image_board_word) Verifica preliminare prima di trasmettere un'immagine preparata: la parola di scheda dell'immagine (fornita accanto al file dell'immagine dagli strumenti del fornitore) deve coincidere con l'identificativo di scheda del modulo. ESP_OK se coincide; ESP_ERR_INVALID_ARG se non coincide (registrato); ESP_ERR_NOT_SUPPORTED sotto la mappa 0x36.
rbamp_std_ota_write_prepared(dev, image, size, cb, ctx) Trasmetta un banco preparato così com'è: begin, pagine in ordine crescente (la pagina 0 viene sempre inviata, le altre pagine tutte 0xFF vengono saltate), commit. La libreria non modifica nulla. Non attiva. size deve coincidere con la dimensione del banco riportata dal modulo (rbamp_std_info_t.ota_bank_size) — altrimenti ESP_ERR_INVALID_SIZE e nulla viene scritto. cb(done, total, ctx) è un callback di avanzamento facoltativo (rbamp_std_ota_progress_cb_t).
rbamp_std_ota_write_prepared_pair(dev, bank_a, size_a, bank_b, size_b, cb, ctx) Come sopra, con entrambe le immagini dei banchi: la libreria chiede al modulo quale banco è in esecuzione e trasmette l'altro. ESP_ERR_NOT_SUPPORTED sui moduli che non segnalano il banco in esecuzione (mappa inferiore a 0x35) — in tal caso usi rbamp_std_ota_write_prepared() e scelga lei in base ad active_bank.
rbamp_std_crc32(data, len) CRC-32 (compatibile zlib) — il checksum che il modulo verifica al commit.
rbamp_std_ota_make_header(out, version, len, crc32) Costruisce l'intestazione dell'immagine in little-endian. Disponibile solo quando l'intestazione dei registri generata definisce le costanti dell'intestazione; mantenuta per l'ABI.

Diagnostica

rbamp_err_to_str

C
const char *rbamp_err_to_str(esp_err_t err);

Restituisce un puntatore a una stringa statica con una descrizione leggibile del codice di errore. Non restituisce mai NULL. Usa il comune esp_err_to_name() per i codici di sistema ed estende le descrizioni per la semantica specifica di rbamp (per esempio, cosa significa ESP_ERR_INVALID_STATE nel contesto di set_ct_model_ch senza set_sensor_class).

Uso tipico:

C
esp_err_t err = rbamp_read_period_snapshot(dev, &snap, 50, false);
if (err != ESP_OK) {
    ESP_LOGE(TAG, "snapshot failed: %s", rbamp_err_to_str(err));
}

rbamp_retry_exhaustion_count / rbamp_sanity_reject_count / rbamp_reset_counters

C
uint32_t rbamp_retry_exhaustion_count(rbamp_handle_t dev);
uint32_t rbamp_sanity_reject_count   (rbamp_handle_t dev);
void     rbamp_reset_counters        (rbamp_handle_t dev);

Getter pubblici per due contatori diagnostici (restituiscono entrambi 0 su un handle NULL):

  • rbamp_retry_exhaustion_count(dev) — un contatore monotono degli eventi "budget di retry esaurito". Ogni incremento = una transazione da un byte che, dopo CONFIG_RBAMP_NACK_RETRY_ATTEMPTS tentativi, non ha mai ricevuto un ACK dal dispositivo.

  • rbamp_sanity_reject_count(dev) — un contatore monotono dei rifiuti del filtro di plausibilità sulle letture float (NaN, Inf, o un valore assoluto oltre il limite della grandezza — RBAMP_SANITY_LIMIT_V / _I / _P / _PF). Ogni incremento = un float arrivato dal bus, giudicato non simile a un valore fisico e scartato; la lettura restituisce ESP_ERR_INVALID_RESPONSE.

rbamp_reset_counters(dev) azzera entrambi i contatori su questo handle (nessun effetto per NULL). È pensata per scenari di test che richiedono una base pulita. Per il monitoraggio in produzione preferisca il pattern canonico "tasso su un intervallo" — snapshot + differenza, robusto rispetto alle finestre di reset perse:

C
uint32_t prev = rbamp_retry_exhaustion_count(dev);
/* ...60 s of normal operation... */
uint32_t delta = rbamp_retry_exhaustion_count(dev) - prev;
if (delta > THRESHOLD) { /* alert */ }

Questi nomi corrispondono alla libreria Arduino multipiattaforma (dev.retryExhaustionCount() / dev.sanityRejectCount() — stessa semantica, snake_case). Per carichi pratici e soglie di allarme, vedi 10 · Risoluzione dei problemi, sezione «Monitoraggio dei contatori».

Logging tramite esp_log

Il componente registra i log con il tag "rbamp". Il livello di log è compilato tramite Kconfig — esp_log_level_set("rbamp", ...) a runtime funziona ma è limitato dall'alto dal livello di compilazione.

C
esp_log_level_set("rbamp", ESP_LOG_DEBUG);   /* for debugging */

Codici di errore

Le funzioni rbamp_* restituiscono valori esp_err_t standard. I codici specifici e la loro semantica nel contesto rbamp:

Codice Quando Dove guardare
ESP_OK (0) Successo —
ESP_FAIL (-1) La transazione I²C è fallita dopo i retry cablaggio, alimentazione, velocità del bus — sezione "Il modulo non risponde su I²C" in 10 · Risoluzione dei problemi
ESP_ERR_INVALID_ARG (0x102) Argomento non valido: dev == NULL, channel o phase fuori intervallo, un cls non riconosciuto, un valore che il modulo rifiuta (modello di CT sconosciuto, corrente di avvio fuori dall'insieme ammesso, un orologio anteriore al 2020) verifichi gli argomenti della chiamata
ESP_ERR_TIMEOUT (0x107) rbamp_wait_ready / rbamp_wait_data_ready scaduto; la finestra di rbamp_commit_address_change (5 s) scaduta; un comando STD o lo stato OTA non si è completato verifichi la reattività tramite rbamp_probe()
ESP_ERR_INVALID_STATE (0x103) Una precondizione o una sequenza di chiamate è errata: set_ct_model* prima di set_sensor_class; il modulo è di classe 2 / 3 (calibrato con il proprio sensore — usi rbamp_set_ct_model_ch_force() per l'assistenza); il modulo ha rifiutato la coppia (classe, modello); commit dell'indirizzo non armato; banco di snapshot STD riarmato dopo un reset del modulo (scartare questo periodo); contatore di generazione STD cambiato (rbamp_std_energy_delta); sessione OTA non aperta sezione «rbamp_set_* restituisce ESP_ERR_INVALID_STATE» in 10 · Risoluzione dei problemi
ESP_ERR_NOT_SUPPORTED (0x106) La funzione o la funzionalità non esiste su questa linea / firmware / modulo: qualsiasi chiamata rbamp_std_* su un handle BASE, potenza reattiva / apparente su BASE, rbamp_read_digest su STD o senza la capacità digest, chiamate di periodo su un modulo STD senza banchi di snapshot né contatori, rbamp_factory_reset su STD, una versione della mappa dei registri troppo vecchia, OTA senza la capacità verifichi rbamp_line(dev), rbamp_std_info() e rbamp_variant(dev)
ESP_ERR_NOT_FOUND Nulla presente: rbamp_std_probe — nessuno risponde all'indirizzo; nessun record di storico / evento; nessun certificato o chiave del dispositivo; commit dell'indirizzo — nessuna risposta al nuovo indirizzo (l'handle mantiene il vecchio) verifichi cablaggio / indirizzo; risalga back solo fino a rbamp_std_hist_info().count
ESP_ERR_INVALID_RESPONSE (0x108) Snapshot di periodo obsoleto (flag di pronto = 0) oppure periodo saltato (contatori STD riancorati, banco riarmato); REG_VERSION = 0/0xFF su rbamp_begin; un float ha superato il filtro di plausibilità; frequenza di rete STD 0 (nessuna rete); rbamp_std_probe — risponde qualcosa che non è un modulo STD sezione «Gli snapshot di periodo sono sempre obsoleti» / «Impossibile uscire da rbamp_begin» in 10 · Risoluzione dei problemi
ESP_ERR_NO_MEM (0x101) Impossibile allocare memoria per l'handle; più di 4 linee DRDY / 8 handle per linea verifichi il budget dell'heap
ESP_ERR_NOT_FINISHED STD: la scrittura flash del modulo è limitata nella frequenza riprovi dopo circa 5 s
ESP_ERR_INVALID_CRC, ESP_ERR_INVALID_MAC, ESP_ERR_INVALID_VERSION, ESP_ERR_INVALID_SIZE, ESP_ERR_NOT_ALLOWED Verdetti di comando / OTA STD: un valore o un controllo dell'immagine è fallito, l'autenticazione è fallita, l'immagine è più vecchia di quella in esecuzione, l'immagine non entra nel banco, il modulo ha rifiutato l'operazione (vedi rbamp_std_command, rbamp_std_ota_commit) rbamp_std_ota_diag() per il motivo

Tutti i codici restituiti possono essere stampati in forma leggibile tramite rbamp_err_to_str().

Configurazione in fase di compilazione (Kconfig)

I seguenti simboli CONFIG_RBAMP_* sono disponibili in idf.py menuconfig → Configurazione componenti (Component config) → rbAmp client:

Simbolo Tipo Intervallo / scelta Predefinito Scopo
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ int 50000–1000000 Hz 50000 Frequenza SCL. 50 kHz è la prescrizione per il firmware attuale su ESP32.
CONFIG_RBAMP_I2C_TIMEOUT_MS int 10–1000 ms 100 Timeout di i2c_master_transmit/receive. Deve essere abbastanza lungo da assorbire la latenza di pre-lettura del modulo.
CONFIG_RBAMP_I2C_SCL_WAIT_US int 2000–60000 µs 10000 Tolleranza allo stretching del clock SCL: per quanto tempo la periferica I²C lascia il modulo tenere SCL basso prima di rinunciare alla transazione. Il predefinito del driver è 2 ms; un modulo allunga SCL più a lungo mentre cancella un settore di flash durante un aggiornamento firmware, e ogni allungamento del genere finirebbe in una riga di log "I2C hardware timeout" e un retry. 10 ms copre la cancellazione del settore. L'ESP32 originale non può attendere più di circa 13 ms (contatore hardware a 20 bit); il componente limita il valore a quel massimo su quel target.
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS int 1–10 3 Tentativi per lettura a un byte.
CONFIG_RBAMP_NACK_RETRY_GAP_MS int 1–100 ms 5 Intervallo tra i tentativi di retry.
CONFIG_RBAMP_BUS_RESET_ON_RETRY_EXHAUSTION bool n/y n Quando tutti i ritentativi NACK di una transazione falliscono, chiami i2c_master_bus_reset() una volta prima dell'ultimo tentativo. Il driver IDF resetta già la propria macchina a stati dopo ogni transazione fallita, e il reset esplicito non prende il lock del bus: con più task che condividono il bus può interrompere la transazione di un altro task (su ESP32 pilota uno STOP sui pin, che il gestore di interrupt del driver può scambiare per la fine di una lettura). Lo lasci disattivato a meno che il master non sia monotask e il bus risulti bloccato dopo errori del driver.
CONFIG_RBAMP_SCT_RATING_CORRECTION bool n/y y Correzione delle letture SCT-013 sul firmware BASIC fino alla 1.4.19, che mantiene la calibrazione a 30 A dopo che l'utente passa il canale a un altro modello. La libreria scala corrente, potenza, potenza di periodo, energia e digest sul modello selezionato (rbamp_sct_correction() riporta l'esito per canale). Un modulo che si corregge da solo (firmware 1.4.20 e successivi) non è interessato. Lo disattivi per leggere i valori grezzi del modulo. Veda Correzione della portata SCT-013.
CONFIG_RBAMP_DRDY_POLL_MS int 5–50 ms 20 Quando un handle non ha un GPIO DRDY, rbamp_wait_data_ready() interroga il contatore di pubblicazione del modulo (STD) o la sequenza di commit (BASIC) a questo intervallo. Il modulo pubblica ogni 100 ms (immagini più vecchie: 200 ms).
CONFIG_RBAMP_DISABLE_ENERGY bool n/y n Rimuove completamente l'accumulatore Wh dalla compilazione (sia archiviazione sia API).
CONFIG_RBAMP_LOG_LEVEL_* scelta NONE / ERROR / WARN / INFO / DEBUG INFO LOG_LOCAL_LEVEL in fase di compilazione per il tag rbamp. Decide se le stringhe di log vengono effettivamente compilate nel binario; indipendente da CONFIG_LOG_DEFAULT_LEVEL.

Un esempio di sdkconfig.defaults per uno scenario di produzione tipico:

Text
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=3
CONFIG_RBAMP_NACK_RETRY_GAP_MS=5
CONFIG_RBAMP_I2C_TIMEOUT_MS=100
CONFIG_RBAMP_LOG_LEVEL_INFO=y
# leave CONFIG_RBAMP_DISABLE_ENERGY disabled (default n)

Per una prova da banco sotto carico intenso:

Text
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=5
CONFIG_RBAMP_I2C_TIMEOUT_MS=200
CONFIG_RBAMP_LOG_LEVEL_DEBUG=y

Costanti di tempo di assestamento

Il componente usa internamente i seguenti tempi di assestamento quando esegue i comandi (per chi lavora sull'API grezza tramite i2c_master_transmit_receive e vuole rispettare gli stessi tempi):

La libreria espone un piccolo insieme di costanti di tempo di assestamento (ms) per chi usa l'API grezza e invia comandi direttamente al dispositivo, e deve attendere che il dispositivo completi l'elaborazione prima di leggere i registri interessati. Le funzioni wrapper del componente (rbamp_save_gains, rbamp_factory_reset, rbamp_set_ct_model_ch, ecc.) gestiscono internamente il ritardo corretto: queste costanti servono solo se si aggirano i wrapper.

Macro Scopo ms
RBAMP_SETTLE_MS_LATCH_PERIOD Dopo CMD_LATCH_PERIOD 50
RBAMP_SETTLE_MS_RESET Dopo CMD_RESET 100
RBAMP_SETTLE_MS_SAVE_GAINS Dopo CMD_SAVE_GAINS (cancellazione + scrittura della flash) 700
RBAMP_SETTLE_MS_FACTORY_RESET Dopo CMD_FACTORY_RESET 1500
RBAMP_SETTLE_MS_SET_CT_MODEL_CH0 Dopo CMD_SET_CT_MODEL_CH0 5
RBAMP_SETTLE_MS_SET_CT_MODEL_CH1 Dopo CMD_SET_CT_MODEL_CH1 5
RBAMP_SETTLE_MS_SET_CT_MODEL_CH2 Dopo CMD_SET_CT_MODEL_CH2 5

La fonte di riferimento è il blocco @defgroup rbamp_settle_ms in include/rbamp.h. I valori sono i minimi di specifica del protocollo rbAmp; non si può andare più in basso, si può andare più in alto.

Dettagli del protocollo sul filo

Mappa a colori dello spazio dei registri del modulo.
Per il porting su piattaforme dove il componente non viene usato, oppure per il debug con un analizzatore logico:

Letture dei registri — auto-incremento

Una lettura in burst + N byte restituisce N byte consecutivi a partire da addr. Esempio: una singola transazione i2c_master_transmit_receive(slave, {0x86}, 1, buf, 16, ...) legge 16 byte a partire da 0x86 (U_RMS + U_PEAK + I_RMS + I_PEAK su UI1).

Scritture di registro — un byte alla volta (NON incremento automatico)

Le letture auto-incrementano mentre le scritture vanno un byte alla volta.
⚠ Le scritture NON sono auto-incrementali.Una SCRITTURA a raffica + N bytesarrivasolo il primo byte— i byte da 1 a N vengono scartati.

Un registro multi-byte viene scritto byte per byte — una transazione I²C separata a un solo byte per ogni indirizzo:

C
/* WRONG — data loss */
uint8_t label[8] = "MyMeter1";
uint8_t buf[9] = { 0x68, 'M', 'y', 'M', 'e', 't', 'e', 'r', '1' };
i2c_master_transmit(slave, buf, 9, 100);   /* only 'M' lands */

/* CORRECT — byte-at-a-time loop */
for (int i = 0; i < 8; i++) {
    uint8_t tx[2] = { 0x68 + i, label[i] };
    i2c_master_transmit(slave, tx, 2, 100);
}

Riguarda i registri multi-byte scrivibili: LABEL (0x68-0x6F), U_GAIN / I_GAIN (f32, vincolati alla fabbrica), NF (u16), THRESH (u16). Le letture in burst sono ammesse (l'auto-incremento funziona in lettura).

Lettura di registri non mappati

Qualsiasi lettura da un indirizzo non mappato restituisce 0x00. Il firmware non risponde mai con NACK alle letture dei registri. Il rilevamento di un dispositivo mancante deve passare per l'ACK del frame di indirizzo I²C, non per il sondaggio dei registri.

Rilevamento della variante

Il byte SKU autorevole è il registro 0x55 (memorizzato in cache come rbamp_variant()):

valore SKU
0x01 UI1 (1× I + U)
0x02 UI2 (2× I + U)
0x03 UI3 (3× I + U)
0x04 I1 (1× I, senza U)
0x05 I2 (2× I, senza U)
0x06 I3 (3× I, senza U)
0x07 UI5 (5× I + U)
0x08 UI7 (7× I + U)

rbamp_topology() è ausiliaria; restituisce solo il numero di canali (1/2/3/5/7) e non distingue la presenza di U.

Sicurezza

⚠ REG_SENSOR_CLASS (0x25) NON è un discriminante di variante (è configurato dall'utente). L'invariante di variante = HW_VARIANT (0x55) + CAPABILITY (0x57/0x58) — entrambi in sola lettura.

CAPABILITY (0x57/0x58, u16 LE) — mappa di rilevamento delle funzionalità

Una mappa delle capacità del dispositivo (per esempio: presenza del front-end di tensione, snapshot General-Call supportato, blocco digest, flag di evento, cambio di indirizzo in due fasi). Il modo canonico per rilevare le funzionalità (invece di confrontare numeri di versione). Controlli i singoli flag di capacità tramite le funzioni di supporto; l'insieme dei flag cresce con il firmware dei moduli.

has_voltage (senza leggere HW_VARIANT):

C
/* Option 1 — the cached helper (no bus traffic after rbamp_begin). */
bool has_voltage = rbamp_has_voltage(dev);

/* Option 2 — read the full 16-bit CAPABILITY (LE). */
uint16_t cap;
rbamp_read_capability(dev, ∩);
bool has_voltage_2 = (cap & RBAMP_CAP_ZC_PHASE_OFFSET) != 0;  /* voltage front-end flag */

Entrambe le opzioni sono equivalenti.

Coerenza HW_VARIANT ⟷ CAPABILITY: HW_VARIANT 1..3 (UI) → flag del front-end di tensione impostato; HW_VARIANT 4..6 (I) → flag azzerato. Un'incoerenza = un'anomalia hardware.

Atomicità / congelamento della lettura (B1)

Lo snapshot di periodo atomico che chiude un periodo e ne apre il successivo senza interruzioni né sovrapposizioni.

  • Blocco float RMS V03 (0x86+: U_RMS, U_PEAK, I_RMS, I_PEAK, P, PF, freq) — lettura congelata presente, la lettura a raffica è atomica.
  • Blocco digest (0x70-0x85) — lettura congelata presente.
  • GC_TICK (0x59) / specchio dell'indirizzo (0x30) / specchi del modello CT (0x51-0x53) — lettura congelata assente; per una lettura affidabile usi il pattern read-twice-agree (legga due volte, consideri valido il valore solo se coincidono).

Semantica della pinza NF

I_RMS = 0x00000000 significa "segnale sotto il rumore di fondo" (il firmware calcola rms_corr² = max(0, raw² − nf²)), NON "nessun dato" / "errore". È una misura valida per scenari a vuoto.

Registri solo di tensione su varianti solo corrente

U_RMS, U_PEAK su I1/I2/I3 leggono 0. Sono validi solo quando il flag di front-end di tensione in CAPABILITY è impostato. REG_AC_FREQ è di origine ZC e disponibile su tutte le varianti (incluse le I*).

Snapshot broadcast General-Call (sincronizzazione multimodulo)

Abilitazione opt-in per modulo tramite bit0 del registro REG_FLEET_CONFIG (0x27) — GC_ENABLE. Predefinito OFF. Si abilita tramite CMD_SAVE_USER_CONFIG + CMD_RESET (soft o hard). Dopo un reset il modulo ascolta il frame broadcast all'indirizzo I²C general-call 0x00:

Text
addr=0x00 | A5 27   
  • A5 — magic.
  • 27 — il codice operativo CMD_LATCH_PERIOD.
  • — 0x00 = all-call, altrimenti deve corrispondere a REG_GROUP_ID (0x28).
  • — un contatore di periodo a 16 bit (sincronizzazione del master).

Il frame attiva solo lo snapshot di periodo; non porta mai opcode distruttivi.

Rilevamento della modalità di guasto (a due livelli, confermato su HW C.10):

  1. NACK dell'indirizzo GC (immediato, a livello di bus): se GC è disabilitato su tutta la flotta — i2c_master_transmit verso 0x00 restituisce ESP_FAIL / ESP_ERR_INVALID_STATE. È un errore fatale, non un'omissione silenziosa. La libreria tratta il NACK come "GC non abilitato" (richiede le precondizioni di abilitazione + reset).
  2. Testimone per modulo (dopo l'assestamento): se non si è verificato alcun NACK — il master legge REG_V03_PERIOD_VALID (0x07) su ogni slave atteso: 1 = snapshot riuscito, 0 = GC disabilitato su questo modulo specifico, oppure il periodo è vuoto.

Appendice — Sotto il cofano

Spostato dal capitolo Panoramica: confronto a livello di registri, architettura e diagrammi di interazione.

Senza il componente (accesso diretto tramite i2c_master_transmit_receive)

C
// Read U_RMS — a single 4-byte burst-read (the firmware supports
// address auto-increment on read).
i2c_master_dev_handle_t slave;
i2c_master_bus_add_device(bus, &(i2c_device_config_t){
    .device_address = 0x50, .scl_speed_hz = 50000,
}, &slave);

uint8_t reg = 0x86, buf[4] = { 0 };
if (i2c_master_transmit_receive(slave, ®, 1, buf, 4,
                                /*xfer_timeout_ms=*/100) != ESP_OK) {
    return;   // handle the error
}
float u_rms;
memcpy(&u_rms, buf, sizeof(float));

Con il componente

C
float u_rms;
ESP_ERROR_CHECK(rbamp_read_voltage(dev, 0, &u_rms));

Lettura di un periodo — senza il componente

C
// Snapshot + 50 ms settle + ready-flag check + burst-read avg_p
uint8_t latch_cmd[2] = { 0x01, 0x27 };   // REG_COMMAND, CMD_LATCH_PERIOD
ESP_ERROR_CHECK(i2c_master_transmit(slave, latch_cmd, 2, /*xfer_timeout_ms=*/100));
int64_t t_latch_us = esp_timer_get_time();
vTaskDelay(pdMS_TO_TICKS(50));   // settle

uint8_t valid_reg = 0x07, valid_byte = 0;
i2c_master_transmit_receive(slave, &valid_reg, 1, &valid_byte, 1, /*xfer_timeout_ms=*/100);
if ((valid_byte & 0x01) == 0) {
    // snapshot is stale — t_latch_us STILL must be recorded,
    // otherwise the next snapshot will count Wh over two periods
    return;
}

// burst-read 4 bytes of avg_p (auto-increment), then assemble the float
// and integrate Wh:
//   double dt_s = (esp_timer_get_time() - t_prev_latch_us) / 1e6;
//   E_Wh += avg_p * dt_s / 3600.0;

Lettura di un periodo — con il componente

C
rbamp_period_snapshot_t snap;
if (rbamp_read_period_snapshot(dev, &snap, 50, false) == ESP_OK && snap.valid) {
    // snap.avg_p[0] is populated,
    // rbamp_energy_wh(dev, 0) has increased by avg_p × master_dt_ms/1000/3600,
    // master_dt_ms = master wall-clock dt between snapshots (canonical for energy).
    // snap.latch_ms (0xEC) — diagnostic module timer, NOT for energy.
}

Internamente il componente garantisce:

  • Un assestamento di 50 ms dopo CMD_LATCH_PERIOD (configurabile tramite il parametro settle_ms), lettura corretta dello snapshot (snapshot atomico sul lato modulo).

  • Un controllo del flag REG_V03_PERIOD_VALID prima della lettura (il campo snap.valid).

  • Registrazione dell'ora con il clock del master anche su uno snapshot stantio (protegge dal doppio conteggio dei Wh al periodo successivo).

  • Contabilità Wh per canale in doppia precisione (il tipo double all'interno dell'handle).

  • Caricamento automatico dei coefficienti di calibrazione quando il sensore di corrente viene selezionato tramite rbamp_set_sensor_class() + rbamp_set_ct_model() — l'utente non deve conoscere i registri interni di calibrazione.

Quando usare il componente, quando usare l'accesso diretto al bus

Attività Componente Accesso diretto tramite i2c_master_*
Lettura di U / I / P / PF / frequenza ✅ solo per il debug con un analizzatore logico
Contabilità dell'energia per periodo ✅ solo se il Wh è memorizzato fuori dal componente (per esempio in un database lato master)
Più moduli su un bus ✅ (snapshot sequenziale + assestamento condiviso, vedi 06_examples.md) —
Contabilità bidirezionale su BASIC ✅ (tramite letture RT — vedi 06_examples.md) l'alternativa è il proprio loop di letture RT + integrazione manuale
Porting su un'altra piattaforma n/a ✅ — vedi 09 · Riferimento API per i dettagli del protocollo di rete
Limite hard di RAM conta poco (~85 byte per handle) ✅ se anche quei ~85 byte sono critici

Per tutte le attività tipiche delle prime righe, il componente è la scelta giusta.

Architettura

Livelli dal task applicativo attraverso il componente rbamp e il driver I2C fino al modulo rbAmp.

Diagrammi di interazione

Il flusso di rbamp_begin()

Sequenza di transazioni sul bus eseguite da rbamp_begin().

Il primo snapshot è un primer (il modulo restituisce tutto ciò che si è accumulato dall'accensione, non adatto alla contabilizzazione tariffaria). Il componente registra da solo che questo snapshot va scartato — il codice utente non lo vede mai.

Il flusso rbamp_read_period_snapshot(dev, &snap, 50, false)

Sequenza di una lettura di snapshot di periodo e dell'integrazione dell'energia sul master.

Lo snapshot atomico sul lato modulo garantisce che ogni misura all'interno di un periodo finisca in esattamente uno snapshot — nessuna duplicazione e nessuna perdita al confine del periodo.

Corrispondenza con l'API a registri diretti

Una tabella per chi migra dal proprio codice di accesso diretto:

API diretta (i2c_master_transmit_receive) Equivalente tramite il componente
Lettura manuale di 4 byte + memcpy rbamp_read_voltage(dev, 0, &v) / rbamp_read_power(dev, ch, &p)
tx([0x01, 0x27]); vTaskDelay(50) rbamp_latch_period(dev); vTaskDelay(pdMS_TO_TICKS(50)) (oppure direttamente rbamp_read_period_snapshot())
Verifica di read_u8(0x07) & 1 il campo snap.valid dopo rbamp_read_period_snapshot()
Formula manuale E_Wh += avg_p * dt_s / 3600 rbamp_energy_wh(dev, 0) — aggiornato automaticamente
Configurazione manuale del sensore di corrente tramite l'API a registri diretti rbamp_set_sensor_class(dev, cls) + rbamp_set_ct_model(dev, code) — i preset di fabbrica vengono caricati automaticamente

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