02 · Inizializzazione e avvio
rbAmp inizia a misurare immediatamente dopo l'accensione. Il master deve solo:
- Attivi il suo bus I²C (inizializzazione standard
Wire/ HAL). - Attenda ~250 ms, oppure faccia polling su
DATA_VALID = 1al registro0xCE. - Opzionalmente legga la versione del firmware da
0x03come controllo di coerenza. - Dati di lettura — pronti.
Non serve alcun comando di avvio né una configurazione a livello di registro sul chip. La calibrazione di fabbrica viene caricata automaticamente all'avvio, quindi il modulo emette valori corretti in unità fisiche già dalla prima lettura.
Importante per i moduli BASIC serie SCT usati con sensori SCT-013: dopo la prima installazione, deve scrivere il modello del sensore nel registro del modello. Il modulo ha bisogno del modello per applicare il coefficiente mV-per-ampere corretto. Il codice del modello è memorizzato in flash e sopravvive ai riavvii. Sul firmware precedente alla 1.4.20 (bit 12 di CAPABILITY a zero) la scala applicata torna al valore di fabbrica dopo un riavvio del modulo — un master che ha selezionato un modello non di fabbrica deve riconfermarlo dopo ogni riavvio del modulo rilevato (vedi Cosa persiste dopo un riavvio e la regola di rilevamento del riavvio in period-metering.md); dal fw 1.4.20 il cambio di modello sopravvive al riavvio. Sulle immagini precedenti alla 1.4.20, l'energia sarà errata dopo qualsiasi riavvio del modulo, a meno che CT_MODEL non venga riconfermato. Le librerie client gestiscono entrambi i casi per lei. I dettagli sono nella sezione Impostare la classe del sensore e il modello CT più sotto.
I moduli BASIC della serie CT sono forniti in coppia con i loro sensori, preimpostati e calibrati in fabbrica per quel sensore; partono senza inizializzazione.
Nelle librerie client — la stessa operazione senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::begin() / RbAmp::waitReady(timeout_ms) |
interroghi il modulo, poi attenda il flag di pronto |
| ESP-IDF | rbamp_begin() / rbamp_wait_ready() |
interroghi il modulo, poi attenda il flag di pronto |
| Python | dev.begin() / dev.wait_ready(timeout_ms=1000) |
interroghi il modulo, poi attenda il flag di pronto |
| ESPHome | rbamp: address: |
indirizzo del modulo impostato nello YAML; il componente sonda il modulo in fase di setup |
Funzioni di supporto (C neutro rispetto alla piattaforma)
Tutti gli esempi seguenti usano tre piccole funzioni di supporto facili da implementare su qualsiasi piattaforma:
// Read one byte from a slave register.
uint8_t rb_read_u8(uint8_t addr, uint8_t reg);
// Read a little-endian float32 (4 bytes from reg, reg+1, reg+2, reg+3).
// rbAmp supports READ auto-increment — both per-byte access and a single
// 4-byte burst-read are valid. The helpers below show per-byte for clarity;
// production code often uses burst-read for atomicity guarantees (see ch 11).
float rb_read_float_le(uint8_t addr, uint8_t reg);
// Write one byte to a slave register.
void rb_write_u8(uint8_t addr, uint8_t reg, uint8_t val);
Messa in servizio su Arduino (Wire.h)
Funzioni di supporto
#include
uint8_t rb_read_u8(uint8_t addr, uint8_t reg) {
Wire.beginTransmission(addr);
Wire.write(reg);
Wire.endTransmission(false); // repeated start, do not release bus
Wire.requestFrom(addr, (uint8_t)1);
return Wire.read();
}
float rb_read_float_le(uint8_t addr, uint8_t reg) {
uint8_t buf[4];
for (int i = 0; i < 4; i++) {
buf[i] = rb_read_u8(addr, reg + i);
}
float f;
memcpy(&f, buf, 4); // little-endian host (AVR, ESP32, ARM)
return f;
}
void rb_write_u8(uint8_t addr, uint8_t reg, uint8_t val) {
Wire.beginTransmission(addr);
Wire.write(reg);
Wire.write(val);
Wire.endTransmission();
}
Test di funzionamento (singolo modulo)
#include
#define RB_ADDR 0x50
void setup() {
Serial.begin(115200);
Wire.begin();
Wire.setClock(50000);
delay(300); // wait for module boot
// Wait DATA_VALID bit
while ((rb_read_u8(RB_ADDR, 0xCE) & 0x01) == 0) {
Serial.println("waiting for DATA_VALID...");
delay(50);
}
uint8_t ver = rb_read_u8(RB_ADDR, 0x03);
Serial.printf("rbAmp ready, version 0x%02X\n", ver);
}
void loop() {
float u_rms = rb_read_float_le(RB_ADDR, 0x86);
float i_rms = rb_read_float_le(RB_ADDR, 0x8E);
float p = rb_read_float_le(RB_ADDR, 0xA6);
float pf = rb_read_float_le(RB_ADDR, 0xB2);
Serial.printf("U=%.1f V I=%.3f A P=%.1f W PF=%.3f\n",
u_rms, i_rms, p, pf);
delay(1000);
}
Usi un carico di almeno ~1 % della portata del sensore — al di sotto di questo valore le letture diventano rumorose e la classe non è garantita (una lampada da 60 W è solo lo 0.9 % di una pinza da 30 A; vedi la tabella delle caratteristiche). Con una pinza da 30 A, un bollitore da 2 kW è un buon carico per il test di funzionamento. Per i moduli BASIC della serie SCT con sensore SCT-013, imposti la classe del sensore e il modello CT prima del test (vedi Impostazione della classe del sensore e del modello CT) — senza il modello le letture di corrente non hanno significato.
Output atteso (un bollitore da 2 kW a 230 V, pinza da 30 A):
rbAmp ready, version 0x04
U=229.8 V I=8.72 A P=2004 W PF=0.999
U=230.1 V I=8.73 A P=2008 W PF=0.999
...
Messa in servizio su STM32 HAL (C)
#include "stm32f1xx_hal.h"
extern I2C_HandleTypeDef hi2c1;
#define RB_ADDR_8BIT (0x50 << 1) // HAL expects 8-bit address format
uint8_t rb_read_u8(uint8_t reg) {
uint8_t v;
HAL_I2C_Mem_Read(&hi2c1, RB_ADDR_8BIT, reg, I2C_MEMADD_SIZE_8BIT, &v, 1, 100);
return v;
}
float rb_read_float_le(uint8_t reg) {
uint8_t buf[4];
for (int i = 0; i < 4; i++) {
HAL_I2C_Mem_Read(&hi2c1, RB_ADDR_8BIT, reg + i, I2C_MEMADD_SIZE_8BIT,
&buf[i], 1, 100);
}
float f;
memcpy(&f, buf, 4);
return f;
}
void main_app(void) {
while ((rb_read_u8(0xCE) & 0x01) == 0) HAL_Delay(50);
uint8_t ver = rb_read_u8(0x03);
printf("rbAmp version: 0x%02X\n", ver);
while (1) {
float u = rb_read_float_le(0x86);
float i = rb_read_float_le(0x8E);
float p = rb_read_float_le(0xA6);
printf("U=%.1f V I=%.3f A P=%.1f W\n", u, i, p);
HAL_Delay(1000);
}
}
Moduli della serie CT: avvio senza configurazione
Un modulo serie CT viene fornito con ogni canale di corrente già configurato: classe del sensore, portata e calibrazione sono scritti in fabbrica per la pinza fornita con quel canale. Non servono scritture di inizializzazione — l'host si limita a leggere.
⚠ Non scriva la classe del sensore né il modello del sensore su un modulo serie CT. - Scrivere il modello su un canale sostituisce la calibrazione di fabbrica di quel canale con un preset generico: l'errore attuale diventa da −2 a +3 % e la soglia di bassa corrente risulta errata. - Scrivere la classe azzera il modello di ogni canale.
Con firmware 1.4.22 e successivi un modulo della serie CT rifiuta in funzionamento normale le scritture di classe e modello con ERR_PARAM (0xFE); le librerie client le rifiutano su tutti i firmware.
Il canale e la sua pinza formano una coppia. Ogni pinza è etichettata con il canale a cui appartiene. Non sposti una pinza su un altro canale e non colleghi un'altra pinza a un canale: la calibrazione vale solo per l'accoppiamento di fabbrica. Le portate sono fisse; non c'è una portata da scegliere.
Sequenza di avvio
- Colleghi le pinze (freccia verso il carico — vedi hardware-connection.md) e alimenti il modulo.
- Legga la classe (
SENSOR_CLASS,0x25):2= serie di pinze CT. - Legga il modello applicato di ogni canale (
0x51..0x53, un registro per canale; UI5/UI7 canali 3 e successivi: tramite la finestra di accesso ai canali, campoCT_MODEL) e lo associ alla portata:
| Codice modello | 0x06 |
0x07 |
0x08 |
0x09 |
0x0A |
0x0B |
0x0D |
|---|---|---|---|---|---|---|---|
| Portata | 1 A | 5 A | 10 A | 20 A | 30 A | 50 A | 100 A |
Usi la portata per scalare gli intervalli di visualizzazione e per validare le letture; il modulo riporta già gli ampere.
- Faccia polling come per qualsiasi modulo BASIC — finestra di misura di 100 ms, pin data-ready o lettura periodica (vedi realtime-polling.md); misura del periodo come in period-metering.md.
Non serve altro: non c'è selezione del sensore, né passo di guadagno, né comando di salvataggio. Il modulo conserva la sua configurazione dopo i riavvii.
Sostituzione di una pinza o di un modulo
La calibrazione appartiene alla coppia. Una pinza o un canale non possono essere sostituiti sul campo: un modulo che richiede una nuova pinza viene restituito al servizio di fabbrica per il riaccoppiamento.
Impostare la classe del sensore e il modello CT
Richiesto solo per i moduli BASIC serie SCT usati con i sensori SCT-013. I moduli BASIC serie CT sono forniti in coppia con i loro sensori: tutto è preimpostato e calibrato in fabbrica per quello specifico sensore, e partono senza inizializzazione — salti questa sezione.
Due registri descrivono il sensore esterno: SENSOR_CLASS (la famiglia — pinze a innesto SCT-013, serie di pinze CT cablate, CT integrato) e CT_MODEL (il codice del modello specifico all'interno della famiglia). Dalla v1.3 il modello si scrive con uno schema di sola predisposizione — scrivere CT_MODEL non lo applica da solo; un comando dedicato per canale conferma il valore predisposto.
Registri
| Nome | Indirizzo | Tipo | Note |
|---|---|---|---|
SENSOR_CLASS |
0x25 |
u8 RW | 0 = Non impostato, 1 = SCT_013, 2 = WIRED_CT (la serie di pinze CT), 3 = BUILTIN_CT (sensore integrato, calibrazione di fabbrica per unità — nessun codice modello). Cambiare la classe riporta CT_MODEL a 0. |
CT_MODEL |
0x05 |
u8 RW | Codice del modello CT — solo registro di preparazione. La scrittura semplice non lo applica. |
Scelta di un sensore
Acquisti uno dei modelli SCT-013 a uscita di tensione elencati nella tabella sotto (spina da 3.5 mm) — non una variante a uscita di corrente. Scelga la pinza di portata più piccola che sia superiore alla sua corrente massima prevista; per la classe dichiarata il carico non dovrebbe stare sotto circa lo 1 % della portata (vedi la tabella di precisione).
Codici modello CT — famiglia SCT-013 (SENSOR_CLASS = 1)
| Codice | Sensore | Corrente nominale | Inizio del clipping RMS | Limite di picco |
|---|---|---|---|---|
0x00 |
non impostato (predefinito sui moduli BASIC serie SCT di nuova fabbricazione) | — | — | — |
0x01 |
SCT-013-005 | 5 A | 5.8 A | 8.2 A |
0x02 |
SCT-013-010 | 10 A | 11.6 A | 16.4 A |
0x03 |
SCT-013-030 | 30 A | 34.8 A | 49.2 A |
0x04 |
SCT-013-050 | 50 A | 58 A | 82 A |
0x05 |
SCT-013-100 | 100 A | 116 A | 164 A |
0x06 |
SCT-013-020 | 20 A | 23.2 A | 32.8 A |
0x07 |
SCT-013-060 | 60 A | 69.6 A | 98.4 A |
I codici 0x06 e 0x07 non sono monotoni per portata — sono stati aggiunti dopo il gruppo originale 0x01..0x05. Scelga sempre in base alla portata che le serve, non per ordine dei codici.
Semantica dei limiti: la corrente nominale e l'inizio del clipping RMS presuppongono un carico sinusoidale; l'inizio del clipping misurato è ≈ 1.16 × la portata. Il limite di picco (≈ 1.64 × la portata) è il vero tetto — un carico distorto (fattore di cresta alto) inizia il clipping a picco / fattore di cresta, al di sotto dei valori RMS. Resti al di sotto o pari alla portata per la precisione specificata: le letture vanno in clipping intorno al 115–120 % della portata.
I valori per portata (soglia rilevabile e leggibile, classe, tolleranza del sensore, punto di clipping) sono nella tabella di precisione in overview.md. Cambiare il modello del sensore significa scrivere il codice modello nel modulo — non serve altro; non c'è alcuna fase di ricalibrazione.
Codici modello CT — serie di pinze CT cablate (SENSOR_CLASS = 2)
I moduli della serie CT- sono forniti come set calibrato in fabbrica con la propria pinza: classe e modello sono già impostati e fanno parte della calibrazione — vedi Moduli serie CT: avvio senza configurazione. Non li scriva. La tabella sotto è un riferimento per leggere il modello applicato; sul modulo serie CT l'utente non seleziona nulla.
| Codice | Pinza | Corrente nominale | Finestra |
|---|---|---|---|
0x01..0x05 |
preset CT cablati storici | — | — |
0x06 |
Pinza CT, 1 A | 1 A | 6 mm |
0x07 |
Pinza CT, 5 A | 5 A | 6 mm |
0x08 |
Pinza CT, 10 A | 10 A | 6 mm |
0x09 |
Pinza CT, 20 A | 20 A | 10 mm |
0x0A |
Pinza CT, 30 A | 30 A | 10 mm |
0x0B |
Pinza CT, 50 A | 50 A | 10 mm |
0x0D |
Pinza CT, 100 A | 100 A | 16 mm |
La dimensione della finestra dipende dalla corrente nominale (6 mm per 1–10 A, 10 mm per 20–50 A, 16 mm per 100 A) e non influisce sulla calibrazione.
Comandi
| Nome | Opcode | Effetto | Attendere |
|---|---|---|---|
CMD_SET_CT_MODEL_CH0 |
0x28 |
Associ il valore preparato CT_MODEL al canale 0 |
~5 ms |
CMD_SET_CT_MODEL_CH1 |
0x29 |
Associ al canale 1 (UI2/UI3/I2/I3) | ~5 ms |
CMD_SET_CT_MODEL_CH2 |
0x2A |
Associ al canale 2 (UI3/I3) | ~5 ms |
CMD_SAVE_USER_CONFIG |
0x32 |
Persista il blocco di configurazione utente (classe del sensore, modello CT, indirizzo, etichetta) in flash | ~700 ms |
Procedura
- Inserisca la/e pinza/e CT nel/i connettore/i del modulo (freccia verso il carico — vedi hardware-connection.md).
-
Imposti la classe del sensore(una volta, se non già impostato):
C++rb_write_u8(0x50, 0x25, 0x01); // SCT_013 -
Per ogni canale il modulo espone:
- Prepari il codice del modello CT in
CT_MODEL:C++rb_write_u8(0x50, 0x05, 0x03); // example: SCT-013-030 - Lo associ al canale corrispondente
CMD_SET_CT_MODEL_CHn:C++rb_write_u8(0x50, 0x01, 0x28); // CMD_SET_CT_MODEL_CH0 delay(5); - Ripeta per ch1 / ch2 se la variante li ha (i canali sono indipendenti — può mescolare codici di modello per canale).
-
Persistain flash con
CMD_SAVE_USER_CONFIG:C++rb_write_u8(0x50, 0x01, 0x32); delay(700); // flash erase/write -
Fatto — con un'avvertenza sul firmware precedente alla 1.4.20 (
CAPABILITYbit 12 a zero): lì il codice del modello salvato sopravvive ai riavvii, ma la scala applicata no (vedi Cosa persiste dopo un riavvio più sotto) — se ha scelto un modello non di fabbrica, ripeta il passo 3 (preparazione + commit) dopo ogni riavvio rilevato del modulo;CMD_SAVE_USER_CONFIGnon va ripetuto. Dal fw 1.4.20 il cambio di modello sopravvive ai riavvii.
: dalla v1.3 può chiamare CMD_SET_CT_MODEL_CH0/1/2 in qualsiasi ordine. Non serve alcun workaround di ordine discendente (era un artefatto interno dei firmware precedenti).
Comportamento con le librerie client attuali
Le librerie client rbAmp (Arduino, ESP-IDF, ESPHome, Python) incapsulano questa procedura e aggiungono:
-
La riscrittura dello stesso valore viene saltata. Impostare la classe del sensore o il modello CT al valore che il modulo ha già non genera alcuna scrittura sul bus né un ciclo di flash — chiamare il setter ad ogni avvio è sicuro.
-
I moduli accoppiati in fabbrica rifiutano il cambio di classe e modello. Sulle SKU fornite come set calibrato in fabbrica con il proprio sensore di corrente (serie CT), la classe e il modello del sensore fanno parte della calibrazione: il modulo (firmware 1.4.22 e successivi) rifiuta la scrittura con
ERR_PARAM (0xFE)in funzionamento normale, e le librerie la rifiutano prima dell'invio su tutti i firmware. Riaccoppiare un sensore sostitutivo è un servizio di fabbrica. -
Limiti per modello. Per ogni modello CT le librerie espongono la corrente nominale, il livello RMS in cui inizia il clipping e il limite di picco — li usi per validare le letture rispetto al sensore collegato.
Verifica
Dopo l'associazione, il modello CT applicato di ogni canale viene replicato in 0x51..0x53 (specchi di sola verifica). Non sono il registro di predisposizione 0x05:
uint8_t ch0 = rb_read_u8(0x50, 0x51); // applied on ch0
uint8_t ch1 = rb_read_u8(0x50, 0x52); // applied on ch1
uint8_t ch2 = rb_read_u8(0x50, 0x53); // applied on ch2
Serial.printf("Applied: ch0=0x%02X ch1=0x%02X ch2=0x%02X\n", ch0, ch1, ch2);
⚠ La rilettura ≠ persistenza. Una lettura riuscita di 0x51..0x53 conferma che il valore è attivo in RAM, non che sia sopravvissuto in flash. Per verificare la persistenza emetta CMD_RESET (o un ciclo di alimentazione) e rilegga dopo la finestra di avvio. Lo schema completo è in period-metering.md.
Quando mette in servizio un nuovo modulo, esegua un controllo di buon senso con un carico resistivo noto (per esempio una lampada a incandescenza da 100 W): I_rms ≈ 100 W / U_rms ≈ 0.43 A e P_real ≈ 100 W. Se le letture sono sbagliate di un fattore elevato, il codice modello è probabilmente errato.
Cosa persiste dopo un riavvio
CMD_SAVE_USER_CONFIG salva il blocco di configurazione utente in flash, ma non tutto ciò che il master imposta viene riapplicato al successivo avvio. Sul firmware precedente alla 1.4.20 (bit 12 di CAPABILITY a zero):
| Voce | Sopravvive a un riavvio? |
|---|---|
| Indirizzo I²C | sì |
| Etichetta del modulo | sì |
| Classe del sensore + codice del modello CT (leggibile) | sì |
| Scala applicata per modello | prima del fw 1.4.20: no — torna al valore di fabbrica; dal 1.4.20 (CAPABILITY bit 12 impostato): sì |
FLEET_CONFIG (attivazione GC) + GROUP_ID |
sì (tramite CMD_SAVE_USER_CONFIG; ha effetto dopo il reset) |
| Configurazione solo in RAM (soglie di evento, configurazione del digest) | no |
La conseguenza su quelle immagini: un modulo commutato su un modello diverso da quello uscito di fabbrica legge di nuovo il codice modello salvato dopo un riavvio, ma misura con la scala di fabbrica finché il modello non viene nuovamente confermato. La regola per qualsiasi master (e per un hub che gestisce una flotta, indicizzata per UID del modulo):
-
Rilevi il riavvio —
UPTIME_S/ bit di eventoRESET_OCCURRED, vedi period-metering.md → Rilevare un riavvio del modulo. -
Ripreperi e ricommetta il modello CT su ogni canale (
CT_MODEL+CMD_SET_CT_MODEL_CHn), poi riapplichi ogni configurazione solo RAM.
Le librerie client implementano esattamente questo nel loro percorso di ripresa. Dal fw 1.4.20 (bit 12 di CAPABILITY, SCT_RATING_SELF) il cambio di modello mantiene la calibrazione dell'unità e sopravvive ai riavvii — il passo 2 non è quindi necessario per il modello CT; la configurazione solo in RAM richiede ancora una reinizializzazione. I moduli che funzionano con il modello di fabbrica (inclusi tutti i moduli serie CT accoppiati in fabbrica) non sono interessati su nessuna immagine — la scala di fabbrica è quella corretta.
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::setSensorClass(cls) / RbAmp::setCTModel(channel, code) |
imposti la classe del sensore e il modello CT per canale |
| ESP-IDF | rbamp_set_sensor_class() / rbamp_set_ct_model_ch() |
imposti la classe del sensore e il modello CT per canale |
| Python | dev.set_sensor_class(cls) / dev.set_ct_model_ch(channel, code) |
imposti la classe del sensore e il modello CT per canale |
| ESPHome | sensor_class: / ct_model: |
Opzioni YAML per la classe del sensore e il modello CT |
Flusso di lavoro con un singolo modulo
- Colleghi il modulo secondo hardware-connection.md.
- Per i moduli BASIC della serie SCT, scriva il modello del sensore una sola volta (sezione precedente).
- Carichi il master con lo sketch di test di funzionamento.
- Apra il monitor seriale — dovrebbe vedere U/I/P ogni secondo.
- Se le letture sembrano errate, consulti troubleshooting.md.
Configurazione multi-modulo
Scenario: tre moduli rbAmp su un unico bus per monitorare diverse sezioni di una casa (alimentazione principale, scaldabagno, condizionatore).
Passo 1 — Indirizzi
Di fabbrica tutti e tre i moduli hanno l'indirizzo 0x50. Vanno riassegnati uno alla volta. Colleghi un solo modulo al bus finché la riassegnazione non è completata.
Passo 2 — Test di funzionamento con un modulo
Usi la sezione sopra. Verifichi che un modulo funzioni correttamente.
Passo 3 — Cambio indirizzo (e, se necessario, impostazione del modello CT)
Usi la procedura di cambio indirizzo qui sotto. Se i moduli usano sensori SCT-013 diversi, imposti il modello CT su ciascuno prima di cambiarne l'indirizzo.
Passo 4 — Ciclo di polling multi-modulo
#include
const uint8_t modules[] = {0x50, 0x51, 0x52}; // main, boiler, AC
const char* labels[] = {"MAIN", "BOIL", "AC "};
const int N = sizeof(modules) / sizeof(modules[0]);
void setup() {
Serial.begin(115200);
Wire.begin();
Wire.setClock(50000);
delay(300);
for (int i = 0; i < N; i++) {
Wire.beginTransmission(modules[i]);
uint8_t rc = Wire.endTransmission();
Serial.printf("Module %s (0x%02X): %s\n",
labels[i], modules[i], rc == 0 ? "OK" : "MISSING");
}
}
void loop() {
for (int i = 0; i < N; i++) {
float u = rb_read_float_le(modules[i], 0x86);
float p = rb_read_float_le(modules[i], 0xA6);
Serial.printf("[%s] U=%.1f P=%.1f W\n", labels[i], u, p);
}
Serial.println();
delay(1000);
}
Output atteso:
Module MAIN (0x50): OK
Module BOIL (0x51): OK
Module AC (0x52): OK
[MAIN] U=229.8 P=850.3 W
[BOIL] U=229.7 P=1850.0 W
[AC ] U=229.9 P=0.0 W
...
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmpFleet::scan(match_product, added) / RbAmpFleet::pollAll(snaps, status, capacity, n_ok) |
individui i moduli sul bus; li legga tutti in un solo passaggio |
| ESP-IDF | rbamp_fleet_scan() / rbamp_fleet_poll_all() |
individui i moduli sul bus; li legga tutti in un solo passaggio |
| Python | fleet.scan(match_product=True) / fleet.poll_all() |
individui i moduli sul bus; li legga tutti in un solo passaggio |
| ESPHome | rbamp: (list) |
un blocco rbamp: per modulo, ciascuno con il proprio id e address |
Cambio indirizzo
L'indirizzo di fabbrica 0x50 è memorizzato nel blocco di configurazione utente in flash. La v1.3 usa una sequenza di commit in due fasi per rendere difficili i cambi di indirizzo accidentali: un indirizzo candidato va prima in un registro di predisposizione in RAM, deve essere armato con un byte magic, e solo allora viene confermato in flash con un comando esplicito. Un reset rienumera il modulo al nuovo indirizzo.
Registri e comandi
| Nome | Indirizzo / opcode | Tipo | Scopo |
|---|---|---|---|
REG_I2C_ADDRESS |
0x30 |
u8 RW | Preparazione per il candidato indirizzo (0x08..0x77). Una regola: prima del reset, 0x30 ripete il candidato preparato; dopo l'avvio legge l'indirizzo attivo. |
ADDR_COMMIT_MAGIC |
0x31 |
u8 W | Armi il commit con 0xA5. Consumato (azzerato) al tentativo di commit. |
CMD_COMMIT_ADDR |
opcode 0x30 scritto in REG_COMMAND (0x01) |
comando | Valida l'indirizzo in predisposizione rispetto al magic e lo rende persistente in flash. |
CMD_RESET |
opcode 0x01 scritto in REG_COMMAND (0x01) |
comando | Reset software. Il modulo si rienumera al nuovo indirizzo dopo ~300 ms. |
Procedura
- Colleghi un solo modulo (ancora su
0x50) al bus. -
Imposti il nuovo indirizzo in fase di predisposizione:
C++rb_write_u8(0x50, 0x30, 0x51); // candidate address → RAM staging -
Armi il commit:
C++rb_write_u8(0x50, 0x31, 0xA5); // ADDR_COMMIT_MAGIC -
Problema
CMD_COMMIT_ADDR(opcode0x30):C++rb_write_u8(0x50, 0x01, 0x30); -
Attendere≥ 700 msper la cancellazione/scrittura della flash:
C++delay(700); -
Problema
CMD_RESET(opcode0x01) —CMD_COMMIT_ADDRfanon auto-reset:C++rb_write_u8(0x50, 0x01, 0x01); -
Attenda ~300 ms per la finestra di avvio. Non invii comandi durante questa finestra.
-
Verifichi che il modulo risponda con ACK al nuovo indirizzo:
C++uint8_t ver = rb_read_u8(0x51, 0x03); // VERSION should be 0x04 on v1.3 if (ver == 0x04) Serial.println("Address change OK"); -
Contrassegni il PCB con il nuovo indirizzo usando una matita a cera o un'etichetta, così può identificare fisicamente il modulo.
Note importanti
- Entrambe le fasi sono obbligatorie. Scrivere il candidato in
0x30da solo non produce nulla di persistente — finisce solo in RAM e va perso al reset successivo. La coppia magic-e-commit è ciò che riscrive davvero la flash. - L'indirizzo preparato deve trovarsi nell'intervallo
0x08..0x77(I²C valido a 7 bit). Le scritture fuori intervallo vengono rifiutate conERR_PARAM; il modulo mantiene l'indirizzo attuale. - Indirizzi I²C riservati:
0x00(chiamata generale, vedi sotto),0x01..0x07(CBus riservato),0x78..0x7F(10 bit riservati). Non li usi. - Una regola di rilettura: prima del reset
0x30ripete il candidato preparato; dopo l'avvio legge l'indirizzo attivo. - Il magic armato scade dopo 5 s senza commit (capitolo 11 §6.1) — armi di nuovo se ha aspettato troppo.
- Promemoria sullo spazio di nomi — lo stesso valore di byte può essere un indirizzo e un opcode:
| Byte | Come indirizzo di registro | Come opcode (scritto in 0x01) |
|---|---|---|
0x27 |
FLEET_CONFIG |
CMD_LATCH_PERIOD |
0x28 |
GROUP_ID |
CMD_SET_CT_MODEL_CH0 |
0x30 |
REG_I2C_ADDRESS |
CMD_COMMIT_ADDR |
Esempio completo di modifica dell'indirizzo
#include
bool change_address(uint8_t old_addr, uint8_t new_addr) {
if (new_addr < 0x08 || new_addr > 0x77) {
Serial.println("ERROR: invalid address");
return false;
}
Serial.printf("Changing 0x%02X -> 0x%02X\n", old_addr, new_addr);
rb_write_u8(old_addr, 0x30, new_addr); // 1. stage candidate
rb_write_u8(old_addr, 0x31, 0xA5); // 2. arm magic
rb_write_u8(old_addr, 0x01, 0x30); // 3. CMD_COMMIT_ADDR
delay(700); // 4. flash erase/write
rb_write_u8(old_addr, 0x01, 0x01); // 5. CMD_RESET (mandatory)
delay(300); // 6. boot window
Wire.beginTransmission(new_addr);
if (Wire.endTransmission() == 0) {
Serial.printf("OK, module now at 0x%02X\n", new_addr);
return true;
}
Serial.printf("FAIL: module not found at 0x%02X\n", new_addr);
return false;
}
void setup() {
Serial.begin(115200);
Wire.begin();
delay(300);
change_address(0x50, 0x51);
}
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::prepareAddressChange(new_addr) / RbAmp::commitAddressChange() |
imposti e armi il nuovo indirizzo, poi lo confermi |
| ESP-IDF | rbamp_prepare_address_change() / rbamp_commit_address_change() |
imposti e armi il nuovo indirizzo, poi lo confermi |
| Python | dev.prepare_address_change(new_addr) / dev.commit_address_change() |
imposti e armi il nuovo indirizzo, poi lo confermi |
| ESPHome | new_address: |
modifica di indirizzo una tantum all'avvio; rimuova l'opzione in seguito |
General Call (broadcast all'indirizzo 0x00)
Il protocollo I²C riserva l'indirizzo 0x00 (chiamata generale) — i frame inviati a questo indirizzo vengono ricevuti contemporaneamente da tutti gli slave del bus. rbAmp può eseguire il proprio snapshot del periodo su un frame di chiamata generale, ma solo dopo che la funzione è stata esplicitamente attivata sul modulo.
Attivazione facoltativa (predefinito OFF)
La ricezione dello snapshot General Call è disattivata per impostazione predefinita — un modulo nuovo risponderà con NACK al frame general-call, che il master rileva come errore grave e passa automaticamente allo snapshot sequenziale per modulo. Per attivare il GC su un modulo:
- Imposti il bit 0 di
FLEET_CONFIG:C++rb_write_u8(0x50, 0x27, 0x01); // bit0 = GC_ENABLE
Nota sul valore 0x27: è l'indirizzo di registro di FLEET_CONFIG. Lo stesso byte 0x27 è anche l'opcode di comando di CMD_LATCH_PERIOD (uno spazio di nomi separato — gli opcode vanno in REG_COMMAND all'indirizzo 0x01). La collisione è puramente formale; indirizzo e opcode non si confondono mai a livello di filo.
-
(Facoltativo) imposti
GROUP_IDper il partizionamento della flotta —0x00accetta tutti-chiamata:C++rb_write_u8(0x50, 0x28, 0x00); // all-call -
Persist:
C++rb_write_u8(0x50, 0x01, 0x32); // CMD_SAVE_USER_CONFIG delay(700); -
Esegua il reset e verifichi che il bit sia stato scritto:
C++rb_write_u8(0x50, 0x01, 0x01); // CMD_RESET delay(300); uint8_t cfg = rb_read_u8(0x50, 0x27); if (cfg & 0x01) Serial.println("GC enabled");
Formato del frame GC
I frame di snapshot GC hanno una struttura fissa di magic e opcode:
addr 0x00 | A5 27
A5— magic del frame (lo slave rifiuta qualsiasi altro byte).27— opcode (CMD_LATCH_PERIOD).— gruppo di destinazione (0x00= all-call; altrimenti deve corrispondere aGROUP_IDdel modulo).— contatore di tick a 16 bit lato master, riportato nel registroGC_TICK (0x59)di ciascun modulo per il rilevamento dei frame persi.
Per progetto i frame GC trasportano solo il comando di snapshot — gli opcode distruttivi (SAVE_*, COMMIT_ADDR, FACTORY_RESET) non vengono eseguiti tramite general-call.
Esempio di snapshot broadcast (dopo l'abilitazione)
// All modules with GC enabled take their snapshots at once.
Wire.beginTransmission(0x00);
Wire.write(0xA5); // frame magic
Wire.write(0x27); // CMD_LATCH_PERIOD opcode
Wire.write(0x00); // group_id = all-call
Wire.write(tick & 0xFF); // tick_lo
Wire.write((tick >> 8) & 0xFF); // tick_hi
uint8_t rc = Wire.endTransmission();
if (rc != 0) {
// NACK at GC level → no module on the bus has GC enabled.
// Fall back to per-module sequential snapshot.
}
Dopo il broadcast, ogni modulo aggiorna il proprio snapshot in modo indipendente. Il master poi legge ogni modulo al suo indirizzo individuale. Verifica testimone (consigliata): dopo ~50 ms di assestamento, legga V03_PERIOD_VALID (0x07) su ciascun modulo atteso — 1 conferma che lo snapshot è arrivato; 0 ricade sullo snapshot per modulo solo su quel modulo.
Applicazione: sincronizzazione precisa dei periodi per il bilanciamento energetico multi-modulo (ad es. mains_input − solar_output), dove l'istante dello snapshot deve essere identico su tutti i moduli.
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::enableGc(enable) / RbAmpFleet::gcLatch(group, tick, settle_ms) |
attivi la General Call su un modulo; invii il frame di snapshot alla flotta |
| ESP-IDF | rbamp_enable_gc() / rbamp_fleet_gclatch() |
attivi la General Call su un modulo; invii il frame di snapshot alla flotta |
| Python | dev.enable_gc(enable=True) / fleet.gc_latch(group, tick, settle_ms) |
attivi la General Call su un modulo; invii il frame di snapshot alla flotta |
| ESPHome | fleet_gc_enable: / group_id: |
Opzioni YAML per l'attivazione della General Call e l'ID di gruppo |
Flusso consigliato per la messa in opera di più moduli
Step 1: Unbox all modules — every module is on address 0x50.
Step 2: For each module, one at a time:
a) Connect only this module to the bus.
b) If it is a BASIC SCT-series module: set SENSOR_CLASS (0x25), stage CT_MODEL (0x05),
issue CMD_SET_CT_MODEL_CHn for each channel, then CMD_SAVE_USER_CONFIG.
c) On images before fw 1.4.20 (`CAPABILITY` bit 12 clear): after any later reset of this
module, re-stage and re-commit CT_MODEL on each channel (see the persistence table above).
d) Run change_address(0x50, ).
e) Verify the module responds at the new address.
f) Physically mark the module (label with 0x51, 0x52, ...).
g) Disconnect and move to the next module.
Step 3: After readdressing all modules, connect them in parallel.
With four or more modules (or a longer bus), cut the built-in
pull-up jumpers on all but one (see hardware-connection.md → I2C pull-ups).
Step 4: At master boot, run a scan loop and verify every readdressed
module responds at its expected address.
BASIC o STD?
La linea di moduli rbAmp STD risponde sullo stesso bus ma usa una mappa di registri diversa, a 16 bit. Prima di applicare il rilevamento BASIC qui sotto, può distinguerli: invii il puntatore a 16 bit 0x00 0x00 e legga 2 byte — un modulo STD restituisce la coppia ASCII 'S','T' (0x53 0x54); un modulo BASIC no (tratta i byte come scritture di registro a 8 bit e restituisce i suoi normali dati). I moduli STD sono coperti dalla loro documentazione di riferimento.
Non serve farlo da sé quando usa una libreria client. Le librerie (Arduino, ESP-IDF, Python, ESPHome) riconoscono già la linea dei moduli e gestiscono le diverse dimensioni dei registri — non deve preoccuparsi se la mappa dei registri sia a 8 o a 16 bit.
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::line() / RbAmp::begin() |
linea rilevata in begin(); la rilegga dal valore in cache |
| ESP-IDF | rbamp_line() / rbamp_begin() |
linea rilevata in begin; la rilegga dal valore memorizzato |
| Python | dev.is_std / dev.begin() |
linea rilevata in begin(); la rilegga dalla proprietà |
| ESPHome | — | non esposto — il rilevamento è automatico, nulla da configurare nel YAML |
Rilevamento automatico della variante del modulo
⚠ Non rilevi la variante sondando un NACK sulle letture dei registri. Il firmware non risponde mai con NACK alle letture dei registri — gli indirizzi non mappati restituiscono 0x00 (vedi capitolo 11 §5.2). Un controllo basato su NACK segnalerebbe sempre "canale presente".
Usi la coppia canonica HW_VARIANT (0x55) + CAPABILITY (0x57/0x58):
struct VariantInfo {
uint8_t hw_variant; // 1=UI1, 2=UI2, 3=UI3, 4=I1, 5=I2, 6=I3
uint8_t n_current; // 1..3
bool has_voltage; // true on UI*, false on I*
};
VariantInfo detect_variant(uint8_t addr) {
VariantInfo v = {0, 0, false};
uint8_t product = rb_read_u8(addr, 0x54); // PRODUCT_ID
if (product != 0x01) return v; // not an rbAmp sensor
v.hw_variant = rb_read_u8(addr, 0x55); // HW_VARIANT
uint8_t hw = v.hw_variant;
v.n_current = (hw == 1 || hw == 4) ? 1
: (hw == 2 || hw == 5) ? 2
: (hw == 3 || hw == 6) ? 3 : 0;
uint8_t cap_hi = rb_read_u8(addr, 0x58); // CAPABILITY high byte
v.has_voltage = (cap_hi & 0x01) != 0; // bit 8 of u16 = voltage-HW
return v;
}
HW_VARIANT 1..3 sono varianti UI (has_voltage == true); 4..6 sono varianti solo corrente (has_voltage == false). Una discordanza tra la famiglia HW_VARIANT e CAPABILITY.bit8 indica un modulo danneggiato o flashato male.
AC_FREQ (0x20) funziona su tutte le varianti — il segnale di passaggio per lo zero proviene da un pin dedicato al passaggio per lo zero di rete, indipendente dal front-end di tensione.
— lo stesso compito senza accesso ai registri:
| Libreria | Chiamata | Cosa fa |
|---|---|---|
| Arduino | RbAmp::readVariant() / RbAmp::readCapability(out) |
legga la variante hardware e la mappa delle funzioni |
| ESP-IDF | rbamp_read_variant() / rbamp_read_capability() |
legga la variante hardware e la mappa delle funzioni |
| Python | dev.read_variant() / dev.read_capability() |
legga la variante hardware e la mappa delle funzioni |
| ESPHome | get_variant_str() / get_capability_hex() |
stringa della variante e mappa delle funzioni dalla superficie di identità |
Avanti
- realtime-polling.md — polling in tempo reale in dettaglio (finestra da 100 ms, DRDY)
- period-metering.md — accumulo tariffario dell'energia