UPnP Device Architecture UPnP Forum

							UPnP Device Architecture
Networking is easy, except…
 Ad hoc networks don't have
  resources just for the sake of the
  network
   E.g.,   DHCP, DNS, directory, …
 Network     is unreliable
   Nodes    added / removed unpredictably
 Programs      need to talk to programs
   Butsoftware is heterogeneous
   One size doesn't fit all

 Must    upgrade system piece at a time
UPnP Strategy
1.   Just send data over the network
        (No executables)
        Minimize version issues
        Minimize security issues
2.   Keep implementation private
        Be agnostic re: programming language, OS
        Update implementation w/o affecting interop
          Improve performance
          Reduce footprint
          Improve capabilities
3.   Agree on meaning / format of data
        Choose substrate of proven protocols
        Define device (service) specific protocols in a
         Forum
UPnP Tactics
 Start   simple
   Buildin only universal things that
    everybody needs (and can live with)
   Add as needed

 Minimize   requirements
        IP network connectivity
   Basic
   Common HTTP protocol stack

 Leverage   existing standards
   HTTP,   XML
Goals
        the protocols for
 Describe
 communication between
   Control points         Control Point

     Controller, usually client
   Device                    Device
     Controlled,            Service
      usually server
   An actual device
                           Control Point
    might contain
    both functions            Device

                               Service
Steps to UPnP Networking
          3 Control     4 Eventing    5 Presentation

       2 Description

    1 Discovery

 0 Addressing

0 Control point and device get addresses
1 Control point finds interesting device
2 Control point learns about device capabilities
3 Control point invokes actions on device
4 Control point listens to state changes of device
5 Control point controls device and/or views device
  status using HTML UI
UPnP Protocol Stack




                                                Vendor-specific physical net
     Vendor-specific API above
UPnP vendor

UPnP Forum

UPnP Device Architecture

HTTPU/MU GENA      SSDP    SOAP   HTTP   GENA
                           HTTP
UDP                        TCP

IP


     Vendor-specific OS below
Steps to UPnP Networking
          3 Control     4 Eventing    5 Presentation

       2 Description

    1 Discovery

 0* Addressing

0* Control point and device get addresses
1 Control point finds interesting device
2 Control point learns about device capabilities
3 Control point invokes actions on device
4 Control point listens to state changes of device
5 Control point controls device and/or views device
   status using HTML UI
0 Addressing
 Control   point and device get address
   Use a DHCP server
   Else use Auto IP

 What    is Auto IP?
       Draft Automatically Choosing an IP
   IETF
   Address in an Ad-Hoc IPv4 Network
 What    steps does it take?
   Pick an address in 169.254/16 range
   Check to see if it is used (ARP)
   Periodically check for DHCP server
Steps to UPnP Networking
          3 Control     4 Eventing    5 Presentation

       2 Description

    1* Discovery

 0 Addressing

0 Control point and device get addresses
1* Control point finds interesting device
2 Control point learns about device capabilities
3 Control point invokes actions on device
4 Control point listens to state changes of device
5 Control point controls device and/or views device
   status using HTML UI
1 Discovery
   Control point            Devices
    finds interesting         Advertise   when
    device                      added
       0 get address          Refresh
                                advertisements
       1 discover device       (cf. lease)
                               Cancel
   Advertise / find            advertisements
                                when removed
    typed devices
    (services)               Control points
                              search as needed
       Guarantee of
        minimal                Devices respond
        capabilities           Control points
                                filter
   Simple
1 Discovery: Protocol Stack


 UPnP vendor

 UPnP Forum

 UPnP Device Architecture

 HTTPMU        GENA   SSDP   HTTPU       SSDP
 (multicast)                 (unicast)

 UDP

 IP
1 Discovery: SSDP Sidebar
 What   is SSDP?
   IETFDraft Simple Service Discovery
   Protocol
 Key   design principles
   Administratively-scoped   multicast
   Unicast   responses
   UDP
   Very simple advertisements
   Very simple search
1 Discovery: Advertising
   Who? Device multicasts
   When? Added or refresh (cf. lease)
   What?

NOTIFY * HTTP/1.1
HOST: 239.255.255.250:1900
CACHE-CONTROL: max-age = seconds until advertisement expires
LOCATION: URL for UPnP description for root device
NT: search target
NTS: ssdp:alive
USN: advertisement UUID


         1 time / service type with NT == service type
         1 time / device type with NT == device type
         1 time / device with NT == device UUID
         1 time with NT == upnp:rootdevice
1 Discovery: Searching
   Who? Control point multicasts
   When? Looking for device or service
   What?

M-SEARCH * HTTP/1.1
HOST: 239.255.255.250:1900
MAN: "ssdp:discover"
MX: seconds to delay response
ST: search target


         ST one of
            Service type
            Device type
            Device UUID
            upnp:rootdevice
            ssdp:all
