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 Example
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://ip_address/api.php
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"
}