rbAmp
FR
Boutique
Docs
Mis à jour · Modifier sur GitHub

02 · Niveaux de modules

Les deux lignes de modules rbAmp, BASIC et STANDARD (STD), et l'endroit où l'énergie est calculée sur chacune.

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_exported existe dans le schéma YAML (pour la compatibilité de configuration), mais sur BASIC il publie toujours 0.
  • 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, aussi voltage_angle_b, voltage_angle_c et phase_sequence.
  • Par canal energy et energy_exported (avec bidirectional: 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.

Comptabilisation de l'énergie sur BASIC (le maître intègre la puissance moyenne de la période) face à STANDARD (le maître lit les compteurs cumulés du module).

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é
Remarque

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

YAML
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

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

YAML
rbamp:
  id: meter1
  ct_model: SCT_013_030   # all channels — SCT-013-030

Ou un profil par canal (pour UI3 avec des pinces mixtes) :

YAML
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 avec ct_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) — utilisez ct_model:.

Pour choisir un modèle, voir 03_sensor_selection.md.

new_address: — attribution unique d'adresse I²C

YAML
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

YAML
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

YAML
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

YAML
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


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