05 · Avvio rapido — da zero a Home Assistant
Circa 5 minuti di lavoro pratico, più i tempi di compilazione e flash (anche la primissima compilazione scarica la toolchain ESP32, fino a ~15 minuti con una connessione lenta), portano da un ESP32 nudo e un modulo rbAmp ai sensori attivi in Home Assistant.
Di cosa avrà bisogno
Hardware
- Scheda ESP32 — funziona qualsiasi scheda con due pin I²C liberi. Gli esempi usano
GPIO21(SDA) eGPIO22(SCL) — i valori standard per il DevKitC. Se la tua scheda è diversa, modifica i numeri dei pin nel YAML. - Modulo rbAmp — qualsiasi SKU UI o I. Per un primo avvio, UI1 è la più semplice: una tensione + un canale di corrente, il minor numero di fili.
- Alimentazione a 5 V per rbAmp — il modulo funziona tra 4.5 e 5.5 V. L'alimentazione USB dell'ESP32 funziona se la scheda espone la linea a 5 V.
- Pinza TA — una pinza di corrente SCT-013 a nucleo apribile collegata al jack TA del modulo. Leggi la portata sull'etichetta (ad esempio
SCT-013-030= 30 A); ti serve perct_model:qui sotto. - Cablaggio (lato bassa tensione): VCC → +5 V, GND → GND, SDA → GPIO21, SCL → GPIO22. Per un singolo modulo non servono resistenze di pull-up esterne (quelle integrate da 4.7 kΩ sono già sulla scheda). Per lo schema completo, vedi 04_hardware.md.
- Cablaggio (lato rete): L e N della rete vanno ai morsetti L/N del modulo (per la lettura della tensione), e la pinza TA si avvolge solo attorno al conduttore L, con la freccia rivolta verso il carico. Vedere 04_hardware.md e 03_sensor_selection.md.
i morsetti L/N portano la tensione di rete. Disalimentare e bloccare il circuito prima di collegare, far eseguire i cablaggi di rete e qualsiasi lavoro all'interno di un quadro a una persona qualificata, agganciare UN solo conduttore (L) e non lasciare mai la pinza TA su un conduttore con il jack TA scollegato.
- Cavo USB dall'ESP32 al computer per il flashing.
Software
| Requisito | Nota |
|---|---|
| ESPHome ≥ 2025.3.0 | Il componente usa la sintassi moderna ota: (elenco di piattaforme) e l'hashing dell'object-id di ESPHome 2025.x. Verificato fino a ESPHome 2026.5 e successivi. |
| Python 3.11..3.13 per la CLI | Il livello PlatformIO interno di ESPHome (penv) non accetta Python 3.14. Se si usa l'Add-on HA, questo punto non si applica. |
| Home Assistant | Qualsiasi versione recente. Il rilevamento automatico funziona via mDNS (Avahi / Bonjour). |
Due percorsi di compilazione:
- Add-on ESPHome di HA (consigliato per la maggior parte degli utenti) — inserire il YAML nella cartella di configurazione dell'add-on e fare clic su Compila. Non serve alcun ambiente Python locale.
- Venv CLI locale — per sviluppo e CI. Installare con
pip install esphomein un venv Python 3.11–3.13.
Configurazione di un venv (solo percorso CLI)
# Windows PowerShell — adjust the Python path to your 3.11 / 3.13
& "C:\Python311\python.exe" -m venv .venv-esphome
.\.venv-esphome\Scripts\Activate.ps1
pip install esphome
esphome version # should print 2025.3.0 or newer
Su Linux / macOS:
python3.11 -m venv .venv-esphome
source .venv-esphome/bin/activate
pip install esphome
esphome version
Passo 1 — Individuare il componente
Esistono due forme per il blocco external_components — scegline una in base al tuo ambiente.
Forma A — github (predefinita, funziona nell'Add-on HA)
external_components:
- source: github://rb-amp/rbamp-esphome@v1.9.0 # pin a release tag
components: [rbamp]
refresh: 1d # 1 day for production. If you track @main during
# development, change this to `0s`, otherwise ESPHome will
# cache the copy and ignore new commits.
Questa forma è l'unica che funziona nel componente aggiuntivo ESPHome di HA (il componente aggiuntivo non ha accesso shell alle directory sorelle). È comoda anche per la CLI: non serve clonare nulla in locale.
Forma B — percorso locale (per lo sviluppo)
Se si è clonato rb-amp/rbamp-esphome e si lavora direttamente con i sorgenti del componente, puntare ESPHome a un percorso locale:
external_components:
- source:
type: local
path: /absolute/path/to/rbamp-esphome/components
components: [rbamp]
In example/ui1.yaml il blocco è già configurato per un percorso relativo (../components), che funziona quando esegui esphome compile dalla directory example/:
cd rbamp-esphome/example
esphome compile ui1.yaml
⚠ Un percorso locale non funziona nell'Add-on HA — l'Add-on tiene il YAML in /config/esphome/ senza accesso shell al resto del file system. Gli utenti dell'Add-on scelgono la forma A.
Passaggio 2 — Crea il YAML
Copia example/ui1.yaml come punto di partenza (usa il percorso locale della forma B; l'elenco qui sotto usa la forma A, quindi funziona anche nel componente aggiuntivo). Aprilo con un qualsiasi editor e inserisci le credenziali WiFi e il nome del dispositivo. Il file completo è mostrato qui sotto con commenti riga per riga.
Regola: power, energy, power_factor, reactive_power e apparent_power richiedono voltage E current dichiarati nello stesso blocco sensor: (aggiungere internal: true a un sensore che non si vuole come entità di Home Assistant); altrimenti esphome config si ferma con "power requires current to also be declared". Lo stesso vale per i sensori di canale numerati (power_1 richiede current_1 e voltage).
esphome:
name: rbamp-ui1 # node name — sets the mDNS hostname (rbamp-ui1.local)
esp32:
board: esp32dev # your board (e.g. nodemcu-32s, lolin_d32)
framework:
type: arduino # arduino or esp-idf — both work with the component
logger:
level: DEBUG # DEBUG shows I²C reads; after the first run you can use INFO
wifi:
ssid: !secret wifi_ssid # see secrets.yaml below
password: !secret wifi_password
ap:
ssid: "rbAmp UI1 Fallback" # fallback AP if the connection fails
password: !secret ap_password
captive_portal: # config page on the fallback AP
api: # Home Assistant native API on port 6053
# encryption:
# key: "BASE64_KEY" # optional — see 08_has_integrations.md
ota:
- platform: esphome # over-the-air updates
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz # IMPORTANT: 100 kHz causes intermittent NACKs from the module;
# 50 kHz reduces them ~5-10x (see 10 · troubleshooting → NACK-discipline)
scan: true # logs every I²C address found at boot
external_components:
- source: github://rb-amp/rbamp-esphome@v1.9.0 # works in the HA Add-on and the CLI
components: [rbamp]
# Working from a local clone instead? Use Form B above.
rbamp:
id: meter1
address: 0x50 # factory default address
update_interval: 60s # how often to close the period and publish sensors
# minimum 1 s (v1.3); below this → cv.Invalid
ct_model: SCT_013_030 # CT clamp model — change it to match yours
# (SCT_013_005 / _010 / _020 / _030 / _050 / _060 / _100)
sensor:
- platform: rbamp
rbamp_id: meter1
voltage:
name: "Mains Voltage" # entity ID in HA: sensor.rbamp_ui1_mains_voltage
current:
name: "Mains Current"
power:
name: "Mains Power"
energy:
name: "Mains Energy" # state_class: total_increasing — ready for the Energy dashboard
frequency:
name: "Mains Frequency"
power_factor:
name: "Mains Power Factor"
La chiave ct_model: carica i coefficienti di fabbrica per il modello di pinza scelto. Se non hai una SCT-013-030, cambiala con il modello che hai. Per la scelta, vedi 03_sensor_selection.md.
secrets.yaml
Creare secrets.yaml nella stessa cartella del YAML (è escluso da .gitignore per impostazione predefinita in example/.gitignore, così le credenziali non finiscono in un commit):
wifi_ssid: "YourNetworkName"
wifi_password: "YourPassword"
ap_password: "rbamprbamp"
Passaggio 3 — Compilazione
# from the example/ directory with the venv active
esphome compile ui1.yaml
Che cosa succede:
- ESPHome estrae
external_componentse carica il pacchetto Pythonrbampda../components. - PlatformIO scarica la piattaforma ESP32 alla prima esecuzione (~1–2 GB, memorizzati nella cache). È il passaggio più lento — fino a 15 minuti con una connessione lenta.
- Il componente C++ compila e collega. Una conclusione riuscita appare così:
SUCCESS Took 58.71 seconds
Wrote .esphome/build/rbamp-ui1/.pioenvs/rbamp-ui1/firmware.factory.bin
Se la build fallisce con Error: Failed to install Python dependencies, l'host sta probabilmente usando Python 3.14. Usare l'Add-on HA oppure un venv con 3.11 / 3.13 (vedere "Cosa serve"). È un'incompatibilità tra il resolver uv di PlatformIO e alcuni modelli di CPU, non un bug del componente.
Passaggio 4 — Primo flash
esphome upload invia il binario via USB. Prima di tutto, individuare la porta corretta:
- Windows: Gestione dispositivi → Porte (COM e LPT). Di solito
COM3–COM9. - Linux / macOS:
ls /dev/tty*— di solito/dev/ttyUSB0o/dev/ttyACM0.
esphome upload --device COM6 ui1.yaml # Windows
esphome upload --device /dev/ttyUSB0 ui1.yaml # Linux
Per il percorso del componente aggiuntivo di HA:
- Apri Home Assistant → Impostazioni → Componenti aggiuntivi → ESPHome. [Settings → Add-ons → ESPHome]
- Aprire l'interfaccia web dell'Add-on ESPHome.
- Trovare il dispositivo (oppure fare clic su "New Device" [Nuovo dispositivo]) → Installa → Collega a questo computer. [Install]
Lo strumento di flash (esptool.py al suo interno) riavvia automaticamente l'ESP32 dopo la scrittura. Il tempo di flash completo è di solito 30–60 secondi.
Passo 5 — Cosa aspettarsi nel log di avvio
4.7 Specchi di verifica del modello TA (0x51..0x53) (riferimento API) · 8.10 Rilettura dello specchio di verifica del modello TA (controllo di sanità dopo l'associazione) (riferimento API)
Esegui esphome logs per seguire l'avvio in tempo reale:
esphome logs ui1.yaml --device COM6
Un primo avvio sano produce più o meno queste righe (valori e tempi sono approssimativi):
[D][i2c]: Found i2c device at address 0x50
[C][rbamp]: Setting up rbAmp at 0x50 ...
[C][rbamp]: Firmware version: 0x04
[C][rbamp]: Variant: UI1
[C][rbamp]: UID: 0x1A2B3C4D5E6F708192A3
[C][rbamp]: sensor_class: matches → skipped (nothing to write)
[C][rbamp]: ct_model[0]: matches → skipped (nothing to write)
[C][rbamp]: rbAmp:
[C][rbamp]: Address: 0x50
[C][rbamp]: Firmware version: 1.3
[C][rbamp]: Topology: SINGLE, channels: 1, voltage: yes
[C][rbamp]: Bidirectional: NO
[C][rbamp]: Wh persistence: NVS every 300s
[C][component]: Setup rbamp took 67ms
La riga i2c: scan: true compare prima delle righe del componente e conferma che il modulo è fisicamente visibile sul bus. Se manca Found i2c device at address 0x50, vedere la sezione "Cosa fare se" qui sotto.
Entro un update_interval (60 s di default) compaiono le pubblicazioni dei sensori — attendi circa 60 s, oppure imposta update_interval: 5s durante i test:
[D][sensor]: 'Mains Voltage': Sending state 226.70 V
[D][sensor]: 'Mains Current': Sending state 0.755 A
[D][sensor]: 'Mains Power': Sending state 92.80 W
[D][sensor]: 'Mains Power Factor': Sending state 0.542
[D][sensor]: 'Mains Frequency': Sending state 50.0 Hz
[D][sensor]: 'Mains Energy': Sending state 0.026 Wh
Valori di riferimento sul banco con uno SKU UI1 e un carico induttivo: U ≈ 225 V, I ≈ 0.78 A, P ≈ 110 W, PF ≈ 0.62. I valori esatti dipendono dal carico collegato.
Passaggio 6 — Rilevamento in Home Assistant
mDNS (automatico)
HA trova da sé i nodi ESPHome con un blocco api: configurato nello stesso segmento di rete locale. Entro 30–60 secondi dal primo avvio dell'ESP32:
- HA mostra una notifica: Nuovi dispositivi rilevati.
- Impostazioni → Dispositivi e servizi → ESPHome (oppure fare clic sulla notifica). [Settings → Devices & Services → ESPHome]
- Seleziona il nuovo nodo (ad es.
rbamp-ui1). - Inserisci l'IP locale del dispositivo (visibile nei log come
[I][wifi]: IP: 192.168.0.xxx) se HA non lo ha trovato da solo. - Add.
Tutte le entità sensore si registrano subito. L'ID entità segue lo schema sensor. (spazi sostituiti con trattini bassi, tutto minuscolo). Per il YAML sopra: sensor.rbamp_ui1_mains_voltage, sensor.rbamp_ui1_mains_energy, e così via.
Aggiunta manuale (se mDNS è bloccato)
Impostazioni → Dispositivi e servizi → Aggiungi integrazione → ESPHome → indirizzo IP e porta API (6053). Se in api: encryption: key: è impostata una chiave, inseriscila quando richiesto. [Settings → Devices & Services → Add Integration → ESPHome]
Dashboard Energia
Il sensore energy è già configurato per Energia di HA:
device_class: energystate_class: total_increasingunit_of_measurement: Wh
Impostazioni → Dashboard → Energia → Aggiungi consumo → selezionare "Mains Energy". HA inizia subito a tracciare il consumo cumulativo.
Passaggio 7 — Scalare a una flotta (installazione canonica multi-modulo)
Un singolo UI1 sulla rete fornisce i totali dell'intera abitazione. Per una suddivisione per sotto-derivazioni (caldaia, climatizzatore, auto elettrica), aggiungere moduli I2/I3 sullo stesso bus I²C. Questo è il deployment canonico all'80% (vedere 01_overview.md).
Estensione minima del YAML
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz
scan: true
# external_components: ... as in Step 1
rbamp:
- id: mains_meter
address: 0x50
sensor_class: SCT_013
ct_model: SCT_013_030
fleet_gc_enable: true # NEW v1.3 — capability-gated GC snapshot
group_id: 1 # cluster id
- id: boiler_meter # I2 sub-meter, address 0x51 after provisioning
address: 0x51
sensor_class: SCT_013
ct_models: [SCT_013_020, SCT_013_010] # 20A boiler + 10A washing machine
fleet_gc_enable: true
group_id: 1 # same group → synchronized snapshots
- id: panel_meter # I3 sub-meter, address 0x52
address: 0x52
sensor_class: SCT_013
ct_models: [SCT_013_005, SCT_013_030, SCT_013_020] # mixed CT sizes
fleet_gc_enable: true
group_id: 1
sensor:
- platform: rbamp
rbamp_id: mains_meter
voltage: { name: "Mains Voltage" }
current: { name: "Mains Current" }
power: { name: "Mains Power" }
energy: { name: "Mains Energy" }
- platform: rbamp
rbamp_id: boiler_meter
current: { name: "Boiler Current" } # SCT_013_020 channel 0
current_1: { name: "Washer Current" } # SCT_013_010 channel 1
- platform: rbamp
rbamp_id: panel_meter
current: { name: "Lighting Current" } # SCT_013_005 channel 0
current_1: { name: "Appliances Current" } # SCT_013_030 channel 1
current_2: { name: "Sub-panel Current" } # SCT_013_020 channel 2
Cosa fare prima del primo avvio
-
Provisioning degli indirizzi — tutti i moduli escono di fabbrica a 0x50. Vedere 04_hardware.md Commit dell'indirizzo in due fasi per la procedura sequenziale (un solo vergine sul bus alla volta).
-
Pull-up — segui la tabella dei pull-up in 04_hardware.md Bus multi-modulo. Per 3 moduli: taglia i ponticelli dei pull-up su tutti e aggiungi una coppia esterna da 2.7–3.3 kΩ (SDA e SCL verso 3.3 V) sull'ESP32.
-
Alimentazione esterna a 5 V — 3 moduli × ~15 mA = ~45 mA + ESP32 ~200 mA. Il VBUS USB di solito basta per la messa in servizio; per un deployment in produzione usare un SMPS separato a 5 V.
Cosa aspettarsi nel log dopo l'avvio
[D][i2c]: Found i2c device at address 0x50
[D][i2c]: Found i2c device at address 0x51
[D][i2c]: Found i2c device at address 0x52
[C][rbamp]: rbAmp 0x50: variant=UI1, fleet_gc=on, group=1
[C][rbamp]: rbAmp 0x51: variant=I2, fleet_gc=on, group=1
[C][rbamp]: rbAmp 0x52: variant=I3, fleet_gc=on, group=1
[I][rbamp]: GC latch enabled fleet-wide: 3 modules in group 1
Verifica di sincronizzazione
6.3 Snapshot broadcast GC — sincronizzazione di flotta opt-in (api-reference) · 8.4 Snapshot broadcast GC + ripiego witness (api-reference)
Con UI1@0x50 + I2@0x51 + I3@0x52 e fleet_gc_enable: true:
[D][rbamp]: GC frame emit: group=1, tick=42, all 3 modules ACK'd
[D][rbamp]: check_sync(tick=42) → 3/3 in_sync ; fleet in sync
Vedere la sezione Fleet di 09_api_reference.md per l'emissione programmatica e la verifica di sincronizzazione tramite i servizi API nativi.
Cosa fare se
| Sintomo | Causa probabile | Che cosa fare |
|---|---|---|
Manca Found i2c device at address 0x50 |
Modulo non alimentato o cablato male, pin GPIO sbagliati | Verificare VCC (dovrebbe essere 4.5–5.0 V), GND, SDA / SCL; assicurarsi che i ponticelli di pull-up sul modulo siano integri |
Probe failed at 0x50 nei log |
Il modulo è visibile nella scansione ma non risponde alle letture dei registri | Verificare frequency: 50kHz nel YAML; assicurarsi che il modulo non sia nel mezzo di una scrittura flash (~700 ms) |
| I sensori leggono 0 o NaN | Il modulo è ancora in avvio; per i primi ~250 ms dopo l'accensione i registri leggono 0 | Attendere il primo ciclo di update_interval; il componente salta la lettura finché il registro di stato non è pronto |
| HA non trova il dispositivo | mDNS bloccato dal router / VLAN; blocco api: mancante |
Aggiungi api:; prova l'aggiunta manuale tramite IP |
Avviso update() ha impiegato 406ms |
Il componente è passato dal percorso di lettura a raffica v1.3 alle letture per singolo registro (4 transazioni × 9 float a 50 kHz) | Non è un problema; verificare che la versione del firmware sia 0x04 e che i pull-up del bus seguano la tabella di 04_hardware.md (tirati a 3.3 V puliti) — un ciclo v1.3 sano resta sotto 30 ms |
| Ripiego sulla modalità access point | SSID / password errati; access point fuori portata | Controlla secrets.yaml; avvicinati all'access point; 2.4 GHz vs 5 GHz |
Per i problemi non elencati qui, vedi 10_troubleshooting.md.
Cosa c'è dopo
- Configurazione a tre canali: 06_examples.md — YAML di UI3 con tre canali di corrente indipendenti e tutte le grandezze derivate.
- Più moduli sullo stesso bus: 06_examples.md — la sezione multi-modulo.
- Approfondimento su Energia di HA: 08_has_integrations.md.
- Integrazioni DIY (Grafana, MQTT, automazioni): 07_diy_integrations.md.
- Riferimento completo della configurazione: 09_api_reference.md.
- Diagnosi dei problemi durante la prima esecuzione con rbAmp: 10_troubleshooting.md.
Fonte e segnalazioni: rb-amp/rbamp-esphome · questa pagina nel repository: docs/05_quickstart.md (v1.9.1)