Sensor & Location Platform Team Blog

Using an Accelerometer to Build a Game Controller

sensblog — Wed, 30 Jun 2010 00:00:00 GMT

The XNA team created their XNA Game Studio to simplify the creation of games for: Windows, the Xbox 360, the Zune, and the Windows Phone 7 Series. The Game Studio includes the XNA Framework--a set of managed libraries that are designed for game development...(read more)

Making Sense of Sensor Permissions

sensblog — Fri, 25 Jun 2010 18:00:00 GMT

In this, my first Sensor and Location Team Blog post, I will discuss sensor permissions. I’ll cover: · Clearing up some confusion around sensors and devices · What are sensor permissions · What permissions permits...(read more)

Understanding Access Denied when working with ISensor::GetState() and ISensor::GetProperty()

sensblog — Wed, 28 Apr 2010 00:00:00 GMT

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...(read more)

State Transition in Location Drivers : Best practices

sensblog — Wed, 14 Apr 2010 00:00:00 GMT

This post will be talking about best practices for handling state to get the best behaviors from the Location API. Before reviewing our best practice guidance we recommend you read up on “ Writing a Location Sensor Driver ”. With information above in...(read more)

Developing Your First Sensor Driver – Part 2

sensblog — Wed, 31 Mar 2010 00:00:00 GMT

In the last blog post we investigated the fundamental characteristics of a sensor driver (properties and data fields) and how the Sensor Class Extension interacts with them. Here we will expand the basic driver template to include raising events and managing clients. A client is an application that has requested a connection to the driver through the class extension.

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))

{            

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

    hr = pThis->m_pDdi->OnGetSupportedDataFields(

        g_wszSensorID, &spKeys);

}

  

if(SUCCEEDED(hr))

{

    CComPtr<IWDFFile> spTemp;

  

    // Get the data fields.

    hr = pThis->m_pDdi->OnGetDataFields(

        spTemp, g_wszSensorID, spKeys, &spEventParams);

}

  

if(SUCCEEDED(hr))

{

    // Add the data event property key.

    hr = spEventParams->SetGuidValue(

        SENSOR_EVENT_PARAMETER_EVENT_ID, 

        SENSOR_EVENT_DATA_UPDATED);

            

if(SUCCEEDED(hr))

{

    // Post the event.

    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.

Developing Your First Sensor Driver – Part 1

sensblog — Wed, 24 Mar 2010 00:00:00 GMT

The Windows Driver Kit (WDK) is a great place to get started when writing your first sensor driver. In this post we will take a look at the Sensor Driver Skeleton Sample, which provides a basic sensor driver template. A future post will investigate the Time Sensor Sample to learn about incorporating events. If you have the WDK installed, the source is located under <WDK Install Path>\src\SensorsAndLocation. For more in-depth information, the WDK Sensor Devices section of MSDN includes a design guide, valuable sensor references, and information about the two sensor driver samples.

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.

Overview of Adaptive Brightness in Windows 7

sensblog — Wed, 10 Mar 2010 01:00:00 GMT

So you just got yourself a new laptop. Congratulations! Did you notice that it has an Ambient Light Sensor (ALS)? With Windows 7, we’re seeing more and more laptops coming to market with built in ALS. How does Windows 7 take advantage of this sensor? How can you tap into it? How do I see it reflected in the system settings? Where is this little gizmo on the machine? We’ll answer some of these questions in this post…

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.

The Parallax Introduction to Sensors Kit

sensblog — Thu, 04 Mar 2010 01:00:00 GMT

Accelerometers, motion-sensors, distance-sensors, and compasses. What do these sensors have in common? They compose the Introduction to Sensors Kit that the Parallax Corporation sells for $79.99. Purchase this kit, a programmable microcontroller like the Parallax BS2, a kit board, and a serial cable and you’re ready to explore the Sensor platform for Windows 7.

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.

-- Sensor & Location Platform Team

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

Introducing Location in .NET 4.0

sensblog — Wed, 24 Feb 2010 01:00:00 GMT

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.

The Sensor and Location Drill Down – Part 3: The Location API

sensblog — Thu, 11 Feb 2010 01:00:00 GMT

Over the last few weeks we have been providing an introduction to the Sensor and Location Platform by examining each component in the platform in greater detail.

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.