2. Windows SideShow: Using the Universal Driver to Implement Devices Rick Swaney Senior Software Design Engineer PC|3

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

4. Device Development Options Windows SideShow Platform Custom Universal Bitmap or text display Device Driver Device Microprocessor-based.NET Micro Framework solution

5. Device Firmware Components Message transport Message processor Shell Content cache Endpoints Display Input Device

6. 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)

7. Packet Format size (bytes) sequence number 310 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 type Strings are 16-bit Unicode with no terminating null Strings and arrays are preceded by an element count

8. 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

9. 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

10. Command Packet Functions DeviceGadget Initiate device communicationConfigure connected gadgets Query device informationSend gadget content Configure device settingsDisplay user notifications Assign current userSend events to gadgets Extend device functionality

11. Device Query Commands Query commandResponse data GetDeviceNameUser-friendly device name GetDeviceManufacturerName of device manufacturer GetDeviceFirmwareVersionFirmware version string GetSupportedEndpointsList of implemented endpoint identifiers GetCapabilitesValue of requested device capability

12. 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

13. Device Settings Commands MessagePurpose SetTimeZoneSets the time zone information (TIME_ZONE_INFORMATION) SetTimeSet current time (UTC) SetLanguageSets the language, culture, and font size for the user interface (example: “en-US:2”) SetShortDateFormat SetLongDateFormat Sets the user’s preferred date formats (example: “MM/DD/YY”) SetShortTimeFormat SetLongTimeFormat Sets the user’s preferred time formats (example: “hh:mm”)

14. 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

15. User Control Commands CommandPurpose GetCurrentUserGet the ID of the current user SetCurrentUserChange the current user SetUserStateReport a change to the set of users currently logged on ChangeUserRequest (to PC)Requests the PC to assign a user to the device

16. User Assignment Sequence Query current user Return current user or console user SID PC (assigned user model) Device Report user log-in or log-out Request current user change Set current user

17. 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

18. Gadget Configuration Commands MessagePurpose AddApplicationConnects a gadget to a device endpoint DeleteApplicationDisconnects a gadget and clears its content and notifications DeleteAllApplicationsDisconnects all gadgets and clears all content and notifications GetApplicationOrderGets the gadget display order SetApplicationOrderSets the gadget display order GetPreEnabledApplicationsGets a list of the gadgets to enable by default

19. 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

20. 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

21. Content Control Commands Sets the display order of the connected gadgets AddContentItem DeleteContentItem DeleteAllContentItems MessagePurpose AddContentItemSends a content item to an endpoint DeleteContentItemDeletes a previously sent content item DeleteAllContentDeletes all content items sent to an endpoint ContentMissing (to PC)Requests a content item from a gadget

22. 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

23. User Notification Commands MessagePurpose AddNotificationDisplays or updates a user notification DeleteNotificationDismisses and deletes a notification DeleteAllNotificationsDeletes all notifications from a specific gadget SetNotificationsEnabledEnables or disables notification pop-ups

24. 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

25. 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

26. Other Commands MessagePurpose PingTests the connection between the device and PC ResetCommands the device to reboot

27. Specific Transport Requirements USB Bluetooth TCP/IP

28. USB Transport Requirements RequirementDetail 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

29. USB Transport Requirements (cont.) RequirementDetail 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

30. Bluetooth Transport Requirements RequirementDetail 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

31. Bluetooth Transport Requirements (cont.) RequirementDetail 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

32. TCP/IP Transport Requirements RequirementDetail Support 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 device Use 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

33. TCP/IP Transport Requirements (cont.) RequirementDetail Specify 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)

34. 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

35. 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

36. Related Sessions Session NameTime Windows SideShow: Tips and Tricks for Building Great Devices Wed. 9:45-10:45 Windows SideShow: Building Low-Cost DevicesMon. 2:45-3:45 and Wed. 2:45-3:45

37. Appendix A: Standard Device Capabilities CapabilityExample Screen typebitmap Screen size320x240 Color type and depthgrayscale, 8bpp Client screen area312x220 Data cachetrue Supported languages“en-US:2;fr-FR:2;ja-JP:1” Supported image formats“image/bmp;image/jpeg” Device icons.ico file

38. 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