Differences

This shows you the differences between two versions of the page.

--- protocole_json [2013/08/29 09:34]
127.0.0.1 external edit
+++ — (current)
@@ Line 1: / Line 1: @@
-====== Protocole pour webservice Calaos ======
-La centrale propose une protocole de communication grâce à des requêtes HTTP. Les données échangés 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://ip_centrale/api.php
-===== Effectuer des tests =====
-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.
-==== Exemple ====
-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://addresse_ip/api.php
-===== 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"
-  }
-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"
-      ]
-  }