1 Discovery: Responding
   Who? Device unicasts
   When? If ST matches an NT
   What?

HTTP/1.1 200 OK
CACHE-CONTROL: max-age = seconds until advertisement expires
LOCATION: URL for UPnP description for root device
ST: search target
USN: advertisement UUID



      1   time for each NT that matches

       Very    simple matching
Steps to UPnP Networking
          3 Control     4 Eventing    5 Presentation

       2* Description

    1 Discovery

 0 Addressing

0 Control point and device get addresses
1 Control point finds interesting device
2* Control point learns about device capabilities
3 Control point invokes actions on device
4 Control point listens to state changes of device
5 Control point controls device and/or views device
   status using HTML UI
2 Description
   Control point          Protocol    stack
    learns about
    device capabilities   UPnP vendor
    0  get address       UPnP Forum
     1 discover device
                          UPnP Device Architecture
       get URL for
         description      HTTP
     2 retrieve descr
                          TCP
       get URL for
         service          IP
         description


   Declare
    capabilities
2 Description
   Device description            Services
       Type                        Functional units
       Physical container           within devices
       Logical container
                                  Service
          For each service
                                  description
              Type
              URL for              Actions
               description          Statevariables
              URL for control
                                    Actual (vs.
              URL for
               eventing
                                     designed)
                                     implementation
       UI
          Icons
          URL for                Expressed   in XML
           presentation
2 Description: XML Sidebar
   What is XML?
       W3C Recommendation Extensible Markup Language
       "Universal format for structured documents and data on
        the Web."
           Field names in <angle brackets>
           Field values between names
       Defines 24 data types
           ui1, ui2, ui4, i1, i2, i4, int
           r4, r8, number, fixed.14.4, float
           char, string
           date, dateTime, dateTime.tz, time, time.tz
           boolean
           bin.base64, bin.hex
           uri
           uuid
 2 Description: Device (phys)
<?xml version="1.0"?>
<root xmlns="urn:schemas-upnp-org:device-1-0">
<URLBase>base URL for all relative URLs</URLBase>




 <device>
  <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>
 <deviceType>urn:schemas-upnp-org:device:deviceType</deviceType>
 <serviceList>
  <service>
    <serviceType>urn:schemas-upnp-org:service:serviceType:v</serviceType>
    <serviceId>urn:upnp-org:serviceId:serviceID</serviceId>
    <SCPDURL>URL to service description</SCPDURL>
    <controlURL>URL for control</controlURL>
    <eventSubURL>URL for eventing</eventSubURL>
  </service>
  Declarations for other services (if any) go here
 </serviceList>
 <deviceList>Description of embedded devices (if any) go here</deviceList>
 <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>
<specVersion>
 <major>1</major> <minor>0</minor>
</specVersion>




</root>
  2 Description: Device (logical)
<?xml version="1.0"?>




<root xmlns="urn:schemas-upnp-org:device-1-0">
 <URLBase>base URL for all relative URLs</URLBase>
 <device>
  <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>




            <deviceType>urn:schemas-upnp-org:device:deviceType :v</deviceType>
            <serviceList>
             <service>
              <serviceType>urn:schemas-upnp-org:service:serviceType:v</serviceType>
              <serviceId>urn:upnp-org:serviceId:serviceID</serviceId>
              <SCPDURL>URL to service description</SCPDURL>
              <controlURL>URL for control</controlURL>
              <eventSubURL>URL for eventing</eventSubURL>
             </service>
             Declarations for other services (if any) go here
            </serviceList>
  <iconList>
            <deviceList>Description of embedded devices (if any) go here</deviceList>
   <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>
 <specVersion>
  <major>1</major> <minor>0</minor>
 </specVersion>




</root>
  2 Description: Device (other)
<?xml version="1.0"?>




<root xmlns="urn:schemas-upnp-org:device-1-0">
 <URLBase>base URL for all relative URLs</URLBase>




 <device>
 <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>
 <deviceType>urn:schemas-upnp-org:device:deviceType</deviceType>
 <serviceList>
  <service>
    <serviceType>urn:schemas-upnp-org:service:serviceType:v</serviceType>
    <serviceId>urn:upnp-org:serviceId:serviceID</serviceId>
    <SCPDURL>URL to service description</SCPDURL>
    <controlURL>URL for control</controlURL>
    <eventSubURL>URL for eventing</eventSubURL>
  </service>
  Declarations for other services (if any) go here
 </serviceList>
 <deviceList>Description of embedded devices (if any) go here</deviceList>




   <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>
 <specVersion>
   <major>1</major> <minor>0</minor>
 </specVersion>
</root>
 2 Description: Service (actns)
