Table of contents
1      Application Template Presentation
2      Template Configuration
2.1         Maven Configuration File (pom.xml)
2.2         Open the Box Properties File (src/main/resources/OSGI-INF/otb.properties)
2.3         Declarative Services Configuration File (src/main/resources/OSGI-INF/component-devices.xml)
3      Java Code
4      GUI

1 Application Template Presentation

The file template.zip contains the complete template of an Open the Box application, allowing readers to build their own application starting from this one (the project is pre-installed in the Eclipse workspace of the Open the Box VM).

We will show in a first stage some configuration modifications that must be done (names & titles for instance), then we will describe the existing code.

The Developer’s Guide page provides a complete and referential presentation of the Open the Box application concept.

2 Template Configuration

2.1 Maven Configuration File (pom.xml)

We will not look over the entire file, but simply note that it is necessary to modify the following fields:

<artifactId> gives the identifier of the application (and of the jar/bundle that will be built).
<name> gives the application name.
The section maven-bundle-plugin contains instructions that are used to build an OSGi bundle, and in particular the adequate manifest:
- <plugin/configuration/instructions/Bundle-Author> sets the field Bundle-Author that will be written in the bundle manifest. Make sure not to modify the field Bundle-Vendor (value hackathon), it is used for connecting to the service providers’ administration site.
- <plugin/configuration/instructions/Application-Icon> if you want to propose an image (png 72×72 pixels) to be used as your application logo (otherwise it will be presented with a default icon).

It is of course possible to modify this file, for example to add dependencies to external libraries or to enrich the configuration of the maven-bundle-plugin (knowing that the default is self-sufficient).

2.2 Open the Box Properties File (src/main/resources/OSGI-INF/otb.properties)

This file contains the properties related to the application, in the Open the Box sense, and is therefore entirely left to the developer. Let’s simply mention the most important fields:

otb.label: the name of the application as it will be displayed in the AppStore and on the dashboard.
otb.config.url=/TemplateApp/index.html: the path to the application’s configuration web page (see section GUI).

2.3 Declarative Services Configuration File (src/main/resources/OSGI-INF/component-devices.xml)

This file contains the OSGi services dependencies required by the application. This information is also used when computing the required devices eligibility.

The developer starts by specifying the component’s implementation class, here com.orange.openthebox.hab.hackathon.template.FakeApp (which can of course be changed but must still correspond to a real bundle class).

The link to file otb.properties must be left unmodified.

Example of dependency to an OSGi framework service, the http service:

<reference name="httpService" cardinality="1..1"
   interface="org.osgi.service.http.HttpService"
   bind="setHttpService" unbind="unsetHttpService" />

Fields bind and unbind are used by the framework to provide the class with the requested service, they must therefore exactly correspond to associated methods in the component’s implementation class, here public void setHttpService(final HttpService httpService)

Example of dependency to a Zigbee device:

<reference name="zigbeeDevice" cardinality="0..n" policy="dynamic"
   interface="org.osgi.service.zigbee.ZigBeeEndpoint"
   bind="setZigbeeDevice" unbind="unsetZigbeeDevice" />
   <!--target="(DEVICE_FRIENDLY_NAME=<a zigbee device>)"    -->

Currently, this dependency is not filtered, which means that any service that implements the interface « Zigbee end point » of the Zigbee base driver (org.osgi.service.zigbee.ZigBeeEndpoint) will be bound to the application. If you wish to limit to specific Zigbee devices, which “friendly name” you know, you can uncomment the line “target" and state (possibly using the wildcard *) the device(s) that you want to capture (and therefore exclude Zigbee devices that do not correspond). For instance, to select alarms with name “IAS Warning Device…”:

<reference name="zigbeeDevice" cardinality="0..n" policy="dynamic"
   interface="org.osgi.service.zigbee.ZigBeeEndpoint"
   bind="setZigbeeDevice" unbind="unsetZigbeeDevice"
   target="(DEVICE_FRIENDLY_NAME=IAS Warning Device*)" />

Reminder:

for further information on devices, see the Device Management page.
for the application’s life cycle (debug / deployment / test), see on the Developer’s Guide.

3 Java Code

The proposed application is a simple servlet that aims at showing how to display the list of all devices present on the platform.

It is composed of the following classes:

FakeApp is the component’s entry point (field implementation of file component-devices.xml) :
- In accordance with the Declarative Services specification, it implements the activate/deactivate/modified methods which contains the framework’s ComponentContext.
- It implements the bind/unbind methods to required OSGi services. The devices that are hence detected are stored in lists, one list per technology.
- When the OSGi http service is bound to the application, the instance then
  - registers as a servlet the class ApiServlet;
  - registers as static resources (on alias "/TemplateApp") the folder that corresponds to the application’s GUI.
ApiServlet is the class that implements the Java servlet (javax.servlet.http.HttpServlet) of the application. It is registered to the OSGi http service with alias "/TemplateApp/myapi" (value that can be modified, but must be kept consistent with property otb.config.url in file otb.properties). It only responds to the request “GetDevices", without parameter, returning a JSon array with detected devices, along with their specificities, according to implemented technologies.

4 GUI

The example application GUI is as simple as it can be, and only aims at illustrating how to create a web page bound to the application.

A simple index.html page is supplied, located in folder WEB-INF (the name that is used in registering static resources to the OSGi http service). It just proposes a link to the GetDevices request of the application’s servlet: <a href="./myapi/GetDevices">Get current devices</a>.