Documentation eedomus

Sommaire

1 Script HTTP sur la box eedomus
2 Bon à savoir

Script HTTP sur la box eedomus

Cet élément du SDK eedomus permet d'héberger et d'exécuter son propre code sur sa box eedomus.

Vous devez d'abord être connecté sous votre compte sur http://secure.eedomus.com.

Rendez vous ensuite sur :

http://ip_de_votre_box/script/

Exemple avec une box eedomus dont l'adresse IP LAN est 192.168.0.30:

Les scripts peuvent être embarqués dans les périphériques du store eedomus.

Usage

Les scripts utilisateurs créés peuvent être appelés par différents moyens:

Manuellement pour test: en cliquant sur Exécuter sur votre page de scripts eedomus
Manuellement: en saisissant un URL du type http://ip_de_votre_box/script/?exec=MonScript.php depuis un browser ou tout autre logiciel ou matériel capable de réaliser des requêtes HTTP
Via un capteur HTTP eedomus : ce dernier peut être mis à jour à intervalle régulier ou par l'intermédiaire d'une règle.
Via un actionneur HTTP eedomus : que vous pourrez actionner manuellement ou via une règle.

Limitations

Afin d'éviter les risques de débordement des scripts eedomus, les limitations suivantes sont appliquées:

La taille de chaque script est limitée à 50 Ko
La durée d'exécution des scripts est limitée à 30 secondes
L'empreinte mémoire des scripts est limitée

Langage de script

La syntaxe utilisée par les scripts est dérivée du language PHP. Les scripts doivent se terminer par l'extension ".php".

La définition des variable se fait donc sous la forme:

$pi = 3.145916; /*Déclaration de ma variable "Pi"*/

Les structures suivantes sont autorisées:

for while if switch foreach

La création de tableaux est autorisée:

array

Les fonctions suivantes sont autorisées:

abs acos addslashes array array_key_exists array_keys array_map array_merge array_reverse array_sum array_unique asin atan atan2 base64_encode bcpow bin2hex bin2hex bindec

ceil chr chunk_split cos count current date decbin dechex define deg2rad die echo elseif empty error_reporting exp explode fclose fgets floor fmod for foreach fsockopen fwrite getprotobyname gettype gmdate hash hash_hmac header hex2bin hexdec html_entity_decode htmlentities htmlspecialchars http_build_query if implode in_array intval ip2long is_float is_int is_numeric is_string isset key list log max mcrypt_decrypt mcrypt_encrypt md5 microtime min mktime next ob_end_clean ob_start openssl_get_publickey openssl_public_encrypt ord pack parse_str pi pow preg_match preg_match_all preg_replace printf rad2deg rand rawurlencode round session_start

sha1 sin sizeof sleep sort sprintf sqrt sscanf str_pad str_repeat str_replace str_split strip_tags stripslashes strlen strpos strrchr strtolower strtotime strtoupper strtr strval substr switch tan time trim uniqid unpack urlencode usleep usort utf8_decode utf8_encode var_dump vsprintf while

Sur eedomus+ uniquement :

socket_bind socket_close socket_create socket_connect socket_last_error socket_recvfrom socket_sendto socket_set_option socket_strerror socket_write getprotobyname stream_bucket_append stream_bucket_make_writeable stream_bucket_new stream_bucket_prepend stream_context_create stream_context_get_default stream_context_get_options stream_context_get_params stream_context_set_default stream_context_set_option stream_context_set_params stream_copy_to_stream stream_filter_append stream_filter_prepend stream_filter_register stream_filter_remove stream_get_contents stream_get_filters stream_get_line stream_get_meta_data stream_get_transports stream_get_wrappers stream_is_local stream_isatty stream_notification_callback stream_register_wrapper stream_resolve_include_path stream_select stream_set_blocking stream_set_read_buffer

stream_set_timeout stream_set_write_buffer stream_socket_accept stream_socket_client stream_socket_enable_crypto stream_socket_get_name stream_socket_pair stream_socket_recvfrom stream_socket_sendto stream_socket_server stream_socket_shutdown stream_supports_lock stream_wrapper_register stream_wrapper_restore stream_wrapper_unregister

Fonctions spécifiques

getArg($var, $mandatory = true, $default = ' ')

Récupère un argument $_GET[$var] et affiche un message d'erreur si l'argument n'est pas précisé.

Le code API du périphérique courant peut être récupéré via getArg('eedomus_controller_module_id')

httpQuery($url, $action = 'GET'/*GET,POST,PUT,DELETE*/, $post = NULL, $oauth_token = NULL, $headers = NULL, $use_cookies = false, $ignore_errors = false, &$info = null, $user_pwd = NULL)

Exécute une requête HTTP/HTTPS et retourne son résultat sous forme de chaine de caractère.

Les arguments $action et $post peuvent être omis, ils peuvent être utilisés dans le cas de requêtes avancées comme un POST.

