API V4

API IPX800_V4

Introduction

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://IPX800_V4/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://IPX800_V4/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 (Doc. à venir).

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'IPX800V4 ou de modifier la valeur de ce dernier) R (les sorties relais de l'IPX800V4 et des extensions) - xx : numéro de la sortie entre 01 et 56 SetR=01 (met le relais 1 à 1)

SetR=56 (relais 56 à 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) VI (les entrées virtuelles) - xxx : numéro de l'entrée virtuelle entre 001 et 128 SetVI=001 (met l'entrée virtuelle 1 à 1)

SetVI=128 (entrée 128 à 1) VA (entrées analogiques virtuelles) - xx : numéro de l'entrée analogique virtuelle de 01 à 32

- y : la valeur de modification de 0 à 65535 SetVA01=65535 (met l'entrée analogique virtuelle 1 à 65535)

SetVA32=0 (met l'entrée analogique virtuelle 32 à 0)

C (les compteurs) - xx : numéro du compteur de 01 à 16 - 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)

SetC16=-200 (décrémente le compteur 16 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)

VR

(extension volet roulant) - xx : le numéro du volet de 01 à 32 (de 1 à 4 pour la première extension, etc.)

- yyy : la valeur de modification de 0 à 100 % SetVR05=0 (met le volet 1 de la seconde extension à 0 %)

API JSON http://IPX800_V4/api/xdevices.json?SetVR02=12&SetVR05=60 (sans clef) (met le volet 4 de la troisième extension à 12 % et le volet 1 de cette même extension à 60%)

- xxx : la valeur de modification de 0 à 100 % SetVR=100 (met l'ensemble des volets connectés à l'IPX à 100%)

SetVR=50 (met l'ensemble des volets connectés à l'IPX à 50%) Pulse

(extension volet roulant, pilotage des BSO)

Cette commande ne doit pas être cumulée avec un SetVR - UP xx : le sens et le numéro du BSO de 01 à 32 (de 1 à 4 pour la première extension, etc.)

- yyy : le nombre de pulse souhaité entre 1 et 127 SetPulseUP05=20

(20 impulsions vers le haut pour le BSO 1 de la seconde extension) -DOWNxx

- yyy : le nombre de pulse souhaité entre 1 et 127 SetPulseDOWN01=2

(2 impulsions vers le bas pour le BSO 1 de la première extension) FP

(extension Fil Pilote) - xx : le numéro de la zone souhaité de 00 à 16 (de 01 à 04 pour la première extension, de 05 à 08 pour la seconde, etc. 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) SMS (commande permettant d'envoyer un SMS via la X-GSM) x : le numéro du destinataire y : le message

x et y étant séparé par deux points « : » SetSMS=+33601020304:Test GCE

SetSMS=0601020304:Test OK G

(Extension X-DIMMER) x : le pourcentage de dimmage yy : le numéro de la voie dimmée z : le temps de la rampe en milliseconde SetG=x (toutes les voies de tous les X-Dimmers sont commandées à x%)

SetGyy=x (Commande de la voie yy à x%)

SetGyy=x&Time=z (Commande de la voie yy à x% avec une rampe de z millisecondes)

Le paramètre « Time » est optionnel. Commande d’extinction : Mettre la valeur de dimmage à « 0 » Commande d’allumage à la dernière valeur de dimmage connue : Mettre la valeur de dimmage à « 101 » EnoVR (Volet roulant Enocean) - xx : le numéro du volet de 01 à 24 (de 1 à 4 pour la première extension, etc.)

- yyy : la valeur de modification de 0 à 100 % SetEnoVR01=0 (met le volet 1 à 0 %)

API JSON http://IPX800_V4/api/xdevices.json?SetVR02=12&SetVR05=60 (sans clef) (met le volet 2 à 12 % et le volet 5 à 60%) Clear

(commande permettant de mettre à 0 l'état d'un élément de l'IPX800V4) R (les sorties relais de l'IPX800V4 et des extensions) - xx : numéro de la sortie entre 01 et 56 ClearR=02 (met le relais 2 à 0)

ClearR=55 (relais 55 à 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) VI (les entrées virtuelles) - xxx : numéro de l'entrée virtuelle entre 001 et 128 ClearVI=002 (met l'entrée virtuelle 2 à 0)

ClearVI=127 (entrée 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'IPX800V4) R (les sorties relais de l'IPX800V4 et des extensions) - xx : numéro de la sortie entre 01 et 56 ToggleR=03 (toggle le relais 2)

ToggleR=54 (toggle le relais 54 à 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) VI (les entrées virtuelles) - xxx : numéro de l'entrée virtuelle entre 001 et 128 ToggleVI=002 (met l'entrée virtuelle 2 à 0)

