05 · Démarrage rapide — de zéro à Home Assistant
Environ 5 minutes de travail pratique, plus le temps de compilation et de flash (la toute première compilation télécharge aussi la chaîne d'outils ESP32, jusqu'à ~15 minutes sur une connexion lente), vous amène d'un ESP32 nu et d'un module rbAmp à des capteurs en direct dans Home Assistant.
Ce dont vous avez besoin
Matériel
- Carte ESP32 — toute carte disposant de deux broches I²C libres convient. Les exemples utilisent
GPIO21(SDA) etGPIO22(SCL) — les valeurs standard du DevKitC. Si votre carte diffère, ajustez les numéros de broches dans le YAML. - Module rbAmp — toute référence UI ou I. Pour un premier essai, UI1 est le plus simple : une tension, un canal de courant, le moins de fils.
- Alimentation 5 V pour rbAmp — le module fonctionne en 4.5..5.5 V. L'alimentation USB de l'ESP32 convient si la carte expose le rail 5 V.
- Pince CT — une pince SCT-013 à noyau fendu branchée sur la prise CT du module. Lisez son calibre sur l'étiquette (par exemple
SCT-013-030= 30 A) ; vous en aurez besoin pourct_model:ci-dessous. - Câblage (côté basse tension) : VCC → +5 V, GND → GND, SDA → GPIO21, SCL → GPIO22. Des résistances de tirage externes ne sont pas nécessaires pour un module unique (les 4.7 kΩ intégrées sont déjà présentes sur la carte). Pour le schéma complet, voir 04_hardware.md.
- Câblage (côté secteur) : le L et le N du secteur vont aux bornes L/N du module (pour la lecture de tension), et la pince CT entoure le seul conducteur L, la flèche pointant vers la charge. Voir 04_hardware.md et 03_sensor_selection.md.
les bornes L/N portent la tension secteur. Mettez le circuit hors tension et verrouillez-le avant de connecter, faites faire le câblage secteur et tout travail à l'intérieur d'un tableau par une personne qualifiée, ne serrez qu'UN conducteur (L), et ne laissez jamais la pince CT sur un conducteur avec la prise CT débranchée.
- Câble USB de l'ESP32 vers votre ordinateur pour le flashage.
Logiciel
| Exigence | Remarque |
|---|---|
| ESPHome ≥ 2025.3.0 | Le composant utilise la syntaxe moderne ota: (liste de plateformes) et le hachage d'object-id d'ESPHome 2025.x. Vérifié jusqu'à ESPHome 2026.5 et au-delà. |
| Python 3.11..3.13 pour la CLI | La couche PlatformIO interne d'ESPHome (penv) n'accepte pas Python 3.14. Si vous utilisez l'Add-on HA, ce point ne vous concerne pas. |
| Home Assistant | Toute version récente. La découverte automatique fonctionne via mDNS (Avahi / Bonjour). |
Deux chemins de compilation :
- Add-on HA ESPHome (recommandé pour la plupart des utilisateurs) — déposez le YAML dans le répertoire de configuration de l'Add-on et cliquez sur Compile. Aucun environnement Python local requis.
- venv CLI local — pour le développement et la CI. Installez avec
pip install esphomedans un venv Python 3.11–3.13.
Création d'un venv (chemin CLI uniquement)
# 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
Sous Linux / macOS :
python3.11 -m venv .venv-esphome
source .venv-esphome/bin/activate
pip install esphome
esphome version
Étape 1 — Localiser le composant
Il existe deux formes pour le bloc external_components — choisissez-en une selon votre environnement.
Forme A — github (par défaut, fonctionne dans l'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.
Cette forme est la seule qui fonctionne dans le module complémentaire ESPHome de HA (celui-ci n'a pas d'accès shell aux répertoires voisins). Elle est aussi pratique pour la CLI : rien n'a besoin d'être cloné localement.
Forme B — chemin local (pour le développement)
Si vous avez cloné rb-amp/rbamp-esphome et travaillez directement avec les sources du composant, pointez ESPHome vers un chemin local :
external_components:
- source:
type: local
path: /absolute/path/to/rbamp-esphome/components
components: [rbamp]
Dans example/ui1.yaml, le bloc est déjà configuré pour un chemin relatif (../components), qui fonctionne lorsque vous lancez esphome compile depuis le répertoire example/ :
cd rbamp-esphome/example
esphome compile ui1.yaml
⚠ Un chemin local ne fonctionne pas dans l'Add-on HA — l'Add-on conserve le YAML dans /config/esphome/ sans accès shell au reste du système de fichiers. Les utilisateurs de l'Add-on choisissent la forme A.
Étape 2 — Créer le YAML
Copiez example/ui1.yaml comme point de départ (il utilise la forme B à chemin local ; la liste ci-dessous utilise la forme A, qui fonctionne aussi dans le module complémentaire). Ouvrez-le dans n'importe quel éditeur et renseignez vos identifiants WiFi et le nom de l'appareil. Le fichier complet est présenté ci-dessous avec des commentaires ligne par ligne.
Règle : power, energy, power_factor, reactive_power et apparent_power requièrent voltage ET current déclarés dans le même bloc sensor: (ajoutez internal: true à un capteur que vous ne voulez pas comme entité Home Assistant) ; sinon esphome config s'arrête avec « power requires current to also be declared ». Idem pour les capteurs de canaux numérotés (power_1 requiert current_1 et 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 clé ct_model: charge les coefficients d'usine du modèle de pince choisi. Si vous n'avez pas de SCT-013-030, remplacez-la par le modèle que vous possédez. Pour en savoir plus sur le choix, voir 03_sensor_selection.md.
secrets.yaml
Créez secrets.yaml dans le même répertoire que le YAML (il est exclu par .gitignore par défaut dans example/.gitignore, pour que les identifiants ne fuient pas dans un commit) :
wifi_ssid: "YourNetworkName"
wifi_password: "YourPassword"
ap_password: "rbamprbamp"
Étape 3 — Compilation
# from the example/ directory with the venv active
esphome compile ui1.yaml
Ce qui se passe :
- ESPHome décompresse
external_componentset charge le paquet Pythonrbampdepuis../components. - PlatformIO télécharge la plateforme ESP32 au premier lancement (~1–2 Go, mise en cache). C'est l'étape la plus lente — jusqu'à 15 minutes sur une connexion lente.
- Le composant C++ compile et s'édite correctement. Une fin réussie ressemble à :
SUCCESS Took 58.71 seconds
Wrote .esphome/build/rbamp-ui1/.pioenvs/rbamp-ui1/firmware.factory.bin
Si la compilation échoue avec Error: Failed to install Python dependencies, l'hôte exécute très probablement Python 3.14. Utilisez l'Add-on HA ou un venv avec 3.11 / 3.13 (voir « Ce dont vous aurez besoin »). C'est une incompatibilité entre le résolveur uv de PlatformIO et certains modèles de CPU, et non un bogue du composant.
Étape 4 — Premier flash
esphome upload flashe le binaire via USB. D'abord, repérez le bon port :
- Windows : Gestionnaire de périphériques → Ports (COM et LPT). En général
COM3–COM9. - Linux / macOS :
ls /dev/tty*— en général/dev/ttyUSB0ou/dev/ttyACM0.
esphome upload --device COM6 ui1.yaml # Windows
esphome upload --device /dev/ttyUSB0 ui1.yaml # Linux
Pour le chemin du module complémentaire HA :
- Ouvrez Home Assistant → Paramètres → Modules complémentaires (Add-ons) → ESPHome.
- Ouvrez l'interface web de l'Add-on ESPHome.
- Trouvez votre appareil (ou cliquez sur « New Device » [New Device]) → Install [Install] → Branchez sur cet ordinateur.
L'outil de flash (esptool.py embarqué) redémarre l'ESP32 automatiquement après l'écriture. Le flash complet dure généralement 30–60 secondes.
Étape 5 — Ce qu'il faut attendre dans le journal de démarrage
4.7 Miroirs de vérification du modèle de TC (0x51..0x53) (api-reference) · 8.10 Relecture du miroir de vérification du modèle de TC (contrôle après liaison) (api-reference)
Lancez esphome logs pour suivre le démarrage en temps réel :
esphome logs ui1.yaml --device COM6
Un premier démarrage sain produit à peu près ces lignes (valeurs et temps approximatifs) :
[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 ligne i2c: scan: true apparaît avant les lignes de composant et confirme que le module est physiquement visible sur le bus. Si Found i2c device at address 0x50 manque, voir la section « Que faire si » ci-dessous.
Dans un update_interval (60 s par défaut), les publications de capteurs apparaissent — attendez environ 60 s, ou définissez update_interval: 5s pendant les tests :
[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
Valeurs de référence au banc avec une référence UI1 et une charge inductive : U ≈ 225 V, I ≈ 0.78 A, P ≈ 110 W, PF ≈ 0.62. Les valeurs exactes dépendent de la charge connectée.
Étape 6 — Découverte dans Home Assistant
mDNS (automatique)
HA trouve seul les nœuds ESPHome disposant d'un bloc api: configuré, sur le même segment réseau local. Dans les 30 à 60 secondes après le premier démarrage de l'ESP32 :
- HA affiche une notification : Nouveaux appareils découverts.
- Paramètres → Appareils et services → ESPHome (ou cliquez sur la notification).
- Sélectionnez le nouveau nœud (par ex.
rbamp-ui1). - Saisissez l'IP locale de l'appareil (visible dans les journaux sous
[I][wifi]: IP: 192.168.0.xxx) si HA ne l'a pas trouvé seul. - Add.
Toutes les entités de capteurs s'enregistrent instantanément. L'entity ID suit le motif sensor. (espaces remplacés par des tirets bas, tout en minuscules). Pour le YAML ci-dessus : sensor.rbamp_ui1_mains_voltage, sensor.rbamp_ui1_mains_energy, etc.
Ajout manuel (si mDNS est bloqué)
Paramètres → Appareils et services → Ajouter une intégration → ESPHome → adresse IP et port API (6053). Si une clé est définie dans api: encryption: key:, saisissez-la lorsqu'elle est demandée.
Tableau de bord Énergie
Le capteur energy est déjà configuré pour l'énergie HA :
device_class: energystate_class: total_increasingunit_of_measurement: Wh
Paramètres → Tableaux de bord → Énergie → Ajouter une consommation → sélectionnez « Mains Energy ». HA commence immédiatement à suivre la consommation cumulée.
Étape 7 — Passage à une flotte (déploiement multi-modules canonique)
Un seul UI1 sur le secteur donne les totaux du logement. Pour une ventilation par sous-branches (chauffe-eau, climatisation, VE), ajoutez des modules I2/I3 sur le même bus I²C. C'est le déploiement canonique 80 % (voir 01_overview.md).
Extension YAML minimale
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
Ce qu'il faut faire avant le premier démarrage
-
Provisionnement d'adresse — tous les modules sortent d'usine à 0x50. Voir 04_hardware.md Validation d'adresse en deux phases pour la procédure séquentielle (un seul vierge sur le bus à la fois).
-
Tirages — suivez le tableau des tirages de 04_hardware.md Bus multi-modules. Pour 3 modules : coupez les straps de tirage sur chacun et ajoutez une paire externe de 2.7–3.3 kΩ (SDA et SCL vers 3.3 V) sur l'ESP32.
-
Alimentation 5 V externe — 3 modules × ~15 mA = ~45 mA + ESP32 ~200 mA. Le VBUS USB suffit en général pour la mise en route ; pour un déploiement en production, utilisez une alimentation à découpage 5 V séparée.
Ce qu'il faut attendre dans le journal après le démarrage
[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
Contrôle de synchronisation
6.3 Instantané de diffusion GC — synchronisation de flotte sur option (api-reference) · 8.4 Instantané de diffusion GC + repli témoin (api-reference)
Avec UI1@0x50 + I2@0x51 + I3@0x52 et 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
Voir la section Fleet de 09_api_reference.md pour l'émission programmatique et la vérification de synchronisation via les services API natifs.
Que faire si
| Symptôme | Cause probable | Que faire |
|---|---|---|
Found i2c device at address 0x50 est absent |
Module non alimenté ou mal câblé, mauvaises broches GPIO | Vérifiez VCC (doit être de 4.5–5.0 V), GND, SDA / SCL ; assurez-vous que les straps de tirage du module sont intacts |
Probe failed at 0x50 dans les journaux |
Le module est visible dans le scan mais ne répond pas aux lectures de registres | Vérifiez frequency: 50kHz dans le YAML ; assurez-vous que le module n'est pas en pleine écriture flash (~700 ms) |
| Les capteurs lisent 0 ou NaN | Le module démarre encore ; pendant les ~250 ms après la mise sous tension, les registres lisent 0 | Attendez le premier cycle update_interval ; le composant saute la lecture tant que le registre d'état n'est pas prêt |
| HA ne trouve pas l'appareil | mDNS bloqué par le routeur / VLAN ; bloc api: absent |
Ajoutez api: ; essayez l'ajout manuel par IP |
Avertissement update() took 406ms |
Le composant est revenu du chemin de lecture en rafale v1.3 vers des lectures registre par registre (4 transactions × 9 flottants à 50 kHz) | Ce n'est pas un problème ; vérifiez que la version du firmware est 0x04 et que les tirages du bus suivent le tableau de 04_hardware.md (tirés vers un 3.3 V propre) — un cycle v1.3 sain reste sous 30 ms |
| Bascule en mode point d'accès | SSID / mot de passe incorrect ; point d'accès hors de portée | Vérifiez secrets.yaml ; rapprochez-vous du point d'accès ; 2.4 GHz ou 5 GHz |
Pour les problèmes absents de cette liste, voir 10_troubleshooting.md.
Suite
- Configuration à trois canaux : 06_examples.md — YAML UI3 avec trois canaux de courant indépendants et toutes les grandeurs dérivées.
- Plusieurs modules sur un bus : 06_examples.md — la section multi-modules.
- Un approfondissement sur l'énergie HA : 08_has_integrations.md.
- Intégrations DIY (Grafana, MQTT, automatisations) : 07_diy_integrations.md.
- Référence complète de configuration : 09_api_reference.md.
- Diagnostiquer les problèmes lors de votre premier démarrage avec rbAmp : 10_troubleshooting.md.
Source et signalements : rb-amp/rbamp-esphome · cette page dans le dépôt : docs/05_quickstart.md (v1.9.1)