Accessing Device Sensors

The PDK provides a set of unified APIs for accessing a number of device sensors.

Physical and Logical Sensors

Sensors are devices sensitive to light, movement, magnetic fields, and so on, such as accelerometers, gyroscopes and ambient light sensors (ALS) that transmit a signal to monitoring device software. Some of these sensors are physical, while others are logical, deriving their values from one or more physical sensor values.

In this section:

Advanced Sensor Use
Supported Sensors
Sensor APIs and Basic Process
Links

See also:

C/C++ sensor defines - One define for each type of supported sensor.
C/C++ sensor event structs - Each sensor has its own event struct. However, the two APIs that return sensor events always return the same struct, which is a union of all the different sensor structs.

Advanced Sensor Use

Examples of advanced sensor use include:

Mobile Gaming

Mobile gaming improves significantly when mobile device motion directly controls game input. A 3-axis accelerometer can support basic gaming, with improved motion control enabled with a combination of accelerometer and gyroscope (or alternatively magnetometer).

Image Stablization

The latest generation of smartphones include high-definition (HD) camcorders, which benefit greatly from gyroscope assisted image stabilization to minimize handheld camera shake.

Augmented Reality

Augmented reality browsers, which superimpose web derived scene data onto a cellphone display, require precise heading information (provided by a compass) and also benefit from image stabilization to insure a stable display.

Navigation

Accurate navigation applications will rely heavily on data from multiple motion sensors. Net-connected cellphones, as a primary navigation device, both in-vehicle and for pedestrian use, are being increasingly used. While GPS provides accurate location outdoors, given technology limits, it is generally not available indoors or sporadically available in dense urban areas. Motion sensors support dead reckoning - tracking a user's position from the last known position - enabling accurate positioning indoors and in GPS-challenged areas.

Supported Sensors

The PDK currently supports the following sensors:

Accelerometer

Moving or tilting an accelerometer allows you to control device orientation.

Acceleration is measured in g-forces along 3-axes:

Each axis measures direction and force. A zero result for a specific axis means there is no force acting on the accelerometer. For example, if you set the device flat on a table, the X and Y axes will measure at, or close to, zero. As you tilt the device left, the X-axis acceleration becomes increasingly negative. If you then center it and tilt it right, it becomes increasingly positive.
Ambient Light Sensor (ALS)

An ALS is a light-sensitive electronic component used to adjust the brightness of an LCD display's backlight so that the display remains comfortably readable over a range of ambient light conditions.

An ALS event returns the device's ambient light level in SI lux units, a measure of a surface's luminosity. One lux is equal to one lumen per square meter. Office lighting typically measures between 320-500 lux.

It is up to the caller to determine what the lux value means for the current device.
Angular Velocity

The angular velocity sensor returns a vector quantity specifying the angular speed of a device and the axis about which the device is rotating. The magnitude, or length, of the angular velocity vector is directly proportional to the angular speed, and is measured in the same units as angular speed (radians per second).

The direction of the angular velocity vector is perpendicular to the plane in which the rotation takes place. If the rotation appears clockwise with respect to an observer, then the angular velocity vector points away from the observer. If the rotation appears counterclockwise, then the angular velocity vector points toward the observer.
Compass

The compass sensor returns magnetic north and true north bearings.
Gravity
A gravity sensor generates a three dimensional vector indicating the gravity event's direction and magnitude.
Linear Acceleration

Linear acceleration is the rate of change in velocity over a given time period of an object moving in one direction.

A linear acceleration event returns a three-dimensional vector indicating acceleration along each device axis, not including gravity. All values have units of m/s^2 (meters per second squared). The coordinate system is the same as that used by the accelerometer.
Magnetic Field

This sensor measures magnetized direction relative to the Earth's poles. A magnetic field event returns data for a device's ambient magnetic field in the X, Y and Z-axes. All values are in micro Teslas (uT).
Orientation

An orientation event gives the device's general position:
- Facing up
- Facing down
- Normal orientation -The device's default orientation - for tablets, this is button on the bottom and camera on the top with the device perpendicular to the ground.
- Upside-down
- Left-side facing down
- Right-side facing down
Proximity

The proximity sensor generates an event if an object comes close (approximately, an inch or less) to a device. A close object moving away also generates an event.
For example, the Phone app uses the proximity sensor to turn the screen off when a person holds the phone close to their face. Doing this prevents the user from accidentally pressing buttons with their cheek while talking on the phone.
Rotation

The rotation sensor can return 3 sets of equivalent values for a rotation event:
1. Rotation matrix - In linear algebra, a rotation matrix is used to perform a rotation in Euclidean space. You can use rotation matrices to perform transformations in openGL programming.
2. Quaternions - A quaternion represents two things. It has an x, y, and z component, which represents the axis about which a rotation will occur. It also has a w component, which represents the amount of rotation that will occur about this axis. With these four numbers, it is possible to build a matrix that represents all the rotations perfectly, with no chance of gimbal lock.
3. Tait-Bryan angles - Three angles that describe device orientation. These angles are also known as "yaw", "pitch" and "roll" and are used in conventional flight dynamics.
Each of these sets of values can be used to represent an object's rotation. It is up to the caller to decide which one to use. You can use rotation matrices, for example, with openGL programming.
Shake

A shake sensor event returns a value for state:
- No shaking
- Shaking started
- Shaking continuing
- Shaking stopped
And a value for shake magnitude, or how vigorous the shaking is, in units of gravitational acceleration or g's.

Sensor APIs and Basic Process

The PDK provides four APIs for calling sensors:

PDL_SensorExists - Returns flag indicating if sensor exists on a device.
PDL_EnableSensor - Enables or disables a sensor. Once enabled, your app can receive the sensor's events. Once disabled, the events stop.
PDL_PollSensor - Gets events from a specific, enabled sensor.
PDL_PollActiveSensors - Same as PDL_PollSensor, but returns the first event available for all the currently active sensors.

Basic Process for Accessing an Individual Sensor

As the above APIs suggest, the following is the basic process for accessing an individual sensor:

Determine if sensor exists.
If sensor exists, enable it.
If sensor is enabled, poll on its events. Each sensor event returns the same union structure.
Use data returned from sensor event.
Disable sensor when done polling.

Including Sensor APIs and Data Types in Your Code

This is the same process as the one for including all PDK code:

Have an #include "PDL.h" line in your source file.
Link with "-- lpdl". The libpdl.so file can be found in your PDK's /lib directory.

The sensor API declarations and data types can be found in PDL_Sensor.h.

Links

Here are links to more information about sensor technology.