Windows SideShow:

Using the Universal Driver to Implement Devices

Rick SwaneySenior Software Design EngineerPC|3

Agenda

• Present options for developing a Windows SideShow compatible device

• Describe the universal driver• Describe universal wire protocol and packet format• Discuss the required handling of each command packet• Discuss the device requirements for specific transports• Questions

Device Development Options

Windows SideShow Platform

Custom

Universal

Bitmap or text display

Device DriverDevice

Microprocessor-based

.NET Micro Framework solution

Device Firmware Components

Message transport

Message processor

Shell

Content cache

EndpointsEndpoints

Display

Input Device

Universal Driver

• Built on Windows user-mode driver framework (UMDF)• Structured as a common framework with multiple transport-

level components• Supports multiple transport types

• USB• Bluetooth• TCP/IP• SSL over TCP/IP

• Uses a published wire protocol• Is extensible through pass-through input/output control code

(IOCTL)

Packet Format

size (bytes)

sequence number

31 0

response flag (0 = command, 1 = response)

packet typeerror

ACK/NAK flag (0 = ACK, 1 = NAK)

header

payload

16

Payload format is determined by the packet typeStrings are 16-bit Unicode with no terminating nullStrings and arrays are preceded by an element count

Message Protocol

• First message must be a SYNC command from the PC• Resets sequence numbers• Verifies protocol version

• Following a SYNC, either side can initiate an exchange• Every command message requires a response

• Response header must match the command type and sequence number

• An invalid command should produce a NAK response

• Command sequence numbers must be consecutive• Each side maintains its own sequence number• An out-of-sequence command must produce a NAK response

Message Protocol (cont.)

• A device must be able to process incoming commands while waiting for a response

• Depending on the underlying transport, a device might have to scan payload bytes for a SYNC command pattern

Command Packet Functions

Device Gadget

Initiate device communication Configure connected gadgets

Query device information Send gadget content

Configure device settings Display user notifications

Assign current user Send events to gadgets

Extend device functionality

Device Query Commands

Query command Response data

GetDeviceName User-friendly device name

GetDeviceManufacturer Name of device manufacturer

GetDeviceFirmwareVersion Firmware version string

GetSupportedEndpoints List of implemented endpoint identifiers

GetCapabilites Value of requested device capability

Device Capabilities

• A device capability is defined by a property key (GUID + index)

• The value is reported as a PropVariant• Standard device capabilities are defined by Microsoft• An OEM can define custom property groups

Device Settings Commands

Message Purpose

SetTimeZone Sets the time zone information (TIME_ZONE_INFORMATION)

SetTime Set current time (UTC)

SetLanguage Sets the language, culture, and font size for the user interface (example: “en-US:2”)

SetShortDateFormatSetLongDateFormat

Sets the user’s preferred date formats (example: “MM/DD/YY”)

SetShortTimeFormatSetLongTimeFormat

Sets the user’s preferred time formats (example: “hh:mm”)

User Assignment Models

• Two user models• Console user: device is assigned to the current interactive

user• Assigned user: device can be assigned to any logged-on user

• An assigned-user device must implement the user selection • Maintains a list of logged-on users• Provides a user interface for switching users

• Users are identified by their security identifiers (SID)• A console user is identified by SID (S-1-5-4)• A null user is identified by SID (S-1-0-0)

• A device must support a single model

User Control Commands

Command Purpose

GetCurrentUser Get the ID of the current user

SetCurrentUser Change the current user

SetUserState Report a change to the set of users currently logged on

ChangeUserRequest (to PC) Requests the PC to assign a user to the device

User Assignment Sequence

Query current user

Return current user or console user SID

PC

(assigned user model)

DeviceReport user log-in or log-out

Request current user change

Set current user

Configuring Gadgets

• Connecting a gadget associates it with a specific endpoint type• Both components are specified by GUIDs• Each gadget is associated with a separate endpoint instance

• The connection allows a gadget to send content to the endpoint• A device optionally creates a cache for the content

• The connection command provides gadget metadata• Name• Icons (16x16, 32x32, 48x48)• Cache policy• Online-only attribute

Gadget Configuration Commands

Message Purpose

AddApplication Connects a gadget to a device endpoint

DeleteApplication Disconnects a gadget and clears its content and notifications

DeleteAllApplications Disconnects all gadgets and clears all content and notifications

GetApplicationOrder Gets the gadget display order

SetApplicationOrder Sets the gadget display order

GetPreEnabledApplications Gets a list of the gadgets to enable by default

Pre-enabled Gadgets

• A device can specify a list of gadgets to be enabled by default

• The user does not need to go to Windows SideShow Control Panel to enable these gadgets

• A pre-enabled gadget is a good choice if your device is closely associated with a gadget• Example: a Windows Media Center Edition (MCE) remote

control and an MCE gadget

Content Items

• A content item is a unit of data formatted by a gadget for a specific endpoint • Typically represents a single page of viewable information• Can be any unit of information, such as an appointment or contact

• Each content item has a unique content ID (32-bit unsigned integer)• The endpoint defines the ID semantics

• Content ID zero is reserved for plain text glance data• Glance data is primary or summary data for the gadget, which is

displayed on the device’s home page

• Most devices cache content items so that they are viewable when the PC is off

Content Control Commands

• Sets the display order of the connected gadgets

• AddContentItem• DeleteContentItem• DeleteAllContentItems

Message Purpose

AddContentItem Sends a content item to an endpoint

DeleteContentItem Deletes a previously sent content item

DeleteAllContent Deletes all content items sent to an endpoint

ContentMissing (to PC) Requests a content item from a gadget

User Notifications

