Installer et configurer un plugin avec S.A.R.A.H.

Hervé

il y a 10 ans

Maintenant que S.A.R.A.H. est installé, il est temps de lui permettre de s’exprimer. Ses capacités et fonctionnalités lui sont données par des ajouts logiciels appelés plugins. Développés par le créateur de l’application mais également par toute une armée de bénévoles bien intentionnés, ils sont mis à disposition de tout un chacun sur un store dédié à S.A.R.A.H. Voyons un peu ensemble ce qu’est un plugin et à quoi cela peut bien servir.

Après avoir installé S.A.R.A.H., la suite des événements est de lui adjoindre des capacités de communication et d’interaction. Cela se fait par du développement. Tout le monde n’étant pas développeur le partage des plugins est une bonne manière de pouvoir bénéficier des talents des autres. Afin de partager ces petites briques logicielles, l’architecture de S.A.R.A.H. permet de les mettre à disposition pour qu’ils puissent être facilement réutilisés par d’autres utilisateurs.

Présentation

Il existe un bon nombre de plugins. Ils permettent de faire tout un tas de choses. Cela va de la récupération de la météo, à la consultation du trafic, en passant par des jeux ou des blagues. En ce qui concerne la domotique, cela se concrétise par la communication avec de nombreux systèmes domotiques. Pour qu’un tel système puisse discuter avec S.A.R.A.H. il lui suffit de proposer des API. C’est le cas de la Zibase, de l’Eedomus, de l’IPX800, de HoMiDoM, de la Zipabox, ou encore de la Vera… De même plusieurs objets connectés ont bénéficié de développements de la part de la communauté et peuvent ainsi être actionnés ou consultés à la voix. On pourra citer à titre d’exemple la station connectée Netatmo ou encore le lapin Karotz.

Les plugins sont tous construits selon le même principe. Ils sont constitués de plusieurs fichiers répondant à des règles précises de nommage et d’architecture. Ils sont packagés en fichiers ZIP. Ce fichier compressé comprend les 5 fichiers principaux suivants:

{plugin}.js : le code javascript du plugin
{plugin}.prop : le fichier de propriétés qui permet à S.A.R.A.H. de l’intégrer dans la bibliothèque des plugins
{plugin}.xml : fichier contenant la listes des mots et phrases que l’utilisateur devra prononcer afin de pouvoir interagir avec le plugin. C’est le fichier de grammaire vocale
{plugin}.gesture : fichier contenant la listes des gestes que l’utilisateur devra effectuer afin de pouvoir interagir avec le plugin. C’est le fichier de grammaire gestuelle
index.html : fichier descriptif du plugin documentant à l’idéal le plugin

De plus amples détails sont donnés par la lecture de l’article de présentation sur le site du projet bien dans le site de documentation du produit.

Installation d’un plugin

Pour installer un plugin il y a 2 manières de procéder: manuellement ou via l’AppStore.

Pour installer un plugin manuellement il faut:

télécharger le plugin souhaité dans la bibliothèque de plugins
si le plugin s’appelle “demo” et que S.A.R.A.H. a été installé dans le répertoire c:\sarah\, il faut le décompresser le contenu du fichier ZIP dans le sous répertoire c:\sarah\plugins\demo\

Pour installer un plugin via l’AppStore il faut :

se connecter à l’interface web de S.A.R.A.H. accessible via l’adresse web suivante: http://127.0.0.1:8080
aller dans “Store” dans le menu de droite en dessous de “Accueil”.

choisir le plugin souhaité
l’installer en cliquant sur “Installer”

Valider l’installation en cliquant sur “Confirmer”

De temps à autres il peut arriver que le fait d’appuyer sur “confirmer” ne produise aucun effet. La fenêtre de confirmation reste ouverte. Vous devez alors appuyer à nouveau sur ce bouton “Confirmer” plusieurs fois pour que cela fonctionne.

Il faut ensuite éteindre le serveur de S.A.R.A.H. puis le relancer. Je vous laisse consulter le précédent article si vous ne vous souvenez pas de la manip à faire.

Désinstallation d’un plugin

Tout comme l’installation, la désinstallation d’un plugin peut se faire en manuel ou bien via l’AppStore.

