Device description

Each device has an XML page that gives a detailed description of the device

• device name, manufacturer, etc
• a list of services
• each service has
  • service name, service type, etc
  • list of methods that can be called (with parameters)
  • list of state variables (that can generate events on change)
  • url for event handling

Basic device

• This device has no services
• It can be used as the "base type" for building your own device description
• Services can be added to a basic type
• A basic device is not recognised as an "official" device by the UPnP consortium
• A basic device which has non-official services added will not be recognised either

• 
  
  <?xml version="1.0"?> 
  <root xmlns="urn:schemas-upnp-org:device-1-0"> 
    <specVersion> 
      <major>1</major> 
      <minor>0</minor> 
    </specVersion> 
    <URLBase>base URL for all relative URLs</URLBase> 
    <device> 
      <deviceType>urn:schemas-upnp-org:device:Basic:1</deviceType> 
      <friendlyName>short user-friendly title</friendlyName> 
      <manufacturer>manufacturer name</manufacturer> 
      <manufacturerURL>URL to manufacturer site</manufacturerURL> 
      <modelDescription>long user-friendly title</modelDescription> 
      <modelName>model name</modelName> 
      <modelNumber>model number</modelNumber> 
      <modelURL>URL to model site</modelURL> 
      <serialNumber>manufacturer's serial number</serialNumber> 
      <UDN>uuid:UUID</UDN> 
      <UPC>Universal Product Code</UPC> 
      <iconList> 
        <icon> 
          <mimetype>image/format</mimetype> 
          <width>horizontal pixels</width> 
          <height>vertical pixels</height> 
          <depth>color depth</depth> 
          <url>URL to icon</url> 
        </icon> 
        XML to declare other icons, if any, go here 
      </iconList> 
      <presentationURL>URL for presentation</presentationURL> 
    </device> 
  </root> 
        

Dimmable light

A dimmable light contains two services: on/off switch and dim

<?xml version="1.0"?> 
<root xmlns="urn:schemas-upnp-org:device-1-0"> 
  <specVersion> 
    <major>1</major> 
    <minor>0</minor> 
  </specVersion> 
  <URLBase>base URL for all relative URLs</URLBase> 
  <device> 
    <deviceType>urn:schemas-upnp-org:device:DimmableLight:1</deviceType> 
    <friendlyName>short user-friendly title</friendlyName> 
    <manufacturer>manufacturer name</manufacturer> 
    <manufacturerURL>URL to manufacturer site</manufacturerURL> 
    <modelDescription>long user-friendly title</modelDescription> 
    <modelName>model name</modelName> 
    <modelNumber>model number</modelNumber> 
    <modelURL>URL to model site</modelURL> 
    <serialNumber>manufacturer's serial number</serialNumber> 
    <UDN>uuid:UUID</UDN> 
    <UPC>Universal Product Code</UPC> 
    <iconList> 
      <icon> 
        <mimetype>image/format</mimetype> 
        <width>horizontal pixels</width> 
        <height>vertical pixels</height> 
        <depth>color depth</depth> 
        <url>URL to icon</url> 
      </icon> 
      XML to declare other icons, if any, go here 
    </iconList> 
    <serviceList> 
      <service> 
        <serviceType>urn:schemas-upnp-org:service: SwitchPower:1</serviceType> 
        <serviceId>urn:upnp-org:serviceId: SwitchPower:1</serviceId> 
        <SCPDURL>URL to service description</SCPDURL> 
        <controlURL>URL for control</controlURL> 
        <eventSubURL>URL for eventing</eventSubURL> 
      </service> 
      <service> 
        <serviceType>urn:schemas-upnp-org:service:Dimming:1</serviceType> 
        <serviceId>urn:upnp-org:serviceId:Dimming:1</serviceId> 
        <SCPDURL>URL to service description</SCPDURL> 
        <controlURL>URL for control</controlURL> 
        <eventSubURL>URL for eventing</eventSubURL> 
      </service> 
      Declarations for other services added by UPnP vendor (if any) go here 
    </serviceList> 
    <deviceList> 
      Description of embedded devices added by UPnP vendor (if any) go here 
    </deviceList> 
    <presentationURL>URL for presentation</presentationURL> 
  </device> 
</root> 

• The detailed description of the service is given by another XML document
• Controlling the service is given by a url to a SOAP service
• Registering for event handling is done at another url

Service description

• Each service has a set of actions which are the methods that can be called
• Each action has a name and a set of parameters
• Each parameter has a type, allowable values (for enumerated types), and direction (in or out)
• The state of the service is given by state variables e.g. onOrOff and brightness for a dimmable light switch. Each one has type, possible values, etc
• Each action is also associated with a state variable that it changes e.g. on() changes the value of onOrOff
• Each state variable can be set to send events on change

• 
  <?xml version="1.0"?> 
  <scpd xmlns="urn:schemas-upnp-org:service-1-0"> 
    <specVersion> 
      <major>1</major> 
      <minor>0</minor> 
    </specVersion> 
    <actionList> 
      <action> 
      <name>SetTarget</name> 
        <argumentList> 
          <argument> 
            <name>newTargetValue</name> 
            <relatedStateVariable> Target
            </relatedStateVariable> 
            <direction>in</direction> 
          </argument> 
        </argumentList> 
      </action> 
      <action> 
      <name>GetTarget</name> 
        <argumentList> 
          <argument> 
            <name>RetTargetValue</name> 
            <relatedStateVariable>Target</relatedStateVariable> 
            <direction>out</direction> 
          </argument> 
        < argumentList/> 
      </action> 
      <action> 
      <name>GetStatus</name> 
        <argumentList> 
          <argument> 
            <name>ResultStatus</name> 
            <relatedStateVariable>Status</relatedStateVariable> 
            <direction>out</direction> 
          </argument> 
        </argumentList> 
      </action> 
      Declarations for other actions added by UPnP vendor (if any) go here 
    </actionList> 
    <serviceStateTable> 
      <stateVariable sendEvents="no"> 
        <name>Target</name> 
        <dataType>boolean</dataType> 
        <defaultValue>0</defaultValue> 
      </stateVariable> 
      <stateVariable sendEvents="yes"> 
        <name>Status</name> 
        <dataType>boolean</dataType> 
        <defaultValue>0</defaultValue> 
      </stateVariable> 
      Declarations for other state variables added by UPnP vendor (if any)  
      go here 
    </serviceStateTable> 
        

• In addition, a set of error codes may be returned
  • 401 Invalid Action
  • 402 Invalid Args
  • 404 Invalid Var
  • 501 Action Failed
• This achieves a similar result to a WSDL description of a web service - why two standards? Don't know

---

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

jan@newmarch.name
Last modified: Tue May 4 22:15:38 EST 2004
Copyright ©Jan Newmarch
Copyright © Jan Newmarch, Monash University, 2007
This work is licensed under a Creative Commons License
The moral right of Jan Newmarch to be identified as the author of this page has been asserted.