The XNA Game Studio is designed to work with Microsoft Visual Studio—and allows you to write games in C#.

If Visual Studio 2008 is installed on your PC, you can download XNA Game Studio 3.1 from the XNA creator’s club site. And, once you download the Game Studio, you’ll find a sample game under the …\Visual Studio 2008\Templates\ProjectTemplates\Visual C#\XNA Game Studio 3.0 folder. This sample game, RacingGameWindows, is a complete auto racing game that runs on a PC or the Xbox 360. The game allows the user to customize their car, to choose the level of difficulty for the track, and to race a pace car. The game includes rich sound and lighting features. And, the game also includes code that responds to the physics of the car and the track—creating realistic responses, for example, to over-acceleration or under-steering.

In its default state, the game accepts input from the keyboard, the mouse, or an Xbox 360 controller. For example, with the keyboard, the user can accelerate the car by pressing the up-arrow (↑) or slow the car down by pressing the down-arrow (↓); the user can steer left by pressing the left-arrow (←) and steer right by pressing the right-arrow (→).

With minor additions to three source files, and using the Sensor and Location platform, we were able to add support for another input device: a dual-axis accelerometer. The updates to the source files consisted of: 1 new line in the file basegame.cs, 13 new lines in the file carphysics.cs, and 46 new lines in the file input.cs. (Minimal changes when you consider the number of lines of new code.)

Once support for the Sensor platform was added, the user can control the car by moving an accelerometer in their hand. When they tilt the accelerometer along its positive Y-axis, the car accelerates, when they tilt the accelerometer along the negative Y-axis, the car slows down. When they tilt the accelerometer along the positive X-axis, the car steers to the right; when they tilt the accelerometer along the negative X-axis, the car steers to the left.

The following screenshot shows a user controlling their car using a circuit board that contains the Memsic dual-axis accelerometer:

The circuit board in the previous illustration was built using the Memsic dual-axis accelerometer and the Parallax BASIC Stamp 2 programmable microcontroller. Both of these components, the circuit board itself, and the USB-to-Serial cable (in the picture) can be ordered from the Parallax Corporation in Rocklin, California. To help you get started building the circuit, we’ve provided a whitepaper that you can download from here. (You can download sample firmware files from this same location).

So, you’re probably asking, how does the accelerometer data reach the racing game? Good question. The linkage between the sensor device and the Sensor API is a sample driver which you can download from here. This driver “listens” for input from the accelerometer and passes that input to the Sensor API. By invoking Sensor API methods and properties in the racing game, we are able to monitor changes in the sensor state and use this data to control the car.

We’ve provided a whitepaper that describes the necessary changes to the racing game. In addition, we’ve provided the three updated source files and a COM Interop that allows you to access the Sensor platform through .Net. You can download the documentation, the updated source files and the COM interop, using the Downloads tab on our Build Your Own Game Controller page on the MSDN Code Gallery.

-- Sensor & Location Platform Team

This posting is provided "AS IS" with no warranties and confers no rights.

I’ll cover:

· Clearing up some confusion around sensors and devices

· What are sensor permissions

· What permissions permits

· How the sensor platform uses permissions

The players in this post are shown in the following diagram:

A Point of Confusion:

Before going into the world of sensor permissions I want to first clear up a misconception around the use of the word ‘sensor’ in our platform.

If you haven’t done so, take a look at the Location and Other Sensors Control Panel (internally we just call it the Sensors CPL – a quick short-cut is to simply enter sensors in the start menu search box). This is where you enable a sensor. In reality when you enable a sensor you are really enabling access to a device.

But why is it that the device manager indicates that the device is enabled when the Sensors CPL says it is disabled? They aren’t really contradicting each other; it is just that the sensor platform uses the term ‘enabled’ to mean that access to sensor data is allowed (more about this below).

The vast majority of devices implement only one sensor per device so enabling a sensor is atomic – one permission for the single sensor device. However new devices may have multiple sensors per device. For such a device granting permission to the sensor in the Sensors CPL is actually going to grant permission to all the sensors on the device. The device with multiple sensors will appear as a single sensor device in the Sensors CPL (for example it could be called “Sensor Array”) even though it will actually expose more than one sensor. You need to be aware that permissions apply to all the sensors on a device. An example of this can be seen on the Sensor Development Kit sold by Freescale. Okay, back to the scheduled blog.

What Are Sensor Permissions?

Sensor permissions control the flow of data between the Sensor Class Extension (which a device driver must have in order to talk to the sensor platform) and the Sensor API.

What Do Sensor Permission Permit?

