The Windows 7 Sensor and Location platform enables your computer and applications to adapt to their current environment and change the way they look, feel, or behave. For example, imagine an application that uses a light sensor and so can change the brightness and contrast of its displayed content based on the differing amounts of indoor and outdoor light. Or an application that uses location sensors and so can know their current location, enabling many different scenarios, such as automatic content localization and location base services.
The Sensor and Location platform provides a standard way to integrate sensor and location devices with Windows 7, and provides a standard programming model for applications to take advantage of these devices. Hardware manufacturers can learn how to write sensor and location drivers by installing the Windows 7 WDK. Developers can learn how to write location-aware and sensor-enabled applications by installing the Windows 7 Beta SDK.
Some may ask, why use the Windows 7 Sensor and Location Platform? To answer that question, we need to understand that most of the applications that we use on a daily basis were designed for “normal” environmental conditions, for example, under indoor standard lighting conditions. However, nowadays laptops offer higher mobility than ever before, allowing us to use them in different locations with different environmental conditions, switching from bright outdoor light into darker indoor light. Wouldn’t it be nice to have an application that adjusts its look, feel, and behavior to the change in the environment? Ambient light sensors, for example, can allow your computer to automatically adjust your screen's brightness based on the current lighting conditions. Furthermore, developers can also enable applications to optimize their content for readability, making your application easier to use in a range of different operating environments.
For example, the following image shows an updated version of the MSDN Reader. This version of the MSDN Reader changes the way the application looks depending upon the amount of light the Ambient Light Sensor detects. On the left is how the application displays under normal indoor light. On the right is how the application displays under outdoor light. On the right, you can see that the application reduces the use of colors to increase contrast and increases the font size, making the displayed content (the actual text displayed) of the application more readable under the brighter lighting conditions. I used the Virtual Light Simulator application that ships with the Windows 7 Beta SDK; you can find it in the Program Files\Microsoft SDKs\Windows\v7.0\Bin\VirtualLightSensor.exe when you install the Windows 7 beta SDK. So you can actually download the sample and install the SDK and try this on your own Windows 7 computer - it is kind of cool. Note that when you launch the Virtual Light Sensor application, you’ll have to go to your computer Device Manager and search for drivers (use the same directory as above) in order to install the unsigned Virtual Light driver. After that, the tool will work.
The Windows 7 Beta SDK provides tools, documentation, and examples for writing drivers for sensor devices as well as using the Sensor and Location platform in building Windows 7 applications. As is true for most Windows 7 APIs, the Sensor and Location API is native. There are some examples in the SDK that display managed code applications using a very thin interop layer. However, this Windows 7 Sensor and Location .NET Interop Sample Library offers a broader and more “.NET-like” programming model with strongly typed objects and an easy extensibility model for sensor and data reports.
Let’s review the Windows 7 Sensor and Location .NET Interop Sample Library architecture and note the important classes.
To start working with sensors, you must first obtain one. You can do this using the SensorManager class whose main purpose in life is to expose sensor classes (for example light and accelerometer sensor classes) to the developer. Using the SensorManager, developers can:
- Get an array of sensors by CategoryID. CategoryID is a GUID that defines a well-known specific class of sensors such as Light Sensors, Accelerometer Sensors, Motion Sensors, or Location. You can find the complete list of well known sensors in the SensorCategories class and in the SDK.
- Get an array of sensors by TypeID. TypeID is a specific type of a sensor that is related to a specific class of sensors. For example, Type of LocationGPS is part of the Location Sensors class, and Accelerometer3d and Accelerometer2d are related to the Accelerometer Sensors class. You can find the complete list of sensor Types in the SensorCategories class.
|  |
- Get a specific Sensor using the sensor's GUID
- GetAllSensors, which retrieves all the sensors that are in the register. You can use any sensors from that list as long as you have permission to do so. The end user will have to enable each sensor for the application to use.
- Show the permission dialog box to provide users with a way to enable sensors.
- Notify the application of a sensor's availability with the SensorAttached event.
Once you have obtained a sensor from the SensorManager, the application can retrieve data using a SensorDataReport class, which is an abstract base class for all DataReports. For a sensor to be useful, it must provide meaningful data. The amount, frequency, and type of data generation vary from sensor to sensor. For example, a sensor that detects whether or not a door is open would generate a small amount of Boolean data, while a motion sensor might continuously generate multiple data items. To standardize the way your program receives data, the native Sensor API uses the sensor data report object.
You can access the information in a sensor data report through the native API that has the ISensorDataReport interface. This interface lets you retrieve the data report’s time stamp so you can determine whether the information in the report is useful. You can retrieve the data itself in two ways: as an individual data field value or as a set of values. To retrieve data as an individual value, call the GetSensorValue method. To retrieve multiple values, call the GetSensorValues method. You specify the type of data, or data fields, you want to retrieve from the report by using a PROPERTYKEY structure. It may be easy for native code developers to use this programming model. However, beside the fact that it is hard to access from managed code, it lacks key features like strong type, since each sensor has different data fields. Therefore, one of our goals is to create a strong typed .NET class for each sensor and for each sensor data report, enabling easy binding to the .NET property system.
The managed code SensorDataReport is the base class for sensor type-tailored data reports (for example, Accelerometer3DReport). When developers implement support for a custom sensor, they usually create a set of two classes: a Sensor-derived class, and a SensorDataReport-derived class. The SensorDataReport provides base methods, such as querying a property by PropertyKey, which are intended to be overridden by type-safe properties in derived classes (for example, AxisY_G - float in Accelerometer3DReport).
The follow diagram illustrates three derived data report classes that we implemented in the Windows 7 Sensor and Location .NET Interop Sample Library. An Accelerometer3DDataReport, an AmbientLightSensorDataReport, and a BooleanSwitchArrayDataReport.
We also implemented a LatLongLocationReport and a CivicAddressLocationReport that you can find under the Location Providers in the Windows 7 Sensor and Location .NET Interop Sample Library.
Let’s examine few lines of code that illustrate the process of reading the amount of light by using the AmbientLightSensor sensor and data report. To do so, a developer will need to:
1. Get an AmbientLightSensor class from the SensorManager
2. Get a data report from the AmbientLightSensor class. Note that GetDataReport returns a generic SensorDataReport
The following code snippet shows how you can obtain a light sensor from the SensorManager and use that light sensor to get an AmbientLightSensorDataReport.
//obtain a light sensor
AmbientLightSensor[] lightSensors =
SensorManager.GetSensorsByType<AmbientLightSensor>();
if (lightSensors.Length > 0)
{
_lightSensor = lightSensors[0];
_lightSensor.ReportInterval = _lightSensor.MinReportInterval;
}
…
//use the light sensor to get en AmbientLightSensorDataReport
AmbientLightSensorDataReport lightReport =
(AmbientLightSensorDataReport)_lightSensor.GetDataReport();
//Get the lux value from that date report
_illuminanceLux = lightReport.IlluminanceLux;
Developers can do a lot more with a given sensor then just retrieve a data report. The Sensor base abstract class contains a comprehensive set of properties that provide general info like FriendlyName, SensorDescription, SensorID, SensorSerialNumber, and SensorState. There are also specific properties such as ReportInterval to set the intervals between each time a sensor device generates a report, and MinReportInterval to set the minimum time between reports. In addition, the Sensor class exposes a set of events including DataUpdated that is triggered when a new data report is ready, and OnStateChanged that is triggered when the sensor state has changed. The Sensor class exposes additional properties that you are welcome to explore. The ISensorEventsInternal diagram shows the Sensor class and three derived classes we created for the Sensors and Location Managed Library Sample.
Enabling Sensors
For each installed sensor the end user will have to enable it for use. Users can do so from the Location and Other Sensors located in the Control Panel. Application can also display the same dialog by calling the proper API. The following image shows the sensors I have installed on my dev machine
The Sensor and Location Managed Library Sample includes two demos: the MSDN Reader and Marble Sample. The latter is an XNA application that requires you to download the XNA Game Studio 3.0. This demo shows how to use the Accelerometer3D sensors. The MSDN Reader uses the AmbientLightSensor to change the size and color of the fonts in the reader.
In a future post, we will further explore the architecture we chose for the Windows 7 Sensor and Location .NET Interop Sample Library and expand your understanding of how to create your own set of sensors.
Dima Zurbalev contributed to this post.