Protocole Client/Serveur

La centrale Calaos permet le contrôle et la récupération d'information de la maison au travers d'un protocole en ligne de commande simple par TCP/IP. La centrale permet les connections sur un port spécifique et peut être utilisé pour le débugage avec l'utilitaire Telnet. La centrale écoute sur le port 4456.

Le protocole est relativement simple et chaque commande reçu par la centrale est renvoyé en retour. Si une réponse est attendu, elle sera ajouté à la requête. Le séparateur de fin de ligne est le retour chariot (<LF>, soit le caractère ASCII 10 ou 0x0A). Le serveur accèpte <LF>, <CR>, 0x00 ou n'importe quel combinaison des trois. Il répondra avec ce qui a été envoyé dans la requête. Pour les chaines de caractères, la centrale utilise l'encodage UTF-8 et les paramètres des requêtes sont encodés grâce au principe d'url encoding (Percent-encoding)

Le format des commandes, requêtes et réponses est le suivant:

<command> <param0> ... <paramN> <LF>

<param0> à <paramN> sont les paramètres envoyés ou reçus.

Note: Chaque paramètre doit être encodé suivant le procédé d'URL encoding (Percent-encoding, les espaces sont remplacés par %20).

login <user> <password>

La commande login permet de s'authentifier sur la centrale. Les paramètres user et password doivent être url-encodé comme pour n'importe quel paramètre. Si l'authentification réussi, le serveur renvoie “ok” à la place du mot de passe. Si elle échoue, le serveur se déconnecte.

Exemples:

Requête : "login theuser thepassword<LF>"
Réponse : "login theuser ok<LF>"

Requête : "login theuser mauvaispassword<LF>"
Réponse : fermeture de la connection

version

Cette commande renvoie la version du serveur.

Exemple:

Requête : "version ?<LF>"
Réponse : "version 1.23<LF>"

save <option>

Cette commande sauvegarde la configuration dans la mémoire et/ou dans la compact flash.

Exemple:

Requête : "save default<LF>" Sauvegarde la configuration par defaut (chargé en cas de probleme avec la configuration courante)
Réponse : "save ok<LF>"
Requête : "save<LF>" Sauvegarde la configuration sur la compact flash
Réponse : "save ok<LF>"

system reboot <option>

Cette commande permet d'arrêter calaosd, calaos_gui ou les 2 (all)

Exemple:

Requête : "system reboot calaosd"
Requête : "system reboot calaos_gui"
Requête : "system reboot all"

system date ntp_on <timezone>

Active le ntp et règle le fuseau horaire.

Exemple:

  Requête : "system date ntp_on 4"
  Réponse : "system date ok"

system date ntp_off <hh> <mm> <ss> <JJ> <MM> <YYYY>

Désactive le ntp et règle l'heure. hh: heures mm: minutes ss: secondes

JJ: jour MM: mois YYYY: années

Exemple:

  Requête : "system date ntp_off 0 12 34 46 4 2 9"
  Réponse : "system date ok"

firmware <option>

Cette commande permet de demander la mise à jour du firmware

Exemple:

  Requête : "firmware webupdate"

listen

Cette commande mets la connexion en mode d'écoute. Le serveur va envoyer les différents évennements survenant dans le systeme sur toutes les connexions en mode listen. Une telle connexion ne pourra plus envoyer de commande.

Exemple:

  Requête : "listen"

poll_listen

Cette commande similaire à listen permet d'interroger la centrale à intervalle régulière pour avoir les évènements survenant dans le systeme. Il faut tout d'abord créer un identifiant et ensuite utiliser cet identifiant pour récupérer les évènements. Après 5 min d'inactivité, un identifiant devient automatiquement invalide.

Exemple:

  Requête : "poll_listen register"
  Réponse : "poll_listen 5716cb99-235c-4ac0-a99b-28d59659a9f4"
  
  Requête : "poll_listen get 5716cb99-235c-4ac0-a99b-28d59659a9f4"
  Réponse : "poll_listen get input%3Ainput_2%3Astate%3Aonsongchange output%3Aoutput_0%3Astate%3Atrue"
  
  Requête : "poll_listen unregister 5716cb99-235c-4ac0-a99b-28d59659a9f4"
  Réponse : "poll_listen unregister true"

camera <param1> <paramN>

