UPnP/Jini Lookup Service

Jan Newmarch

Draft UPnP/Jini specification

A draft UPnP/Jini specification is available at http://jan.newmarch.name/java/jini/upnpLUS/specification.html. JavaDoc supporting this specification is available from http://jan.newmarch.name/java/jini/upnpLUS/doc/index.html

Draft paper

A draft paper is here

Status

Version 0.8 alpha. Last modified 1 August 2005.
The code is full of debugging statements, and large chunks need to be completed. But it is capable of

Generating a Java interface from a UPnP description file or URL
Has a lookup service that can listen for UPnP devices and their services, and return a Java proxy to a Jini client doing a lookup()
A Jini client can make calls on a UPnP device's services using SOAP
A Jini client can register as a listener for UPnP events
A Jini client registered as a listener can receive UPnP events

What is it?

UPnP is a TCP-based middleware designed for managing devices such as those found in a home or office. These devices include light switches, home heating systems, etc. The home site for UPnP is www.upnp.org.

UPnP does not use a lookup service. Instead, each device broadcasts an advert about every 2 minutes. Control points can listen for such adverts or send out requests for devices. Devices hosts services - usually one, but a device could host many. In addition, some devices can also include other devices, with their own services. Once a control point has located a service it can send remote procedure calls to it, query state variables or act as a listener to state changes in the service. Remote procedure calls, state queries and state change events are all sent as SOAP messages.

This project builds a Jini lookup service that listens for UPnP device adverts. Each UPnP service can be represented by a Java interface (defined by this project), and Jini clients can query the lookup service using these interfaces. The lookup service will then deliver a Java Proxy that will use SOAP to talk directly to the UPnP service.

Required software

This project is built using the CyberLink UPnP toolkit for Java. This is required to build and run the lookup service and is downloaded to the client to run the proxy. The default file clink170.jar contains the source code as well as the classes, and it is a waste of bandwidth to download the source code. A classes-only version is available from here.

CyberLink also uses XML parsers. The default is the Xerces parser xercesImpl.jar and xml-apis.jar, but these are really heavyweight (over 1Mbyte). The kXML parser is used instead and is available from SourceForge.

These files clink170-nosrc.jar (or clink170.jar) and kxml2.jar have to be in the runtime of the lookup service. The project builds a file upnpLUS-dl.jar and all of upnpLUS-dl.jar, clink170-nosrc.jar and kxml2.jar have to be on the codebase of the lookup service as the proxy downloaded to clients makes use of them. This means about 200k has to be downloaded from the HTTP server to a client. This is larger than many proxies (e.g. reggie-dl.jar is about 50k) but is not significant. Still, that is one of the problems with using SOAP...

Source code

The source code is available as a zip file.

Creating service interfaces

A UPnP device description file is used to create Java interfaces using

    java upnp.Interface destinationDirectory device-description-file|url

The interfaces are written to files in the destination directory. The interfaces are defined to belong to the package jiniupnp.service. Some examples are in the directory src/jiniupnp/service.

There may be many services for any device. A device may also contain embedded devices with their own services. All of these service interfaces are generated.

Running the lookup service

    java upnpLUS.UPnPLUS


or by the Ant command
    ant runlus

This requires standard Jini jar files to be in the classpath and also the Cyberlink
jar files.


Running UPnP services


Some devices on the network may already be UPnP services, such as routers.
These will be detected by the UPnP LUS. Other services, such as a clock,
a light and aTV are on the CyberLink site. This package also contains a
simple "echo" service in the directory src/device. This may be
run by
    java device.EchoDevice
or by the Ant command
    ant runechoservice
This requires the Cyberlink jar files to be in the classpath.


Running Jini clients


Some sample Jini clients able to call UPnP services are given in the
src/client directory. For example, to run the light switch power
client
    java client.PowerClient
or by the Ant command
    ant runpower
This requires the Jini jar files to be in the classpath.


License


This software is covered by the Apache 2 license, the same as Jini.


To do



  
      The client side currently needs CyberLink and an XML parser.
      Using Xerces, these amount to 1.3M of download from an HTTP
      server. Replacing this with kXML reduces it to about 300k.
      Most of this is clink170.jar. I currently build a Device object
      in the client and this pulls in almost all of the CyberLink
      package. This should be replaced by a lighter package
  
  
      The Holder classes are not complete
  
  
      State variable queries are deprecated by the UPnP organisation, so will not be done
  
  
      Complete the stub methods in the registrar
  
  
      Add generation of Entry information from service description
  
  
      Add handling of Entry information in lookup
  
  
      Link UPnP UUID to Jini UUID
  



Changes

Version 0.8 (1 August, 2005)



  
      Tidied up datatypes in specification
  
  
      Modified example echo client for new datatypes
  



Version 0.7 (July 26, 2005)


  
      Updated draft UPnP/Jini specification to version 0.2.
      The implementation has not been changed and is thus out-of-date
      with respect to the specification
  
  
      Draft paper added
  


Version 0.6 (July 14, 2005)


  
      Added draft UPnP/Jini specification
  


Version 0.5 (July 12, 2005)



  
      Added UPnPEntry class, and fill it with device data
  
  
      Completed registrar method ServiceMatches lookup(template, maxMatches)
  


Version 0.4 (June 25, 2005)



  
      Added event handling from UPnP services
  
  
      Modified build.xml to run client classes from a directory where they can't
      access service files except by HTTP server
  



Version 0.3 (June 18, 2005)



  
      "No source" version of CyberLink made available to reduce download size
  
  
      Integer data types added
  
  
      Interface for my Billion Wireless Gateway device generated and included.
      However, this device doesn't implement all of the UPnP Gateway spec and
      doesn't seem to work anyway
  
  
      Example client for CyberLink Clock device/Timer service included
  
  
      Example client for CyberLink Light device/Power service included
  



Version 0.2 (June 15, 2005)



  
      Nested devices are now handled
  
  
      Interfaces are saved to file instead of (just) printed to stdout
  



Version 0.1 (June 13, 2005)


Initial version



Jan Newmarch (http://jan.newmarch.name)
jan@newmarch.name


Last modified: Mon Aug  1 20:55:26 EST 2005


Copyright ©Jan Newmarch

Access count since May 2005 is: 

This page is