introductiondownload.microsoft.com/.../wifiverticalpair.docx · web viewusing windows rally...

Using Windows Rally Vertical Pairing to Automatically Install Wi-Fi DevicesJanuary 15, 2010

Abstract

This paper provides information about Windows® Rally™ Vertical Pairing technologies for the Windows family of operating systems. It provides guidelines for device manufacturers to develop Wi-Fi devices that pair with Windows while Windows configures the device's wireless network settings.

This information applies for the following operating systems:Windows Server® 2008 R2Windows 7

References and resources discussed here are listed at the end of this paper.

For the latest information, see: http://www.microsoft.com/whdc/connect/rally/WiFiVerticalPair.mspx

http://www.microsoft.com/whdc/connect/rally/WiFiVerticalPair.mspx

Using Windows Rally Vertical Pairing to Automatically Install Wi-Fi Devices - 2

Disclaimer: This document is provided “as-is”. Information and views expressed in this document, including URL and other Internet Web site references, may change without notice. You bear the risk of using it.

This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this document for your internal, reference purposes.

© 2010 Microsoft Corporation. All rights reserved.

Document HistoryDate ChangeJanuary 15, 2009 Changed “PrintFax.Printer.MFP” to “PrintFax.MFP” in XML examples.September 15, 2009 Clarified how multiple device categories, hardware IDs, or compatible

IDs are delimited. Reformatted Examples 1 and 2.August 4, 2009 First publication

ContentsIntroduction...................................................................................................................3Rally Vertical Pairing End-to-End Experience.................................................................3

History.......................................................................................................................3Usage Scenarios........................................................................................................4

Initial Installation..................................................................................................4Subsequent Installations.......................................................................................5Scenario Benefits..................................................................................................5

Rally Vertical Pairing Theory of Operation.....................................................................6Device Implementation Overview.............................................................................6WCN-NET...................................................................................................................7

WPS Vendor Extensions........................................................................................8Microsoft Vendor Extensions................................................................................9Rally Vertical Pairing TLVs...................................................................................10Vertical Pairing Identifier TLV..............................................................................10Transport UUID TLV............................................................................................11WPS Example......................................................................................................12Protocol Transport Requirements.......................................................................13UUID Values........................................................................................................13

PnP-X.......................................................................................................................14Implementing PnP-X Support..............................................................................14Device Metadata.................................................................................................15

Device Drivers..........................................................................................................24Default Pass-Through Driver...............................................................................24INF File................................................................................................................24Driver and Software Configuration......................................................................29

Devices and Printers Presence................................................................................30Best Practices...............................................................................................................31

Simple Wi-Fi Configuration and Boot-to-Pairing......................................................31Combine PIN and Push-Button WPS Modes............................................................32WPS Advertising Performance.................................................................................32DHCP and Automatic Configuration of IPv4 Link-Local Addresses...........................32Quick Network Connectivity....................................................................................32Use Finish-Install Actions.........................................................................................33

Feedback.....................................................................................................................33Resources....................................................................................................................33

January 15, 2010© 2010 Microsoft Corporation. All rights reserved.


IntroductionNetwork-connected devices have become increasingly popular among consumers. They provide ubiquitous connectivity that enables exciting customer scenarios. However, along with these scenarios consumers want Wi-Fi wireless networking technologies that eliminate wired network cables. Unfortunately, the complexity of configuring Wi-Fi devices has caused poor user experiences, high return rates, and customer service calls.

Many consumers have problems installing a new wireless device because of the amount of technical understanding that is required and the number of steps that must be performed to join the device to a Wi-Fi network, connect to the device from a computer, and then install the appropriate device drivers.

This paper discusses how to use Windows® Rally™ Vertical Pairing technologies to automatically configure Wi-Fi devices and connect them to a computer that is running Windows. It discusses Rally Vertical Pairing concepts, scenarios, technical implementation details, and best practices. It shows Wi-Fi device manufacturers how to enable simple and easy end-to-end device installation experiences for their customers.

Rally Vertical Pairing End-to-End ExperienceThe following sections discuss the history behind Rally Vertical Pairing and some example usage scenarios.

HistoryThe Plug and Play subsystem for the Windows operating system automatically detects devices and then locates and installs the appropriate device drivers. This was a breakthrough technology that simplified device installation. It eliminated the requirement to manually edit configuration files that specify the paths to binary driver files and various parameter settings. However, for network-connected devices Plug and Play does not work because it was not designed to extend over a networking bus.

The Windows Vista® operating system extended the implementation of Plug and Play to accommodate the installation of network-connected devices. This feature is called Plug and Play Extensions (PnP-X). It lets both UPnP™ devices and Devices Profile for Web Services (DPWS) devices participate in the Plug and Play device installation experience.

Device manufacturers took advantage of this improved network device installation capability by adding PnP-X support to their network-connected devices. Many UPnP and DPWS devices do not require device driver support. However, these devices can still take advantage of the PnP-X discoverability and device notification capabilities by using a dummy driver that Microsoft includes with Windows Vista. Even though a network-connected device might not require a device driver to function, manufacturers have used the dummy driver to bootstrap the device installation process.



However, as wireless networking became more and more popular, consumers encountered problems with installing wireless devices because they were required to configure the Wi-Fi settings on their devices to connect their devices to their wireless networks. Only after a user correctly configured the Wi-Fi settings on his or her device could the user begin the process of discovery and PnP-X pairing with the device.

The Wi-Fi configuration process was confusing enough for device manufacturers to justify developing software that would do most of the work for the consumer. These manufacturers began shipping devices with software on CD-ROMs that users were required to install before they could use the device. Because each device manufacturer shipped different software with its wireless devices, a consumer's computer could fill up with many different one-time-use software packages. Furthermore, there was no consistency among device manufacturers for users to learn how to configure and manage their wireless devices.

Windows 7 improves the wireless device installation experience. Users can easily manage all their devices through the Devices and Printers UI. Furthermore, the Add a Device Wizard gives consumers the only way to discover and install their networked (UPnP and DPWS) and wireless (Wi-Fi and Bluetooth) devices. Consumers use Rally Vertical Pairing technology to configure the Wi-Fi settings for a device at the same time as they perform the PnP-X device installation, which can download the appropriate device drivers from Windows Update. Therefore, device manufacturers are not required to ship software to install with their wireless devices.

For more information about UPnP, see ”Universal Plug and Play.” For more information about DPWS, see ”Web Services on Devices.” Both papers are available on the WHDC Web site.

Usage ScenariosThe following scenarios are for a fictitious family that consists of Jane, her husband Bob, and her daughter Amy. They have a Wi-Fi network in their home that they use to share music, movies, and pictures, and to access the Internet.

Initial InstallationOne day Jane decides to purchase a new Wi-Fi scanner. She goes to her local computer store and purchases a fully featured model. When she returns home, Jane and her family are excited to install the new scanner and start scanning all their old photographs.

As Jane starts to open the box, she does not realize it but she is about to witness the Rally Vertical Pairing end-to-end experience because the scanner manufacturer implemented Rally Vertical Pairing support in the scanner device. She performs the following very simple steps to perform a first-time installation of her scanner:

1. Jane removes the new scanner from the box and plugs it into an electrical outlet.2. Jane opens the Devices and Printers UI on her computer that is running

Windows 7 and clicks the Add a device button. This runs the Add a Device Wizard.3. Jane double-clicks the scanner icon that represents her new scanner device.

4. Jane enters the scanner device’s pairing code, which is displayed on the scanner.



5. Jane selects which network the scanner is to use.

After the installation is complete, a photorealistic image of the new scanner appears in Devices and Printers on Jane's computer and she is ready to scan her old photographs.

Subsequent InstallationsJane’s husband Bob and her daughter Amy watched as Jane installed the new scanner on her computer. They are both excited to scan their own photos and documents, so they decide to install the new scanner on their own computers.

Neither Bob nor Amy has ever installed a network device before, so they try to use the same steps that they saw Jane use. Even though her installation involved both configuring the scanner with the Wi-Fi settings and then installing the scanner drivers, the steps are similar for Bob and Amy:

1. Open the Devices and Printers UI on their computers that are running Windows 7, and then click the Add a device button. This runs the Add a Device Wizard.

2. Double-click the scanner icon that represents the new scanner.

They both see the photorealistic image of the scanner in Devices and Printers on their computers and can start scanning immediately.

Scenario BenefitsIn both scenarios, the customer’s experience flow was the same:

1. Run the Add a Device Wizard.2. Select the device.

3. Answer any questions that are asked.

These scenarios demonstrate the following benefits of Rally Vertical Pairing:

There is no ambiguity about what users do to install the device. The steps are similar for both first-time and subsequent installations. In both scenarios users run the Add a Device Wizard.