So why have sensor permissions? It comes down to Personally Identifiable Information or PII. You don’t want to expose personal details by default. Your location based on location sensors or health data (e.g. blood sugar levels based on some as yet developed sensor) are examples of sensor data that expose PII. Once the data is available it can be made available to all apps – some of which could broadcast the data to others. To allow you, the user, to secure your personal data an opt-in model is used. Once you install a new sensor device you need to decide who can get access to the data. You can grant access to all users to the sensor data by checking the check box on the CPL main page or you can go to the User Settings page and choose which users are enabled to access sensor data. The latter is useful in case you don’t want another user of the computer to access sensor data. An example is allowing yourself access to your location but not allowing your children to get (and broadcast) their location from their account.

The sensor platform uses SIDs (security identifiers) to identify users. Associated with the SID is an enable flag. There can be multiple SID/flag pairs depending upon how the permissions were set up in the User Settings page. The sensor permissions are stored in the registry with the format shown in the picture below for a root enumerated sensor:

Okay so I’ve established that sensor permissions determine who (which user accounts) gets access to potentially PII sensor data but you can still access certain sensor data even if the sensor is not enabled. What is going on here? The key here is that sensor data is divided into sensor properties and sensor data fields. Only sensor data fields are protected using sensor permissions. If you develop a device driver for a sensor make sure you keep this in mind. Always place PII data in data fields only so users can turn off access to the data. This division between properties and data fields is enforced by the Sensor Class Extension.

How the Sensor Platform Uses Permissions

Device drivers must instantiate the Sensor Class Extension in order to integrate with the sensor platform. The diagram at the top of this post shows the Sensor API talking with the Sensor Class Extension. In reality the Sensor API communicates with the driver via DeviceIoControl() as exposed by IPortableDevice::SendCommand(). To address a sensor the sensor object ID, which is exposed via the WPD_OBJECT_ID property, is passed into SendCommand(). When the driver receives the command the call is forwarded to the Sensor Class Extension. When the Sensor API needs to get sensor data, as opposed to getting sensor properties, the sensor object ID is pre-pended with a string that the Sensor Class Extension uses to identify a sensor data field call. In this case the Sensor Class Extension checks the sensor permissions against the SID of the calling process. If the enable flag is set for that SID the Sensor Class Extension calls ISensorDriver::OnGetSupportedDataFields() and/or ISensorDriver::OnGetDataFields() passing in the actual sensor ID. When the Sensor API needs sensor properties the actual sensor ID is passed to the Sensor Class Extension which then calls the appropriate ISensorDriver call without doing permission checks.

So what goes on when you enable a sensor? (I know, I know, I said ‘enable a sensor’ but I get lazy) The CPL tracks changes in the checkbox states. When there is a change the Apply button is enabled. The User Settings Page works in the same way. Once the Apply button is clicked the magic of UAC (User Account Control) allows the CPL to forward the device path, the SID and the enable flag to an elevated process (dllhost.exe) for each changed checkbox. The process needs to be elevated because data will be written to HKEY_LOCAL_MACHINE. The elevation of privilege provides a level of security since only someone with administrator access can make changes. The code that is executed in dllhost uses a library that maintains sensor permissions - this is the Sensor Permissions Manager. This is shown above just under the Sensors CPL.

The Sensor Permissions Manager is used by the Sensors CPL not only to set sensor permissions in the registry but also to get sensor permissions from all sensor devices. The Sensor Permissions Manager can get all the information it needs from the registry so the CPL doesn’t need to talk to any devices. Even if the device is no longer connected to the computer the device registry is still present until the device driver is uninstalled. This means that you can change sensor permissions on a device that is not even connected.

So how does a loaded sensor driver (i.e. in memory and running) know that the permissions have changed? In this case the Sensor Permission Manager communicates with the device. Using IPortableDevice::SendCommand() the Sensor Permission Manager sends a command to the driver which forwards it to the Sensor Class Extension. The command identifier tells the Sensor Class Extension that the permissions for the device have changed which causes the Sensor Class Extension to query the sensor permissions. There isn’t anything a device driver author needs to do to enable this synchronization (other than include the Sensor Class Extension) so this behavior comes for free.

I hope you’ve found this informative. Many thanks go to other members of our team that helped proof-read this blog and made this complex topic easier to follow.

Thanks for reading,

Kevin

This posting is provided "AS IS" with no warranties and confers no rights.

In last week’s blog post we provided best practice guidance for Sensor State management in Location Sensors. At the bottom of that post we mention that SENSOR_STATE_ACCESS_DENIED is reserved and should only be used by the Platform. As a follow-on post we wanted to briefly dig into an issue that some customers have reported related to SENSOR_STATE_ACCESS_DENIED.

As mentioned above - this blog topic is actually based on a question from one of our customers. The customer in question, a driver developer, had noticed that if access was denied to their sensor in the Location and Other Sensors Control Panel that they could get different answers for Sensor State depending on where they asked the question in the Sensor API.

Let’s take the following scenario:

1. You have a Sensor Device running on your machine.

2. You know the device is currently reporting a Sensor State of SENSOR_STATE_READY

3. You open the Location and Other Sensors Control Panel.

4. You disable access to your sensor device.

