Documentation eedomus

Le Store eedomus est un lieu de partage des réalisation de la communauté eedomus.

Tout le monde peut y soumettre son "objet connecté" réalisé autour de requêtes HTTP, de scripts eedomus et d’icônes personnalisées.

Consulter la liste actuelle des périphériques du Store eedomus

Sommaire

1 Ajouter un périphérique du store eedomus sur votre box
2 Réaliser un périphérique pour le store eedomus
3 Soumettre un script pour le store

Ajouter un périphérique du store eedomus sur votre box

Depuis le portail eedomus, cliquez sur Configuration / Ajouter ou supprimer un périphérique / Store eedomus puis cliquez sur le périphérique de votre choix pour en apprendre plus.

Il est possible de télécharger les sources du périphérique si vous souhaitez voir comment il est construit, le faire évoluer et le soumettre à nouveau sur le store ou vous en inspirer pour réaliser votre propre périphérique et le proposer sur le store.

Un lien vers le sujet associé sur le forum eedomus est parfois disponible, c'est un espace sur lequel vous pourrez échanger avec la communauté eedomus autour de ce périphérique.

Enfin cliquez sur Créer afin d'ajouter le périphérique à votre box eedomus.

Réaliser un périphérique pour le store eedomus

Structure d'un périphérique du store eedomus

Un périphérique du store eedomus est composé de plusieurs éléments :

1 fichier JSON eedomus_plugin.json décrivant les périphériques à créer
0 ou plusieurs scripts PHP eedomus
0 ou plusieurs images au format PNG 128x128 dans un sous répertoire /img
0 ou plusieurs fichier readme_xx.md ou xx est la langue employée (fr, en, es, de, ... exemple readme_fr.md). Le contenu est un fichier texte au format MarkDown

Le fichier d'aide est accessible sur la fiche du périphérique du store, sur son formulaire de création et sur les périphériques créés.

Exemple de structure du périphérique Anniversaires:

eedomus_plugin.json

Il s'agit du fichier principal, c'est lui qui décrit la structure de votre périphérique.

Son nom doit impérativement être eedomus_plugin.json

Exemple de eedomus_plugin.json pour la gestion des anniversaires :

Il est possible de créer des actionneurs HTTP et des périphériques à multiples "canaux", pour cela vous pouvez vous inspirez des scripts Smarter Coffee ou Vigilance météo

Vous pouvez vérifier que le contenu de votre JSON est valide avec un outil en ligne du type : https://jsonlint.com/

Structure du JSON

parameters

Cette section décrit les paramètres affichés dans le formulaire affiché lors de la création du périphérique.

parameter: nom du paramètre, doit être unique et pourra être utilisé ensuite via plugin.parameters.xxx

description: Texte affiché à gauche du paramètre

default_value: Valeur par défaut pré-saisie dans le champ

xtype: type de champ : textfield, numberfield, combo, displayfield, checkbox

field: paramétrage du contenu du champ. Ex. width:400, allowBlank:false

Exemple d'utilisation d'expression régulières dans un "textfield"

{
 "parameter": "MAC",
 "description": "Adresse Mac de l'équipement",
 "xtype": "textfield",
 "default_value": "",
 "field": "allowBlank: false , maskRe:/[0-9A-Da-d:]/, maxLength:17, minLength:17, width: 250,
 regex:/^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$/, regexText:'Adresse MAC invalide, format AA:AA:AA:AA:AA:AA'"
}

Exemple d'utilisation d'un "numberfield"

{
 "parameter": "PORT",
 "description": "Port HTTP",
 "xtype": "numberfield",
 "default_value": "80",
 "field": "minValue:0, allowDecimals:false, width:60, allowBlank:false"
},

Détail pour la construction de listes (Combo)

Nouveau : Il est possible de créer des listes dont les valeurs sont prédéfinies, ex :

{
 "parameter": "ZONE_EJP",
 "description": "Zone EJP",
 "xtype": "combo",
 "field": "width:200, allowBlank:false, store:[['nord', 'Nord'], ['ouest', 'Ouest'], ['paca', 'PACA'], ['sud', 'Sud']], triggerAction: 'all'"
}