Neither scenario required the customer to install custom software that the device manufacturer provided.

The technical details of configuring the Wi-Fi settings and installing the device were abstracted from the customer.

Rally Vertical Pairing is a method that an unconfigured Wi-Fi device uses to communicate its intention to pair itself with a computer that is running Windows. Windows uses this information to evaluate which dependencies must first be configured or connected, such as configuring the device’s Wi-Fi settings before pairing the device with Windows.



Rally Vertical Pairing Theory of OperationConsider a device that implements a DPWS print service (WS-Print). When a user first tries to connect to the print service on the device, Windows discovers that the device’s internal topology specifies that the device's print service depends on a Wi-Fi radio. Windows determines that it must first configure the device's Wi-Fi settings before it can communicate with the DPWS print service. Therefore, Windows performs the task of Wi-Fi provisioning and then pairs with the device.

It is important for wireless devices to communicate the internal device topology to Windows. This is the fundamental technology behind Rally Vertical Pairing. It enables Windows to discover and pre-pair with the high-level service before the device comes online. This is considered an out-of-band pairing. By pre-pairing with the high-level service, Windows can install the device as soon as it discovers the device, which occurs as soon as the device comes online.

Pre-pairing with high-level services is not necessary for wired devices because Windows discovers the high-level services only after the lower level dependencies, such as the wired Ethernet radio, have already been configured. A wired device must first configure its network interface and connect to the wired network by using its low-level dependency (the network radio) before Windows can discover the high-level services.

Windows 7 uses Rally Vertical Pairing when it connects to an unconfigured Wi-Fi device. The device uses the Wi-Fi alliance Wi-Fi Protected Setup (WPS) protocol to communicate the device’s topology to Windows by using a WPS vendor extension. The vendor extension identifies the protocols and unique identifiers that the device uses in its higher level services. The device sends the vendor extension with all WPS M1 messages so that the information about the device's topology is communicated during WPS discovery.

Windows uses this information to perform PnP-X out-of-band pairing while it configures the device's Wi-Fi settings during the WPS exchange. This pre-pairs the device with Windows before the device is actually available on the network.

After the device connects to the network and announces itself, PnP-X detects the device and starts the standard PnP process to install and load the appropriate device drivers for the device.

Device Implementation OverviewThis paper discusses many details about how to implement Rally Vertical Pairing support for a wireless device. However the things that you must do are actually very simple:

1. Implement Wi-Fi Protected Setup on the device.Add WPS protocol support to the device, including the Rally Vertical Pairing vendor extension. All Wi-Fi devices must support this vendor extension to support Rally Vertical Pairing.

For more information about how to implement WPS in a device, see ”WCN-NET” later in this paper.



2. Implement PnP-X support on the device.

Windows implements PnP-X support for UPnP and DPWS devices. Adding PnP-X support to a device requires adding just a few XML elements into the device’s metadata.Some networked devices do not support pairing with Windows, so for these devices PnP-X support is not necessary. Such a device must still support the Rally Vertical Pairing vendor extension. However, the vendor extension should indicate that no pairing is required. Because these types of devices do not require Windows installation, they are outside the scope of this paper.

For more information about how to implement PnP-X in a device, see ”PnP-X” later in this paper.

3. Provide a driver package for the device (optional).Creating a driver package can be as simple as defining an INF configuration file or as complex as creating kernel-mode drivers and co-installers.For more information about driver packages, see ”Device Drivers” later in this paper.

4. Provide co-installer software for the device (optional).

A device manufacturer can provide co-installer software that runs during device installation. This software could perform any of the following tasks:

Install additional software packages. Register shell shortcut menu handlers for Devices and Printers or Windows

Explorer. Install COM components.

Register AutoPlay handlers. Any other task that must be performed during device installation.

5. Provide a metadata package for the device (optional).A device manufacturer can create a metadata package that provides a rich description and photorealistic icons of the device to optimize the device experience for the customer. The metadata package can be automatically downloaded from the Microsoft Windows Metadata Information Service (WMIS), installed by an application such as a co-installer, or preinstalled on a computer by an original equipment manufacturer (OEM) before shipping.For more information about how to create a metadata package, see ”Devices and Printers Presence” later in this paper.

The minimum that is required for Rally Vertical Pairing is to implement items 1 and 2. Note that a wireless device that requires WPS support but not PnP-X pairing support (such as a network monitoring device), is required only to implement item 1.

WCN-NETThe Windows Rally suite of protocols includes the Microsoft implementation of WPS, which is known as Windows Connect Now-NET (WCN-NET). This protocol is used to set up Wi-Fi networks and to add wireless devices to Wi-Fi networks.



Rally Vertical Pairing is achieved by including vendor extensions that identify the device’s UPnP and/or DPWS identity string’s universally unique identifier (UUID) values in the WCN-NET/WPS messages. This enables Windows to determine the device’s intent both to connect to a Wi-Fi network and to pair with Windows. After Windows has configured the device's Wi-Fi settings and has paired with the device, Windows waits for layer-3 PnP-X discovery by using Simple Service Discovery Protocol (SSDP) for a UPnP device or Web Services Dynamic Discovery (WS-Discovery) for a DPWS device. If the device is successfully discovered, Windows installs and loads the appropriate drivers for the device.

WPS Vendor ExtensionsA vendor extension is a custom attribute that a device manufacturer can include in WCN-NET/WPS messages. These vendor extensions are defined as blocks of data that are stored in a WPS message's <other> field. The <other> field is an optional field that exists in all WCN-NET/WPS messages, including messages M1-M8 and in the WPS Information Element (WPS IE) in the Probe Request and Probe Response frames. Figure 1, on the following page, shows the location of the vendor extensions in the WPS M1 and M2 messages.

Figure 1. Vendor extensions in WPS messages


Attribute R/O Notes Attribute R/O Notes

Version R 0x10 = version 1.0, 0x11 = version 1.1, etc

Version R 0x10 = version 1.0, 0x11 = version 1.1, etc

Message Type R Value is 0x04 for M1 Message Type R Value is 0x05 for M2

UUID-E R UUID-E R

MAC Address R MAC Address R

Enrolee Nonce R Enrolee Nonce R

Public Key R Public Key R

Public Key R Diffie-Hellman key of Enrollee. Key size and Group are implied by the attribute data size.

Public Key R Diffie-Hellman key of Enrollee. Key size and Group are implied by the attribute data size.

Authentication Type Flags R Authentication Type Flags R

Encryption Type Flags R Encryption Type Flags R

Connection Type Flags R Connection Type Flags R

Config Methods R Config Methods R

Simple Config State R Simple Config State R

Manufacturer R Manufacturer R

Model Name R Model Name R

Model Number R Model Number R

Serial Number R Serial Number R

Primary Device Type R Primary Device Type R

Device Name R Device Name R

RF Bands R Specific RF band used for this message

RF Bands R Specific RF band used for this message

Association State R Association State R

Device Password ID R Device Password ID R Device Password ID Indicated by the Registrar may be different than the ID sent by the Enrollee in M1

Configuration Error R Configuration Error R

OS Version R OS Version R

<other…> O Multiple attributes are permitted <other…> O Multiple attributes are permitted

Authenticator R

WPS M1 Message WPS M2 Message

Vendor extensions go here


Vendors, such as Microsoft, can define vendor extensions for their own use. Every vendor extension contains a vendor ID and vendor data, as shown in Figure 2.

Figure 2. Vendor extension contents

The vendor ID field is three octets long and contains a specific vendor’s ID value that the Internet Assigned Numbers Authority (IANA) provides. The Microsoft vendor ID is 0x137 and is used for every Microsoft vendor extension, including the vendor extension that is used for Rally Vertical Pairing.

Vendor extensions are included with a WPS message by following the WPS message with one or more vendor extensions, as shown in Figure 3.

Figure 3. Including vendor extensions with a WPS message

Microsoft Vendor ExtensionsThe vendor data block that is in each vendor’s vendor extensions contains an arbitrary block of data that the vendor defines. The vendor data block in Microsoft vendor extensions consists of one or more Type-Length-Value (TLV) structures. The organization of the TLV structure is shown in Figure 4.

Figure 4. Organization of the TLV structure

Microsoft has defined various TLV types. Each TLV type represents specific functionality and has different requirements. For example, the TLVs that are related to Rally Vertical Pairing must be sent in the WPS M1 message. However, they can also be sent in other WPS messages.

In a TLV structure, both the Type and the Length fields are 2 bytes long. The Value field can be anywhere from 0 to 1017 bytes long. The value that is stored in the Type field is feature-dependent, and the value that is stored in the Length field must represent the length of the data, in bytes, that is stored in the Value field. Table 1, on the following page, provides a detailed description of each field of the TLV structure.


