04 · Cablaggio
Questo capitolo descrive il cablaggio fisico del modulo rbAmp alle schede della famiglia ESP32: piedinatura lato BT, requisiti di alimentazione, compatibilità dei livelli di tensione I²C, lunghezza del bus e i pin predefiniti standard per i 7 chip ESP32 supportati (esp32, esp32s2, esp32s3, esp32c2, esp32c3, esp32c6, esp32h2).
Il modulo stesso è tutto a bassa tensione; sulle varianti UI* il riferimento di rete singolo è una derivazione L–N dietro un partitore isolato galvanicamente. Il lato LV (alimentazione + I²C + DRDY facoltativo) è descritto per primo; il collegamento di rete e CT è in Collegamento di rete e CT più sotto.
Pinout lato LV
| Pin | Segnale | Scopo |
|---|---|---|
VCC |
+5 V (4.5..5.5 V) | Alimentazione del modulo; minimo 4.5 V per il corretto funzionamento |
GND |
Terra | Condiviso con il master — obbligatorio |
SDA |
I²C SDA | Dati I²C |
SCL |
I²C SCL | Clock I²C |
DRDY |
Dati pronti (opzionale) | Drain aperto, impulso LOW di ~10 µs ogni ~100 ms |
Potenza
Parametri VCC
- Tensione nominale: 5 V DC
- Intervallo ammesso: da 4.5 a 5.5 V
- Assorbimento di corrente: ~15 mA tipici, ~25 mA di picco durante le scritture in flash
- Ripple: < 50 mV picco-picco (per la precisione di misura)
Il modulo porta un regolatore di bordo, un filtro RC, condensatori ceramici e una perlina di ferrite — non serve alcun filtraggio aggiuntivo da parte dell'utente. Il modulo può essere alimentato dalla linea +5V o +5V0 di qualsiasi scheda DevKitC (alimentata da USB-5V).
Compatibilità dei livelli di tensione I²C
-
SDA/SCLfunzionano con logica a 3.3 V (i pull-up integrati portano le linee a 3.3 V). -
Le linee sono tolleranti a 5 V, ma la famiglia ESP32 è comunque a 3.3 V — non servono convertitori di livello.
-
Il driver
i2c_masterdi ESP-IDF usa uscite open-drain sui GPIO — compatibili con i pull-up integrati del modulo.
Comportamento all'accensione
- Avvio a freddo: ~250 ms fino al primo risultato valido.
- Dopo un reset (software o brown-out): ~250 ms per riprendersi.
- Fino al primo risultato valido i registri leggono
0, con il flagDATA_VALID= 0.
Il componente attende che il modulo sia pronto dentro rbamp_begin(dev) stesso — il codice utente chiama semplicemente rbamp_begin() e prosegue.
Isolamento
Il modulo stesso è interamente a bassa tensione — non c'è alcun circuito di misura ad alta tensione su di esso. La corrente è letta da una pinza CT che si accoppia magneticamente dall'esterno del conduttore isolato, senza contatto elettrico con il filo di rete. Sulle varianti a rilevamento di tensione (UI) il riferimento di rete singolo è il morsetto L–N, che alimenta un partitore di rilevamento isolato galvanicamente*; le varianti solo amperometriche non hanno alcuna connessione di rete.
Consequences:
- Il
GNDdel modulo non è collegato alla linea di rete né al neutro. - I pin BT si collegano all'ESP32 senza un riferimento di rete: la pinza si accoppia magneticamente e la presa di tensione UI sta dietro un partitore isolato galvanicamente. Questo non sostituisce le precauzioni per il cablaggio di rete della sezione successiva.
⚠ Non aprire l'involucro del modulo — questo invalida la calibrazione di fabbrica.
Collegamento di rete e CT
⚠ La tensione di rete può uccidere. Scolleghi e blocchi il circuito prima di collegare i terminali L/N o di montare la pinza; faccia eseguire il cablaggio di rete e ogni lavoro dentro un quadro da una persona qualificata. Agganci UN solo conduttore (L) — mai l'intero cavo. Protegga la derivazione L con un fusibile secondo le norme locali (obbligatorio, fino a 0.1 A; un filo AWG26–22 è sufficiente — il sensore di tensione assorbe pochissima corrente).
-
Tensione (solo varianti UI): il modulo misura la tensione dal collegamento L/N sul lato rete: il PCB espone i terminali
L(linea) eN(neutro), e la polarità conta per il segno della potenza. Le varianti I (I1/I2/I3) non hanno ingresso di tensione. -
Corrente: la pinza SCT-013 si inserisce nel jack CT da 3.5 mm del modulo (con chiave per la polarità corretta; ogni jack sulla scheda è etichettato con il suo canale,
I0,I1, …) e si chiude attorno al conduttore di linea (L). La freccia sul corpo della pinza punta nella direzione della corrente verso il carico. Una pinza invertita dà unaPnegativa su un carico consumatore. -
Stringa il conduttore di linea, non il neutro e non entrambi i conduttori insieme.
- Non apra il contenitore del modulo — annullerebbe la calibrazione di fabbrica. I ponticelli di pull-up citati sotto si trovano sul lato inferiore della scheda; segua le istruzioni del modulo per raggiungerli.
Resistenze di pull-up integrate — a bordo
Importante: ogni modulo rbAmp ha resistenze di pull-up da 4.7 kΩ integrate su SDA e SCL verso 3.3 V. Per un singolo modulo sul bus non servono pull-up esterni — colleghi l'ESP32 direttamente.
Il i2c_master_bus_config_t di ESP-IDF permette anche di abilitare i pull-up GPIO interni tramite flags.enable_internal_pullup = true. Sono deboli (~50 kΩ sull'ESP32) e lavorano in parallelo con i 4.7 kΩ esterni del modulo — la combinazione dà un effettivo di ~4.4 kΩ, accettabile. Per le installazioni di produzione, preferisca affidarsi ai 4.7 kΩ esterni del modulo; i pull-up GPIO interni sono facoltativi con quelli del modulo e servono soprattutto per prove su banco senza un modulo a disposizione (per esempio quando si verifica solo una scansione del bus).
Quando disattivare i pull-up integrati
Se ci sono più moduli rbAmp sul bus (o altri dispositivi I²C con i propri pull-up), collegarli in parallelo dà una resistenza effettiva troppo bassa, il che:
- Aumenta l'assorbimento di corrente del bus
- Potrebbe superare la massima corrente di sink dello stadio di uscita del master I²C
- Aggiunge capacità capacitiva su un bus lungo, con scarso beneficio per l'immunità al rumore
Soluzione: sul lato inferiore della scheda di ogni modulo, accanto alle resistenze di pull-up, ci sono ponticelli di giunzione (serigrafia Pull-Up). Li tagli con una lama affilata:
-
Lasci attivi i pull-up solo su un solo modulo (oppure li sposti in un unico punto vicino all'ESP32).
-
Tagliare i ponticelli sugli altri moduli rimanenti.
Regola pratica
I valori esterni sono valori consigliati (calcolati dalla specifica I²C: corrente di assorbimento ≤ 3 mA a 3.3 V, capacità del bus ≤ 400 pF). Collegare i pull-up esterni a 3.3 V (il livello logico del bus), non all'alimentazione VCC a 5 V.
: misuri la resistenza tra SDA e la linea 3V3 con tutti i dispositivi non alimentati. Deve trovarsi nell'intervallo da 1.5 a 4.7 kΩ. Se è più bassa — troppi pull-up attivi in parallelo.
Parametri del bus I²C
- Indirizzo predefinito:
0x50(7 bit) - Intervallo di indirizzi:
0x08..0x77(riassegnabile in fabbrica) -
Velocità consigliata su ESP32: 50 kHz (vedi la sezione sulla disciplina di retry+sanità qui sotto)
-
Auto-incremento del puntatore: solo in lettura. Una lettura a raffica
restituisce N byte consecutivi a partire da+ N byte addr(auto-incremento). Le scritture NON sono auto-incrementate: una scrittura a rafficascrive solo il primo byte, il resto viene scartato. I registri multi-byte vengono scritti byte per byte — una transazione separata da un byte per ogni indirizzo. Per i dettagli vedi 09 · Riferimento API, la sezione "Scritture multi-byte".+ N byte
Lunghezza del bus
L'I²C è un bus corto (~15 cm di default). Molti utenti collegano i moduli con cavetti di bassa qualità, che captano molto rumore e perdono molti trasferimenti — da qui il limite breve. Topologie consigliate per rbAmp:
| Cavo | Lunghezza massima | Velocità |
|---|---|---|
| JST standard / piatto a 4 conduttori | fino a 0.15 m | 100 kHz |
| Doppino intrecciato UTP (cat-5/5e/6) — SDA+GND e SCL+GND in coppie separate | fino a 1 m | 100 kHz |
| Coppia intrecciata + buffer I²C (PCA9515 / TCA9617) | fino a 3 m | 100 kHz |
| Bus differenziale (PCA9615 / LTC4332) | fino a 100 m | 100 kHz |
Le lunghezze sopra sono state verificate a 100 kHz. La velocità di bus predefinita del componente è 50 kHz (vedi «Schema di NACK di riferimento di ESP32» più sotto), più tollerante di cavi più lunghi; mantenga 50 kHz e non superi queste lunghezze.
Per lunghezze oltre 0.15 m è obbligatorio un doppino intrecciato: SDA e SCL devono stare in coppie diverse, ciascuna con la propria massa. SDA e SCL nella stessa coppia creano un accoppiamento capacitivo incrociato che distorce i fronti.
⚠ All'interno di un quadro elettrico, schermi il cavo I2C. Campi magnetici intensi vicino ai conduttori di rete, ai contattori e ai trasformatori inducono rumore in un cavo non schermato. Tenga il cavo il più corto possibile e lontano dai cablaggi di rete.
Bus multimodulo — la topologia principale
Il caso d'uso canonico della libreria è più moduli rbAmp su un unico bus I²C, gestiti da un ESP32 tramite un handle della flotta. Tutte le regole e le ottimizzazioni qui sotto sono pensate proprio per questa topologia; un singolo modulo è un caso particolare (lo stesso handle, ma le chiamate di flotta diventano banali).
Installazioni tipiche
| Scenario | Configurazione | Numero di moduli |
|---|---|---|
| 80% canonico: contatore principale di casa + sotto-contatori | 1× UI1 (principale, energia di rete) + 3-6× UI1 (carichi; potenza e Wh richiedono una variante UI) | 4-7 |
| Sottoquadro con suddivisione della corrente | 1× UI1 (principale) + 1-2× I2/I3 (corrente per circuito) | 3-5 |
| Sotto-misura industriale | 1× UI1 (principale) + N× I2/I3 (per macchina, suddivisione della corrente) | fino a ~16 |
Vincoli elettrici
- Numero di moduli: fino a ~16 (capacità totale del bus ≤ 400 pF a 100 kHz).
- Indirizzi: ogni modulo ha il proprio indirizzo a 7 bit (intervallo
0x08..0x77). Tutti i moduli escono di fabbrica su0x50— li riassegni uno alla volta prima di collegarli in parallelo (vedi sotto il commit in due fasi e il provisioning tramiterbamp_provision()). - Pull-up (importante per un bus di flotta): i pull-up interni dell'ESP32 (~45 kΩ) sono troppo deboli per un bus multimodulo con tracciati lunghi e rumore. Per un funzionamento affidabile servono pull-up esterni (2.7…3.3 kΩ per 3 moduli, di meno per bus più grandi — vedi la tabella sopra) verso 3.3 V su SCL/SDA in un unico punto del bus + da 4 moduli in su (oppure già su un bus più lungo di 15 cm) i pull-up integrati vengono staccati su tutti i moduli tranne uno — con 2–3 moduli su un bus fino a 15 cm li lasci stare, quel caso è misurato (oppure staccati su tutti e tenuti solo quelli esterni). Questo fa parte della mitigazione a tre livelli contro il blocco del bus su un bus marginale — vedi 10 · Risoluzione dei problemi.
Indirizzamento — messa in servizio e scambio sul campo
L'indirizzo di fabbrica predefinito è 0x50. Ogni modulo nuovo o sostitutivo passa per la messa in servizio (una volta): riassegnazione da 0x50 a un indirizzo di lavoro + salvataggio facoltativo della configurazione (modello CT, group_id, etichetta) in flash.
In codice è un'unica chiamata — rbamp_provision(bus, desired_addr, save_config, &dev). Verifica che ci sia davvero un solo modulo vergine su 0x50 sul bus, lo riassegna tramite un commit in due fasi (vedi sotto), salva facoltativamente la configurazione utente e restituisce un handle pronto.
⚠ Disciplina di messa in servizio (OBBLIGATORIA): deve esserci esattamente un modulo vergine (su 0x50) sul bus nel momento in cui viene chiamato rbamp_provision(). Se due moduli allo stesso indirizzo rispondono su I²C contemporaneamente — una collisione nella fase dati, il comportamento è indefinito e non c'è modo di distinguerli (open-drain a AND cablato). Percorso di ripristino: spegnere e riaccendere, passare fisicamente a un avvio con un solo modulo, mettere in servizio uno alla volta, poi collegare gli altri. Veda 10 · Risoluzione dei problemi, sezione «Messa in servizio fallita / conflitto di indirizzo».
Se non ha un handle di flotta e rinomina manualmente tramite rbamp_prepare_address_change() + rbamp_commit_address_change() (la forma a basso livello) — la disciplina è esattamente la stessa: un vergine alla volta.
Commit in due fasi per un cambio di indirizzo
Il firmware supporta un cambio di indirizzo in modalità produzione tramite una sequenza in due fasi:
1. write candidate_addr → REG_I2C_ADDRESS (0x30, in RAM)
2. write 0xA5 → REG_ADDR_COMMIT_MAGIC (0x31, armed)
3. issue CMD_COMMIT_ADDR (opcode 0x30 in REG_COMMAND)
4. issue CMD_RESET (0x01)
5. wait ~300 ms; the new address is active
Il componente racchiude questo in rbamp_prepare_address_change() / rbamp_commit_address_change() — vedi 09 · Riferimento API. La persistenza è confermata solo dopo un reset (vedi il riquadro «Modalità produzione vs fabbrica» in 03_sensor_selection.md).
Budget energetico del bus — quanti moduli può sostenere la sua frequenza di polling
Su un bus a 50 kHz una singola transazione di lettura di un registro ≈ 200-400 µs (dipende dal driver del MCU). Un blocco RT completo di un canale (U + I + P + PF) = 4 float = 16 byte + 4 fasi di indirizzo ≈ 5-8 ms per canale.
| Configurazione | Bus per ciclo | A 50 kHz | Frequenza massima di polling |
|---|---|---|---|
| 1× UI1, blocco RT | ~5 ms | < 5 ms | 100+ Hz (ma il modulo aggiorna a 10 Hz) |
| 1× I3, blocco RT + periodo | ~25 ms | ~25 ms | fino a 10 Hz |
| 5× UI1, blocco RT | ~25 ms | ~25 ms | fino a 10 Hz |
| 16× I3, RT + periodo | ~400 ms | 400 ms > 100 ms | non riesce a tenere il passo con il modulo (10 Hz); ~2 Hz al meglio |
I numeri qui sopra sono stime e dipendono dall'MCU host e dal driver.
Regola: a 50 kHz i limiti comodi sono 8-10× I3 o 15-16× UI1 con polling a 5 Hz (ogni secondo finestra del modulo), e circa la metà di questo a 10 Hz pieni. Oltre:
- Riduca la frequenza di polling (1 Hz = 10× di margine).
- Passi a 100 kHz con ritentativo (si attendano NACK frequenti e si affidi al ritentativo).
- Usi il pin
DRDYper l'asincrono — non interroghi i moduli non ancora pronti.
Sincronizzazione del periodo — sincronia dei periodi per una sincronia stretta
Per la tariffazione tutti i moduli devono prendere lo snapshot sullo stesso intervallo di tempo. Due strategie:
Strategia 1 — snapshot sequenziale + assestamento condiviso (funziona su qualsiasi firmware):
/* Phase 1: sequential snapshot */
for (int i = 0; i < n; i++) {
rbamp_latch_period(devs[i]);
}
/* Phase 2: shared settle (≥ 50 ms for the snapshot + ~1 commit cycle for witness) */
vTaskDelay(pdMS_TO_TICKS(50));
/* Phase 3: read snapshots with skip_latch=true */
rbamp_period_snapshot_t snaps[n];
for (int i = 0; i < n; i++) {
rbamp_read_period_snapshot(devs[i], &snaps[i], 0, /*skip_latch=*/true);
}
Sfasamento tra moduli: 16 moduli × ~1 ms/snapshot = ~16 ms rispetto a un periodo di 60 secondi → 0.027%. Trascurabile.
Strategia 2 — snapshot broadcast General-Call (richiede l'abilitazione):
Tutti i moduli ricevono lo snapshot in un unico frame I²C all'indirizzo 0x00:
addr=0x00 | A5 27 (5 bytes)
Sfasamento = 0 (atomico). Pre-configurazione:
- Su ogni modulo abiliti
REG_FLEET_CONFIG.bit0 = 1tramiteCMD_SAVE_USER_CONFIG. CMD_RESET— la ricezione GC viene attivata all'avvio.- Dopo il reset il master invia il frame da 5 byte.
- Testimone: per ogni modulo atteso legga
REG_V03_PERIOD_VALID (0x07).!=1→ ripieghi sulla strategia 1.
Quando usare cosa:
- < 8 moduli: strategia 1 (più semplice, nessuna abilitazione richiesta).
- ≥ 8 moduli o sincronizzazione stretta: strategia 2.
Filtraggio per gruppo GC — un bus multi-tenant
REG_GROUP_ID (0x28) permette di avere più domini GC su un unico bus:
group = 0x00→ all-call (tutti i moduli con GC abilitato fanno lo snapshot).group = N→ solo i moduli conREG_GROUP_ID = Nprendono lo snapshot.
Esempio: un bus con 10 moduli, dove serve fare lo snapshot di 5 per la tariffa A e di 5 per la tariffa B in modo indipendente:
write REG_GROUP_ID = 1 on the 5 tariff-A modules
write REG_GROUP_ID = 2 on the 5 tariff-B modules
GC frame [A5 27 01 tl th] → only tariff A takes a snapshot
GC frame [A5 27 02 tl th] → only tariff B takes a snapshot
GC frame [A5 27 00 tl th] → all 10 take a snapshot (all-call)
Modalità di guasto su un bus multi-modulo
| Sintomo | Causa | Che cosa fare |
|---|---|---|
i2c bus scan mostra più moduli allo stesso indirizzo dopo un'aggiunta sul campo |
Il nuovo modulo su 0x50 è in conflitto con uno già indirizzato |
Riassegni il nuovo indirizzo del modulo appena flashato separatamente prima di aggiungerlo al bus |
| Un modulo inizia a dare NACK più spesso degli altri | Guasto del cavo / caduta di VCC su quel modulo | Verifichi VCC sotto carico + livelli logici |
| Il Wh di un modulo diverge in modo costante | Il timer del modulo differisce dall'orologio del master | Integri l'energia rispetto al clock master (master_dt_ms) |
| Dopo un frame GC un modulo non esegue lo snapshot | FLEET_CONFIG.bit0 = 0 o gruppo non corrispondente |
Controlli REG_FLEET_CONFIG e REG_GROUP_ID |
Note di progettazione del bus
- Clock stretching: il firmware attuale lo riduce al minimo (la finestra
__disable_irqin LatchPeriod è breve, ~µs). Lo snapshot in sé non tira significativamente SCL. Per il Raspberry Pi BCM283x (un noto bug hardware di clock stretching): applichi la cautela standard — 50 kHz + ritentativo sono già raccomandati. - Lunghezza del bus con più di 4 moduli: anche su un doppino intrecciato la capacità effettiva cresce linearmente con il numero. Consideri un buffer I²C (PCA9515) da ≥ 8 moduli + lunghezza > 1 m.
Gli scenari multi-modulo dettagliati sono in 06 · Esempi, negli scenari "Sotto-misurazione su bus condiviso" e "Snapshot broadcast GC".
Piedinatura sulla famiglia ESP32
I 7 chip elencati in cima a questo capitolo sono supportati (secondo idf_component.yml). Di seguito i pin predefiniti consigliati per I²C; per le installazioni di produzione scelga il GPIO in base al layout specifico della sua scheda.
ESP32 (originale / DevKitC / WROOM)
const i2c_master_bus_config_t bus_cfg = {
.i2c_port = I2C_NUM_0,
.sda_io_num = GPIO_NUM_21,
.scl_io_num = GPIO_NUM_22,
.clk_source = I2C_CLK_SRC_DEFAULT,
.glitch_ignore_cnt = 7,
.flags.enable_internal_pullup = true,
};
| Pin | GPIO |
|---|---|
| SDA | GPIO21 |
| SCL | GPIO22 |
| DRDY | qualsiasi GPIO libero che non sia un pin di strapping (sull'ESP32 classico eviti GPIO0/2/12/15) |
ESP32-S2
Lo stesso GPIO21/22 predefinito dell'ESP32 originale. L'S2 non ha Bluetooth — è disponibile circa 30 kB di heap in più per gli scenari TLS.
ESP32-S3
Lo S3 non ha valori I²C fissi in hardware — qualsiasi GPIO tramite la matrice. Sulla maggior parte delle schede di sviluppo WROOM-S3 GPIO8/GPIO9 sono una scelta comoda (verifichi lo schema della sua scheda: sulla N16R8 questi pin possono essere occupati dalla flash QSPI; USB-JTAG usa GPIO19/20). Adatti i campi sda_io_num / scl_io_num in i2c_master_bus_config_t:
.sda_io_num = GPIO_NUM_8,
.scl_io_num = GPIO_NUM_9,
L'S3 ha USB-OTG — può essere usato per il debug senza un chip USB-UART esterno.
ESP32-C2 / C3 / C6 / H2
Chip RISC-V single-core (C3 e C6 sono single-core; H2 è single-core con BLE+802.15.4; C2 è single-core con RAM limitata). I pin I²C non sono fissati in hardware — ecco un esempio per l'ESP32-C3 (sul C3-SuperMini GPIO5/GPIO6 sono comodi; sul C3-DevKitM-1 il USB-JTAG occupa GPIO18/19, e GPIO8/9 sono di strapping):
const i2c_master_bus_config_t bus_cfg = {
.i2c_port = I2C_NUM_0,
.sda_io_num = GPIO_NUM_5,
.scl_io_num = GPIO_NUM_6,
.clk_source = I2C_CLK_SRC_DEFAULT,
.glitch_ignore_cnt = 7,
.flags.enable_internal_pullup = true,
};
Per gli altri chip — consulti la documentazione ESP-IDF specifica del target (docs.espressif.com → ESP-IDF v5.2+ → il suo chip → API reference → peripherals → I2C).
ESP32-P4 — non è un target supportato
L'ESP32-P4 non è nell'elenco dei target supportati: il supporto a P4 richiede ESP-IDF v5.3+, mentre il minimo del componente è v5.2 (una build v5.2 per esp32p4 fallirebbe con «target esp32p4 not in idf»).
Schema di NACK dell'ESP32 di base — velocità di bus 50 kHz
Con il driver i2c_master di ESP-IDF v5, rbAmp mostra NACK frequenti a 100 kHz, molti meno a 50 kHz (una caratteristica del driver lato ESP32, non dello slave). Il componente lo copre su due livelli:
-
Velocità di bus predefinita di 50 kHz tramite il Kconfig
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000. Il componente richiede questa frequenza quando aggiunge il proprio handle del dispositivo al bus che lei crea. -
Ritentativo per byte —
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=3× pausa di 5 ms. A 50 kHz il tasso residuo di errore è < 0.8%.
Se necessario, sovrascriva tramite idf.py menuconfig:
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=5 # for dense workloads
CONFIG_RBAMP_NACK_RETRY_GAP_MS=5
CONFIG_RBAMP_I2C_TIMEOUT_MS=200
Per approfondire la diagnosi dei problemi a livello di bus — vedi 10 · Risoluzione dei problemi.
DATA_READY (DRDY)
Un pin opzionale per l'ottimizzazione del polling. Se l'applicazione interroga il modulo non più spesso di una volta ogni 100 ms — DRDY può restare non collegato.
Parametri elettrici
- Tipo di uscita: drain aperto (nessuna pull-up attiva verso VCC)
-
Livello di riposo: ALTO (richiede un pull-up sul lato master — un
gpio_pullup_en()interno oppure una resistenza esterna; si consigliano 10 kΩ verso 3.3 V) -
Impulso di pronto: BASSO per ~10 µs dopo che i registri RT sono stati aggiornati con dati freschi
-
Frequenza degli impulsi: ~10 Hz (un impulso per finestra RT di ~100 ms)
Semantica
Un fronte di discesa su DRDY garantisce che tutti i registri RT siano sincronizzati e pubblicati (il firmware li aggiorna in modo atomico nell'ISR prima di abbassare il pin). Dopo il fronte di discesa il master può leggere il blocco RT senza rischio di campione spezzato.
Pattern a interruzione — semaforo FreeRTOS
ESP-IDF offre un modello pulito: un ISR in IRAM alza un semaforo binario, e un task FreeRTOS separato attende il semaforo e legge RT.
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "freertos/semphr.h"
#include "driver/gpio.h"
#define DRDY_GPIO GPIO_NUM_4 /* a free GPIO; do not use
* GPIO0/2/12/15 — strapping pins
* (ESP32 classic), they can disrupt boot
* if the open-drain DRDY goes LOW
* during reset */
static SemaphoreHandle_t drdy_sem;
static void IRAM_ATTR drdy_isr_handler(void *arg) {
BaseType_t hi_task_woken = pdFALSE;
xSemaphoreGiveFromISR(drdy_sem, &hi_task_woken);
if (hi_task_woken) portYIELD_FROM_ISR();
}
void bidir_task(void *arg) {
rbamp_handle_t dev = arg;
while (1) {
if (xSemaphoreTake(drdy_sem, portMAX_DELAY) == pdTRUE) {
float p;
if (rbamp_read_power(dev, 0, &p) == ESP_OK) {
/* integrate + publish */
}
}
}
}
void app_main(void) {
/* ...rbamp_new + rbamp_begin... */
drdy_sem = xSemaphoreCreateBinary();
/* The ISR service is installed ONCE for the whole project — if another
* component (LCD, encoder, anything) has already installed it,
* gpio_install_isr_service() returns ESP_ERR_INVALID_STATE.
* This is normal, do not fail on it. ESP_INTR_FLAG_IRAM keeps the
* ISR dispatcher in IRAM — important for the single-core C3/C6/H2/S2,
* where non-IRAM code is unavailable while the flash cache is disabled. */
esp_err_t err = gpio_install_isr_service(ESP_INTR_FLAG_IRAM);
if (err != ESP_OK && err != ESP_ERR_INVALID_STATE) {
ESP_ERROR_CHECK(err);
}
gpio_config_t io_cfg = {
.pin_bit_mask = 1ULL << DRDY_GPIO,
.mode = GPIO_MODE_INPUT,
.pull_up_en = GPIO_PULLUP_ENABLE,
.pull_down_en = GPIO_PULLDOWN_DISABLE,
.intr_type = GPIO_INTR_NEGEDGE,
};
gpio_config(&io_cfg);
gpio_isr_handler_add(DRDY_GPIO, drdy_isr_handler, NULL);
/* Priority 6 — above idle (0), below WiFi (23) and the standard
* MQTT (5+). 4096 bytes of stack are enough for rbamp_read_* +
* ESP_LOG; if you add an MQTT publish right in this task —
* raise it to 6144. On dual-core ESP32/S3, for a clean
* separation from the WiFi task (usually core 0), you can pin
* this task to core 1: xTaskCreatePinnedToCore(..., 1).
* On the single-core C3/C6/H2/S2 — keep xTaskCreate. */
xTaskCreate(bidir_task, "bidir", 4096, dev, 6, NULL);
}
DRDY è facoltativo — il polling a qualsiasi velocità ≤ 10 Hz funziona anche senza. Il componente non dipende da DRDY in nessuno dei suoi percorsi.
Collegamenti
- 05 · Guida rapida — il suo primo progetto funzionante
-
06 · Esempi — scenari di lavoro (incluso il bus multi-modulo)
-
09 · Riferimento API — la sezione "Simboli Kconfig" per la configurazione dettagliata dei parametri I²C
-
10 · Risoluzione dei problemi — debug a livello di bus, schema di NACK, disciplina di retry+sanità
Fonte e segnalazioni: rb-amp/rbamp-esp-idf · questa pagina nel repository: docs/04_hardware.md (v1.7.3)