Now here is where it can get interesting. When you call the following two methods you might expect to get the same response for the state of your sensor – but you don’t:

• Calling ISensor::GetState() will return the state of SENSOR_STATE_ACCESS_DENIED.

• Calling ISensor::GetProperty() with an input Property Key of SENSOR_PROPERTY_STATE will return SENSOR_STATE_READY.

The driver partner mentioned above asked the question: Why?

To answer this question we need to briefly discuss where permissions are managed in the Sensor API. I should note that this will be a very brief discussion on permissions management. We expect to have additional posts coming that dig into the subject of permissions in greater detail.

A brief introduction into Permissions:

In an earlier blog post we provided this diagram as an example for how the Sensor Platform is designed:

As you can see in this diagram the Sensors Class Extension and the Sensor API both talk to the Location and Other Sensors Control Panel. The Sensors Class Extension working with the Location and Other Sensors Control Panel provide the permissions infrastructure for the Platform. When you change permissions in the Location and Other Sensors Control Panel the Sensor API, working with the Sensor Class Extension, will stop granting access to that device. In this way the Sensor Class Extension serves as a kind-of “gate keeper” for accessing sensor devices.

In the example scenario above when you asked the Sensor API for the sensors state via a call to ISensor::GetState() you were essentially asking the platform what state it understood the sensor to be in. In this case, because the platform knows the sensor is Access Denied, it will return a state of SENSOR_STATE_ACCESS_DENIED. Because permissions are managed separate from device properties the platform in this case needs supersede the Sensor State from the device and return SENSOR_STATE_ACCESS_DENIED. Alternatively, when you make a call to ISensor::GetProperty() for property SENSOR_PROPERTY_STATE you are requesting a property directly from the sensor. The Sensor Device, which does not know the platform has denied access to the Sensor, will return its current Sensor State.

We understand that this nuance in Platform behavior has caused some confusion. We will evaluate this in the future.

So which method should you use to access Sensor State?

The guidance we have for application developers is that if you need access to Sensor State then request the state from ISensor::GetState(). Calling ISensor::GetState() will insure that you have the most accurate representation of State from a Sensor Platform perspective.

-- Sensor & Location Platform Team

This posting is provided "AS IS" with no warranties and confers no rights.

With information above in mind, let’s now talk about best practices for handling state transition in a location driver. This is not meant to replace the Managing State Transitions section of the document mentioned above, it’s meant to help a developer have a better understanding of how state usage was anticipated when used by the Location API.There are many logic decisions made by the API based on the sensor state, and this becomes even more important as multiple devices are added to the platform that it can make better decisions with drivers giving it fresh and accurate data.

A new Sensor device enters:

As a location sensor comes on-line, its initial status should be set to SENSOR_STATE_NO_DATA. With this state the Location API knows that you are a location provider that has no data, which allows the Location API to optimize it’s usage of other location providers of the same type.

Once a Sensor device is ready to provide data:

Once the provider has been started up and has been able to get data (or not) from its hardware it can move into one of the following states:

Some expected uses for error states:

SENSOR_STATE_READY	Sensor driver is able to provide new location reports with complete and accurate data.For example, a Wi-Fi or cellular provider is connected and working, or a GPS sensor has a fix.
SENSOR_STATE_NOT_AVAILABLE	The location provider is not available. For example, a Wi-Fi provider has no access to the Internet. A GPS sensor could be in this state if no signal is available.
SENSOR_STATE_ERROR	The sensor has encountered a major error. The sensor can recover from this state, but the time frame for recovery is not known.

This is a just part of the full table that can be found in “Writing a Location Sensor Driver”.

Once a Sensor device has data:

Once a sensor has moved into a SENSOR_STATE_READY and has provided valid data to the platform it’s recognized as legitimate source to get location data from.

Once the driver is up and running it may need to transition back to one of these other states to indicate a change in what the driver will be able to provide to the Location Platform:

What about SENSOR_STATE_INITIALIZING:

SENSOR_STATE_INITIALIZING is not meant to be the all-purpose initializing state; instead it is used for a more limited scope. The Location API expects devices in SENSOR_STATE_INITIALIZING to provide data, but if the sensor has invalid data or no data, it may be ignored by the API.

SENSOR_STATE_INITIALIZING would be best used by a GPS type device.

A hypothetical example:

A hypothetical GPS Device requires 4 satellites before it would consider its provided data to be of expected accuracy. But it could still provide lower accuracy data with only 3 satellites. In this situation the driver could go into an initializing state once it has 3 satellites with less accurate data. Once the device has a fix on 4 or more satellites and has recovered its accuracy then it could return to SENSOR_STATE_READY.

Also if the device lost satellites and was back down to 3, it could change SENSOR_STATE_INITIALIZING once more.

So the device’s transition could look like this:

States to not use:

