Capteurs et unités

RBgrid mesure à travers deux couches :

• Capteurs — les canaux physiques que le hub peut voir. Dans un hub v1.1.x, ce sont les canaux des modules I²C rbAmp : une entrée de tension et un ou plusieurs canaux de courant par module. Il n'y a pas d'ADC intégré ; les modules mesurent et le hub les lit en I²C.
• Unités — les points de mesure que vous créez en liant un canal. Une unité a sa propre identité, son nom, son rôle, ses statistiques et son historique. Déplacer une unité vers un autre canal (rebind) conserve son identifiant, son nom, son historique et son emplacement d'historique.

Vous n'écrivez aucun code pour ajouter un capteur ou une unité. Les canaux apparaissent d'eux-mêmes lorsqu'un module est connecté ; vous transformez un canal en unité depuis l'application web ou l'API REST, à l'exécution.

Capteurs — les canaux physiques

Chaque canal d'un module connecté est listé, qu'il soit utilisé ou non. Un canal non lié à une unité est simplement free : il ne produit aucune donnée, n'est pas additionné et ne déclenche aucune alerte. Un module peut être utilisé avec n'importe quel sous-ensemble de ses canaux, dans n'importe quel ordre.

Chaque canal porte :

• ch_label — le canal tel qu'imprimé sur le boîtier du module : I0, I1, … pour les canaux de courant (numérotés à partir de 0), V pour l'entrée de tension du module, et L1–L3 sur un module sensible à la phase.
• Modèle de TC — pour un canal de courant, le modèle de transformateur de courant utilisé (ct_code / ct_name lisible, par exemple SCT-013-050, 50 A ; ct_name est omis lorsque le modèle est inconnu) et les limites du module pour ce modèle. Dans l'application, c'est le Current sensor du point. Sur un module qui accepte une pince de courant de votre choix, vous réglez le modèle (voir Choix du modèle de TC ci-dessous) ; sur un module dont la pince est appairée en usine au canal, le modèle est fixe.
• État de la correction — indique si le module a appliqué sa correction pour le modèle de TC choisi. Si ce n'est pas le cas (readings not corrected), l'interface affiche un avertissement et la raison (le canal n'est pas calibré · son gain ne correspond pas au modèle de TC · le module ne connaît pas ce modèle de TC). Tant que la correction n'est pas appliquée, les lectures peuvent différer des valeurs réelles.

Les modules eux-mêmes proviennent de la configuration de modules du hub ; un module à l'adresse par défaut (0x50) est trouvé sans aucune configuration (voir Get started). Les familles de modules rbAmp, leur composition en canaux et leur gamme de TC sont documentées avec les modules — voir la documentation des modules rbAmp.

Unités — les points de mesure

Une unité est créée en liant un canal à un point. Elle porte :

Dans l'application, les rôles se nomment Appliance, Load, Breaker, Generation, Storage, Charging station, Heating/cooling, Smart appliance, et pour les rôles d'alimentation Grid input et Backup input.

Deux unités sont des unités d'alimentation particulières — l'alimentation principale (le raccordement au réseau) et une alimentation alternative facultative (production interne). L'application ne propose jamais les rôles d'alimentation lors de la liaison et ne permet pas de les modifier, et le hub verrouille les deux : une modification touchant l'un de ces rôles est refusée (HTTP 409). Elles portent le suivi économique du site. Le bus de tension (l'entrée V du module) et l'entrée principale ne peuvent pas être supprimés.

Configurer à l'exécution — application web ou REST

Tout se configure sur le hub en fonctionnement. Rien n'est défini dans le code C.

Application web — Points → Free sensors → Bind transforme un canal libre en unité ; les champs de l'unité se modifient dans ses réglages.

REST — les mêmes opérations sont disponibles en HTTP :

Les opérations d'écriture exigent le jeton d'administration du hub lorsqu'il est défini — définissez-le avec POST /api/system/token et envoyez-le lors des écritures ; c'est recommandé. Tant que vous n'avez pas défini de jeton, les écritures sont ouvertes sur le réseau local.

Par exemple, pour lier un canal :

POST /api/v1/units
{
  "sensor": { "iface": "i2c", "bus": 0, "module": 0, "ch": 1 },
  "name": "Kitchen", "point": "kitchen",
  "role": "ZONE_LOAD", "stat_class": "1HOUR", "location": "ground floor"
}

La réponse renvoie le nouveau unit_id. Les nouveaux identifiants sont attribués à partir de 0100 vers le haut. Renommer un point retire l'ancien slug, afin qu'un système externe ne reprenne pas silencieusement un autre point sous la même clé.