Vendor ID Vendor Data

Vendor Extension

0-1021 octets3 octets


Vendor ExtensionWPS

Messge Vendor ID Vendor Data

Vendor Extension


Vendor Extension

LT V

2 bytes 2 bytes 0 – 1017bytes


Table 1. Microsoft Vendor Extension TLV Structure FieldsByte offset Field length

(bytes)Field name Description

0 2 (T) Attribute type The type identifier for the attribute.2 2 (L) Data length The length, in bytes, of the attribute’s

value/data field.4 0–1017 (V) Value/data The attribute data. This field is restricted to

a maximum of 242 bytes when it is used in 802.11 IE fields.

The Microsoft vendor extensions allow for one or more TLV structures to be present in the vendor data field, as shown in Figure 5.

Figure 5. Multiple TLV structures in the vendor data field of a Microsoft vendor extension

There is no limit to the number of TLV structures that can be contained in a Microsoft vendor extension. However, if a device specifies multiple Microsoft TLV structures it should use only one vendor extension that contains all the TLV structures instead of using multiple vendor extensions.

Rally Vertical Pairing TLVsTwo specific TLV types are defined for Rally Vertical Pairing. These TLV types are listed in Table 2.

Table 2. Rally Vertical Pairing TLVsName Description Type Length

(bytes)Vertical Pairing Identifier Communicates the internal topology of the

device0x1001 –2

Transport UUID The device’s transport UUID value 0x1002 16

Vertical Pairing Identifier TLVThe Vertical Pairing identifier (VPI) TLV communicates a device’s internal topology, which specifies how Windows can communicate with the device’s services. At least one VPI is required to support Rally Vertical Pairing extensions, even if Vertical Pairing is not implemented in the device. In this situation, the VPI would specify that no transports are used. The VPI TLV must be sent as part of the Microsoft vendor extension in the WPS M1 message.

The data that is included with a VPI TLV is 2 bytes long and consists of two different fields: a Transport field and a Profile Request field, as shown in Figure 6. Each field is 1 byte long.

Figure 6. Data included with a VPI TLV


Vendor ID

Vendor DataLT V LT V

Profile Request Transport

Vertical Pairing Identifier

1 byte 1 byte


VPI Transport FieldThe Transport field specifies the transport that Windows can use to communicate with the device. Only one transport can be specified per VPI. If the device supports multiple PnP-X transports, it can communicate this by including multiple VPI TLVs (one for each transport) in the Microsoft vendor extension. The valid values for the VPI Transport field are listed in Table 3.

Table 3. VPI Transport Field ValuesValue Transport0x00 None0x01 DPWS0x02 UPnP0x03 Secure DPWS0x04–0xFF Reserved

Note: Windows 7 provides support for DPWS (0x01) or Secure DPWS (0x03), but not both.

Note: If a device does not implement Rally Vertical Pairing, it must specify only one VPI with a Transport value of 0x00 (None). In this situation, the device should not specify a Transport UUID TLV. This notifies Windows that it should not expect to pair with the device. Therefore, Windows does not try to pre-pair with the device while it configures the device's Wi-Fi settings.

VPI Profile Request FieldThe VPI lets a device use the WPS protocol to provision the device's services. In this situation, a device service can request that Windows send it information for configuring the service. This information is known as a profile. The VPI’s second field specifies whether the device is requesting that Windows send it a profile. The valid values for the VPI Profile Request field are listed in Table 4.

Table 4. VPI Profile Request Field ValuesValue Description0x00 Wi-Fi profile not requested. This value is not currently supported by

Windows 7.0x01 Wi-Fi profile requested. This is the only value that is currently supported

by Windows 7.0x02–0xFF Reserved.

Note: The VPI Profile Request field value of 0x00 is considered reserved because it is not currently supported by Windows 7. The VPI Profile Request field should only be set to a value of 0x01 (Wi-Fi profile requested), even if a value of 0x00 (none) is specified for the transport.

Transport UUID TLVThe Transport UUID TLV specifies that a specific transport (DPWS or UPnP) has a different base UUID value than the WPS UUID. The Transport UUID TLV is optional. If the Transport UUID TLV is not included, the WPS UUID is used to form an identity for the specified transport.

If a Transport UUID TLV is included, it must immediately follow the VPI TLV that identifies the transport. If more than one VPI TLV is included, a Transport UUID TLV can be included after each VPI TLV.



Notes: The Transport UUID TLV data value must be in network byte order.If the device specifies a VPI Transport value of 0x00 (none), do not include a Transport UUID TLV.

WPS ExampleFor this example, assume that a printer device uses DPWS and implements the WS-Print interface. The device uses the UUID values in Table 5.

Table 5. WPS Example—Service UUID ValuesService IdentityWPS ec742c0d-5915-4bcb-b969-008132afec5eDPWS Print urn:uuid:00010203-0405-0607-0809-0a0b0c0e0e0f

Notes: UUID values are specified in all lowercase, and the DPWS identity string uses the format urn:uuid:uuid_value.

The UUID values in this example are fictitious and must not be used in a real device.

When the device sends out its WPS M1 messages, it includes the Microsoft vendor extension that is shown in Figure 7.

Figure 7. Example vendor extension details

In this example, the vendor extension contains a Vendor ID value of 0x137, which identifies it as a Microsoft vendor extension. Inside the vendor extension’s vendor data field are two TLV structures.

The first TLV has a Type value of 0x1001, which identifies the TLV as a VPI. The length of the data in the first TLV is 2 bytes, which contain a value of 0x0101. This specifies that the device supports the DPWS transport (0x01) and that it is requesting a profile (0x01).

The second TLV has a Type value of 0x1002, which identifies the TLV as a Transport UUID. The length of the data in the second TLV is 16 bytes, which contain the binary version of the UUID value 00010203-0405-0607-0809-0a0b0c0e0e0f.


001d 000137 011049 00021001 01 1002 0010 00010203 0405 0607 08090a0b0c0d0e0f

WPS Type:0x1049(vendor

extension)

WPS Length0x001dbytes

Vendor ID:0x137

(Microsoft)Microsoft Vendor Extension Payload

TLV #1(VPI)

TLV #2(UUID)

Transport0x01

DPWS00010203 0405 0607 08090a0b0c0d0e0f

ProfileRequest:

0x01(Requested)

Type:0x1001(VPI)

Length0x0002bytes

ValueType:

0x1002(UUID)

Length0x0010bytes

Value

Vendor Extension


When a customer vertically pairs the printer, Windows first configures the device’s Wi-Fi radio with appropriate settings. It then pairs the device’s DPWS device by using the specified transport UUID value.

After the device connects to the Wi-Fi network and announces its DPWS services, Windows creates the appropriate PnP device nodes and installs and loads the appropriate drivers.

Protocol Transport RequirementsIn Windows 7, Rally Vertical Pairing supports only the UPnP and DPWS protocols. A device can use either or both protocols. It is the responsibility of the device to communicate its intent to use a protocol to Windows. This means that the device must explicitly state which protocol Windows is to use to pair with the device. If a device exposes no protocols, it must explicitly specify that the device uses no protocols.

UUID ValuesThe WPS, UPnP, and DPWS protocols all use a UUID value. For Rally Vertical Pairing support, you must observe the following guidelines when you use UUIDs: Identity strings must use all lowercase characters.

A device’s UPnP root node must implement its identity string by using only numeric digits and lowercase characters. This is important because UPnP matches case-sensitive identity strings. When the device communicates its UUID over WPS by using a vendor extension, it is sent in its binary format. When Windows converts the binary UUID to a text UUID, it uses all lowercase characters. Therefore, if the device uses any uppercase characters in its identity string, UPnP discovery of the device fails.

The DPWS identity must use the ”urn:uuid:<uuid_value>” format.All DPWS devices must implement a uniform resource identifier (URI) by using the format that is recommended in the DPWS specification urn:uuid:uuid_value, for example, urn:uuid:f8d8fe06-6f4a-4ea2-93aa-38061a6c8550. Windows assumes that the URI consists of only numeric digits and lowercase characters.

Identity string UUID values can be shared.Devices can share the same UUID value across different transports to conserve space in the Rally Vertical Pairing vendor extension. If a transport uses the same UUID as the WPS UUID, there is no requirement for the vendor extension to include a Transport UUID TLV for that particular transport. However if the UUID value is shared only between UPnP and DPWS but differs from the WPS UUID, both transports must include their own Transport UUID TLV.For example, if a device uses the UUIDs in Table 6, providing a Transport UUID TLV for UPnP is optional but is required for DPWS.

Table 6. Example UUIDsProtocol IdentityWPS f8d8fe06-6f4a-4ea2-93aa-38061a6c8550UPnP uuid:f8d8fe06-6f4a-4ea2-93aa-38061a6c8550DPWS urn:uuid:55363c1c-8547-4195-a325-fc3ecba5b312



