Guide du développeur

Atelier Open the Box

Table des matières

1      Anatomie d’une application Open the Box
1.1         Présentation
1.2         Prérequis
1.3         Métadonnées de description de l’application
1.4         Éligibilité des applications dans le magasin d’application
1.5         Interface Web de configuration / utilisation
1.6         Utilisation des équipements
2      Cycle de vie d’une application Open the Box
2.1         Développement
2.2         Production
2.3         Utilisation du dashboard
3      Exemple d’application : Heating Control System
3.1         Structure de l’application
3.2         Accès aux équipements
3.3         Code de l’application
3.4         IHM de l’application
4      Exemple de Base Driver : le Heating Base Driver
5      Références & Tutoriels
5.1         Conditional Permission Admin
5.2         Device Access Specification
5.3         Declarative Services
5.4         Maven
5.5         Autres exemples

1         Anatomie d’une application Open the Box

1.1       Présentation

Les applications Open the Box sont des programmes destinés à fonctionner sur une plate-forme Java OSGi sur laquelle ont été ajoutés des services de gestion propres au modèle Open the Box et rassemblés sous le nom HABAM ; ces services gèrent l’installation (locale ou à distance) des applications, les permissions d’accès aux équipements, le suivi des ressources et les interfaces vers une application de présentation (tableau de bord, ou dashboard). Une application Open the Box peut être composée d’un ou plusieurs bundles OSGi ainsi que d’un ensemble de métadonnées nécessaires à sa bonne intégration dans le magasin d’application et la plate-forme de gestion.

Le présent document suppose que le lecteur possède une connaissance minimale de l’écosystème et de la technologie OSGi. Cependant, afin de faciliter la montée en compétence, des références à des tutoriels sur les différentes technologies utilisées sont données en annexe (voir section 5).

Pour une présentation basique des concepts Open the Box, voir ici.

1.2       Prérequis

À l’heure actuelle, le framework OSGi utilisé est Knopflerfish en version 4.0.1 (la dernière release de production de Knopflerfish pour OSGi R4) avec une machine virtuelle Java en version 7 (implémentation Oracle), toutefois le code des services HABAM est développé de manière à rester compatible avec Java ME CDC 1.1. L’ensemble tourne notamment sur la JVM JBed de Myriad implémentant le profil Java ME CDC Foundation Profile sur une Livebox Pro V3.

La plate-forme OSGi hébergeant l’application doit à minima disposer des services suivants :

  • le service OSGi Log ;
  • le service OSGi Http pour l’interface de configuration et utilisation de l’application ;
  • un parseur XML : l’implémentation actuelle utilise les interfaces xmlpull et requiert donc qu’une implémentation de ces interfaces soit disponible (par exemple le bundle kxml, déjà présent dans Knopflerfish par défaut car utilisé par Declarative Services). Ce parseur est utilisé pour l’analyse des fichiers de description des dépendances en termes d’équipements ;
  • le service OSGi Conditional Permission Admin (voir § 5.1) ;
  • la déclaration de services suivant la spécification Declarative Services (voir § 5.3) : c’est le format que doivent utiliser les applications pour gérer la recherche et la dépendance vers les différents services OSGi dont elles ont besoin.

1.3       Métadonnées de description de l’application

Un certain nombre de métadonnées sont nécessaires pour la bonne intégration d’une application dans le magasin d’application (Application Store, AS) et dans le dashboard d’Open the Box :

  1.  le logo de l’application (taille 72×72 pixels) : ce doit être un fichier dans le jar du bundle, dont le chemin est donné dans le Manifest, champ Application-Icon. Si le logo n’est pas fourni, un logo par défaut (point d’interrogation) sera utilisé. Exemple : Application-Icon: OSGI-INF/logo.png (correspond à un fichier ~/workspace/<project name>/src/main/resources/OSGI-INF/logo.png).
  2. le nom du fournisseur, indiqué dans le Manifest, champ Bundle-Vendor. Pour pouvoir utiliser la page d’administration des fournisseurs de service, la valeur de ce champ doit être un nom authentifié par la PFG, par exemple : Bundle-Vendor: hackathon
  3. des informations décrivant l’application : label, descriptions, prix, etc.