Supprimer (ou délier) une unité efface son historique stocké définitivement ; son canal redevient libre. L'identifiant d'un point supprimé peut être réutilisé volontairement : l'application le propose lors de la liaison (Bind with the previous ID). Le hub repart alors d'un historique neuf, mais Home Assistant et MQTT continuent l'ancienne série comme un seul point.

Les paramètres tels que name, role, phase, rated_power_w, max_current_a et le modèle de TC se modifient en direct avec l'endpoint de patch et sont conservés après un redémarrage. La référence complète des champs se trouve dans la documentation API des unités et capteurs.

Choix du modèle de TC

Sur un canal dont le module accepte une pince de courant de votre choix (série SCT), réglez le modèle de TC sur la pince réellement montée : le Current sensor du point dans ses réglages, ou ct_code via l'endpoint de patch. Le modèle est écrit dans le module avec son étalonnage de type, et associé à l'identité de ce module ; ainsi, un autre module dans le même emplacement conserve son propre modèle enregistré.

Ne le modifiez que si une autre pince est réellement montée. Écrire le modèle remplace l'étalonnage d'usine du canal, et cet étalonnage ne peut pas être restauré. Sur un canal appairé en usine (série CT), le modèle est fixe : le hub refuse la modification. Sur un module non calibré, le modèle ne peut pas être choisi.

Phase

phase indique à quelle ligne d'alimentation appartient un canal. Sur une alimentation monophasée, tous les canaux utilisent la valeur par défaut (1P / L1). Les alimentations monophasées et triphasées sont prises en charge. La puissance et l'énergie monophasées sont validées sur matériel. La puissance et l'énergie triphasées sont aussi vérifiées sur matériel, avec les trois entrées de tension sur une même phase de banc ; un réseau triphasé réel à 120° n'a pas été testé sur banc. Une entrée triphasée est un seul STD-U3I3, et sa carte de module permet de choisir si l'entrée est mesurée comme un seul point avec les phases compensées ou comme un point par phase, chaque phase ayant son propre import et son propre export. Les systèmes d'alimentation validés sur votre hub sont listés dans GET /api/v1/schema → enums.grid_system_validated.

phase n'est qu'une étiquette. Le hub ne multiplie ni ne divise jamais les valeurs d'une unité par le nombre de phases : une unité avec un seul transformateur de courant indique ce que transporte ce seul conducteur, quelle que soit la valeur de son phase. Une unité réglée sur 3 phases sur une charge triphasée représente l'énergie mesurée d'une seule phase — ne la divisez pas et ne la multipliez pas par trois.

Statistiques

Chaque unité conserve des données sur 3 secondes et 15 minutes uniquement en RAM ; elles n'ont pas d'historique stocké. L'historique stocké commence au niveau horaire : le hub conserve des enregistrements horaires sur sa propre mémoire flash, qui survivent à un redémarrage, et construit les jours, semaines, mois et années à partir de ceux-ci. C'est identique pour chaque unité, quelle que soit sa stat_class. L'historique est conservé pour 12 unités au maximum ; au-delà de douze, les unités n'affichent que des valeurs en direct. Une unité ajoutée pendant que le hub fonctionne commence son historique après le redémarrage suivant. Les totaux d'énergie à vie sont conservés séparément de l'historique.

Lorsqu'un canal approche de sa limite

Un point signale son état sur sa tuile dans l'Overview, dans Load lines, dans le tableau des points et dans Needs attention ; la page du point affiche une alerte :

• clipping — le courant a atteint le point d'écrêtage du capteur (son courant pleine échelle, supérieur à son calibre nominal). Au-delà, la lecture est sous-comptée, et le module ne peut pas le détecter seul. Les réglages du point avertissent aussi à l'avance lorsque le disjoncteur de la ligne dépasse la limite du capteur, et les lignes de l'historique signalent l'écrêtage.
• sensor limit — le courant est proche du courant d'écrêtage du capteur : le hub le signale à environ 90 % de ce courant. Pour les pinces SCT-013, le courant d'écrêtage est d'environ 116 % du calibre (58 A sur un SCT-013-050), donc l'avertissement arrive à environ 104 % du calibre (52 A). Jusqu'au courant d'écrêtage, les lectures sont correctes. Les capteurs propres aux modules STD ne portent pas de tels signaux ; ils lisent correctement jusqu'à environ 130 % de leur calibre.
• Un TC inversé sur un module BASIC : le point affiche sensor reversed — not metered. Un module BASIC ne compte que le flux dans le sens direct, donc la charge n'est pas comptée tant que vous ne retournez pas la pince.

Le journal des événements ajoute une ligne lorsque l'état change : « near its limit », « clipping » ou « back within range ». Seul clipping marque l'enregistrement horaire (un indicateur de qualité pour le dépassement de plage) ; « near its limit » n'apparaît que dans le journal. Voir The Overview et Points pour l'endroit où ces signaux apparaissent.