Subscribe to News
OSAmI-ES Device Abstraction HowTo
Author : Jesus Bermejo
From TechnologicalWiki
Contents |
Introduction
In the OSAmI project, work is being done to develop a platform which, among other things, may offer an easy way of controlling, configuring, and accessing the data generated from all kind of devices related to Ambient Intelligence.
The way that the OSAmI Commons Consortium offers to attain this goal, involves the use of some previously existing standards, and the proposal of some new conventions on top of them. This set of standards and conventions are called “OSAmI Device Abstraction”.
This is a manual on HowTo integrate a device or set of devices into an OSAmI system.
[edit] Pre-Required knowledge
In order to properly follow the guidelines given in the present document, the reader may need to have a proper understanding of :
- OSGi Service Platform Core Specification 4.2 (at least Module, Life Cycle and Service layers).
- OSGi Device Access Specification v1.1 (OSGi Service Platform Service Compendium, Chapter 103)
- OSGi Wire Admin Service Specification v1.0 (OSGi Service Platform Service Compendium, 108)
- OSGi Event Admin Service Specification v1.2 (OSGi Service Platform Service Compendium, 113)
- OSAmI-ES Device Model v1.0
Also recommended :
- OSGi Configuration Admin Service Spec v1.3 (OSGi Service Platform Service Compendium, 104)
[edit] First Common Steps
[edit] Base Driver
The first step to be addressed in the integration of any device into the OSAmI platform is the development of the proper base driver for the specific technology or protocol used by the device communications, if one does not already exist.
According to the OSGi Device Access Specification, “base drivers provide the lowest-level representation of a physical device”, being “the distinguishing factor that they do not have to compete for access to the underlying technology”.
Base drivers are so accountable for discovering connected physical devices and then registering correponding Device Services, but the exact way this is done is out of the specification, and very dependent on the particular technologies and communication and control protocols being used. For technologies that do not support a discovery mechanism, the driver will require external help, and the recommended approach in this situation is the use of the OSGi Configuration Admin service to dynamically configure it.
The Device services registered by the base drivers will generally offer, as already stated above, a very generic and low level API that will reflect the connection technology more than the type of the device (e.g. a usb mouse will be registered as a generic usb device, not as a mouse).
Also, the OSGi Access specification says that these Device services must belong to a defined device category. The definition of this device category implies the definition of :
- a Java interface all the device services of this category must implement
- a set of service registration properties
- a range of match values
For further info, refer to the OSGi Device Access Specification.
[edit] Example
If we need to integrate a UPnP device into the platform, we first of all need a UPnP base driver that enables us to access all the devices of this technology in a generic way, probably offering a quite low level and not very developer-friendly API.
For this purpose we could for example use the Apache Felix UPnP driver (http://felix.apache.org/site/apache-felix-upnp.html). Indeed it is an implementation of the UPnP Device Service Specification, which is the specification for a base driver for UPnP networks. This specification defines the “UPnP” device category to which the Device services registered by this driver belong. The correponding Java interface for this device category is org.osgi.service.upnp.UPnPDevice. The service registration properties and match values are also specified.
So, if with this driver installed in the framework we connected a UPnP printer to the network, a service would be automatically registered in the framework under the UPnPDevice interface, representing the physical printer. Notice that the base driver itself will not install a Printer service that would allow a programmer to abstract herself from the possibly irrelevant fact that the printer is connected through UPnP.
This can be easily tested by running a framework with this driver installed, and then using also some of the UPnP device examples also provided by the Apache Felix project (http://felix.apache.org/site/upnp-examples.html). It may also be useful to use their UPnP viewer (http://felix.apache.org/site/upnp-testing-devices.html).
[edit] Refining Drivers and OSAmI Device model
As it is stated in the “Device Services” section in the OSGi Device Access specification, “several device services can represent the same physical device at different levels of abstraction”.
They provide the following example: a USB mouse can be considered as
- a generic USB device which delivers information over the USB bus, or
- as a mouse device which delivers x/y coordinates and button events;
So the fact that a particular device is a mouse is irrelevant to an application which provides management of USB devices, and that a mouse is attached to a USB bus or serial port is inconsequential to applications that respond to mouse-like input.
The definition of a base driver in the previous section will serve to offer access to devices by using the first approach. On the other hand, in order to easy the development of applications using the OSAmI platform as a base, one of the goals of the project is to provide uniform access to a set of device types (OSAmI Device Model), independently of the underlying technologies they work upon: this would be the second approach mentioned.
To achieve this, drivers need to be developed for each specific technology that:
- attach themselves to Device services of the device category specified for the particular underlying technology
- register new Device services belonging to another device category representing the same physical device but with a higher level API, implementing the corresponding interface defined in the OSAmI Device model.
[edit] Example
Following the UPnP example, let us assume now that we have connected an UPnP binary light bulb to the system, and that it is running the Felix UPnP driver. In this situation, a new device service representing the light, which implements the UPnPDevice interface will be registered in the framework.
Let us also suppose that there is also an already developed application for illumination control, that shows the users a graphical interface so that they can control all the “Light” devices, according to the “Light” device model specified in the OSAmI Device model.
So if we want our UPnP Light to be shown in this user interface so that a user is able to control it, we need to develop a “Refining Driver” that:
- registers a driver service with the framework that attaches itself to UPnPDevice services (or device services which device category is “UPnP”) representing light bulbs.
- registers a new service that implements the “Light” interface defined in the OSAmI Device model. Invocation of the appropriate methods of this service will change the state of the device it represents.
But how should we do this? Please read on.
[edit] Device and driver matching
Once our driver service is registered, the device manager will call the match method in our driver service for each idle device service in the framework, and it will return a value indicating if this is a suitable driver for the device. What our driver service should do is to check if the received device service belongs to the device category that it is able to handle: “UPnP”, and then check the rest of the properties registered with the device service, and return a value between the ones defined in the constants
- MATCH_GENERIC,
- MATCH_MANUFACTURER_MODEL,
- MATCH_MANUFACTURER_MODEL_REVISION,
- MATCH_MANUFACTURER_MODEL_REVISION_SERIAL, or
- MATCH_TYPE,
in the interface UPnPDevice. For further info on which value to return, please read the description of these constants in the OSGi UPnP Device Service specification. In particular, our driver will check if the UPnPDevice represents a device of type “BinaryLight”(type specified in a property defined in the specification of the device category for the base driver).
[edit] Attachment and refinement
Then, if the matching is successful, the device manager will attach the device to our driver by invoking its attach method, passing a reference to the device service.
At this point, our driver will register a service implementing the osami.device.model.control.Light interface, defined in the OSAmI Device model, which will wrap a reference to the UPnPDevice service, and translate any invocation of Light device service methods into lower level UPnP actions invocation on the UPnP device, as appropriate, through the UPnPDevice service.
Also note that bye implementing the Light interface, also all its super interfaces are implemented. This is useful since our driver is supposed to register the refined service not only under the Light device, but under all of the interfaces of the OSAmI model that it implements. In our example the service would be registered under the following interfaces: Light, Switch, Actuator, and LogicalDevice. This way, applications can access more abstract common views of several types of devices that share common characteristics.
[edit] Further requirements
Besides all this, every device is expected to implement some more requirements depending on its kind: actuator or sensor.
Read on trough next sections for further info.
[edit] How to integrate a Sensor device in the OSAmI Platform
Apart from what has been explained in the previous section, some other conventions has been set for the integration of devices into the OSAmI platform.
In this chapter, the way in which sensor devices should publish their different measurements is described.
[edit] Measurements model
Along with the definition of the interfaces for the supported device types, the OSAmI model also provides some interfaces to represent the different kinds of measurements the supported sensor types can provide. Some examples are Temperature, CO2Level, or WindSpeed, among others.
This interfaces are based upon the OSGi Measurement specification.
[edit] OSGi Wires: publishing and consuming measurements
The proposed approach for distributing the data measured by a sensor device is through the use of the OSGi Wire Admin service.
Besides the appropriate device services from the OSAmI device model (according to section 3.2 Refining Drivers and OSAmI Device model), for each sensor device there must be some service implementing the Producer interface and indicating the type of measurements it produces in the FLAVORS property, and be registered in the framework also under this interface. In order to properly publish the data produced, it may have to deal with the reception of events in a technology dependent way.
In order to consume this data, another service must implement the Consumer interface and set the data flavors it is interested in, and may also set some filters to apply in the data reception.
For further info read the OSGi Wire Admin Service Specification (OSGi Service Platform Service Compendium, 108).
[edit] Example
To follow the same example as in the previous sections,let us suppose that the need now is to integrate a UPnP temperature sensor into the OSAmI platform.
Assuming the device is already connected and the base driver is installed, a refining driver should successfully attach itself to the appropriate UPnP Device service and register a TemperatureSensor service representing the device.
But this device should also be represented by a Producer service which will deliver all the measurements generated from the sensor. The entity accountable for the registration of this Producer should be the refining driver, since it is supposed to already know the kind of device and type of data it is going to produce.
Anyway, this producer may poll the device regularly or listen to the appropriate UPnP events and interpret them correctly, transform the data to the corresponding Temperature type (from the OSAmI Device model), and publish it by means of the OSGi Wire Admin service (in this particular case, the OSGi UPnP base driver makes use of the OSGi Event Admin service to distribute the UPnP events, under the topic "org/osgi/service/upnp/UPnPEvent").
[edit] How to integrate an Actuator device in the OSAmI Platform
Any application can act on any device integrated in the platform by simply retrieving the service representing it and invoking the appropriate methods. The same can also be applied when an application needs to know the state of a device at a given time: it will simply invoke the methods offering this info.
Anyway, sometimes an application needs to be notified whenever a change on the state of a device happens, without having to constantly poll it.
In this chapter, the way in which actuator devices should notify their state changes is described.
[edit] OSAmI Device Events
Basically, device drivers will make use of the OSGi Event Admin service to distribute events conveying information about their state changes.
The events will comply with the following points:
- The event topic must be "osami/device/statechanged"
- A property named “id” will contain the source device id
- A property named “deviceType” will contain the type of the source device (simple interface name in the OSAmI model, e.g. “Light”)
- A property named “statevarname” will contain the name of the altered state variable. The possible values for this property depend on the type of the device.
- A property named “value” will contain the new value for the altered state variable. The possible values for this property depend on the state variable changed.
- A property named “timestamp” will contain the value of System.currentTimeMillis() in the instant the change took place.
The supported device types, the state variables of each one of them, and their valid values are specified in the OSAmI-ES Device model.
[edit] Example
Let us continue the UPnP Light example in previous sections.
Assuming the device is already connected and the base driver is installed, a refining driver should successfully attach itself to the UPnP Device service and register a Light service representing the device.
Also, this device should also be publishing its state changes through the OSGi Event Admin service.
So, supposing someone just switched the light on, the driver will receive some notification (in a technology dependent way) and will post an OSGi Event with the following properties:
- Topic : “osami/device/statechanged”
- id : “justanexample-light-id-01”
- statevarname: “lightOn”
- value : “true”
- timestamp: “9876543210” (made up number)
Any application that needs to be notified whenever a change happens in a particular device just has to register an EventListener service for this topic, maybe with some filter based on the device type or id, or state variable name.