Note : En cas de construction du jar par Maven, on peut définir les champs Application-Icon et Bundle-Vendor dans les instructions du maven-bundle-plugin :

  • <Application-Icon>OSGI-INF/logo.png</Application-Icon>
  • <Bundle-Vendor>hackathon</Bundle-Vendor>

Les informations sur l’application sont données par le fichier OSGI-INF/otb.properties qui doit se trouver dans un bundle de l’application (si l’application possède plusieurs bundles, un seul de ces bundles doit contenir ce fichier). Le fichier otb.properties doit être encodé en UTF-8 et respecter la syntaxe Java classique des fichiers properties (cf. java.util.Properties).

Le squelette de fichier otb.properties donne ceci :

# Open the Box properties

# otb.label : nom de l'application sur l'AS et sur le Dashboard
# Optionnel mais fortement conseillé (par défaut, champ Bundle-Name du manifest)

# otb.config.url : URL de configuration de l'application.
# Ce doit être exactement l'alias du servlet enregistré auprès du service http OSGi.

# otb.category : liste d'items à choisir parmi : 
#    bureautique, domestique, education, jeux, multimedia, social, utilitaires.
# Optionnel.

# otb.description : description simplifiée de l'application sur l'AS (phrase courte, sur une ligne).
# Optionnel mais fortement conseillé (par défaut, chaîne vide)

# otb.fullDescription : description longue de l'application sur l'AS (paragraphe).
# Optionnel mais fortement conseillé (par défaut, chaîne vide).

# otb.price : prix de vente de l'application. Uniquement pour affichage, l'achat est simulé !
# Optionnel. Par défaut : 0,00

Exemple :

# Open the Box properties
otb.category=domestique, utilitaires
otb.label=Heating System
otb.description=Control the heating system in your Smart Home!
otb.fullDescription=Control the heating system in your Smart Home! \
   <b><i>Heating System</i></b> is an application designed for your \
   Smart Home Box which controls the heating system in your whole house.
otb.config.url=/app/MyAppUrl
otb.price=5,00

1.4       Éligibilité des applications dans le magasin d’application

Quand l’utilisateur navigue sur l’AS depuis le dashboard, les applications qui lui apparaissent sont celles qui sont éligibles, i.e. potentiellement installables dans son environnement. Le calcul d’éligibilité est basé sur les références aux équipements dans le fichier de configuration Declarative Services (fichier qui doit avoir un nom de la forme *devices.xml et être dans le répertoire OSGI-INF).

Une application est éligible si toutes ses références le sont.

On prend en compte :

  • l’interface, qui doit correspondre soit à un service, soit à un équipement référencé et présent sur la HAB du client ;
  • la cardinalité : 0..1, 0..n, 1..1 ou 1..n. Dans les cas 0..1 et 0..n, la référence est considérée d’office éligible, sinon on vérifie la présence d’au moins un équipement présent correspondant à l’interface ; on ne fait pas de distinction entre 1..1 et 1..n, et les cardinalités de type 1..2 ou 2..n ne sont pas permises, on ne compte donc pas le nombre exact d’équipements mais seulement leur présence / absence.
  • le filtrage, qui peut prendre en compte une description fine de l’équipement visé, via son numéro de série ou son “friendly name”.

Exemple : target="(DEVICE_FRIENDLY_NAME=heater .*)"

Les mots-clefs acceptés sont : DEVICE_FRIENDLY_NAME, DEVICE_DESCRIPTION, DEVICE_SERIAL, SERVICE_PID. Plusieurs conditions peuvent être chaînées par && ou ||. Exemple :

<reference name="device" cardinality="1..n"
   interface="com.orange.dhi.otb.mocked.osgizigbeedevice.api.MockedOsgiZigBeeDeviceApi"
   target="(DEVICE_FRIENDLY_NAME=heater .*) || (DEVICE_SERIAL=xxx)" />

Les propriétés correspondent respectivement à :

  • DEVICE_FRIENDLY_NAME : propriété apportée par les Base Drivers, s’efforçant de trouver la description la plus “parlante” de l’équipement.
  • DEVICE_DESCRIPTION, DEVICE_SERIAL : propriétés définies dans la spécification OSGi Device.
  • SERVICE_PID : identifiant de service OSGi.

1.5       Interface Web de configuration / utilisation

Toutes les applications doivent obligatoirement publier une interface web (http) permettant a minima de configurer (et potentiellement utiliser) l’application. Un lien vers cette interface est affiché sur le dashboard dans la page de détail de l’application.