La commande camera permet soit de récupérer le nombre de caméra disponible (argument “?”), soit de récupérer les informations (url du flux mjpeg, capture d'une image, nom, etc…) des caméras avec l'argument “get”, soit encore d'effectuer des actions (Uniquement pour les caméras disposant de ces fonctionnalités) sur une caméra avec l'argument “action”.

Exemple:

  Requête : "camera ?<LF>"
  Réponse : "camera 2<LF>" 2 caméras disponibles
  Requête : "camera get 0<LF>"
  Réponse : "camera 0 id:cam0 name:Caméra1 url:!http://10.0.0.1:80 mjpeg_url:!http://10.0.0.1:80/mjpeg.cgi mpeg_url:!http://10.0.0.1:80/mpeg4.cgi jpeg_url:!http://10.0.0.1:80/picture.cgi ptz:false<LF>"

Uniquement pour les modèles PTZ (motorisé):

  Requête : "camera move 0 left<LF> bouge la camera a gauche (left, right, up, down, home)"
  Réponse : "camera move 0 ok<LF>"
  Requête : "camera save 0 5<LF> sauvegarde la position de la camera à l'emplacement 5 (emplacement de 1 à 16)"
  Réponse : "camera save 0 ok<LF>"
  Requête : "camera move 0 5<LF> bouge la camera a la position sauvegardé en 5"
  Réponse : "camera move 0 ok<LF>"

Gestion des propriété des cameras:

  Requête : "camera capabilities 0 get<LF>"
  Réponse : "camera capabilities 0 ptz:true resolution:640x480 led:true contrast:255<LF>"
  Requête : "camera capabilities 0 set contrast:100 led:false<LF>" mets le contraste a 100 et eteint les leds
  Réponse : "camera capabilities 0 set ok<LF>"

Notes: Les propriétés renvoyés par camera get peuvent varier suivant le type de caméras.

home <param1> <paramN>

La commande home, avec l'argument “?”, sert à récupérer les types de pièces définit dans la maison. Avec l'argument “get”, on peut récupérer les informations d'un type de pièce. Par ex, pour récupérer tous les salons de la maison, on utilisera les paramètres “get salon”. Pour obtenir tous les types disponibles, il faut utiliser “get ?”.

Notes: L'ordre des pièces dans les réponses respecte l'ordre du fichier [wiki:StructureXML io.xml]

Exemple:

  Requête : "home ?<LF>"
  Réponse : "home salon:2 cuisine:1 sdb:1 chambre:2 chambre_parent:1<LF>" Dans cette configuration, nous avons 2 salons, 1 cuisine, etc...
  Requête : "home get salon<LF>"
  Réponse : "home count:2 0:name:Salon1 0:hits:152 1:name:Salon2 1:hits:59<LF>" Récupération des salons (noms, plus nombre de [wiki:hits Hits])

room <type>

La commande room permet de récupérer les différentes entrées/sorties d'une pièce de type <type>

Exemple:

  Requête : "room salon ?<LF>"
  Réponse : "room salon:2<LF>" 2 salons disponibles
  Requête : "room salon get 0<LF>" demande les infos du salon 0
  Réponse : "room salon:0 name:salon1 hits:99 input:in1 input:in2 output:out1 input:in45 output:lum01 input:scenario23<LF>"
  Requête : "room salon delete 0<LF>"
  Réponse : "room salon delete ok<LF>" Le salon a été supprimé

room get <id>

La commande room get permet de récupérer les différentes entrées/sorties d'une pièce

Notes: id respecte l'ordre des pièces du fichier [wiki:StructureXML io.xml]

Exemple:

  Requête : "room get 0<LF>"
  Réponse : "room id:0 input:in1 input:in2 output:out1 input:in45 output:lum01 input:scenario23<LF>"

room <type> get <nom>

Cette commande permet de récupérer les informations concernant la pièce de nom “nom”.

Exemple:

  Requête : "room chambre get chambre_parent"
  Réponse : "room id:0 input:in1 input:in2 output:out1 input:in45 output:lum01 input:scenario23<LF>"

room <type> set <id> <type> <nouvelle_valeur>

La commande room set permet de modifier une variable d'un enregistrement room.

Notes: id respecte l'ordre des pièces du fichier [wiki:StructureXML io.xml]

Exemple:

  Requête : "room salon set 0 name Chambre3<LF>"
  Réponse : "room salon set 0 name ok<LF>" le nom a été changé
  Requête : "room salon set 0 type chambre<LF>"
  Réponse : "room salon set 0 type ok<LF>" le type a été changé en chambre
  Requête : "room chambre set 0 hits 56<LF>"
  Réponse : "room chambre set 0 hits ok<LF>"
  Requête : "room add chambre Chambre1<LF>"
  Réponse : "room add ok<LF>"

room <type> <id> create <io_type> <param1>...<paramN>

La commande room <type> <id> create permet de créer une entrée/sortie dans une pièce.

Exemple:

  Requête : "room salon 0 create input type:WIDigitalTriple name:Inter1 host:10.0.0.123 port:502<LF>"
  Réponse : "room salon 0 create ok<LF>" l'interrupteur a été crée
  Requête : "room salon 0 create camera name:Camera1 host:10.0.0.5<LF>"
  Réponse : "room salon 0 create ok<LF>"

input <id> <action>

Permet de récuperer les informations d'une entrée, ou de forcer une entrée (pour activer un scénario par exemple)

Exemple:

  Requête : "input id1 get<LF>"
  Réponse : "input id:id1 name:Entree1 type:scenario<LF>"
  Requête : "input id1 set true<LF>"
  Réponse : "input id1 set ok"
  Requête : "input id1 state?<LF>"
  Réponse : "input id1 123"
  Requête : "input id1 states?<LF>"
  Réponse : "input id1 default:123 power:true statusN:valueN"
  Requête : "input id1 delete<LF>"
  Réponse : "input id1 ok"
  Requête : "input id1 query input_source ?<LF>" Envoie une demande d'infos complémentaire (uniquement pour certaines entrées et paramètre renvoyant une liste d'items)
  Réponse : "input id1 query input_source 0:Test 2:Param2"
  Requête : "input id1 params?<LF>" Permet de récupérer les paramètres avancés
  Réponse : "input name:truc id:id1 var:3 ip:192.168.0.4"
  Requête : "input id1 set_param name bidule<LF>"
  Réponse : "input id1 set_name name ok"
  Requête : "input id1 delete_param name<LF>"
  Réponse : "input id1 delete_param ok"
  Requête : "input plage1 plage get<LF> à utiliser uniquement pour les entrées de type InPlageHoraire"
  Réponse : "input plage1 1:13:00:00:0:1:15:00:00:0:1 1:17:00:00:0:1:17:30:00:0:1 2:13:00:00:1:1:15:00:00:0:1<LF>" 1..7 représente le jour de la semaine suivit de la plage
  Requête : "input plage1 plage set 1:12:00:00:0:1:14:00:00:0:1<LF>" à utiliser uniquement pour les entrées de type InPlageHoraire
  Réponse : "input plage1 plage set ok<LF>"
  Requête : "input plage1 plage months get<LF>"
  Réponse : "input plage1 plage months 111010011000<LF>"
  Requête : "input plage1 plage months set 000000111111<LF>"
  Réponse : "input plage1 plage months set ok<LF>"
  Requête : "input list<LF>" Retourne une liste de toutes les entrées disponibles
  Réponse : "input id2 in3 scenar4<LF>"

