UPnP programming

• Microsoft supply a .NET API for Windows XP and CE
• Atinav has a commercial C and Java UPnP stack. MetroWorks has a Java stack
• Intel has an open source implementation in C for Linux
• CyberLink has an open source implementation in Java
• There is no apparent Java support from Sun for UPnP, although they are a member of the UPnP consortium

Cyberlink Java

Cyberlink Programmer's Guide

Echo

• The internet "echo" service listens on a standard port and just sends back whatever string is sent to it.
• We can write a UPnP device/service that will perform the same role
• The device contains a service that echoes back what is sent to it
• Source code, etc, is here

Echo device description

<?xml version="1.0" ?> 
<root xmlns="urn:schemas-upnp-org:device-1-0">
	<specVersion>
		<major>1</major> 
		<minor>0</minor> 
	</specVersion>
	<device>
		<deviceType>urn:schemas-upnp-org:device:echo:1</deviceType> 
		<friendlyName>Echo device</friendlyName> 
		<manufacturer>Jan Newmarch</manufacturer> 
		<manufacturerURL>http://jan.newmarch.name</manufacturerURL> 
		<modelDescription>Jan's Simple Echo Device</modelDescription> 
		<modelName>Echo</modelName> 
		<modelNumber>1.0</modelNumber> 
		<modelURL>http://jan.newmarch.name</modelURL> 
		<serialNumber>1234567890</serialNumber> 
		<UDN>uuid:jan_echo_server_1</UDN> 
		<UPC>123456789012</UPC> 
		<iconList>
			<icon>
				<mimetype>image/gif</mimetype> 
				<width>48</width> 
				<height>32</height> 
				<depth>8</depth> 
				<url>/description/icon.gif</url> 
			</icon>
		</iconList>
		<serviceList>
			<service>
				<serviceType>urn:schemas-upnp-org:service:echo:1</serviceType> 
				<serviceId>urn:schemas-upnp-org:serviceId:echo:1</serviceId> 
				<SCPDURL>/service_description.xml</SCPDURL> 
				<controlURL>/service/timer/control</controlURL> 
				<eventSubURL>/service/timer/eventSub</eventSubURL> 
			</service>
		</serviceList>
		<presentationURL>/presentation</presentationURL> 
	</device>
</root>

Echo service description

<?xml version="1.0"?>
<scpd xmlns="urn:schemas-upnp-org:service-1-0" >
    <specVersion>
	<major>1</major>
	<minor>0</minor>
    </specVersion>
    <actionList>
	<action>
	    <name>Echo</name>
	    <argumentList>
		<argument>
		    <name>InText</name>
  		    <relatedStateVariable>Text</relatedStateVariable>
		    <direction>in</direction>
		</argument>
		<argument>
		    <name>ReturnText</name>
		    <relatedStateVariable>Text</relatedStateVariable>
		    <direction>out</direction>
		</argument>
	    </argumentList>
	</action>
    </actionList>
    <serviceStateTable>
	<stateVariable sendEvents="no">
	    <name>Text</name>
	    <dataType>string</dataType>
	</stateVariable>
    </serviceStateTable>
</scpd>

Echo device

Echo client

Ant file for echo

A build.xml is

<project name="UPnP demos" default="usage" basedir=".">

    <!-- CONFIGURABLE STUFF HERE -->
    <!-- where this directory is -->
    <property name="top" value="/home/httpd/html/internetdevices/upnp/java/echo"/>

    <property name="upnp_lib" value="${top}/lib/clink132a.jar"/>
    <property name="xerces_lib" value="${top}/lib/xercesImpl.jar"/>
    <property name="xml_lib" value="${top}/lib/xml-apis.jar"/>

    <!-- END CONFIGURABLE STUFF -->

    <!-- Directories -->

  <!-- Show the usage options to the user -->
  <target name="usage" >
    <echo message=""/>
    <echo message=""/>
    <echo message="-------------------------------------------------------------"/>
    <echo message=""/>
    <echo message="available targets are:"/>
    <echo message=""/>
    <echo message=" compile"/>
    <echo message=" rundevice"/>
    <echo message=" runclient"/>
    <echo message=" clean"/>
    <echo message=" usage"/>
    <echo message=""/>
    <echo message="See comments inside the build.xml file for more details."/>
    <echo message="-------------------------------------------------------------"/>
    <echo message=""/>
    <echo message=""/>
  </target>

  <target name="all" depends="init,compile"/> 

    <!-- CLEAN -->
    <target name="clean">
 	<!-- Delete our the ${build}, and ${deploy} directory trees -->
	<delete dir="classes"/>
    </target>


    <target name="init">
	<!-- Create the build directory structure used by compile N deploy -->
    </target>

    <target name="compile">
	<mkdir dir="classes"/>
	<javac destdir="classes" srcdir="src" 
	       classpath="${upnp_lib}"
               target="1.1"/>
    </target>

    <target name="runclient" depends="compile">
	<java
            classpath="${upnp_lib}:${xerces_lib}:${xml_lib}:classes"
	    classname="controlPoint.Client"/>
    </target>

    <target name="rundevice" depends="compile">
	<exec executable="java">
            <env key="CLASSPATH" 
                 path="${upnp_lib}:${xerces_lib}:${xml_lib}:classes"/>
	    <arg line="device.EchoDevice"/>
	</exec>
    </target>
