Scripts

Documentation eedomus

Sommaire

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:

 

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_merge array_reverse asin atan base64_encode bcpow ceil chr chunk_split cos count date dechex define deg2rad die echo empty exp explode floor fmod hexdec http_build_query implode in-array isset log md5 microtime mktime ord parse_str pow preg_match preg_match_all printf rad2deg rand rawurlencode round sha1 sin sizeof sqrt stripslashes strlen str_pad strpos strrchr str_repeat str_replace strtolower strtotime strtoupper substr tan time trim uniqid urlencode usleep utf8_decode utf8_encode var_dump


Sur eedomus+ uniquement :

socket_bind socket_close socket_create socket_last_error socket_recvfrom socket_sendto socket_set_option socket_strerror


 

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é.


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

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


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.


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)

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.


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)

Retourne un tableau contenant la liste de votre 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


getValue($periph_id /*Code API*/)

Retourne un tableau contenant la valeur d'un périphérique via son code API.
Le tableau est de type array(["value"]=> xx, ["change"] => 'AAAA-MM-JJ HH:MM:SS')


sdk_json_decode($json)

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


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

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.

Fichier:eedomus_script_encodage.png

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.