02 · Niveaux de modules
rbAmp est livré en deux gammes de modules : BASIC et STANDARD (STD). Chaque niveau est une combinaison complète de révision matérielle et de build firmware, et non un simple indicateur dans le firmware. Passer d'un niveau à l'autre exige de remplacer physiquement le module, et non une simple mise à jour du firmware.
Le composant ESPHome fonctionne avec les deux lignes de modules à partir d'un seul YAML : le schéma est commun, et le composant identifie automatiquement la ligne de module connectée (BASIC ou STANDARD (STD)) au démarrage. Les différences tiennent aux données que le module exporte réellement et aux clés YAML pertinentes sur chaque ligne.
Gammes
BASIC — entrée de gamme
Le firmware conserve un comptage de consommation unidirectionnel : la puissance active moyenne sur une période ne peut jamais être négative — les segments inverses dans la fenêtre sont mis à zéro avant intégration. Ce comportement ressemble à celui d'un compteur mécanique classique à disque.
- L'énergie est intégrée sur l'ESP32 à partir de la puissance moyenne de période que le module renvoie après chaque instantané, et sauvegardée en flash de l'ESP32 (NVS).
- Le capteur
energy_exportedexiste dans le schéma YAML (pour la compatibilité de configuration), mais sur BASIC il publie toujours0. - Les capteurs d'énergie de total général (
energy_total,energy_exported_total,energy_net,reactive_energy,reactive_energy_exported) se valident mais ne publient jamais sur BASIC. - Applications typiques : appartements sans production sur site, sous-comptage précis de charges (chauffe-eau, moteurs, appareils ménagers, CVC).
STANDARD (STD) — bidirectionnel, énergie embarquée
STANDARD (STD) est la gamme actuelle. Il mesure l'import et l'export séparément et conserve ses propres compteurs d'énergie cumulée à l'intérieur du module.
- Même YAML. Le composant reconnaît au démarrage un module STANDARD (STD) et prend le nombre de canaux, la variante et les fonctions disponibles depuis le module. Vous ne réglez pas de niveau et n'avez pas besoin de
topology:. - Énergie depuis les compteurs du module. Le composant accumule les compteurs du module au lieu d'intégrer lui-même la puissance, de sorte que les totaux survivent aux redémarrages de l'ESP32 et du module, restent monotones à travers les redémarrages du module et les remises à zéro de compteur, et ne dérivent pas. Les valeurs sont en plus sauvegardées dans la flash de l'ESP32 (NVS) toutes les 5 minutes et lors d'un arrêt propre (redémarrage / OTA).
- Nouveaux capteurs :
energy_total,energy_exported_total,energy_net(import − export, peut diminuer),reactive_energy,reactive_energy_exported— totaux généraux sur tous les canaux ; sur les variantes à trois tensions, aussivoltage_angle_b,voltage_angle_cetphase_sequence. - Par canal
energyetenergy_exported(avecbidirectional: true) proviennent des mêmes compteurs. start_current_ua:fixe un courant de démarrage en dessous duquel un canal ne compte aucune énergie, afin que le bruit à vide ne s'ajoute pas aux compteurs.- Applications typiques : foyers avec production solaire ou éolienne, stockage par batterie, bornes de recharge VE, toute installation où l'import et l'export doivent être comptés séparément, et installations où les totaux d'énergie doivent survivre aux redémarrages.
Sur un module STD, l'énergie provient des compteurs propres du module ; latch_interval ne s'applique qu'au BASIC.
Les clés qui n'existent que pour la ligne BASIC (fleet_gc_enable:, group_id:, broadcast_latch:, latch_interval: pour le chemin d'énergie côté maître) sont ignorées sur un module STANDARD avec une ligne de journal.
Matrice des capacités
| Capacité | BASIC | STANDARD |
|---|---|---|
| Tension efficace (RMS) | oui | oui |
| Courant efficace RMS (1..3 canaux, plus sur les variantes à plus de canaux) | oui | oui |
| Puissance active (flottant signé) | oui | oui |
| Facteur de puissance | oui | oui |
| Puissance réactive (lue depuis le module, canaux 0..2 ; non signée, calculée comme √(S² − P²), inclut la distorsion ; aucune précision indiquée) | oui | oui |
| Puissance apparente (CH0 uniquement) | oui (U × I[0], calculé sur l'ESP32) |
oui (depuis le module) |
| Fréquence de ligne | oui | oui |
Capteur energy (Wh importés), sauvegardé en NVS |
oui (intégré sur l'ESP32) | oui (à partir des compteurs embarqués) |
Capteur energy_exported (nécessite bidirectional: true) |
toujours 0 | oui |
| L'énergie survit aux redémarrages de l'ESP32 et du module | ESP32 uniquement | oui |
Totaux généraux : energy_total, energy_exported_total, energy_net |
non | oui |
Énergie réactive : reactive_energy, reactive_energy_exported |
non | oui |
start_current_ua: |
non | oui |
voltage_angle_b/_c, phase_sequence (variantes à trois tensions) |
non | oui |
ct_models: par canal |
oui | seulement si le module stocke les modèles par canal ; sinon refusé avec une ligne de journal |
fleet_gc_enable: / group_id: — synchronisation par appel général |
oui (firmware v1.3+) | ignoré |
Le composant ne lit que ce pour quoi des capteurs sont déclarés — un registre non déclaré n'est jamais demandé.
Clés YAML par niveau
bidirectional: (par défaut false)
Active les capteurs d'énergie exportée par canal (energy_exported, energy_exported_1, energy_exported_2).
rbamp:
id: solar_meter
address: 0x51
bidirectional: true # meaningful on STANDARD; on BASIC the export sensors read 0
Sur STANDARD, l'énergie exportée provient des compteurs du module. Sur BASIC, la clé est acceptée par le schéma sans erreur, mais energy_exported renvoie toujours 0. Les capteurs de totaux généraux energy_exported_total et energy_net n'ont pas besoin de cette clé.
sensor_class: — figer la famille de capteurs
rbamp:
id: meter1
sensor_class: SCT_013 # default SCT_013
Accepté sur les deux lignes de modules. Sur le firmware v1.2+, la valeur est écrite en flash et devient une condition préalable à l'écriture du modèle CT : le module refuse d'écrire le modèle si la classe n'est pas définie. Une valeur déjà présente dans le module n'est pas réécrite.
Valeurs d'énumération : SCT_013 (pinces SCT-013 à noyau fendu, par défaut), WIRED_CT et BUILTIN_CT (modules fournis calibrés avec leur propre capteur intégré). Sur un tel module appairé en usine, un changement de classe ou de modèle depuis le YAML est refusé avec une ligne de journal, pour protéger la calibration individuelle.
ct_model: / ct_models: — modèle de pince CT
Un seul profil global pour tous les canaux :
rbamp:
id: meter1
ct_model: SCT_013_030 # all channels — SCT-013-030
Ou un profil par canal (pour UI3 avec des pinces mixtes) :
rbamp:
id: meter_ui3
ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
Accepté sur les deux gammes de modules, mutuellement exclusif. Sur le firmware v1.2+, le module charge automatiquement les coefficients d'usine du modèle choisi — aucune étape d'étalonnage supplémentaire n'est requise. Sur un firmware antérieur, la valeur est stockée comme marqueur de modèle.
- Changer le calibre SCT conserve la précision d'usine : le composant termine le changement (un redémarrage du module dans le flux est normal sur le firmware jusqu'à 1.4.19 ; le firmware plus récent corrige sur le module) et met à l'échelle les relevés selon le capteur choisi.
- Garde-fous d'écriture : une valeur égale n'est pas réécrite ; sur un module appairé en usine, le changement est refusé avec une ligne de journal.
ct_model_force: true(option de service, valide uniquement avecct_model:/ct_models:) passe outre délibérément. - Les
ct_models:par canal sur un module STANDARD nécessitent que le module stocke les modèles par canal ; sinon le composant refuse bruyamment (avertissement, clés ignorées) — utilisezct_model:.
Pour choisir un modèle, voir 03_sensor_selection.md.
new_address: — attribution unique d'adresse I²C
rbamp:
id: meter1
address: 0x50
new_address: 0x51 # one-shot; remove after a successful boot
Accepté sur les deux lignes de modules. Sur le firmware v1.3+, le changement d'adresse est production-OK — le composant utilise un protocole de commit en deux phases (préparation → armement → commit → redémarrage) sans mode spécial. Sur le firmware hérité (v1.0-v1.2), le repli monophasé exige le mode de provisionnement usine ; consultez la documentation du module ou votre fournisseur pour la procédure d'activation. Le mode de provisionnement usine reste requis sur toutes les versions du firmware pour les opérations de calibrage (saveGains) et de réinitialisation d'usine.
Déroulement sur un seul démarrage : le composant interroge l'adresse actuelle, écrit la nouvelle adresse et la sauvegarde en flash, réinitialise le module et vérifie la réponse sur la nouvelle adresse. En cas de succès, mettez à jour le YAML avec address: 0x51 et retirez new_address:. Si le composant constate que l'ancienne adresse est silencieuse alors que la nouvelle répond, il s'adapte automatiquement avec un avertissement dans le journal (au cas où un démarrage précédent aurait déjà appliqué le changement).
fleet_gc_enable: / group_id: — instantané synchrone pour un bus multi-modules
rbamp:
- id: meter1
fleet_gc_enable: true # v1.3 production path — recommended
group_id: 1 # cluster id (modules in the same group snapshot together)
Lorsqu'il est activé, le composant envoie une trame General-Call de 5 octets à l'adresse de diffusion I²C — synchronisant l'instantané de période entre tous les modules de même group_id en une seule transaction.
Sur le firmware BASIC v1.3, l'instantané par appel général est optionnel et conditionné par la capacité. Le composant vérifie au démarrage si le firmware l'annonce et active le chemin automatiquement lorsque la clé YAML et le firmware concordent. Sur le firmware historique (v1.0..v1.2), il n'est pas annoncé ; le composant revient à un instantané séquentiel pour chaque module individuellement et journalise une ligne informative. Sur un module STANDARD, ces clés sont ignorées avec une ligne de journal.
La clé historique broadcast_latch: est toujours acceptée par le schéma pour la rétrocompatibilité, mais n'a aucun effet. Utilisez fleet_gc_enable: + group_id:.
Le décalage entre modules sur un bus à 50 kHz est de l'ordre de ~540 µs × N, soit moins de 0.003 % d'une période de 60 secondes. Sur les totaux journaliers de HA, cette irrégularité est imperceptible.
topology: — indication de topologie
rbamp:
id: meter1
topology: SINGLE # SINGLE / SPLIT_PHASE / THREE_PHASE
Facultatif et non nécessaire sur les modules STANDARD, où le nombre de canaux et la variante viennent du module lui-même. Sur les modules BASIC, le composant déduit le nombre de canaux des emplacements de capteurs déclarés (si current_1 est déclaré, il y a au moins 2 canaux). La clé est cosmétique et apparaît dans la ligne de journal dump_config.
drdy_pin: — interruption facultative de données prêtes
rbamp:
id: meter1
drdy_pin: GPIO15
Accepté sur les deux lignes de modules. Se connecte à la sortie DRDY facultative du module, en drain ouvert. La broche est configurée et journalisée, mais les registres instantanés sont interrogés à update_interval quoi qu'il arrive. Avec un update_interval: 60s typique, la clé peut être omise.
Nécessite une résistance de tirage de 10 kΩ sur le GPIO maître vers 3.3 V (la sortie est en drain ouvert ; il n'y a pas de tirage interne côté module). Voir 04_hardware.md.
Tableau récapitulatif — clé YAML × ligne de module
| Clé YAML | BASIC | STANDARD | Remarques |
|---|---|---|---|
address: |
oui | oui | — |
update_interval: |
oui | oui | Minimum 1s |
latch_interval: |
oui | n/a | Découple la cadence d'instantané/énergie de la cadence de lecture ; STANDARD lit ses compteurs à chaque update() |
drdy_pin: |
oui | oui | Facultatif, nécessite une résistance de tirage de 10 kΩ ; non utilisé comme déclencheur de lecture |
topology: |
oui | inutile | Indication informative |
sensor_class: |
oui | oui | Non réécrit si identique ; refusé sur les modules appairés en usine |
ct_model: / ct_models: |
oui | oui | Mutuellement exclusif ; la liste par canal sur STANDARD requiert un module qui la stocke |
ct_model_force: |
oui | oui | Option de service ; le schéma exige une clé de modèle |
bidirectional: |
accepté (l'export lit 0) | fonctionne | Nécessaire pour les capteurs par canal energy_exported* |
start_current_ua: |
ignoré avec un avertissement | fonctionne | 0 ou 10..2540 par pas de 10 |
new_address: |
oui | oui | Production-OK sur le firmware BASIC v1.3+ ; un seul passage |
fleet_gc_enable: / group_id: / broadcast_latch: |
oui | ignoré | La synchronisation par appel général est une fonctionnalité de la gamme BASIC |
Capteur energy_exported |
toujours 0 | fonctionne | Requiert bidirectional: true |
energy_total, energy_exported_total, energy_net, reactive_energy[_exported] |
ne publie jamais | fonctionne | Totaux généraux issus des compteurs embarqués |
voltage_angle_b/_c, phase_sequence |
ne publie jamais | fonctionne sur les variantes à trois tensions avec un firmware qui les fournit | Voir 09 §2.2–2.3 |
Capteurs par phase (voltage_a/b/c, current_a/b/c, …) |
aucune valeur | publier pour les canaux que le module signale | Détails dans 09 §2.2 |
Et ensuite
- 03_sensor_selection.md — choix d'une pince CT et comportement de
ct_model:/ct_models: - 04_hardware.md — câblage physique, choix des GPIO
Source et signalements : rb-amp/rbamp-esphome · cette page dans le dépôt : docs/02_tiers.md (v1.9.1)