1 Introduction

1.1 Caution

The reference guide for implementing base drives is a part of “OSGi Device Access” specification, see [1].

This document is nothing but a guide for developers in order to facilitate their job as well as to give some “Open the Box specific” details . As time goes by, this document will be improved in order to take into account new requirements for development, integration or test steps.

1.2 Basics

Base drivers function consists in reifying the services that are supplied by the devices connected to the HAB (Home Automation Box) and exposing them as OSGI services within the business programing model.

In the Open the Box software stack there exist as many base drivers as there are managed connecting technologies (ZigBee, Zwave, EnOcean, UPnP, etc.)

The array hereafter summarizes the base drivers that were produced during the Open the Box project.

Technologies	Authors, Owners	License	Code Base, Web site or person in touch with
ZigBee	Orange	Orange
EnOcean	Orange	Orange	https://github.com/eclipse/smarthome/tree/master/protocols/enocean
X3D	Delta Dore	Delta Dore
GreenNet	STM	STM
USB	Bouygues Telecom	Bouygues Telecom

2 Plug‘n’Play

Base Driver architecture pattern is deeply involved in the equipment plug’n’play experience. As soon as the equipment has been appaired (by dedicated procedure involving low levels of the protocol stack), the base driver corresponding to the connecting technology used by the equipment exposes automatically the reified view of the services offered by the equipment. This exposure occurs within the business run time environment whatever these services are used by some business application code or not.

2.1 API and Programming Pattern

Each service exported by some device is represented by some dedicated OSGI Java object (proxy) implementing a shared interface (eg. ZigBeeEndPoint in the ZigBee case). These interfaces are published as services in the OSGI registry. Any method of a service (previously registered in the OSGI service registry) can be invoked by a business bundle provided that this bundle gets the (eventually) required permissions. The base driver translates these methods invocations to corresponding messages that are sent to the addressed devices through the technology network. Note that some technologies allow multi-services equipments.

Example:

public interface MyDeviceApi {
   // The Java interface of a device
}
public class MyDeviceImpl implements MyDeviceApi {
   // The implementation of the device
}
public class MyDeviceBaseDriver {
   // Code for registering a device
   MyDeviceApi myDevice = new MyDeviceImpl();
   Dictionary props = new Hashtable(); // Service properties, see below
   bundleContext.registerService(MyDeviceApi.class.getName(), myDevice, props);
}

2.2 Service Properties

When a new service given by some connected device is published, the corresponding base driver (the one corresponding to the device connecting technology) must attach to the service the following properties:

Ident	Status	Type	Comment & Reference
Connectivity independent properties
DEVICE_CATEGORY	MUST	String[].The first element of these array takes one of the following attribute : X3D,ZiigBee,USB,UPnP…	Connectivity technology [1], could be completed as needed.
DEVICE_DESCRIPTION	SHOULD	String. Device description according to OSGi Device Access [1]
DEVICE_SERIAL	SHOULD	String. Device serial number according to OSGi Device Access [1]	OSGi Device Access [1]
service.pid	MUST	String. unique and persistent identifier according to OSGi Device Access [1]	service Persistent ID[1]
DEVICE_FRIENDLY_NAME	MUST	String. The device name with one or more words with length less than 25 characters	If this property is not available, the 25 first characters of DEVICE_DESCRIPTION Will be used for displaying device Friendly name in the user GUI
Connectivity dependent properties (zigBee example hereafter)
NODE_TYPE			ZigBee exemple [2]
MANUFACTURER_CODE			ZigBee exemple [2]
HOST_PID			ZigBee exemple [2]

Example:

   Dictionary props = new Hashtable();
   props.put(org.osgi.service.device.Constants.DEVICE_CATEGORY, new String[] { "the technology name" });
   props.put(org.osgi.service.device.Constants.DEVICE_DESCRIPTION, "a description of the device");
   props.put(org.osgi.service.device.Constants.DEVICE_SERIAL, "the device serial number");
   props.put(org.osgi.framework.Constants.SERVICE_PID, "the OSGi device service id");
   props.put("DEVICE_FRIENDLY_NAME", "a friendly name of the device");
   // there can be some techno specific properties
   props.put("DEVICE_MANUFACTURER", "my company");
   props.put("DEVICE_SYSTEM_TYPE", "Virtual");

2.3 Device Access and Command Invocation

An interface dedicated to each technology (ZigBee, X3D, GreenNet) represents the concepts of the corresponding technology. For example, interfaces ZigBeeNode, ZigBeeEndPoint, ZigBeeCluster and ZigBeeCommand reify respectively as Java object the concepts of node, endpoint, cluster, command of the ZigBee specification. This model could be simpler as for the X3D technology where only the X3D interface is given. According to the technology at hand, these interfaces allow to scan the device characteristics as well as their discoverable commands.
After discovering in the OSGI registry the object that represents a device, business code can send commands to the device through corresponding method invocations on the suitable interface: e.g. ZigBeeCommand.invoke(byte[], ZigBeeHandler) for ZigBee and X3DDevice.executeCommand(String cmd, String[] arguments, X3DHandler) for X3D.
Command sending (or method invocation) and response reception (if any) may work asynchronously. In that case command sending could be managed with some “handler” (or callback) as argument. This handler is a Java object built up by the business application that must be notified in an asynchronous way as soon as the response has been received.

See the Connectivity Guide for more details on referenced technologies.

2.4 Event Notification

ZigBee, EnOcean, X3D, GreenNet, and so on… protocols allow event notification. To be notified on some event occurrence, the application should register a listener service attached to this kind of event. This listener service implements an interface, e.g. « ZigBeeEventListener » in the zigbee case or EventHandler for X3D, which use the OSGI Event Admin standard service . The application registers to this service with dedicated properties that qualify the subscribed to event (e.g. the device identifier). The base driver, through the service registry, gets the subscribed events and adds the corresponding protocols of the used technology. As soon as an event occurs and is notified to the connecting technology network, the base driver notifies the listeners (if exist) that have subscribed to these events.

Example for EnOcean:

import org.osgi.service.event.EventHandler;
import org.osgi.service.event.EventConstants;
public class MyApplication implements EventHandler {
   // ...
   Hashtable ht = new Hashtable();
   ht.put(EventConstants.EVENT_TOPIC, new String[] { EnOceanEvent.TOPIC_MSG_RECEIVED, });
   bundleContext.registerService(EventHandler.class.getName(), this, ht); // register for EnOcean events

   public void handleEvent(Event event) {
      if (! event.getTopic().equals(EnOceanEvent.TOPIC_MSG_RECEIVED)) {
         return;
      }
   // process EnOcean events, as returned by the EnOcean base driver
   }

3 Example: Heating Base Driver

We present the HeatingSystem base driver(sample.heatingsystem.driver.zip), which is in fact a virtual Base Driver that publishes services corresponding to two simulated device types : heaters and thermometers.

All these devices are purely virtual : no communication towards any concrete devices is carryed out, this virtual driver is nothing but a help to show how devices 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.

4 References

[1] OSGi Alliance, OSGi Service Compendium, Release 4 version 4.3, May 2012. Chapter 103: “Device Access Specification”.

[2] OSGi Alliance, RFC 192 ZigBee Device Service, ongoing specification. https://github.com/osgi/design/raw/master/rfcs/rfc0192/rfc-0192-ZigBeeDeviceService.pdf