If you are to look at the Sensor State Enumeration page you will find there is SENSOR_STATE_ACCESS_DENIED. This is a reserved state for the API and it should not be used by the driver. Please refer to “Sensor State Enumeration” to get a look at all the reserved states.

As stated at the beginning, this is the anticipated use of the states by the Location API. While you can use them in other ways, you might find that the Location API behaves unexpectedly. In these cases I hope that understanding what Location API expects will help you in your design.

-- Sensor & Location Platform Team

This posting is provided "AS IS" with no warranties and confers no rights.

This blog post will focus on the Time Sensor Sample from the Windows Driver Kit. In general this driver creates a thread that periodically requests data from the ‘device’ (just the system time), and posts it to the class extension. This differs from the skeleton sample examined previously, which merely responds to synchronous data requests. Let’s look at the following code snippet from _EventThreadProc in CSampleEvents to illustrate this additional functionality. Note some comments have been modified.

   1: // 

   2: // Fetching data and posting an event, 

   3: // from _EventThreadProc, lines 193 - 225 

   4: // 

   5:  

   6: CComPtr<IPortableDeviceValues> spEventParams;

   7: CComPtr<IPortableDeviceKeyCollection> spKeys;

   8:             

   9: if(SUCCEEDED(hr))

  10: {            

  11:     // Use the Ddi class to create the key collection.

  12:     hr = pThis->m_pDdi->OnGetSupportedDataFields(

  13:         g_wszSensorID, &spKeys);

  14: }

  15:  

  16: if(SUCCEEDED(hr))

  17: {

  18:     CComPtr<IWDFFile> spTemp;

  19:  

  20:     // Get the data fields.

  21:     hr = pThis->m_pDdi->OnGetDataFields(

  22:         spTemp, g_wszSensorID, spKeys, &spEventParams);

  23: }

  24:  

  25: if(SUCCEEDED(hr))

  26: {

  27:     // Add the data event property key.

  28:     hr = spEventParams->SetGuidValue(

  29:         SENSOR_EVENT_PARAMETER_EVENT_ID, 

  30:         SENSOR_EVENT_DATA_UPDATED);

  31:             

  32: if(SUCCEEDED(hr))

  33: {

  34:     // Post the event.

  35:     hr = pThis->PostDataEvent(spEventParams);                

In the first two blocks of code, we get a list of supported data fields and populate an IPortableDeviceValues collection with their current values. OnGetDataFields is the same method the class extension would call into if a client requested data on demand. Next we set the event type using the event property key. Setting the correct type is important because clients can register to be notified of specific types of events. For example an application may care about a new data event but not a state change event. The sensor and location platform defines several event property keys and types, which can be seen at MSDN. Finally we call into the PostDataEvent helper method to signal the class extension. Here is this method in its entirety.

   1: // Post a data updated event, lines 148 - 170

   2: HRESULT CSampleEvents::PostDataEvent(IPortableDeviceValues* pValues)

   3: {

   4:     HRESULT hr = (NULL == m_spSensorCXT) ? E_UNEXPECTED : S_OK ;

   5:  

   6:     if (SUCCEEDED(hr))

   7:     {

   8:               CComPtr<IPortableDeviceValuesCollection> 

   9:                   spValuesCollection;

  10:         hr = spValuesCollection.CoCreateInstance(

  11:             CLSID_PortableDeviceValuesCollection);

  12:  

  13:         if (SUCCEEDED(hr))

  14:         {

  15:             hr = spValuesCollection->Add(pValues);

  16:  

  17:             if (SUCCEEDED(hr))

  18:             {

  19:                 hr = m_spSensorCXT->PostEvent(

  20:                     g_wszSensorID, spValuesCollection);

  21:             }

  22:         }

  23:     }

  24:  

  25:     return hr;

  26: }

PostDataEvent simply takes the data field values, adds them to an IPortableDeviceValeus collection, and posts the collection to the Sensor Class Extension. The extension will notify appropriate clients of new data.

The Sensor Class Extension also informs a sensor driver of client connection and subscription changes through several methods: OnClientConnect, OnClientDisconnect, On ClientSubscribeToEvents, and OnClientUnsubscribeFromEvents. These enable a driver to adjust its activity accordingly (such as disabling device sampling when no client is connected or adjusting event frequency). For instance, the Time Sensor Sample keeps track of client applications in a Clients list, which it uses to update the driver’s report interval.

To wrap up, these simple additions allow a sensor driver can take advantage of events in the sensor and location platform. This event-driven model can improve performance in both the driver and client applications. For more information about sensor driver events, take a look here. Best of luck!

-- Sensor & Location Platform Team

This posting is provided "AS IS" with no warranties and confers no rights.

Three of the four classes in the skeleton sample (CMyDriver, CMyDevice, and CMyQueue) implement various User-Mode Driver Framework (UMDF) interfaces. In these we initialize the device, configure the IO queue, and create the class extension and device driver interface (DDI). Head over to MSDN for more information about UMDF.

The remainder of this post will focus on the fourth class, CSensorDdi, which implements the ISensorDriver interface. This class emulates access to hardware devices and handles communication with the sensor class extension. Your first step – determine the properties and data fields your sensor supports. Properties describe a sensor device, while data fields describe sensor-generated data. Take a look at the code snippets below from SensorDDI.cpp.

// Sensor properties, lines 26-51

const PROPERTYKEY g_SupportedCommonProperties[] =

{

    WPD_OBJECT_ID,

    WPD_OBJECT_PERSISTENT_UNIQUE_ID,

    WPD_OBJECT_PARENT_ID,

    WPD_OBJECT_NAME,

    WPD_OBJECT_FORMAT,

    WPD_OBJECT_CONTENT_TYPE,

    WPD_OBJECT_CAN_DELETE,

};

const PROPERTYKEY g_SupportedTemperatureProperties[] =

{

    SENSOR_PROPERTY_TYPE,

    SENSOR_PROPERTY_STATE,

    SENSOR_PROPERTY_MIN_REPORT_INTERVAL,

    SENSOR_PROPERTY_CURRENT_REPORT_INTERVAL,

    SENSOR_PROPERTY_PERSISTENT_UNIQUE_ID,

    SENSOR_PROPERTY_MANUFACTURER, 

    SENSOR_PROPERTY_MODEL,

    SENSOR_PROPERTY_SERIAL_NUMBER,

    SENSOR_PROPERTY_FRIENDLY_NAME,

    SENSOR_PROPERTY_DESCRIPTION, 

    SENSOR_PROPERTY_CONNECTION_TYPE,

    WPD_FUNCTIONAL_OBJECT_CATEGORY,

};

// Sensor data fields, lines 69-73

const PROPERTYKEY g_SupportedTemperatureDataFields[] =

{

    SENSOR_DATA_TYPE_TIMESTAMP,

    SENSOR_DATA_TYPE_TEMPERATURE_CELSIUS,

};

These properties and data fields describe the mock temperature sensor. The g_SupportedCommonProperties array holds properties shared by all sensors for this driver, while the other two are temperature-sensor specific. Note that these strings and associated GUIDs can be user-defined, but they must be shared and understood between the driver and client applications to be useful. The sensor platform defines a set of constants for sensor drivers, which can also be found in <WDK Install Path>\inc\api\Sensors.h.

We initialize each sensor by storing its properties and data fields into collections for future reference. The following code from InitializeTemperatureSensor demonstrates adding our temperature properties to the m_pSupportedTemperatureSensorProperties collection and setting some default values. A similar collection is maintained for the data field values.

// Add temperature sensor property keys, lines 161-165

for (DWORD dwIndex=0;    

    dwIndex<ARRAYSIZE(g_SupportedTemperatureProperties); 

    dwIndex++)

{

    m_pSupportedTemperatureSensorProperties->Add(

        g_SupportedTemperatureProperties[dwIndex]);

}

// Add temperature sensor property values, lines 184-186

m_pTemperatureSensorPropertyValues->SetGuidValue(

    WPD_FUNCTIONAL_OBJECT_CATEGORY, SENSOR_CATEGORY_ENVIRONMENTAL);

m_pTemperatureSensorPropertyValues->SetGuidValue(

    SENSOR_PROPERTY_TYPE, SENSOR_TYPE_ENVIRONMENTAL_TEMPERATURE);

m_pTemperatureSensorPropertyValues->SetStringValue(

    SENSOR_PROPERTY_MANUFACTURER, DEVICE_MANUFACTURER_VALUE);

...

Once the CSensorDdi initialization is finished, the sensor class extension loads and calls OnGetSupportedSensorObjects. Here we report each sensor to the class extension and provide its supported properties. The final step is to enable the driver in the control panel so that it can be accessed by client applications. A quick note – although we are describing each sensor separately, permissions are granted at the driver level and cannot be set for specific sensors.

With our driver initialized and sensor values defined, let’s take a look at some key callback methods of the ISensorDriver interface.

• OnClientConnect, OnClientDisconnect, OnClientSubscribeToEvents, OnClientUnsubscribeFromEvents

These methods inform the driver of client application activity. The driver can use this information to optimize reporting of state change and data values.

• OnGetSupportedProperties, OnGetSupportedDataFields, OnGetSupportedEvents

These methods provide the sensor class extension with access to a sensor’s supported properties, data fields, and events. Remember those collections we populated earlier? This is how each sensor exposes its functionality. Recall we will talk about events in a future blog post.

• OnGetProperties, OnSetProperties, OnGetDataFields

These methods expose the property and data field values that client applications will likely care about. OnSetProperties allows an application to update settable properties, such as a sensor’s report interval.

OnGetDataFields returns a sensor’s data field values. These could be from a cached copy or requested from the device on demand. In our sample the default values stored in the m_pTemperatureSensorDataFieldValues collection are returned for each supported data field.

That’s it! While this skeleton sample offers minimal functionality, hopefully you now have a better understanding of the driver architecture and its interaction with the sensor class extension. Starting with some simple modifications to the properties and data fields, your driver will be up and running in no time. One more thing – the Sensor Diagnostic Tool offers a great mechanism for interacting with your driver during development.

Good luck and stay tuned for the follow-up post.

-- Sensor & Location Platform Team

This posting is provided "AS IS" with no warranties and confers no rights.

Where can I find the ALS on my machine ?

Can you find where the ALS is exposed on your laptop? Sometimes it’s obvious other times it’s not. You have to know what you’re looking for. Most of the time the ALS is behind some translucent or dark glass. Here is what an ALS chip looks like:

I’ll leave it as an exercise to you to find the ALS chip on your computer. Don’t feel bad if you don’t find it. When one of the first prototype computers that had an ALS implemented arrived it took us about an hour to find it. We weren’t sure if the chip was on the exposed motherboard of prototype board or if the vender hid it behind some dark glass on the monitor. It was a real challenge since we need do measurements on the ALS’s response to various light levels and not knowing where it was made that a bit challenging. We finally found it on the motherboard… Finding the power button was a whole different story on this prototype… you had to be there.

How does Windows 7 use the ALS?

New with Windows 7 is the Adaptive Brightness feature. This feature is built on top of our Sensor Platform. This feature will adjust the screen brightness according to the ambient light level. If the ambient light level gets darker then the screen brightness decreases; if the ambient light level increases then the screen brightness increases. This solves the problem of when you resume your computer the morning after a late night of hardcore programming only to discover that the screen is so dark that you’re having a hard time reading it. As an added bonus it helps to extend battery life. As the day turned to night you invariably used the Mobility Center to adjust your screen brightness making it darker and darker as the room grew darker and darker. (Win – X will open the Mobility Center).

This is where the Adaptive Brightness feature takes over. The feature makes use of the built in ALS. The ALS needs to be enabled before Adaptive Brightness will work. Let’s open the Location and Other Sensors CPL. Quick access to this Control Panel (CPL) is achieved by pressing the Windows Key and typing “sensors”.

If the Light Sensor is not enabled then perhaps we can have a dramatic unveiling of this feature by trying to enable the Light Sensor in a dark room. Enable the Light Sensor then click Apply. We’ll cover the inner workings of this CPL in another post. For now let’s just use it to enable our Light Sensor. Did you notice the screen darken? That’s the Adaptive Brightness feature at work for you.

Remember that this ALS is exposed not only to the Adaptive Brightness feature in Windows but is also exposed via the Sensor Platform. In a future post we’ll go through some simple code to find the ALS Sensor, setup an event on the sensor and output the resulting light level detected. Soon you could be writing applications that make use of this built in sensor.

-- Sensor & Location Platform Team

This posting is provided "AS IS" with no warranties and confers no rights.

Below is a screenshot of the Passive Infrared (PIR) or motion sensor running on a Parallax HomeWork board:

The Parallax BS2 (BasicStamp 2) is a programmable microcontroller that you code with Parallax PBASIC. This microcontroller has the following features:

· 20MHz processor

· 32 bytes RAM

· 2KB EEPROM (able to hold ~500 PBASIC instructions)

· 16 I/O pins

· 5 VDC with 3mA draw while running

Sensor Applications in .NET

With very little code, you’ll begin to see the rich power of the Sensor platform. For example, the below screenshot was taken from a simple C# .NET application that graphs the output for the Memsic 2-axis accelerometer:

This application was written with just 100 lines of code. And, below is a screenshot of another application that renders compass output in real-time:

This application contained a little more code (closer to 200 lines); however, even 200 lines is a remarkably small footprint for an application that renders real-time data from a remote device.

How do I get started ?

That depends: If you’re a hardware type, building the circuit will be a piece of cake. But, creating the driver (the interface between the sensor hardware and Windows) might be a challenge. Same goes for application developer: If you know your way around .Net, you might find it a challenge to write the driver or build the hardware. Driver developers will probably have the least difficulty of all.

But, we’ve tried to simplify the process for everyone. We’ve provided a sample driver that supports all four sensors in the kit. And, we’ve provided sample firmware for the four devices as well as a simple .Net application that demonstrates the use of the Sensor platform for the Passive Infrared (PIR) sensor.

You’ll find the sample driver, firmware, PIR application, and a descriptive whitepaper on the MSDN Code Gallery here.

You’ll find a sample application that demonstrates real-time graphing of accelerometer data on the MSDN Code Gallery here.

Where can I find out more ?

· To learn more about the programmable microcontrollers and sensors offered by Parallax, see the Parallax Web site.

· For information about the Sensor API, see Sensor API in the Win32 and COM Development section MSDN.

· For information about Sensor Drivers, see Sensor Devices in the Windows Driver Kit (WDK) section of MSDN.

· To download a free version of Visual C# 2008 Express, see this Downloads page on the Microsoft site.

The .NET Framework 4.0 RC, which is integrated with Visual Studio 2010, is now available for download. This release of the .NET Framework 4 provides a managed location API in the System.Device.Location namespace that allow .NET developers to access location data from the Windows 7 Sensors & Location platform.  If you are familiar with the Location classes from .NET Framework 4 Beta 2, note that this API has been refactored in RC with changes described here.

The managed Location API is built on top of the C++/COM API described in the previous post, so it uses the same mechanism to simplify access to location data by automatically returning data from the best location source it identifies on the computer. However, the methods in the managed API do not correspond exactly to methods in the COM API. The root location object for the .NET Framework 4 Location API, GeoCoordinateWatcher, supplies location data based on latitude and longitude coordinates. Either the Start or TryStart method must be called to initiate the acquisition of data, after which the location data is accessed either by accessing the Position property or by subscribing to the PositionChanged event. In location-aware applications that require continuous updates, such as a navigation application, you’ll want to subscribe to the PositionChanged event. For applications that only require accessing the location once, such as for pre-populating form fields or tagging a file with location metadata, you can get the location from the Position property or by subscribing to the PositionChanged event, getting the location from the first event, and then calling Stop to stop receiving further events. The Status property indicates whether a location sensor is initializing, ready to supply new data, or if no location data is available from any sensor. You can subscribe to the StatusChanged event for status updates.

To get you started using the managed Location API, let’s look at a couple of simple location-aware programs that access the location property or subscribe to updates when the location or location status changes.  For each of these examples, you’ll want to add a reference to System.Device in your Visual Studio 2010 project, and add a using statement for the System.Device.Location namespace to your code.  The first example gets the location from the Position property, and the second gets the location and status by subscribing to events.

Example 1: Accessing the Position Property

// Accessing the Position Property

using System;

using System.Device.Location; // Add a reference to System.Device.dll

namespace LocationPropertyExample

{

    class Program

    {

        static void Main(string[] args)

        {

            GetLocationProperty();

        }

        static void GetLocationProperty()

        {

            GeoCoordinateWatcher watcher = new GeoCoordinateWatcher();

             // Initiate acquisition of location data, so that we 

             // can get location coordinates from the Position property.

             // 1. If we don’t have access to the location sensors, 

             // the user will be prompted with a permission dialog.

             // 2. If we have permissions, following this call, we can 

             //    access location data from the Position property, 

             //    and we'll get PositionChanged events if we have set

             //    up an event handler.

            watcher.TryStart(false, // Do not suppress permissions prompt.

               TimeSpan.FromMilliseconds(1000)); // Wait 1000 ms to start.

            GeoCoordinate coord = watcher.Position.Location;

            if (coord.IsUnknown != true)

            {

                Console.WriteLine("Lat: {0}, Long: {1}",

                    coord.Latitude,

                    coord.Longitude);

            }

            else

            {

                Console.WriteLine("Unknown latitude and longitude.");

            }

        }

    }

}

Example 2: Subscribing to PositionChanged and StatusChanged Events

// Subscribing to Location Events

using System;

using System.Device.Location; // Add a reference to System.Device.dll 

namespace LocationEventExample

{

    class Program

    {

        static void Main(string[] args)

        {

            Console.WriteLine("Displaying location updates. Press any key to exit...");

            // GeoCoordinateWatcher is the root object for the .NET 4 Location API

            GeoCoordinateWatcher locationWatcher;

            // Initialize the GeoCoordinateWatcher with default accuracy settings

            locationWatcher = new GeoCoordinateWatcher();

            // Subscribe to updates when the location changes

            locationWatcher.PositionChanged += new EventHandler<GeoPositionChangedEventArgs<GeoCoordinate>>(locationWatcher_PositionChanged);

            // Subscribe to updates when the status changes.

            // The Status property indicates whether a location sensor is 

            // initializing, ready to supply new data, or if location data is not  

            // available from any sensor. 

            watcher.StatusChanged += new EventHandler<GeoPositionStatusChangedEventArgs> (locationWatcher_StatusChanged);

            // Initiate acquisition of location data, so that we 

            // get PositionChanged events.

            // 1. If we don’t have access to the location sensors, the user will 

            //    prompted with a dialog to grant or deny permission.

            // 2. If we have permissions, following this call, we'll be able to 

            //    access location data, and we'll get PositionChanged events if

            //    we have set up an event handler

            locationWatcher.Start();

            Console.ReadKey();

        }

        static void locationWatcher_PositionChanged(object sender, GeoPositionChangedEventArgs<GeoCoordinate> e)

        {

            // Output the new location coordinate to the console if present

            if (e.Position.Location != GeoCoordinate.Unknown)

            {

                Console.WriteLine(

                    "Latitude:  " + e.Position.Location.Latitude.ToString() +

                    " Longitude: " + e.Position.Location.Longitude.ToString());

            }

        }

       static void locationWatcher_StatusChanged(object sender, GeoPositionStatusChangedEventArgs e)

       {

            switch (e.Status)

            {

                case GeoPositionStatus.Initializing:

                    Console.WriteLine("Working on location fix");

                    break;

                case GeoPositionStatus.Ready:

                    Console.WriteLine("Have location");

                    break;

                case GeoPositionStatus.NoData:

                    Console.WriteLine("No data");

                    break;

                case GeoPositionStatus.Disabled:

                    Console.WriteLine("Disabled");

                    break;

            }

       }

    }

}

-- Sensor & Location Platform Team

This posting is provided "AS IS" with no warranties and confers no rights.

We started first with an overview of the Sensor and Location Platform.

This was followed up with a drill down in the Sensor DDI or Device Driver Interface.

Next we examined the Sensor API and how it fits into the Sensor and Location Platform.

As the final post in this series we will be examining the Location API. The Location API, as described in the introduction post (link) sits on top of the sensor and location “API stack”. That is to say that the Location API is really a client of the Sensor API and the framework provided by the Sensor DDI. As a refresher – here is a diagram of the Location Platform:

There are a few important notes to cover about the Location API Layer in this diagram. The first is that the Location API is actually a collection of two API’s. A COM API which is accessible via native C++ applications and an IDispatch or “scripting” API. The IDispatch API provides access to Location in script enabled environments like the Windows Scripting Host and Active X controls. As an example – it’s possible to write a Sidebar Gadget (as identified in the diagram above) that can access Location via the IDispatch API interface.

What may not be clear in this diagram is that a “Location Sensor” is really just a Sensor that provides Location information. The location sensor data that is available from the Location API is also available, in a more basic format, from the Sensor API.

This may make you ask – what does the Location API do for you? The Location API is designed to focus on making access to location information easier. Two specific guiding goals are important to drill into:

- Simplify access to location sources (i.e. location sensors).

- Simplify accessing location information from location sensors.

Let’s examine each of those goals in isolation:

First, simplifying access to location sources: At any given time you may have one or more location sensors on your machine (default location + some other location sensor like a GPS sensor). If you were to access these location sensors directly from the Sensor API you would need to talk to all available location sensors and make some determination about which sensor is likely to provide the location data you want. The Location API does the work, internally, to identify and use the location sensor which appears to be most accurate and reliable.

Second, simplify accessing location information from location sensors: A location sensor is just a sensor. As such you can access the location sensors information from the Sensor API. However, the Sensor API is designed to provide generalized access to all forms of sensor devices on your machine. As a result accessing data from sensors usually requires a several steps. Take a look at our last blog post on the Sensor API to get a quick overview of these steps (link). The Location API automatically calls into the Sensor API and extracts location information for you. The Location API then presents the information in a format that is specifically suited for location data, such as ILatLongReport and ICivicAddressReport. The net effect is that it is generally much simpler to ask the Location API for location data instead of using the Sensor API.

So, how do you access location data from the Location API? Let’s walk through a quick example using the COM Location API. Note - each step below will contain a link to the relevant document in MSDN.

- First create an instance of the Location API by CoCreating ILocation.

- Next, call ILocation->RegisterForReports() to register to receive ILocationReport’s (either an ILatLongReport or an ICivicAddressReport).

- When you call RegisterForReports() on an ILocation object you will register a call-back object which will be called when the Location API wants to notify you of changes in Location or Location Status. The callback object will need to implement the ILocationEvents interface to receive location events. When a location change occurs the OnLocationChanged() method, which will be implemented in your callback object, will get called with the updated ILatLongReport or ICivicAddressReport.

- The OnLocationChanged() callback method will deliver to your callback object either an ILatLongReport or an ICivicAddressReport. Each report object provides methods to access the location information contained by the object. As an example you can access the latitude on an ILatLongReport by calling the GetLatitude() method. The GetLatitude() method will return a double which represents the current latitude for your location sensor.

The Location API documentation on MSDN has an example which shows all of the above in steps in one location with a description for each object used. You can find that information here.

To summarize:

- The Location API sit’s at the top of the Sensor API stack and provides simplified access to location data.

- To access Location you can either use the COM Location API interface in C++ or you can use the scripting interface.

- To get location updates in your application all you need to do is create the Location API, register for reports and then handle location changes on your call back object.

A few final notes: The Location API team has been working over the last several months with the .NET CLR Team to build a Managed Location API which will ship in the next version of .NET. We are tremendously excited about having location exposed to developers via COM, Scripting and now .NET. You can find some initial information about the .NET Location API on Gavin’s blog (link). Stay tuned here for more information!

-- Sensor & Location Platform Team

This posting is provided "AS IS" with no warranties and confers no rights.