• A notification is a timely message that appears to the user• Typically displayed in a pop-up window• A notification command specifies

• Source gadget• Notification title• Message text• Optional icon• Expiration time (64-bit FILETIME )

• Enable command allows a user to enable or disable notifications from the PC

User Notification Commands

Message Purpose

AddNotification Displays or updates a user notification

DeleteNotification Dismisses and deletes a notification

DeleteAllNotifications Deletes all notifications from a specific gadget

SetNotificationsEnabled Enables or disables notification pop-ups

Application Event Command

• An application event is a message sent from an endpoint to a gadget

• It notifies the gadget of a user action such as a button press, menu selection, or page navigation

• An event command includes:• Endpoint ID• Gadget ID• Event type identifier• Event data

• An endpoint defines the event types and data formats it can send

• Microsoft reserves a range of event types for common events

Pass-Through Command

• Allows arbitrary data to be sent and received• Driver passes data as an opaque binary object

• Implemented as a buffered read/write IOCTL• Is the only mechanism for an application other than a

gadget to communicate with the device

Other Commands

Message Purpose

Ping Tests the connection between the device and PC

Reset Commands the device to reboot

Specific Transport Requirements

• USB• Bluetooth• TCP/IP

USB Transport Requirements

Requirement Detail

Hardware ID • Ensure that each device model has a unique hardware ID• Typically a vendor ID (VID) followed by a

product ID (PID)

Microsoft OS Descriptor (MOD)

• Use the extended compatible ID feature to indicate the device is compatible with the universal driver• Compatible ID: SIDESHW• Subcompatible ID: UNIV1

USB Version • Must support USB version 2.0 to use MODs• Can specify a 2.0 USB descriptor for a

version 1.1 device

USB Transport Requirements (cont.)

Requirement Detail

Interface and endpoints • Expose a single interface with two endpoints• Bulk-in: address 0x81• Bulk-out: address 0x02

• Make the maximum packet size as large as possible

Serial number • Ensure that each device has a unique serial number

Manufacturer and product name • Supply accurate, descriptive names

USB Selective Suspend feature • Provide maximum power savings for battery-driven PCs

Bluetooth Transport Requirements

Requirement Detail

Support required protocols • Bluetooth Radio Frequency Communications (RFCOMM)• Logical Link Control and Adaptation

Protocol (L2CAP)Publish a Service Discovery Protocol (SDP) record

• The published SDP must specify the Windows SideShow service ID

Recognize a unique SDP published by the driver

• The driver publishes a unique service ID for its associated device• The ID contains the device’s MAC address• The device must match its address to

identify the correct service

Bluetooth Transport Requirements (cont.)

Requirement Detail

Provide user interface for Bluetooth pairing

• The device must be paired with the PC to load the Windows SideShow driver

Act as a client to the PC server • The device must open and close the connection to the PC when necessary• This preserves battery life by using the

radio only when necessary

TCP/IP Transport Requirements

Requirement DetailSupport required protocols • The device can use IPV4 or IPV6

Support Plug and Play Extensions for Windows (PnP-X)

• The device must be discoverable• Network discovery in Windows Vista must

be enabled• The user uses Network Explorer to install

the deviceUse a SideShow compatible ID • PnP-X uses compatible IDs to identify

devices and locate the matching driver• SideShow Compatible IDs are

• PnPX_WindowsSideShow_CPID• PnPX_WindowsSideShow_SSL_CPID

TCP/IP Transport Requirements (cont.)

Requirement DetailSpecify the SideShow device category

• Full category name is Displays.WindowsSideShow

Act as server to the PC client • Device broadcasts its presence when it’s ready to connect• PnP-X initializes the driver, which then

attempts to connect to the device Encrypted communication (optional) • Transport must use SSL/TLS protocol

• Device must provide an X.509 certificate (may be self-signed)

Resources

Windows Driver Kit: • Windows SideShow Specifications/Guidelines

http://go.microsoft.com/fwlink/?LinkId=128397

Microsoft Download Center• Windows SideShow Device Simulator

http://go.microsoft.com/fwlink/?LinkId=128399

MDSN• Simple Content Format Reference

http://go.microsoft.com/fwlink/?LinkId=128400

Resources (cont.)

WHDC Web Site:• SideShow Resources

http://go.microsoft.com/fwlink/?LinkId=128403• Universal Driver Protocol Specification

http://go.microsoft.com/fwlink/?LinkId=128398 • Microsoft OS Descriptors

http://go.microsoft.com/fwlink/?LinkId=128401• PNP-X: Plug and Play Extensions for Windows Specification

http://go.microsoft.com/fwlink/?LinkId=128402

Related Sessions

Session Name Time

Windows SideShow: Tips and Tricks for Building Great Devices

Wed. 9:45-10:45

Windows SideShow: Building Low-Cost Devices Mon. 2:45-3:45 and

Wed. 2:45-3:45

Appendix A: Standard Device Capabilities

Capability Example

Screen type bitmap

Screen size 320x240

Color type and depth grayscale, 8bpp

Client screen area 312x220

Data cache true

Supported languages “en-US:2;fr-FR:2;ja-JP:1”

Supported image formats “image/bmp;image/jpeg”

Device icons .ico file

Appendix B: Bluetooth Service ID Example

SideShow service ID {5d9dda39-1e82-49c7-a0d6-6507ba9287ef}Device MAC address 0x00081b00881c

Driver custom service ID {5d9dda39-1e82-49c7-1c88-001b0800873f}Service ID in memory 39 da 9d 5d 82 1e c7 49 1c 88 00 1b 08 00 87 ef

Insert device address to generate a device-specific service ID