ouput <id> <action>

Permet de récuperer les informations d'une sortie, ou de forcer une sortie (pour activer/désactiver une lumière par exemple)

Exemple:

  Requête : "output id1 get<LF>"
  Réponse : "output id:id1 name:Sortie1 type:WODigital gtype:light state:true<LF>"
  Requête : "output id1 set true<LF>"
  Réponse : "output id1 set ok"
  Requête : "output id1 state?<LF>"
  Réponse : "output id1 true"
  Requête : "output id1 delete<LF>"
  Réponse : "output id1 ok"
  Requête : "input id1 query input_source ?<LF>" Envoie une demande d'infos complémentaire (uniquement pour certaines entrées et paramètre renvoyant une liste d'items)
  Réponse : "input id1 query input_source 0:Test 2:Param2"
  Requête : "output id1 params?<LF>" Permet de récupérer les paramètres avancés
  Réponse : "output name:truc id:id1 var:3 ip:192.168.0.4"
  Requête : "output id1 set_param name bidule<LF>"
  Réponse : "output id1 set_name name ok"
  Requête : "output id1 delete_param name<LF>"
  Réponse : "output id1 delete_param ok"
  Requête : "output list<LF>" Retourne une liste de toutes les sorties disponibles
  Réponse : "output volet1 tr1 lum2<LF>"