Ou des listes contenant des périphériques (afin d'éviter la saisie manuelle du code API)

{
 "parameter": "APII", 
 "description": "Périphérique Consommation Instantanée (en w)",
 "xtype": "combo",
 "field": "store : getCombo('/json/list_all.php?value_type=float&filter_unit=W,kW'), displayField: 'label', valueField: 'id',
 triggerAction: 'all', selectOnFocus: true, editable: false, shadow:true, mode: 'local', width: 250, listWidth: 300, allowBlank: true"
}

en utilisant /json/list_all.php tous les périphériques seront affichés.

Cette liste peut être restreinte avec des paramètres qui peuvent être cumulés dans l'URL

Exemple de paramètres: value_type=float; value_type=list; filter_unit=W,kW; actuator_only=1; sensor_only=1

devices

Tableau de périphériques à créer.

device_id: identifiant unique du périphérique, lettre et chiffres en minuscule (peut être réutilisé dans le JSON en appelant plugin.devices.device_id)

parent_id: identifiant parent du périphérique, permet de relier les périphériques entre eux pour une gestion simplifiée en créant un "canal"

module_id

type de périphérique à créer

11 état générique

31 géolocalisation

41 actionneur HTTP

51 capteur HTTP

54 Widget HTML

utilisation_id

Utilisation cible du périphérique

Si module_id = 11 : 0 = N/R, 16 = Armement alarme, 43 = Autre indicateur (Actionneur), 35 = Autre indicateur (Capteur), 42 = Centralisation des ouvertures, 25 = Compteur d'eau, 26 = Compteur d'électricité, 45 = Compteur de gaz, 15 = Consigne de température, 10 = Détecteur d'ouverture, 17 = Détection alarme, 19 = Etat chauffages, 20 = Etat lampes, 21 = Etat présence humaine, 44 = Tarif énergie, 7 = Température

Si module_id = 31 : 0 = N/R

Si module_id = 41 : 0 = N/R, 1 = Lampe, 2 = Appareil électrique, 4 = Chauffage, 15 = Consigne de température, 115 = Mode Thermostat, 43 = Autre, 48 = Ouverture

Si module_id = 51 : 0 = N/R, 7 = Température, 10 = Détecteur d'ouverture, 22 = Humidité, 24 = Luminosité, 25 = Compteur d'eau, 26 = Compteur d'électricité, 29 = Vent [Vitesse], 31 = Indice UV, 32 = Pression, 35 = Autre indicateur, 37 = Détecteur de mouvement, 45 = Compteur de gaz

Si module_id = 54 : 0 = N/R

name: Nom du périphérique, utiliser plugin.name si vous souhaitez reprendre le nom qui sera saisi par l'utilisateur lors de la création du périphérique

value_type

type de valeur du périphérique

list, les valeurs du périphérique seront parmi une liste définie dans le JSON device.values

float les valeurs du périphérique seront un nombre décimal

string les valeurs du périphérique seront un texte libre (limité à 40 caractères)

icon: icône à afficher pour le périphérique. ex. tv.png; l’icône doit être disponible parmi les images globales d'eedomus ou se trouver dans le zip du périphérique du store

default_value: Valeur par défaut que prendra le périphérique à sa création

Nouveau : les champs create et enable qui peuvent valoir 0 ou 1 mais également prendre la valeur de plugin.parameters.xxx permette de ne créer ou de n'activer que les canaux souhaités pour un périphérique.

Il est possible d'inverser la valeur avec le caractère "!", ex. !plugin.parameters.xxx ou de faire une comparaison du type plugin.parameters.xxx==3 ou plugin.parameters.xxx!=3

Vous pouvez ainsi ajouter un paramètre de type combo dont la valeur servira à créer/afficher ou non un canal optionnel de périphérique

create: 1 ou 0, crée le périphérique où non

enable: 1 ou 0, le périphérique est créé mais son état est actif où non (Quand un périphérique est désactivé, il n'est plus visible)

visible: 1 ou 0, le périphérique est créé mais aucune pièce ne lui sera affectée (Il restera invisible à moins que l'utilisateur ne lui affecte une pièce)

device.parameters

Ce sont les paramètres d'un périphériques qui apparaitrons dans l'interface du périphérique et qui pourront être modifiables par la suite par l'utilisateur.

Exemple de paramètres qui peuvent être définis dans le JSON d'un périphérique :

Pour un Capteur ou actionneur HTTP

 {
   "VAR1": "plugin.parameters.car_id",
   "VAR2": "plugin.parameters.parent_controller_module_id",
   "value_type": "float",
   "ignore_errors": 3,
   "RAW_URL": "http://localhost/script/?exec=xee_oauth.php&car_id=[VAR1]&position_controller_module_id=[VAR2]",
   "RAW_XPATH": "//*[contains(text(), 'EVBatteryHealth')]/../value",
   "POLLING": "3"
 }

Pour un Widget HTML

"parameters":
 {
   "SMARTPHONE_HEIGHT": 5,
   "CONTENT_NOSCROLL": 1,
   "VAR1": "POW:plugin.devices.power,FAN:plugin.devices.fan,…",
   "RAW_URL": "http://localhost/script/?exec=ibox_widget.php&eepl=[VAR1]"
 }

device.values

Ce sont les valeurs qu'un périphérique périphérique peut prendre quand il a été défini avec value_type = list

Exemple :

"values":
 [
  { "value": "up", "http_url": "http://localhost/script/?exec=freebox.php&freebox_ip=[VAR1]", 
   "http_type": "GET", "http_params": "", "description": "Up", "icon": "heartbeat_c1.png" },
  { "value": "down", "http_url": "http://localhost/script/?exec=freebox.php&freebox_ip=[VAR1]", 
   "http_type": "GET", "http_params": "", "description": "Down", "icon": "heartbeat_c2.png" }
 ]

value: Valeur brute du périphérique (ne sera pas affichée, préférer un nombre)

description: Valeur texte affichée

icon: Icône affichée

http_url: URL qu'eedomus appellera lorsque cette action sera déclenchée (actionneur uniquement)

http_type: Type de requête effectuée pour l'URL (GET/POST/PUT/DELETE)

http_params: sera rajouté à la fin de l'URL

hidden: 0 ou 1. Si 1, la valeur ne sera pas affichée dans la liste des actions possibles de l'actionneur. (mais pourra être utilisé dans les règles)

device.macros

Macros d'un périphérique (valable pour un actionneur uniquement)

Exemple :

"macros":
 [
  { "name": "Extinction dans [x]min", "dynamic_value": 10,
   "actions": 
   [ 
    { "wait": 0, "wait_unit": "min", "action_type": "a", "value": 1 }, 
    { "wait": 10, "dynamic": true, "wait_unit": "min", "action_type": "a", "value": 0 } 
   ] 
  }
 ]

macro_id: (optionnel) identifiant de la macro, lettre et chiffres en minuscule. Peut être réutilisé dans le JSON avec plugin.macros.macro_id

name: Nom de la macro ([x] sera remplacé par la "dynamic_value" sélectionnée par l'utilisateur (optionnel))

dynamic_value: Valeur par défaut. Pourra être changée par l'utilisateur au moment du lancement de la macro.

actions: Liste des actions de la macro qui s’exécuterons consécutivement

wait: durée d'attente avant d'exécuter l'action

wait_unit: unité de la durée d'attente (sec/min/heu ou rnd pour une valeur aléatoire de 0 à 60 min)

action_type: "a" pour action, "r" pour répéter la macro

value: Valeur brute du périphérique pour l'action

hidden

   0 ou 1. Si 1, la valeur ne sera pas affichée dans la liste des macros de l'actionneur. (mais pourra être utilisé dans les règles)

rules

Nouveau : il est possible de créer automatiquement des règles depuis le JSON (ex. dans le script Double détection)

Exemple:

"rules": [
     {
       "name_fr": "plugin.name - Synchro Détecteur 1 - plugin.parameters.NAME1",
       "enable" : 1,
       "cron":
       [
         { "day_of_week": "1", "hour": "12", "minute": "0" }
       ],
       "criterias":
       [
         { "device_id": "plugin.parameters.API1", "type": "c" }
       ],
       "actions":
       [
         { "device_id": "plugin.devices.detect1", "type": "other", "action": "plugin.parameters.API1"}
       ]
     }
   ]

name_fr: Nom de la règle, peut contenir des tags du type plugin.name ou plugin.parameters.xxx

enable: 0 la règle est créée mais inactive, 1 la règle est active

cron: Tableau de critères horaires : day_of_week (-1= Tous les jours, 1=lundi, 2=mardi...), hour (-1=Toutes les heures, 0..23), minute (-1=Toutes les minutes, 0..59)

criterias: Tableau des critères de règles, peut contenir 0 à N valeurs (0 valeur pour une règle de type CRON, implémentation à venir)

device_id: code API du périphérique. Entier ou plugin.parameters.xxx

type: e est; t est maintenant; u devient; d devient maintenant; a n'a pas; c change de valeur; i était

criteria: == égal à; < inférieur à; > supérieur à; != différent de; M== égal au périphérique; M< inférieur au périphérique; M> supérieur au périphérique; M!= différent du périphérique; ch changé depuis; hb contacté le serveur depuis; g< à moins de; g> à plus de; macro en cours de macro; macr! non en cours de macro

target: Valeur cible ou code API du périphérique. Entier ou plugin.parameters.xxx

operation: AND Et (Par défaut si non précisé dans le JSON); OR Ou

actions: Tableau des actions a exécuter lorsque les critères sont remplis, peut contenir 1 à N valeurs

device_id: code API du périphérique. Entier ou plugin.parameters.xxx

type: direct Action directe (ex. 0 pour un Off, 0 pour une "mise à jour de capteur HTTP"); macro Lancer une macro; other le périphérique prend la valeur d'un autre périphérique

action: Valeur cible ou code API du périphérique ou code API de la macro. Entier ou plugin.parameters.xxx

script(s)

Votre périphérique peut faire appel à 0 ou plusieurs scripts eedomus.

Reportez vous à la documentation des scripts pour découvrir la manière de les écrire ou inspirez vous des périphériques déjà présents dans le store en téléchargeant leurs sources.

images

Les images référencées dans eedomus_plugin.json peuvent être des images communes à tous les utilisateurs eedomus (Faire un clic droit depuis son browser Copier l'adresse de l'image et ne conserver que le nom après le dernier "/"

Exemple pour :

Le lien original est https://secure.eedomus.com/img/mdm/01/smoke_ok.png dans eedomus_plugin.json l'image sera smoke_ok.png

Il est également possible d'embarquer des images dans le répertoire /img du zip, dans ce cas il suffira de les référencer dans eedomus_plugin.json par leur nom.

Soumettre un script pour le store

Depuis le store eedomus, cliquez sur le lien Publier sur le store (En haut à droite)

Cliquez sur Parcourir afin d'attacher le fichier au format .zip contenant votre périphérique et cliquez sur Envoyer

Le script est alors immédiatement disponible en mode Privé pour l'utilisateur qui peut l'utiliser pour ses propres besoins.

Ensuite il est possible de proposer le script pour tous en cliquant sur Publier

L'équipe eedomus traitera votre demande de pulibcation dans les meilleurs délais, vous serez informé par email de la publication de votre script. Si le script ne peut être publié en l'état nous échangerons par mail afin d'effectuer les ajustements nécessaires.

Une fois publié, les modifications ultérieures du script (Correction de bugs, améliorations) ne sont plus soumises à l'approbation de l'équipe eedomus dans la mesure où vous êtes l'auteur original du script.

En d'autre terme vous pouvez sans problème corriger ou améliorer un script dont vous n'êtes pas l'auteur, mais une validation sera nécessaire pour des raisons de sécurité.

Navigation

Le store eedomus