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:
- 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 intern variable: https://calaos_server_ip/api?cn_user=XXX&cn_pass=XXX&action=set_state&id=intern_4&value=true
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"
}