<?xml version="1.0"?>
<scpd xmlns="urn:schemas-upnp-org:service-1-0">
 <actionList>
  <action>
   <name>actionName</name>
   <argumentList>
    <argument>
      <name>formalParameterName</name>
      <direction>in xor out</direction>
      <retval />
      <relatedStateVariable>stateVariableName</relatedStateVariable>
    </argument>
    Declarations for other arguments (if any) go here
   </argumentList>
  </action>
  Declarations for other actions (if any) go here
 </actionList>
<serviceStateTable>
 <stateVariable sendEvents=“yes” xor “no”>
   <name>variableName</name>
   <dataType>variable datatype</dataType>
   <defaultValue>default value</defaultValue>
   <allowedValueRange>
    <minimum>minimum value</minimum>
    <maximum>maximum value</maximum>
    <step>increment value</step>
   </allowedValueRange>
 </stateVariable>
 <stateVariable sendEvents=“yes” xor “no”>
   <name>variableName</name>
   <dataType>variable data type</dataType>
   <defaultValue>default value</defaultValue>
   <allowedValueList>
    <allowedValue>some value</allowedValue>
    <allowedValue>some value</allowedValue>
   </allowedValueList>
 </stateVariable>
 Declarations for other state variables (if any) go here
</serviceStateTable>
<specVersion>
 <major>1</major> <minor>0</minor>
</specVersion>




</scpd>
 2 Description: Service (vars)
<?xml version="1.0"?>
<scpd xmlns="urn:schemas-upnp-org:service-1-0">
<actionList>
 <action>
   <name>actionName</name>
   <argumentList>
    <argument>
      <name>formalParameterName</name>
      <direction>in xor out</direction>
      <retval />
      <relatedStateVariable>stateVariableName</relatedStateVariable>
    </argument>
   Declarations for other arguments (if any) go here
   </argumentList>
 </action>
 Declarations for other actions (if any) go here
</actionList>




     <serviceStateTable>
      <stateVariable sendEvents=“yes” xor “no”>
       <name>variableName</name>
       <dataType>variable datatype</dataType>
       <defaultValue>default value</defaultValue>
       <allowedValueRange>
        <minimum>minimum value</minimum>
        <maximum>maximum value</maximum>
        <step>increment value</step>
       </allowedValueRange>
      </stateVariable>
 <stateVariable sendEvents=“yes” xor “no”>
  <name>variableName</name>
  <dataType>variable data type</dataType>
  <defaultValue>default value</defaultValue>
  <allowedValueList>
    <allowedValue>some value</allowedValue>
    <allowedValue>some value</allowedValue>
  </allowedValueList>
 </stateVariable>
 Declarations for other state variables (if any) go here




     </serviceStateTable>
<specVersion>
 <major>1</major> <minor>0</minor>
</specVersion>




</scpd>
 2 Description: Service (vars)
<?xml version="1.0"?>
<scpd xmlns="urn:schemas-upnp-org:service-1-0">
<actionList>
 <action>
   <name>actionName</name>
   <argumentList>
    <argument>
      <name>formalParameterName</name>
      <direction>in xor out</direction>
      <retval />
      <relatedStateVariable>stateVariableName</relatedStateVariable>
    </argument>
   Declarations for other arguments (if any) go here
   </argumentList>
 </action>
 Declarations for other actions (if any) go here
</actionList>




     <serviceStateTable>
 <stateVariable sendEvents=“yes” xor “no”>
  <name>variableName</name>
  <dataType>variable datatype</dataType>
  <defaultValue>default value</defaultValue>
  <allowedValueRange>
    <minimum>minimum value</minimum>
    <maximum>maximum value</maximum>
    <step>increment value</step>
  </allowedValueRange>
 </stateVariable>




      <stateVariable sendEvents=“yes” xor “no”>
       <name>variableName</name>
       <dataType>variable data type</dataType>
       <defaultValue>default value</defaultValue>
       <allowedValueList>
        <allowedValue>some value</allowedValue>
        <allowedValue>some value</allowedValue>
       </allowedValueList>
      </stateVariable>
      Declarations for other state variables (if any) go here
     </serviceStateTable>
<specVersion>
 <major>1</major> <minor>0</minor>
</specVersion>




</scpd>
Steps to UPnP Networking
          3* Control    4 Eventing    5 Presentation

       2 Description

    1 Discovery

 0 Addressing

0 Control point and device get addresses
1 Control point finds interesting device
2 Control point learns about device capabilities
3* Control point invokes actions on device
4 Control point listens to state changes of device
5 Control point controls device and/or views device
   status using HTML UI
3 Control
   Control point          Protocol    stack
    invokes actions on
    device                UPnP vendor

    0  get address       UPnP Forum
     1 discover device   UPnP Device Architecture
     2 retrieve descr
                          SOAP
       get URL for
         control          HTTP
     3 send actions to   TCP
      device
                          IP
