Le 5 septembre 2017, eedomus a introduit dans une de ses mises à jour une nouvelle fonctionnalité appelée « Le store ». Dans cet article, nous allons découvrir toutes les possibilités qu’il offre et comment l’utiliser de A à Z pour que vous puissiez vous aussi participer et proposez vos propres périphériques !
Présentation
Qu’est ce que le store eedomus ?
Le store eedomus est un lieu communautaire de partage des réalisations de la communauté eedomus. Il est ouvert à tout le monde pour que chaque utilisateur puisse proposer son objet connecté. Les objets sont codés sous formes de scripts PHP et de chaines Json.
Il évoluera au fur et a mesure des mises à jour et permettra d’accueillir des périphériques indispensables qui n’existent pas encore de manière physique !
Accès au store
Pour accéder au store eedomus, rien de plus simple. Il suffit de vous rendre dans « Ajouter ou supprimer un périphérique« .
Ajouter un périphérique
Tout en bas dans « Autres types de périphériques » vous trouverez « Store eedomus« .
Store eedomus
Et vous arrivez sur la page des différents Plugins. Ils sont rangés par catégories (Météo, Utilitaires..) et ils sont créés par la communauté ! Nous verrons un peu plus tard comment créer son propre plugin.
Les catégories du store
Pour tester le bon fonctionnement du store et voir comment paramétrer les périphériques, nous allons en tester un qui s’appel « Va-t-il pleuvoir dans l’heure ? ». C’est un plugin relativement simple qui permet, comme son nom l’indique, de savoir si il va pleuvoir dans l’heure. Lorsque vous cliquez dessus, différentes informations apparaissent.
Vous avez le nom, la description, le créateur de plugin, le nombre de téléchargement, la date ou encore la version. En cliquant sur cette dernière, vous avez possibilité de télécharger les fichiers directement sur votre ordinateur et de voir le code, de le modifier etc… Pour créer le nouveau périphérique, il vous suffit de cliquer sur « Créer ».
Exemple de plugin
La page de création est identique à celle d’un nouveau périphérique. Vous pouvez renseignez le nom, la pièce et des infos utilisateurs.
Dans la partie « Affichage« , vous trouverez les paramètres du plugin qu’il faut remplir pour le faire fonctionner. Dans notre exemple, il suffit de rentrer le code de sa ville (disponible sur le site météo correspondant).
Configuration du plugin
Une fois le code rentré et votre périphérique créé, rendez-vous dans la pièce où il a été enregistré pour consulter les informations. Vous pouvez constater que le module nous affiches les données et qu’il ne va pas pleuvoir chez nous. Quelle chance !
Il s’agit d’un exemple simple mais efficace puisqu’il permet de comprendre la façon dont les périphériques provenant du store fonctionnent !
Mais comme je l’ai dit plus haut, il est possible de créer son propre plugin en fonction de ses besoins et de le partager à la communauté eedomus ! C’est un peu technique et nécessite des connaissances en développement, mais c’est à la portée de tous.
Et c’est ce que nous allons voir dans le prochain chapitre 🙂
Créer un plugin
Prérequis
Pour créer son plugin sur le store eedomus, il faut prendre en compte un certains nombre d’informations.
- Le code accepté est uniquement du PHP. Toutes les fonctions existantes en PHP ne seront pas disponibles et de nouvelles sont mises en place par l’équipe eedomus.
- La structure est très précise :
- 1 Fichier JSON portant le nom « eedomus_plugin.json« qui permet de définir les paramètres du périphérique.
- 0 ou plusieurs Scripts PHP.
- 0 ou plusieurs images au format PNG en 128×128 enregistré dans un dossier /img.
- Les fichiers doivent être dans un dossier au format .zip
Voici un exemple de la racine du fichier :
Vous pourrez bien évidemment retrouver toutes les informations de la documentation eedomus pour le store ici et pour les scripts php là.
Début du projet
Pour ce tutoriel, nous allons réaliser un script permettant de faire varier l’intensité lumineuse d’une lampe dimmable progressivement à l’aide d’une télécommande à 4 boutons (On, Off, + et – ). Ainsi, les touches ON / OFF permettront d’allumer et éteindre la lampes de manière classique mais les deux autres touches (+ et -) permettront quant à elles d’augmenter ou de diminuer l’intensité lumineuse de 10 à chaque appui sur la touche.
Et oui, car dans beaucoup de cas, il faut paramétrer un bouton pour chaque valeur, et une télécommande 10 boutons ce n’est pas très pratique ! C’est pourquoi ce script tout simple permettra d’incrémenter les valeurs avec seulement 2 boutons dédiés.
Grâce à une simple télécommande à 4 boutons, nous pourrons gérer l’intensité complète d’une lampe ! Vous êtes prêts ? C’est parti !
Création du Json
Commençons par la construction du Json. Chaque ligne sera commenté pour indiqué à quoi elle correspond et plus particulièrement dans le cas de notre script. Vous pouvez également allez sur la doc eedomus pour avoir des informations complémentaires.
La première partie du Json ce sont les informations du périphériques.
{
"plugin_id": "light_inc", // Identifiant Unique de notre périphérique
"name_fr": "Incrémentation de la luminosité", // Nom du périphérique sur le store FR
"name_en": "Light incrementation", // Nom du périphérique sur le store EN
"icon": "light_inc.png", // Icone du périphérique sur le store (celle dans le dossier img dans notre cas)
"version": "1.0", // La version de notre plugin
"creation_date": "2017-12-06", // La date de création du plugin
"modification_date": "2017-12-08", // La date de mise à jour du plugin
"author": "Planète domotique", // L'auteur du périphérique avec possibilité d'ajouter un lien type HTML
"description_fr": "Description en français", // Description FR du périphérique dans le store
"description_en": "Description en Anglais", // Description EN du périphérique dans le store
Maintenant nous allons définir les paramètres qui serviront à notre script. Ils permettent de créer des « champs » dans lesquels les utilisateurs viendront renseigner les informations permettant de faire fonctionner le plugin avec leurs appareils. Ils peuvent donc être modifiés en fonction de votre script PHP pour faciliter la gestion des données et la saisis des utilisateurs.
"parameters": [ // Le paramètre n°1 sera un lien de contact pour proposer des modifications/améliorations { "parameter": "help_url", // L'identifiant de notre paramètre "description": "Pour signaler un bug ou proposer une amélioration", // La description associé à ce paramètre "xtype": "displayfield", // Le type de paramètre, Displayfield = Champ "field": "style: 'padding: 3px;', // On peut ajouter des styles aux fields value: '<a href=\\'mailto:email\\'>Contacter nous</a>'" // Le contenu du field }, // Le paramètre n°2 sera le périphérique que l'on veut modifier (lampe). Une liste sera présentée à l'utilisateur pour qu'il sélectionne parmi tous les périphériques présents sur sa box. Cela évite d'avoir à chercher le code API du périphérique. { "parameter": "ID_PERIPH", // L'identifiant UNIQUE du périphérique que l'on veut contrôler. On le ciblera avec ce nom dans le script PHP. "description": "Périphérique à contrôler", // La description affichée pour ce paramètre. Pour bien orienter l'utilisateur "xtype": "combo", // "Combo" définit le type de paramètre en liste déroulante. "field": // Le contenu de la liste déroulante avec des paramètres spécifiques "store : getCombo('/json/list_all.php'), // Permet de lister l'ensemble des périphériques présents sur la box dans la liste combo displayField: 'label', valueField: 'id', // Affiche l'ID des périphériques typeAhead: true, forceSelection: true, triggerAction: 'all', selectOnFocus: true, editable: false, // Contenu non éditable, non modifiable shadow : true, mode: 'local', // Choix du mode Local width: 250, // Largeur du champ listWidth: 300, // Largeur de la liste allowBlank: false" // Oblige l'utilisateur à renseigner une valeur }, // Le paramètre n°3 sera le périphérique qui contrôlera la lampe (télécommande). Une liste sera également présentée à l'utilisateur Nous utilisons les mêmes paramètres que le paramètre précédent mais nous modifions l'identifiant pour qu'il soit unique. { "parameter": "ID_PERIPH_CTRL", // On n'oublie pas de modifier l'identifiant ! "description": "Périphérique contrôleur", // Et la description aussi ! "xtype": "combo", "field": "store : getCombo('/json/list_all.php'), displayField: 'label', valueField: 'id', typeAhead: true, forceSelection: true, triggerAction: 'all', selectOnFocus: true, editable: false, shadow:true, mode: 'local', width: 250, listWidth: 300, allowBlank: false" }, // Le paramètre n°4 permettra d'attribuer les bonnes touches de l'utilisateur. Comme elles sont propres à chaque paramétrage de télécommande, il est impératif de pouvoir rendre dynamique le script. Par exemple si dans les paramètres de votre télécommande la valeur de votre touche + = 40, - = 10, ON = 20 et off = 30 Alors il faudra renseigner les informations dans ce champ sous la forme : 40,10,20,30. { "parameter": "COMMANDE", // Identifiant unique à bien changer ! "description": "Valeur de +, -, on, off de votre télécommande (dans cet ordre)", "xtype": "textfield", // Champ pouvant être modifié par l'utilisateur "default_value": "0,1,2,3", "field": "width:200, allowBlank:false" // Rend la variable obligatoire } ],
Maintenant que nous avons défini les paramètres qui seront utilisés dans le script, nous pouvons cibler notre script comme cela :
"scripts": [ { "name": "light_inc.php" // Le nom du ou des scripts php associés } ],
Il est très important de définir le bon type de périphérique que prendra votre plugin pour qu’il puisse être utilisé de la bonne façon.
"devices": [ { "device_id": "light_incrementation", // Identifiant unique de l'appareil "module_id": "41", // Type de module, dans notre cas 41 pour Actionneur HTTP "type": "http", // Pas d'autre choix pour le moment "name_fr": "plugin.name", // Le nom que prendra le périphérique sera celui que l'utilisateur saisira "icon": "light_inc.png", // L'image sera celle de notre dossier /img "utilisation_id": "43", // 43 définira le type de module comme autre. "parameters": { // Les paramètres de notre périphérique. "value_type": "string", // Valeur de type chaîne de caractères "ignore_errors": 3, // A 3, il ignore jusqu'à 3 erreurs // Définit la variable 1 sur les informations entrées par l'utilisateur, dans notre cas les valeurs de sa télécommande car on cible "COMMANDE". "VAR1": "plugin.parameters.COMMANDE", // Définit la variable 2 sur les informations entrées par l'utilisateur dans notre cas le périphérique à contrôler car on cible "ID_PERIPH" "VAR2": "plugin.parameters.ID_PERIPH", // Définit la variable 3 sur les informations entrées par l'utilisateur dans notre cas le périphérique contrôleur car on cible "ID_PERIPH_CTRL" "VAR3": "plugin.parameters.ID_PERIPH_CTRL", // L'URL de la requête de mise à jour avec l'insertion des variables de l'utilisateur en ciblant via les ID uniques "RAW_URL": "https://localhost/script/?exec=light_inc.php&ID_PERIPH=[VAR2]&ID_PERIPH_CTRL=[VAR3]&COMMANDE=[VAR1]", "RAW_XPATH": "/root", // Le Xpath "POLLING": "0" // A 0 = Pas de rafraîchissement automatique. } } ],
Et pour finir, une fonction présente depuis peu, la possibilité de créer une règle automatique dès la création du périphérique. Pour notre script, nous voulons qu’à chaque appui sur la télécommande il soit rechargé.
"rules": [ { "name_fr": "plugin.name", // Nom de la règle = nom saisi par l'utilisateur "criterias": // Les critères de la règle [ // Le périphérique contrôleur (ID_PERIPH_CTRL) aura comme critère "Change d'état" { "device_id": "plugin.parameters.ID_PERIPH_CTRL", "type": "c" } ], "actions": // L'action qui aura lieu sera le rechargement du script [ // Notre périphérique créé (ciblé par son ID) sera mis à jour. { "device_id": "plugin.devices.light_incrementation", "action": "update" } ] } ] }
Maintenant que le Json est créé, place au script PHP ! Rien de très compliqué pour notre exemple.
Création du script PHP
Pour le PHP, certaines fonctions sont mises à disposition dans la documentation eedomus. Je vous invite à aller regarder si vous voulez en savoir plus.
Commençons le script !
Dans un premier temps, il faut penser à récupérer les variables saisies par l’utilisateur et que nous avons identifié dans le Json. Pour ce faire, rien de plus simple
<?php // Permet de récupérer le code API de l'appareil à contrôler qui est entré par l'utilisateur dans la liste déroulante du JSon. On le cible avec son identifiant qui est "ID_PERIPH" avec la fonction getArg fournis par l'équipe eedomus. Mandatory = true signifie que cette variable est obligatoire. $periph_id = getArg("ID_PERIPH", $mandatory = true); // On fait pareil pour le périphérique contrôleur $periph_id_ctrl = getArg("ID_PERIPH_CTRL", $mandatory = true);
Pour les commandes du contrôleur, c’est un peu plus compliqué. L’utilisateur a renseigné des informations dans un seul champ et séparé par des virgules « , ». Il va donc falloir récupérer les 4 valeurs en supprimant les virgules.
$remote_all = getArg("COMMANDE", $mandatory = true); // Recupération de la chaîne saisie par l'utilisateur en ciblant l'ID $remote_explode = explode(",", $remote_all); // On sépare la chaîne en un tableau avec la fonction explode. // On assigne les valeurs de la chaines récupéré sous la forme d'un tableau $remote_more = $remote_explode[0]; // Première valeur du tableau = + $remote_less = $remote_explode[1]; // Deuxième valeur du tableau = - $remote_on = $remote_explode[2]; // Troisième valeur du tableau = On $remote_off = $remote_explode[3]; // Quatrième valeur du tableau = Off
Maintenant que nous savons quels sont les périphériques que l’utilisateur veut utiliser, nous pouvons récupérer leur état. Dans le cas de la télécommande, nous allons récupérer la touche appuyée et pour la lampe sa valeur d’intensité.
Ensuite, la chaîne Json récupérée doit être décodée pour être exploitée. Pour ce faire, nous allons utiliser une fonction :
// Pour le premier périphérique // On récupère la valeur du périphérique à contrôler avec l'API eedomus en le ciblant dynamiquement avec la variable $url = "https://api.eedomus.com/get?action=periph.value&periph_id=".$periph_id; // Permet de décoder le json et d'éxécuter une requête HTTP pour retourner le résultat sous forme de chaine de caractère. $periph_list = sdk_json_decode(utf8_encode(httpQuery($url,'GET'))); // Retourne la dernière valeur du périphérique $last_value = $periph_list["body"]["last_value"]; // Pour l'autre périphérique, c'est la même chose $url_ctrl = "https://api.eedomus.com/get?action=periph.value&periph_id=".$periph_id_ctrl; $periph_list_ctrl = sdk_json_decode(utf8_encode(httpQuery($url_ctrl,'GET'))); $last_value_ctrl = $periph_list_ctrl["body"]["last_value"];
Pour pouvoir incrémenter de manière dynamique les valeurs d’intensité de la lampe (Augmenter de +10 à chaque appui à partir de la dernière valeur) il est important de stocker la dernière valeur de la lampe quelque part pour la réutiliser. Des fonctions sont présentes et nous permettent de le faire très rapidement.
$sauvegarde = saveVariable('save_variable', $last_value); // On stocke la dernière valeur d'intensité de la lampe $valeur_sauvee = loadVariable('save_variable'); // On charge la charge dans une nouvelle variable.
Maintenant que toutes nos variables sont définies, nous pouvons créer les conditions permettant de monter ou de baisser l’intensité en fonction du bouton appuyé sur la télécommande.
Commençons par définir les cas :
- L’utilisateur appuie sur la touche +
// Si la dernière valeur de la lampe est supérieure ou égale à 0 et qu'elle est plus petite ou égale à 90 Et que la touche appuyée est "+", alors la dernière valeur de la lampe augmente de 10. if($last_value >= 0 && $last_value <= 90 && $last_value_ctrl == $remote_more){ setValue($periph_id, $valeur_sauvee +10); }
- L’utilisateur appuie sur la touche +
// Si la dernière valeur de la lampe est supérieure ou égale à 10 et qu'elle est plus petite ou égale à 100 Et que la touche appuyée est "-", alors la dernière valeur de la lampe augmente de 10. if($last_value >= 10 && $last_value <= 100 && $last_value_ctrl == $remote_less){ setValue($periph_id, $valeur_sauvee -10); }
- L’utilisateur appuie sur la touche On
// Si l'utilisateur appui sur ON, alors la lampe passe à 100%. if($last_value_ctrl == $remote_on){ setValue($periph_id, 100); }
- L’utilisateur appuie sur la touche Off
// Si l'utilisateur appui sur Off, alors la lampe passe à 0%. if($last_value_ctrl == $remote_on){ setValue($periph_id, 0); }
Notre script est maintenant terminé ! On peut également afficher un XML à chaque fois que la requête est executée pour faciliter la lecture des données.
$xml = " // On créé le XML <data> <valueCtrl>$last_value_ctrl</valueCtrl> <valuePeriph>$last_value</valuePeriph> <valueSave>$valeur_sauvee</valueSave> <more>$remote_more</more> <less>$remote_less</less> <on>$remote_on</on> <off>$remote_off</off> </data>"; sdk_header('text/xml'); echo $xml; // On affiche le XML
Voilà, tout est fini. Maintenant nous allons voir comment utiliser ce plugin et surtout comment le mettre en ligne pour que la communauté puisse en profiter.
Mettre son plugin en ligne
Pour partager votre nouveau périphérique fraîchement créé avec toute la communauté eedomus, c’est très simple. Rendez-vous dans l’onglet « Ajouter ou supprimer un périphérique » et dans « Store eedomus« .
En haut à droite vous avez « Publiez sur le store », c’est ici que ça se passe.
Un bouton pour télécharger vos fichiers sur votre box eedomus apparaît. Sélectionnez le fichier .zip sur votre ordinateur et envoyez-le.
Choisissez un fichier
Une fois envoyé, il y a deux options :
- Le fichier n’est pas conforme et vous devez modifier des éléments
Erreur d’upload
Dans ce cas vous trouverez votre création dans la rubrique « Autre » en mode privé. Cela signifie que vous pouvez le tester et que vous seule êtes capable de le voir. Il pourra, si vous le validez, être soumis à vérification pour une mise en ligne.
Votre plugin
En cliquant dessus, vous aurez les informations rentrées dans le JSON comme la date, la version, l’auteur etc.. Le bouton « créer » permet de l’ajouter en tant que périphérique.
Créer un périphérique
A l’intérieur vous pourrez le configurer comme n’importe quel périphérique mais encore une fois, en fonction de votre JSON. Comme vous le constatez, les champs à remplir sont soit une liste déroulante, soit un champ de saisie pour les valeurs de la télécommande. Une fois que la configuration est bonne, cliquez sur enregistrer.
Configuration de votre périphérique
En vous rendant dans les règles associées, vous pouvez voir qu’une règle à automatiquement été créée.
A l’intérieur, nous avons bien les paramètres rentrés dans le JSON.
Paramètres de la règle
Il ne reste plus qu’à tester notre script !
Résultat
Voici ce qu’il se passe à chaque appui sur la touche + ou – :
Animation incrémentation
La lampe garde son ancienne valeur et ajoute ou soustrait 10 afin d’adapter la luminosité.
Pour ceux qui voudraient ce script sans avoir à le coder, il sera disponible sur le store eedomus très prochainement !
Conclusion
Le store eedomus est un incroyable marché ! Vous pouvez trouver beaucoup de choses pour répondre à vos besoins. Vous avez également la possibilité de proposer vos propres scripts pour aider les utilisateurs qui ont des besoins mais pas les connaissances nécessaires.
C’est un formidable outil qui permet à eedomus de prendre une longueur d’avance sur ses concurrentes ! Bien qu’il soit jeune durant les phases de tests, le store risque d’évoluer très rapidement vers quelques choses de très puissant !
Lucas
