rbAmp
FR
Boutique
Docs
Mis à jour le · Modifier sur GitHub [Edit on GitHub]

04 · Câblage

Ce chapitre décrit le câblage physique du module rbAmp sur les cartes de la famille ESP32 : brochage côté basse tension, exigences d'alimentation, compatibilité des niveaux de tension I²C, longueur du bus, et les broches par défaut standard pour les 7 puces ESP32 prises en charge (esp32, esp32s2, esp32s3, esp32c2, esp32c3, esp32c6, esp32h2).

Le module lui-même est entièrement basse tension ; sur les variantes UI*, l'unique référence secteur est une prise L–N derrière un diviseur isolé galvaniquement. Le côté BT (alimentation + I²C + DRDY facultatif) est décrit en premier ; le raccordement secteur et CT figure plus bas dans Raccordement secteur et CT.

Brochage côté basse tension

Les broches basse tension du module : VCC, GND, SDA, SCL et la ligne data-ready facultative.
Le module fonctionne en logique I²C 3.3 V et estTolérant au 5 Vsur les lignes de signal. Toutes les broches basse tension sont entièrement isolées galvaniquement du secteur.

Broche Signal Objet
VCC +5 V (4.5..5.5 V) Alimentation du module ; minimum 4.5 V pour un fonctionnement correct
GND Terre Partagé avec le maître — obligatoire
SDA SDA I²C Données I²C
SCL I²C SCL Horloge I²C
DRDY Données prêtes (facultatif) Drain ouvert, impulsion LOW d'environ 10 µs toutes les ~100 ms

Puissance

Paramètres de VCC

  • Tension nominale : 5 V CC
  • Plage admissible : 4.5..5.5 V
  • Consommation de courant : ~15 mA typique, ~25 mA en crête pendant les écritures en flash
  • Ondulation : < 50 mV crête à crête (pour la précision de mesure)

Le module embarque un régulateur, un filtre RC, des condensateurs céramiques et une perle de ferrite — aucun filtrage supplémentaire n'est requis de la part de l'utilisateur. Le module peut être alimenté depuis le rail +5V ou +5V0 de toute carte DevKitC (alimentée en USB-5V).

Compatibilité des niveaux de tension I²C

  • SDA / SCL fonctionnent en logique 3.3 V (les résistances de rappel intégrées tirent les lignes vers 3.3 V).

  • Les lignes sont tolérantes au 5 V, mais la famille ESP32 est de toute façon en 3.3 V — aucun adaptateur de niveau n'est nécessaire.

  • Le pilote i2c_master de l'ESP-IDF utilise des sorties en drain ouvert sur les GPIO — compatibles avec les résistances de tirage intégrées du module.

Comportement à la mise sous tension

  • Démarrage à froid : ~250 ms jusqu'au premier résultat valide.
  • Après une réinitialisation (logicielle ou coupure de tension) : environ 250 ms pour reprendre.
  • Jusqu'au premier résultat valide, les registres se lisent comme 0, avec le drapeau DATA_VALID = 0.

Le composant attend que le module soit prêt à l'intérieur même de rbamp_begin(dev) ; le code utilisateur appelle simplement rbamp_begin() et continue.

Isolation

Le module lui-même est entièrement basse tension — il n'y a pas de circuit de mesure haute tension sur celui-ci. Le courant est lu par une pince CT qui se couple magnétiquement depuis l'extérieur du conducteur isolé, sans contact électrique avec le fil secteur. Sur les variantes de détection de tension (UI), l'unique référence secteur est la borne L–N, qui alimente un diviseur de détection isolé galvaniquement* ; les variantes à ampèremètre seul n'ont aucune connexion secteur.

Consequences:

  • Le GND du module n'est pas raccordé au conducteur de phase ni au neutre.
  • Les bornes basse tension se raccordent à l'ESP32 sans référence secteur : la pince se couple magnétiquement et la prise de tension UI se trouve derrière un diviseur isolé galvaniquement. Cela ne remplace pas les précautions de câblage secteur de la section suivante.
Sécurité

⚠ N'ouvrez pas le boîtier du module — cela annule la calibration d'usine.

Raccordement secteur et CT

Câblage côté secteur : la prise L et N de tension et la pince sur le conducteur de phase.

Sécurité