As another example, if the device uses the UUIDs in Table 7 (UPnP and DPWS UUIDs are shared, but differ from the WPS UUID), both transports require their own Transport UUID TLV.

Table 7. Example UUIDsProtocol IdentityWPS f8d8fe06-6f4a-4ea2-93aa-38061a6c8550UPnP uuid:55363c1c-8547-4195-a325-fc3ecba5b312DPWS urn:uuid:55363c1c-8547-4195-a325-fc3ecba5b312

For more information about WCN-NET, see “Configuration Technologies: Windows Connect Now” and ”Windows Connect Now-NET Specification.” Both papers are available on the WHDC Web site.

PnP-XAll Rally devices must support PnP-X. In Windows, PnP-X provides the mechanism to discover the presence of a paired Rally device. When Windows discovers a Rally device, it engages the Plug and Play subsystem to load or unload the appropriate device drivers when the device comes onto the network or leaves the network.

Many devices use PnP-X so that their device-specific drivers are correctly loaded. Network printers that implement WS-Print and WS-Scan interfaces are examples of such devices. However some devices, such as Digital Living Network Alliance (DLNA) renderers, do not require device drivers. In this situation, Windows includes a PnP-X pass through driver that can be used. This driver does not provide any functionality. However, it enables the Plug and Play subsystem to correctly detect the device’s presence, load the driver, and then announce the device to Windows. Such notifications are important for software such as Devices and Printers, AutoPlay handlers, and Sidebar gadgets.

Implementing PnP-X SupportA device implements PnP-X support by adding metadata to the device’s description document (UPnP) or the device’s metadata (DPWS). These metadata tags communicate information that Windows requires to map the device to the appropriate device drivers and to provide a Plug and Play presence.

The PnP-X metadata maps the device to a device driver by using a driver information (INF) file. The INF file tells the Plug and Play subsystem to which devices the driver package applies, where the files are located in the driver package, and where to copy the files on the system during device installation. The most critical point here is the matching of the PnP-X device to a driver package. Windows does this by comparing the hardware IDs and compatible IDs that were retrieved from the device with the IDs that are specified in the INF files in the driver store, on Windows Update, and other sources. All INF files that match the device are then ranked according to several criteria, and the driver package with the best match is selected for installation. Some INF files are included with Windows and others are accessed as part of a driver package on Windows Update, on a CD-ROM, or that is downloaded from the device manufacturer's Web site. For more information about driver packages, see “Device Drivers” later in this paper.



For more information about PnP-X, see “Discovery Technologies: PnP-X” on the WHDC Web site.

Device MetadataThere are five PnP-X XML elements that you can add to a Rally device's metadata, which are described in Table 8.

Table 8. PnP-X Metadata XML ElementsName Requirement DescriptionDevice Category Optional

(Windows Vista)Required (Windows 7)

Describes the device category for the device.

Hardware ID Required A unique identifier for the device. Windows uses this identifier to determine the appropriate drivers and metadata packages to use for the device.

Compatible ID Required (if applicable)

An identifier for the device that indicates that the device is compatible with another device or class of devices. Windows uses this identifier to determine the appropriate drivers and metadata packages to use for the device. If a compatible ID exists for a device, it must be included in the device's metadata.

Container ID Optional A unique identifier that specifies the physical device. This identifier is shared across all transports and services that the device provides. Windows uses this identifier to group all the functionality of the device into a single physical device.This element is new for Windows 7.

Model ID Optional A unique identifier that specifies the particular model of the physical device. Windows uses this identifier to determine the appropriate metadata packages to use for the device. This element is useful to identify variations of a given device, such as different colors of the same device.This element is new for Windows 7.

All Rally devices that support PnP-X must implement the elements in Table 8 that are noted as being required.

XML Element DetailsThe following sections provide more details about each XML element in Table 8.

Device CategoryThe Device Category element informs Windows about the functionality that the device provides. In Windows Vista and Windows 7, each device is associated with a device category such as Printer, Scanner, or Modem. A single physical device can represent several different device categories. For example, a multifunction printer device might fit into the categories of Printer, Scanner, Fax, and Storage.

The value for the Device Category element in your device metadata is specified as a list of device categories that are each separated by a space character. The first entry in the list is considered the primary device category. Network Explorer and Devices and Printers display the device by using an icon that represents the primary device



category. If Windows does not recognize the primary device category for a device, the device is displayed as a generic device icon with a device category of Other or Unknown.

There are two different XML namespaces where the Device Category element can be specified, one for backward support (for Windows Vista) and one for forward support (for Windows 7 and later). If you want your device to appear the best in both Windows Vista and Windows 7, you must specify the Device Category element for your PnP-X device in both namespaces.

Windows Vista Device Category SupportWindows Vista includes support for various device categories. The device category value can be any text string. However, Windows Vista recognizes only a limited list of device category values. For more information about the device categories that Windows Vista supports, see ”PnP-X: Plug and Play Extensions for Windows Specification” on the WHDC Web site.

Windows 7 Device Category SupportWindows 7 changed some device categories to include a broader range of devices. The Windows 7 device category list provides a hierarchical taxonomy that can be used to provide generic to specific device categories. For example, for a printer you might supply the general PrintFax device category or you might choose to identify the printer by using the more specific device category of PrintFax.Printer.Laser.

For more information about the device categories that Windows 7 supports, see ”How to Create a Device Metadata Package for Devices and Printers” on the WHDC Web site.

Note: Multiple device categories must be separated by space characters only. You cannot use tabs, newlines, or any other forms of white space, other than space characters, to separate multiple device categories.

Hardware IDThe hardware ID uniquely identifies the device model on a particular transport. Windows uses this identifier to determine the correct device drivers and metadata packages to use for the device.

For example, Devices and Printers uses the hardware ID (and the model ID) to identify the correct metadata package for the device. This enables Windows to display the device by using photorealistic icons and rich device descriptions.

You should use the same hardware ID value for all devices of the same model.

Beginning with Windows 7, PnP-X devices must use the following format for their hardware ID values:

VEN_VID&DEV_DID&SUBSYS_SID&REV_RIDVID

The device vendor’s vendor ID. Device vendors should use their Winqual ID for their vendor ID.



DIDThe device ID for the device. This value is defined by the device vendor and must be unique for each device model.

SID An optional subsystem ID for the device. This value is defined by the device vendor.Some devices of the same model may differ by subsystem components. For example, one variant of a device model might implement support for a Wi-Fi network whereas another variant of the same device model might implement support for a wired network.A device vendor might design a device on behalf of another company. In this situation, the device vendor might use the subsystem ID to identify itself and the Winqual ID to identify the company for which it designed the device.

A device vendor might want to use both UPnP and the DPWS network protocols. In this situation, the hardware ID values for the two different protocols can be unique if the vendor specifies different values for the subsystem ID.

RIDAn optional revision ID for the device. This value is defined by the device vendor. This value represents a revision of the device. It might represent the revision of the device's hardware or firmware.

For example:

VEN_999&DEV_22&REV_2533or

VEN_999&DEV_22&SUBSYS_01&REV_2533You can specify multiple hardware IDs for a device. In this situation, the hardware IDs typically range from specific to more general. For example, a device might define a hardware ID that represents the model number and another hardware ID that represents the model number plus the firmware revision or device options.

For example, you could specify the following three hardware IDs for a device:

VEN_999&DEV_22&SUBSYS_01&REV_2533VEN_999&DEV_22&SUBSYS_01VEN_999&DEV_22

Specifying multiple hardware IDs for your device can be very useful because it enables Windows to match your device to the appropriate device drivers at various levels. For example, Windows might determine the appropriate device driver and metadata package for a device that are based on the device’s basic hardware ID, such as VEN_999&DEV_22. However, if you must release an updated device driver only for those devices that have a specific firmware version, you can release an updated driver package that specifies a more specific hardware ID, such as VEN_999&DEV_22&SUBSYS_01&REV_2533. Some device manufacturers use the basic hardware ID to identify an appropriate driver package and use more specific hardware IDs to identify an appropriate metadata package. This enables differentiation between functionally identical devices that have different device characteristics such as color or shape or that have been rebranded.



When specifying multiple hardware ID values in your device metadata, you must make sure that each is separated by a space character and that they are ordered most specific to least specific. The order is critical because it affects how Windows determines the appropriate device drivers and metadata packages for the device.

