The Sensor and Location Drill Down - Part 2: The Sensor API

  • Article

We continue our overview of the Sensor and Location Platform this time focusing on the Sensor API. The Sensor API is made up of several COM Interfaces but where to start and how does it all fit together? Today we’ll answer that question.

The Sensor API is used by applications that want to access sensors. This is illustrated in the diagram below. The Sensor API is your interface into the properties, data and events that a sensor exposes. It’s generic so it really doesn’t matter what sort of sensor you need to interface with – the API is the same. The only thing that is different is the data and properties that are exposed.

 

image

 

The best place to start is to trace through the flow of how you find and access a desired sensor. To do this we’ll introduce some of the API’s and Interfaces exposed by the Sensor API.

The first thing we need to do is to create an instance of ISensorManager. This is the top level interface into finding a sensor or a collection of sensors. In most cases we won’t know the actual ID of a sensor but we will know what type or category of sensor we want to use.

In this walk through let’s assume that we know the category or type of sensor we want. This means we’ve used ISensorManager->GetSensorByCategory() or ISensorManager->GetSensorByType(). The result is that we’ll have an ISensorCollection.

An ISensorCollection is like most any other collection. It can be added to, removed from, cleared and we can get a count or get a sensor at a specific index into the collection. The end result is to get at an ISensor object which brings us to:

The star of the Sensor API! Want data? ISensor has it. Want properties. ISensor is where you go. Setup an event? ISensor will set you up. ISensor is THE sensor. Perhaps the most important data that we’ll get from the Sensor is the data that the sensor was created to report on. We can ask the Sensor for its data in two ways, either by calling ISensor->GetData() or by setting up an event sink. Both will return an ISensorDataReport that encapsulates the data the Sensor reports.

Most applications will want to setup the Sensor to respond to changes to sensor data by raising an event which, as we just stated, will provide the application with an ISensorDataReport. To do this we’ll need to do a few things. The first thing is to implement the interface defined by ISensorEvents. The next thing is to create your implementation of the ISensorEvents object and attach it to the sensor of interest by calling ISensor->SetEventSink(). Now when sensor data is updated or if the sensor state changes your application will be notified and will response to those changes by executing the code you’ve provided in your implementation of the ISensorEvents interface.

The ISensorManager also has the ability to respond to events except the ISensorManager’s event interface is called ISensorManagerEvents. The ISensorManagerEvents can only raise one event: OnSensorEnter. This is a really useful event since if tells your application when a sensor is connected to the machine. Once the application hears this event it will still need to check if the sensor is one that your application is interested in.

To summarize:

  • Create ISensorManager
  • Add an ISensorManagerEvent to listen for sensors added to the machine
  • Get an ISensorCollection because your desired sensor may already be on the machine
  • Extract your desired ISensor
  • Setup an event sink to listen for data event
  • Let your application do its thing until some sensor data comes rolling in…
  • If its sensor data then crack open the ISensorDataReport and pull out the data…
  • If it’s an ISensorManagerEvent check to see if the sensor added to the machine is one of interest…

So there we have it, a quick walk through of the Sensor API. Next week we’ll dive into the Location API.

Sensor & Location Platform Team

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