State Transition in Location Drivers : Best practices

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

Comments

• Anonymous
  April 25, 2010
  Team, - Thanks very much for the clarification. We've been having headaches understanding the mucky language on MSDN. /rafael