Sensor APIs
Sensor APIs consist of two parts: Sensor Channel API and Sensor Definitions API. The Sensor Channel API defines the basic functionality and utilities for using sensors. The Sensor Definitions API defines the features of different sensor channels. In addition to these, the Nokia N97 SDK introduces the Sensor Data Compensator API, used for compensating sensor data for device or display orientation.
Sensor API library |
|
Headers |
Sensor Channel API for accessing sensor channels Sensor Definitions API for sensor channel data definitions |
Capabilities |
|
Sensor channels |
The Sensor Channel API gives you access to each sensor channel. One physical sensor might provide several different types of data, so you use one sensor channel to get one particular type of data from the sensor. For example, the physical magnetometer provides data for the Magnetometer channel and for the Magnetic North channel.
Through the Sensor Channel API you can query and configure the properties of a sensor channel. And, of course, the API allows you to receive data from sensors.
A sensor channel may also support conditional listening. This means that you can configure it to notify you when the data on the channel matches some particular values, or exceeds some boundaries that you set beforehand. This saves you having to check every single item of incoming data.
Each sensor channel has its own sensor channel data definition in the Sensor Definitions API that defines the format of the data package supplied by the sensor channel. The data definition can also define properties for each data item in the data package.
Figure: Simplified sensor class diagram
The above diagram shows that one physical sensor can supply data to several
sensor channels (CSensrvChannel)
. A sensor channel provides data to an application in a channel-specific data
format (e.g. TSensrvXyzData) by a callback to the MSensrvDataListener::DataReceived() interface. A
sensor channel has a single channel info item (TSensrvChannelInfo) that describes the channel in general. A sensor channel has multiple
property items (TSensrvProperty)
that describe the channel in more detail. Each property item is referenced
by a property id plus an index.
Use CSensrvChannelFinder to find which sensor channels are supported by your device.
See the Sensor API class structure page for a more detailed class diagram and information about other callback interfaces.
How to use the Sensor APIs
The basic implementation procedure is the same regardless of sensor channel type. For implementation information, see Using sensor data in applications.
For information on which sensor channel types are supported in different devices, see Device specifications on Forum Nokia. You can also scan the target device to see which channel types it supports.
Sensor Data Compensator API (Nokia N97 SDK only)
The Sensor Data Compensator API, available in the Nokia N97 SDK, allows you to compensate sensor data for device or display orientation. This API is not available in the S60 5th Edition SDK, and is supported in the N97 device only.
Error handling
The leave mechanism and return values
are used to indicate errors. Use normal Symbian error handling practises,
including e.g. using the cleanup stack and the TRAP harness.
Listener callback interfaces (MSensrvDataListener, MSensrvPropertyListener, MSensrvChannelConditionListener, and MSensrvChannelListener) offer a callback method for informing of errors during listening.
Memory overhead
The Sensor channel API memory overhead depends on the channel's data rate and/or size of the data in the receiving buffer. A high data rate with a small data receiving buffer causes increased interprocess communication. On the other hand, a large data receiving buffer reserves more memory. See example in Listening for channel data.