⚠ La tension du secteur peut tuer. Coupez et verrouillez le circuit avant de raccorder les bornes L/N ou de poser la pince ; faites réaliser le câblage secteur et tout travail dans un tableau par une personne qualifiée. Ne serrez qu'UN seul conducteur (L) — jamais le câble entier. Protégez la dérivation L selon les règles locales (obligatoire, jusqu'à 0.1 A ; un fil AWG26–22 suffit — le capteur de tension consomme très peu de courant).

  • Tension (variantes UI uniquement) : le module mesure la tension depuis la connexion L/N côté secteur : le PCB expose les bornes L (phase) et N (neutre), et la polarité détermine le signe de la puissance. Les variantes I (I1/I2/I3) n'ont pas d'entrée de tension.

  • Courant : la pince SCT-013 se branche sur la prise CT 3.5 mm du module (détrompée pour la bonne polarité ; chaque prise sur le circuit imprimé porte son canal, I0, I1, …) et se referme autour du conducteur de phase (L). La flèche sur le corps de la pince pointe dans le sens du courant vers la charge. Une pince montée à l'envers donne une P négative sur une charge consommatrice.

  • Pincez le conducteur de phase, ni le neutre ni les deux conducteurs ensemble.

  • N'ouvrez pas le boîtier du module — cela annule l'étalonnage d'usine. Les pontets de résistance de rappel mentionnés ci-dessous se trouvent sur la face inférieure de la carte ; suivez les instructions du module pour y accéder.

Résistances de rappel intégrées — sur la carte

Important : chaque module rbAmp dispose de résistances de tirage intégrées de 4.7 kΩ sur SDA et SCL vers 3.3 V. Pour un seul module sur le bus, aucune résistance de tirage externe n'est nécessaire : connectez directement l'ESP32.

