DSF USB Keyboard Samples

Description

The DSF USB keyboard sample is split into two pieces--a generic HID device and a keyboard. Both of these pieces show how a HID device interacts with the Device Simulation Framework (DSF). The generic device shows how a device interacts with DSF, and the keyboard device shows how to build a HID simulator on top of the generic device.

Theory of Operation

The keyboard sample is split into two different executable files--InputKbd.dll and SoftHIDDevice.dll. This organization gives the code greater flexibility because any HID Class device can use the SoftHIDDevice.dll as a base and just implement the device-specific code in its own executable. For example, you can write a mouse simulator on top of the HIDDevice, which takes care of all of the HID Class Specific USB protocol messages. The simulator just needs to implement the device and vendor-specific messages. For example, the keyboard has to implement LED indication for CAPS LOCK key and also has to handle the key presses for the device.

Implementation and Design

Use this sample to develop DSF HID simulators.

Building the Sample

You can compile the sample code from the Microsoft Windows Driver Kit (WDK) build environment.

To compile by using the WDK build environment, navigate to the src\Test\DSF\USB\InputKbd directory and run build -cZP. Then, navigate to the src\Test\DSF\USB\SoftHidDevice directory and run build -cZP.

Installation

General

Before running the test script, you must install a simulated USB controller on the target system. To install the simulated EHCI controller, run softehcicfg.exe /install.

The simulated ECHI controller will appear in Device Manager under DSFRoot. You should wait for this enumeration to complete before you plug the simulated devices into the root hub.

To run the script, open a Command Prompt window, navigate to the Program Files\dsf\usbhid directory, and run cscript Create1.1Kbd.wsf. You should then follow the instructions on the command line. These instructions tell you to open a new Command Prompt window to run cscript Use1.1Kbd.wsf (also in the Program Files\dsf\usbhid directory).

The Create1.1Kbd script creates and plugs in a new simulated USB hub to the root hub. The Create1.1Kbd script then creates a new keyboard device that is plugged into the simulated hub that was just created. All USB 1.0 devices that are simulated with DSF must be plugged in via a simulated USB hub. Only USB 2.0 devices can be plugged in directly to the root hub. The system informs the user that a new HID class device is found and that the device is a Microsoft Natural Keyboard. The system then loads the appropriate drivers for the device. The Create1.1Kbd script prompts the user to continue at each step. When both the hub and keyboard devices are fully enumerated, the Create1.1Kbd script prompts the user to run the Use1.1Kbd.wsf script. The Use1.1Kbd.wsf script generates HID reports of key presses sent by the keyboard. If you have the Command Prompt window in focus, you will see the text "Hello World" appear.

End User

To use the version of the code that you have compiled, simply replace the DLLs that are loaded when DSF is installed on the target system. The files are located in Program Files\dsf\usbhid. Replace both InputKbd.dll and SoftHIDDevice.dll. You do not need to register these files because that operation is performed when DSF is installed.

Code Tour

File Manifest

File Description

softhidevice.dll Inputkbd.dll

DSF HID Device simulators

Send comments about this topic to Microsoft

Build date: 9/21/2010