Differences

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

Link to this comparison view

Next revision 		Previous revision
protocole_json [2011/01/17 17:34]
admin créée 		protocole_json [2014/04/23 13:50]
admin [poll_listen]
Line 15: Line 15:
   https://ip_centrale/api.php   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 ===== ===== API Calaos Network =====
  
 ==== get_ip ==== ==== get_ip ====
  
-Cette commande permet le login et la récupération de l'adresse IP de la centrale.+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 === === Exemple ===
Line 122: Line 160:
             "volume": "0",             "volume": "0",
             "time_elapsed": "0",             "time_elapsed": "0",
 +            "playlist_size": "5",
 +            "playlist_current_track": "0",
             "cover_url": "https://127.0.0.1/music.php?player_id=0",             "cover_url": "https://127.0.0.1/music.php?player_id=0",
             "current_track": {             "current_track": {
Line 136: Line 176:
         }         }
     ]     ]
 +  }
 +  
 +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"
 +      ]
 +  }
 +
 +==== 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": "<xml ...... >",
 +          "rules.xml": "<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": "<xml ...... >",
 +          "rules.xml": "<xml ...... >"
 +      }
 +  }
 +
 +Réponse:
 +  {
 +      "success": "true"
   }   }