Calaos Webservice protocol

Calaos server has a communication protocol base on HTTP requests. Data exchanged are formated in the JSON format.

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

https://calaos_server_ip/api.php

It's possible to test the API with command line utils like Wget or cURL

Data to be sent has the JSON format and are places in the file query.json. The resulting file will be then result.json.

wget --no-check-certificate --post-file query.json --output-document result.json https://ip_address/api.php

TBC

TBC

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

Json Data to be send :

{
    "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 give us 3 arrays wich represent the configuration of the house [“home”], the list of cameras [“camera”] and the audio zones [“audio”]. All these informations has the same type of what is sent by the TCP Protocole.

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 find in the the TCP Protocol.

JSON Data to be send

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

}

The answer contains the list of I/O asked and the values of the states.

This command is used to change the state of one or many I/O. Parameters contains the ID of I/o, those found in the the TCP Protocole.

JSON data to be send :

{
    "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 can chante the type by :

"type": "input"

Command may also be sent to the music zone. Those commande are the same found in the the TCP Protocole.

JSON Data to be send :

{
    "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 motorised camera. Commands are the same as those found in the the TCP Protocole.

JSON Data to be send :

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

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

Données JSON à envoyer:

{
    "cn_user": "mail@example.com",
    "cn_pass": "the_password",
    "action": "get_playlist",
    "player_id": "0"
}

You can alos add the parameters from et to to specify a part ot the playlist to load. This can be usefull 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 and more informations id they are available, like artist, album, title, …

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

To register and get an 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 it's not used, it becomes invalide after 5 min.

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 5min on inactivity.

JSON Data to be send :

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

Answer:

{
    "success": "true"
}

Once the registration is done and you get an unique ID, you can ask the server periodically to know what happens on this IO. The answer are the same as those sent by the listen command of the TCP Protocole.

JSON Data to be send:

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

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

To retrieve the whole config you can 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 ...... >"
    }
}

To send the configuration on the server you can 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"
}