04 · Câblage
Ce chapitre traite du câblage physique de rbAmp sur un ESP32 : choix des GPIO, règles de tirage, bus multi-modules, alimentation, ligne DRDY facultative et provisionnement des adresses.
Déploiement canonique — une flotte multi-modules sur un bus unique. 80 % des installations sur le terrain se composent de 1× UI1 (secteur) + N× I2/I3 (sous-compteurs) sur un bus I²C d'ESP32, avec les tirages réglés selon le tableau ci-dessous. Voir 01_overview.md pour la vue d'ensemble de la flotte. Un module unique est le cas minimal, non le canon. Ce chapitre couvre les deux topologies, mais le multi-modules est signalé comme « topologie principale » dans les sections concernées.
Modules STANDARD (STD). Le câblage, les règles de tirage, l'alimentation et la ligne DRDY facultative sont identiques pour les modules BASIC et STANDARD, et le même YAML fonctionne pour les deux — le composant identifie le module connecté au démarrage. new_address: fonctionne sur les deux gammes. La synchronisation de flotte par appel général (fleet_gc_enable: / group_id:) ne s'applique qu'aux modules BASIC ; sur un module STANDARD, ces clés sont ignorées avec une ligne de journal.
DANGER : les bornes L/N transportent la tension du secteur. Mettez le circuit hors tension et verrouillez-le avant le raccordement, faites réaliser le câblage secteur et tout travail dans un tableau par une personne qualifiée, ne pincez qu'UN seul conducteur (L), et ne laissez jamais la pince CT sur un conducteur avec la prise CT débranchée.
Câble et fusible. Un câble épais n'est pas nécessaire pour la connexion de tension : AWG26–22 suffit, car le capteur de tension consomme très peu de courant. Un fusible sur la ligne L est obligatoire, calibre jusqu'à 0.1 A.
Côté secteur en un coup d'œil. Le L et le N du secteur vont aux deux bornes du module (elles fournissent la lecture de tension) ; la pince CT se branche sur la prise CT et entoure le seul conducteur L, flèche vers la charge. Tout le reste de ce chapitre concerne le côté basse tension.
Brochage côté basse tension
Le côté basse tension du module expose cinq signaux. Tous sont isolés galvaniquement du secteur — la broche GND est le GND de l'ESP32, non le neutre du secteur.
| Broche | Signal | Description |
|---|---|---|
VCC |
+4.5..+5.5 V CC | Alimentation du module. 5 V nominal ; en dessous de 4.5 V, les relevés peuvent devenir peu fiables. |
GND |
Commun | Commun avec le maître. Requis. |
SDA |
Données I²C | Logique 3.3 V ; tolère 5 V. |
SCL |
Horloge I²C | Logique 3.3 V ; tolère 5 V. |
DRDY |
Données prêtes (facultatif) | Sortie en drain ouvert. Impulsion LOW d'environ 10 µs toutes les ~100 ms après la mise à jour des registres instantanés. |
Choix des GPIO sur l'ESP32
Toute paire de GPIO prenant en charge l'I²C fonctionnera. La matrice de périphériques de l'ESP32 permet de router l'I²C vers presque toutes les broches. Contraintes pratiques :
- GPIO0 et GPIO2 sont des broches de démarrage (strapping). Un niveau bas à la mise sous tension bloque le démarrage. Ne les utilisez pas.
- GPIO 6..11 sont câblés au flash ou à la PSRAM embarqués sur la plupart des modules ESP32-WROOM. Indisponibles.
- Les GPIO 34..39 sont en entrée seule. Inadaptés à l'I²C (qui requiert une commande bidirectionnelle).
- Ne connectez aucune GPIO de l'ESP32 à une ligne de réinitialisation du module — le module se réinitialise par une commande I²C, et aucune broche de réinitialisation matérielle n'est nécessaire côté maître.
Affectations par défaut recommandées, qui fonctionnent sur la plupart des cartes ESP32-DevKitC :
| Signal | GPIO | Remarque |
|---|---|---|
| SDA | GPIO21 | Par défaut dans tous les YAML d'exemple |
| SCL | GPIO22 | Par défaut dans tous les YAML d'exemple |
| DRDY | GPIO15 | Facultatif ; toute broche capable d'entrée convient |
Si GPIO21/22 sont déjà utilisées, choisissez une autre paire valide et mettez à jour le bloc i2c: du YAML.
Câblage d'un module unique
Le câblage complet de l'ESP32 est présenté dans le schéma de référence ci-dessous.
Des résistances de tirage externes ne sont pas nécessaires pour un seul module — la carte rbAmp intègre déjà des tirages de 4.7 kΩ sur SDA et SCL vers 3.3 V.
Bus multi-modules (topologie principale)
La plupart des déploiements rbAmp sont une flotte de plusieurs modules sur un seul bus I²C d'ESP32 : un UI1 sur le secteur et plusieurs I2/I3 sur les sous-branches. C'est la topologie principale pour laquelle le composant a été conçu, et la configuration de tirage ci-dessous lui est optimisée.
Lorsque deux modules ou plus (ou d'autres appareils I²C avec leurs propres tirages) partagent un bus, leurs tirages s'ajoutent en parallèle. La résistance combinée descend sous le minimum effectif — ce qui conduit à :
- Consommation excessive sur le bus.
- Surcharge possible des sorties à drain ouvert de l'ESP32 (typiquement ≤ 3 mA sous 3.3 V).
- Charge capacitive plus élevée sur un bus long.
La face inférieure de chaque PCB rbAmp porte des straps de soudure marqués Pull-Up. Couper la piste avec une lame fine déconnecte la paire intégrée de 4.7 kΩ de ce module.
| Modules sur le bus | Configuration des tirages (pull-up) | R effective |
|---|---|---|
| 1 | Laissez la paire intégrée. Aucune externe n'est nécessaire. | ~4.7 kΩ |
| 2 | Laissez-en un seul ; coupez le second. | ~4.7 kΩ |
| 3 | Coupez tout. Une paire externe de 2.7..3.3 kΩ sur l'ESP32. | 2.7..3.3 kΩ |
| 4..6 | Coupez tout. Une paire externe de 2.2..2.7 kΩ sur l'ESP32. | 2.2..2.7 kΩ |
| 7..16 | Coupez sur tous. Une paire externe de 1.5..2.2 kΩ à l'ESP32 + une vérification de la capacité du bus (voir ci-dessous). | 1.5..2.2 kΩ |
| L'ESP32 fournit déjà des tirages | Coupez sur tous les modules. Les tirages internes de l'ESP32 (≥50 kΩ) sont faibles — un bus long a toujours besoin de 2.2..4.7 kΩ externes. | comme ci-dessus |
Les valeurs externes sont des valeurs recommandées (calculées à partir de la spécification I²C : courant absorbé ≤ 3 mA à 3.3 V, capacité du bus ≤ 400 pF). Reliez les résistances de rappel externes à 3.3 V (le niveau logique du bus), et non à l'alimentation VCC 5 V.
Logique de sélection : la résistance de tirage effective R_pullup est la combinaison parallèle de tous les tirages actifs. La plage cible est de 1.5..4.7 kΩ (le minimum est borné par le courant absorbé de l'ESP32 ≤ 3 mA sous 3.3 V ; le maximum par la constante de temps RC du bus). Formule : 1/R_eff = N/R_unit. Pour la paire intégrée de 4.7 kΩ : 2 modules = 2.35 kΩ, 3 = 1.57 kΩ, 4 = 1.18 kΩ — à 3 modules, la valeur parallèle est 1.57 kΩ, toujours dans la plage, et un bus à 3 modules jusqu'à 15 cm est mesuré comme fiable (fils de 15 cm, 50 kHz) ; le tableau conserve donc les straps intégrés à 2 et 3 modules. À partir de 4 modules, ou plus tôt sur un bus plus long, on les désactive et on passe à une paire externe unique.
Contrôle de diagnostic : mesurez la résistance entre SDA et VCC hors tension. Le résultat doit être dans la plage 1.5..4.7 kΩ. Inférieur à 1.0 kΩ signifie trop de tirages actifs en parallèle ; supérieur à 10 kΩ signifie aucun tirage actif (vérifiez les straps).
Capacité du bus (pour ≥7 modules ou une longueur totale de câblage > 50 cm) : la spécification I²C limite la capacité totale C_b à ≤ 400 pF. Un bus court avec 2–3 modules se situe typiquement entre 50 et 100 pF ; un bus de 1 m avec 10 modules peut atteindre 300–400 pF. À l'approche de la limite, passez à frequency: 50kHz (si vous êtes encore à 100 kHz) ou utilisez un CI de tirage actif (par exemple le PCA9517).
Vitesse du bus
Définissez frequency: 50kHz dans le bloc i2c: d'ESPHome. Sur le firmware actuel, c'est obligatoire pour un fonctionnement fiable avec ESP-IDF v5 :
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz # recommended on ESP32 — ESP-IDF i2c_master driver interaction, see below
Le module envoie périodiquement des NACK aux lectures d'un ESP32 à 100 kHz (une part notable des transactions) à cause de l'interaction entre la temporisation du pilote ESP-IDF v5 i2c_master et la fenêtre de récupération après STOP de la périphérique I²C du module. À 50 kHz, les NACK sont bien plus rares, et la relance par octet à l'intérieur du composant récupère plus de 99 % des lectures valides.
Le firmware a durci la fenêtre de récupération I²C du module (livré en v1.1 et v1.3), ce qui a réduit la contribution côté module — mais 50 kHz reste le réglage recommandé sur les maîtres basés sur ESP-IDF, car l'interaction de temporisation du pilote persiste à 100 kHz. Considérez-le comme la recommandation permanente pour l'ESP32, non comme un contournement provisoire en attente d'un correctif.
D'autres maîtres I²C font fonctionner ce module à 100 kHz sans problème : STM32 HAL, SDK RP2040, smbus2 sur Raspberry Pi (I²C du noyau Linux), et les Arduino non ESP32 (AVR / STM32duino). Notez que l'axe est le pilote, non la carte : Arduino sur un ESP32 utilise le même pilote i2c_master de l'ESP-IDF, il lui faut donc aussi 50 kHz — seul l'Arduino non ESP32 fonctionne à 100 kHz.
Schéma de référence — un ESP32 + un rbAmp
Notes:
- La résistance de 10 kΩ sur DRDY se trouve côté maître (près du GPIO), et non côté module. DRDY est en drain ouvert, sans tirage interne.
- La prise CT doit être entièrement enfichée ; la pince doit entourer entièrement un seul conducteur, flèche pointant vers la charge.
- La polarité L/N aux bornes affecte le signe de P (voir 03_sensor_selection.md).
Puissance
Alimentation du module (VCC)
Le module nécessite +4.5..+5.5 V DC. Consommation :
| Mode | Typique |
|---|---|
| Mesure en régime établi | ~15 mA |
Écriture flash (lors de ct_model: / provisionnement d'adresse) |
~25 mA crête, ~700 ms |
| Préchauffage au démarrage (~250 ms) | ~15 mA |
La broche 5V d'un ESP32-DevKitC (généralement reliée au VBUS USB) peut alimenter le module directement — l'hôte USB doit fournir le courant combiné de l'ESP32 (~200 mA) + rbAmp (~15 mA en crête) = ~215 mA. Pour les installations où l'ESP32 est alimenté par une alimentation à découpage 5 V externe, reliez VCC au même rail 5 V.
Brownout de l'ESP32
Le détecteur de sous-tension de l'ESP32 se déclenche vers 2.43 V sur VDD. Lorsqu'il se déclenche, le bus I²C reste inactif tandis que le module continue à mesurer de façon autonome (il dispose de sa propre alimentation 5 V). Lorsque l'ESP32 se rétablit, setup() restaure l'énergie accumulée depuis la NVS avant le premier update(). HA ne voit ni trou ni remise à zéro sur le graphe d'énergie.
DRDY optionnel
La broche DRDY du module est en drain ouvert. Elle passe à LOW pendant environ 10 µs toutes les ~100 ms, juste après la mise à jour du bloc de registres instantanés. Elle ne se déclenche pas lors de l'instantané de période.
À update_interval: 60s, vous pouvez omettre DRDY — le composant vérifie le registre d'état au début de chaque update() et saute la lecture si le module n'est pas prêt. Le composant journalise la broche DRDY ; les lectures sont pilotées par minuterie (update_interval).
Câblage DRDY
DRDY est à drain ouvert : il tire vers LOW mais ne peut pas piloter HIGH. Il a besoin d'une résistance de tirage externe :
rbAmp DRDY ──────────────────┬── ESP32 GPIO (input)
|
[10K]
|
3.3V
10 kΩ vers 3.3 V. Ne reliez pas DRDY à 5 V, même si SDA/SCL tolèrent 5 V — DRDY est un signal distinct, et le maximum absolu d'une GPIO d'entrée de l'ESP32 est 3.6 V.
Déclarez la broche dans le YAML :
rbamp:
id: meter1
drdy_pin: GPIO15
DRDY multi-modules
Les signaux DRDY de plusieurs modules peuvent être reliés en OU câblé sur une seule GPIO de l'ESP32 (les sorties à drain ouvert se combinent naturellement). Le signal partagé passe à LOW lorsque n'importe quel module a mis à jour ses registres instantanés. Le composant ne journalise que la broche ; il ne dit pas quel module a déclenché.
Si vous avez besoin de signaux séparés, reliez le DRDY de chaque module à sa propre GPIO et déclarez drdy_pin: dans chaque bloc rbamp: individuellement.
Attribution d'adresses sur un bus multi-modules
Tous les modules rbAmp sortent d'usine à l'adresse 0x50. Avant de connecter plusieurs modules à un même bus, chacun doit recevoir une adresse unique. Sur le firmware v1.3, cela peut se faire en production, sans mode provisionnement en usine — grâce au protocole de validation en deux phases.
Commit d'adresse en deux phases (v1.3+, production-OK)
Avec new_address: , le composant exécute la séquence suivante :
-
Vérifie si le firmware prend en charge la validation en deux phases. Si oui, il emprunte le chemin de production. Sinon, il revient à l'ancienne méthode monophasée + verrouillage en mode provisionnement en usine (firmware v1.0-v1.2).
-
Écrit la nouvelle adresse dans
REG_I2C_ADDRESS(en transit, pas encore active). -
Écrit le « mot magique »
0xA5dansREG_ADDR_COMMIT_MAGIC— une confirmation explicite d'intention qui protège contre une écriture accidentelle dansREG_I2C_ADDRESS. -
Envoie l'opcode
CMD_COMMIT_ADDR— le module applique atomiquement l'adresse en transit, la sauvegarde en flash et effectue un soft reset. -
Après ~700 ms, le composant rattache son handle i2c_address à la nouvelle adresse et vérifie la réénumération par une lecture de sonde.
Si une étape échoue, le module revient à l'adresse précédente, sans état « à moitié appliqué ». Un aller-retour 0x50 → 0x60 → 0x50 se réénumère en moins d'une seconde.
Provisionnement séquentiel (flux de travail recommandé)
Plusieurs modules ensemble sur le bus avant le provisionnement constituent une collision d'adresse (tous sur 0x50). Le provisionnement se fait donc séquentiellement, un module à la fois :
- Ne connectez que le module 1 à l'ESP32 (seul sur le bus).
-
Flashez la configuration de
example/address_change.yamlavecaddress: 0x50etnew_address: 0x51. Au démarrage, le composant détecte l'écart → exécute la validation en deux phases (voir ci-dessus). -
Confirmez le succès dans les journaux ESPHome (réénumération à la nouvelle adresse). Mettez à jour le YAML :
address: 0x51, supprimeznew_address:. -
Déconnectez le module 1. Connectez le module 2 (toujours à l'adresse d'usine
0x50). -
Répétez pour
0x52,0x53, etc. IMPÉRATIF : un seul module vierge sur le bus à la fois — sinon les deux répondent sur 0x50, ce qui provoque une contention du bus. -
Lorsque tous les modules ont des adresses uniques, connectez-les tous au bus et réglez les tirages selon le tableau de Bus multi-modules (2 modules : conservez une paire ; 3 modules ou plus : coupez tout et ajoutez une paire externe).
Danger de provisionnement concurrent : si deux modules vierges sont tous deux à 0x50, les deux acquittent l'octet d'adresse et tirent SDA l'un contre l'autre pendant la phase de données → contention du bus et données indéterminées. Toujours un seul vierge à la fois.
Exemple de YAML multi-modules
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz
scan: true
rbamp:
- id: meter_house
address: 0x50
update_interval: 60s
- id: meter_solar
address: 0x51
update_interval: 60s
bidirectional: true
- id: meter_evcharger
address: 0x52
update_interval: 60s
sensor:
- platform: rbamp
rbamp_id: meter_house
voltage: { name: "House Voltage" }
current: { name: "House Current" }
power: { name: "House Power" }
energy: { name: "House Energy" }
- platform: rbamp
rbamp_id: meter_solar
voltage: { name: "Solar Voltage", internal: true }
current: { name: "Solar Current" }
power: { name: "Solar Power" }
energy: { name: "Solar Energy" }
energy_exported: { name: "Solar Energy Exported" }
- platform: rbamp
rbamp_id: meter_evcharger
voltage: { name: "EV Charger Voltage", internal: true }
current: { name: "EV Charger Current" }
power: { name: "EV Charger Power" }
energy: { name: "EV Charger Energy" }
La version complète annotée se trouve dans example/multi_module.yaml.
Longueur du bus
L'I²C est un protocole à courte portée (~15 cm par défaut). Beaucoup d'utilisateurs relient les modules avec des fils de liaison de mauvaise qualité, qui captent beaucoup de bruit et perdent de nombreux transferts — d'où la limite courte. Longueurs recommandées pour rbAmp :
| Type de câble | Longueur maximale | Vitesse |
|---|---|---|
| JST standard / plat 4 fils | 0.15 m | 50 kHz |
| Paire torsadée (SDA+GND et SCL+GND en paires séparées) | 1 m | 50 kHz |
| Paire torsadée + tampon I²C (PCA9515 / TCA9617) | 3 m | 50 kHz |
| Bus différentiel (PCA9615 / LTC4332) | 100 m | 50 kHz |
Pour plus de 0.15 m, utilisez une paire torsadée, et SDA et SCL doivent se trouver dans des paires séparées (par exemple bleu + blanc-bleu pour SDA, vert + blanc-vert pour SCL). Si SDA et SCL partagent une même paire, le couplage croisé déforme les fronts, même à 50 kHz.
⚠ Dans une armoire électrique, blindez le câble I2C. Les champs magnétiques intenses près des conducteurs secteur, des contacteurs et des transformateurs induisent du bruit dans un câble non blindé. Gardez le câble aussi court que possible et à l'écart du câblage secteur.
Mode provisionnement en usine (firmware historique v1.0-v1.2)
Sur le firmware v1.3, un changement d'adresse ne nécessite pas le mode provisionnement en usine — il s'exécute en production via la validation en deux phases (voir ci-dessus). Cette section ne s'applique qu'au firmware historique (v1.0-v1.2), où le changement d'adresse monophasé exigeait un mode spécial.
Sur le firmware hérité, certaines opérations du module (changer l'adresse I²C, réinitialisation d'usine) exigeaient que le module soit en mode de provisionnement usine — un mode spécial pour les actions de provisionnement ponctuelles. Les modules de production standard étaient livrés avec le mode de provisionnement désactivé : une tentative de changement d'adresse renvoyait une erreur, visible dans les journaux ESPHome sous la forme d'un WARNING au démarrage.
Comportement de compatibilité du composant v1.3 :
-
Avec
new_address:le composant vérifie d'abord si le firmware prend en charge le commit en deux phases. Oui → chemin production (deux phases, sans verrouillage du provisionnement usine). -
Si ce n'est pas le cas (firmware hérité v1.0-v1.2) → repli sur l'écriture monophasée, qui ne prend effet qu'en mode de provisionnement usine. Le composant journalise cela comme
WARN_FACTORY_MODE_REQUIREDdans le journal de démarrage.
Si vous avez un module sur firmware hérité (le DUT est mis à jour via le banc d'usine, pas par OTA terrain), contactez votre fournisseur pour la procédure d'activation temporaire du mode de provisionnement. Sur le firmware v1.3, ce problème n'existe pas.
La configuration des capteurs de courant (ct_model: / ct_models:) n'a jamais exigé le mode de provisionnement usine — un module sur n'importe quel firmware accepte directement une écriture de modèle CT (voir 03_sensor_selection.md).
Suite
- 05_quickstart.md — premier lancement
- 06_examples.md — scénarios complets : UI1 / UI3 / multi-modules / provisionnement d'adresse
- 10_troubleshooting.md — diagnostics orientés symptômes
Source et problèmes : rb-amp/rbamp-esphome · cette page dans le dépôt : docs/04_hardware.md (v1.9.1)