3 Control: SOAP Sidebar
 What   is SOAP?
   IETF Draft Simple Object Access
    Protocol
   "Lightweight, XML-based protocol for
    exchange of information in a
    decentralized, distributed environment."
     Envelope: defines a framework for
      describing what is in a message and
      how to process it.
     Convention: represent remote
      procedure calls and responses.
3 Control: Invoke Action
     Who? Control point
     When? To invoke action on device
     What?

POST path of control URL HTTP/1.1
HOST: host of control URL:port of control URL
CONTENT-TYPE: text/xml; charset="utf-8"
SOAPACTION: "urn:schemas-upnp-org:service:serviceType:v#actionName"

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
  s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
 <s:Body>
   <u:actionName xmlns:u="urn:schemas-upnp-org:service:serviceType:v">
    <argumentName>in arg value</argumentName>
    other in args and their values (if any) go here
   </u:actionName>
 </s:Body>
</s:Envelope>
3 Control: Action Result
     Who? Device
     When? Action completes
     What?

HTTP/1.1 200 OK
CONTENT-TYPE: text/xml; charset="utf-8"

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
  s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
 <s:Body>
   <u:actionNameResponse
     xmlns:u="urn:schemas-upnp-org:service:serviceType:v">
    <argumentName>out arg value</argumentName>
    other out args and their values (if any) go here
   </u:actionNameResponse>
 </s:Body>
</s:Envelope>
Steps to UPnP Networking
          3 Control     4* Eventing   5 Presentation

       2 Description

    1 Discovery

 0 Addressing

0 Control point and device get addresses
1 Control point finds interesting device
2 Control point learns about device capabilities
3 Control point invokes actions on device
4* Control point listens to state changes of device
5 Control point controls device and/or views device
   status using HTML UI
4 Eventing
   Control point           Protocol    stack
    listens to state
                           UPnP vendor
    changes of device
    0  get address        UPnP Forum

     1 discover device    UPnP Device Architecture
     2 retrieve descr
                           HTTP                GENA
       get URL for
         eventing
     4 subscribe to       TCP
      events from device
                           IP


 Basicpush model
 Simple
4 Eventing: GENA Sidebar
 What   is GENA?
   IETF Draft General Event Notification
    Architecture
   "Send and receive notifications using
    HTTP over TCP/IP and administratively-
    scoped multicast UDP."
     SUBSCRIBE to notifications
     UNSUBSCRIBE
     NOTIFY
       Of device availability
       Of state variable changes
4 Eventing: Subscribing
   Who? Control point
   When? Before receiving any events
   What?

SUBSCRIBE publisher path HTTP/1.1
HOST: publisher host:publisher port
CALLBACK: <delivery URL>
NT: upnp:event
TIMEOUT: Second-requested subscription duration
4 Eventing: Subscription
   Who? Device
   When? Accepts subscription
   What?

HTTP/1.1 200 OK
SID: uuid:subscription-UUID
TIMEOUT: Second-actual subscription duration




       Device    immediately sends a special,
         initial event to control point with the
         value of all evented variables
4 Eventing: Notify
   Who? Device
   When? A state variable changes
   What?

NOTIFY delivery path HTTP/1.1
HOST: delivery host:delivery port
CONTENT-TYPE: text/xml
NT: upnp:event
NTS: upnp:propchange
SID: uuid:subscription-UUID
SEQ: event key

<e:propertyset xmlns:e="urn:schemas-upnp-org:event-1-0">
 <e:property>
  <variableName>new value</variableName>
 </e:property>
 Other variable names and values (if any) go here
</e:propertyset>
Steps to UPnP Networking
          3 Control     4 Eventing    5* Presentation

       2 Description

    1 Discovery

 0 Addressing

0 Control point and device get addresses
1 Control point finds interesting device
2 Control point learns about device capabilities
3 Control point invokes actions on device
4 Control point listens to state changes of device
5* Control point controls device and/or views device
   status using HTML UI
5 Presentation
   Control point            Protocol    stack
    controls device
    and/or views            UPnP vendor
    device status
    using HTML UI           UPnP Device Architecture
    0  get address         HTTP
     1 discover device
                            TCP
     2 retrieve descr
       get URL for         IP
         presentation
     5 load presentation
      page


   (Don't constrain
    implementation)
Summary
   UPnP says
    1.   Just send data
    2.   Keep implementation private
    3.   Agree on content / format of data
   UPnP is
        Web-based protocols
        Tailored by a Forum for device (service) types
        That are API, OS, physical network neutral
        For discovery, description, control, eventing
        (And simple HTML UI too)
   For more information
        Resources: http://www.upnp.org
        Questions? mailto:UPNPWORLD@FORUM.UPNP.ORG