You are on page 1of 9

Cling OSGi UPnP Device Service

Release 1, Version 1
Cling OSGi Device Service Release 1


Introduction
The Cling OSGi UPnP Device Service is an implementation of the OSGi UPnP Device Service
specification version 1.1 as defined in the OSGi Service Platform Service Compendium
(Release 4, Version 4.2 August 2009).

The UPnP Device Architecture specification provides the protocols for a peer-
to-peer network. It specifies how to join a network and how devices can be
controlled using XML messages sent over HTTP. The OSGi specifications
address how code can be download and managed in a remote system. Both
standards are therefore fully complimentary. Using an OSGi Service Platform to
work with UPnP enabled devices is therefore a very successful combination.

This specification specifies how OSGi bundles can be developed that
interoperate with UPnP™ (Universal Plug and Play) devices and UPnP control
points.
1

The OSGi Alliance provides a UPnP Device Service Java package
2
which includes interfaces
and classes that bundles operate with to use or provide UPnP devices.

Cling
3
is a UPnP compliant Java software stack and provides the underlying UPnP
implementation for this OSGi service. Hence the name “Cling” OSGi UPnP Device Service.

The Cling stack is composed of:
● Cling Core: a Java library that implements the UPnP Device Architecture 1.0
4
.
● Teleal Common: a Java library that provides functionality for XML, HTTP, logging, etc.

The Cling project also includes other libraries. Their functionality is not required for this project.

This service is similar to Apache Felix’s UPnP Device Service. Both are built upon a third party
UPnP stack. Apache Felix is built upon CyberLink for Java
5
. This service is built upon Cling.
While the underlying implementation is different, the Apache Felix’s OSGi examples and testing
should work this service.
UPnP Base Driver
1
OSGi Device Service specification version 1.1
2
http://www.osgi.org/javadoc/r4v42/org/osgi/service/upnp/package-summary.html
3
http://teleal.org/projects/cling
4
http://www.upnp.org
5
http://sourceforge.net/projects/cgupnpjava
Cling OSGi Device Service Release 1

The core of a OSGi UPnP Device Service is UPnP base driver. The base driver acts as a bridge
between OSGi and the UPnP networks. It provides the following functions.

UPnP Base Driver Function Cling OSGi UPnP Device Service
Implementation
Discover UPnP devices on the network and
map each discovered device into an OSGi
registered UPnP Device service.

UPnP devices detected on the local
network must be detected and automatically
registered under the UPnPDevice interface
with the Framework by the UPnP driver
implementation bundle.
The Cling UPnP Service includes UPnP
network listeners, background maintenance
threads, etc. Cling accepts a custom
RegistryListener instance which is notified of
all incoming device and service registrations
as soon as the network stack is ready
6
.

Using a Cling RegistryListener the base
driver can observe the discovery of devices
and then register them with the OSGi
framework.
Present UPnP marked services that are
registered with the OSGi Framework on
one or more networks to be used by other
computers.

To make a UPnP service available to
UPnP control points on a network, an OSGi
service object must be registered under the
UPnPDevice interface with the Framework.
The UPnP driver bundle must detect these
UPnP Device services and must make them
available to the network as UPnP devices
using the UPnP protocol.
An OSGi bundle exposes its UPnP device
services by registering them with the OSGi
framework. Using an OSGi framework
ServiceTracker the base driver can observe
the registration of these services and then
present them externally using Cling’s UPnP
Service.
UPnP Device
A UPnP device is a logical representation of services associated with a networked computing
device. A UPnP device can be a single UPnP device or a root UPnP device with a number of
UPnP sub-devices.

A OSGi UPnP Device Service exposes a UPnP device with the UPnPDevice interface using
OGSi’s white board model. A base driver, upon discovering a UPnP device, would wrap the
description of the device within an implementation of the UPnPDevice interface and then
register that instance as a UPnPDevice with the OSGi framework. If the base driver detects
that the UPnP device is not longer available it would unregister that instance from the OSGi
framework.

6
http://teleal.org/projects/cling/core/manual/cling-core-
manual.html#section.BasicAPI.UpnpService
Cling OSGi Device Service Release 1

A OSGi UPnPDevice can represent either an remote or local UPnP device. Remote devices
are imported by the base driver from the network to the OSGi service registry. Local devices
originate from with the OSGi Service Platform. A local UPnP device is registered by its provider
with the OSGi framework and the base driver is required to then export that device to the
network.

Clients within the OSGi framework have the choice of using a UPnPDevice service, listening to
a device’s events via UPnPEventListener, or both.
Discovering Devices
Upon activation the base driver will query and continual monitor the network for UPnP
devices. Upon discover of the device the base driver will register a UPnPDevice with the OSGi
framework. Clients wanting to use that device can then start using its service. The base driver
will also begin tracking UPnPEventListener’s registered for that device and its services. As
events are received from an external device the base driver will route these events to all the
appropriate OSGi listeners.
Presenting Devices
The base driver tracks the registration of internal UPnPDevice’s. When an internal device is
registered the base driver will present and support that device to the network according to the
UPnP specification. It will also register a UPnPEventListener for that device to support external
subscriptions to the device’s services.

The base driver manages UPnP events fired by internal devices. It tracks all
UPnPEventListener’s and handles UPnP event. When it receives an event it notifies all of the
appropriate listeners.