Pour désinstaller un plugin manuellement il faut:

si le plugin s’appelle “demo” et que S.A.R.A.H. a été installé dans le répertoire c:\sarah\, il faut tous simplement supprimer le sous répertoire c:\sarah\plugins\demo\

Pour désinstaller un plugin via l’AppStore il faut :

se connecter à l’interface web de S.A.R.A.H. (http://127.0.0.1:8080)
aller dans “Store” dans le menu de droite
choisir le plugin souhaité

le désinstaller en cliquant sur “Supprimer”
Valider l’installation en cliquant sur “Confirmer”

Pensez ensuite à éteindre le serveur S.A.R.A.H. et à le relancer ensuite.

Paramétrage d’un plugin

Certains plugins ont besoin d’être paramétrés pour fonctionner convenablement. Si l’on prend l’exemple du plugin eedomus. Il faut d’un côté lui donner les informations nécessaires pour se connecter à votre box eedomus et de l’autre lui indiquer quelles sont les phrases à prononcer pour que S.A.R.A.H. interagisse avec la box eedomus en utilisant son API.

Après avoir installé le plugin eedomus en employant au choix la méthode manuelle ou via l’AppStore il faut lui indiquer les paramètres de connections. Pour cela:

se connecter à l’interface web de S.A.R.A.H. (http://127.0.0.1:8080)

sur la page d’accueil retrouvez le plugin eedomus et appuyez sur le coin supérieur droit pour accéder au paramétrage du plugin

Tous les plugins n’ont pas d’image de présentation appelé portlet. C’est une fonctionnalité non obligatoire mis à disposition des développeurs.

3 boutons sont alors visibles sur le portlet du plugin eedomus:

le plus à gauche (1) permet d’accéder au paramétrage du plugin
le bouton central (2) permet de consulter la documentation du plugin
le bouton à droite (3) permet de modifier le code ou la grammaire du plugin

En appuyant sur le bouton de gauche (2) vous pourrez renseigner les paramètres de connexion demandés puis les enregistrer.

Il faut ensuite paramétrer l’ensemble des commandes vocales qui vous permettront d’interagir avec votre box domotique eedomus par l’intermédiaire de S.A.R.A.H. Ces phrases se trouvent dans le fichier qui porte le nom du plugin et qui porte l’extension “.XML”. Dans notre exemple il faudra donc modifier le fichier “eedomus.xml”.

A ce stade il est important de rappeler comment fonctionne la reconnaissance vocale dans S.A.R.A.H.: la reconnaissance vocale marche en 3 étapes.

Le moteur tente de reconnaître une phrase correspondant à la grammaire.
Puis tous les <tag> présenta dans le fichier XML et correspondant à la phrase prononcée sont exécutés.
Enfin une série d’actions sont exécutées.

Pour modifier le fichier XML, un éditeur est disponible directement dans l’application:

Appuyer sur le bouton le plus à droite (3) présent sur le portlet du plugin. Il permet de modifier la grammaire
Sélectionner le fichier “eedomus.xml”
compléter le fichier avec vos ordres et vos périphériques.

Le XML de ce plugin est de la forme :

<grammar version="1.0" xml:lang="fr-FR" mode="voice" root="ruleEedomus" xmlns="http://www.w3.org/2001/06/grammar" tag-format="semantics/1.0">
 <rule id="ruleEedomus" scope="public">
 <example>Sarah allume la lampe du salon</example>
 <tag>out.action=new Object(); </tag>

 <item>Sarah</item>

 <one-of>
 <item>allume<tag>out.action.periphValue=100</tag></item>
 <item>eteint<tag>out.action.periphValue=0</tag></item>
 <item>quel est</item>
 </one-of>

 <one-of>
 <item>la lampe du salon<tag>out.action.periphId=17777</tag></item>
 <item>la lampe de la salle à manger<tag>out.action.periphId=17788</tag></item>
 <item>la température dehors<tag>out.action.periphId=10110</tag></item>
 </one-of>
 
 <tag>out.action._attributes.uri="http://127.0.0.1:8080/sarah/eedomus";</tag>
 </rule>
</grammar>

Pour des raisons de facilité d’utilisation on pourra rajouter dans les actions en plus de “allume”, ou “éteint” les mots “rallume” ou “ferme” par exemple.

Dans l’exemple ci-dessus on a renseigné des ordres ainsi que 2 périphériques. Un actionneur permettant d’allumer ou d’éteindre la lumière du salon et une sonde de température.

<item>Sarah</item> ne doit mas être modifié. Il est possible de changer le prénom de Sarah pour commander à la voix votre système S.A.R.A.H. A la maison il s’appelle “Rose” par exemple. Le programme reconnaîtra automatiquement ce mot dans la grammaire et le remplacera à la volée par le nom qua vous aurez pu paramétré dans la configuration. Vous devez laisser le mot Sarah dans le fichier XML.

En s’inspirant de l’exemple présent à l’installation ou pourra donc avoir les ordres suivants:

<one-of>
 <item>allume<tag>out.action.periphValue=100</tag></item>
 <item>ouvre<tag>out.action.periphValue=100</tag></item>
 <item>monte<tag>out.action.periphValue=100</tag></item>
 <item>remonte<tag>out.action.periphValue=100</tag></item>
 <item>éteint<tag>out.action.periphValue=0</tag></item>
 <item>baisse<tag>out.action.periphValue=0</tag></item>
 <item>ferme<tag>out.action.periphValue=0</tag></item>
 <item>arrête<tag>out.action.periphValue=240</tag></item>
 <item>quelle est</item> 
 <item>quel est</item>
</one-of>

Utilisation du plugin

Le plugin paramétré peut maintenant être utilisé. Imaginons que l’on souhaite par exemple ordonner l’allumage de la lampe du salon. Avec le paramétrage mis en place on pourra tout simplement dire à haute voix: “Sarah allume la lampe du salon”.

Que se passe-t-il exactement lorsque l’on prononce la phrase “Sarah allume la lampe du salon”? Voici comment le programme utilise la grammaire XML pour interpréter votre commande:

si S.A.R.A.H. est appelée par son petit nom:

<item>Sarah</item>

et qu’ensuite l’action “allume” est ordonnée :

<one-of>
 <item>allume<tag>out.action.periphValue=100</tag></item>
 </one-of>

en indiquant que l’ordre s’applique au périphérique “la lampe du salon”:

<one-of>
 <item>la lampe du salon<tag>out.action.periphId=17777</tag></item>
</one-of>

… alors S.A.R.A.H. contactera l’API de la box eedomus pour lui transmettre le fait que vous souhaitez affecter au périphérique 17777 la valeur 100.

En français cela correspond à demander à ce que la lampe du salon s’allume. Ce n’est pas plus compliqué que cela.

En renseignant dans ce fichier l’ensemble des actions ainsi que l’ensemble des périphériques vous pourrez piloter à la voix votre box eedomus que ce soit des périphériques liés à des modules physiques ou virtuels, des capteurs ou des actionneurs HTTP, …

Conclusion

Il y a des plugins correspondant à une multitude de besoins. Si le votre n’est pas pris en compte par un développement déjà effectué par quelqu’un, n’hésitez pas à le créer et à le partager par la suite sur le Store. Il sera surement utile à d’autres. Pour démarrer la création d’un plugin je vous conseille la lecture de cet article en guise d’introduction et de celui-ci pour approfondir le sujet.

on le voit, il faut passer un peu de temps à renseigner dans le fichier eedomus.xml la liste des périphériques qu vous souhaitez piloter à la voix. Cela peut être un peu fastidieux si vous avez beaucoup de périphériques à déclarer. Cela dit ce n’est à faire qu’une seule fois et le jeu en vaut la chandelle car quel plaisir que de pouvoir parler à sa domotique pour qu’elle s’exécute!

Il est également possible que ce soit votre domotique qui vous interpelle en fonction d’un événement ou d’un stimulus précis. Pour cela il faut installer le plugin “Parle” par exemple. Je vous laisse le faire tout seul. Ce sera votre exercice pratique. On verra dans un prochain article comment faire pour que la box puisse prendre la main sur le système S.A.R.A.H.