</project>

Compile and run

• Compile all files using javac with classpath set to include
  • src directory
  • clink132a.jar
  • xercesImpl.jar
  • xml-apis.jar
• Run the files using java with classpath set to
  • classes directory
  • clink132a.jar
  • xercesImpl.jar
  • xml-apis.jar
• The run commands are

  
        java device.EchoDevice
        

  
        java controlPoint.Client
        

Flashing clocks

• Any house or organisation with multiple electric timers or clocks will have at least one that is flashing an invalid time, either because no-one has reset it after a power failure or because no-one knows how to
• Ideally, only one timer should need to be set - any one. The rest will set themselves to this one
• Each timer should be available as a service so that any timer can be set from any other one that has been set
• Different devices (wall clock, alarm clock, VCR, stove, ...) will all contain this service

Timer service

• The UPnP consortium has not yet published a timer service, so we can invent our own
• (This is different to the timer service in the Cyberlink doco) The service should have methods
  • GetTime
  • SetTime
  • IsValidTime
• The data-type for the time should be one of the standard XML data types: there is the type date which is defined by ISO 8601 by XML. This represents local time of day using a 24-hour clock as a string "HH:MM" or "HH:MM:SS". The validity should be boolean
• The signatures should look like

  
        time GetTime();
        void SetTime(time);
        boolean IsValidTime();
        

  These will depend on state variables Time and ValidTime
• When the state variables change state, should an event be raised and sent to all listeners? The Time state could change say once a second - this may be too frequent for network traffic, so choose no. The ValidTime will change rarely, and could be important to other timers, so say yes
• The XML description of the service could be

  
  <?xml version="1.0"?>
  <scpd xmlns="urn:schemas-upnp-org:service-1-0" >
      <specVersion>
  	<major>1</major>
  	<minor>0</minor>
      </specVersion>
      <actionList>
  	<action>
  	    <name>SetTime</name>
  	    <argumentList>
  		<argument>
  		    <name>NewTime</name>
    		    <relatedStateVariable>Time</relatedStateVariable>
  		    <direction>in</direction>
  		</argument>
  	    </argumentList>
  	</action>
  	<action>
  	    <name>GetTime</name>
  	    <argumentList>
  		<argument>
  		    <name>CurrentTime</name>
  		    <relatedStateVariable>Time</relatedStateVariable>
  		    <direction>out</direction>
  		</argument>
  	    </argumentList>
  	</action>
          <action>
              <name>TimeValid</name>
              <argumentList>
  		<argument>
  		    <name>Valid</name>
  		    <relatedStateVariable>TimeValid</relatedStateVariable>
  		    <direction>out</direction>
  		</argument>
  	    </argumentList>
  	</action>
      </actionList>
      <serviceStateTable>
  	<stateVariable sendEvents="no">
  	    <name>Time</name>
  	    <dataType>time</dataType>
  	</stateVariable>
  	<stateVariable sendEvents="yes">
  	    <name>TimeValid</name>
  	    <dataType>boolean</dataType>
  	</stateVariable>
      </serviceStateTable>
  </scpd>
        

Java classes for timer service

Running the example

All the source code is available from here . This includes an ant build.xml file. You can use this to build/run the examples by

ant compileclock
ant runtickerclock
ant runcomputerclock

clink123a.jar
xercesImpl.jar
xml-apis.jar

Time

A convenience class to handle ISO 8601 time format

Timer

Interface for different implementations of timers, matches the methods defined for the timer service

Computer Timer

Implementation of timer that gets its time from the computer clock using the Calendar class

Ticker Timer

Another implementation that runs a "ticker" in a thread to update the time. This timer is invalid until something else sets its time

Clock device

• This implements the device part of the clock. It inherits from Device which means it broadcasts information about itself to control points
• It can be sent control messages which are handled by the actionControlReceived() method - it is an ActionListener
• It also has a control point so that it can control other clocks by the deviceNotifyReceived() method - it is a NotifyListener

TickerClock

This creates a clock device, sets a ticker timer in it and starts the frame

ComputerClock

This creates a clock device, sets a computer timer in it and starts the frame

Clock Frame

A JFrame to display the clock

Clock Pane

And a JPane to display the clock