rbAmp
FR
Boutique
Docs
Mis à jour · Modifier sur GitHub

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) et GPIO22 (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 pour ct_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.
DANGER

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 :

  1. 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.
  2. venv CLI local — pour le développement et la CI. Installez avec pip install esphome dans un venv Python 3.11–3.13.

Création d'un venv (chemin CLI uniquement)

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

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

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

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

Shell
cd rbamp-esphome/example
esphome compile ui1.yaml
Sécurité

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

YAML
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"
Remarque

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

YAML
wifi_ssid: "YourNetworkName"
wifi_password: "YourPassword"
ap_password: "rbamprbamp"

Étape 3 — Compilation

Shell
# from the example/ directory with the venv active
esphome compile ui1.yaml

Ce qui se passe :

  1. ESPHome décompresse external_components et charge le paquet Python rbamp depuis ../components.
  2. 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.
  3. Le composant C++ compile et s'édite correctement. Une fin réussie ressemble à :
Text
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/ttyUSB0 ou /dev/ttyACM0.
Shell
esphome upload --device COM6 ui1.yaml             # Windows
esphome upload --device /dev/ttyUSB0 ui1.yaml     # Linux

Pour le chemin du module complémentaire HA :

  1. Ouvrez Home Assistant → Paramètres → Modules complémentaires (Add-ons) → ESPHome.
  2. Ouvrez l'interface web de l'Add-on ESPHome.
  3. 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

Lancez esphome logs pour suivre le démarrage en temps réel :

Shell
esphome logs ui1.yaml --device COM6

Un premier démarrage sain produit à peu près ces lignes (valeurs et temps approximatifs) :

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

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

  1. HA affiche une notification : Nouveaux appareils découverts.
  2. Paramètres → Appareils et services → ESPHome (ou cliquez sur la notification).
  3. Sélectionnez le nouveau nœud (par ex. rbamp-ui1).
  4. 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.
  5. 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: energy
  • state_class: total_increasing
  • unit_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

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

Ce qu'il faut faire avant le premier démarrage

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

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

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

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

Avec UI1@0x50 + I2@0x51 + I3@0x52 et fleet_gc_enable: true :

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


Source et signalements : rb-amp/rbamp-esphome · cette page dans le dépôt : docs/05_quickstart.md (v1.9.1)