rules <type:name> <action> <param0> ... <paramN>

Permet de gérer les règles.

Exemple:

  Requête : "rules ?<LF>"
  Réponse : "rules light:2 volet:5<LF>"Il y a 2 catégories de règles
  Requête : "rules light get 0 condition<LF>"
  Réponse : "rules type:light name:Lumiere1 0:id:id1 0:oper:== 0:val:true 0:var_val:id3<LF>"
  Requête : "rules light get 0 action<LF>"
  Réponse : "rules type:light name:Lumiere1 0:id:id2 0:val:true 1:id:id3 1:val:false<LF>"
  Requête : "rules light set 0 condition 0 id:id6 oper:!= val:false var_val:<LF>"
  Réponse : "rules light set 0 condition 0 ok<LF>"
  Requête : "rules light set 0 action 0 id:id8 val:false<LF>"
  Réponse : "rules light set 0 action 0 ok<LF>"
  Requête : "rules light delete 0 condition 0<LF>"
  Réponse : "rules light delete 0 condition 0 ok<LF>"
  Requête : "rules light delete 0 action 0<LF>"
  Réponse : "rules light delete 0 action 0 ok<LF>"
  Requête : "rules light delete 0<LF>"
  Réponse : "rules light delete ok<LF>"
  Requête : "rules add light Regle 0:iid:id2 0:ioper:true 0:ival:true 0:ivar_val:true 0:oid:id3 1:oval:false<LF>"
  Réponse : "rules add ok<LF>"
  Requête : "rules light add 0 condition id:id2 oper:true val:true var_val:true<LF>"
  Réponse : "rules light add ok<LF>"
  Requête : "rules light add 0 action id:id2 val:true<LF>"
  Réponse : "rules light add ok<LF>"

audio <param1> <paramN>

La commande audio permet de gérer les lecteurs de musiques.

Exemple:

  Requête : "audio ?<LF>"
  Réponse : "audio 2<LF>" 2 lecteurs audios disponibles
  Requête : "audio get 0<LF>"
  Réponse : "audio 0 id:audio0 name:Lecteur%20Salon playlist:true database:true<LF>" On est capable de gerer la playlist du lecteur et on a également accès a sa base de donnée de musiques.

  Requête : "audio 0 play<LF> lance la lecture
  Réponse : "audio 0 ok<LF>"
  Requête : "audio 0 pause<LF>
  Réponse : "audio 0 ok<LF>"
  Requête : "audio 0 stop<LF>
  Réponse : "audio 0 ok<LF>"
  Requête : "audio 0 next<LF>
  Réponse : "audio 0 ok<LF>"
  Requête : "audio 0 previous<LF>
  Réponse : "audio 0 ok<LF>"
  Requête : "audio 0 off<LF>
  Réponse : "audio 0 ok<LF>"
  Requête : "audio 0 on<LF>
  Réponse : "audio 0 ok<LF>"
  Requête : "audio 0 volume?<LF>
  Réponse : "audio 0 volume:75<LF>"
  Requête : "audio 0 volume 80<LF>
  Réponse : "audio 0 volume ok<LF>"
  Requête : "audio 0 songinfo?<LF>
  Réponse : "audio 0 title:Some%20Title artist:Some%20Artist album:Some%20Album cover:true Genre:Rock duration:10.5566 bitrate:192Kbps type:mp3<LF>"
  Requête : "audio 0 cover?<LF>
  Réponse : "audio 0 cover:http://host/cover.jpg<LF>"
  Requête : "audio 0 cover 456<LF>
  Réponse : "audio 0 cover http://host/cover.jpg<LF>"
  Requête : "audio 0 time?<LF>
  Réponse : "audio 0 time:5.12233<LF>"
  Requête : "audio 0 time 15.65<LF>
  Réponse : "audio 0 time ok<LF>"
  Requête : "audio 0 status?<LF>
  Réponse : "audio 0 status:playing<LF>"
  Requête : "audio stop all<LF>" arrête toutes les lectures en cours
  Réponse : "audio stop ok<LF>"

