====== Calaos Webservice protocol ======

Calaos server has a communication protocol based on HTTP requests. Data exchanged are formatted in the [[http://fr.wikipedia.org/wiki/Json|JSON]] format.

===== Requests details =====

Requests are made via HTTPS directly on calaos server. Requests have to be done on the following URL :

  https://calaos_server_ip/api.php
  
===== Testing =====

==== Wget ====
It is possible to test the API using command line tools like [[http://en.wikipedia.org/wiki/Wget|Wget]] or [[http://en.wikipedia.org/wiki/CURL|cURL]]

Data in JSON format are placed in the file //query.json//. The resulting file will then be //result.json//.

  wget --no-check-certificate --post-file query.json --output-document result.json https://calaos_server_ip/api.php
  
==== In url with HTTP GET ====

The requests must be made with HTTP POST with Calaos v2.  Calaos v3 also supports HTTP GET and it is therefore possible to send a request directly in the url.

Examples:
  * Get the config: https://calaos_server_ip/api?cn_user=XXX&cn_pass=XXX&action=get_home
  * Get a picture from a camera: https://calaos_server_ip/api?cn_user=XXX&cn_pass=XXX&action=camera&type=get_picture&id=input_57_output_32
  * Set an output: https://calaos_server_ip/api?cn_user=XXX&cn_pass=XXX&action=set_state&id=output_7&value=true
  * Set an intern variable: https://calaos_server_ip/api?cn_user=XXX&cn_pass=XXX&action=set_state&id=intern_4&value=true
  * Read a variable : https://calaos_server_ip/api?cn_user=XXX&cn_pass=XXX&action=get_state&items=output_21,output_25

That allows an external system that only supports HTTP GET to easily communicate to Calaos.

==== HTML Page ====

Calaos v3 includes a debug web page to test the POST and Websocket requests.  It allows to easily verify the format of the JSON data to send.

We need first to activate the debug mode with following command:
<code>
calaos_config set debug_enabled true
</code>
or directly add it in the file ///etc/calaos/local_config.xml//.

The page is then accessible from https://calaos_server_ip/debug or http://calaos_server_ip:5454/debug .

{{ :fr:api_debug_html.png?nolink&600 |}}

==== Use the API with other languages ====

  * [[json_python2|Python 2]]
  * [[json_python3|Python 3]]

===== API Calaos Network =====

TBC

===== Calaos Server API =====

==== get_home ====

With this command you can get the complete configuration of the house.

=== Example ===

Json Data to be sent :
  {
      "cn_user": "mail@example.com",
      "cn_pass": "the_password",
      "action": "get_home"
  }

Answer
  {
    "home": [
        {
            "type": "livingroom",
            "hits": "0",
            "name": "Livingroom",
            "items": {
                "inputs": [
                    {
                        "visible": "false",
                        "var_type": "bool",
                        "id": "input_0",
                        "hits": "0",
                        "name": "Switch",
                        "type": "WIDigitalBP",
                        "state": "false"
                    },
                    {
                        "visible": "",
                        "var_type": "string",
                        "id": "input_1",
                        "hits": "0",
                        "name": "CCTV 1",
                        "type": "CamInput",
                        "state": ""
                    },
                    {
                        "visible": "",
                        "var_type": "string",
                        "id": "input_2",
                        "hits": "0",
                        "name": "Music player",
                        "type": "AudioInput",
                        "state": ""
                    }
                ],
                "outputs": [
                    {
                        "id": "output_0",
                        "hits": "0",
                        "name": "Light",
                        "gtype": "light",
                        "state": "false",
                        "type": "WODigital",
                        "visible": "true",
                        "var_type": "bool"
                    },
                    {
                        "id": "output_1",
                        "hits": "0",
                        "name": "Shutter",
                        "state": "stop -2.14748e 09",
                        "type": "WOVoletSmart",
                        "visible": "true",
                        "var_type": "string"
                    },
                    {
                        "id": "output_2",
                        "hits": "0",
                        "name": "CCTV 1",
                        "state": "",
                        "type": "CamOutput",
                        "visible": "",
                        "var_type": "string"
                    },
                    {
                        "id": "output_3",
                        "hits": "0",
                        "name": "Music player",
                        "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": "CCTV 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": "Music player",
            "playlist": "true",
            "database": "true"
        }
    ]
  }
  
The answer gives us 3 arrays which represents the configuration of the house ["home"], the list of cameras ["camera"] and the audio zones ["audio"]. All those information have the same type as in the [[protocole_tcp|TCP Protocol]].

==== get_state ====

This command may be used to get the state of one or many Input/Output and the state of the music zones. Parameters included are the ID of the I/O as found in the [[protocole_tcp|TCP Protocol]].

=== Example ===

JSON Data to be sent
  {
      "cn_user": "mail@example.com",
      "cn_pass": "the_password",
      "action": "get_state",
      "inputs": ["input_0"],
      "outputs": ["output_0", "output_1"],
      "audio_players": ["0"]
  }

Answer:
{
    "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"
        }
    ]
}

Answer contains the list of queried I/O and their state value.

==== set_state ====

This command is used to change the state of one or many I/O. Parameters contains the ID of I/O, as in the [[protocole_tcp|TCP Protocol]]. 

=== Example ===

JSON data to be sent :
  {
      "cn_user": "mail@example.com",
      "cn_pass": "the_password",
      "action": "set_state",
      "type": "output",
      "id": "output_0",
      "value": "true"
  }

Answer:
  {
      "success": true,
      "cn_user": "mail@example.com"
  }

If you want to force the value of an input, you need to set type to "input" :
  "type": "input"
  
Command may also be sent to the music zones. Those commands are the same as in the [[protocole_tcp|TCP Protocol]].

=== Example ===

JSON Data to be sent :
  {
      "cn_user": "mail@example.com",
      "cn_pass": "the_password",
      "action": "set_state",
      "type": "audio",
      "player_id": "0",
      "value": "volume 75"
  }

We can also send data to a camera with PTZ control. Commands are the same as in the [[protocole_tcp|TCP Protocol]].

=== Example ===

JSON Data to be sent :
  {
      "cn_user": "mail@example.com",
      "cn_pass": "the_password",
      "action": "set_state",
      "type": "camera",
      "camera_id": "0",
      "camera_action": "move",
      "value": "left"
  }

==== get_playlist ====

This command is used to get the current playlist of a music zone.

=== Example ===

JSON Data to be sent :
  {
      "cn_user": "mail@example.com",
      "cn_pass": "the_password",
      "action": "get_playlist",
      "player_id": "0"
  }

You can also add the parameters //from// and //to// to specify a part of the playlist to load. This can be useful in case of asynchronous uses or when the playlist is big.

Answer:
{
    "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)"
        }
    ]
}

The answer contains the list of tracks with all their information like id, artist, album, title, ...

==== poll_listen ====

This command is used to monitor all the changes of an IO of the server. Every call will get only changes. You need first to register and get a unique id, and the server will notify you each time a change occurs on the specified I/O

=== Register ===

To register and get a unique ID, you have to send the following request :
  {
      "cn_user": "mail@example.com",
      "cn_pass": "the_password",
      "action": "poll_listen",
      "type": "register"
  }

And you will receive the ID :
  {
      "uuid": "abbcaa23-17f7-430f-a30a-221f55077408"
  }

This ID is unique and is valid as long as you used it. If not used within 5 min, it becomes invalid.

=== Remove ===

When you have finished listening changes on an IO, you can remove this ID. Deleting an ID is not mandatory, as it's always done after 5 min on inactivity.

JSON Data to be sent :
  {
      "cn_user": "mail@example.com",
      "cn_pass": "the_password",
      "action": "poll_listen",
      "type": "unregister",
      "uuid": "abbcaa23-17f7-430f-a30a-221f55077408"
  }

Answer:
  {
      "success": "true"
  }

=== Get Events ===

Once the registration is done and you have your unique ID, you can ask the server periodically to know what happens. The answer are the same as those sent by the //listen// command in the [[protocole_tcp|TCP Protocol]].

JSON Data to be sent:
  {
      "cn_user": "mail@example.com",
      "cn_pass": "the_password",
      "action": "poll_listen",
      "type": "get",
      "uuid": "abbcaa23-17f7-430f-a30a-221f55077408"
  }

Answer:
  {
      "success": "true",
      "events": [
          "input input_0 state%3Atrue",
          "output output_0 state%3Atrue",
          "output output_1 state%3Atrue"
      ]
  }

==== config ====

This command is used to read/write the configuration through the json protocol.

=== get ===

To retrieve the whole config you need to use the following request :
  {
      "cn_user": "mail@example.com",
      "cn_pass": "the_password",
      "action": "config",
      "type": "get"
  }

And you will get the xml configuration files in the json answer :
  {
      "success": "true",
      "config_files": {
          "io.xml": "<xml ...... >",
          "rules.xml": "<xml ...... >"
      }
  }

=== put ===

To send the configuration on the server you need to use the following request
  {
      "cn_user": "mail@example.com",
      "cn_pass": "the_password",
      "action": "config",
      "type": "put",
      "config_files": {
          "io.xml": "<xml ...... >",
          "rules.xml": "<xml ...... >"
      }
  }

Answer:
  {
      "success": "true"
  }