Ce document a pour objectif de définir le fonctionnement des Gadgets TuxDroid et du conteneur associé. Il a valeur de loi, et nul n'est sensé ignorer la loi
L'ensemble des développements est sous Licence GPL v2. Chaque fichier source dispose d'un en-tête décrivant sommairement la licence, le nom de l'auteur et les droits à la société Kysoh.
Le système proposé suit le schéma d'un framework. C'est à dire que les gadgets sont insérés dans le flot de traitement d'un ensemble plus large qui en fixe les règles de gestion, contrairement à une API ou une librairie qui s'insère dans le flot de traitement de l'appelant.
L'architecture du Tuxdroid Gadget Framework est centré autour d'un conteneur. Cette philosophie est emprunté aux serveurs d'application, de même que le système de déploiement/retrait des gadgets du système. L'idée en est que le framework maintient en permanence la liste des gadgets qu'il connait, de leur état, de leurs propriétés, etc. Le conteneur est le médiateur obligatoire entre l'application tiers et les gadgets. C'est lui qui les instancie, les exécute, les arrête, les détruit, etc.
Le conteneur de gadget observe en permanence un dossier spécial dit dossier d'auto déploiement. Lorsqu'il y détecte l'arrivée d'une nouvelle archive, il la décompresse dans un autre dossier dit dossier de travail. Cette phase est appelée déploiement.
A chaque lancement du conteneur, les gadgets sont redéployés. Si un gadget est détruit, le dossier correspondant l'est lui aussi. Enfin, si au démarrage un dossier n'a pas d'archive associée, il est automatiquement retiré.
Le conteneur est un objet Java produisant un certain nombre de notifications à ceux qui s'y abonnent
La mise en oeuvre du conteneur est très simple
Un gadget est programme écrit dans n'importe quel langage qui lors de son exécution communique avec le conteneur à l'aide d'un protocole normalisé. Comme nous l'avons vu plus haut, une fois le gadget déployé dans le conteneur, il est soit utilisable à travers une instance de la class Gadget. Cette instance peut soit être récupérée de manière assynchrone via le listener du conteneur, soit comme suit :
Un Gadget est une archive au format ZIP portant l'extension .tgf. Son contenu est totalement libre. Le langage utilisé pour rédiger un gadget est lui aussi absolument libre (C, en Python, en Java, en Bash, etc.).
A la racine de l'archive se trouve fichier XML, nommé gadgets.xml donnant :
Voici un exemple pour un tel fichier :
Comme vous le voyez, ce fichier peut définir plusieurs gadgets contenus dans la même archive.
La description d'un gadget n'est JAMAIS à lire à travers le fichier XML. En fait toute application utilisant un gadget doit passer impérativement par son instance de la classe Gadget.
La section interpreter définit :
Le gadget fournit aussi des données fondamentales :
Pour accéder à la description d'un gadget, il faut passer par son objet Gadget, par exemple :
Les gadgets utilisent le système gettext standard dans le monde de l'openSource (utilisé par Drupal, Linux, Gnome, etc.).
En fait le concept est ultra simple. L'idée est que toutes les chaînes à traduire sont passées par une fonction unique qui maintient les traductions en mémoire.
Pour du code Java ça donne quelque chose comme cela :
La fonction i18n.tr(....) va chercher dans son dictionnaire la traduction de This is a message with one parameter : %d. S'il la trouve, il renvoie sa valeur, sinon il renvoie la chaîne d'origine.
Il est donc possible de voir ce qui n'est pas encore traduit en basculant par exemple en français et en localisant toutes les chaînes encore en anglais. L'avantage c'est que si la traduction n'a pas encore été faite, les chaînes restent lisibles pour l'utilisateur ET dans le code.
Les dictionnaires sont de simples fichiers textes que l'objet I18n va chercher dans le dossier qui est passé en paramètre de son constructeur (./resources). Pour ce faire, il se base sur la fonction java Locale.getDefault().getLanguage() qui renvoie la langue courante du système.
Pour un système français cela renvoie "fr". L'objet i18n va donc chercher un fichier appelé ./resources/fr.po.
Ce fichier fr.po contient une série de traductions sous la forme :
Ce sont ces traductions que l'objet I18n va charger en mémoire et que la fonction i18n.tr va utiliser.
Pour les fichiers XML, il n'y a évidement pas de fonction i18n.tr directement dans le fichier. C'est le framework qui avant de renvoyer une chaîne provenant du fichier gadgets.xml, par exemple au ControlCenter, va la faire passer dans i18n.tr.
De la même manière le framework va passer à la fonction i18n.tr toutes les notifications de gadget de type message. Du coup, le code gadget suivant sera automatiquement traduit :
Le Control Center recevra cette notification déjà traduite donc, sauf si bien sur cette chaîne n'est pas dans le fichier .po de la langue courante ou que la langue courante n'a pas encore de fichier .po.
Le format des fichiers .po est très évolué, il permet de chercher des chaînes simples, des chaînes "floues", des chaînes avec pluriels, etc. Pour l'instant, la lecture des fichiers .po se fait dans karmalab-commons (la librairie d'utilitaires utilisé par le framework) avec une version très simple et très rapide d'un parser de .po.
Si les besoins évoluent vers plus de complexité, on fera évolué cet objet pareillement.
En somme, les avantages l'approche .po par rapport aux classique Bundles de ressources Java sont :
Pour l'aspect développeur, La génération de .po est elle aussi assez simple, y compris à partir du code Java.
La première étape consiste à générer un fichier .pot (Portable Object Template) qui n'est rien d'autre qu'un .po dont tous les "msgstr" sont vides. Cela se fait par la commande suivante
Ensuite on duplique le .pot en, par exemple, fr.po pour rédiger une traduction ou envoyer les fichiers à un traducteur.
Ensuite pour la mise à jour, quant le code source évolue et donc que de nouveaux messages apparaissent, ou que d'anciens messages disparaissent, il suffit de régénérer le .pot et d'appliquer cette nouvelle mouture aux fichiers .po existants :
Concernant le fichier d'aide du gadget, il est lui aussi traductible mais de manière un peu différente. L'idée est que par défaut le gadget doit avoir un fichier ./resources/help.html et optionellement plusieurs fichiers ./resources/help_xx.html. De la même manière lorsque l'hote demande la référence au fichier d'aide du gadget, celui-ci lui renvoie la version traduite automatiquement si elle existe, la version anglaise le cas échéant ou null si aucun fichier n'est présente.
A travers les sections commands et notifications, le gadget indique au conteneur les commandes qu'il prend en charge et les notifications qui peut générer. Le lancement de ces commandes et la prise en charge des notifications est à la charge du Control Center.
Dans les deux cas, chaque commande/notification est caractérisée par
Pour accéder à ces données, il faut passer par son objet Gadget. Dans les deux cas l'objet retourné est de classe GadgetToken, par exemple :
Dans la section parameters, le Gadget fournit l'ensemble des données dont il a besoin pour fonctionner. Cela correspond à une liste où chaque élément est composé comme suit :
Pour accéder à ces données, il faut passer par son objet Gadget et récupérer l'objet GadgetParameter correspondant, par exemple :
Un gadget dans l'état une fois connu du conteneur est dans un état "chargé" et n'est pas instancié en mémoire (cad exécuté). Seule sa description (cf gadgets.xml) est connue du conteneur et des applications tiers.
Pour exécuter une commande du Gadget, il convient donc de transforme le Gadget en Instance de Gadget que le Control Center va ensuite pouvoir exécuter et même stopper en cours d'exécution si besoin était.
A ce titre on comprend qu'une instance est composée :
La conséquence de cette approche est qu'il n'est pas besoin de faire des gadgets à la configuration complexes mais d'utiliser les instances pour réduire cette complexité. Prenons l'exemple d'un Gadget lisant les flux RSS. Il a pour données l'URL à lire et comme commande checkRSS. Pour effectuer le traitement, il va falloir créer une instance du Gadget RSS, prenant en paramètre la commande à exécuter ET les valeurs des paramètres de l'instance. On en déduit que si l'on désire lire plusieurs flux RSS, il suffira de crée plusieurs instances associées chacune à un jeu de données unique.
Pour créer une instance de gadget à travers le framework, la syntaxe est la suivante
Ensuite une commande est invokable de la manière suivante :
Si command est à null, c'est la commande par défaut du gadget qui est utilisée, sinon il s'agit d'un objet GadgetToken que l'on récupère par gadget.getCommands().get(XXX). Les paramétres sont une liste de GadgetParameter contenant les valeurs des paramétres pour cette exécution de commande.
La communication entre le gadget et l'hôte, doit être suffisamment simple pour permettre la rédaction dans tous les langages. L'idée de base est que les commandes sont passées en argument, les données dans les variables d'environnement, et les notifications sont renvoyés sur le canal StdOut.
Les données dans les variables d'environnement sont préfixées avec la chaîne de caractère tgp_. Si le gadget déclare une données message, il recevra donc sa valeur dans la variable $tgp_message.
Lorsqu'un gadget est exécuté sans paramètres, il revoies sa description sous la forme d'un flux XML. Ensuite exécuté avec en paramètre un ID de commande, il exécute la commande correspondante.
Les notifications sont émises sur le canal stdOut sous la forme :
ID "PARAM1" "PARAM2" ... "PARAM2"
Les paramètres sont des chaînes qui sont échappées sur le caractère ".
Il existe un certain nombre de d'ID de notification standard que le gadget n'a pas besoin de déclarer pour les utiliser :
- répondre
jaguarondi, le 9 May, 2008 - 14:14D'autres niouses fraîches du pingouin? Moi je viens de refaire l'I2C complètement et je m'attaque à la RF, un gros morceau. J'espère pouvoir ainsi fixer le sleep et les problèmes de wifi et j'aurai terminé ma mission (ouais, je t'ai piqué le terme
). Et en attendant que tu finalises ma promotion de correcteur (j'ai pas le tab "actions" avec tes pages, juste sur "mon compte"), voici 2,3 petits trucs:
"il va faudrait"
"ces derniers ne pouvaient pas dire ensuite soutenir que les dites librairies leur appartenait"
"que les fonctionnalité"
"cette librairie a pas mal évoluée"
"le projet [...] pour être définitivement intégrée"
- répondre
Ulhume, le 15 May, 2008 - 13:45Corrigé
Tiens, à l'occaz j'aimerais bien avoir ton avis là dessus (et pas que pour les fautes
http://www.assembla.com/wiki/show/tuxdroid_collaborating/Sp%C3%A9cificat...
- répondre
jaguarondi, le 26 May, 2008 - 10:33Bon ben passons les fautes du genre "sortie standard STDIN" alors
Ca m'a l'air bien foutu en tout cas mais je suis un peu perdu sur les appels vers le gadget. Pour le retour via xml, pas de problème.
Un petit exemple aiderait peut-être à saisir l'ensemble plus facilement. Disons que j'ai un gadget qui fait juste dire hello à tux, avec un bouton hello. J'imagine donc que tu exécutes "hello.xgf description" pour avoir l'info et créer ton IHM. Puis quand le bouton est appuyé, tu lances "hello.xgf hello" et tu récupères la commande à exécuter. C'est bien ça?
Si maintenant je veux avoir une status box qui m'affiche si les yeux sont ouverts ou fermés par exemple, et le bouton à côté qui fera dire hello ou bye bye selon l'état de la status box. Dans ce cas tu dois lancer le gadget en service pour qu'il to renvoie constamment des balises xml quand la status box doit changer. Mais comment fais-tu après pour exécuter la méthode quand le bouton est appuyé? Parce que ton service tourne toujours, et si tu lances une autre commande, tu n'as pas accès à l'état de la status box.
A part ça, le portail assembla a l'air bien foutu, avec tout ce qu'il faut et un esprit agile, ça me plaît bien, je viens de m'inscrire
- répondre
Ulhume, le 26 May, 2008 - 17:59Bon, c'est malin ton exemple, j'ai du tout changer
) Pour la peine, j'ai téléporté tes commentaires
Ca va mieux comme cela ?
- répondre
jaguarondi, le 27 May, 2008 - 10:12Yes, ça va mieux
Bon maintenant, toute la communication avec tux a visiblement lieu en dehors du serveur de gadget, donc du gadget lui-même. Ca veut dire que chaque gadget va devoir se connecter lui-même au serveur REST. Je trouve ça un peu bizarre mais pourquoi pas. Dans ce cas, c'est le serveur qui va devoir refaire tout ce que fait le manager actuel de gadgets, principalement gestion des conflits, priorités, sélection des événements, etc.
Sinon, tout autre chose, comme tu fais souvent des mises à jour de tes articles, ce serait pas mal d'avoir le diff module de drupal sur ton site, comme ça on peut voir uniquement ce qui a changé (enfin, si il fonctionne mieux que http://www.assembla.com/wiki/history/tuxdroid_collaborating/Spécification_Serveur_de_Gadgets n'a visiblement pas compris grand chose aux diffs, tout ce qui est barré est remis tel-quel à côté...)
D'un autre côté, je suppose que moins tu installes de modules séparés du code, moins tu as de problèmes de maintenance et d'update. Sous Plone, plein de modules bien utiles sont abandonnés/pas maintenus ce qui fait que tu deviens vite coincé si tu as pas mal de dépendances externes.
- répondre
Ulhume, le 27 May, 2008 - 12:07Non, ce n'est pas si bizarre que cela si tu envisages cela sous l'angle des librairies. Le framework gadgets a beau être capable de faire tourner un gadget écrit simplement en perl ou en sh, si tu imagines qu'il le soit en Java, il va y avoir deux librairies dont il sera dépendant. L'API Tuxdroid Java qui n'est rien d'autre qu'un stub Java/XML-RPC et l'API Gadget qui fournit un mini serveur telnet qui causera avec le framework gadget. Ca c'est plus une spécification de l'infrastructure, cela ne dédouane pas d'écriture d'API par langage pour rendre cela plus facile d'accès encore.
Sinon excellent ce petit module, je ne connaissais pas. C'est maintenant activé. Ca donne tout son sens aux révision cette histoire, merci !
Pour ce qui est de la profusion de modules, ce n'est pas un gros problème, en tout cas pour moi. Ca m'oblige dés fois à porter moi même certains mais finalement c'est aussi ça le libre.
- répondre
Rémi Jocaille, le 27 May, 2008 - 15:12Concernant l'API (je suis en plein dedans
). Elle est séparée du système de gadgets pour la raison que je veux éviter au maximum les dépendances inter-systèmes ou inter-architectures. La V1 est un vrai supplice à maintenir car dans le même processus sont exécuté : L'API python, le framework (toutes la gestion de déploiement des gadgets, leur encapsulation, les gestion des conflits, la gestion des attitunes (format de scène), la pseudo reconnaissance vocale, les traducteurs, etc...), Le manager de gadgets, et tout les gadgets. Sans oublier les interfaces graphiques, qui avec python/gtk sont hard à gérer en mode threadé (en java et en delphi, c'est un autre monde
). Tout ce bordel peut être vérolé par la défaillance d'un gadget mal foutu puisque qu'en python le moindre incident génère une exception, et si cette exception n'est pas gérée et bien ça fout tout en l'air. C'est pas évident d'arriver à gérer tout les problèmes qu'un gadget écrit par tiers peut engendrer. J'ai d'ailleurs écrit un débuggeur dans le framework accessible dans le manager, pour y voir plus clair, mais certaines erreurs passent encore au travers.
Avec un système tournant dans un seul processus contenant des dizaines de threads (lorsqu'on utilise plein de gadget surtout), j'ai fini par croire qu'un jour le système aller créer lui même des gadgets lol
Pour en revenir à l'API, celle-ci n'a plus rien à voir avec l'ancienne. Premièrement, il n'y a plus que 2 threads, un pour le rapatriement des évènements et un autre pour le mode auto-connexion (pas obligatoire). Plus, évidement, le processus faisant appel à l'API.
J'écris cette API conjointement en java, en python et en javascript (celle-ci est plus simpliste que les deux autres).
La modularisation est totale, et chaque classe possède son fichier source. Les fonctionnalités sont réparties dans un arbre d'objets beaucoup plus cohérent qu'avant.
Par exemple pour l'état de connexion du dongle, on à sa disposition ces fonctionnalités:
tux.dongle.getConnected()
tux.dongle.waitConnected(timeout)
tux.dongle.waitDisconnected(timeout)
idx = tux.dongle.registerEventOnConnected(mon pointeur de fonction)
idx = tux.dongle.registerEventOnDisconnected(mon pointeur de fonction)
tux.dongle.unregisterEventOnConnected(mon idx)
tux.dongle.unregisterEventOnDisconnected(mon idx)
Toutes les fonctions de "wait" et de "register" font appel à un objet de centralisation et de gestion des évènements que l'on utilise de cette façon (l'exemple vient de la fonction qui teste l'intégrité de ce module):
print "Create an event handlers ..."
eventHandlers = TuxEventHandlers()
print "Insert a new event ..."
eventHandlers.insert("testEvent")
print "Insert a callback without condition ..."
idx1 = eventHandlers.register("testEvent", onTestEvent)
print "Insert a callback with condition ..."
idx2 = eventHandlers.register("testEvent", onTestEventC, (1, 7))
print "Start the loop of dummy events"
t = threading.Thread(target = fakeEventLoop)
t.start()
print "Store and clear the current context of callbacks. Callbacks will be inactive ..."
eventHandlers.storeContext()
eventHandlers.clearContext()
print "Wait a condition (1, 2).. which will be completed ..."
print eventHandlers.waitCondition("testEvent", (1, 2), 10.0), "For condition (1, 2)"
print "Wait a condition (1, 15)... which will not be completed (timeout too short) ..."
print eventHandlers.waitCondition("testEvent", (1, 15), 5.0), "For condition (1, 15)"
print "Restore the previous context of callbacks ..."
eventHandlers.restoreContext()
print "Wait a condition (1, 20)... which will be cleared ..."
print eventHandlers.waitCondition("testEvent", (1, 20), 10.0), "For condition (1, 20)"
eventHandlers.unregister("testEvent", idx1)
eventHandlers.unregister("testEvent", idx2)
print "Destroy the event handlers ..."
eventHandlers.destroy()
Enfin bref tout ça pour dire que la qualité de cette API n'aura rien à voir avec la première.
- répondre
Ulhume, le 27 May, 2008 - 15:23Juste pour bien préciser le vocabulaire, ce qui est important
Librairie : un ensemble de fonctions
Service : Une librairie dont les fonctions s'intègrent dans le flot de traitement du programme appelant.
API : Une librairie qui permet d'atteindre les fonctions d'un service avec un niveau plus ou moins élevé.
Framework : C'est l'inverse d'un service au sens ou c'est lui qui contrôle le traitement. On appelle cela aussi une "inversion de commande".
Tu es donc en train de coder un service packagé en démon/serveur qui cause avec le tux (via l'USB) et propose des fonctions (via REST).
Tu vas fournir une API packagé en librairie (Java, Python, etc) qui transforme les appels du langage natif en appels REST au service.
Moi je code un framework packagé en librairie qui anime un cycle de vie pour les gadgets qu'il contient. A ce titre les gadgets sont un service de mon framework
Je vais fournir une librairie (qui n'est pas une API) permettant de simplifier la réalisationde gadget en cachant, en autre, les aspects communication avec le framework.
La personne qui fait un gadget va donc utiliser ma librairie et ton API.
La personne qui fait le "Control Center" va utiliser mon framework et ton API pour fonctionner. Ce que je fait est donc un service pour l'IHM mais un framework pour les gadgets
- répondre
Rémi Jocaille, le 27 May, 2008 - 15:49Merci pour ces précisions
Il est vrai qu'en ce qui concerne la nomenclature des architectures, je suis une vrai quiche.
L'API dont je dis plus haut que je suis entrain de développer, c'est celle dont tu parles et que apparement, j'ai bien nommée.
En tout cas, l'architecture globale commence à avoir de la gueule, et je me réjouis que l'on puisse d'ici quelques mois, pouvoir proposer un tuxdroid qui au niveau software, firmware, hardware et look, sera de bien meilleur qualité que la version 1.
- répondre
Ulhume, le 30 May, 2008 - 10:23J'ai pas dis que tu avais mal utilisé le vocabulaire, c'est plus pour moi, histoire de se fixer les idées
Sinon, moi aussi j'ai pas mal avancé sur l'infrastructure des gagdets avec quelques évolutions qu'il faudrait que j'ajoute à la spec. L'idée est de passer par un système de messagerie plutôt que par des classiques appels/listeners. L'avantage est que tel que c'est parti, un gadget va pouvoir faire appel à un autre gadget sans avoir à passer par le control center...
Poster un nouveau commentaire