Compensating sensor data for device or display orientation

Use the Sensor Data Compensator API to compensate sensor data for device or display orientation. This is recommended in order to get correct sensor axis data in relation to the mobile device user's current display orientation, i.e. adjust the coordinate system.

Note: The Sensor Data Compensator API is only available in the Nokia N97 SDK.

The figure below depicts the adjusting of the coordinate system in the Nokia N97.

Figure: Adjusting of the coordinate system in the Nokia N97.

You can get an idea how the sensor data compensation works by using the Maps application of Nokia N97, the keyboard opened and closed. The behaviour is the following:

Phone position Phone movement Application behaviour
The keyboard is closed and the display is upward and parallel with the table surface Phone spins around the z-axis The compass needle points to the north and the map doesn’t move on the screen
The keyboard is opened and the display is upward and parallel with the table surface Phone spins around the z-axis The compass needle points to the north and the map is all the time in the north-south direction on the screen

The coordinate and angle data provided from different sensors with the API set are always bound to the device form factor and hardware configurations, using one coordinate system named as the device base coordinate system (see Accelerometer sensor channel for more information about the coordinate system).

For example, if the display orientation changes, the accelerometer sensor still provides the axis data by using the device base coordinate system. In order to convert the axis data to match the current display orientation, illustrated in the figure below, the Sensor Data Compensator API is provided for adjusting the coordinate system to match the changed system characteristics. This procedure is called sensor data compensation.

For converting the raw sensor data to the compensated values, the adjustment values (e.g. interchanging x-axis with y-axis) for each device state the compensation is applied to need to be configured and taken as an input for calculations. These values are called compensation data, also referred to as compensation values in this document.

Figure: Example of adjustment of the coordinate system due to device orientation change

The Sensor Data Compensator API allows you to compensate sensor data for the following, defined in TSensorCompensationType:

Data compensation based on

Triggered when

Display orientation

The display orientation is changed from portrait to landscape

Device orientation

The N97 keyboard is opened, resulting in the display being at an angle to the keyboard.

Both device and display orientation

Either or both of the above

To compensate sensor data for device or display orientation using the Sensor Data Compensator API, follow the steps below:

  1. Create a new CSensorDataCompensator object.

  2. Use the Compensate() method of the CSensorDataCompensator object to carry out the compensation.

    In order to avoid compensation errors, first ensure that the data received from the sensor channel is not already compensated by using the CSensrvChannel::GetPropertyL() method as in the example below. For more information, see Getting channel properties.
    // 'iChannel' contains an open channel
TSensrvProperty property;
TRAPD( err, iChannel->GetPropertyL( KSensrvPropIdChannelDataCompensation, KSensrvItemIndexNone, property ) );
if ( err == KErrNone && property.PropertyType() == ESensrvIntProperty )
     {
     // Channel data is compesated, check the compensation type
     TInt compensationType;
     property.GetValue( compensationType );
     // 'compensationType' contains now a value from TSensorCompensationType enumeration declared in sensordatacompensationtypes.h
     }
else
     {
     // Channel data is not compesated
     }

You can use the Sensor Data Compensator API for data from the following sensor channel types and related data classes:

Sensor channel type

Data class

Accelerometer axis data

TSensrvAccelerometerAxisData

Magnetometer axis data

TSensrvMagnetometerAxisData

Accelerometer double-tap

TSensrvTappingData

Note: In the Nokia N97 device, data from the Magnetic North sensor channel is compensated for display and device orientation by default.

Example

The example below illustrates using the Sensor Data Compensator API.

The example assumes you have opened a sensor channel and implemented the listener interface MSensrvDataListener, where the method DataReceived() is derived from. For further information, see Listening for channel data.

You must also have successfully registered as a listener to the accelerometer data channel with the iSensorChannel object, which is an instance of the CSensrvChannel class also belonging to the Sensor Channel API.

#include <sensordatacompensator.h> // link against sensordatacompensator.lib

void CMyClass::ConstructL()

   {
   // iSensorChannel already instantiated and registered
   if ( !AlreadyCompensated() )
          {
          iCompensator = CSensorDataCompensator::NewL( 
          TSensrvAccelerometerAxisData::KDataTypeId, 
           ESensorCompensateDeviceAndUIOrientation );
          }
   }


CMyClass::~CMyClass()

   {
   delete iCompensator;
   }


void CMyClass::DataReceived( CSensrvChannel& aChannel,

                            TInt /*aCount*/, 
                            TInt /*aDataLost*/ )
   {
    
   TPckgBuf<TSensrvAccelerometerAxisData> dataBuf;
   iSensorChannel->GetData( dataBuf );

   if ( iCompensator )
       {
       if ( iCompensator->Compensate( dataBuf ) == KErrNone )
           {
           // Now use the compensated data.
           }
       }
© Nokia 2009.