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 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 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/ .

Utiliser l'API avec d'autres languages

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 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 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 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.

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.

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"
}

Table of Contents

Protocole pour webservice Calaos

Détails des requêtes

Effectuer des tests

Wget

Dans l'url avec HTTP GET

Page HTML

Utiliser l'API avec d'autres languages

API Calaos Network

get_ip

Exemple

API de la centrale

get_home

Exemple

get_state

Exemple

set_state

Exemple

Exemple

Exemple

get_playlist

Exemple

poll_listen

Enregistrement

Suppression

Récupération des évènements

config

get

put