API EDRT

API v2.00.33

Introduction

API EcoDevice RT2
Nom			API EcoDevice RT2
Famille			EcoDevice RT2

L'ensemble de l'API est protégée par une clef secrète. Par défaut, cette clef est : « apikey ». Elle est bien sur paramétrable et il est également possible de supprimer cette protection.

Lors de l'utilisation de l'API M2M, la clef n'est demandée qu'une seule fois par connexion. Cependant, lors de l'utilisation de l'API JSON, il sera nécessaire de renseigner cette clef à chaque commande.

Pour cela, dans tous les cas, il vous suffira de la placer en premier argument de la manière suivante :

« key=apikey ».

Les requêtes JSON commenceront donc de la manière suivante : « http://EcoDevices_RT/api/xdevices.json?key=apikey&... ». Elles pourront également comprendre plusieurs commandes à la fois (même si cela aura un impact sur la réponse).

Enfin, les requêtes de l'API M2M devront être effectuées après une connexion TCP client (port 9870 par défaut). Cette connexion ne sera cependant possible qu'après l'activation du M2M (menu « http://EcoDevices_RT/admin/m2m.htm »). Un message « key=apikey » devra ensuite être envoyé afin de s'authentifier. Chaque message sera porteur d'une seule commande.

Lorsque la clef est désactivée, l'argument « key » est inutile.

Le tableau suivant récapitule les commandes disponibles dans les deux API. Ces commandes sont générales, elles peuvent être utilisées sur l'une ou l'autre des API (même si le format des trames n'est pas tout à fait le même). Les réponses sont, quant à elle, différentes et seront ensuite détaillées API par API

Remarque : :les en-têtes des réponses peuvent être supprimés dans les réponses de l'API M2M. La réponse type à un Get=R serait alors directement une suite de '0' ou '1' sans rien avant (cet exemple s'applique a toutes les réponses types).

Commandes

Commande	Argument	Paramètre(s)	Exemple(s)
Set (commande permettant de mettre à 1 l'état d'un élément de l'EcoDevices RT ou de modifier la valeur de ce dernier)	R (les sorties relais de l'Eco Devices RT et des extensions)	- xx : numéro de la sortie entre 01 et 10	SetR=01 (met le relais 1 à 1) SetR=10 (relais 10 à 1)
	VO (les sorties virtuelles)	- xxx : numéro de la sortie virtuelle entre 0x1 et 128	SetVO=001 (met la sortie virtuelle 1 à 1) SetVO=128 (sortie 128 à 1)
	C (les compteurs)	- xx : numéro du compteur de 01 à 12 - l'opérateur (optionnel, lorsqu'il n'y en a pas, il s'agit d'une modification directe du compteur) qui peut être '+' (incrémentation) ou '-' (décrémentation) - y : la valeur de modification (de 0 à 255)	SetC01=0 (met le compteur 1 à 0) SetC08=+2 (incrémente le compteur 8 de 2) SetC12=-200 (décrémente le compteur 12 de 200)
		- l'opérateur (optionnel, lorsqu'il n'y en a pas, il s'agit d'une modification directe du compteur) qui peut être '+' (incrémentation) ou '-' (décrémentation) - y : la valeur de modification SetC=0 (met l'ensemble des compteurs à 0)	SetC=+50 (incrémente l'ensemble des compteurs de 50) SetC=-150 (décrémente l'ensemble des compteurs de 150)
	FP (extension Fil Pilote)	- xx : le numéro de la zone souhaité de 00 à 08 (de 01 à 04 pour la première extension, de 05 à 08 pour la seconde, 00 permettant le pilotage de l'ensemble des zones) -y : la commande : 0 pour confort, 1 pour Eco, 2 pour Hors Gel, 3 pour Arrêt, 4 pour Confort -1 et 5 pour Confort -2	SetFP00=1 (met l'ensemble des zone en ECO) SetFP05=3 (arrête la zone 1 de la seconde extension)
