Cette application Android est un client pour le framework Avatar.
Comme un client fixe sur un PC Windows, Android Client est un vrai client Avatar:
- Il peut être associé à une pièce mais a l'avantage supplémentaire d'être mobile.
- Il peut être aussi utilisé comme clone d'un client existant. Les règles sont exécutées comme si le client fixe de la pièce les avait passé.
- Il est bi-directionnel. Il ne fait pas qu'envoyer vos règles à Avatar, il reçoit aussi ses messages sur son haut parleur. De même, il accepte les dialogues de questions/réponses (les askme) vous permettant ainsi d'effectuer de véritables conversations synchrones avec Avatar depuis votre smartphone.
- Vous pouvez le configurer pour que les dialogues soient envoyés sur votre système de son préféré, comme par exemple, votre système Sonos.
- Son menu navigateur vous permet de créer des actions sous formes de textes entièrement configurables sans aucun développement avec la possibilité d'y ajouter des paramètres de saisie.
- Par exemple, vous avez un plugin qui permet de gèrer la température de votre chauffage ? Créez une action de menu associée à ce plugin, ajoutez un slider pour définir la température et une liste déroulante de choix pour sélectionner la pièce où la température doit être modifié.
- Avatar Serveur >= 3.3
- Prendre la dernière version courante
- OS Android >= 4.1 Jelly Bean (API 16)
- Depuis le Play Store sur votre smartphone, installez l'application
Avatar Android Client
(App Store). - Téléchargez et dézippez le fichier
Avatar-Plugin-Android.zip
dans un répertoire temporaire. - Copiez le répertoire
android
dans le répertoireAvatar-Serveur/plugins
.
Chaque client Android (un smartphone, une tablette) doit avoir un nom unique et doit être associé à un répertoire de liaison du même nom dans le répertoire android/clients
.
A l'installation, un répertoire de liaison android/clients/Android
existe déjà pour un client Android
configuré dans les paramètres par défaut de l'application installée sur votre smartphone.
Pour changer le nom du client par défaut:
- Renommez le répertoire
android/clients/Android
par le nom que vous avez donné dans les paramètres de l'application installée sur votre smartphone.- Par exemple, sur votre smartphone, vous avez changé le nom en
Salon
, renommez alors le répertoireandroid/clients/Android
enandroid/clients/Salon
- Par exemple, sur votre smartphone, vous avez changé le nom en
- Ouvrez le fichier
client.ini
dans le répertoire de votre client et modifiez la propriétéclient
par le nom que vous avez donné.
Pour ajouter un autre client:
- Copiez un répertoire de liaison disponible dans
android/clients/
en le nom que vous avez donné dans les paramètres de l'application installée sur votre smartphone.- Par exemple, un répertoire de liaison
Salon
pour un clientSalon
existe, copiez alors ce répertoireandroid/clients/Salon
enandroid/clients/Cuisine
(en supposant que votre nouveau client Android s'appelleCuisine
).
- Par exemple, un répertoire de liaison
- Ouvrez le fichier
client.ini
dans le répertoire de votre nouveau client et modifiez la propriétéclient
par le nom que vous lui avez donné.
Cette version intégre la possibilité d'avoir une voix différente pour chaque client android.
La voix par défaut est "Virginie".
Pour changer la voix:
- Ouvrez le fichier
client.ini
dans le répertoire de votre client et modifiez la propriétévoice
-name
par le nom de la voix à utiliser.
Important Depuis la version 1.3, les voix 64 bits sont parfaitement reconnues. Il n'est plus nécessaire de modifier la base de registre. Si vous avez modifié le registre de votre PC serveur 64 bits A.V.A.T.A.R, supprimez vos modifications de registre, désinstallez la voix puis réinstallez-la.
Depuis la version 0.1.1 du Client Android pour Avatar , la configuration est automatique.
Après avoir démarré le Serveur Avatar et lancé l'application sur votre téléphone:
- Déplacez-vous dans les paramètres de l'application
- Cliquez sur le bouton à coté de l'adresse IP du serveur Avatar (pour une 1ère connexion, l'adresse IP est XXX.XXX.XXX.XXX)
- L'application:
- Recherche le serveur Avatar sur le réseau
- Configure automatiquement les paramètres de connexion sur le Serveur:
- Le nom du client (Champ "Nom du client" dans les paramètres de l'application)
- L'adresse IP du client (Champ "Mon IP adresse" dans les paramètres de l'application)
- Le port de communication du client (Champ "Mon IP PORT" dans les paramètres de l'application)
- Configure automatiquement le paramètre de connexion sur le client:
- L'adresse IP du Serveur
- L'application:
Lorsque vous modifiez le nom du client Android dans les paramètres de l'application sur votre smartphone ou que son adresse IP a changée (adressage DHCP) ou encore si vous changez de serveur Avatar, utilisez ce bouton pour remettre à jour automatiquement les propriétés de l'application dans le serveur Avatar et les paramètres dans l'application Android.
Vous devez aussi définir quelques paramètres supplémentaires sur le smartphone, référez-vous aux paramètres de l'application ou à l'aide en ligne dans la page d'À propos de l'application.
Aucune configuration n'est nécessaire, les clients Android mobiles sont reconnus automatiquement.
Une nouvelle fonction Avatar.isMobile()
a été ajoutée (Avatar V 0.1.6 et supérieure) afin de savoir si le client est un client Android et pouvoir le gérer dans vos plugins.
if (Avatar.isMobile(data.client)) {
// Do stuff...
}
Avatar.isMobile(client)
- true si le client est un client mobile.
- false si le client n'est pas un client mobile.
var clients = Avatar.Socket.getClients();
_.map(clients, function(num) {
// Redémarre le client Avatar si il n'est pas un mobile...
if (!Avatar.isMobile(num.id))
Avatar.runApp('%CD%/restart/Restart.vbs', null, num.id);
});
Important:
Plusieurs propriétés sont envoyées automatiquement avec la requète HTTP de votre règle vers le serveur Avatar. Ces propriétés peuvent être utilisées dans vos plugins. Voir le chapitre Développement.
- Appuyez sur le bouton "REC".
- Attendez le bip de la reconnaissance vocale pour dicter une règle.
- Le bip vous signifie que la reconnaissance est disponible. Il peut arriver dans certains cas qu'il y ait une latence dû au réseau Wi-Fi ou aux performances de votre smartphone. Dans tous les cas, si cela arrive, soyez patient. L'application se débloquera toujours d'elle-même.
- Dictez votre règle.
Pour les dialogues AskMe, attendez toujours le bip de la reconnaissance vocale pour dicter vos réponses.
Il existe quelques règles vocales que vous pouvez dicter sur votre smartphone. Ces règles permettent d'intérrompre l'écoute d'Avatar.
Les règles sont définies dans le fichier Avatar-Serveur/plugins/android/android.prop
et dans le tableau "rules":
- "listen_stop" : Les règles simples lorsque vous avez déclenché l'écoute sur votre smartphone et que vous voulez l'intérrompre.
- Par défaut : "Je ne t'ai rien demandé","non rien","désolé rien"
- "listen_stop_gracefully" : Les règles gracieuses lorsque vous avez déclenché l'écoute sur votre smartphone et que vous voulez l'intérrompre.
- Par défaut : "merci Sarah"
Avatar vous répond les phrases pré-définies pour chaque client dans le fichier client.ini associé.
"locale" : {
"fr-FR" : {
"stop_listen" : "d'accord|reçu|pas d'soucis",
"stop_listen_gracefully": "avec plaisir|à ton service"
}
}
Il est possible de définir des actions "textes" dans le navigateur de l'application. Ces règles sont associéés à des règles de plugins existants uniquement.
Ces actions sont regroupées par menus et sont entièrement paramètrables. Ils sont définis dans le fichier client.ini
du répertoire de chaque client qui peut ainsi avoir ses propres menus et actions.
Point d'entré:
"navigation_cmds" : {
},
Les menus de navigateur regroupent les actions selon votre configuration, par exemple par périphériques (sons, box tv, box domotique) ou encore par pièces ('Salon', 'Chambre', etc...).
"navigation_cmds" : {
"Nom de Menu 1" : {
"description" : "Description principale du menu 1",
"plugin" : "nom du plugin global associé au menu 1",
"client" : "nom du client global associé au menu 1",
"actions" : {
}
},
"Nom de Menu 2" : {
....
....
}
},
Propriété | Obligatoire | Description |
---|---|---|
Nom de Menu | Oui | Le menu regroupant les actions dans le menu déroulant de l'application et apparaissant aussi en haut de la page de l'action. |
description | Non | Une description apparaissant en dessous du menu dans la page de l'action. |
plugin | Non (partiel) | Défini un plugin global pour toutes les actions du menu. Si aucun plugin n'est spécifié pour l'action du menu, alors ce plugin est utilisé. Attention, si ce paramètre n'est pas défini, toutes les actions du menu doivent avoir un paramètre plugin . |
client | Non | Défini un client global pour l'exécution de toutes les actions du menu. Si aucun client n'est spécifié pour l'action alors ce client est utilisé. Si aucun client n'est spécifié (globalement et dans l'action) alors le nom du client Android défini dans les paramètres de l'application est utilisé. Voir le tableau Mots-clés pour le paramètre client pour les mot-clés possibles. |
actions | Oui | Défini les actions à exécuter pour ce menu. voir le tableau Actions de menu suivant pour la description d'une action. |
"navigation_cmds" : {
"Nom de Menu 1" : {
"description" : "Description principale du menu 1",
"plugin" : "nom du plugin global associé au menu 1",
"client" : "nom du client global associé au menu 1",
"actions" : {
"nom de l'action 1" : {
"order" : "Ordre de l'action dans le menu",
"description" : "Description de l'action",
"client" : "nom du client spécifique pour l'action",
"plugin" : "nom du plugin spécifique pour l'action",
"close" : "Ferme l'activité action après l'exécution",
"command" : "nom de la commande à exécuter dans le plugin",
"type" : "Type d'action à effectuer",
"icon" : {
"name" : "nom de l'icone",
"deftype" : "drawable",
"defpackage" : "android"
}
},
"nom de l'action 2" : {
....
....
}
}
},
....
},
Propriété | Obligatoire | Description |
---|---|---|
Nom de l'action | Oui | Le nom de l'action à exécuter. Apparait dans le menu déroulant de l'application et aussi dans la page de l'action. |
order | Oui | L'ordre de l'action dans le menu. Commence à 1 et s'incrémente pour chaque action du menu. Vous pouvez modifier l'ordre de la numérotation des actions, par exemple, commencer à order=3 pour la 1ere action puis order=1 pour la 2ème et order=1 pour la 3ème, ce qui compte, c'est qu'il y ait un nombre égal d'order et d'actions. |
description | Non | Une description apparaissant en dessous de l'action dans la page de l'action. |
client | Non | Défini un client spécifique pour l'exécution de l'action. Si aucun client n'est spécifié pour l'action, alors le client global (au niveau du menu) est utilisé. Si aucun client n'est spécifié (globalement et dans l'action) alors le nom du client Android est utilisé. Voir le tableau Mots-clés pour le paramètre client pour les mot-clés possibles. |
plugin | Non (partiel) | Défini un plugin spécifique pour l'action. Si aucun plugin n'est spécifié alors le plugin global (au niveau du menu) est utilisé. |
close | Non | Comme une page peut être ouverte pour une action, par exemple pour choisir un paramètre à envoyer avec la commande, ce paramètre est à utiliser si vous désirez la fermer après son exécution et revenir dans la page principale de l'application. A utiliser aussi lorsque votre plugin envoie un message de confirmation vocale. Les message vocaux ne peuvent être vocalisés que dans la page principale, donc fermez la page Action est nécessaire dans ce cas pour vocaliser le message. |
command | Non | Si nécessaire, les paramètres de commande du plugin pour l'action. |
type | Non | Voir le tableau des types d'actions ci-dessous. |
icon | Non | Défini une image pour l'action dans le navigateur. 3 paramètres sont à définir: name: Le nom de l'image. deftype: Le type d'image. Doit toujours être "drawable". defpackage: Package de définition de l'image. Doit toujours être "android". Référez-vous au fichier android/images/Icons.png pour avoir une représentation des icones Android disponibles et leurs noms. |
(1): La propriété "type" peut avoir les types chainables séparés par un caractère "&" vous permettant de créer une saisie de plusieurs valeurs pour une action, par exemple:
"type" : "slider:<def du slider>&spinner:<def du spinner>&editText<def de l'editTExt>&spinner:<def du spinner>&slider:<def du slider>"
(2): L'IDentifiant d'un type chainable est obligatoire pour repérer le widget dans l'activité action. Commence à 1 et s'incrémente pour chaque chainable ajouté dans le type. Par exemple, un 1er slider aura un ID à 1 puis le suivant aura un ID à 2 puis un editText suivant aura un ID à 3, etc..., Exemple:
"type" : "slider:setvol@**1**@350@100@Define volume:&slider:setsize@**2**@350@100@Define size:&editText:room@**3**@300@Define room"
En plus de spécifier un nom de client Avatar, comme par exemple "Salon", il est possible de définir des mots-clés:
client | Description |
---|---|
currentRoom | Comme pour un client fixe sur PC Windows, "currentRoom" permet de définir l'exécution de l'action pour la pièce courante. La pièce courante est définie soit par la propriété default.client du fichier de propriétés d'Avatar, soit par des capteurs de présences qui modifient automatiquement la variable Avatar.currentRoom , soit par tout autre moyen, comme par exemple, un menu de l'application qui modifie cette variable, une règle vocale "Je suis dans le Salon", etc... Ainsi, une commande unique peut commander le même équipement dans toutes les pièces. Par exemple, une action "Allume la lumière" sera donc exécutée dans la pièce courante, indépendamment de l'endroit où vous vous trouvez. |
Server | Permet de définir l'exécution de l'action sur le serveur Avatar. |
N'importe quoi d'autre | Si vous définissez une autre valeur pour la propriété "client" de l'action, vous devrez absolument gérer une autre propriété à envoyer au plugin comme nom de client pour l'exécution. Voir l'exemple avec la valeur "la pièce sélectionnée" dans le chapitre ci-dessous. |
Vous pouvez visualiser des exemples de création de menus/actions dans le fichier client.ini du répertoire de liaison du plugin/clients
.
Quelques exemples sont très intéressants pour connaitre le potentiel des actions et des propriétés qu'ont peut définir.
Par exemple, définir la propriété "client" avec une phrase (ex: la pièce sélectionnée) et ajouter un paramètre "setRoom" dans la requète HTTP qui recevra la valeur selectionnée qui sera traitée par le plugin.
Chercher "la pièce sélectionnée" dans le fichier client.ini de plugin/clients
pour voir l'exemple.
Les propriétés HTTP sont à utiliser dans vos plugins et sont accessibles via l'objet data.action
data.client
Contient toujours le nom du client Android qui envoie l'action.
data.action.mobile
Si cette variable existe et non null alors l'exécution provient d'un client Android.
if (data.action.mobile) {
// Do stuff...
}
data.action.room
Contient la valeur de la propriété client définie dans les actions de menus si celle-ci est présente (non obligatoire, certains plugins ne nécessitent pas de client pour fonctionner).
Si la valeur est currentRoom
, cette valeur est automatiquement remplacée par la pièce courante dans Avatar.
Avec toute ces variables, nous pouvons "jouer" afin de récupérer tout ce que l'on veut, par exemple:
Supposons notre plugin dans lequel nous voulons connaitre:
- QUI a envoyé l'action
- QUI doit l'exécuter
QUI a envoyé l'action est très facile à connaitre, c'est toujours data.client
QUI doit l'exécuter
Plusieurs paramètres peuvent définir ce "QUI". En effet, ce paramètre peut provenir de différentes sources et donc ne pas forcément avoir le même nom:
- Une box domotique peut envoyer un paramètre data.action.room (ou autre chose...)
- Le traitement d'un ordre vocale d'un client fixe (dans le fichier action du plugin) peut aussi envoyer un paramètre avec un nom différent...
- Même punition avec le client mobile...
Bref, vous l'aurez compris, il est nécessaire d'utiliser toujours les mêmes noms de variables pour toutes ces sources et de bien structurer les développements.
Imaginons maintenant une fonction qui retourne le bon nom pour le QUI doit l'exécuter:
var setClient = function (data) {
// client direct (la commande provient du client et est exécutée sur le client)
var client = data.client;
if (data.action.room) {
// Client spécifique fixe (la commande provient du paramètre HTTP "client" d'un client Android)
// Ou
// de la fonction Avatar.ia.clientFromRule() qui retourne 'current' s'il n'y a pas de nom de client dans la règle vocale
client = (data.action.room != 'current') ? data.action.room : (Avatar.currentRoom) ? Avatar.currentRoom : Config.default.client;
}
if (data.action.setRoom) {
// Client spécifique non fixe dans la commande HTTP d'un client Android
client = data.action.setRoom;
}
return client;
}
Explication:
client
est d'abord "sété" avecdata.client
, de cette façon, si c'est un client fixe qui envoie l'action à exécuter sur "ce client", on est bon...- Ensuite, on test si il y a une variable
data.action.room
non null. Si c'est le cas, alors c'est a exécuter sur le client défini dans cette variable qui peut être la pièce courante ou un nom de pièce. - Ensuite, on peut "jouer" avec tous les autres paramètres possibles, comme
data.action.setRoom
qui est défini dans une requète HTTP du client Android... - Si il y en a d'autres, alors on peut continuer à tester d'autres variables...
- Et on retourne client dans la fonction principale, ce qui donne:
exports.action = function(data, callback){
var client = setClient(data);
info("Commande envoyée par:", data.client);
info("Commande exécutée pour:", client);
// Je peux retourner un message vocale sur le client qui a envoyé la commande (soit data.client):
Avatar.speak("On est bon !", data.client, function(){
Avatar.Speech.end(data.client);
});
// Je peux exécuter l'action sur le client désigné (soit client):
switchLight (client, "On");
callback();
}
Vous pouvez retrouver des exemples de gestion des clients (les QUI) dans les plugins `generic` et `SonosPlayer`.
Version 1.3 - 02/09/2019
- Voix configurable pour chaque client android.
Version 0.1.2 - 22/02/2019
- Mise à jour mineure pour la compatibilité avec Avatar 3.0 Released
- Fichier android\clients\Android\client.js
- Peut être copié seul dans chaque répertoire de client Android plutôt que de reinstallé le plugin complet.
- Fichier android\clients\Android\client.js
Version 0.1.1 - 13/01/2018
- Mise à jour mineure pour la compatibilité avec Avatar 3.0
Version 0.1.0 - 13/01/2018
- Initial version