rbAmp
IT
Negozio
Docs
Aggiornato il

02 · Inizializzazione e avvio

rbAmp inizia a misurare immediatamente dopo l'accensione. Il master deve solo:

  1. Attivi il suo bus I²C (inizializzazione standard Wire / HAL).
  2. Attenda ~250 ms, oppure faccia polling su DATA_VALID = 1 al registro 0xCE.
  3. Opzionalmente legga la versione del firmware da 0x03 come controllo di coerenza.
  4. 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.

La sequenza dall'accensione alla prima lettura valida.

Nota

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:

C
// 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

C++
#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)

C++
#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):

Text
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)

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.

Sicurezza

⚠ 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

  1. Colleghi le pinze (freccia verso il carico — vedi hardware-connection.md) e alimenti il modulo.
  2. Legga la classe (SENSOR_CLASS, 0x25): 2 = serie di pinze CT.
  3. 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, campo CT_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.

  1. 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

Nota

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
Nota

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
Nota

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

  1. Inserisca la/e pinza/e CT nel/i connettore/i del modulo (freccia verso il carico — vedi hardware-connection.md).
  2. Imposti la classe del sensore(una volta, se non già impostato):

    C++
    rb_write_u8(0x50, 0x25, 0x01);    // SCT_013
    

  3. Per ogni canale il modulo espone:

  4. Prepari il codice del modello CT inCT_MODEL:
    C++
    rb_write_u8(0x50, 0x05, 0x03);    // example: SCT-013-030
    
  5. Lo associ al canale corrispondenteCMD_SET_CT_MODEL_CHn:
    C++
    rb_write_u8(0x50, 0x01, 0x28);    // CMD_SET_CT_MODEL_CH0
    delay(5);
    
  6. Ripeta per ch1 / ch2 se la variante li ha (i canali sono indipendenti — può mescolare codici di modello per canale).
  7. Persistain flash conCMD_SAVE_USER_CONFIG:

    C++
    rb_write_u8(0x50, 0x01, 0x32);
    delay(700);                          // flash erase/write
    

  8. Fatto — con un'avvertenza sul firmware precedente alla 1.4.20 (CAPABILITY bit 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_CONFIG non va ripetuto. Dal fw 1.4.20 il cambio di modello sopravvive ai riavvii.

Indipendenza dall'ordine dei canali

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

C++
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);
Sicurezza

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

  1. Rilevi il riavvio — UPTIME_S / bit di evento RESET_OCCURRED, vedi period-metering.md → Rilevare un riavvio del modulo.

  2. 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.

Nelle librerie client

— 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

  1. Colleghi il modulo secondo hardware-connection.md.
  2. Per i moduli BASIC della serie SCT, scriva il modello del sensore una sola volta (sezione precedente).
  3. Carichi il master con lo sketch di test di funzionamento.
  4. Apra il monitor seriale — dovrebbe vedere U/I/P ogni secondo.
  5. 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

C++
#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:

Text
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
...
Nelle librerie client

— 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.

Il cambio di indirizzo in due fasi: predisporre l'indirizzo candidato, armarlo, confermarlo, poi resettare.

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

  1. Colleghi un solo modulo (ancora su 0x50) al bus.
  2. Imposti il nuovo indirizzo in fase di predisposizione:

    C++
    rb_write_u8(0x50, 0x30, 0x51);    // candidate address → RAM staging
    

  3. Armi il commit:

    C++
    rb_write_u8(0x50, 0x31, 0xA5);    // ADDR_COMMIT_MAGIC
    

  4. ProblemaCMD_COMMIT_ADDR (opcode 0x30):

    C++
    rb_write_u8(0x50, 0x01, 0x30);
    

  5. Attendere≥ 700 msper la cancellazione/scrittura della flash:

    C++
    delay(700);
    

  6. ProblemaCMD_RESET (opcode 0x01) — CMD_COMMIT_ADDRfanon auto-reset:

    C++
    rb_write_u8(0x50, 0x01, 0x01);
    

  7. Attenda ~300 ms per la finestra di avvio. Non invii comandi durante questa finestra.

  8. 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");
    

  9. 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 0x30 da 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 con ERR_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 0x30 ripete 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

C++
#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);
}
Nelle librerie client

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

  1. Imposti il bit 0 diFLEET_CONFIG:
    C++
    rb_write_u8(0x50, 0x27, 0x01);    // bit0 = GC_ENABLE
    
Nota

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.

  1. (Facoltativo) impostiGROUP_IDper il partizionamento della flotta —0x00accetta tutti-chiamata:

    C++
    rb_write_u8(0x50, 0x28, 0x00);    // all-call
    

  2. Persist:

    C++
    rb_write_u8(0x50, 0x01, 0x32);    // CMD_SAVE_USER_CONFIG
    delay(700);
    

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

Layout dei byte del frame di snapshot general-call.

Text
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 a GROUP_ID del modulo).
  • — contatore di tick a 16 bit lato master, riportato nel registro GC_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)

C++
// 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.

Nelle librerie client

— 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
Text
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.

Come distinguere a runtime un modulo BASIC da un modulo STD.

Nelle librerie client

— 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

Sicurezza

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

C++
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.

Nelle librerie client

— 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