EnoPC (Actionneur Enocean)	X : le numéro de l'actionneur de 1 à 24	SetEnoPC=8 (actionneur 8 à 1)
Clear (commande permettant de mettre à 0 l'état d'un élément de l'EcoDevices RT)	R (les sorties relais de l'EcoDevices RT et des extensions)	- xx : numéro de la sortie entre 01 et 10	ClearR=02 (met le relais 2 à 0) ClearR=10 (relais 10 à 0)
	VO (les sorties virtuelles)	- xxx : numéro de la sortie virtuelle entre 001 et 128	ClearVO=002 (met la sortie virtuelle 1 à 0) ClearVO=127 (sortie 127 à 0)
	EnoPC (Actionneur Enocean)	X : le numéro de l'actionneur de 1 à 24	ClearEnoPC=7(Actionneur 7 à 0)	Toggle (commande permettant de faire un switch de l'état d'un élément de l'EcoDevices RT)	R (les sorties relais de l'EcoDevices RT et des extensions)	- xx : numéro de la sortie entre 01 et 10	ToggleR=03 (toggle le relais 2) ToggleR=10 (toggle le relais 10 à 0)
VO (les sorties virtuelles)	- xxx : numéro de la sortie virtuelle entre 001 et 128 ToggleVO=003 (toggle la sortie virtuelle 3)	ToggleVO=127 (sortie 127 à 0)
EnoPC (Actionneur Enocean)	X : le numéro de l'actionneur de 1 à 24	ToggleEnoPC=3 (toggle l'actionneur 3)
BitMask (commande permettant de modifier l'état d'un groupe d'élément de l'EcoDevices RT)	R - les états (par groupe de huit) des relais correspondants. Il peut y avoir de 2 à 10 états (EcoDevices_RT + 1 extensions) dans la même commande.	BitMaskR=00 (pilote les 2 relais de l'EcoDevices RT) BitMaskR=0000000000 (pilote les 2 relais de l'EcoDevices RT et les 8 de l'extension)	VO - les 128 états	BitMaskVO=00000000000000000000000000000000...000 (pilote les 128 sorties virtuelles)
	Index C (commande permettant d'obtenir l'index des 12 compteurs de l'Eco Devices RT) / Index=C API JSON http://EcoDevices_RT/api/xdevices. json?Index=C (sans clef) T (commande permettant d'obtenir l'index des 16 tores de l'Eco Devices RT et des extensions même non câblées) / Index=T API JSON http://EcoDevices_RT/api/xdevices. json?Index=T (sans clef) GCE Electronics 01/02/2017 4 (commande permettant de connaître les index globaux de l'Eco Devices RT) E (commande permettant d'obtenir l'ensemble des index de télé- information EDF disponible sur l'Eco Devices RT) / Index=E API JSON http://EcoDevices_RT/api/xdevices. json?key=apikey&Index=E (avec clef) P (commande permettant d'obtenir les index de l'ensemble des postes de l'Eco Devices RT) / Index=P API JSON http://EcoDevices_RT/api/xdevices. json?Index=P (sans clef) S (commande permettant d'obtenir les index de l'ensemble des souspostes de chaque poste de l'Eco Devices RT) / Index=S API JSON http://EcoDevices_RT/api/xdevices. json?key=apikey&Index=S (avec clef) all (commande permettant d'obtenir tous les index de l'Eco Devices RT) Cette commande est uniquement disponible en JSON ! / Index=all http://EcoDevices_RT/api/xdevices. json?Index=all (sans clef) DIndex (commande permettant de connaître les index du jour de l'Eco Devices RT) P (commande permettant d'obtenir les index journaliers de l'ensemble des postes de l'Eco Devices RT) / DIndex=P API JSON http://EcoDevices_RT/api/xdevices. json?key=apikey&DIndex=P (avec clef) S (commande permettant d'obtenir les index journaliers de l'ensemble des souspostes de chaque poste de l'Eco Devices RT) / DIndex=S API JSON http://EcoDevices_RT/api/xdevices. json?key=apikey&DIndex=S (avec clef) C (commande permettant d'obtenir le cumul de prix des 12 compteurs de l'Eco Devices RT) / Price=C API JSON http://EcoDevices_RT/api/xdevices. json?Price=C (sans clef) GCE Electronics 01/02/2017 5 Price (commande permettant de connaître les cumuls globaux de prix de l'Eco Devices RT) T (commande permettant d'obtenir le cumul de prix des 16 tores de l'Eco Devices RT et des extensions même non câblées) / Price=T API JSON http://EcoDevices_RT/api/xdevices. json?key=apikey&Price=T (avec clef) E (commande permettant d'obtenir l'ensemble des cumuls de prix de télé-information EDF disponible sur l'Eco Devices RT) / Price=E API JSON http://EcoDevices_RT/api/xdevices. json?Price=E (sans clef) P (commande permettant d'obtenir les cumuls de prix de l'ensemble des postes de l'Eco Devices RT) / Price=P API JSON http://EcoDevices_RT/api/xdevices. json?key=apikey&Price=P (avec clef) S (commande permettant d'obtenir les cumuls de prix de l'ensemble des sous-postes de chaque poste de l'Eco Devices RT) / Price=S API JSON http://EcoDevices_RT/api/xdevices. json?Price=S (sans clef) all (commande permettant d'obtenir tous les cumuls de prix de l'Eco Devices RT) Cette commande est uniquement disponible en JSON ! / Price=all API JSON http://EcoDevices_RT/api/xdevices. json?Price=all (sans clef) DPrice (commande permettant de connaître les cumuls globaux de prix de l'Eco Devices RT) P (commande permettant d'obtenir les cumuls de prix journalier de l'ensemble des postes de l'Eco Devices RT) / DPrice=P API JSON http://EcoDevices_RT/api/xdevices. json?key=apikey&DPrice=P (avec clef) S (commande permettant d'obtenir les cumuls de prix journalier de l'ensemble des souspostes de chaque poste de l'Eco Devices RT) / DPrice=S API JSON http://EcoDevices_RT/api/xdevices. json?DPrice=S (sans clef) GCE Electronics 01/02/2017 6 Get (commande permettant de connaitre l'etat d'un groupe d'element de l'EDRT) TI (commande permettant d'obtenir l'ensemble de la télé-information EDF disponible sur l'Eco Devices RT) / Get=TI API JSON http://EcoDevices_RT/api/xdevices. json?key=apikey&Get=TI (avec clef) P (commande permettant d'obtenir les valeurs instantanées de l'ensemble des postes de l'Eco Devices RT) / Get=P API JSON http://EcoDevices_RT/api/xdevices. json?Get=P (sans clef) S (commande permettant d'obtenir les valeurs instantanées de l'ensemble des souspostes de chaque poste de l'Eco Devices RT) / Get=S API JSON http://EcoDevices_RT/api/xdevices. json?key=apikey&Get=S (avec clef) R (commande permettant d'obtenir l'état des 10 relais de l'Eco Devices RT et des extensions même si elles ne sont pas câblées) / Get=R API JSON http://EcoDevices_RT/api/xdevices. json?key=apikey&Get=R (avec clef) D (commande permettant d'obtenir l'état des 12 entrées digitales de l'Eco Devices RT et des extensions même si elles ne sont pas câblées) / Get=D API JSON http://EcoDevices_RT/api/xdevices. json?Get=D (sans clef) VO (commande permettant d'obtenir l'état des 128 sorties virtuelles de l'EcoDevices RT) / Get=VO API JSON http://EcoDevices_RT/api/xdevices. json?Get=VO (sans clef) C (commande permettant d'obtenir l'état des 12 compteurs de l'EcoDevices RT) / Get=C API JSON http://EcoDevices_RT/api/xdevices. json?Get=C (sans clef) X xxx : le nom de l'extension Get=XENO GCE Electronics 01/02/2017 7 (commande permettant d'obtenir l'état des éléments d'une extension, pour l'instant seule les périphériques Enocean et les X-THL sont intégrés) (actuellement ne fonctionne qu'avec ENO et THL) API JSON http://EcoDevices_RT/api/xdevices. json?Get=XENO (sans clef) FP (commande permettant d'obtenir l'état des 16 zones des différentes X4FP) / Get=FP API JSON http://EcoDevices_RT/api/xdevices. json?Get=FP all (Commande dédié) / Get=all API JSON http://EcoDevices_RT/api/xdevices. json?Get=FP Dall (Commande dédié) / Get=Dall API JSON http://EcoDevices_RT/api/xdevices. json?Get=FP Reset / Remarque : Pour les commandes Set, Clear et Toggle des relais, entrées et sorties virtuelles il est possible de mettre plusieurs paramètres séparés par une virgule comme dans l'exemple suivant : « http://EcoDevices_RT/api/xdevices.json?key=apikey&SetR=01,02 » qui met les 2 relais de l' Eco Devices RT à 1. Remarque pour l'API JSON uniquement : il faut ajouter « http://EcoDevices_RT/api/xdevices.json?key=apikey& »avant la commande donnée en exemple (cf. les exemples donnés pour la commande Get...). Les commandes peuvent également être ajoutées les unes après les autres (une seule commande Get prise en compte) en étant séparées par un & : « http://EcoDevices_RT/api/xdevices.json?key=apikey&cmd1&cmd2 ». Pour ajouter plusieurs commandes Get, il est possible de séparer les arguments par un caractère '|' de la manière suivante : « http://EcoDevices_RT/api/xdevices.json?key=apikey&Get=Arg1%7CArg2%7C Arg3 ». Cette commande est cependant à utiliser avec parcimonie afin de ne pas consommer trop de ressources. Le nombre d'argument est limité à 10 mais il n'est pas conseillé de dépasser les 5 arguments. Enfin, ce type de commande n'est pas compatible avec l'argument « X ». GCE Electronics 01/02/2017 8 Inclure des étiquettes dans les notifications (mail, push et GSM) Il est possible d'inclure des étiquettes de l'EDRT dans vos push en utilisant le signe « $ ». Plusieurs étiquettes peuvent être inclues dans une même notification. Les exmples ci-dessous sont purement théorique, les nom de variable, de page ou autre sont libre. Argument Paramètre(s) optionnel(s) Exemple Retour M : l'adresse MAC / 192.168.1.100/mapag e.htm?data=$M 192.168.1.100/mapage.htm ?data=00:04:A3:87:00:1F D: les entrées digitales xx : le numéro de l'entrée digital (sans ce paramètre les 12 états des entrées sont renvoyées) compris entre 01 et 12. 192.168.1.100/mapag e.htm? data=$D01&$D 192.168.1.100/mapage.htm ?data=0&010101... R : les relais xx : le numéro du relais (sans ce paramètre les 10 états des relais sont renvoyées) compris entre 01 et 10. 192.168.1.100/mapag e.htm?data=$R08&$R 192.168.1.100/mapage.htm ?data=1&010101... A : les entrées analogiques xx : le numéro de l'entrée analogique (sans ce paramètre les valeurs des 4 entrées analogiques sont renvoyées) compris entre 01 et 04. 192.168.1.100/mapag e.htm? data=$A04&$A 192.168.1.100/mapage.htm ? data=200&10&20&30&20 0 C : les compteurs xx : le numéro du compteur (sans ce paramètre les valeurs des 12 compteurs sont renvoyées) compris entre 01 et 16. 192.168.1.100/mapag e.htm?data=$C09&$C 192.168.1.100/mapage.htm ?data=20&10&20&30&... VO : les sorties virtuelles xxx : le numéro de la sortie virtuelle (sans ce paramètre les 128 états des sorties virtuelles sont renvoyées) compris entre 001 et 128. 192.168.1.100/mapag e.htm? data=$VO008&$VO 192.168.1.100/mapage.htm ?data=1&010101... FP : les états des zones fils pilotes xx : le numéro de la zone entre 01 et 16 (de 01 à 04 pour la première extension, de 05 à 08 pour la seconde, …, de 13 à 16 pour la 4). Sans ce paramètre les 16 états sont renvoyés 192.168.1.100/mapag e.htm? data=$FP01&$FP 192.168.1.100/mapage.htm ? data=Confort&Confort&Ar rêt... XENO xx : le numéro du périphérique souhaité entre 01 et 48 (de 01 à 24 pour les actionneurs ou wall plug, de 25 à 48 pour les capteurs analogiques (→ ces derniers n'intègrent pas les compteurs correspondant). Il est possible de remplacer ce paramètre par un 'A' pour obtenir tous les capteurs analogiques où un 'W' pour les Wall Plug. 192.168.1.100/mapag e.htm? data=$XENO08&$X ENOA 192.168.1.100/mapage.htm ?data=1&25.2&65.5&.. THL : les états des XTHL xx : le numéro de la valeur analogique entre 01 et 06 (de 01 à 03 pour la première extension, de 04 à 06 pour la seconde). La température étant en 1 et 4 l'humidité en 2 et 5 et la luminosité en 3 et 6. Sans ce paramètre les 6 états sont renvoyés 192.168.1.100/mapag e.htm? data=$THL01&$THL 192.168.1.100/mapage.htm ?data=25.2&25.2&13&.. GCE Electronics 01/02/2017 9 TS : TimeStamp / 192.168.1.100/mapag e.htm?data=$TS 192.168.1.100/mapage.htm ? data=2017/01/16T14:52:30 +01:00 IP : les index des postes xx : le numéro du poste de 01 à 08. Sans ce paramètre les 8 postes sont renvoyés 192.168.1.100/mapag e.htm?data=$IP01&IP 192.168.1.100/mapage.htm ?data=2500&2500&25&.. IS : les index des souspostes xx: le numéro du sous poste allant de 01 à 64 (01 à 08 pour le poste 1, 09 à 16 pour le poste 2, …, 57 à 64 pour le poste 8. Sans ce paramètre, rien ne sera renvoyé. 192.168.1.100/mapag e.htm?data=$IS01 192.168.1.100/mapage.htm ?data=1700 PP : les prix courant des postes xx : le numéro du poste de 01 à 08. Sans ce paramètre les 8 postes sont renvoyés 192.168.1.100/mapag e.htm? data=$PP02&PP 192.168.1.100/mapage.htm ?data=1000&25&50.. PS : les prix courant des sous-postes xx: le numéro du sous posute allant de 01 à 64 (01 à 08 pour le poste 1, 09 à 16 pour le poste 2, …, 57 à 64 pour le poste 8. Sans ce paramètre, rien ne sera renvoyé. 192.168.1.100/mapag e.htm?data=$PS25 192.168.1.100/mapage.htm ?data=12.53 DIP : les index journaliers des postes xx : le numéro du poste de 01 à 08. Sans ce paramètre les 8 postes sont renvoyés 192.168.1.100/mapag e.htm? data=$DIP08&DIP 192.168.1.100/mapage.htm ?data=2500&2500&25&.. DIS : les index journaliers des souspostes xx: le numéro du sous posute allant de 01 à 64 (01 à 08 pour le poste 1, 09 à 16 pour le poste 2, …, 57 à 64 pour le poste 8. Sans ce paramètre, rien ne sera renvoyé. 192.168.1.100/mapag e.htm?data=$DIS64 192.168.1.100/mapage.htm ?data=2.25 DPP : les prix courant journaliers des postes xx : le numéro du poste de 01 à 08. Sans ce paramètre les 8 postes sont renvoyés 192.168.1.100/mapag e.htm? data=$DPP07&DPP 192.168.1.100/mapage.htm ?data=25.10&25.10&25&.. DPS : les prix courant journaliers des souspostes xx: le numéro du sous posute allant de 01 à 64 (01 à 08 pour le poste 1, 09 à 16 pour le poste 2, …, 57 à 64 pour le poste 8. Sans ce paramètre, rien ne sera renvoyé. 192.168.1.100/mapag e.htm?data=$DPS12 192.168.1.100/mapage.htm ?data=2500&2500&25&.. TI : les étiquettes de Téléinforamt ion xx : le numéro de l'étiquette allant de 1 à 32 192.168.1.100/mapag e.htm?data=$TI02 192.168.1.100/mapage.htm ?data=HCHP P : les valeurs instantanées des postes xx : le numéro du poste de 01 à 08. Sans ce paramètre les 8 postes sont renvoyés 192.168.1.100/mapag e.htm?data=$P01&P 192.168.1.100/mapage.htm ?data=3500&2500&25&.. S : les valeurs instantanées xx: le numéro du sous posute allant de 01 à 64 (01 à 08 pour le poste 1, 09 à 16 pour le poste 2, …, 57 à 64 pour le 192.168.1.100/mapag e.htm?data=$S42 192.168.1.100/mapage.htm ?data=2500 GCE Electronics 01/02/2017 10 des souspostes poste 8. Sans ce paramètre, rien ne sera renvoyé. Remarque : La taille des url ON et OFF de vos push ne doit pas dépasser les 220 caractères (avec caractères spéciaux pris en compte) même avec les retours liés aux étiquettes. GCE Electronics 01/02/2017 11 Description des fichiers status,xml et status,json Des fichiers sont mis à disposition afin de récupérer les informations de l'EDRT depuis un élément IP. Ces fichiers sont protégés par les mots de passe utilisateur et administrateur. On les retrouve ainsi aux adresses IP suivantes : - http://EcoDevices_RT/admin/status.xml - http://EcoDevices_RT/admin/status.json - http://EcoDevices_RT/user/status.xml - http:// EcoDevices_RT/user/status.json Ces fichiers contiennent tous les mêmes informations formaté au choix en XML ou en JSON (certains caractères sont interdits en XML et peuvent donc entraîner des erreurs sur ces fichiers). Voici un résumé des variables disponible et de leur signification : Variable Description configmac L'adresse MAC configip L'adresse IP locale configport Le port infofirm La version de firmware date La date interne heure L'heure interne ionameXXX Les noms des différents éléments de l'EDRT avec : - le premier X : le type d'élément (1 pour les relais, 0 pour les entrées digitales, 3 pour les compteurs, 5 pour les tores) - les deux autres XX pour le numéro de l'élément (début à 0 tous les éléments sauf X-8R et X-8D qui commencent à 8) xthsXX Les valeurs des X-THL avec : - le premier X pour le numéro de l'extension (0 ou 1) - le second X : 1 pour la température, 2 pour l'humidité et 3 pour la luminosité. in L'état des 12 entrées digitales rly L'état des 10 relais rlyta L'état des Ta (à 1 si un Ta est en cours) des relais vout L'état des 128 sorties virtuelles voutta L'état des Ta (à 1 si un Ta est en cours) des sorties relais eno L'état des 24 actionneurs Enocean enoAXX L'état des capteurs analogiques Enocean avec XX le numéro du capteur de 0 à 23 x4fpXX L'état des X-4FP avec : -le premier X pour le numéro de l'extension (1 ou 2) GCE Electronics 01/02/2017 12 - le second X pour le numéro de la zone de 0 à 4 (0 pour toutes les zones) etiquetteXX Le label lié à l’étiquette de Téléinformation etiquetteECXX Le retour de la Téléinformation indexXX Renvoi l'index des étiquette de téléinformation interprétées en tant qu'index de consommation posteX Le nom des postes infoX L'index et le prix correspondant des postes X suivant la période sélectionnée dans le site (année/mois/jour) instant Les consommations instantanées des 8 postes séparées par des virgules ssposteXX Le nom des sous-postes, le premier X correspond au numéro du poste, le second au numéro du sous-poste. sspencoursXX La consommation instantanée des sous-postes, le premier X correspond au numéro du poste, le second au numéro du sous-poste. sspindexXX L'index et des sous-postes suivant la période sélectionnée dans le site (année/mois/jour), le premier X correspond au numéro du poste, le second au numéro du sous-poste. ssptodayXX L'index journalier des sous-postes, le premier X correspond au numéro du poste, le second au numéro du sous-poste. trade La tendance des 8 postes, 1 si la tendance est négative (plus de consommation que la période précédente) 0 dans le cas contraire mois La consommation des 12 mois de l'année (en prix) séparé par des virgule. Cette variable correspond au graphique présent sur le dachboard principal. vref L'offset de tension appliqué. La tension utilisé dans le produit est vmesure+vref vmesure La tension mesuré par l'EDRT. La tension utilisé dans le produit est vmesure+vref gsmco Niveau de réseau Gsm de 0 à 3 gsmnetwork Le nom du réseau auquel est connecté la X-GSM gsmpin L'état de la carte SIM vis-à-vis du code pin ddnsstate Le retour d'info fourni pas le DDNS periodeencours La période tarifaire courante suivant les prix variable prixcourantXXXX Le prix global avec le deux premiers X : 3 pour les compteurs, 5 pour les pinces ampèremétrique, 64 pour les index de téléinformation. Les deux derniers X correspondent au numéro du compteur, de la pince ou de l'index de TIC respectivement de 0 à 11, de 0 à 15 et de 0 à 6. indexcourantXXXX L'index global avec le deux premiers X : 3 pour les compteurs, 5 pour les pinces ampèremétrique, 64 pour les index de téléinformation. Les deux derniers X correspondent au numéro du compteur, de la pince ou de l'index de TIC respectivement de 0 à 11, de 0 à 15 et de 0 à 6. GCE Electronics 01/02/2017