La i2c_master_bus_config_t de l'ESP-IDF permet aussi d'activer les résistances de tirage GPIO internes via flags.enable_internal_pullup = true. Elles sont faibles (~50 kΩ sur l'ESP32) et fonctionnent en parallèle avec les 4.7 kΩ externes du module — la combinaison donne environ 4.4 kΩ effectifs, ce qui est acceptable. Pour les déploiements en production, préférez vous appuyer sur les 4.7 kΩ externes du module ; les résistances GPIO internes sont facultatives avec celles du module et servent surtout aux tests sur banc sans module sous la main (par exemple pour vérifier un scan de bus).

Quand désactiver les résistances de rappel intégrées

Si plusieurs modules rbAmp se trouvent sur le bus (ou d'autres périphériques I²C avec leurs propres résistances de tirage), les câbler en parallèle donne une résistance effective trop faible, ce qui :

  • Augmente la consommation de courant du bus
  • Peut dépasser le courant de puits maximal de l'étage de sortie du maître I²C
  • Ajoute une charge capacitive sur un long bus tout en améliorant peu l'immunité au bruit

Solution : sur la face inférieure de la carte de chaque module, à côté des résistances de tirage, se trouvent des straps à pont (sérigraphie Pull-Up). Coupez-les avec une lame fine :

  • Laissez les résistances de rappel activées sur un seul module (ou placez-les en un seul point près de l'ESP32).

  • Coupez les straps sur les modules restants.

Règle empirique

Règles de résistances de rappel pour un à trois modules sur un bus court et pour quatre ou plus.
| Modules rbAmp sur le bus | Résistances de rappel | |:---:|---| | 1 | Laisser en l'état (la résistance intégrée de 4.7 kΩ suffit) | | 2 | Laisser sur l'un, couper sur l'autre | | 3 | Couper sur tous les modules, poser une paire externe de 2.7…3.3 kΩ près de l'ESP32 | | 4…6 | Couper sur tous les modules, une paire externe de 2.2…2.7 kΩ près de l'ESP32 | | 7…16 | Couper sur tous les modules, une paire externe de 1.5…2.2 kΩ près de l'ESP32 ; vérifier la capacité du bus (≤ 400 pF), réduire la vitesse du bus si nécessaire |

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.

En cas de doute

: mesurez la résistance entre SDA et la ligne 3V3, tous les appareils hors tension. Elle doit se situer dans la plage 1.5..4.7 kΩ. Plus basse — trop de résistances de rappel actives en parallèle.

Paramètres du bus I²C

  • Adresse par défaut : 0x50 (7 bits)
  • Plage d'adresses : 0x08..0x77 (réassignable en usine)
  • Vitesse recommandée sur ESP32 : 50 kHz (voir la section sur la discipline de reprise et de contrôle de cohérence ci-dessous)

  • Incrémentation automatique du pointeur : uniquement sur les lectures. Une lecture en rafale + N octets renvoie N octets consécutifs à partir de addr (incrémentation automatique). Les écritures ne sont PAS incrémentées : une écriture en rafale + N octets n'écrit que le premier octet, les autres sont perdus. Les registres multi-octets s'écrivent octet par octet — une transaction distincte d'un octet par adresse. Pour les détails, voir 09 · Référence de l'API, section « Multi-byte writes » (écritures multi-octets).

Longueur du bus

I²C est un bus court (environ 15 cm par défaut). Beaucoup d'utilisateurs connectent 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. Topologies recommandées pour rbAmp :

Câble Longueur maximale Vitesse
JST standard / 4 conducteurs plats jusqu'à 0.15 m 100 kHz
Paire torsadée UTP (cat-5/5e/6) — SDA+GND et SCL+GND dans des paires séparées jusqu'à 1 m 100 kHz
Paire torsadée + tampon I²C (PCA9515 / TCA9617) jusqu'à 3 m 100 kHz
Bus différentiel (PCA9615 / LTC4332) jusqu'à 100 m 100 kHz
Sécurité

Les longueurs ci-dessus ont été vérifiées à 100 kHz. La vitesse de bus par défaut du composant est de 50 kHz (voir « Motif NACK de référence ESP32 » ci-dessous), plus tolérante aux câbles longs ; gardez 50 kHz et ne dépassez pas ces longueurs.

Pour des longueurs au-delà de 0.15 m, une paire torsadée est obligatoire : SDA et SCL doivent être dans des paires différentes, chacune avec sa propre masse. SDA et SCL dans la même paire créent un couplage capacitif croisé qui déforme les fronts.

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

Bus multi-modules — la topologie principale

Le cas d'usage canonique de la bibliothèque est plusieurs modules rbAmp sur un même bus I²C, gérés par un seul ESP32 via un handle de flotte. Toutes les règles et optimisations ci-dessous sont conçues précisément pour cette topologie ; un module unique est un cas particulier (même handle, mais les appels de flotte deviennent triviaux).

Plusieurs modules rbAmp sur un même bus I²C, avec les résistances de rappel gérées selon les règles.

Déploiements types

Scénario Configuration Nombre de modules
80 % canonique : arrivée principale + sous-compteurs 1× UI1 (principal, énergie du secteur) + 3-6× UI1 (charges ; la puissance et les Wh exigent une variante UI) 4-7
Sous-tableau avec répartition du courant 1× UI1 (principal) + 1 à 2× I2/I3 (courant par circuit) 3-5
Sous-comptage industriel 1× UI1 (principal) + N× I2/I3 (par machine, répartition du courant) jusqu'à environ 16

Contraintes électriques

  • Nombre de modules : jusqu'à environ 16 (capacité totale du bus ≤ 400 pF à 100 kHz).
  • Adresses : chaque module a sa propre adresse à 7 bits (plage 0x08..0x77). Tous les modules sortent d'usine à 0x50 — réadressez-les un par un avant de les câbler en parallèle (voir plus bas la validation en deux phases et le provisionnement via rbamp_provision()).
  • Résistances de rappel (important pour un bus de flotte) : les résistances de rappel internes de l'ESP32 (~45 kΩ) sont trop faibles pour un bus multi-modules avec de longues pistes et du bruit. Pour un fonctionnement fiable, il vous faut des résistances de rappel externes (2.7…3.3 kΩ pour 3 modules, plus basses pour les grands bus — voir le tableau ci-dessus) vers 3.3 V sur SCL/SDA en un seul point du bus + à partir de 4 modules (ou plus tôt sur un bus de plus de 15 cm) les résistances intégrées sont coupées sur tous les modules sauf un — avec 2–3 modules sur un bus de 15 cm au plus, laissez-les en place, ce cas a été mesuré (ou coupez-les sur tous et ne gardez que les externes). Cela fait partie de l'atténuation en trois couches contre le blocage du bus sur un bus marginal — voir 10 · Dépannage.

Adressage — provisionnement et remplacement à chaud

L'adresse d'usine par défaut est 0x50. Chaque nouveau module ou module de remplacement passe par le provisionnement (une fois) : réadressage depuis 0x50 vers une adresse de travail + sauvegarde facultative de la configuration (modèle de CT, group_id, étiquette) en flash.

Dans le code, c'est un seul appel — rbamp_provision(bus, desired_addr, save_config, &dev). Il vérifie qu'il y a vraiment un seul module vierge sur 0x50 sur le bus, le réadresse via une validation en deux phases (voir plus bas), sauvegarde éventuellement la configuration utilisateur, et renvoie un handle prêt.

Flux de provisionnement : connectez un nouveau module à l'adresse 0x50, donnez-lui son adresse, puis le suivant.

Sécurité

⚠ Discipline de provisionnement (OBLIGATOIRE) : il doit y avoir exactement un module vierge (sur 0x50) sur le bus au moment où rbamp_provision() est appelé. Si deux modules à la même adresse répondent simultanément sur I²C — une collision en phase de données, le comportement est indéfini, et il n'existe aucun moyen de les distinguer (collecteur ouvert en ET câblé). Procédure de récupération : couper l'alimentation, passer physiquement à une mise en service d'un seul module, provisionner-les un par un, puis connecter le reste. Voir 10 · Dépannage, section « Échec du provisionnement / conflit d'adresse ».

Si vous n'avez pas de handle de flotte et que vous réadressez manuellement via rbamp_prepare_address_change() + rbamp_commit_address_change() (la forme bas niveau) — la discipline est exactement la même : un seul module vierge à la fois.

Commit en deux phases pour un changement d'adresse

Le firmware prend en charge un changement d'adresse en mode production via une séquence en deux phases :

Les étapes d'un changement d'adresse en deux phases, de la mise en attente de la nouvelle adresse à sa vérification.

Text
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

Le composant enveloppe cela dans rbamp_prepare_address_change() / rbamp_commit_address_change() — voir 09 · Référence API. La persistance n'est confirmée qu'après une réinitialisation (voir l'encadré « Mode production ou usine : persistance » dans 03_sensor_selection.md).

Budget énergétique du bus — combien de modules votre cadence de scrutation peut supporter

Sur un bus à 50 kHz, une transaction de lecture de registre dure ≈ 200 à 400 µs (selon le pilote du MCU). Un bloc RT complet d'un canal (U + I + P + PF) = 4 flottants = 16 octets + 4 phases d'adresse ≈ 5 à 8 ms par canal.

Configuration Bus par cycle À 50 kHz Cadence d'interrogation maximale
1× UI1, bloc RT ~5 ms < 5 ms 100+ Hz (mais le module se met à jour à 10 Hz)
1× I3, bloc RT + période ~25 ms ~25 ms jusqu'à 10 Hz
5× UI1, bloc RT ~25 ms ~25 ms jusqu'à 10 Hz
16× I3, temps réel + période ~400 ms 400 ms > 100 ms ne suit pas le module (10 Hz) ; ~2 Hz au mieux
Remarque

Les nombres ci-dessus sont des estimations et dépendent du microcontrôleur hôte et du pilote.

Règle : à 50 kHz, les limites confortables sont 8 à 10× I3 ou 15 à 16× UI1 avec une scrutation à 5 Hz (toutes les deux fenêtres de module), et environ la moitié de cela à la pleine cadence de 10 Hz. Au-delà :

  • Réduisez la cadence de scrutation (1 Hz = 10× de marge).
  • Passer à 100 kHz avec nouvelles tentatives (attendez-vous à des NACK fréquents et comptez sur les nouvelles tentatives).
  • Utilisez la broche DRDY pour l'asynchrone — n'interrogez pas les modules qui ne sont pas encore prêts.

Synchronisation des périodes — mise en phase des périodes pour une synchronisation serrée

Pour le comptage tarifaire, tous les modules doivent prendre leur instantané sur le même intervalle de temps. Deux stratégies :

Latch séquentiel de chaque module, comparé à une seule trame General-Call qui latch tous les modules en même temps.

Stratégie 1 — instantané séquentiel + stabilisation partagée (fonctionne sur tout firmware) :

C
/* 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);
}

Décalage entre modules : 16 modules × ~1 ms/instantané = ~16 ms par rapport à une période de 60 secondes → 0.027 %. Négligeable.

Stratégie 2 — instantané par diffusion General-Call (nécessite une activation) :

Tous les modules reçoivent l'instantané dans une seule trame I²C à l'adresse 0x00 :

La disposition de la trame d'instantané General-Call de 5 octets envoyée à l'adresse 0x00.

Text
addr=0x00 | A5 27      (5 bytes)

Décalage = 0 (atomique). Préconfiguration :

  1. Sur chaque module, activez REG_FLEET_CONFIG.bit0 = 1 via CMD_SAVE_USER_CONFIG.
  2. CMD_RESET — la réception GC est activée au démarrage.
  3. Après la réinitialisation, le maître envoie la trame de 5 octets.
  4. Témoin : pour chaque module attendu, lisez REG_V03_PERIOD_VALID (0x07). !=1 → repli sur la stratégie 1.

Quand utiliser quoi :

  • < 8 modules : stratégie 1 (plus simple, aucune activation requise).
  • ≥ 8 modules ou synchronisation serrée : stratégie 2.

Filtrage par groupe GC — un bus multi-locataires

REG_GROUP_ID (0x28) vous permet d'avoir plusieurs domaines GC sur un même bus :

  • group = 0x00 → appel général (tous les modules avec GC activé prennent l'instantané).
  • group = N → seuls les modules avec REG_GROUP_ID = N prennent l'instantané.

Exemple : un bus de 10 modules, où vous devez prendre un instantané de 5 pour le tarif A et de 5 pour le tarif B, indépendamment :

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

Modes de défaillance sur un bus multi-module

Symptôme Cause Que faire
i2c bus scan montre plusieurs modules à la même adresse après un ajout sur site Le nouveau module sur 0x50 est en conflit avec un module déjà adressé Reprogrammez l'adresse du nouveau module séparément avant de l'ajouter au bus
Un module commence à émettre des NACK plus souvent que les autres Défaut de câble / chute de VCC sur ce module Vérifier VCC sous charge + niveaux logiques
Les Wh d'un module divergent de façon constante La propre horloge du module diffère de l'horloge du maître Intégrez l'énergie par rapport à l'horloge maître (master_dt_ms)
Après une trame GC, un module ne prend pas l'instantané FLEET_CONFIG.bit0 = 0 ou groupe non concordant Vérifiez REG_FLEET_CONFIG et REG_GROUP_ID

Notes de conception du bus

  • Étirement d'horloge : le firmware actuel le minimise (la fenêtre __disable_irq dans LatchPeriod est courte, ~µs). L'instantané lui-même ne tire pas significativement SCL. Pour le Raspberry Pi BCM283x (bogue matériel connu d'étirement d'horloge) : appliquez la prudence habituelle — 50 kHz + nouvelles tentatives sont déjà recommandés.
  • Longueur du bus avec plus de 4 modules : même avec une paire torsadée, la capacité effective croît linéairement avec le nombre. Envisagez un tampon I²C (PCA9515) à partir de 8 modules + une longueur supérieure à 1 m.

Des scénarios multi-modules détaillés figurent dans 06 · Exemples, aux scénarios « Sub-metering shared bus » (sous-comptage sur bus partagé) et « GC broadcast snapshot » (instantané diffusé GC).

Brochage de la famille ESP32

Les 7 puces listées en tête de ce chapitre sont prises en charge (selon idf_component.yml). Vous trouverez ci-dessous les broches par défaut recommandées pour I²C ; pour les déploiements en production, choisissez le GPIO en fonction de la disposition propre à votre carte.

ESP32 (original / DevKitC / WROOM)

Câblage de référence d'un ESP32 vers un module rbAmp, avec la pince dans la prise I0.

C
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,
};
Broche GPIO
SDA GPIO21
SCL GPIO22
DRDY tout GPIO libre qui n'est pas une broche de strapping (sur l'ESP32 classique, éviter GPIO0/2/12/15)

ESP32-S2

Les mêmes GPIO21/22 par défaut que l'ESP32 d'origine. Le S2 n'a pas de Bluetooth — environ 30 ko de tas supplémentaires sont disponibles pour les scénarios TLS.

ESP32-S3

Le S3 n'a pas de valeurs I²C fixées dans le matériel — n'importe quel GPIO via la matrice. Sur la plupart des cartes de développement WROOM-S3, GPIO8/GPIO9 sont un choix confortable (vérifiez le schéma de votre carte : sur le N16R8, ces broches peuvent être prises par la flash QSPI ; l'USB-JTAG occupe GPIO19/20). Ajustez les champs sda_io_num / scl_io_num dans i2c_master_bus_config_t :

C
.sda_io_num = GPIO_NUM_8,
.scl_io_num = GPIO_NUM_9,

Le S3 dispose d'USB-OTG — il peut servir au débogage sans puce USB-UART externe.

ESP32-C2 / C3 / C6 / H2

Puces monocœur RISC-V (le C3 et le C6 sont monocœur ; le H2 est monocœur avec BLE+802.15.4 ; le C2 est monocœur avec une RAM limitée). Les broches I²C ne sont pas figées matériellement — voici un exemple pour l'ESP32-C3 (sur le C3-SuperMini, GPIO5/GPIO6 conviennent ; sur le C3-DevKitM-1, le USB-JTAG occupe GPIO18/19, et GPIO8/9 sont des broches de strap) :

C
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,
};

Pour les autres puces, consultez la documentation ESP-IDF propre à la cible (docs.espressif.com → ESP-IDF v5.2+ → votre puce → référence API → périphériques → I2C).

ESP32-P4 — cible non prise en charge

L'ESP32-P4 ne figure pas dans la liste des cibles prises en charge : la prise en charge de la P4 exige ESP-IDF v5.3+, alors que le minimum du composant est la v5.2 (une compilation v5.2 pour esp32p4 échouerait avec « target esp32p4 not in idf »).

Schéma de NACK de référence de l'ESP32 — vitesse de bus 50 kHz

Avec le pilote i2c_master de l'ESP-IDF v5, rbAmp présente des NACK fréquents à 100 kHz, bien moins à 50 kHz (une caractéristique du pilote côté ESP32, non de l'esclave). Le composant traite cela en deux couches :

  1. Vitesse de bus par défaut de 50 kHz via le Kconfig CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ=50000. Le composant demande cette fréquence lorsqu'il ajoute son handle de périphérique au bus que vous créez.

  2. Nouvelle tentative par octet — CONFIG_RBAMP_NACK_RETRY_ATTEMPTS=3 × intervalle de 5 ms. À 50 kHz, le taux d'erreur résiduel est < 0.8%.

Remplacez la valeur par défaut via idf.py menuconfig si nécessaire :

Text
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

Pour un diagnostic plus poussé des problèmes au niveau du bus, voir 10 · Dépannage.

DATA_READY (DRDY)

Une broche facultative pour optimiser l'interrogation. Si l'application n'interroge pas le module plus souvent qu'une fois toutes les 100 ms — DRDY peut rester non raccordée.

Paramètres électriques

  • Type de sortie : drain ouvert (pas de rappel actif vers VCC)
  • Niveau de repos : HAUT (nécessite une résistance de rappel côté maître — gpio_pullup_en() interne ou une résistance externe ; 10 kΩ vers 3.3 V recommandé)

  • Impulsion de disponibilité : BAS pendant ~10 µs après la mise à jour des registres RT avec des données fraîches

  • Cadence d'impulsions : ~10 Hz (une impulsion par fenêtre RT d'environ 100 ms)

Sémantique

Un front descendant sur DRDY garantit que tous les registres RT sont synchronisés et publiés (le firmware met à jour ces registres de façon atomique dans l'ISR avant d'abaisser la broche). Après le front descendant, le maître peut lire le bloc RT sans risque d'échantillon scindé.

Schéma d'interruption — sémaphore FreeRTOS

ESP-IDF offre un modèle propre : une ISR en IRAM lève un sémaphore binaire, une tâche FreeRTOS séparée attend le sémaphore et lit RT.

C
#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 est facultatif — la scrutation à n'importe quelle cadence ≤ 10 Hz fonctionne aussi sans lui. Le composant ne dépend de DRDY dans aucun de ses chemins.


Source et problèmes : rb-amp/rbamp-esp-idf · cette page dans le dépôt : docs/04_hardware.md (v1.7.3)