L'argument $oauth_token est utilisé pour les scripts des objets connectés, dans les scripts personnels il peut donc être ommis ou passé à NULL

L'argument $headers doit être fourni sous la forme d'un tableau, par exemple :

 $headers = array("X-Fbx-App-Auth: xxxx");

L'argument $cookies, vous permet d'activer la gestion des cookies pour la 1ère requête et celles qui suivront

L'argument $info permet de récupérer un tableau contenant entre autre le code HTTP, le header, ...

L'argument $user_pwd permet de passer un éventuel "user:password" dans la requête

saveVariable($variable_name, $variable_content)

Sauvegarde le contenu d'une variable, ce qui la rend réutilisable lors d'une prochaine exécution du script (via loadVariable).

Remarque: Les variables portant le même nom ne sont pas visibles entre différents scripts. $variable_name doit être une chaine de caractères.

loadVariable($variable_name)

Charge le contenu d'une variable précédemment sauvée avec saveVariable()

Remarque: Les variables portant le même nom ne sont pas visibles entre différents scripts. $variable_name doit être une chaine de caractères.

deleteVariable($variable_name)

Supprime le contenu d'une variable.

jsonToXML($json)

Convertie une chaine de caractère au format JSON vers le format XML (Utile notamment pour la réalisation de traitements xpath() par la suite)

xpath($xml, $path)

Il s'agit des même accesseurs xpath/xquery que pour les capteurs HTTP eedomus

Le validateur xpath peuvent être utilisé pour les test:

http://doc.eedomus.com/xpath/

setValue($periph_id /*Code API*/, $value, $verify_value_list = false, $update_only = false, $time = ' ', $delete_previous_value = false)

Demande une action sur un périphérique via son code API

Remarque 1 : l'action est exécutée de manière asynchrone, "au plus vite". En cas d'échec, elle sera retentée ultérieurement (ex. prise Z-Wave en limite de portée)

Remarque 2 : le paramètre $verify_value_list est optionnel. S'il vaut true, la valeur ne sera acceptée que si elle existe parmi la liste des valeur référencées (ex. On/Off). L'activation de se paramètre ralentie très légèrement la fonction puisque des vérifications préliminaires sont nécessaires.

update_only passez à true si vous souhaitez mettre à jour la valeur du périphérique eedomus sans demander d'action physique sur le matériel correspondant

time, indiquer au format yyyy-mm-dd hh:mm:ss si vous souhaitez insérer une valeur dans l'historique

delete_previous_value , supprime la précédente valeur si elle existe (plus lent)

setMacro($periph_id /*Code API*/, $macro_id /*Code API Macro*/, $dynamic_value = 0)

Actionne un périphérique via son code API et le code API de sa macro.

L'argument $dynamic_value peut être omis, il permet de définir la durée d'une macro variable le cas échéant.

getPeriphList($show_notes = false, $filter_device_id = NULL)

Retourne un tableau contenant la liste de vos périphériques (Rajoute les notes utilisateurs quand $show_notes est à 1)

Le format est similaire à celui de la requête API get -> periph.list

setBattery($periph_id /*Code API*/, $value)

Met à jour le niveau de la batterie du périphérique (valeur entre 0 et 100)

getPeriphValueList($periph_id /*Code API*/)

Retourne un tableau contenant la liste des valeur d'un périphérique (Valable uniquement pour les périphériques de type Liste)

Renvoie un tableau de la forme :

resultat[0] = array('value' => 0, 'state' => 'Off', 'state_img' => 'lamp_off.png', 'hidden' => 0)

getValue($periph_id /*Code API*/, $value_text = false)

Retourne un tableau contenant la valeur d'un périphérique via son code API.

Le tableau est de type array(["full_name"] => 'my device', ["value"] => xx, ["value_type"] => float, ["change"] => 'AAAA-MM-JJ HH:MM:SS', ["pending_action"] => NULL, ["unit"] => 'xx', ["icon"] => 'xx')

Si $value_text est à true, le tableau contiendra également ["value_text"]=> xx, qui correspond à la description de la valeur (ex. "On")

getRooms($periph_id /*Code API*/)

Retourne un tableau contenant les pièces affectées au périphériques via son code API.

Le tableau est de type array(["room_id"] => int, ["room_name"] => string, ["img"] => string)

sdk_json_decode($json, $decode_utf8 = false)