Internal UPnPDevice’s do not need to track their listeners. When an internal device’s state
variable changes the UPnPDevice implementation will send an event to the OSGi Event Admin
service. The base driver captures that event and then routes it to the listeners.
Running with Apache Felix
Apache Felix project is an source source implement of the OSGi R4 Service Platform
7
under the
Apache license. The Cling OSGi UPnP Device Service has been tested with Felix.
Requirements
● Apache Felix Framework Distribution 3.0.7
● OSGi Service Platform Release 4 Compendium Interfaces and Classes bundle.
7
The Felix project includes an implementation of the OSGi UPnP Device Service. This service
is not required to run the Cling OSGi UPnP Device Service and should not be used at the same
time.
Cling OSGi Device Service Release 1

● Apache Felix Event Admin 1.2.8 bundle.
Installation
● Extract the Apache Felix Framework Distribution to a desired location.
● Deploy the OSGi Service Platform Release and Apache Felix Event Admin bundles.
○ This can be achieved in a variety of ways. The simplest is to copy of the bundles
to the bundle directory.
● Deploy the Cling OSGi UPnP Device Service bundle.
○ This can be achieved in a variety of ways. The simplest is to copy of the bundle
to the bundle directory.
Running Apache Felix
Start Apache Felix:

java -jar bin/felix.jar

Depending on the deployment strategy chosen the various bundles will load and activate. The
installed bundles can be listed using the Felix shell command lb. This command should produce
a result similar to this.

START LEVEL 1
ID|State |Level |Name
0|Active | 0|System Bundle (3.0.7)
1|Active | 1|Cling OSGi UPnP Base Driver (1.0.0.SNAPSHOT)
2|Active | 1|Apache Felix Bundle Repository (1.6.2)
3|Active | 1|Apache Felix EventAdmin (1.2.8)
4|Active | 1|Apache Felix Gogo Command (0.6.1)
5|Active | 1|Apache Felix Gogo Runtime (0.6.1)
6|Active | 1|Apache Felix Gogo Shell (0.6.1)
7|Active | 1|OSGi R4 Compendium Bundle (4.1.0)

The Cling OSGi UPnP Device Service is now running. It will expose external UPnP devices to
the framework and present internal UPnP devices to the network.
Running Apache Felix
The Apache Felix Web Console UPnP Plugin is a deployable component for the Apache Felix
Web Console. The UPnP Plugin lists all the registered UPnP devices, their actions and state
variables. It will monitor state variables that send events and it can be used to invoke actions.

To run the web console with the UPnP plugin deploy the following bundles:

● HTTP Service Bundle 2.0.4
● Apache Felix Web Console 3.1.6 (Full)
Cling OSGi Device Service Release 1

● Apache Felix Web Console UPNP Plugin 1.0.0
● JSON Bundle

Start Apache Felix:

java -Dorg.apache.felix.http.jettyEnabled=true -jar bin/felix.jar

The web console will be available at:

http://localhost:8080/system/console

One of the top menu links will be UPnP. Click on this link to access the UPnP console. The
UPnP console will look similar to this.
Cling OSGi Device Service Release 1

Here are some typical sources of the bundles mentioned.

Bundle(s) Bundle Source
Apache Felix http://felix.apache.org/site/downloads.cgi
OSGi Service
Platform R4
Compendium
http://mvnrepository.com/artifact/org.apache.felix/org.osgi.compendium/
1.4.0
JSON http://wiki.chameleon.ow2.org/xwiki/bin/view/Main/Downloads
Test Devices
Description
A test device is available to test the base driver. This device is comprised of a Test service.
The Test service is comprised of a set of “evented” state variables (one for each OSGi UPnP
variable type) and getter/setter actions for each variable. There is also a “GetAllVariables”
action which returns the current value of each variable.
All of the state variables are “evented”. Client applications may monitor them via
UPnPEventListener.
When instantiated the device set the state variables to a default value. If an external properties
file is specified then it will use default to the values in that file. To specify a default data property
Cling OSGi Device Service Release 1

file start the framework with the following Java runtime command line parameter.
-Dorg.teleal.cling.osgi.upnp.basedriver.get.test.properties=path_to_file
This device is contained within an OSGi bundle. When the bundle is activated the device is
instantiated and registered with the OSGi framework. When the bundle is deactivated the device
is unregistered.
Additional Runtime Requirements
None. This device does not have any special pre-requisites.
Test Client
The Test client is an OSGi bundle which include a client which will execute the Test Device’s
service. The client waits for a Test Device to be registered and then will run a set of get and set
tests. It will also monitor changes to the state variables.
Sample Devices
Introduction
OSGi based UPnP sample devices provide examples of how to use the base driver. Each
device or group of devices is contained within an OSGi bundle. When the bundle is activated
the device is instantiated and registered with the OSGi framework. When the bundle is
deactivated the device is unregistered.
UPnP Baisic Device
Description
This sample implements a Basic device. A Basic device (version 1.0) is a minimal device
(one that does not add any services or embedded devices) which is discoverable using UPnP
discovery and may provide identifying information and a Presentation URL using the normal
Device Description mechanism. The Basic Device type does not define any Services or
embedded Devices.
Additional Runtime Requirements
None. This device does not have any special pre-requisites.
Lighting Controls
Description
The UPnP Forum defines two standard lighting control devices:
Cling OSGi Device Service Release 1

● BinaryLight
● DimmableLight
This sample implements each device.
A BinaryLight device is comprised of a Switch Power Service.
A DimmableLight device is comprised of a Switch Power and a Dimming Service. The switching
component is serially connected to the dimming component. The dimmer’s settings will not be
physically realized by the load until the switch is on.
Additional Runtime Requirements
Each device provides a presentation URL. This is an optional feature and will be activated if an
HTTP Service is available.

Cling OSGi Device Service Release 1