# Sensor Driver Skeleton Sample

[This is preliminary documentation and subject to change.]

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 to start your own sensor driver projects. You can find the Skeleton sample in the folder named SensorsAndLocation.

## 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 noteworthy classes.

Class | Files | Descripton
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 SensorDdi.cpp | Provides an implementation for the sensor driver callback interface, ISensorDriver.
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.
WpdObjectProperties | WpdObjectProperties.h WpdObjectProperties.cpp | Handles WPD property value requests. This class emulates accessing a device that includes a temperatue sensor and a GPS sensor. When requests for data are received in CSensorDdi, the driver calls through to WpdObjectProperties. WpdObjectProperties returns a preset value for each request. The header file 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.

## 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 SkeletonSensor.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 SkeletonSensor.rc to match the new RC file name.

3. In the NTTARGETFILE0 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 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 wpdObjectProperties.h to contain the correct values for your device. Update the code in wpdObjectProperties.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 UMDFSkeleton_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 dllsup.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.

## 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 install the sensor Skeleton sample for testing in the same way you install 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 two coninstaller DLL files (either checked or free) from the redist/wdf/processor_type folder where you installed the WDK. Copy these files to the folder you created in step 3. For example, if you installed the WDK on your C: drive, you might copy WdfCoInstaller01009.dll and 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. For example, for a sensor named WDKExample, you would type:

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

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