L’url de cette page est spécifiée dans les métadonnées de l’application (otb.properties file, voir section 1.3). L’interface étant ensuite servie par la HAB, cette url est une adresse relative et correspond en pratique à l’alias avec lequel a été enregistrée la servlet (auprès du service http) dans l’application.

Cette interface web peut être réalisée de n’importe quelle manière dans la mesure où elle présente une page affichable dans un navigateur à l’adresse spécifiée.  Une approche souple et efficace, recommandée mais non obligatoire, est d’implémenter une API web de type REST (JSON sur HTTP) et de servir une page HTML statique utilisant cette API. Cette approche est mise en œuvre dans l’application de démonstration et a les avantages suivants :

  • L’IHM (HTML + JavaScript pour faire appel à l’API) peut être développée en dehors du framework OSGi, ce qui se révèle très utile étant donné que ce dernier ne propose généralement que le service HTTP et ne supporte pas d’utilitaires de haut niveau pour le développement web.
  • L’API REST peut être utilisée par une autre application (application native Android / Ios par exemple, ou application pour Smart TV, Set top box, etc.) sans modification du code.

1.6       Utilisation des équipements

Les équipements connectés à la HAB sont représentés sous la forme de services OSGi publiés par le Base Driver correspondant à la technologie de l’équipement (ZigBee, EnOcean, etc.) en respectant les spécifications OSGi Device Access (voir § 5.2).

Une application Open the Box utilise les équipements en accédant à ces services et aux méthodes qu’ils possèdent. Elle peut aussi généralement souscrire à des événements par l’enregistrement d’objets appelés « Service Listener » (e.g., ZigBeeEventListener pour la technologie ZigBee) selon le White Board Pattern, ou d’objets « Event Handlers » selon le paradigme Publish-Subscribe (e.g., utilisé par l’EnOcean Base Driver). La gestion des droits d’accès d’Open the Box s’applique sur l’appel des méthodes aux services représentant les équipements. La gestion des droits d’accès aux Service Listeners et aux éventuels Event Handlers utilisant Event Admin n’est pas supportée.

L’accès aux services représentant les équipements est contrôlé via le mécanisme OSGi standard Conditional Permission. Cela signifie qu’une application ne peut utiliser, et ne voit, que les services représentant les équipements pour lesquels les permissions lui ont été explicitement accordées. Ces permissions sont accordées et retirées  via le service OTBAccessControlManagement, une API d’HABAM (accessible uniquement aux bundles du framework opérateur, et non aux applications utilisateur standards) ou via le dashboard de la HAB (qui lui-même fait appel aux APIs HABAM).

