Sensor Driver Skeleton Sample

The Sensor Driver Skeleton Sample demonstrates how to write a minimal sensor driver and shows best practices, including how to use the sensor class extension. You can use this driver as a template from which you can start your own sensor driver projects. You can find the Skeleton sample in the folder named SensorsAndLocation\SensorSkeleton.

Theory of Operation

The sensor Skeleton driver is based upon the UMDF Skeleton driver sample. The sample uses Active Template Library (ATL) to provide COM functionality. The Skeleton driver defines and uses the following classes.

Class	Files	Description
CMyDriver	Driver.h Driver.cpp	Provides an implementation for IDriverEntry. The OnDeviceAdd method creates an instance of the CMyDevice class.
CMyDevice	Device.h Device.cpp	Provides an implementation for IPnPCallbackHardware. The OnPrepareHardware method creates and initializes the sensor class extension and creates an instance of the CSensorDdi class. The OnReleaseHardware method uninitializes and frees the class extension object. Implements IFileCallbackCleanup::OnCleanupFile, which notifies the sensor class extension when the file handle to the device is closed.
CSensorDdi	SensorDdi.h Defines.h SensorDdi.cpp	Provides an implementation for the sensor driver callback interface, ISensorDriver. This class emulates accessing a device that includes a temperatue sensor and a GPS sensor. The header file named Defines.h contains defined constants that correspond to device property values, such as the friendly name string that displays in Control Panel. You should change these values to contain your own values. You should also change the implementation in the .cpp file to handle your device's values.
CMyQueue	Queue.h Queue.cpp	Provides an implementation for IQueueCallbackDeviceIoControl. The Initialize method creates an instance of the I/O queue for the device. The OnDeviceIoControl method manages forwarding WPD I/O requests to the sensor class extension.

 

Customizing the Sample

To create a new driver that is based on the sensor Skeleton sample, do the following:

1. Copy all the project files to a new directory.

2. Rename SensorSkeleton.rc, SensorSkeleton.ctl, SensorSkeleton.idl, SensorSkelton.def, and SensorSkeleton.inx to appropriate names for your driver.

3. Update the sources file as follows:

   1. Change the TARGETNAME to the name of the new driver.
   2. In the SOURCES variable, change SensorSkeleton.rc to match the new RC file name and change SensorSkeleton.idl to match the new IDL file name.
   3. In the NTTARGETFILES variable, change the INF file name to match the new name.
   4. Change value for DLLDEF to match the new DEF file name.

4. Update the strings in the RC file to match the new driver name.

5. In the DEF file, change the LIBRARY value to the new driver library name. This name must match the value you provided for TARGETNAME.

6. In Internal.h:

   1. Update the WPP tracing control GUID at WPP_DEFINE_CONTROL_GUID. You can generate a new GUID by using the uuidgen or guidgen tools in the Microsoft Windows SDK. Be sure to match the format for the new GUID to the existing one.
   2. Change the SensorsSkeletonDriverTraceControl string to use the name of your driver.
   3. Change the driver tracing ID (choose a string that should be unique to your driver) at MYDRIVER_TRACING_ID.

7. Update the IDL file as follows:

   1. Generate a new GUID and change the type library GUID.
   2. Generate a new GUID and change the driver class ID. You must use this class ID again (in registry format) in later steps.
   3. Change the name of the library.
   4. Change the name of the coclass.
   5. Change the help strings.

8. In SensorSkeleton.ctl, change the WPP tracing control GUID and tracing ID to match the changes you made in step 6.

9. Update the constant definitions in Defines.h to contain the correct values for your device. Update the code in SensorDdi.cpp to handle the correct values for your device.

10. Update the INX file, as follows:

    1. Change the device's hardware ID in the [Microsoft.NT$ARCH$] section.
    2. Change the binary name from SensorSkeleton.dll to the name for your driver everywhere it appears in the file.
    3. Change the DriverCLSID value set in the UMDFSensorSkeleton_Install section to match your new driver's class ID.
    4. Update the strings at the bottom of the file to contain descriptions of your new driver.
    5. Change the provider name in the [Version] section to match your company, and update the device's class ID to the installation class of your device.
    6. (Optional) Replace SensorSkeleton with the name of your driver in all of the INF section names and strings names. For example, you can replace SensorSkeletonDeviceName with MySensorDriverDeviceName.

11. Change the name of the driver module in DllMain.cpp.

12. Update Driver.h as follows:

    1. Change public CComCoClass<CMyDriver, &CLSID_SensorsSkeletonDriver> to contain the correct constant for your driver's class. The MIDL compiler generates this constant from the coclass name you provided in the IDL file.
    2. Change the first parameter to OBJECT_ENTRY_AUTO to contain the new driver's class name.

13. Update Driver.cpp to reference the new header file name that is generated by the IDL instead of SensorSkeleton.h.

Implementation and Design

This sample can be used as the basis for a new sensor driver.

Building the Sample

1. At the command prompt, change to the directory that contains the device source code.

2. Run build -ceZ, or use the BLD macro.

If the build succeeds, you will find the driver DLL and INF files in a subdirectory of your project directory. For example, if you build by using an x86fre build, the DLL and INF files will be placed in projectDirectory\.objfre_win7_x86\i386.

If the build fails, you can find errors and warnings in the log file (for example, buildfre_win7_x86.log).

Installation

You can install the sensor Skeleton sample for testing in the same way as you installed the UMDF Skeleton sample driver. For more information, see Installing UMDF Drivers.

To install the sensor Skeleton sample driver:

1. Ensure that the driver builds without errors.

2. Copy the DLL and INF files to a separate folder.

3. Locate the co-installer DLL file (either checked or free) from the redist/wdf/processor_type folder where you installed the WDK. Copy this file to the folder you created in step 2. For example, if you installed the WDK on your C: drive, you might copy WUDFUpdate_01009.dll from C:\WinDDK\build#\redist\wdf\x86.

4. Run Devcon.exe. You can find this program in the tools\devcon folder where you installed the WDK. Type the following command in the command window:

   devcon.exe install SensorSkeleton.inf "Sensors\SensorSkeleton"

5. Enable the driver in the Location and Other Sensors control panel.

Related topics

Writing a Sensor Device Driver

 

 

Send comments about this topic to Microsoft

Build date: 9/7/2011