Note: Hardware ID values must not include forward slash ('/') or backslash ('\') characters. These characters are reserved for delimiting a bus from a hardware ID in a device driver INF file.

Note: Hardware ID values should be unique across transport protocols (for example, UPnP and DPWS). If a device implements more than one transport protocol, the device should have a unique hardware ID value for each transport protocol. This enables different drivers to load for the device for each transport protocol. However, some device vendors have implemented a single driver for their device that supports multiple transport protocols. In this situation, the hardware IDs for the device are not required to be unique across transport protocols.

Note: When hardware ID and compatible ID values are specified in XML documents (such as DPWS metadata exchanges and UPnP description documents), they must be appropriately coded as entity references.

Note: Multiple hardware IDs must be separated by space characters only. You cannot use tabs, newlines, or any other forms of white space, other than space characters, to separate multiple hardware IDs.

Compatible IDMuch like the hardware ID, the compatible ID is a value that is used to determine the appropriate device drivers and metadata packages for a device. However, the compatible ID does not specify a specific device. Instead, it declares that the device is compatible with particular types of functionality.

For example, for a particular UPnP webcam Windows might not find a driver or metadata package that is installed on the system that matches any of the device's hardware ID values. However, the device might be compatible with a more generic webcam device driver and metadata package that is installed on the system. If the device specifies compatible IDs, Windows can use the generic device drivers and metadata package for the device.

Basically, a compatible ID is used to indicate that a device is compatible with another device. Typically, a compatible ID is the same as the other device’s hardware ID. Often a device specifies a compatible ID that matches a class driver that is included with Windows for a particular type of device.

Table 9 provides some examples of the compatible ID values for some well-known device types.

Table 9. Examples of Well-Known Compatible ID ValuesDevice type Compatible IDDLNA media renderer MS_DigitalMediaDeviceClass_DMR_V001DLNA media server MS_DigitalMediaDeviceClass_DMS_V001DLNA media player MS_DigitalMediaDeviceClass_DMP_V001DLNA media controller MS_DigitalMediaDeviceClass_DMC_V001Media Center Extender MICROSOFT_MCX_0001



Device type Compatible IDDPWS printer http://schemas.microsoft.com/windows/2006/08/wdp/print

/PrinterServiceTypeBasic PnP-X support GenericUmPass

Just as you can with the hardware ID, you can specify a list of multiple compatible ID values for a device. The compatible IDs in your device metadata must each be separated by a space character, must not contain backslash ('\') or forward slash ('/') characters, and must be ordered from most relevant to least relevant (if applicable).

You can specify a compatible ID value of GenericUmPass for a device if the device does not implement any device-class-specific functionality. If you specify a list of compatible ID values for the device, GenericUmPass should be the last value in the list. In this situation, Windows loads the generic default driver, Umpass.sys, if no other hardware ID or compatible ID matches a device driver that is installed in the system. For more information, see ”Default Pass-Through Driver” later in this paper.

Note: Multiple compatible IDs must be separated by space characters only. You cannot use tabs, newlines, or any other forms of white space, other than space characters, to separate multiple compatible IDs.

Container IDThe container ID is a unique identifier that specifies the physical device. This value is new for Windows 7. Windows uses this identifier to group devices that function over multiple transports into a single physical device that is displayed in Devices and Printers. If a device does not support multiple transports, this value should be omitted.

For example, if a printer can be accessed over UPnP, DPWS, and USB, the same container ID value should be specified for all three transports. When Windows enumerates all devices across all transports, it finds multiple devices with the same container ID and groups them as a single physical device.

The container ID value is specified as a GUID, for example, {01392d0-5e91-10ad-ad8b-0a00200c9e12}.

For more information about the container ID element, see ”Multifunction Device Support and Device Container Groupings in Windows 7” on the WHDC Web site.

Model IDThe model ID is a unique identifier that specifies the particular model of the physical device. Windows uses this identifier to determine the appropriate metadata packages to use for the device.

The model ID is typically used to differentiate among different versions of a device. For example, a particular MP3 playback device model may be available in different colors. If the same hardware ID is specified for all colors, Windows uses the same device driver regardless of the color of the device. However, if a different model ID is specified for each color of the device, Windows can use different metadata packages for each different color of the device. This lets each color of the device use a different photorealistic icon of the device in Devices and Printers to represent the correct color of the device.


Like the container ID, the model ID value is specified as a GUID, for example, {01392d0-5e91-10ad-ad8b-0a00200c9e12}.

DPWS DevicesAll DPWS devices must expose all required PnP-X metadata elements that were listed previously in Table 8. Table 10 associates each PnP-X metadata element with its respective DPWS XML element container and namespace.

Table 10. DPWS XML Element Containers and Namespaces for PnP-X ElementsPnP-X element

Element container

Namespace

DeviceCategory

ThisModel

For Windows Vista: http://schemas.microsoft.com/windows/pnpx/2005/10For Windows 7: http://schemas.microsoft.com/windows/2008/09/devicefoundation

HardwareId Hosted http://schemas.microsoft.com/windows/pnpx/2005/10CompatibleId Hosted http://schemas.microsoft.com/windows/pnpx/2005/10ContainerId ThisDevic

ehttp://schemas.microsoft.com/windows/2008/09/devicefoundation

ModelId ThisModel

http://schemas.microsoft.com/windows/2008/09/devicefoundation

Example 1 shows a DPWS Simple Object Access Protocol (SOAP) message that specifies metadata for a printer/scanner device that supports two hosted services. The PnP-X-related metadata elements are shown in bold type.

Example 1: DPWS Metadata Message with PnP-X Support<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:wsdisco="http://schemas.xmlsoap.org/ws/2005/04/discovery" xmlns:wsx="http://schemas.xmlsoap.org/ws/2004/09/mex" xmlns:wsd="http://schemas.xmlsoap.org/ws/2006/02/devprof" xmlns:pnpx="http://schemas.microsoft.com/windows/pnpx/2005/10" xmlns:df="http://schemas.microsoft.com/windows/2008/09/devicefoundation" >

<soap:Header>  </soap:Header>

<soap:Body> <wsx:Metadata> <wsx:MetadataSection Dialect="http://schemas.xmlsoap.org/ws/2006/02/devprof/ThisDevice"> <wsd:ThisDevice> 

<df:ContainerId> <-- only define if using multiple protocols --> {101392d0-5e91-11dd-ad8b-0800200c9a66} </df:ContainerId>

</wsd:ThisDevice> </wsx:MetadataSection>

<wsx:MetadataSection Dialect="http://schemas.xmlsoap.org/ws/2006/02/devprof/ThisModel"> <wsd:ThisModel> 

<pnpx:DeviceCategory>  MFP Printers Scanners </pnpx:DeviceCategory>

<df:DeviceCategory>  PrintFax.MFP PrintFax.Printer.Laser Imaging.Scanner </df:DeviceCategory>

<df:ModelId>  {01392d0-5e91-10ad-ad8b-0a00200c9e12} </df:ModelId>

</wsd:ThisModel> </wsx:MetadataSection>

<wsx:MetadataSection Dialect="http://schemas.xmlsoap.org/ws/2006/02/devprof/Relationship"> <wsd:Relationship Type="http://schemas.xmlsoap.org/ws/2006/02/devprof/host">

<wsd:Hosted> 

<pnpx:HardwareId>   VEN_999&DEV_22&SUBSYS_01&REV_2533 VEN_999&DEV_22&SUBSYS_01 VEN_999&DEV_22 </pnpx:HardwareId>

<pnpx:CompatibleId>  http://schemas.microsoft.com/windows/2006/08/wdp/print/PrinterServiceType GenericUmPass </pnpx:CompatibleId>

</wsd:Hosted>

<wsd:Hosted> 

<pnpx:HardwareId>   VEN_999&DEV_22&SUBSYS_11&REV_2533 VEN_999&DEV_22&SUBSYS_11 VEN_999&DEV_22 </pnpx:HardwareId>

<pnpx:CompatibleId>  http://schemas.microsoft.com/windows/2006/08/wdp/scan/ScannerServiceType GenericUmPass </pnpx:CompatibleId>

</wsd:Hosted>

<wsd:Hosted>   </wsd:Hosted> </wsd:Relationship> </wsx:MetadataSection> </wsx:Metadata> </soap:Body></soap:Envelope>Note that this example specifies GenericUmPass as the compatible ID value for each DPWS service. Devices should leave this as the last compatible ID value, as discussed earlier in this paper.

UPnP DevicesAll UPnP devices must be PnP-X-enabled. The following sections discuss how to include PnP-X support in a UPnP device.

SSDP Discovery For PnP-X support, no changes are required to the UPnP SSDP discovery packets. However, for Rally Vertical Pairing support, the device identity string must be specified with lowercase characters.

UPnP Description DocumentSimilar to DPWS devices, all UPnP devices must expose all required PnP-X metadata elements that were listed previously in Table 8. Table 11 associates each PnP-X metadata element with its respective parent UPnP element block.

Table 11. UPnP XML Element Containers and Namespaces for PnP-X ElementsPnP-X element Element

container

Namespace

X_deviceCategory

<device>

For Windows Vista: http://schemas.microsoft.com/windows/pnpx/2005/11For Windows 7: http://schemas.microsoft.com/windows/2008/09/devicefoundation

X_hardwareId <device>

http://schemas.microsoft.com/windows/pnpx/2005/11

X_compatibleId <device>

http://schemas.microsoft.com/windows/pnpx/2005/11

X_containerId <device>


X_modelId <device>

Example 2 shows a UPnP description document that specifies metadata for a printer/scanner device that supports two hosted services. The PnP-X–related metadata elements are shown in bold type.

Example 2: UPnP Description Document with PnP-X Support<?xml version="1.0" ?> <root xmlns="urn:schemas-upnp-org:device-1-0" xmlns:pnpx="http://schemas.microsoft.com/windows/pnpx/2005/11" xmlns:df="http://schemas.microsoft.com/windows/2008/09/devicefoundation" >

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

<device> <pnpx:X_hardwareId>  VEN_999&DEV_22&SUBSYS_00&REV_2533 VEN_999&DEV_22&SUBSYS_00 VEN_999&DEV_22 </pnpx:X_hardwareId>

<pnpx:X_compatibleId>  GenericUmPass </pnpx:X_compatibleId>

<pnpx:X_deviceCategory>  MFP Printers Scanners </pnpx:X_deviceCategory>

<df:X_deviceCategory>  PrintFax.MFP PrintFax.Printer.Laser Imaging.Scanner </df:X_deviceCategory>

<df:X_containerId>  {101392d0-5e91-11dd-ad8b-0800200c9a66} </df:X_containerId>

<df:X_modelId>  {701392d0-5e91-10ad-ad8b-0a00200c9e12} </df:X_modelId >

<deviceType>UPnP_DEVICE_TYPE_VALUE</deviceType> <friendlyName>friendly name</friendlyName> <manufacturer>manufacturer</manufacturer> <manufacturerURL>manufacturer URL</manufacturerURL> <modelDescription>model description</modelDescription> <modelName>model name</modelName> <modelNumber>model number</modelNumber> <modelURL>URL to model site</modelURL> <serialNumber>manufacturer's serial number</serialNumber> <UDN>device UDN</UDN> <UPC>universal product code</UPC> <serviceList> <service> <serviceType /> <serviceId />

<SCPDURL /> <controlURL /> <eventSubURL /> </service> </serviceList> <deviceList>  </deviceList> <presentationURL>presentation URL</presentationURL> </device></root>

Note that this example specifies GenericUmPass as the compatible ID value. Devices should leave this as the last compatible ID value, as discussed earlier in this paper.

Device DriversAfter Windows has configured a Rally device's Wi-Fi settings and has paired with the device, Windows detects that the device is online and starts the Plug and Play process. This process installs and loads the appropriate device drivers for the device. Plug and Play determines which device driver is the most appropriate driver for the device by examining drivers that are included with Windows, drivers that were previously installed on the system, and drivers on Windows Update. A Rally device that uses drivers that are included with Windows or drivers that are available on Windows Update does not require the user to install software from a CD-ROM or software that was manually downloaded from the device manufacturer's Web site.

Default Pass-Through DriverMany PnP-X devices do not require the functionality that a device driver provides. For example, applications that communicate with a DLNA media library by using the UPnP protocol do not use a driver to communicate with the device. However, Rally Vertical Pairing devices require a driver to be loaded so that Windows can notify applications and services about the arrival of the device and any associated interfaces.

For devices that do not require the functionality that a device driver provides, Windows includes a passthrough driver, Umpass.sys. This driver has no functionality other than support for loading and unloading. It can be used with any device that just must provide notification to applications and services that it has arrived. If a Rally Vertical Pairing device does not require a device driver, it should use the Umpass.sys driver.

You can use the Umpass.sys passthrough driver for your device either by specifying a well-known compatible ID value for another device or class of device that uses Umpass.sys or by specifying a hardware ID and providing an INF file for your device that specifies the Umpass.sys driver as the driver to use for your device. If your device does not implement any functionality that is compatible with any of the well-known compatible ID values, it can specify a compatible ID of GenericUmPass. In this situation, Windows loads the passthrough driver without any additional support, such as defining interfaces. This is useful because it eliminates the requirement to provide a specialized INF file for a device that requires no special driver or software support. For more information about how to specify compatible ID values, see ”Compatible ID” earlier in this paper.


INF FileExample 3, later in this section, shows a sample device driver INF file for a PnP-X device. It provides the driver installation information for a device with a hardware ID of VEN_999&DEV_22&SUBSYS_01.

If you modify this sample INF file for use with your device, you must prefix the device's hardware ID or compatible ID value with UMB\. This indicates to Windows that the ID is related to PnP-X. If an INF file does not include this prefix, PnP-X does not recognize the device and the device cannot be installed. The example INF file does this for the sample VEN_999&DEV_22&SUBSYS_01 device, but if you add hardware IDs or compatible IDs to the file for your device, you must ensure that you do this for every ID.

Many networked devices, such as DLNA media devices, use functionality that is built into Windows 7. For such a device, you simply must specify the compatible ID for the built-in functionality. For example, for a DLNA renderer device you can simply specify a compatible ID of MS_DigitalMediaDeviceClass_DMR_V001 in the device’s UPnP or DPWS metadata. This results in Plug and Play using the DLNA INF file that is included with Windows. In this situation, you are not required to provide an INF file for your device.

However, for devices that expose functionality that is not built into Windows, you must provide an INF file for the device. The INF file must specify a device driver to use for the device. If the device uses only the Umpass.sys passthrough driver that is included with Windows, no INF file is required. In this situation, the device should specify a compatible ID value of GenericUMPass in the device’s PnP-X metadata.

Modifying the Sample INF FileThe sample INF file shows how an INF file for a PnP-X device might look. Note that this sample is incomplete as shown. The following items must be modified as appropriate for a particular device:

In the [Version] section: Class: Specify the actual device class for your device, for example,

WSDPrintDevice. ClassGuid: Specify the GUID that represents the device class that was specified

for the Class item, for example, {c30ecea0-11ef-4ef9-b02e-6af81e6e65c0}. VersionStamp: Specify a date/version stamp for the INF file in the following

format: mm/dd/yyyy,version. For example, 12/08/2006,1.0.0.0000.

In each [Device.NTxxxx.6.y] section:

Specify any hardware ID and/or compatible ID values for your device. Only specify compatible ID values in your INF file if you created them. Otherwise,

other INF files define them. Ensure that all hardware ID and compatible ID values are prefixed with UMB\ as

previously discussed. For example, use UMB\VEN_999&DEV_22&SUBSYS_01 to specify VEN_999&DEV_22&SUBSYS_01 for a hardware ID.



In the [Device_Install_Win7.NT.HW.AddReg] and [Device_Install_Vista.NT.HW.AddReg] sections: Replace the GUID value with a valid interface GUID value. For example, for an

audio card kernel-streaming interface, you would specify the following GUID: {6994ad04-93ef-11d0-a3cc-00a0c9223196}. Multiple entries can be specified to associate a device with multiple interfaces.If no interfaces should be associated with the device, remove all lines in these sections.

In the [String] section:

Company: Specify the manufacturer of the device, for example, Microsoft. ClassName: Specify a friendly name for the device class, for example, WSD Print

Provider. Device.DeviceDesc: Specify a friendly name that describes the device, for

example, WSD Print Device.

In the Device Class Section:

This section is required only if you are creating a new device class. If you reference an existing device class (that is, you use a predefined compatible ID):

Remove the [ClassInstall32] section. Remove the [Device_ClassReg] section.

Remove the ClassName entry in the [Strings] section.

If you define a new device class (that is, there is no known compatible ID value for your device class): Uncomment the [ClassInstall32] section by removing the semicolon at the

beginning of each line in the section. Uncomment the [Device_ClassReg] section by removing the semicolon at the

beginning of each line in the section. Modify the ClassName item in the [Strings] section to specify a friendly name

for the device class. Modify the Class and ClassGuid values in the [Version] section to specify a

unique class name and GUID for the device class.

The items in Example the sample INF file that must be modified for devices are shown in bold type.

Example 3: Device Driver INF File;; Copyright (c) Microsoft Corporation. All rights reserved.;; Description:; INF SAMPLE for PnP-X Devices;

[Version]Signature = "$WINDOWS NT$"Provider = %Company% ; Manufacturer of this deviceClass = "MyDeviceClass" ; Provide a class for your device... ; ...predefined or new.



ClassGuid = {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} DriverVer = 02/05/2009,1.0.0.000

; ===================== Device Class Section =======================; This section is required if you are defining a new Class.; If the device class has not been defined then uncomment this; section and modify the [Strings] section’s ClassName value.

; [ClassInstall32]; Addreg=Device_ClassReg

; [Device_ClassReg]; HKR,,,,%ClassName% ; Friendly name for this device class; HKR,,SilentInstall,,1 ; Specify a silent installation; HKR,,Icon,,"-52" ; Icon: generic network device

; ======================== Device Section ==========================

; Should list all device manufacturer/model combinations here[Manufacturer]; Note: next line wraps but should be only one line%Company%=Device, NTx86.6.0, NTamd64.6.0, NTia64.6.0, NTx86.6.1, NTamd64.6.1, NTia64.6.1

; Model Device Description Install Section HWIDs, Compatible IDs; ------------------------ -------------------- ---------------------

; Model specific install section list for Windows Vista x86/amd64/ia64[Device.NTx86.6.0]%Device.DeviceDesc% = Device_Install_Vista, UMB\VEN_999&DEV_22&SUBSYS_01

[Device.NTamd64.6.0]%Device.DeviceDesc% = Device_Install_Vista, UMB\VEN_999&DEV_22&SUBSYS_01

[Device.NTia64.6.0]%Device.DeviceDesc% = Device_Install_Vista, UMB\VEN_999&DEV_22&SUBSYS_01

; Model specific install section list for Windows 7 x86/amd64/ia64[Device.NTx86.6.1]%Device.DeviceDesc% = Device_Install_Win7, UMB\VEN_999&DEV_22&SUBSYS_01

[Device.NTamd64.6.1]%Device.DeviceDesc% = Device_Install_Win7, UMB\VEN_999&DEV_22&SUBSYS_01

[Device.NTia64.6.1]%Device.DeviceDesc% = Device_Install_Win7, UMB\VEN_999&DEV_22&SUBSYS_01

; =================== Install Sections: Windows 7 ===================

[Device_Install_Win7.NT]Include=umpass.infNeeds=UmPass

; Section to add device-specific information to the registry ; and declare an AddReg section[Device_Install_Win7.NT.HW] Include=umpass.inf



Needs=UmPass.HWAddReg=Device_Install_Win7.NT.HW.AddReg

;Add the registry entries [Device_Install_Win7.NT.HW.AddReg] HKR,,InterfaceGUIDs,0x10000, "{yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy}" [Device_Install_Win7.NT.CoInstallers]Include=umpass.infNeeds=UmPass.CoInstallers

; Set up the UMPass service for the device[Device_Install_Win7.NT.Services]Include=umpass.infNeeds=UmPass.Services

[Device_Install_Win7.NT.Interfaces]Include=umpass.infNeeds=UmPass.Interfaces

; ==================== Install Sections: Windows Vista =============

[Device_Install_Vista.NT]; Install section for Windows Vista compatible .Services ; section, below.; For Windows 7 and later, include all sections from Umpass.inf, ; as above.

; Section to add device-specific information to the registry ; and declare an AddReg section[Device_Install_Vista.HW] AddReg=Device_Install_Vista.NT.HW.AddReg

;Add the registry entries [Device_Install_Vista.NT.HW.AddReg] HKR,,InterfaceGUIDs,0x10000, "{yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy}"

[Device_Install_Vista.NT.Services]; Services section compatible with installing Umpass.sys on ; Windows Vista.; For Windows 7 and later, include all sections from Umpass.inf, ; as above.AddService = UMPass, 0x00000002, UMPassService_Install

[UMPassService_Install]DisplayName = "Microsoft UMPass Driver" ; Service Friendly Name ServiceType = 1 ; SERVICE_KERNEL_DRIVERStartType = 3 ; SERVICE_DEMAND_START ErrorControl = 1 ; SERVICE_ERROR_NORMALServiceBinary = %12%\umpass.sysLoadOrderGroup = Extended Base

; ======================= Strings Section =========================; Strings that are referenced throughout the INF[Strings]Company = "Microsoft"Device.DeviceDesc = "My Device Name"ClassName = "My Device Class Name"



For more information about INF files, see ”INF Files” and ”INF File Sections and Directives” in the Windows Driver Kit (WDK).

For more information about device driver packages, see “Driver Packages” in the WDK.

For more information about device driver installation, see “Device Driver Installation” on the WHDC Web site and ”Device and Driver Installation” in the WDK.

Driver and Software ConfigurationFor certain devices, it is important to configure the device when the device drivers for the device are installed. In this situation, the configuration of a device is typically performed by a device co-installer or by post-installation actions. This configuration step is optional and applies only if a device uses a device driver package that includes an INF file. This section discusses the different techniques that a driver package can use to install and/or configure software and device settings.

Co-InstallerWhen Windows installs a device driver for a device, it can call a DLL that is included in the driver package. The DLL exposes a function that can run any code that is required to correctly set up the system. This DLL is known as a co-installer.

A co-installer can perform the work of registering COM classes, shell shortcut menu handlers, and AutoPlay handlers, or other similar tasks. A co-installer is a way to extend device driver installation to include device and/or software setup.

A co-installer is run before the installation of the device is completed. Therefore, the code is run before notification about the arrival of the device is sent to applications or services.

A co-installer runs in an administrative process with elevated credentials. Therefore, you must ensure that a co-installer for your device does not accidentally configure Windows incorrectly. As a security precaution, a co-installer should not use any network resources because it runs with elevated credentials.

A co-installer should not display a user interface. If the configuration of your device requires user interaction, use a finish-install action or an AutoPlay handler.

Note: Co-installers are not recommended for printers because they can interfere with Point and Print installations.

For more information about how to write a co-installer, see ”Writing a Co-installer” in the WDK.

Finish-Install ActionsSometimes it is useful to run an application, such as a device setup and configuration application, immediately after a device is installed. For example, after successful installation of a scanner you might want to run an application that verifies the operation of the scanner by performing a test scan.

You can run applications after a device is installed by using a finish-install action. After Windows completes the device installation process, it runs a command to finish the installation if such a finish-install action is registered.



A finish-install action runs in an administrative process with elevated credentials. Therefore, you must ensure that a finish-install action for your device does not accidentally configure Windows incorrectly. As a security precaution, a finish-install action should not use any network resources because it runs with elevated credentials.

For more information about finish-install actions, see ”Device Finish-Install Actions in Windows Vista” on the WHDC Web site and ”Finish-Install Actions” in the WDK.

AutoPlay HandlersThe AutoPlay version 2 architecture binds software with a device interface. When Windows detects a device and loads a device driver for the device, any device interface that is bound to the device driver is enabled. Windows then sends notifications to any registered applications or services about the arrival of the device interface. AutoPlay receives these notifications and runs any software that is registered for the device interface. You can use this feature to have Windows automatically run software for your PnP-X–enabled device when it is detected.

For example, a PnP-X-enabled network picture frame can define a device interface in its INF file. After the user pairs Windows with the picture frame, Windows detects the device and then installs an appropriate driver from Windows Update. During the driver installation process, a co-installer installs the picture frame’s photo synchronization software and registers an AutoPlay handler. The driver is loaded after the co-installer process is complete. After the driver is loaded, Windows sends a notification to AutoPlay about the arrival of the device interface. AutoPlay receives this notification and runs the picture frame’s photo synchronization software that retrieves information from the device, such as its UUID and IP address, and then synchronizes photos.

AutoPlay handlers are run by using the credentials of the currently logged-on user. Therefore, it is safe for an AutoPlay handler to display a user interface and use network resources. However, because AutoPlay handlers do not run with elevated credentials, they have limited system configuration capabilities.

You can register an AutoPlay handler by using a co-installer that runs during device installation. Or, a user can register AutoPlay handlers at any time by using software on a CD-ROM, downloaded from the Web, or from other sources.

For more information about how to create and register AutoPlay handlers, see ”AutoPlay in Windows XP: Automatically Detect and React to New Devices on a System” on the WHDC Web site

Devices and Printers PresenceWindows automatically detects the presence of PnP-X devices, including devices that use Rally Vertical Pairing, and displays them in Devices and Printers. Windows uses each device’s PnP-X metadata to correctly categorize and display the device.

If a device manufacturer defines a metadata package for a device and submits the metadata package to Microsoft, Windows automatically downloads it from WMIS when Devices and Printers detects the presence of the device. Windows displays any photorealistic icons for the device and any rich metadata in Devices and Printers. If



the device supports Device Stage, the Device Stage experience for the device is also available.

For more information about how to create device metadata and Device Stage packages, see ”How to Create a Device Metadata Package for Devices and Printers” and ”Windows Device Experience” on the WHDC Web site.

Best PracticesThis section discusses some best practices that you should consider when you develop your Wi-Fi devices.

Simple Wi-Fi Configuration and Boot-to-PairingIn many scenarios, the first thing that a user wants to do with a new Wi-Fi device is connect the user's computer to it. That means the user must configure the device's Wi-Fi settings to connect the device to the user's Wi-Fi network. Also, if the user moves the device to another location or wireless network or if the user's wireless settings change, the device's Wi-Fi settings must be modified so that the device can communicate on the new Wi-Fi network.

The WPS protocol eliminates many consumer complaints about how difficult it is to configure a device's Wi-Fi settings. However, now that WPS makes the actual configuration process simple and easy, consumers are frustrated with how difficult it is to put a device into WPS mode. Many devices place the option to enable WPS mode deep in a menu tree. For some devices it can take 15 or more steps to enable WPS mode. For the typical consumer, this is far too difficult. If the consumer cannot easily place the device into WPS mode, the advantages of the WPS feature are decreased.

Therefore, the device should make entering WPS mode very easy and simple. This can be done by using many methods. You should follow these guidelines when you provide this functionality on your device:

The first-use experience must be very simple. For many consumers this is the first Wi-Fi device that they use, so they might not understand Wi-Fi concepts such as WPS mode. Therefore, the device must intelligently and automatically enter WPS mode. This feature is known as boot-to-pairing:

1. When the device is powered on, it checks for any kind of connectivity, such as USB, Ethernet, or Wi-Fi.

2. If the device does not detect any connectivity it enters WPS mode. It should at least enter PIN WPS mode, but preferably it should go into both PIN and push-button WPS modes.

3. The device remains in WPS mode until either connectivity is established, the user cancels WPS mode, or a time-out occurs.

The user should be able to cancel WPS mode at any time.

The device should include a menu option to disable the boot-to-pairing feature so that, when it is powered on, it does not automatically enter WPS mode.

Manually entering WPS mode must be obvious. Either or both of the following methods for entering WPS mode should be implemented:



The device should include a simple and obvious button that places the device into a WPS configuration mode when the user presses it. The button should be easily discoverable by a user, and its functionality should be clearly identified.

The device should include a menu option that appears on the device's display (if it has one) to enable WPS mode. The menus for the device should be easy to navigate, easy to understand, and no more than two levels deep. For example, an item in the top level of the device’s configuration menu that is called “Easy Wi-Fi Configuration” is good.

Combine PIN and Push-Button WPS ModesConsumers are not typically knowledgeable about technical protocols. Therefore, we recommend that you do not offer the user a choice between PIN and push-button WPS modes. Instead, perform both WPS modes at the same time. Displaying a message of “Enter PIN xxxx or press the button on your router” is a much better user experience than asking users whether they want to use PIN WPS mode or pushbutton WPS mode.

WPS Advertising PerformanceTo minimize unnecessary latencies, Wi-Fi devices should advertise themselves only to access points that have set the Registrar flag. Access points that have set the Registrar flag are actively looking for WPS devices to configure. Skipping access points that do not have this flag set increases the device’s responsiveness in environments that have many access points.

DHCP and Automatic Configuration of IPv4 Link-Local AddressesAll Wi-Fi devices should support Dynamic Host Configuration Protocol (DHCP) as a way to obtain an IP address. The most common scenarios involve Wi-Fi networks that provide DHCP services. However, there are some scenarios in which DHCP is not available and the device still must be assigned an IP address. Therefore, Wi-Fi devices that support IPv4 should also support automatic configuration of an IPv4 link-local address.

For more information about DHCP and automatic configuration of IPv4 link-local addresses, see ”RFC 2131 - Dynamic Host Configuration Protocol” and ”RFC 3927 - Dynamic Configuration of IPv4 Link-Local Addresses” on the IETF Web site.

Quick Network ConnectivityThe time between when a device's Wi-Fi settings are configured by using WPS and when the device is connected to a Wi-Fi network and able to announce its presence on the network by using UPnP and/or DPWS should be as short as possible. When pairing Windows with a device, a customer must wait until Windows discovers the device’s presence on the network. Customers become more anxious and more prone to cancel the process, thinking that the device is faulty if they have to wait a long time for Windows to discover the device. Therefore, you should make every effort to minimize this latency.



Use Finish-Install ActionsIf the installation of your device installs a driver package that includes additional software, the software should be installed after the device is installed by using a finish-install action. This installs the software that is included in the driver package in an administrative process. The software installation runs with elevated credentials that let it register and install the software and display a user interface.

However, if the installation of the software requires access to network resources, such as the device manufacturer's Web site, you should develop an AutoPlay handler and register it by using a co-installer. After the device has completed installation, Windows runs the AutoPlay handler when it detects the arrival of the device's interface.

FeedbackIf you have additional questions or feedback about Rally Vertical Pairing, you can contact us at [email protected].

Resources

Papers and SpecificationsConfiguration Technologies: Windows Connect Now

http://www.microsoft.com/whdc/connect/rally/rallywcn.mspxInstallation and Driver Signing

http://www.microsoft.com/whdc/driver/install/default.mspxDevice Finish-Install Actions in Windows Vista

http://www.microsoft.com/whdc/driver/install/Finish_Install.mspxDiscovery Technologies: PnP-X

http://www.microsoft.com/whdc/connect/rally/rallypnpx.mspxHow to Create a Device Metadata Package for Devices and Printers

http://www.microsoft.com/whdc/device/DeviceExperience/CreateDevMetadataPkg.mspxMultifunction Device Support and Device Container Groupings in Windows 7

http://www.microsoft.com/whdc/Device/DeviceExperience/ContainerIDs.mspxPnP-X: Plug and Play Extensions for Windows Specification

http://www.microsoft.com/whdc/connect/Rally/pnpx-spec.mspxUniversal Plug and Play

http://www.microsoft.com/whdc/device/media/upnp.mspx Windows Connect Now-NET Specification

http://www.microsoft.com/whdc/connect/Rally/WCN-Netspec.mspxWeb Services on Devices (DPWS)

http://www.microsoft.com/whdc/connect/rally/rallywsd.mspxWindows Device Experience

http://www.microsoft.com/whdc/device/DeviceExperience/default.mspx


http://www.microsoft.com/whdc/device/DeviceExperience/default.mspx

http://www.microsoft.com/whdc/connect/rally/rallywsd.mspx

http://www.microsoft.com/whdc/connect/Rally/WCN-Netspec.mspx

http://www.microsoft.com/whdc/device/media/upnp.mspx

http://www.microsoft.com/whdc/connect/Rally/pnpx-spec.mspx

http://www.microsoft.com/whdc/Device/DeviceExperience/ContainerIDs.mspx

http://www.microsoft.com/whdc/device/DeviceExperience/CreateDevMetadataPkg.mspx

http://www.microsoft.com/whdc/connect/rally/rallypnpx.mspx

http://www.microsoft.com/whdc/driver/install/Finish_Install.mspx

http://www.microsoft.com/whdc/driver/install/default.mspx

http://www.microsoft.com/whdc/connect/rally/rallywcn.mspx

mailto:[email protected]


Windows Driver KitDevice and Driver Installation

http://msdn.microsoft.com/en-us/library/aa972910.aspxDriver Packages

http://msdn.microsoft.com/en-us/library/dd406684.aspxFinish-Install Actions (Windows Vista and Later)

http://msdn.microsoft.com/en-us/library/aa477001.aspxINF Files

http://msdn.microsoft.com/en-us/library/dd406703.aspxINF File Sections and Directives

http://msdn.microsoft.com/en-us/library/ms794346.aspxWriting a Co-installer

http://msdn.microsoft.com/en-us/library/ms790151.aspx

ArticlesAutoplay in Windows XP: Automatically Detect and React to New Devices on a System

http://msdn.microsoft.com/en-us/magazine/cc301341.aspx

Network ProtocolsRFC 2131 - Dynamic Host Configuration Protocol

http://tools.ietf.org/html/rfc2131

RFC 3927 - Dynamic Configuration of IPv4 Link-Local Addresseshttp://tools.ietf.org/html/rfc3927

OrganizationsWi-Fi Alliance

http://www.wi-fi.org/

IEEEhttp://www.ieee.org/


http://www.ieee.org/

http://www.wi-fi.org/



http://msdn.microsoft.com/en-us/magazine/cc301341.aspx



http://msdn.microsoft.com/en-us/library/dd406703.aspx

http://msdn.microsoft.com/en-us/library/aa477001.aspx

http://msdn.microsoft.com/en-us/library/dd406684.aspx

http://msdn.microsoft.com/en-us/library/aa972910.aspx

introductiondownload.microsoft.com/.../wifiverticalpair.docx · web viewusing windows rally...

Documents