Une application décrit ses besoins en termes d’équipements via un fichier OSGI-INF/*devices.xml au format spécifié par Declarative Services.

Une dépendance vers un équipement est définie par plusieurs éléments (voir § 1.4) :

  • une interface : il s’agit de l’interface Java sous laquelle est enregistré (par le Base Driver) le service représentant l’équipement souhaité ;
  • une cardinalité (par défaut 1..1) ;
  • un filtre (optionnel) permettant de préciser quel(s) équipement(s) est (sont) visé(s), en spécifiant des conditions sur les propriétés du service représentant le(s) équipement(s).

Exemple de déclaration de dépendances :

<?xml version="1.0" encoding="UTF-8"?>
<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0"    
      name="HeatingApplication" immediate="true">
   <implementation class = "com.orange.openthebox.hab.heatingcontrolapplication.HeatingControlApplicationImpl" />
   <reference name="log" cardinality="1..1" interface="org.osgi.service.log.LogService"
      bind="setLog" unbind="unsetLog" />
   <reference name="httpService" cardinality="1..1" interface="org.osgi.service.http.HttpService"
      bind="setHttpService" unbind="unsetHttpService" />
   <reference name="heaterService" cardinality="0..n" policy="dynamic"
      interface="com.orange.openthebox.hab.heatingsystemdriver.Heater"
      bind="setHeaterDevice" unbind="unsetHeaterDevice"
      target="(DEVICE_FRIENDLY_NAME=Heater ?)" >
</scr:component>

Pour plus de détails sur les différents types de connectivités utilisées par les équipements, voir la section « Guide des connectivités Open the Box ».

2         Cycle de vie d’une application Open the Box

Ce chapitre précise comment tester et rendre disponible aux utilisateurs une application Open the Box.

Dans un premier temps on indiquera comment, pendant la phase de développement / debug, on peut déployer localement l’application sur la plate-forme et la tester, puis une fois l’’application stabilisée comment on peut la charger dans l’AS.

Figure 1 Servlet HABAM

2.1       Développement

2.1.1         Construction

Nous ne préciserons pas ici quel environnement de programmation le développeur d’applications Open the Box doit utiliser pour écrire son code (même si nous préconisons Eclipse + Maven), nous supposerons simplement qu’il aboutit à la construction d’un fichier .jar qui est un bundle au sens OSGi.

Rappelons simplement que nous fournissons un kit de développement complet autour de ces outils.

Une fois la compilation correcte dans Eclipse, il suffit donc, depuis un terminal :

  • d’’aller dans le répertoire du projet (e.g. cd ~/workspace/hackathon.template.app) ;
  • de synchroniser les environnements Eclipse et Maven : mvn eclipse:eclipse
  • de lancer le build : mvn clean install
  • le bundle est créé dans le répertoire ~/workspace/hackathon.template.app/target : hackathon.template.app-1.0.3-SNAPSHOT.jar (attention le nom du jar dépend en fait du pom.xml, par défaut des champs artifactId et version)

2.1.2         Déploiement

Open the Box offre, au-dessus du modèle OSGi de déploiement granulaire de bundles, un modèle d’applications. Ce modèle spécifie des fichiers d’informations nécessaires pour la construction de magasin d’application et l’administration des applications du client par la plate-forme de l’opérateur Smart Home. Cela inclut la déclaration de droits d’accès par application envers les équipements, qui permet d’évaluer l’éligibilité des applications pour le client par l’AS.

Le mode de déploiement classique d’OSGi (cycle de vie et commandes installupdateuninstall) est ici utilisé et masqué par le mode Open the Box de déploiement d’applications. Le déploiement Open the Box gère les permissions d’accès aux services techniques, notamment aux équipements.

Les applications peuvent donc être déployées selon deux méthodes.

-          En phase de développement : déployer localement l’application par utilisation d’une page web d’administration (HABAM) servie par la box. Cette méthode est plus efficace durant le cycle de développement et de test, et a l’avantage de ne pas rendre les applications publiques pendant cette phase.

-          En phase de production : installer l’application depuis l’AS, ce qui suppose de l’y avoir précédemment téléchargée et donc rendue publique. Cette méthode est donc réservée aux applications « en production », qui doivent avoir été testées auparavant.

La page web d’administration locale est une servlet qui vient avec les services HABAM, elle est donc lancée au démarrage de la plate-forme Knopflerfish. Elle est utilisable depuis tout ordinateur connecté sur le même réseau local que la Raspberry, donc a priori depuis l’’environnement de développement du programmeur. On y accède par une page d’administration :

http://<@IP-target:port>/habam/index.html, par exemple http://10.0.10.1n:8081/habam/index.html

L’’adresse IP est celle de la plate-forme cible Raspberry, le port étant défini dans le fichier de configuration props.xargs (-Forg.osgi.service.http.port=8081).

La page d’’accueil (voir Figure 1) se présente sous la forme d’’une suite de formulaires HTML correspondant aux actions de la servlet. Nous ne détaillerons pas ici toutes ces actions, très intuitives ; notons simplement que « Upload Application » permet de télécharger le bundle de l’’application Open the Box (~/workspace/hackathon.template.app/target/<bundle name>-<bundle version>.jar) : si l’’installation s’’est bien déroulée, la page renverra l’’identifiant de l’’application ainsi créée, ID qui servira par la suite pour d’’autres manipulations sur la servlet (start, stop, uninstall, update, etc.) « Update Application » permet de mettre à jour une application Open the Box en se basant sur la commande OSGi framework/update, c’’est-à-dire sans avoir à désinstaller / réinstaller l’application.

2.1.3         Pilotage

Une fois installée, l’’application peut être pilotée de deux façons différentes : soit depuis le dashboard (elle y apparait dès son déploiement effectué), soit via la servlet d’’administration HABAM. On peut ainsi la démarrer, l’’arrêter, la désinstaller ou lancer son interface web de configuration.

Une action disponible seulement sur le dashboard permet d’’associer finement les droits d’’accès aux différents équipements détectés sur la plate-forme (par défaut le déploiement donne à l’’application les droits sur tous les services indiqués en declarative services).

2.1.4         Applications multi-bundles

Il est possible de créer des applications Open the Box composées de plusieurs bundles OSGi, à condition qu’un seul d’entre eux possède un fichier otb.properties. L’application se compose d’un fichier zip comprenant à la racine les fichiers jars des différents bundles. Le déploiement local se fait par la même page d’administration (les méthodes upload /update acceptent les fichiers jar et zip).

2.2       Production

Rappelons que le déploiement local décrit au paragraphe précédent n’est pas synchronisé avec la PFG. L’’application ainsi installée n’’est vue ni de la PFG ni de l’’AS.

Une fois considérée suffisamment complète et stabilisée pour un déploiement public, on peut alors la publier dans l’’AS.

Cette procédure utilise une API fournie sur Internet par la PFG. L’’URL de la page d’’administration pour les fournisseurs de services est la suivante : http://ohomeint.orange-labs.fr:9000/OpenTheBox/sp/index.jsp

Il faut se connecter en hackathon/hackathon.

L’’onglet Application/Submit permet de télécharger le jar de l’’application. Elle sera alors disponible sur l’’AS, plus précisément visible depuis toutes les HABs sur lesquelles elle est éligible.

2.3       Utilisation du dashboard

Pour la configuration du dashboard Open the Box, voir ici.

2.3.1         Pilotage local des applications

Une fois l’’installation d’’une application effectuée soit localement (voir § 2.1.2) soit depuis l’’AS (voir § 2.3.2 ci-dessous), il est possible de la piloter localement depuis le dashboard, un bouton (sous la forme du logo de l’’application, tel que défini dans les métadonnées) permettant d’’afficher une page générique de l’’application. Par défaut, au cours de l’’installation, le framework donne à l’’application les permissions d’accès aux équipements qu’’elle référence explicitement.

Figure 2 Page d’accueil du dashboard

  • Appuyer sur le bouton « Manage permissions » (voir Figure 3). Le dashboard, via le Dashboard Server, interroge HABAM pour connaitre les équipements connectés, puis sélectionne ceux qui sont compatibles avec les services requis référencés par l’’application. Ces équipements sont présentés avec une case à cocher : l’’utilisateur les choisit puis appuie sur le bouton « Apply ».
    • Les équipements choisis sont associés à l’’application, i.e. les droits d’’accès sont positionnés.
    • Si les cases de équipements ont été décochées, les droits d’’accès correspondant sont enlevés à l’’application.
  • Appuyer sur le bouton « Configure ». Ceci lance le navigateur sur la page de configuration de l’’application, si celle-ci en possède une. Cette page est fonctionnellement tout-à-fait indépendante du framework HABAM et uniquement liée à l’’application.
  • Appuyer sur le bouton « Start » pour lancer l’’application, « Stop » pour l’’arrêter.
  • Pour désinstaller l’’application, appuyer sur le logo poubelle en bas du dashboard. Un dialogue de confirmation s’’ouvre pour éviter les erreurs de manipulation. Il faut préciser que quand une application est désinstallée d’’une HAB (que ce soit localement ou depuis l’’AS), il est possible de la ré-installer depuis l’’AS.

Figure 3 Gestion des permissions d’une application

2.3.2         Pilotage des applications depuis l’’AS

Depuis la tablette, afficher la page d’’accueil du magasin d’’application (url WAN + authentification).

  • L’’AS affiche les applications qu’il peut installer sur la HAB (applications éligibles selon les équipements présents).

    Figure 4 Application Store

  • Cliquer sur l’application sélectionnée.
  • Sur l’’écran de sa tablette, on voit maintenant une page liée à l’’application (comportant une description du service et la liste des équipements requis) avec un bouton « Select » de simulation d’’achat. En cliquant dessus, un nouveau bouton « Install » apparait. Cliquer sur ce bouton.
    • L’’application s’’installe sur la HAB.

    Figure 5 Installation d’une application

  • L’application est installée et lancée automatiquement, un bouton « Stop » apparait en vert. Par défaut, HABAM donne à l’’application les permissions d’’accès à tous les services explicitement référencés dans le fichier de configuration Declarative Services (voir Utilisation des équipements). Pour modifier cette répartition (enlever les droits d’accès à certains équipements, ou les ajouter si de nouveaux équipements sont installés après le démarrage de l’application), il faut utiliser le dashboard (cf § 2.3.1).
  • Appuyer sur le bouton stop.
    • L’’application s’’arrête.
    • Le bouton Stop est remplacé par un bouton « Start » en rouge.
    • Un bouton « Uninstall » permet de désinstaller l’’application de la HAB.
  • Appuyer sur le bouton start.
    • L’’application démarre si elle est correctement configurée.
    • Le bouton Start est remplacé par un bouton « Stop » en vert.

3         Exemple d’’application : Heating Control System

L’’application Heating Control System ( hackathon.template.app.zip) est une application fictive de pilotage de chauffage, visant à donner les principes de base du développement d’’une application dans le cadre d’’Open the Box. Les points principaux sont les suivants :

  • utilisation de Declarative Services pour obtenir les références des services représentant les appareils utilisés par l’’application (des radiateurs et des thermomètres) ;
  • publication d’’une API REST permettant de piloter l’’application ;
  • présentation d’’une API Web implémentée via du code HTML statique, qui utilise l’’API REST.

L’’application est fonctionnellement extrêmement simple, elle ne fait qu’’afficher la liste des équipements auxquels elle a accès. Une évolution intéressante, et laissée comme exercice au lecteur, serait d’’implémenter un asservissement entre la température remontée par le (ou les !) thermomètre(s) et le(s) radiateur(s) (qui possèdent une méthode on/off).

Les équipements référencés, radiateurs et thermomètres, sont virtuels ! Leur base driver est détaillé à la section suivante.

Nous avons choisi de présenter ici une application volontairement très simple. Pour un exemple d’’application plus complexe, gérant notamment des équipements ZigBee, voir ce tutoriel.

3.1       Structure de l’’application

L’’application est implémentée avec uniquement deux classes : un composant Declarative Services et une Servlet.

 

3.2       Accès aux équipements

L’’accès aux équipements utilise Declarative Services. La déclaration des dépendances est faite dans le fichier src/main/resources/OSGI-INF/component-devices.xml :

   <?xml version="1.0" encoding="UTF-8"?>
   <scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.2.0" name="HeatingController" immediate="false">
      <implementation class= "com.orange.openthebox.hab.heatingcontrolapplication.HeatingControlController" />
      <reference name="log" cardinality="1..1" interface="org.osgi.service.log.LogService"
         bind="setLog" unbind="unsetLog" />
      <reference name="httpService" cardinality="1..1" interface="org.osgi.service.http.HttpService"
         bind="setHttpService" unbind="unsetHttpService " />
      <reference name="heaterService" cardinality="0..n" policy="dynamic"
         interface="com.orange.openthebox.hab.heatingsystemdriver.Heater"
         target="(DEVICE_FRIENDLY_NAME=Heater *)"
         bind="setHeaterDevice" unbind="unsetHeaterDevice" />
      <reference name="thermometerService" cardinality="0..n" policy="dynamic" 
         interface="com.orange.openthebox.hab.heatingsystemdriver.Thermometer"
         bind="setThermometerDevice" unbind="unsetThermometerDevice" />
   </scr:component>

Grâce à Declarative services, les services des équipements utilisables par l’’application sont fournis (« liés », mot-clef bind) et enlevés (« déliés », mot-clef unbind) par l’’appel automatique de la méthode (un)setXXX correspondante (ci-dessus : (un)setThermometerDevice). En cas de changement des permissions, un redémarrage de l’’application est nécessaire, Conditional Permission ne permettant pas la prise en compte « à chaud » des permissions sur un bundle en cours d’exécution.

3.3       Code de l’’application

La classe HeatingControlController, définie en tant qu’’implementation du composant Declarative Services, possède des méthodes activate/deactivate/modified appelées par le framework et permettant d’’actualiser le ComponentContext OSGi.

La référence au service OSGi HttpService permet d’’enregistrer la servlet.

3.4       IHM de l’’application

La servlet APIServlet sert une API REST sur http (encodée en JSON). Cette API possède deux ressources qui permettent de voir la liste des radiateurs et des thermomètres auxquels l’’application peut accéder :

  • http://<ip_hab>:<port>/HeatingControl/api/heaters
  • http://<ip_hab>:<port>/HeatingControl/api/thermometer

L’’IHM est ensuite implémentée avec des fichiers statiques (dans le bundle, répertoire static), servis comme simples ressources par le service http OSGi. Des appels vers l’’API REST sont effectués, en JavaScript, de manière à avoir une IHM dynamique. Il serait très facile de développer une application Android ou iOS utilisant cette même API.

L’’IHM elle-même est accessible à l’’adresse :

http://<ip_hab>:<port>/HeatingControl/static/index.html

4         Exemple de Base Driver : le Heating Base Driver

L’’application Heating Control System utilise des équipements publiés par le base driver HeatingSystem Driver (sample.heatingsystem.driver.zip). Il s’’agit d’’un Base Driver virtuel qui publie des services correspondant à deux types d’’appareils : des radiateurs et des thermomètres.

Ces appareils sont totalement virtuels : aucune communication n’’est implémentée vers des appareils physiques, l’’objectif de ce driver est uniquement de montrer un exemple de publication d’’équipements via des services OSGi. Il démontre en particulier l’’enregistrement (et le dé-enregistrement) d’’un service OSGi avec toutes les propriétés nécessaires à sa bonne intégration dans la plate-forme Open the Box.

Un guide de bonne pratique pour de développement de base drivers dans le cadre d’’Open the Box est disponible dans un document séparé.

5         Références & Tutoriels

5.1       Conditional Permission Admin

Conditional Permission Admin est le mécanisme standard de gestion des permissions de la plate-forme OSGi, il remplace Permission Admin en ajoutant la possibilité de faire varier les permissions au cours de l’’exécution du framework : aucun redémarrage de la plate-forme n’’est requis pour prendre en compte un éventuel changement de permission. En revanche, étant donné le type de permissions paramétrées (droits d’’import de package Java, par exemple) un redémarrage des bundles impactés par les permissions modifiées peut être nécessaire (c’’est le cas pour les applications Open the Box).

Conditional Permission Admin permet de définir des permissions sous la forme de règles avec la syntaxe suivante :<access> <condition> <permission>

Par exemple :

ALLOW {
   [org.osgi.service.condpermadmin.BundleLocationCondition "file:/opt/kf/totest/*"]
      (org.osgi.framework.PackagePermission "*" "import")
}

Où :

  • Access : ALLOW
  • Condition : org.osgi.service.condpermadmin.BundleLocationCondition "file:/opt/kf/totest/*"
  • Permission : (org.osgi.framework.PackagePermission "*" "import")

Références :

Rappel :

  • Nous utilisons une version corrigée du framework Knopflerfish pour la gestion des permissions, voir les notes du Guide d’installation.

5.2       Device Access Specification

La spécification Device Access définit la façon dont des services OSGi peuvent être utilisés pour représenter des équipements au sein d’’un framework OSGi, ainsi que la manière dont sont localisés les base drivers permettant la publication de ces services.

Le meilleur exemple d’’utilisation de Device Access est la spécification du base driver UPnP.

Références :

5.3       Declarative Services

Declarative Service est un mécanisme de type « injection de dépendance » qui permet de ne pas avoir à gérer manuellement la recherche de service et le cycle de vie des dépendances. Les services utilisés par le code d’un bundle sont déclarés dans un fichier de métadonnées xml et les objets correspondants sont directement passés au composant à l’exécution, dès que les services déclarés dans le fichier xml sont disponibles.

Références :

5.4       Maven

Maven est un système de build Java très répandu dont les caractéristiques principales sont d’être déclaratif (on décrit ce que l’on veut obtenir, et pas comment doit se dérouler le build) et de gérer les dépendances.

Pour la création des bundles OSGi, il est conseillé d’utiliser Maven avec le Maven bundle plugin qui encapsule l’utilitaire bnd (http://www.aqute.biz/Bnd/Bnd) pour permettre son intégration dans un build Maven.

Maven bundle plugin : http://felix.apache.org/site/apache-felix-maven-bundle-plugin-bnd.html

En complément des exemples donnés sur le site de Felix, le base driver et l’application d’exemple Heating Control donnés dans le présent document constituent de bonnes lectures.

5.5       Autres exemples

Comme autres exemples d’applications Open the Box, on pourra se reporter à ce tutoriel, qui contient une application gérant des équipements ZigBee, et pour se lancer on peut utiliser ce template d’application.