Windows SideShow : Using the Universal Driver to Implement Devices

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 SideShowcompatible 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 Device Device Driver Bitmap or text display Custom Windows SideShow Platform Microprocessor-based Universal .NET Micro Framework solution

5. Device Firmware Components Message transport Display Shell Endpoints Message processor Endpoints Content cache 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 31 16 0 header size (bytes) error packet type payload sequence number ACK/NAK flag (0 = ACK, 1 = NAK) response flag (0 = command, 1 = response) 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

11. Device Query Commands

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

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

16. User Assignment Sequence PC Device Query current user Return current user or console user SID (assigned user model) 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

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

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

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

27. Specific Transport Requirements • USB • Bluetooth • TCP/IP

28. USB Transport Requirements

29. USB Transport Requirements (cont.)

30. Bluetooth Transport Requirements

31. Bluetooth Transport Requirements (cont.)

32. TCP/IP Transport Requirements

33. TCP/IP Transport Requirements (cont.)

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: • SideShowResources 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

37. Appendix A: Standard Device Capabilities

38. Appendix B: Bluetooth Service ID Example SideShow service ID {5d9dda39-1e82-49c7-a0d6-6507ba9287ef} Device MAC address0x00081b00881c Driver customservice ID {5d9dda39-1e82-49c7-1c88-001b0800873f} Service ID in memory39 da 9d 5d 82 1e c7 49 1c 88 00 1b 08 0087 ef Insert device address to generate a device-specific service ID