UPnP Device Architecture 1.0
Document Version 1.0.1, 20 July 2006
Note: This document version 1.0.1 consolidates the several separate documents that make up the entirety of UPnP Device Architecture Version 1.0, including the previously separate specifications for AutoIP, SSDP, HTTPU/MU, FXPP, and GENA, and clarifications made in the UPnP Vendor Implementation Guide. It does not introduce any new technical requirements, but constitutes an editorial clarification only.
Contributors
Allegro Software Development Corporation Conexant Systems, Inc.
Intel Corporation Microsoft Corporation Motorola
Nokia Corporation Philips Electronics Pioneer
Sony Electronics
© 1999-2006 Contributing Members of the UPnP Forum. All rights reserved. See http://www.upnp.org/info/cpyright.asp for more information.
Table of Contents
Introduction... 1
What is UPnP Technology? ...1
UPnP Forum ...1
In this document ...2
Audience ...4
Required vs. recommended ...4
Acronyms ...4
References and resources...5
0. Addressing ... 6
0.1 Addressing: Determining whether to use Auto-IP...6
0.2 Addressing: Choosing an address ...6
0.3 Addressing: Testing the address...7
0.4 Addressing: Periodic checking for dynamic address availability...8
0.5 Addressing: Device naming and DNS interaction...8
0.6 Addressing: Name to IP address resolution ...8
0.7 Addressing references ...9
1. Discovery... 10
1.1 Discovery: Advertisement ... 12
1.2 Discovery: Search... 18
1.3 Discovery references... 22
2. Description... 23
2.1 Description: Device description ... 25
2.2 Description: UPnP Device Template ... 30
2.3 Description: Service description ... 30
2.4 Description: UPnP Service Template ... 36
2.5 Description: Non-standard vendor extensions... 37
2.6 Description: UPnP Template Language for devices... 38
2.7 Description: UPnP Template Language for services ... 40
2.8 Description: Retrieving a description... 42
2.9 Description references... 43
3. Control... 45
3.1 Control: Protocols ... 46
3.2 Control: Action... 47
3.3 Control: Query for variable ... 54
3.4 Control references ... 59
4. Eventing ... 60
4.1 Eventing: Subscription ... 62
4.2 Eventing: Event messages ... 68
4.3 Eventing: UPnP Template Language for eventing ... 71
4.4 Eventing: Augmenting the UPnP Template Language ... 72
4.5 Eventing references... 73
5. Presentation... 74
5.1 Presentation references ... 75
Glossary... 76
Introduction
What is UPnP Technology?
UPnP technology defines an architecture for pervasive peer-to-peer network connectivity of intelligent appliances, wireless devices, and PCs of all form factors. It is designed to bring easy-to-use, flexible, standards-based connectivity to ad-hoc or unmanaged networks whether in the home, in a small business, public spaces, or attached to the Internet. UPnP technology provides a distributed, open networking architecture that leverages TCP/IP and the Web technologies to enable seamless proximity networking in addition to control and data transfer among networked devices.
The UPnP Device Architecture (UDA) is more than just a simple extension of the plug and play peripheral model. It is designed to support zero-configuration, "invisible" networking, and automatic discovery for a breadth of device categories from a wide range of vendors. This means a device can dynamically join a network, obtain an IP address, convey its capabilities, and learn about the presence and capabilities of other devices. Finally, a device can leave a network smoothly and automatically without leaving any unwanted state behind.
The technologies leveraged in the UPnP architecture include Internet protocols such as IP, TCP, UDP, HTTP, and XML. Like the Internet, contracts are based on wire protocols that are declarative, expressed in XML, and communicated via HTTP. Using internet protocols is a strong choice for UDA because of its proven ability to span different physical media, to enable real world multiple-vendor interoperation, and to achieve synergy with the Internet and many home and office intranets. The UPnP architecture has been explicitly designed to accommodate these environments. Further, via bridging, UDA accommodates media running non-IP protocols when cost, technology, or legacy prevents the media or devices attached to it from running IP.
What is "universal" about UPnP technology? No device drivers; common protocols are used instead. UPnP networking is media independent. UPnP devices can be implemented using any programming language, and on any operating system. The UPnP architecture does not specify or constrain the design of an API for applications; OS vendors may create APIs that suit their customers’ needs.
UPnP Forum
The UPnP Forum is an industry initiative designed to enable easy and robust connectivity among stand-alone devices and PCs from many different vendors. The UPnP Forum seeks to develop standards for describing device protocols and XML-based device schemas for the purpose of enabling device-to-device interoperability in a scalable networked environment.
The UPnP Implementers Corporation (UIC) is comprised of UPnP Forum member companies across many industries who promote the adoption of uniform technical device interconnectivity standards and testing and certifying of these devices. The UIC develops and administers the testing and certification process, administers the UPnP logo program, and provides information to UIC members and other interested parties regarding the certification of UPnP devices. The UPnP device certification process is
open to any vendor who is a member of the UPnP Forum and UIC, has paid the UIC dues, and has devices that support UPnP functionality. For more information, see http://www.upnp-ic.org.
The UPnP Forum has set up working committees in specific areas of domain expertise. These working committees are charged with creating proposed device standards, building sample implementations, and building appropriate test suites. This document indicates specific technical decisions that are the purview of UPnP Forum working committees.
UPnP vendors can build compliant devices with confidence of interoperability and benefits of shared intellectual property and the logo program. Separate from the logo program, vendors may also build devices that adhere to the UPnP Device Architecture defined herein without a formal standards procedure. If vendors build non-standard devices, they determine technical decisions that would otherwise be determined by a UPnP Forum working committee.
In this document
The UPnP Device Architecture (formerly known as the DCP Framework) contained herein defines the protocols for communication between controllers, or control points, and devices. For discovery, description, control, eventing, and presentation, the UPnP Device Architecture uses the following protocol stack (the indicated colors and type styles are used throughout this document to indicate where each protocol element is defined):
UPnP vendor [purple-italic]
UPnP Forum [red-italic]
UPnP Device Architecture [green-bold]
SSDP [blue] SOAP [blue] GENA [navy-bold]
HTTPMU (multicast) [black] HTTPU (unicast) [black] HTTP [black] HTTP [black]
UDP [black] TCP [black]
IP [black]
At the highest layer, messages logically contain only UPnP vendor-specific information about their devices. Moving down the stack, vendor content is supplemented by information defined by UPnP Forum working committees. Messages from the layers above are hosted in UPnP-specific protocols such as the Simple Service Discovery Protocol (SSDP) and the General Event Notification Architecture (GENA) defined in this document, and others that are referenced. The above messages are delivered via HTTP, either a multicast or unicast variety running over UDP, or the standard HTTP running over TCP. Ultimately, all messages above are delivered over IP. The remaining sections of this document describe the content and format for each of these protocol layers in detail. For reference, colors in [square brackets] above indicate which protocol defines specific message components throughout this document.
Two general classifications of devices are defined by the UPnP architecture: controlled devices (or simply “devices”), and control points. A controlled device functions in the role of a server, responding to requests from control points. Both control points and controlled devices can be implemented on a variety of platforms including personal computers and embedded systems. Multiple devices, control points, or both may be operational on the same network endpoint simultaneously.
The foundation for UPnP networking is IP addressing. Each device must have a Dynamic Host Configuration Protocol (DHCP) client and search for a DHCP server when the device is first connected to the network. If a DHCP server is available, i.e., the network is managed, the device must use the IP address assigned to it. If no DHCP server is available, i.e., the network is unmanaged, the device must use Auto IP to get an address. In brief, Auto IP defines how a device intelligently chooses an IP address from a set of reserved addresses and is able to move easily between managed and unmanaged networks. If during the DHCP transaction, the device obtains a domain name, e.g., through a DNS server or via DNS forwarding, the device should use that name in subsequent network operations; otherwise, the device should use its IP address.
Given an IP address, Step 1 in UPnP networking is discovery. When a device is added to the network, the UPnP discovery protocol allows that device to advertise its services to control points on the network. Similarly, when a control point is added to the network, the UPnP discovery protocol allows that control point to search for devices of interest on the network. The fundamental exchange in both cases is a discovery message containing a few, essential specifics about the device or one of its services, e.g., its type, identifier, and a pointer to more detailed information. The section on Discovery below explains how devices advertise, how control points search, and details of the format of discovery messages.
Step 2 in UPnP networking is description. After a control point has discovered a device, the control point still knows very little about the device. For the control point to learn more about the device and its capabilities, or to interact with the device, the control point must retrieve the device's description from the URL provided by the device in the discovery message. Devices may contain other, logical devices, as well as functional units, or services. The UPnP description for a device is expressed in XML and includes vendor-specific, manufacturer information like the model name and number, serial number, manufacturer name, URLs to vendor-specific Web sites, etc. The description also includes a list of any embedded devices or services, as well as URLs for control, eventing, and presentation. For each service, the description includes a list of the commands, or actions, the service responds to, and parameters, or arguments, for each action; the description for a service also includes a list of variables; these variables model the state of the service at run time, and are described in terms of their data type, range, and event
characteristics. The section on Description below explains how devices are described and how those descriptions are retrieved by control points.
Step 3 in UPnP networking is control. After a control point has retrieved a description of the device, the control point can send actions to a device's service. To do this, a control point sends a suitable control message to the control URL for the service (provided in the device description). Control messages are also expressed in XML using the Simple Object Access Protocol (SOAP).
Like function calls, in response to the control message, the service returns any action-specific values. The effects of the action, if any, are modeled by changes in the variables that describe the run-time state of the service. The section on Control below explains the description of actions, state variables, and the format of control messages.
Step 4 in UPnP networking is eventing. A UPnP description for a service includes a list of actions the service responds to and a list of variables that model the state of the service at run time. The service publishes updates when these variables change, and a control point may subscribe to receive this information. The service publishes updates by sending event messages. Event
messages contain the names of one of more state variables and the current value of those variables. These messages are also expressed in XML. A special initial event message is sent when a control point first subscribes; this event message contains the names and values for all evented variables and allows the subscriber to initialize its model of the state of the service. To support scenarios with multiple control points, eventing is designed to keep all control points equally informed about the effects of any action. Therefore, all subscribers are sent all event messages, subscribers receive event messages for all evented variables that have changed, and event messages are sent no matter why the state variable changed (either in response to a requested action or because the state the service is modeling changed). The section on Eventing below explains subscription and the format of event messages.
Step 5 in UPnP networking is presentation. If a device has a URL for presentation, then the control point can retrieve a page from this URL, load the page into a browser, and depending on the capabilities of the page, allow a user to control the device and/or view device status. The degree to which each of these can be accomplished depends on the specific capabilities of the presentation page and device. The section on Presentation below explains the protocol for retrieving a presentation page.
Audience
The audience for this document includes UPnP device vendors, members of UPnP Forum working committees, and anyone else who has a need to understanding the technical details of UPnP protocols.
This document assumes the reader is familiar with the HTTP, TCP, UDP, IP family of protocols; this document makes no attempt to explain them. This document also assumes most readers will be new to XML, and while it is not an XML tutorial, XML-related issues are addressed in detail given the centrality of XML to the UPnP device architecture. This document makes no assumptions about the reader's understanding of various programming or scripting languages.
Required vs. recommended
In this document, features are described as Required, Recommended, or Optional as follows:
Required (or Must or Shall).
These basic features must be implemented to comply with the UPnP Device Architecture. The phrases “must not” and
“shall not” indicate behavior that is prohibited that if performed means the implementation is not in compliance.
Recommended (or Should).
These features add functionality supported by the UPnP Device Architecture and should be implemented.
Recommended features take advantage of the capabilities of the UPnP Device Architecture, usually without imposing major cost increases. Notice that for compliance testing, if a recommended feature is implemented, it must meet the specified requirements to be in compliance with these guidelines. Some recommended features could become requirements in the future. The phrase “should not” indicates behavior that is permitted but not recommended.
Optional (or May).
These features are neither required nor recommended by the UPnP Device Architecture, but if the feature is implemented, it must meet the specified requirements to be in compliance with these guidelines. These features are not likely to become requirements in the future.
Acronyms
Acronym Meaning
ARP Address Resolution Protocol
CP Control Point
DCP Device Control Protocol
Acronym Meaning
SOAP Simple Object Access Protocol SSDP Simple Service Discovery Protocol UDA UPnP Device Architecture
DHCP Dynamic Host Configuration Protocol DNS Domain Name System
GENA General Event Notification Architecture HTML HyperText Markup Language
HTTP Hypertext Transfer Protocol HTTPMU HTTP (Multicast over UDP) HTTPU HTTP (Unicast over UDP)
UPC Universal Product Code URI Uniform Resource Identifier URL Uniform Resource Locator URN Uniform Resource Name UUID Universally Unique Identifier XML Extensible Markup Language
References and resources RFC 2616
HTTP: Hypertext Transfer Protocol 1.1. <http://www.ietf.org/rfc/rfc2616.txt>.
RFC 2279
UTF-8, a transformation format of ISO 10646 (character encoding). <http://www.ietf.org/rfc/rfc2279.txt>.
XML
Extensible Markup Language. W3C recommendation. <http://www.w3.org/TR/2000/REC-xml-20001006>.
Each section in this document contains additional information about resources for specific topics.
Formatted: English (U.S.) Formatted: English (U.S.) Field Code Changed Formatted: English (U.S.) Field Code Changed Formatted: English (U.S.) Formatted: English (U.S.)
0. Addressing
Addressing is Step 0 of UPnP networking. Through addressing, devices get a network address. Addressing enables discovery (Step 1) where control points find interesting device(s), description (Step 2) where where control points learn about device capabilities, control (Step 3) where a control point sends commands to device(s), eventing (Step 4) where control points listen to state changes in device(s), and presentation (Step 5) where control points display a user interface for device(s).
The foundation for UPnP networking is IP addressing. Each UPnP device which does not itself implement a DHCP server must have a Dynamic Host Configuration Protocol (DHCP) client and search for a DHCP server when the device is first connected to the network (if the device itself implements a DHCP server, it may allocate itself an address from the pool that it controls). If a DHCP server is available, i.e., the network is managed, the device must use the IP address assigned to it. If no DHCP server is available, i.e., the network is unmanaged; the device must use automatic IP addressing (Auto-IP) to obtain an address.
Auto-IP, which is defined in RFC 3927, defines how a device: (a) determines if DHCP is unavailable, and (b) intelligently chooses an IP address from a set of link-local IP addresses. This method of address assignment enables a device to easily move between managed and unmanaged networks.
This section provides an overview of the basic operation of Auto-IP. The operations described in this section are detailed and clarified in the reference documents listed below. Where conflicts between this document and the reference documents exist, the reference document always takes precedence.
0.1 Addressing: Determining whether to use Auto-IP
A device that supports Auto-IP and is configured for dynamic address assignment begins by requesting an IP address via DHCP by sending out a DHCPDISCOVER message. The amount of time this DHCP Client should listen for DHCPOFFERs is implementation dependent. If a DHCPOFFER is received during this time, the device must continue the process of dynamic address assignment. If no valid DHCPOFFERs are received, the device may then auto-configure an IP address.
0.2 Addressing: Choosing an address
To auto-configure an IP address using Auto-IP, the device uses an implementation-dependent algorithm for choosing an address in the 169.254/16 range. The first and last 256 addresses in this range are reserved and must not be used.
The selected address must then be tested to determine if the address is already in use. If the address is in use by another device, another address must be chosen and tested, up to an implementation dependent number of retries. The address selection should be randomized to avoid collision when multiple devices are attempting to allocate addresses. It is recommended that the device choose an address using a pseudo-random algorithm (distributed over the entire address range from 169.254.1.0 to
169.254.254.255) to minimize the likelihood that devices that join the network at the same time will choose the same address
and subsequently choose alternative addresses in the same sequence when collisions are detected. This pseudo-random algorithm may be seeded using the device’s Ethernet hardware MAC address.
0.3 Addressing: Testing the address
To test the chosen address, the device must use an Address Resolution Protocol (ARP) probe. An ARP probe is an ARP request with the device hardware address used as the sender's hardware address and the sender's IP address set to 0s. The device will then listen for responses to the ARP probe, or other ARP probes for the same IP address. If either of these ARP packets is seen, the device must consider the address in use and try a different address. The ARP probe may be repeated for greater certainty that the address is not already in use; it is recommended that the probe be sent four times at two-second intervals.
After successfully configuring a link-local address, the device should send two gratuitous ARPs, spaced two seconds apart, this time filling in the sender IP address. The purpose of these gratuitous ARPs is to make sure that other hosts on the net do not have stale ARP cache entries left over from some other host that may previously have been using the same address.
Devices that are equipped with persistent storage may record the IP address they have selected and on the next boot use that address as their first candidate when probing, in order to increase the stability of addresses and reduce the need to resolve address conflicts.
Address collision detection is not limited to the address testing phase, when the device is sending ARP probes and listening for replies. Address collision detection is an ongoing process that is in effect for as long as the device is using a link-local address. At any time, if a device receives an ARP packet with its own IP address given as the sender IP address, but a sender hardware address that does not match its own hardware address, then the device must treat this as an address collision and must respond as described in either (a) or (b) below:
(a) Immediately configure a new link-local IP address as described above; or,
(b) If the device currently has active TCP connections or other reasons to prefer to keep the same IP address, and has not seen any other conflicting ARP packets recently (e.g., within the last ten seconds) then it may elect to attempt to defend its address once, by recording the time that the conflicting ARP packet was received, and then broadcasting one single gratuitous ARP, giving its own IP and hardware addresses as the source addresses of the ARP. However, if another conflicting ARP packet is received within a short time after that (e.g., within ten seconds) then the device must immediately configure a new Auto-IP address as described above.
The device must respond to conflicting ARP packets as described in either (a) or (b) above; it must not ignore conflicting ARP packets. If a new address is selected, the device must cancel previous advertisements and re-advertise with the new address.
After successfully configuring an Auto-IP address, all subsequent ARP packets (replies as well as requests) containing an Auto-IP source address should be sent using link-level broadcast instead of link-level unicast, in order to facilitate timely detection of
duplicate addresses. As an alternative, a device which cannot send broadcast ARP replies should send a unicast ARP reply but then neglect to follow the instructions in RFC 826 about recording sender information from received ARP requests. This means that, having failed to record the sender information, the device is likely to send a broadcast ARP request of its own shortly later, which allows another device using the same IP address to detect the conflict and respond to it.
IP packets whose source or destination addresses are in the 169.254/16 range must not be sent to any router for forwarding. IP datagrams with a multicast destination address and an Auto-IP source address should not be forwarded off the local link. Devices and control points may assume that all 169.254/16 destination addresses are on-link and directly reachable. The 169.254/16 address range MUST NOT be subnetted.
0.4 Addressing: Periodic checking for dynamic address availability
A device that has auto-configured an IP address must periodically check for the existence of a DHCP server. This is accomplished by sending DHCPDISCOVER messages. How often this check is made is implementation dependent, but checking every 5 minutes would maintain a balance between network bandwidth required and connectivity maintenance. If a DHCPOFFER is received, the device must proceed with dynamic address allocation. Once a DHCP assigned address is in place, the device may release the auto-configured address, but may also choose to maintain this address for a period of time (or indefinitely) to maintain connectivity.
To switch over from one IP address to a new one, the device should, if possible, cancel any outstanding advertisements made on the previous address and reissue new advertisements on the new address. The section on Discovery explains advertisements and their cancellations.
0.5 Addressing: Device naming and DNS interaction
Once a device has a valid IP address for the network, it can be located and referenced on that network through that address.
There may be situations where the end user needs to locate and identify a device. In these situations, a friendly name for the device is much easier for a human to use than an IP address. If a UPnP device chooses to provide a host name to a DHCP server and register with a DNS server, the device should either ensure the requested host name is unique or provide a means for the user to change the requested host name. Most often, UPnP devices do not provide a host name, but provide URLs using literal (numeric) IP addresses.
Moreover, names are much more static than IP addresses. Clients referring a device by name don't require any modification when the IP address of a device changes. Mapping of the device's DNS name to its IP address could be entered into DNS database manually or dynamically according to RFC 2136. While devices supporting dynamic DNS updates can register their DNS records directly in DNS, it is also possible to configure a DHCP server to register DNS records on behalf of these DHCP clients.
0.6 Addressing: Name to IP address resolution
A device that needs to contact another device identified by a DNS name needs to discover its IP address. The device submits a DNS query according to RFC1034 and 1035 to the pre-configured DNS server(s) and receives a response from a DNS server
containing the IP address of the target device. A device can be statically pre-configured with the list of DNS servers.
Alternatively a device could be configured with the list of DNS server through DHCP, or after the address assignment through a DHCPINFORM message.
0.7 Addressing references RFC1034
Domain Names - Concepts and Facilities. <http://www.ietf.org/rfc/rfc1034.txt>.
RFC1035
Domain Names - Implementation and Specification. <http://www.ietf.org/rfc/rfc1035.txt>.
RFC 2131
Dynamic Host Configuration Protocol. <http://www.ietf.org/rfc/rfc2131.txt>.
RFC 2136
Dynamic Updates in the Domain Name System. <http://www.ietf.org/rfc/rfc2136.txt>.
RFC 3927
Dynamic Configuration of IPv4 Link-Local Addresses. <http://www.ietf.org/rfc/rfc3927.txt>.
1. Discovery
Discovery is Step 1 in UPnP networking. Discovery comes after addressing (Step 0) where devices get a network address. Through discovery, control points find interesting device(s). Discovery enables description (Step 2) where control points learn about device capabilities, control (Step 3) where a control point sends commands to device(s), eventing (Step 4) where control points listen to state changes in device(s), and presentation (Step 5) where control points display a user interface for device(s).
Discovery is the first step in UPnP networking. When a device is added to the network, the UPnP discovery protocol allows that device to advertise its services to control points on the network. Similarly, when a control point is added to the network, the UPnP discovery protocol allows that control point to search for devices of interest on the network. The fundamental exchange in both cases is a discovery message containing a few, essential specifics about the device or one of its services, e.g., its type, universally unique identifier, and a pointer to more detailed information.
When a new device is added to the network, it multicasts a number of discovery messages advertising itself, its embedded devices, and its services. Any interested control point can listen to the standard multicast address for notifications that new capabilities are available.
Similarly, when a new control point is added to the network, it multicasts a discovery message searching for interesting devices, services, or both. All devices must listen to the standard multicast address for these messages and must respond if any of their embedded devices or services match the search criteria in the discovery message.
To reiterate, a control point may learn of a device of interest because that device sent discovery messages advertising itself or because the device responded to a discovery message searching for devices. In either case, if a control point is interested in a device and wants to learn more about it, the control point uses the information in the discovery message to send a description query message. The section on Description explains description messages in detail.
When a device is removed from the network, it should, if possible, multicast a number of discovery messages revoking its earlier announcements, effectively declaring that its embedded devices and services will no longer be available. When the IP address of a device is changed, it should revoke any earlier announcements and advertise using the new IP address.
For devices and control points that have multiple network interfaces, UPnP advertisements and searches should be sent on all network interfaces enabled for UPnP networking. Each advertisement or search must specify an address in the LOCATION header that is reachable on that interface
To limit network congestion, the time-to-live (TTL) of each IP packet for each multicast message should default to 4 and should be configurable. When the TTL is greater than 1, it is possible for multicast messages to traverse multiple routers; therefore control points and devices using non-AutoIP addresses must send an IGMP Join message so that routers will forward multicast messages to them (this is not necessary when using an Auto-IP address, since packets with Auto-IP addresses will not be forwarded by routers).
Discovery plays an important role in the interoperability of devices and control points using different versions of UPnP networking.
The UPnP Device Architecture (defined herein) is versioned with both a major and a minor version, usually written as major.minor, where both major and minor are integers (for example, version 2.10 [two dot ten] is newer than version 2.2 [two dot two]). Advances in minor versions must be a compatible superset of earlier minor versions of the same major version.
Advances in major version are not required to be supersets of earlier versions and are not guaranteed to be backward compatible.
Version information is communicated in discovery and description messages. In the former, each discovery message includes the version of UPnP networking that the device supports (in the SERVER header); the version of device and service types supported is also included in relevant discovery messages. As a backup, the latter also includes the same information. This section explains the format of version information in discovery messages and specific requirements on discovery messages to maintain compatibility with advances in minor versions.
The remainder of this section explains the UPnP discovery protocol known as SSDP (Simple Service Discovery Protocol) in detail, enumerating how devices advertise and revoke their advertisements as well as how control points search and devices respond.
1.1 Discovery: Advertisement
When a device is added to the network, the device advertises its services to control points. It does this by multicasting discovery messages to a standard address and port (239.255.255.250:1900). Control points listen to this port to detect when new capabilities are available on the network. To advertise the full extent of its capabilities, a device multicasts a number of discovery messages corresponding to each of its embedded devices and services. Each message contains information specific to the embedded device (or service) as well as information about its enclosing device. Messages should include duration until the advertisements expire; if the device remains available, the advertisements should be re-sent (with new duration). If the device becomes unavailable, the device should explicitly cancel its advertisements, but if the device is unable to do this, the advertisements will expire on their own.
1.1.1 Discovery: Advertisement protocols and standards
To send (and receive) advertisements, devices (and control points) use the following subset of the overall UPnP protocol stack.
(The overall UPnP protocol stack is listed at the beginning of this document.)
UPnP vendor [purple]
UPnP Forum [red]
UPnP Device Architecture [green]
SSDP [blue]
HTTPMU (multicast) [black]
UDP [black]
IP [black]
At the highest layer, discovery messages contain vendor-specific information, e.g., URL for the device description and device identifier. Moving down the stack, vendor content is supplemented by information from a UPnP Forum working committee, e.g., device type. Messages from the layers above are hosted in UPnP-specific protocols, defined in this document. In turn, the above messages are delivered via a multicast variant of HTTP extended using additional methods and headers. The HTTP messages are delivered via UDP over IP. For reference, colors in [square brackets] above indicate which protocol defines specific headers and values in discovery messages listed below.
1.1.2 Discovery: Advertisement: Device available -- NOTIFY with ssdp:alive
When a device is added to the network, it multicasts discovery messages to advertise its root device, any embedded devices, and any services. Each discovery message contains four major components:
1. a potential search target (e.g., device type), sent in an NT (Notification Type) header,
2. a composite identifier for the advertisement, sent in a USN (Unique Service Name) header,
3. a URL for more information about the device (or enclosing device in the case of a service), sent in a LOCATION header, and
4. a duration for which the advertisement is valid, sent in a CACHE-CONTROL header.
To advertise its capabilities, a device multicasts a number of discovery messages. Specifically, a root device must multicast:
• Three discovery messages for the root device.
NT USN *
1 upnp:rootdevice uuid:device-UUID::upnp:rootdevice 2 uuid:device-UUID ** uuid:device-UUID (for root device UUID) 3 urn:schemas-upnp-org:device:deviceType:v or
urn:domain-name:device:deviceType:v uuid:device-UUID::urn:schemas-upnp-org:device:deviceType:v (of root device) or uuid:device-UUID::urn:domain-name:device:deviceType:v
• Two discovery messages for each embedded device.
NT USN *
1 uuid:device-UUID ** uuid:device-UUID
2 urn:schemas-upnp-org:device:deviceType:v or
urn:domain-name:device:deviceType:v uuid:device-UUID::urn:schemas-upnp-org:device:deviceType:v or uuid:device-UUID::urn:domain-name:device:deviceType:v
• Once for each service type in each device.
NT USN *
1 urn:schemas-upnp-org:service:serviceType:v or
urn:domain-name:service:serviceType:v uuid:device-UUID::urn:schemas-upnp-org:service:serviceType:v or uuid:device-UUID::urn:domain-name:service:serviceType:v
* Note that the prefix of the USN header (before the double colon) must match the value of the UDN element in the device description. (The section on Description explains the UDN element.)
** Note that the value of this NT header must match the value of the UDN element in the device description.
If a root device has d embedded devices and s embedded services but only k distinct service types, this works out to 3+2d+k requests. If a particular device or embedded device contains multiple instances of a particular service type, it is only necessary to advertise the service type once (rather than once for each instance). This advertises the full extent of the device's capabilities to interested control points. These messages must be sent out as a series with roughly comparable expiration times; order is unimportant, but refreshing or canceling individual messages is prohibited.
Updated UPnP device and service types are required to be fully backward compatible with previous versions of the same type.
Devices must advertise the highest supported version of each supported type. For example, if a device supports version 2 of the
“Audio” service, it would advertise only version 2, even though it also supports version 1. Control points that support a given version of a device or service are able to also interact with higher versions because of this backward compatibility requirement, but only using the functionality that was defined in the lower version. For example, if a control point supports only version “1” of the “Audio” service, and a device advertises that it supports version “2” of the “Audio” service, the control point should recognize and be able to use the device.
Choosing an appropriate duration for advertisements is a balance between minimizing network traffic and maximizing freshness of device status. Relatively short durations close to the minimum of 1800 seconds will ensure that control points have current device status at the expense of additional network traffic; longer durations, say on the order of a day, compromise freshness of device status but can significantly reduce network traffic. Generally, device vendors should choose a value that corresponds to expected device usage: short durations for devices that are expected to be part of the network for short periods of time, and significantly longer durations for devices expected to be long-term members of the network. Devices that frequently connect to and leave the network (such as mobile wireless devices) should use a shorter duration so that control points have a more accurate view of their availability. Advertisements in the initial set should have comparable durations and the entire set should be sent as quickly as possible. Subsequent refreshments of the advertisements may be spread over time rather than being sent as a group.
Devices should wait a random interval less than 100 milliseconds before sending an initial set of advertisements in order to reduce the likelihood of network storms; this random interval should also be applied on occasions where the device obtains a new IP address or a new network interface is installed.
Due to the unreliable nature of UDP, devices should send each of the above discovery messages more than once, although to avoid network congestion discovery messages should not be sent more than three times. In addition, the device must re-send its advertisements periodically prior to expiration of the duration specified in the CACHE-CONTROL header; it is recommended that such refreshing of advertisements be done at a randomly-distributed interval of less than one-half of the advertisement expiration time, so as to provide the opportunity for recovery from lost advertisements before the advertisement expires, and to distribute over time the advertisement refreshment of multiple devices on the network in order to avoid spikes in network traffic.
Note that UDP packets are also bounded in length (perhaps as small as 512 Bytes in some implementations); each discovery message must fit entirely in a single UDP packet. There is no guarantee that the above 3+2d+k messages will arrive in a particular order.
When a device is added to the network, it must send a multicast request with method NOTIFY and ssdp:alive in the NTS header in the following format. Values in italics are placeholders for actual values.
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
SERVER: OS/version UPnP/1.0 product/version USN: advertisement UUID
(No body for request with method NOTIFY, but note that the message must have a blank line following the last HTTP header.)
The TTL for the IP packet should default to 4 and should be configurable.
Listed below are details for the request line and headers appearing in the listing above. All header values are case sensitive except where noted.
Request line NOTIFY
Method for sending notifications and events.
*
Request applies generally and not to a specific resource. Must be *.
HTTP/1.1
HTTP version.
Headers HOST
Required. Multicast channel and port reserved for SSDP by Internet Assigned Numbers Authority (IANA). Must be 239.255.255.250:1900. If the port number (“:1900”) is omitted, the receiver should assume the default SSDP port number of 1900.
CACHE-CONTROL
Required. Must have max-age directive that specifies number of seconds the advertisement is valid. After this duration, control points should assume the device (or service) is no longer available. Should be greater than or equal to 1800 seconds (30 minutes). Specified by UPnP vendor. Integer.
LOCATION
Required. Contains a URL to the UPnP description of the root device. Normally the host portion contains a literal IP address rather than a domain name in unmanaged networks. Specified by UPnP vendor. Single URL.
NT Required. Notification Type. Must be one of the following. (cf. table above.) Single URI.
upnp:rootdevice
Sent once for root device.
uuid:device-UUID
Sent once for each device, root or embedded. Device UUID specified by UPnP vendor.
urn:schemas-upnp-org:device:deviceType:v
Sent once for each device, root or embedded. Device type and version defined by UPnP Forum working committee. Specifies the highest supported version of the device type.
urn:schemas-upnp-org:service:serviceType:v
Sent once for each service. Service type and version defined by UPnP Forum working committee. Specifies the highest supported version of the service type.
urn:domain-name:device:deviceType:v
Sent once for each device, root or embedded. Domain name, device type and version defined by UPnP vendor.
Specifies the highest supported version of the device type. Period characters in the domain name must be replaced with hyphens in accordance with RFC 2141.
urn:domain-name:service:serviceType:v
Sent once for each service. Domain name, service type and version defined by UPnP vendor. Specifies the highest supported version of the service type. Period characters in the domain name must be replaced with hyphens in accordance with RFC 2141.
NTS
Required. Notification Sub Type. Must be ssdp:alive. Single URI.
SERVER
Required. Concatenation of OS name, OS version, UPnP/1.0, product name, and product version. Specified by UPnP vendor. String. Must accurately reflect the version number of the UPnP Device Architecture supported by the device.
Control points must be prepared to accept a higher minor version number than the control point itself implements. For example, control points implementing UDA version 1.0 will be able to interoperate with devices implementing UDA version 1.1.
USN
Required. Unique Service Name. Identifies a unique instance of a device or service. Must be one of the following. (cf.
table above.) The prefix (before the double colon) must match the value of the UDN element in the device description.
(The section on Description explains the UDN element.) Single URI.
uuid:device-UUID::upnp:rootdevice
Sent once for root device. Device UUID specified by UPnP vendor.
uuid:device-UUID
Sent once for every device, root or embedded. Device UUID specified by UPnP vendor.
uuid:device-UUID::urn:schemas-upnp-org:device:deviceType:v
Sent once for every device, root or embedded. Device UUID specified by UPnP vendor. Device type and version defined by UPnP Forum working committee. Specifies the highest supported version of the device type.
uuid:device-UUID::urn:schemas-upnp-org:service:serviceType:v
Sent once for every service. Device UUID specified by UPnP vendor. Service type and version defined by UPnP Forum working committee. Specifies the highest support version of the service type.
uuid:device-UUID::urn:domain-name:device:deviceType:v
Sent once for every device, root or embedded. Device UUID, domain name, device type and version defined by UPnP vendor. Specifies the highest supported version of the device type. Period characters in the domain name must be replaced by hyphens in accordance with RFC 2141.
uuid:device-UUID::urn:domain-name:service:serviceType:v
Sent once for service. Device UUID, domain name, service type and version defined by UPnP vendor. Specifies the highest supported version of the device type. Period characters in the domain name must be replaced by hyphens in accordance with RFC 2141.
(No response for a request with method NOTIFY.)
1.1.3 Discovery: Advertisement: Device unavailable -- NOTIFY with ssdp:byebye
When a device and its services are going to be removed from the network, the device should multicast a ssdp:byebye message corresponding to each of the ssdp:alive messages it multicasted that have not already expired. If the device is removed abruptly from the network, it might not be possible to multicast a message. As a fallback, discovery messages must include an expiration value in a CACHE-CONTROL header (as explained above); if not re-advertised, the discovery message eventually expires on its own and must be removed from any control point cache.
(Note: when a control point is about to be removed from the network, no discovery-related action is required.)
When a device is about to be removed from the network, it should explicitly revoke its discovery messages by sending one multicast request for each ssdp:alive message it sent. Each multicast request must have method NOTIFY and ssdp:byebye in the NTS header in the following format. Values in italics are placeholders for actual values.
NOTIFY * HTTP/1.1
HOST: 239.255.255.250:1900 NT: search target
NTS: ssdp:byebye
USN: uuid:advertisement UUID
(No body for request with method NOTIFY, but note that the message must have a blank line following the last HTTP header.)
The TTL for the IP packet should default to 4 and should be configurable.
Listed below are details for the request line and headers appearing in the listing above. All header values are case sensitive except where noted.
Request line NOTIFY
Method for sending notifications and events.
*
Request applies generally and not to a specific resource. Must be *.
HTTP/1.1
HTTP version.
Headers HOST
Required. Multicast channel and port reserved for SSDP by Internet Assigned Numbers Authority (IANA). Must be 239.255.255.250:1900. If the port number (“:1900”) is omitted, the receiver should assume the default SSDP port number of 1900.
NT
Required. Notification Type. (See list of required values for NT header in NOTIFY with ssdp:alive above.) Single URI.
NTS
Required. Notification Sub Type. Must be ssdp:byebye. Single URI.
USN
Required. Unique Service Name. (See list of required values for USN header in NOTIFY with ssdp:alive above.) Single URI.
(No response for a request with method NOTIFY.)
Due to the unreliable nature of UDP, devices should send each of the above messages more than once. As a fallback, if a control point fails to receive notification that a device or services is unavailable, the original discovery message will eventually expire yielding the same effect.
1.2 Discovery: Search
When a control point is added to the network, the UPnP discovery protocol allows that control point to search for devices of interest on the network. It does this by multicasting on the reserved address and port (239.255.255.250:1900) a search message with a pattern, or target, equal to a type or identifier for a device or service. Responses from devices contain discovery messages essentially identical to those advertised by newly connected devices; the former are unicast while the latter are multicast.
1.2.1 Discovery: Search protocols and standards
To search for devices (and be discovered by control points), control points (and devices) use the following subset of the overall UPnP protocol stack. (The overall UPnP protocol stack is listed at the beginning of this document.)
UPnP vendor [purple]
UPnP Forum [red]
UPnP Device Architecture [green]
SSDP [blue]
HTTPU (unicast) [black] HTTPMU (multicast) [black]
UDP [black]
IP [black]
At the highest layer, search messages contain vendor-specific information, e.g., the control point, device, and service identifiers.
Moving down the stack, vendor content is supplemented by information from a UPnP Forum working committee, e.g., device or service types. Messages from the layers above are hosted in UPnP-specific protocols, defined in this document. In turn, search requests are delivered via a multicast variant of HTTP that has been extended using additional methods and headers. Search responses are delivered via a unicast variant of HTTP that has also been extended. Both kinds of HTTP messages are delivered via UDP over IP. For reference, colors in [square brackets] above indicate which protocol defines specific headers and values in discovery messages listed below.
1.2.2 Discovery: Search: Request with M-SEARCH
When a control point is added to the network, it should send a multicast request with method M-SEARCH in the following format.
Values in italics are placeholders for actual values.
M-SEARCH * HTTP/1.1 HOST: 239.255.255.250:1900 MAN: "ssdp:discover"
MX: seconds to delay response ST: search target
(No body for request with method M-SEARCH, but note that the message must have a blank line following the last HTTP header.)
The TTL for the IP packet should default to 4 and should be configurable.
Listed below are details for the request line and headers appearing in the listing above. All header values are case sensitive except where noted.
Request line M-SEARCH
Method for search requests.
*
Request applies generally and not to a specific resource. Must be *.
HTTP/1.1
HTTP version.
Headers HOST
Required. Multicast channel and port reserved for SSDP by Internet Assigned Numbers Authority (IANA). Must be 239.255.255.250:1900. If the port number (“:1900”) is omitted, the receiver should assume the default SSDP port number of 1900.
MAN
Required by HTTP Extension Framework. Unlike the NTS and ST headers, the value of the MAN header is enclosed in double quotes; it defines the scope (namespace) of the extension. Must be "ssdp:discover".
MX
Required. Maximum wait time in seconds. Should be between 1 and 120 inclusive. Device responses should be delayed a random duration between 0 and this many seconds to balance load for the control point when it processes responses.
This value may be increased if a large number of devices are expected to respond. The MX value should not be increased to accommodate network characteristics such as latency or propagation delay (for more details, see the explanation below). Specified by UPnP vendor. Integer.
ST
Required. Search Target. Must be one of the following. (cf. NT header in NOTIFY with ssdp:alive above.) Single URI.
ssdp:all
Search for all devices and services.
upnp:rootdevice
Search for root devices only.
uuid:device-UUID
Search for a particular device. Device UUID specified by UPnP vendor.
urn:schemas-upnp-org:device:deviceType:v
Search for any device of this type. Device type and version defined by UPnP Forum working committee.
urn:schemas-upnp-org:service:serviceType:v
Search for any service of this type. Service type and version defined by UPnP Forum working committee.
urn:domain-name:device:deviceType:v
Search for any device of this type. Domain name, device type and version defined by UPnP vendor. Period characters in the domain name must be replaced with hyphens in accordance with RFC 2141.
urn:domain-name:service:serviceType:v
Search for any service of this type. Domain name, service type and version defined by UPnP vendor. Period characters in the domain name must be replaced with hyphens in accordance with RFC 2141.
Due to the unreliable nature of UDP, control points should send each M-SEARCH message more than once. As a fallback, to guard against the possibility that a device might not receive the M-SEARCH message from a control point, a device should re-send its advertisements periodically (cf. CACHE-CONTROL header in NOTIFY with ssdp:alive above).
The control point should wait at least the amount of time specified in the MX header for responses to arrive from devices. The random distribution of responses over the MX interval means that a responder may send a response at MX seconds after receiving the M-SEARCH request. The MX value may be adjusted by heuristics at the requester based on, for example, observed number of responders. Network characteristics affecting the propagation of traffic cannot be addressed by increasing the MX value because of the reason cited above. A requester may adapt to network characteristics with heuristics based on observed network behavior
(the exact heuristics are out of scope). The net effect is that the M-SEARCH request persists at the requester for a period of time exceeding MX such that the characteristics of the network are properly accommodated to minimize lost responses.
Updated versions of device and service types are required to be fully backward compatible with previous versions. Devices must respond to M-SEARCH requests for any supported version. For example, if a device implements “urn:schemas-upnp-
org:service:Audio:2”, it should respond to search requests for both that type and “urn:schemas-upnp-org:service:Audio:1”. The response should specify the same version as was contained in the search request. If a control point searches for a device or service of a particular version and receives no responses (presumably because no device present on the network supports the specified version), but is willing to operate using a lower version, it may repeat the search request specifying the lower version.
1.2.3 Discovery: Search: Response
To be found, a device must send a UDP response to the source IP address and port that sent the request to the multicast channel. Devices respond if the ST header of the M-SEARCH request is “ssdp:all”, “upnp:rootdevice”, “uuid:” followed by a UUID that exactly matches one advertised by the device.
Devices should wait a random period of time between 0 seconds and the number of seconds specified in the MX header of the search request before responding, in order to avoid flooding the requesting control point with search responses from multiple devices. If the search request results in the need for multiple responses from the device, those responses should be spread at random intervals through the time period from 0 to the number of seconds specified in the MX header. If the search request does not contain an MX header, the device must silently discard and ignore the search request. Devices may assume an MX value less than that specified in the MX header. If the MX header specifies a value greater than 120, the device should assume that it contained the value 120 or less. Devices should not stop responding to other requests while waiting the random delay before sending a response.
The URL specified in the LOCATION header of the M-SEARCH response must be reachable by the control point to which the response is directed.
Responses to M-SEARCH are intentionally parallel to advertisements, and as such, follow the same pattern as listed for NOTIFY with ssdp:alive (above) except that the NT header there is an ST header here. The response must be sent in the following format.
Values in italics are placeholders for actual values.
HTTP/1.1 200 OK
CACHE-CONTROL: max-age = seconds until advertisement expires DATE: when response was generated
EXT:
LOCATION: URL for UPnP description for root device SERVER: OS/version UPnP/1.0 product/version
ST: search target USN: advertisement UUID
(No body for a response to a request with method M-SEARCH, but note that the message must have a blank line following the last HTTP header.)
(No need to limit TTL for the IP packet in response to a search request.)
Listed below are details for the headers appearing in the listing above. All header values are case sensitive except where noted.
Headers CACHE-CONTROL
Required. Must have max-age directive that specifies number of seconds the advertisement is valid. After this duration, control points should assume the device (or service) is no longer available. Should be greater than or equal to 1800 seconds (30 minutes), although exceptions are defined in the text above. Specified by UPnP vendor. Integer.
DATE
Recommended. When response was generated. “rfc1123-date” as defined in RFC 2616.
EXT
Required by HTTP Extension Framework. Confirms that the MAN header was understood. (Header only; no value.) LOCATION
Required. Contains a URL to the UPnP description of the root device. Normally the host portion contains a literal IP address rather than a domain name in unmanaged networks. Specified by UPnP vendor. Single URL.
SERVER
Required. Concatenation of OS name, OS version, UPnP/1.0, product name, and product version. Specified by UPnP vendor. String. Must accurately reflect the version number of the UPnP Device Architecture supported by the device.
Control points must be prepared to accept a higher version number than the control point itself implements. For example, control points implementing UDA version 1.0 will be able to interoperate with devices implementing UDA version 1.1.
ST Required. Search Target. Single URI. If ST header in request was, ssdp:all
Respond 3+2d+k times for a root device with d embedded devices and s embedded services but only k distinct service types (see section 1.1.2 for a definition of each message to be sent). Value for ST header must be the same as for the NT header in NOTIFY messages with ssdp:alive. (See above.) Single URI.
upnp:rootdevice
Respond once for root device. Must be upnp:rootdevice. Single URI.
uuid:device-UUID
Respond once for each matching device, root or embedded. Must be uuid:device-UUID. Device UUID specified by UPnP vendor. Single URI.
urn:schemas-upnp-org:device:deviceType:v
Respond once for each matching device, root or embedded. Must be urn:schemas-upnp-
org:device:deviceType:v. Device type and version defined by UPnP Forum working committee. Should specify the version of the device type contained in the M-SEARCH request.
urn:schemas-upnp-org:service:serviceType:v
Respond once for each matching service type. Must be urn:schemas-upnp-org:service:serviceType:v. Service type and version defined by UPnP Forum working committee. Should specify the version of the service type contained in the M-SEARCH request.
urn:domain-name:device:deviceType:v
Respond once for each matching device, root or embedded. Domain name, device type and version defined by UPnP vendor. Period characters in the domain name must be replaced with hyphens in accordance with RFC 2141. Should specify the version of the device type specified in the M-SEARCH request.
urn:domain-name:service:serviceType:v
Respond once for each matching service type. Domain name, service type and version defined by UPnP vendor. Period characters in the domain name must be replaced with hyphens in accordance with RFC 2141.
Should specify the version of the service type contained in the M-SEARCH request.
USN
Required. Unique Service Name. (See list of required values for USN header in NOTIFY with ssdp:alive above.) Single URI.
If there is an error with the search request (such as an invalid value in the MAN header, a missing MX header, or other malformed content), the device should silently discard and ignore the search request; sending of error responses is not recommended due to the possibility of packet storms if many devices send an error response to the same request.
1.3 Discovery references RFC 2141
URN Syntax. <http://www.ietf.org/rfc/rfc2141.txt>.
RFC 2616
HTTP: Hypertext Transfer Protocol 1.1. <http://www.ietf.org/rfc/rfc2616.txt>.
RFC 2774
HTTP Extension Framework. <http://www.ietf.org/rfc/rfc2774.txt>.
2. Description
Description is Step 2 in UPnP networking. Description comes after addressing (Step 0) where devices get a network address, and after discovery (Step 1) where control points find interesting device(s). Description enables control (Step 3) where control points send commands to device(s), eventing (Step 4) where control points listen to state changes in device(s), and presentation (Step 5) where control points display a user interface for device(s).
After a control point has discovered a device, the control point still knows very little about the device -- only the information that was in the discovery message, i.e., the device's (or service's) UPnP type, the device's universally-unique identifier, and a URL to the device's UPnP description. For the control point to learn more about the device and its capabilities, or to interact with the device, the control point must retrieve a description of the device and its capabilities from the URL provided by the device in the discovery message.
The UPnP description for a device is partitioned into two, logical parts: a device description describing the physical and logical containers, and service descriptions describing the capabilities exposed by the device. A UPnP device description includes vendor-specific, manufacturer information like the model name and number, serial number, manufacturer name, URLs to vendor- specific Web sites, etc. (details below). For each service included in the device, the device description lists the service type, name, a URL for a service description, a URL for control, and a URL for eventing. A device description also includes a description of all embedded devices and a URL for presentation of the aggregate. This section explains UPnP device descriptions, and the sections on Control, Eventing, and Presentation explain how URLs for control, eventing, and presentation are used, respectively.
Note that a single physical device may include multiple logical devices. Multiple logical devices can be modeled as a single root device with embedded devices (and services) or as multiple root devices (perhaps with no embedded devices). In the former case,
there is one UPnP device description for the root device, and that device description contains a description for all embedded devices. In the latter case, there are multiple UPnP device descriptions, one for each root device.
A UPnP device description is written by a UPnP vendor. The description is in XML syntax and is usually based on a standard UPnP Device Template. A UPnP Device Template is produced by a UPnP Forum working committee; they derive the template from the UPnP Template Language, which was derived from standard constructions in XML. This section explains the format for a UPnP device description, UPnP Device Templates, and the part of the UPnP Template Language that covers devices.
A UPnP service description includes a list of commands, or actions, the service responds to, and parameters, or arguments, for each action. A service description also includes a list of variables. These variables model the state of the service at run time, and are described in terms of their data type, range, and event characteristics. This section explains the description of actions, arguments, state variables, and the properties of those variables. The section on Eventing explains event characteristics.
Like a UPnP device description, a UPnP service description is written by a UPnP vendor. The description is in XML syntax and is usually based on a standard UPnP Service Template. A UPnP Service Template is produced by a UPnP Forum working committee;
they derived the template from the UPnP Template Language, augmenting it with human language where necessary. The UPnP Template Language is derived from standard constructions in XML. This section explains the format for a UPnP service description, UPnP Service Templates, typical augmentations in human language, and the part of the UPnP Template Language that covers services.
UPnP vendors can differentiate their devices by extending services, including additional UPnP services, or embedding additional devices. When a control point retrieves a particular device's description, these added features are exposed to the control point for control and eventing. The device and service descriptions authoritatively document the implementation of the device.
Retrieving a UPnP device description is simple: the control point issues an HTTP GET request on the URL in the discovery message, and the device returns the device description. Retrieving a UPnP service description is a similar process that uses a URL within the device description. The protocol stack, method, headers, and body for the response and request are explained in detail below.
As long as the discovery advertisements from a device have not expired, a control point may assume that the device and its services are available. The device and service descriptions may be retrieved at any point since the device and service descriptions are static as long as the device and its services are available. If a device cancels its advertisements or if the advertisements expire, a control point should assume the device and its services are no longer available. If a device needs to change one of these descriptions, it must cancel its outstanding advertisements and re-advertise. Consequently, control points should not assume that device and service descriptions are unchanged if a device re-appears on the network.
Like discovery, description plays an important role in the interoperability of devices and control points using different versions of UPnP networking. As explained in the section on Discovery, the UPnP Device Architecture is versioned with both a major and a
minor version. The major version and minor version are separate integer numbers; they are not to be interpreted or compared as though they were a single decimal number, even though they may appear as such in print. Advances in minor versions must be a compatible superset of earlier minor versions of the same major version. Advances in major version are not required to be supersets of earlier versions and are not guaranteed to be backward compatible. Version information is communicated in description messages as a backup to the information communicated in discovery messages. This section explains the format of version information in description messages.
Device and service types standardized by UPnP Forum working committees or created by vendors have an integer version. Every later version of a device or service must be a fully backwardly compatible superset of the previous version, i.e., compared to earlier versions of the device, it must include all embedded devices and services of the same or later version. The UPnP device or service type remains the same across all versions of a device whereas the device or service version must be larger for later versions. Versions of device and service templates may have non-integer versions (such as “0.9”) during development in the working committee, but this must become an integer upon standardization. Devices and services may have a version number greater than the major version number of the architecture they are designed for (e.g., “Power:2” may be designed to work on UDA version 1.0); there is no direct correlation between the version of a device or service template and the architecture version with which it is designed to work. If a non-backward-compatible version of a device or service is defined, it must have a different device or service name to indicate that it is not backwardly compatible (and version numbers of the new type should restart at 1).
UPnP device and service types are “building blocks” that may be assembled in various combinations. Both standard and vendor- defined device types may be embedded in standard device types. Both standard and vendor-defined device types may be embedded in vendor-defined device types. Likewise, both standard and vendor-defined service types may be embedded in both standard and vendor-defined device types. A control point that is capable of operating with a particular device or service type should recognize that device or service type even when it is embedded within another device type (standard or vendor-defined) that it does not recognize. For example, if a standard service type “Print:1” is defined, and a standard device type “Printer:1” is defined that contains the “Print:1” service, a control point that wishes to use the “Print:1” service should find and use it whether the service is embedded within a “urn:schemas-upnp-org:device:Printer:1” device or embedded within a vendor-defined
“urn:acme-com:device:Printer:1” or “urn:acme-com:device:AcmeMultifunctionPrinter:1” device.
The remainder of this section first explains how devices are described, explaining details of vendor-specific information, embedded devices, and URLs for control, eventing, and presentation. Second, it explains UPnP Device Templates. Third, it explains how services are described, explaining details of actions, arguments, state variables, and properties of those variables.
Then it explains UPnP Service Templates, and the UPnP Template Language. Finally, this section explains in detail how a control point retrieves device and service descriptions from a device.
2.1 Description: Device description
The UPnP description for a device contains several pieces of vendor-specific information, definitions of all embedded devices, URL for presentation of the device, and listings for all services, including URLs for control and eventing. In addition to defining