Retourne un tableau contenant le JSON décodé (Similaire à la fonction json_decode() de PHP

Passer $decode_utf8 à true si certains caractères sont invalides en sortie.

sdk_header($content_type)

Personnalise le header de la réponse HTTP du script. Seul $content_type = 'text/xml' et 'image/jpg' sont supportés pour l'instant.

netSend($ip, $port, $data)

Envoie une donnée à un périphérique réseau (expériemental).

Retourne une éventuelle réponse du périphérique.

Disponible seulement sur eedomus+ à ce jour

ftpUpload($ftp_server, $ftp_user, $ftp_pass, $content, $file_name)

Envoie une fichier sur un FTP en mode binaire (Utilisé par exemple pour déposer les images du portier Doorbird sur un périphérique caméra)

Retourne le résultat de l'envoi au format json

sendUPNP($ip, $param)

Envoi une action UPnP vers l'IP (ou les IP séparées par des virgules) d'un diffuseur UPnP

Les paramètres sont aux même format que ceux d'un actionneur UPnP (ex. pour lire un son préalablement chargé &play

sdk_get_input()

Renvoi le contenu de php://input

sdk_get_ip_from_ip_or_mac($ip_or_mac)

Renvoi toujours une adresse IP.

Si une adresse MAC est donnée en paramètre, renvoie la dernière adresse IP connue pour cette adresse MAC (La box eedomus rechercher toutes les 30 minutes les éventuels changement d'adresse IP des périphériques)

Si c'est une adresse IP elle est renvoyée telle quelle (permet de faire des scripts utilisables au choix avec l'IP ou la MAC)

Remarque: Seules les box eedomus+ sont capables de convertir une adresse MAC en adresse IP, les box eedomus 1ère générations devront utiliser cette fonction avec l'adresse IP comme paramètre.

Remarque 2: si $ip_or_mac == 'localhost', vous obtiendrez l'adresse IP locale de votre box eeedomus.

sdkUploadCameraSnap($periph_id /*Code API*/, $mode)

Capture une image sur la caméra associée ($periph_id peut être aux choix l'identifiant de la caméra ou de l'un de ses canaux) et la dépose sur le FTP eedomus pour alimenter l'historique d'image de la caméra.

L'argument $mode peut valoir 'JPG' ou 'RTSP' (Le mode 'RTSP' nécessite une eedomus+)

Exemples

Retrouvez ces fonctions spécifiques dans quelques exemples mis à votre disposition:

Eedomus_scripts_samples.zip

Scripts "Objets connectés"

Certains "Objets Connectés", pré-paramétrés pour eedomus fonctionnent avec des scrits spécialement développés par Connected Object], ces scripts sont déployés automatiquement sur votre box, néanmoins vous pouvez également les consulter ci-après à titre d'exemple.

Vous êtes libres de vous inspirer de ces scripts, de les modifier, de les re-publier sur le forum.

Fonctions utilisateur

Il est possible de définir ses propres fonction utilisateur, à condition de les préfixer par sdk_:

Par exemple:

function sdk_add($a, $b) { return $a + $b; }

Variables personnelles

2 approches sont possibles pour définir vos variables personnelles:

Définition "en dur" dans votre script

Cette méthode est la plus directe, mais elle ne facilite pas le partage de script avec la communauté eedomus.

$ma_lampe = 1234;

Définition via un argument de votre script

Cette méthode permet de ne pas faire apparaitre directement les codes API de vos périphériques dans votre code, le rendant plus "générique" et partageable.

$ma_lampe = getArg('ma_lampe');

Il faudra ensuite appeler votre script de la manière suivante (Dans cet exemple l'IP de la box eedomus est 192.168.0.30):

http://192.168.0.30/script/?exec=mon_script.php&ma_lampe=1234

Encodage

Vos fichiers de script doivent être encodés au format ISO-8859-1 ou ANSI, sans quoi les éventuels caractères accentués affichés pourraient être incorrects.

Un éditeur de texte comme Notepad2 est une très pratique pour modifier ou vérifier son encodage.

Remarque: En cas de problème avec les accents de chaines passées en argument il faudra utiliser la fonction utf8_decode()

$mon_texte_correctement_accentue = utf8_decode(getArg('mon_argument_accentue'));

Bon à savoir

Testez votre script

Le téléchargement du script nécessite une double connexion sur la eedomus et sur la plate-forme eedomus (sur le même navigateur).

N'hésitez pas à tester votre script en cas de problème. Si le script retourne "1", c'est souvent qu'il est absent ou incomplètement chargé.

Sauvegarde

Les scripts sont sauvegardés sur la plateforme eedomus (en plus de la box eedomus elle-même). Ils sont récupérés lors des restaurations, mises à jour.

Appel automatique du script

Si vous avez besoin d'appeler votre script de manière régulière ou sur évènement, vous pouvez créer un actionneur HTTP.

Le paramétrage de l'actionneur est comme suit :

Exemple de paramétrage d'actionneur HTTP pour appeler le script bonjour.php

Pour un appel régulier, vous avez ensuite deux possibilités :

créer une règle qui va appeler l'actionneur HTTP sur l'agenda (toutes les minutes ou toutes les heures par exemple)
utiliser le capteur HTTP inclus dans à l'actionneur HTTP

ou les deux !

Par exemple pour déclencher le script de récupération d'image sur mouvement, vous pouvez utiliser le capteur HTTP pour récupérer une image toutes les heures, ainsi qu'une règle pour prendre une image toutes les minutes lorsque l'alarme est activée.

Navigation

Scripts