Source: http://openthebox.org/guide-du-developpeur_en/
Timestamp: 2019-04-26 04:05:47+00:00

Document:
Open the Box applications are programs intended for running on a Java OSGi platform on which management services pertaining to the Open the Box model were added, gathered with name HABAM ; these services manage the installation of applications (locally or remotely), the access permissions to devices, the resource management and interfaces towards a display application (dashboard). An Open the Box application can be composed of one or more OSGi bundles, along with a set of metadata that are necessary for its integration into the AppStore and the management platform (PFG).
This document requires from the reader a minimal knowledge of the OSGi ecosystem and technology. However, in order to improve OSGi skills, references to tutorials about the different technologies are given in the annex (see section 5).
For a basic presentation of Open the Box concepts, see here.
Currently, we use the Knopflerfish OSGi framework, release 4.0.1 (the last production release of Knopflerfish for OSGi R4), with a Java virtual machine in version 7 (Oracle implementation), however the code of HABAM services is developed so as to remain compatible with Java ME CDC 1.1. It all runs notably on the Myriad JBed JVM with Java ME CDC Foundation Profile on a Livebox Pro V3.
The OSGi Http service for the application’s configuration and the use of web interfaces.
An XML parser: the current implementation uses the xmlpull interfaces and therefore requires that an implementation of these interfaces be available (for example the kxml bundle, already present by default in Knopflerfish as it is used by Declarative Services). The parser is used for analyzing the dependencies in description files in terms of devices.
The OSGi service Conditional Permission Admin (see § 5.1).
Declarative Services specification (see § 5.3): this is the format that applications must use to deal with searching and binding to the different OSGi services they need.
The application logo (size 72×72 pixels): it must be a file inside the bundle jar, whose path is given in the Manifest, field “Application-Icon”. If the logo is not supplied, a default one will be used. Example : Application-Icon: OSGI-INF/logo.png (corresponds to a file ~/workspace/<project name>/src/main/resources/OSGI-INF/logo.png).
Information describing the application: label, descriptions, price, etc.
Information on the application are given in the file OSGI-INF/otb.properties that must be in the application bundle (if the application is composed of several bundles, one and only one of these bundles should contain this file). The file otb.properties must be encoded in UTF-8 and respect the classical Java syntax for properties files (cf. java.util.Properties).
# otb.config.url: URL of the application web page.
# Must be exactly the alias of the servlet as registered to the OSGi http service.
#    bureautique, domestique, education, jeux, multimedia, social, utilitaires.
# otb.description: simplified description of the application on the AS (short, one-line sentence).
# otb.fullDescription: full description of the application on the AS (paragraph).
# otb.price: application's selling price. Only for display, purchase is simulated!
otb.description=Control the heating system in your Smart Home!
Smart Home Box which controls the heating system in your whole house.
When a user browses the AS from the dashboard, visible applications are the eligible ones, i.e. applications that are potentially installable in her/his environment. The eligibility computing is based on the references to devices in the Declarative Services configuration file (file with a name *devices.xml that must be in folder OSGI-INF).
An application is eligible if all its references are eligible.
The interface, that must correspond either to a service, or to a device that is referenced and present on the customer’s HAB.
Cardinality: 0..1, 0..n, 1..1 or 1..n. In cases 0..1 and 0..n, the reference is automatically considered as eligible, otherwise we check the presence of at least one current device that corresponds to the interface ; no distinction is made between 1..1 and 1..n, and 1..2 or 2..n cardinalities are not allowed, we do not count the exact number of devices but only their presence / absence.
Filtering, that allows a finer description of the targeted device, via its serial number or its “friendly name”.
DEVICE_FRIENDLY_NAME: property brought by the Base Drivers, trying to give the most vivid description of the device.
DEVICE_DESCRIPTION, DEVICE_SERIAL: properties defined in the OSGi Device specification.
All applications must publish a web interface (http) that supplies at least the configuration and/or use of the application. A link to this interface is displayed on the dashboard, from the application’s detailed page.
The url of this page is specified in the application’s metadata (otb.properties file, see section 1.3). As this interface is served by the HAB, this url is a relative address that corresponds, in practice, to the registration alias from the application’s servlet to the HTTP service.
The REST API may be used by any other application (native Android / Ios application for example, or an application for Smart TV, Set top box, etc.) without modifying the code.
The devices connected to the HAB are represented as OSGi services published by the Base Driver that corresponds to the device technology (ZigBee, EnOcean, etc.), complying with OSGi Device Access specification (see § 5.2).
An Open the Box application uses devices by accessing to their services and their methods. It can also subscribe to events by registering so-called “Service Listener” objects (e.g. ZigBeeEventListener for ZigBee technology) according to the White Board Pattern, or “Event Handlers” objects (Publish-Subscribe paradigm, e.g. used by the EnOcean Base Driver). Open the Box access rights management applies on method calls to services that represent devices. Access rights management to Service Listeners and potential Event Handlers using Event Admin is not supported.
Access to services that represent devices is controlled via the OSGi Conditional Permission standard mechanism. This means that an application may use, and see, only the services that represent the devices for which it has been explicitly granted the permissions. These permissions are granted and removed via the OTBAccessControlManagement service, an HABAM API (only accessible to the framework operator bundles, and not to standard user applications) or via the HAB dashboard (that, for itself, can request HABAM APIs).
An application describes its needs for devices through a file OSGI-INF/*devices.xml, with format specified by Declarative Services.
An interface : this is the Java interface, as registered by the service that represents the requested device (registration is performed by the Base Driver).
A cardinality (by default 1..1).
A filter (optional) for specifying the targeted device(s), and the conditions on the properties of the service that represents the device.
For further details on the different types of connectivities used by devices, see chapter Open the Box Device Management.
This section describes how to test and make available to users an Open the Box application.
In a first stage, during the development / debug phase, we will show how to deploy the application locally – on the platform – and test it, and then once the application is stabilized, how to upload it on the AS.
We will not precise here which programming environment the Open the Box application developer must use to write her/his code (even if we advocate Eclipse + Maven), we will just suppose that it ends up building a jar file that is a bundle in the OSGi sense.
Reminder: we supply here a complete development kit around these tools.
Open the Box offers, on top of the OSGi granular bundle deploy model, an applications deploy model. This model specifies informations files necessary for building the AS and for managing customer applications on the Smart Home operator’s platform. This includes the declaration of access rights for the application on devices, thereby computing eligibility of applications for the client par the AS.
OSGi’s classical deployment mode (life cycle and commands install, update, uninstall) is replaced here by the Open the Box applications deployment mode. This deployment manages access permissions to technical services, in particular to devices.
Applications can then be deployed with two methods.
- In development phase: locally deploy the application through an administration web page available on the box. This method is more efficicent during the development and test cycle, and has the advantage of not making public the applications throughout this phase.
- In production phase: install the application from the AS, which supposes that it was previously uploaded there, hence made public. This method is therefore reserved to production applications, that must have been tested before.
The IP address is Raspberry target’s one, port being defined in configuration file props.xargs (-Forg.osgi.service.http.port=8081).
The home page (see Figure 1) presents a list of HTML forms that correspond to servlet actions. We will not detail here all these actions, very intuitive, but simply note that “Upload Application” is for uploading the Open the Box application’s bundle (~/workspace/hackathon.template.app/target/<bundle name>-<bundle version>.jar) : if the installation went through, the page will return the created application’s ID, which will be subsequently used for other servlet operations (start, stop, uninstall, update, etc.) “Update Application” is for updating an Open the Box application, based on OSGi command “framework/update”, that is without desinstall / reinstall of the application.
Once installed, the application can be handled in two different ways: either from the dashboard (it appears on it after deployment is over), or via thes HABAM administration servlet . It is possible to start, stop or deinstall it, or to browse its configuration page.
An action that is available only on the dashboard allows the user to finely associate the application’s access rights to the different devices detected on the platform (by default, deployment grants the application with access rights on all services that were stated on the declarative services configuration).
It is possible to create Open the Box applications that are composed of several OSGi bundles, on condition that only one among them contains a file otb.properties. The application is made of a zip file that contains at the root the jar files of the different bundles. Local deployment is made from the same administration page (methods upload /update accept jar and zip files).
Remember that local deployment as described above is not synchronized with the PFG. The applications installed in this way are neither seen from the PFG nor from the AS.
Once considered complete and stabilized enough for a public deployment, it becomes possible to publish it on the AS.
The tab “Application/Submit” gives a way to upload the application jar (or zip). It will then be available on the AS, more precisely visible from all HABs on which it is eligible.
For configuring the Open the Box dashboard, see here.
Once an application is installed, either locally (see § 2.1.2) or from the AS (see § 2.3.2 under), it is possible to drive it locally from the dashboard: a button (with the application’s logo, as defined in the metadata, or a default icon) opens a generic page for the application. By default, during installation, the framework grants the application with access permissions to the devices it explicitely references.
Click on button “Manage permissions” (see Figure 3). The dashboard, via le Dashboard Server, queries HABAM for the list of connected devices, then selects those that are compatible with required services that are referenced by the application. These devices are displayed with a tick-box: the user selects them, and clicks on “Apply”.
Chosen devices are associated with the application, i.e. access rights are set.
If devices have been unticked, corresponding access rights are removed from the application.
Click on button “Configure”. This will bring the browser on the application’s configuration page. This page is functionally absolutely independant from the HABAM framework and only related to the application.
Click on “Start” button to launch the application, “Stop” to stop it.
To deinstall the application, click on the trash bin icon lower left of the dashboard. Un confirmation dialog opens up to avoid errors. We must precise that when an application is deinstalled from a HAB (either locally or from the AS), it is possible to re-install it from the AS.
From the tablet, display the AppStore home page (url WAN + authentification).
The AS displays the applications it can install on the HAB (applications “eligible” according to present devices).
Click on the selected application.
On the tablet screen, we now have a page that is related to the application (containing a description and the list of required services) with a “Select” button for simulating purchase. Click on it, a new “Install” button appears. Click on this button.
The application is installed on the HAB.
The application is installed and automatically started, a “Stop” green button appears. By default, HABAM grants the application permissions access to all explicitely referenced services in the Declarative Services configuration file (see Device Management). To modify this cette distribution (remove access rights to some devices, or add them if new devices were installed after the application started), dashboard must be used (cf § 2.3.1).
The Stop button is replaced by a “Start” red button.
An “Uninstall” button allows the user to deinstall the application from the HAB.
The application starts if correctly configured.
The Start button is replaced by a green “Stop”.
presentation of a Web API based on static html code using the previous REST API.
Functionnally, the application is rather simple, it does nothing except displayiong the list of equipments that it access to. An interesting extension (let to the reader as a trainning) consists in implementing a fedback control loop from the temperature reported by the thermometer(s) to the heater(s) control through its(their) on/off command.
The displayed equiments, Heater(s) and thermometer(s) are virtual ones ! And their base drivers are installed in the next section.
We deliberatly choose to show a rather simple application. For a more complex example including ZigBee devices access see thistutoriol.
The application is implemented through two classes only : one component Declarative Services et one Servlet.
Grâce à Declarative services, The services offered by the equipments available for the application are bind ( keyword bind) and unbind ( keyword unbind) by the corresponding method (un)setXXX invokation (see above : (un)setThermometerDevice). If Permissions are modified, the application should be stoped then restarted to update its permissions. Conditional Permission does not take into account dynamically permission modification for a running bundle. .
The HeatingControlController Class, defined as Declarative Services component implementation, exports activate/deactivate/modified methods that are invoked by the framework to update the OSGi ComponentContext .
La référence au service OSGi HttpService permet d’enregistrer la servlet.
The Heating Control System application uses équipements that have being published by the HeatingSystem Driver base driver(sample.heatingsystem.driver.zip). This is in fact a virtualBase Driver that publishes services corresponding to two Equipment types : heaters and thermometers.
All these equipments are purely virtual : no communication towards some concrete equipments is carryed out, this virtual driver is nothing but a help to show how equipments are published by OSGi services. It particularly demonstrates how to register and how to unregister an OSGi service with all necessary properties for a proper integration in the Open the Box platform.
A “Best Practice” guide for developing base drivers in the ‘Open the Box framework can be found in a separate document.
Conditional Permission Admin is the OSGi standard for permission management, It extends Permission Admin with the dynamic permission assignment while the OSGi Framework is running : there no need to stop and restart the OSGi Framework to take into account a new permission assignment for some application. At the contrary, because of the parametred permission type (e.g. package Java import rights) the bundle athat are impacted by these permission modification should be sttep then restarted (This is expecially the case for Open the Box applications ).
We use a corrected (and thus improved) version of the Knopflerfish framework for permission management, see notes from Installation Guide.
The Device Access specification defines how to use OSGi services in order to represent home equipments within an OSGi framework , and where the base drivers are localized to allow the publication of these services.
The best exemple of Device Access use is the UPnP base driver specification.
Declarative Service uses « dependancies injection » mechanism that prevent from having to manage the service search as well as dependancies life-cycle. The services used by some bundle code are declared un meta-data file xml coded and the corresponding instances are straightforwardly given to the component at run time, as soon as these declared services become available.
Maven is a very popular Java build system based on a declarative style (“What we want to get” is given as inputs but not “how to get it”). Maven also supports dependencies management.
For OSGi bundle development we recommand the use of Maven together with the Maven bundle plugin which embeds the bnd (http://www.aqute.biz/Bnd/Bnd) tool for including this development in a Maven build >.
Other Open the Box application exemples are included in tutoriel : e.g. an application that manages ZigBee devices. Finally, for a quick kick off, an application template could be used.

References: § 5
 § 5
 § 5
 § 2
 § 2
 § 2