Commandes pour la playlist:

  Requête : "audio 0 playlist size?<LF>
  Réponse : "audio 0 playlist 25<LF>"
  Requête : "audio 0 playlist current?<LF>
  Réponse : "audio 0 playlist 5<LF>" La piste courrante est la 5
  Requête : "audio 0 playlist 13 getitem?<LF>
  Réponse : "audio 0 playlist item:13 title:Some%20Title artist:Some%20Artist album:Some%20Album cover:true Genre:Rock duration:10.5566 bitrate:192Kbps type:mp3<LF>"
  Requête : "audio 0 playlist 13 cover?<LF>
  Réponse : "audio 0 playlist 13 cover:http://host/cover.jpg<LF>"
  Requête : "audio 0 playlist 13 moveup<LF>
  Réponse : "audio 0 playlist 13 ok<LF>"
  Requête : "audio 0 playlist 13 movedown<LF>
  Réponse : "audio 0 playlist 13 ok<LF>"
  Requête : "audio 0 playlist 13 delete<LF>
  Réponse : "audio 0 playlist 13 ok<LF>"
  Requête : "audio 0 playlist 13 play<LF>
  Réponse : "audio 0 playlist 13 ok<LF>"
  Requête : "audio 0 playlist clear<LF>
  Réponse : "audio 0 playlist ok<LF>"
  Requête : "audio 0 playlist save Ma_Playlist<LF>
  Réponse : "audio 0 playlist save ok<LF>"
  Requête : "audio 0 playlist add track_id:123<LF> Peut etre track_id, album_id, artist_id, genre_id, year, playlist_id, folder_id, radio_id
  Réponse : "audio 0 playlist add ok<LF>"
  Requête : "audio 0 playlist play track_id:123<LF>
  Réponse : "audio 0 playlist play ok<LF>"

Notes:

Pour radio_id, il faut passer le type de radio: radio_id:123:shoutcast

  Requête : "audio 0 options?<LF>
  Réponse : "audio 0 options sync:true sleep:true<LF>"
  Requête : "audio 0 options sync?<LF>
  Réponse : "audio 0 options sync id:123123 name:Lecteur1<LF>"
  Requête : "audio 0 options sync list?<LF>
  Réponse : "audio 0 options sync id:123123 name:Lecteur1 id:456456 name:Lecteur2<LF>"
  Requête : "audio 0 options sync id:123123<LF>
  Réponse : "audio 0 options sync ok<LF>"
  Requête : "audio 0 options sync off<LF>
  Réponse : "audio 0 options sync ok<LF>"
  Requête : "audio 0 options sleep?<LF>
  Réponse : "audio 0 options sleep:45<LF>"
  Requête : "audio 0 options sleep:60<LF>
  Réponse : "audio 0 options sleep ok<LF>"

Commandes pour la librairie de musique:

  Requête : "audio 0 database capabilities?<LF>
  Réponse : "audio 0 database artist:true album:true genre:false year:false music%20folder:true playlist:true radio:false search:true<LF>"
  Requête : "audio 0 database stats?<LF>
  Réponse : "audio 0 database artists:563 albums:2033 genres:53 years:123 music%20folder:4456 playlists:13 radios:5<LF>"

