Documentation

Compteurs définis par l'utilisateur

Remarque: Le gestionnaire de charge cFos peut lire la plupart des onduleurs solaires utilisant SunSpec (type d'appareil "Onduleur solaire / Compteur SunSpec"). Dans ce cas, vous n'avez pas besoin de créer votre propre définition de compteur.

Le gestionnaire de charge cFos vous permet de créer vos propres définitions de compteurs afin de prendre en charge les compteurs qui ne sont pas disponibles dans le répertoire standard. Il en existe actuellement trois types : Compteurs Modbus, Compteurs HTTP/JSON et Compteurs MQTT/JSON. Les fichiers de définition de ces compteurs sont très similaires. Les compteurs Modbus lisent leurs données via Modbus à partir de certains registres, tandis que les compteurs HTTP/JSON récupèrent leurs données via HTTP Request et analysent JSON en réponse. Pour les compteurs MQTT/JSON, le cFos Charging Manager s'abonne aux topics MQTT et analyse les messages publiés sous le topic en tant que JSON. Pour l'analyse, le cFos Charging Manager utilise un petit "query language". Voici la documentation des capacités MQTT dans cFos Charging Manager.

Les compteurs définis par l'utilisateur peuvent lire des variables inconnues définies par l'utilisateur, interroger des entrées et définir des sorties, en plus d'une série de variables prédéfinies, comme le courant et la tension. La lecture de variables et l'activation de sorties permettent d'évaluer des formules. En combinaison avec les variables du gestionnaire de charge et les sorties globales du gestionnaire de charge décrites plus loin, il s'agit d'une fonction puissante qui permet même d'effectuer certaines tâches de domotique et de commander des appareils externes tels que des accumulateurs. Si vous réalisez des tâches de contrôle avec ce système, n'hésitez pas à nous donner votre avis. Nous sommes très intéressés par ce que les gens contrôlent avec le Charging Manager de cFos et cela nous aide à développer le Charging Manager en fonction des besoins des clients.

Voici un exemple simple de définition pour Modbus, qui lit un seul registre pour la puissance active. Vous pouvez facilement modifier le numéro de registre pour votre application concrète :
Exemple de définition pour un seul registre.

Voici un exemple de définition pour Modbus et un autre pour HTTP/JSON :
Télécharger un exemple de définition pour le compteur Modbus
Télécharger un exemple de définition pour le compteur HTTP/JSON

Le Charging Manager est déjà livré avec quelques fichiers de ce type, mais vous pouvez télécharger vos propres fichiers sous "Configuration du système" et également les supprimer à nouveau.
Vous trouverez ici la plupart des définitions de compteurs que nous fournissons :
Télécharger les définitions des compteurs fournies

Si vous avez créé votre propre fichier de comptage et qu'il pourrait être utile à d'autres utilisateurs, nous vous serions très reconnaissants de le mettre à notre disposition. Nous le livrerons alors avec les futures versions du Charging Manager.

Télécharger les définitions des compteurs pour les compteurs supplémentaires

Structure d'un fichier de définition :

Les définitions de compteurs sont des fichiers JSON avec un objet JSON global qui possède des propriétés et des sous-objets. rtype' détermine le type d'opération de lecture : 0 = Modbus, 1 = HTTP/JSON, 2 = MQTT/JSON. 'mtype' détermine le type d'appareil : 0 = autre appareil, 1 = compteur, 2 = onduleur, 4 = stockage sur batterie.

Les nombres peuvent être indiqués au choix en décimal ou en hexadécimal avec le préfixe 0x. En outre, les commentaires d'une seule ligne sont autorisés au moyen de //. Nous recommandons de faire passer vos fichiers de définition par un validateur JSON5, par ex. ce validateur JSON5

Vous devez absolument avoir lu le chapitre Formules pour comprendre quelles valeurs peuvent être utilisées dans les formules de la référence suivante.

Les définitions Modbus possèdent un objet 'rtu' avec les propriétés suivantes :

silence_period, déterminé en msec., la longueur de la pause avant un accès Modbus RTU, afin que l'appareil détecte le début d'un message.
silence_same_slave, true : la pause est respectée même en cas d'accès multiples au même appareil.
retries: le nombre de répétitions si l'appareil ne répond pas.
rcv_timeout: en msec. le temps d'attente maximal par accès avant que l'appareil ne réponde.

Ces propriétés globales sont valables pour Modbus TCP et RTU :

modbus_read: Le numéro de fonction de la commande de lecture Modbus, généralement 3 ou 4.
modbus_read_max_registers: Le nombre maximum de registres lisibles à la fois.
modbus_allow_gaps: true = Les zones de registre non utilisées peuvent être lues dans une opération de lecture.

Pour Modbus TCP et HTTP/JSON, il existe un objet 'tcp' avec les propriétés suivantes :

connect_timeout: is msec. le temps d'attente maximum pour une connexion TCP.
delay_after_connect: in msec. Pause après l'établissement de la connexion avant l'envoi de la première commande.

Les deux types de définition (Modbus et HTTP/JSON) ont en outre les propriétés suivantes :

upd_delay: en msec. détermine l'intervalle dans lequel un appareil peut être lu. Certains appareils sont surchargés s'ils sont interrogés trop souvent.
manufacturer: chaîne de caractères, nom du fabricant. Ceci est affiché dans les informations étendues de la tuile.
delay_accumulated: true = les valeurs accumulées (kWh) ne sont interrogées que toutes les 3 secondes ou lorsque la puissance est suffisante. false = ces valeurs sont toujours interrogées en même temps.
ui_addr: URL, si elle diffère de l'adresse de l'appareil pour appeler l'interface web.
reserved: Tableau de valeurs interprétées comme 0 (utile si l'appareil supporte certaines valeurs en fonction du modèle).

Si vous omettez les propriétés énumérées ci-dessus, le cFos Charging Manager prend des valeurs par défaut qui fonctionnent bien dans la plupart des cas.

Dans la définition JSON, l'étape suivante consiste à définir les variables que le compteur utilise pour lire ou calculer les valeurs de courant, de tension, etc. Le Charging Manager connaît les variables suivantes :
type_designation, version, firmware_version, serial: elles constituent la désignation du modèle, comme indiqué dans les infos étendues de la tuile. Elles sont demandées une fois lors de la configuration ou de la réinitialisation du compteur.
voltage_l1..voltage_l3, current_l1..current_l3, power_w, power_var, power_va, power_w_l1..power_w_l3: Le gestionnaire de charge cFos tente de calculer à partir de ces valeurs voltage_l1..l3, current_l1..l3 signé, power_w et power_va. Il n'est pas nécessaire d'indiquer toutes les variables. Le gestionnaire de charge cFos tente de calculer les valeurs à partir des variables existantes.
import_wh, export_wh: le gestionnaire de charge utilise ces variables pour afficher import_wh et export_wh. Pour les compteurs unidirectionnels (par ex. les onduleurs), vous devriez toujours définir uniquement import_wh. Ce n'est que pour les compteurs bidirectionnels (comme les accumulateurs ou les compteurs de référence du réseau) qu'il faut définir export_wh.

soc: si elle est disponible, l'état de charge d'un accumulateur est affiché ici en % dans la tuile.
De plus, vous pouvez définir d'autres variables avec un autre nom qui seront lues ou calculées à l'aide de formules lors de chaque mise à jour. Si vous définissez des variables commençant par CM., par ex. CM._set_price, les valeurs attribuées sont enregistrées dans les variables globales Charging Manager (voir ci-dessous) et peuvent être consultées en conséquence.
Variables avec *: Si vous définissez des variables commençant par *, elles sont affichées dans l'UI sur la tuile du compteur sous Informations avancées, par exemple la température d'un accumulateur.

Définition d'une variable :

L'objet est nommé d'après le nom des variables listées ci-dessus et possède les propriétés suivantes :
fixed: chaîne de caractères avec valeur fixe. Utile si, par exemple, aucune valeur ne peut être déterminée, par exemple pour type_designation ou tension.
expr: Chaîne, la variable n'est pas lue, mais évaluée comme une formule.
type: Si pas fixed ou expr, le type de la variable : int16, uint16, int32, uint32, float, int64, string. Ceci est important pour Modbus afin de pouvoir lire les registres dans le bon format. uint16 et uint32 sont des types qui ne peuvent accepter que des nombres positifs. Pour JSON/HTTP, on peut généralement prendre float.
resolution: float, la valeur lue est multipliée par 'resolution'. Les valeurs de tension doivent être en volts, les courants en milliampères, les puissances en watts, l'énergie en watts-heures (Wh). Une 'resolution' négative permet d'inverser une valeur si celle-ci est de signe inverse.
once: bool (true ou false), si true, la valeur n'est lue qu'une seule fois à l'initialisation de l'appareil, sinon périodiquement.
address: number (Modbus) ou String (HTTP/JSON), le numéro de registre Modbus ou l'URL HTTP de la valeur à lire.
query: String, pour HTTP JSON, l'indication dans le query language du Charging Manager, avec laquelle il trouve la valeur à lire dans la réponse JSON.
order: String, pour Modbus l'ordre des octets, soit "hl" soit "lh", dans lequel la valeur est présente. length: number, pour Modbus la longueur d'une chaîne dans les registres. Pour les variables 'version' et 'firmware_version', 'length' est utilisé pour transformer des versions numériques en chaînes de caractères avec des points. Dans ce cas, des valeurs de 2 ou 4 sont autorisées pour 'length', ce qui résulte alors dans les formats de version a.b, et a.b.c.d. Pour 'length' 2 et le type 'int16' ou 'uint16', le Charging Manager sépare low et high byte par un point, pour 'int32' ou 'uint32' low et high word, pour 'int64' low et high dword. Pour 'lenth' 4 et 'int32' ou 'uint32', le Charging Manager décompose la valeur en 4 octets séparés par un point. Pour 'int64', les 4 mots en conséquence.
regex: Chaîne. Si une expression régulière est indiquée, la réponse du compteur n'a pas besoin d'être en JSON. Le résultat est soit la totalité de la correspondance de l'expression régulière, soit le premier groupe. A n'utiliser que si l'appareil ne renvoie pas de JSON. Voici la liste des caractéristiques de nos expressions régulières :
any char: .
named classes: \d \s \w \D \S \W
anonymous classes: [a-z0-9_], [^0-9], [^\d]
groups with alternatives: (ab|cd|ef)
non-captured groups: (?:ab|cd)
(greedy) once or none: a ?, a ??
(greedy) many or none: a*, a* ?
(greedy) once or more: a+, a+ ?
begin of string: ^
end of string: $

Définition des intrants :

Pour chaque appareil, le Charging Manager peut demander jusqu'à 32 valeurs d'entrée à partir de différents registres ou éléments JSON. La propriété "Inputs" est un tableau JSON. Pour chaque input, vous devez définir les propriétés suivantes :
address: adresse (registre Modbus ou URL).
count: Nombre de bits d'entrée qui seront lus avec cette requête.
query: Pour HTTP/JSON, query language, pour trouver la valeur dans la réponse.

Le gestionnaire de charge cFos lit à chaque mise à jour toutes les entrées ainsi définies et place les bits en interne dans un tableau qui peut ensuite être interrogé avec des formules, Input1..InputN.

Définition des extrants :

Le Charging Manager peut commuter jusqu'à 32 sorties par appareil. Les sorties sont définies sous "outputs" comme un tableau JSON d'objets de sortie. Toutes les sorties sont activées à la fin de chaque cycle de mise à jour, dans la mesure où l'état de la sortie correspondante a changé.
Pour chaque sortie, vous devez définir les propriétés suivantes dans l'objet de sortie :
address: URL HTTP avec méthode HTTP optionnelle, par ex. GET http://www.example.com?output1=${var1}. Pour définir des registres Modbus, vous pouvez utiliser l'API HTTP du cFos Charging Manager. Le Charging Manager reconnaît les accès appropriés à localhost et redirige la demande vers le handler interne, de sorte que vous n'avez pas besoin d'autorisation comme pour les accès HTTP API externes. Si l'URL est vide après tous les remplacements, aucune sortie n'est définie. Ainsi, il est par exemple possible de ne commuter des outputs que si certaines variables existent (voir formules : fonction exists()). Dans l'adresse, on peut en outre indiquer ${address} et ${id}. Il s'agit de l'adresse actuelle de l'appareil et de l'ID Modbus, comme défini dans les paramètres. Address et id servent surtout à utiliser l'API Modbus (voir ci-dessous).
body: corps HTTP optionnel pour POST ou PUT.
Dans l'URL et le body, vous pouvez utiliser des formules au moyen de ${expr} qui référencent des variables globales Charging Manager ou du compteur correspondant. La formule 'expr' est évaluée lors de la définition de la sortie et remplacée dans le texte de l'URL ou du body. Dans l'exemple ci-dessus, si http://www.example.com?output1=1 définit la sortie et que http://www.example.com?output1=0 la supprime, vous pouvez définir une variable 'var1' et lui attribuer la valeur 1 ou 0 comme vous le souhaitez. De cette manière, vous pouvez également écrire des valeurs numériques dans les registres Modbus pour contrôler les performances de la mémoire, valeurs que vous avez préalablement enregistrées dans une variable au moyen d'une formule.
Si, au lieu de transmettre une valeur numérique dans l'URL, vous devez remplacer un texte par un autre selon la formule, comme par exemple pour les prises WLAN Shelly, vous pouvez l'écrire ainsi : ${if expr`text1`text2}. L'"apostrophe" est une barre oblique inverse (code ASCII 96). Si le 'expr' != 0, text1 est inséré, sinon text2. Pour la prise Shelly WLAN, l'URL ressemble par exemple à ceci : http://<ip-addr>/relay/0?turn=${if expr`on`off}, c.-à-d. que si expr != 0, le Charging Manager appelle alors http://<ip-addr>/relay/0?turn=on, sinon http://<ip-addr>/relay/0?turn=off.

Si vous indiquez un chemin relatif comme URL, le gestionnaire de charge prend l'adresse configurée pour l'appareil concerné. Si vous indiquez 'localhost' comme domaine, le Charging Manager prend l'adresse de l'appareil sur lequel il fonctionne. S'il reconnaît ce faisant un accès à sa propre API, il utilise le gestionnaire interne au lieu d'exécuter un accès HTTP complet, de sorte que vous n'avez pas besoin de définir un nom d'utilisateur et un mot de passe dans la définition du compteur. Une URL commençant par un * incite le gestionnaire de chargement à toujours exécuter un accès HTTP complet.

Réinitialiser les "outputs" : En plus d'un tableau "outputs", il est possible de définir un tableau "resets" construit comme le tableau "outputs". Ainsi, les sorties peuvent être remises à leurs valeurs initiales lorsque l'appareil est désactivé. Ceci permet, en combinaison avec des variables définies par l'utilisateur et "once" : true, de remettre l'appareil dans son état initial.
Écrire périodiquement les outputs : Pour certains appareils, les sorties doivent être écrites périodiquement, sinon l'appareil remet les valeurs à leur état "standard". Par exemple, la mémoire Kostal utilise à nouveau ses règles standard si la commande de la mémoire n'a pas été écrite activement pendant un certain temps. Pour définir des sorties périodiques, vous pouvez faire précéder l'adresse d'un #xxx#, où xxx indique le nombre de secondes pendant lesquelles la sortie est réécrite, même si la valeur à écrire est restée la même. Par exemple, si l'adresse est /cnf?cmd=set_cm_vars&name=test&val=42, vous pouvez utiliser #30#/cnf?cmd=set_cm_vars&name=test&val=42 pour faire en sorte que cette valeur soit écrite toutes les 30 secondes.

Définition de la query langage :

Actuellement, les noms de membres et les opérateurs "." et "[]" peuvent être utilisés dans les expressions de recherche "query", exemples :

testÉlément nommé " test "
nom1.nom2L'élément nommé "nom2" dans l'objet enfant "nom1"
nom[idx]Élément "idx" de l'élément d'objet "name". "idx" peut être un nombre, par exemple pour les tableaux, ou une chaîne de caractères
nom["u2"]Élément "u2" de l'élément objet "name", correspond à "name.u2"
name[{"el1" : "v1", "el2" : 3}].valueSélectionnez l'élément du tableau qui remplit la condition de la notation d'objet et évaluez l'élément nommé 'valeur'. Ici, par exemple, dans le tableau 'nom', on sélectionne l'élément qui a pour objet 'el1' avec la valeur 'v1' et 'el2' avec la valeur 3, puis on retourne la valeur de l'élément 'valeur' à partir de cet objet.

Variables globales du gestionnaire de charge :

Dans la configuration du Charging Manager, vous pouvez créer des variables. Vous pouvez utiliser une valeur fixe ou une formule comme valeur. A la fin de chaque cycle de mise à jour, le Charging Manager recalcule la valeur de ces variables, le cas échéant. Vous pouvez ensuite les utiliser dans (certains) paramètres du Charging Manager, dans les règles de chargement ou pour contrôler les sorties. Vous pouvez également écrire Ex.member ou Mx.member comme variable. Dans ce cas, Exet Mxsont les ID des appareils d'une Wallbox ou d'un compteur configuré dans le Charging Manager. member est une variable "définie par l'utilisateur" qui est enregistrée dans l'appareil correspondant. Certaines variables peuvent avoir une signification particulière : Pour KEBA, "out1" est une sortie de commutation, pour les compteurs ABB B23, "out1" et "out2" sont des sorties de commutation (pour les modèles qui le supportent). Un 1 active la sortie, un 0 la désactive.

Si vous avez des appareils qui doivent être mis en marche dans certaines conditions, mais qui doivent ensuite fonctionner pendant un certain temps (par ex. machine à laver, lave-vaisselle), vous pouvez également définir la variable comme "déclencheur". Dans ce cas, la formule de la variable est la condition par laquelle la variable est mise à 1. Après un temps réglable, elle est remise à 0. Une "condition de redéclenchement" permet de prolonger le temps jusqu'à l'arrêt (c.-à-d. la mise à 0 de la variable) tant que la condition est remplie.

À des fins de test, vous pouvez afficher les variables du gestionnaire de charge et du compteur, ici par exemple les prix actuels d'Awattar :


                        Capture d'écran Affichage des variables de comptage

Sorties globales du gestionnaire de charge :

Dans la configuration du Charging Manager, vous pouvez configurer des sorties globales, comme décrit ci-dessus dans la définition du compteur sous 'Outputs'. Celles-ci sont activées à la fin de chaque cycle de mise à jour, si leur état a changé. Si vous souhaitez commander des sorties de commutation dans des appareils définis par l'utilisateur, il est recommandé d'utiliser la convention ci-dessus (voir Charging Manager Variables) : Vous définissez dans le compteur défini par l'utilisateur des variables nommées "out1", "out2", etc. et configurez dans le compteur défini par l'utilisateur des sorties qui commutent la sortie en fonction de la valeur de ces variables.

API Modbus globale du gestionnaire de charge :

L'API Modbus du Charging Manager sert à piloter des appareils Modbus qui ont une adresse Modbus RTU ou TCP quelconque (accessible par le Charging Manager). Comme adresse pour Modbus RTU, indiquez, comme dans la configuration des différents appareils, COMx,bd,8,p,s, où x est le numéro du port COM, bd la vitesse de transmission, p la parité ('N', 'E' ou 'O') et s le nombre de bits d'arrêt (1 ou 2). Pour Modbus TCP, l'adressee est l'adresse IP de l'appareil dans le réseau du Charging Manager, y compris le numéro de port.
L'URL (pour HTTP GET) de l'API Modbus est la suivante :
/cnf?cmd=modbus_get ou /cnf?cmd=modbus_set
Le gestionnaire de charge cFos supporte les autres paramètres query suivants :
addr: L'adresse de l'appareil Modbus RTU ou TCP mentionnée ci-dessus.
func: Numéro de fonction Modbus, par ex. pour la lecture 3 ou 4, pour l'écriture 6 ou 16.
id: ID de l'appareil Modbus.
reg: Le numéro de registre Modbus. La valeur peut être indiquée en décimal ou en hex (avec le préfixe 0x).
val: numéro, valeur à écrire dans le registre. Omettre lors de la lecture.
type: 'w' 16bit (default), d = 32bit, f = float, q = 64bit, s = string.
cnt: number, la longueur maximale de la chaîne dans les registres, à omettre pour les autres types ou à mettre à 1.
order: String, l'ordre des octets, soit "hl" soit "lh".

Remarque: si votre 'compteur' a principalement des fonctions de contrôle, vous pouvez cocher l'option 'Masquer le périphérique' dans les paramètres de cette vignette afin que ce périphérique n'apparaisse pas sur la page d'accueil.

Remarque: certains compteurs lus via HTTP nécessitent un nom d'utilisateur/mot de passe comme autorisation. Vous pouvez l'indiquer dans l'adresse pour l'accès HTTP, par ex. avec http://username:password@192.168.2.111. Si votre nom d'utilisateur ou votre mot de passe contient un "@", vous devez le remplacer par "%40".