This is an old revision of the document!


Calaos Webservice protocol

Calaos server has a communication protocol based on HTTP requests. Data exchanged are formatted in the 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 Wget or 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:

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:

calaos_config set debug_enabled true

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

Use the API with other languages

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