Le store eedomus

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

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, 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)

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",
       "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
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)
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 : smoke_ok.png

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