====== Protocole pour webservice Calaos ======
La centrale propose un protocole de communication grâce à des requêtes HTTP. Les données échangées sont au format [[http://fr.wikipedia.org/wiki/Json|JSON]].
Le Calaos Network propose également ce type de service, en particulier pour les applications clientes et l'authentification des utilisateurs.
===== Détails des requêtes =====
Les requêtes se font en HTTPS soit sur la centrale directement, soit sur le Calaos Network. Les requêtes sur le Calaos Network se font grâce à l'url suivante:
https://www.calaos.fr/calaos_network/api.php
Les requêtes sur la centrale se font grâce à l'url suivante:
https://calaos_server_ip/api.php
===== Effectuer des tests =====
==== Wget ====
Il est possible d'effectuer des requêtes de tests grâce à l'outil [[http://fr.wikipedia.org/wiki/Wget|Wget]] en ligne de commande.
Les données à envoyer sont au format JSON dans le fichier //query.json// et le résultat se retrouvera dans //result.json//.
wget --no-check-certificate --post-file query.json --output-document result.json https://calaos_server_ip/api.php
==== Dans l'url avec HTTP GET ====
Les requêtes doivent se faire avec HTTP POST avec Calaos v2. Calaos v3 supporte aussi HTTP GET et donc les requêtes peuvent être directement passées dans l'url.
Exemple:
* Avoir toute la config : https://calaos_server_ip/api?cn_user=XXX&cn_pass=XXX&action=get_home
* Avoir l'image d'une camera : https://calaos_server_ip/api?cn_user=XXX&cn_pass=XXX&action=camera&type=get_picture&id=input_57_output_32
* Activer une sortie : https://calaos_server_ip/api?cn_user=XXX&cn_pass=XXX&action=set_state&id=output_7&value=true
* Activer une variable interne : https://calaos_server_ip/api?cn_user=XXX&cn_pass=XXX&action=set_state&id=intern_4&value=true
* Lire une variable : https://calaos_server_ip/api?cn_user=XXX&cn_pass=XXX&action=get_state&items=output_21,output_25
Cela permet à un système externe ne supportant que HTTP GET de facilement communiquer avec Calaos.
==== Page HTML ====
Calaos v3 inclu une page HTML permettant de tester des requêtes POST et Websocket. Elle permet de facilement vérifier le format des données JSON à envoyer.
Il faut d'abord activer le mode debug avec la commande :
calaos_config set debug_enabled true
ou l'ajouter directement dans le fichier ///etc/calaos/local_config.xml//.
On peut ensuite y accéder via:
https://calaos_server_ip/debug/ ou http://calaos_server_ip:5454/debug/ .
{{ :fr:api_debug_html.png?nolink&600 |}}
==== Utiliser l'API avec d'autres languages ====
* [[json_python2|Python 2]]
* [[json_python3|Python 3]]
===== API Calaos Network =====
==== get_ip ====
Cette commande permet le login et la récupération de l'adresse IP de la centrale. Elle est a effectuer uniquement sur le Calaos Network en utilisant l'url suivante:
https://www.calaos.fr/calaos_network/api.php
=== Exemple ===
Données JSON à envoyer:
{
"cn_user": "mail@example.com",
"cn_pass": "the_password",
"action": "get_ip"
}
Réponse:
{
"private_ip": "192.168.50.50",
"cn_user": "mail@example.com",
"at_home": true,
"public_ip": "50.50.50.50"
}
La réponse contient 2 adresses IP, l'adresse //privée//, qui correspond à l'adresse IP de la centrale sur le réseau local, et l'adresse //publique//, qui correspond à l'adresse IP public ou il faudra se connecter à la centrale. A l'extérieur, uniquement le port HTTPS 443 est normalement ouvert.
Calaos Network nous donne également le paramètre //at_home// qui est un booléen qui définit si on est dans le même réseau que la centrale ou à l'extérieur.
===== API de la centrale =====
==== get_home ====
Cette commande permet de récupérer la configuration complète de la maison.
=== Exemple ===
Données JSON à envoyer:
{
"cn_user": "mail@example.com",
"cn_pass": "the_password",
"action": "get_home"
}
Réponse:
{
"home": [
{
"type": "salon",
"hits": "0",
"name": "Salon",
"items": {
"inputs": [
{
"visible": "false",
"var_type": "bool",
"id": "input_0",
"hits": "0",
"name": "Interrupteur",
"type": "WIDigitalBP",
"state": "false"
},
{
"visible": "",
"var_type": "string",
"id": "input_1",
"hits": "0",
"name": "Caméra 1",
"type": "CamInput",
"state": ""
},
{
"visible": "",
"var_type": "string",
"id": "input_2",
"hits": "0",
"name": "lecteur pull-house",
"type": "AudioInput",
"state": ""
}
],
"outputs": [
{
"id": "output_0",
"hits": "0",
"name": "Lumière",
"gtype": "light",
"state": "false",
"type": "WODigital",
"visible": "true",
"var_type": "bool"
},
{
"id": "output_1",
"hits": "0",
"name": "Volet",
"state": "stop -2.14748e 09",
"type": "WOVoletSmart",
"visible": "true",
"var_type": "string"
},
{
"id": "output_2",
"hits": "0",
"name": "Caméra 1",
"state": "",
"type": "CamOutput",
"visible": "",
"var_type": "string"
},
{
"id": "output_3",
"hits": "0",
"name": "lecteur pull-house",
"state": "",
"type": "AudioOutput",
"visible": "",
"var_type": "string"
}
]
}
}
],
"cameras": [
{
"url_lowres": "https://127.0.0.1/camera.php?camera_id=0&width=300&height=225",
"name": "Caméra 1",
"ptz": "false",
"url_highres": "https://127.0.0.1/camera.php?camera_id=0&width=640&height=480"
}
],
"audio": [
{
"player_id": 0,
"volume": "0",
"time_elapsed": "0",
"playlist_size": "5",
"playlist_current_track": "0",
"cover_url": "https://127.0.0.1/music.php?player_id=0",
"current_track": {
"title": "?",
"duration": "0",
"artist": "?",
"album": "?",
"coverart": "1"
},
"status": "error",
"name": "lecteur pull-house",
"playlist": "true",
"database": "true"
}
]
}
La réponse nous donne 3 tableaux principaux qui reflètent la configuration de la maison ["home"], la liste des caméras ["camera"] et enfin la liste des zones de musique ["audio"]. Toutes les informations sont du même type que ce qui est renvoyé par [[protocole_tcp|le protocole TCP]].
==== get_state ====
Cette commande permet de récupérer l’état d'une ou plusieurs entrée/sorties ainsi que l'états des zones de musique. Les paramètres comprennent les ID des entrées/sorties, tels qu'on le trouve dans [[protocole_tcp|le protocole TCP]].
=== Exemple ===
Données JSON à envoyer:
{
"cn_user": "mail@example.com",
"cn_pass": "the_password",
"action": "get_state",
"inputs": ["input_0"],
"outputs": ["output_0", "output_1"],
"audio_players": ["0"]
}
Réponse:
{
"inputs": {
"input_0": "false"
},
"outputs": {
"output_0": "false",
"output_1": "stop 0"
}
"audio_players": [
{
"player_id": "0",
"playlist_current_track": "0",
"volume": "33",
"playlist_size": "5",
"time_elapsed": "1420.68",
"cover_url": "/music.php?player_id=0",
"current_track": {
"title": "Sun",
"duration": "0",
"artist": "Sun",
"album": "",
"coverart": "1"
},
"status": "playing"
}
]
}
La réponse contient la liste des entrées/sorties demandée avec les états.
==== set_state ====
Cette commande permet de changer l’état d'une ou plusieurs entrée/sorties. Les paramètres comprennent les ID des entrées/sorties, tels qu'on le trouve dans [[protocole_tcp|le protocole TCP]].
=== Exemple ===
Données JSON à envoyer:
{
"cn_user": "mail@example.com",
"cn_pass": "the_password",
"action": "set_state",
"type": "output",
"id": "output_0",
"value": "true"
}
Réponse:
{
"success": true,
"cn_user": "mail@example.com"
}
Ceci fonctionne aussi avec les scenarios cependant syntaxiquement le type reste "output"
De la même manière on peut force la valeur d'une entrée avec
"type": "input"
On peut également donner des commandes à une zoner de musique. Les commandes sont les même que celle du [[protocole_tcp|protocole TCP]].
=== Exemple ===
Données JSON à envoyer:
{
"cn_user": "mail@example.com",
"cn_pass": "the_password",
"action": "set_state",
"type": "audio",
"player_id": "0",
"value": "volume 75"
}
Ou encore donner des commandes à une caméra motorisé. Les commandes sont les même que celle du [[protocole_tcp|protocole TCP]].
=== Exemple ===
Données JSON à envoyer:
{
"cn_user": "mail@example.com",
"cn_pass": "the_password",
"action": "set_state",
"type": "camera",
"camera_id": "0",
"camera_action": "move",
"value": "left"
}
==== get_playlist ====
Cette commande permet de récupérer la playliste courante d'une zone de musique.
=== Exemple ===
Données JSON à envoyer:
{
"cn_user": "mail@example.com",
"cn_pass": "the_password",
"action": "get_playlist",
"player_id": "0"
}
On peut rajouter le paramètre //from// et //to// qui permettent de spécifier une partie de la playlist a charger. Pratique en cas d'utilisation asynchrone et lorsqu'une playlist est grande.
Réponse:
{
"count": "5",
"current_track": "1",
"items": [
{
"item": "0",
"artist": "Boss Of Nova",
"album": "Blah",
"title": "History"
},
{
"item": "1",
"title": "Gaëtan Roussel - Inside / Outside",
"artist": "Rock moderne"
},
{
"item": "2",
"artist": "Radio Nova"
},
{
"item": "3",
"artist": "Radio Paradise"
},
{
"item": "4",
"artist": "NRJ 88.2 (Français)"
}
]
}
La réponse contient la liste des pistes avec les informations complémentaire si elles sont diponibles (artiste, album, titre, ...).
==== poll_listen ====
Cette commande permet de faire du polling pour récupérer les changements d'état des E/S de la centrale. Chaque appel va permettre de récupérer uniquement les changements. Il va falloir auparavant demander un identifiant pour s'enregistrer sur la centrale en tant que participant d'écoute.
=== Enregistrement ===
Pour s'enregistrer et récupérer un identifiant il faut envoyer la requête:
{
"cn_user": "mail@example.com",
"cn_pass": "the_password",
"action": "poll_listen",
"type": "register"
}
On recevra en réponse l'identifiant:
{
"uuid": "abbcaa23-17f7-430f-a30a-221f55077408"
}
Cette identifiant unique est valable tant qu'on l'utilise. Si on ne l'utilise pas il devient automatiquement invalide après 5 min.
=== Suppression ===
A la fin de l'utilisation, on peut supprimer l'identifiant pour le rendre invalide. Cette suppression n'est pas obligatoire, et se fait automatiquement après 5 min d'inactivité avec l'identifiant.
Données JSON à envoyer:
{
"cn_user": "mail@example.com",
"cn_pass": "the_password",
"action": "poll_listen",
"type": "unregister",
"uuid": "abbcaa23-17f7-430f-a30a-221f55077408"
}
Réponse:
{
"success": "true"
}
=== Récupération des évènements ===
Une fois l'enregistrement fait et l'identifiant récupéré, on peut interroger la centrale à intervalle régulière (< 5 min) pour avoir les évènements intervenues. Les réponses sont similaires à la commande //listen// du mode TCP.
Données JSON à envoyer:
{
"cn_user": "mail@example.com",
"cn_pass": "the_password",
"action": "poll_listen",
"type": "get",
"uuid": "abbcaa23-17f7-430f-a30a-221f55077408"
}
Réponse:
{
"success": "true",
"events": [
"input input_0 state%3Atrue",
"output output_0 state%3Atrue",
"output output_1 state%3Atrue"
]
}
==== config ====
Cette commande permet de lire/ecrire la config au travers du protocole json.
=== get ===
Pour recuperer la config il faut faire:
{
"cn_user": "mail@example.com",
"cn_pass": "the_password",
"action": "config",
"type": "get"
}
On recevra en réponse les fichier xml dans le json
{
"success": "true",
"config_files": {
"io.xml": "",
"rules.xml": ""
}
}
=== put ===
Pour recuperer la config il faut faire:
{
"cn_user": "mail@example.com",
"cn_pass": "the_password",
"action": "config",
"type": "put",
"config_files": {
"io.xml": "",
"rules.xml": ""
}
}
Réponse:
{
"success": "true"
}