Les requetes de base de donnée se présente sous cette forme:
  audio <id> database <type de requete> <from> <nb max de reponse> [paramètres optionnels]

  Requête : "audio 0 database albums 0 2<LF>renvoie la liste d'albums
  Réponse : "audio 0 database albums id:563 year:1999 name:Album%20machin artist:Artiste%20machin cover_id:4456 id:123 year:2000 name:Album%20machin2 artist:Artiste%20machin2 cover_id:66445<LF>"
  Requête : "audio 0 database album_titles 0 1 album_id:123<LF>renvoie la liste de piste d'un album
  Réponse : "audio 0 database album_titles id:563 title:Titre year:2000 artist:Artiste album:Album genre:Genre cover_id:4456 duration:1233 type:mp3 bitrate:128<LF>"

  Requête : "audio 0 database artists 0 2<LF>renvoie la liste d'artistes
  Réponse : "audio 0 database artists id:563 name:Artiste id:123 name:Artiste2<LF>"
  Requête : "audio 0 database artist_albums 0 1 artist_id:123<LF>renvoie la liste d'album d'un artiste
  Réponse : "audio 0 database artist_albums id:563 name:Nom year:2000 artist:Artiste cover_id:4456<LF>"

  Requête : "audio 0 database genres 0 2<LF>renvoie la liste de genres
  Réponse : "audio 0 database genres id:563 name:Rock id:123 name:Valse<LF>"
  Requête : "audio 0 database genre_artists 0 1 genre_id:123<LF>renvoie la liste d'artiste d'un certain genre
  Réponse : "audio 0 database genre_artists id:563 name:Nom<LF>"

  Requête : "audio 0 database years 0 2<LF> renvoie la liste d'années
  Réponse : "audio 0 database years year:1960 year:2000<LF>"
  Requête : "audio 0 database year_albums 0 1 year:2000<LF> renvoie la liste d'albums d'une certaine année
  Réponse : "audio 0 database year_albums id:563 name:Nom year:2000 artist:Artiste cover_id:4456<LF>"

  Requête : "audio 0 database playlists 0 2<LF>renvoie la liste de playlists
  Réponse : "audio 0 database playlists id:123 name:playlist1 id:234 name:playlist2<LF>"
  Requête : "audio 0 database playlist_titles 0 1 playlist_id:123<LF>renvoie la liste de piste d'une playlist
  Réponse : "audio 0 database playlist_titles id:563 title:Titre year:2000 artist:Artiste album:Album genre:Genre cover_id:4456 duration:1233 type:mp3 bitrate:128<LF>"
  Requête : "audio 0 database playlist delete playlist_id:123<LF>supprime une playlist

  Requête : "audio 0 database radios 0 2<LF>renvoie la liste de radios
  Réponse : "audio 0 database radios id:shoutcast name:ShoutCAST id:radioio name:RadioIO<LF>"
  Requête : "audio 0 database radio_items 0 2 radio_id:shoutcast<LF> renvoie la liste d'item pour un certaine radio
  Réponse : "audio 0 database radio_items id:563 name:NomRadio isaudio:1 id:5634 name:NomRadio2 isaudio:0<LF>"
  Requête : "audio 0 database radio_items 0 1 radio_id:shoutcast item_id:5634<LF> renvoie la liste d'item pour un certaine radio et un sous item
  Réponse : "audio 0 database radio_items id:5634.1 name:NomRadioSousItem isaudio:1<LF>"
  Requête : "audio 0 database radio_items 0 1 radio_id:shoutcast item_id:5634 search:Nirvana<LF> renvoie la liste d'item pour un certaine radio et un sous item, inclut aussi une recherche
  Réponse : "audio 0 database radio_items id:5634.1 name:NomRadioSousItem isaudio:1<LF>"

  Requête : "audio 0 database randoms 0 100<LF>renvoie la liste de type de random disponible
  Réponse : "audio 0 database randoms id:tracks name:RandomTracks id:albums name:RandomAlbums id:artists name:RandomArtists id:years name:RandomYears<LF>"
  Requête : "audio 0 random random_id:tracks<LF> active le mode de random sélectionné
  Réponse : "audio 0 random ok<LF>"

  Requête : "audio 0 database search 0 2 search_terms:quelquechose<LF> renvoie la reponse a une recherche
  Réponse : "audio 0 database search id:123 type:album name:quelquechose id:234 type:track track_id:563 title:Titre year:2000 artist:Artiste album:Album genre:Genre cover_id:4456 duration:1233 type:mp3 bitrate:128<LF>"

  Requête : "audio 0 database music_folder 0 2<LF> renvoie la liste du dossier racine
  Réponse : "audio 0 database music_folder id:1.1 type:folder name:Dossier id:1.3 type:track track_id:563 title:Titre year:2000 artist:Artiste album:Album genre:Genre cover_id:4456 duration:1233 type:mp3 bitrate:128<LF>"
  Requête : "audio 0 database music_folder 0 2 folder_id:1.1<LF> renvoie la liste d'un sous dossier
  Réponse : "audio 0 database music_folder id:2.1 type:folder name:Dossier id:2.3 type:track track_id:563 title:Titre year:2000 artist:Artiste album:Album genre:Genre cover_id:4456 duration:1233 type:mp3 bitrate:128<LF>"