ToggleVI=031 (entrée 31 à 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'IPX800V4) R - les états (par groupe de huit) des relais correspondants. Il peut y avoir de 8 à 56 états (IPX + 6 extensions) dans la même commande. BitMaskR=00000000 (pilote les 8 relais de l'IPX800V4)

BitMaskR=0000000000000000 (pilote les 8 relais de l'IPX800V4 et les 8 de la première extension) VO - les 128 états BitMaskVO=00000000000000000000000000000000...000

(pilote les 128 sorties virtuelles) VI - les 128 états BitMaskVI=00000000000000000000000000000000...000

(pilote les 128 entrées virtuelles) Get

(commande permettant de connaître l'état d'un groupe d'élément de l'IPX800V4) R (commande permettant d'obtenir l'état des 56 relais de l'IPX800V4 et des extensions même si elles ne sont pas câblées) / Get=R

API JSON http://IPX800_V4/api/xdevices.json?key=apikey&Get=R (avec clef) D (commande permettant d'obtenir l'état des 56 entrées digitales de l'IPX800V4 et des extensions même si elles ne sont pas câblées) / Get=D

API JSON http://IPX800_V4/api/xdevices.json?Get=D (sans clef)

A (commande permettant d'obtenir l'état des 4 entrées analogiques de l'IPX800V4) / Get=A

API JSON http://IPX800_V4/api/xdevices.json?key=apikey&Get=A (avec clef) C (commande permettant d'obtenir l'état des 16 compteurs de l'IPX800V4) / Get=C API JSON http://IPX800_V4/api/xdevices.json?Get=C (sans clef) VI (commande permettant d'obtenir l'état des 128 entrées virtuelles de l'IPX800V4) / Get=VI

API JSON http://IPX800_V4/api/xdevices.json?key=apikey&Get=VI (avec clef) VO (commande permettant d'obtenir l'état des 128 sorties virtuelles de l'IPX800V4) / Get=VO API JSON http://IPX800_V4/api/xdevices.json?Get=VO (sans clef) VA (commande permettant d'obtenir l'état des 32 entrées analogiques virtuelles de l'IPX800V4) / Get=VA API JSON http://IPX800_V4/api/xdevices,json?Get=VA (sans clef) PW (commande permettant d'obtenir l'état des 32 ping watchdog) / Get=PW API JSON http://IPX800_V4/api/xdevices.json?key=apikey&Get=PW (avec clef) X

(commande permettant d'obtenir l'état des éléments d'une extension, pour l'instant seule les extensions Enocean, DMX et PWM sont prises en compte) xxx : le nom de l'extension

(actuellement ne fonctionne qu'avec ENO et THL) Get=XENO API JSON

http://IPX800_V4/api/xdevices.json?Get=XENO (sans clef) xxx : le nom de l'extension (seules les extensions DMX et PWM sont intégrées) '|' : un séparateur yy-zz : une plage de valeur souhaitée (DMX de 1 à 512 et de 1 à 24 pour le PWM) Ces commandes sont disponibles uniquement en JSON et sont à utiliser avec parcimonie, leur fréquence d'utilisation doit être très faible. Get=XPWM|12 (uniquement le 12ème canal) ou encore Get=XPWM|1-24

API JSON http://IPX800_V4/api/xdevices.json?Get=DXM%7C1-512 VR (commande permettant d'obtenir l'état des volets d'une ou plusieurs extensions volet roulant) x : le numéro de l'extension de 0 à 8 (0 permettant l'affichage de toutes les extensions) Get=VR1

API JSON http://IPX800_V4/api/xdevices.json?Get=VR0 FP (commande permettant d'obtenir l'état des 16 zones des différentes X-4FP) / Get=FP

API JSON http://IPX800_V4/api/xdevices.json?Get=FP SMS (commande permettant d'obtenir le dernier SMS transmis à l'IPX800 V4 par la X-GSM) / Get=SMS

API JSON http://IPX800_V4/api/xdevices.json?Get=SMS G (commande permettant d’obtenir l’état des 24 voies des différents X-Dimmer) / Get=G

API JSON http://IPX800_V4/api/xdevices.json?Get=G T (commande permettant d’obtenir la consigne de température des Thermostats) / Get=T

API JSON http://IPX800_V4/api/xdevices.jsjs?Get=T

all (commande permettant d'obtenir l'état de tous les éléments de l'IPX800V4) Cette commande est uniquement disponible en JSON ! / Get=all Reset /

Remarque : Pour les commandes Set, Clear et Toggle des relais, entrées et sorties virtuelles ainsi que les commandes Set du DMX et du PWM, il est possible de mettre plusieurs paramètres séparés par une virgule comme dans l'exemple suivant : « http://IPX800_V4/api/xdevices.json?key=apikey&SetR=01,02,03,04,05,06,07,08 » qui met les 8 relais de l'IPX800V4 à 1.

Remarque pour l'API JSON uniquement : il faut ajouter « http://IPX800_V4/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://IPX800_V4/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://IPX800_V4/api/xdevices.json?key=apikey&Get=Arg1%7CArg2%7CArg3 ». Cette commande est cependant à utiliser avec parcimonie afin de ne pas consommer trop de ressources de l'IPX800V4. 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 ».

Inclure des étiquettes dans les notifications (mail, push et GSM)

Il est possible d'inclure des étiquettes de l'IPX800V4 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 noms de variable, de page ou autre sont libre.

Argument Paramètre(s) optionnel(s) Exemple Retour M : l'adresse MAC / 192.168.1.100/mapage.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 56 états des entrées sont renvoyées) compris entre 01 et 56. 192.168.1.100/mapage.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 56 états des relais sont renvoyées) compris entre 01 et 56. 192.168.1.100/mapage.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/mapage.htm?data=$A04&$A 192.168.1.100/mapage.htm?data=200&10&20&30&200 C : les compteurs xx : le numéro du compteur (sans ce paramètre les valeurs des 16 compteurs sont renvoyées) compris entre 01 et 16. 192.168.1.100/mapage.htm?data=$C09&$C 192.168.1.100/mapage.htm?data=20&10&20&30&... VI : les entrées virtuelles xxx : le numéro de l'entrée virtuelle (sans ce paramètre les 128 états des entrées virtuelles sont renvoyées) compris entre 001 et 128. 192.168.1.100/mapage.htm?data=$VI001&$VI 192.168.1.100/mapage.htm?data=0&010101... 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/mapage.htm?data=$VO008&$VO 192.168.1.100/mapage.htm?data=1&010101... VA : les entrées analogiques virtuelles xx : le numéro de l'entrée analogique virtuelle (sans ce paramètre les valeurs des 32 entrées analogiques virtuelles sont renvoyées) compris entre 01 et 32. 192.168.1.100/mapage.htm?data=$VA08&$VA 192.168.1.100/mapage.htm?data=65535&12&13&.. VR : les positions des volets roulants ou BSO xx : le numéro du volet roulant compris entre 01 et 32 (de 01 à 04 pour la première extension, de 05 à 08 pour la seconde, …, de 29 à 32 pour la huitième). Sans ce paramètre les 32 états sont renvoyés 192.168.1.100/mapage.htm?data=$VR08&$VR 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/mapage.htm?data=$FP01&$FP

XENO xx : le numéro du périphérique souhaité entre 01 et 80 (de 01 à 24 pour les interrupteurs, de 25 à 48 pour les capteurs magnétiques, de 49 à 72 pour les Wall Plug, de 73 à 96 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, un 'S' pour les interrupteurs, un 'C' pour les capteurs magnétiques où un 'W' pour les Wall Plug. 192.168.1.100/mapage.htm?data=$XENO08&$XENOA XDMX xxx : le numéro du canal souhaité entre 001 et 512 (sans ce paramètre, la commande est caduc) 192.168.1.100/mapage.htm?data=$XDMX002&XDMX512 XPWM xx : le numéro du canal souhaité entre 01 et 24 (sans ce paramètre les 24 canaux sont transmis) 192.168.1.100/mapage.htm?data=$XPWM22&XPWM01&XPWM PW: les ping watchdog xx : le numéro du ping watchdog (sans ce paramètre les 32 états des ping watchdog sont renvoyées) compris entre 01 et 32. 192.168.1.100/mapage.htm?data=$PW08&$PW 192.168.1.100/mapage.htm?data=1&010101... THL : les états des X-THL xx : le numéro de la valeur analogique entre 01 et 42 (de 01 à 03 pour la première extension, de 04 à 06 pour la seconde, …, de 40 à 42 pour la 14). La température étant en 1, 4 ,…, 40, l'humidité en 2, 5, ,,,, 41 et la luminosité en 3, 6, …, 52. Sans ce paramètre les 42 états sont renvoyés 192.168.1.100/mapage.htm?data=$THL01&$THL

192.168.1.100/mapage.htm?data=25.2&25.2&13&.. TS : TimeStamp / 192.168.1.100/mapage.htm?data=$TS 192.168.1.100/mapage.htm?data=2017/01/16T14:52:30+01:00

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.