All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups
CompassService

Detailed Description

The Compass Service combines information from Pebble's accelerometer and magnetometer to automatically calibrate the compass and transform the raw magnetic field information into a CompassHeading, that is an angle to north.

The Compass Service provides magnetic north and information about its status and accuracy through the CompassHeadingData structure. The API is designed to also provide true north in a future release.

Calibration

The Compass Service requires an initial calibration before it can return accurate results. Calibration is performed automatically by the system when required. The compass_status field indicates whether the Compass Service is calibrating. To help the calibration process, your application should show a message to the user asking them to move their wrists in different directions.

Refer to the compass examples for suggestions on how to implement this screen.

Magnetic North and True North

Depending on your location on earth, the measured heading towards magnetic north and true north can significantly differ. This is called magnetic variation or declination.

Pebble does not currently automatically correct the magnetic heading to return a true heading, but the API is designed so that this feature can be added in the future and your applications will be able to automatically take advantage of it:

Battery Considerations

Using the compass will turn on both Pebble's magnetometer and accelerometer. Those two devices will have a slight impact on battery life. A much more significant battery impact will be caused by redrawing the screen too often or performing CPU-intensive work every time the compass heading is updated.

We recommend that you follow the following best practices to optimize for battery life:

Defining "up" on Pebble

Compass readings are always relative to the current orientation of Pebble. Using the accelerometer, the Compass Service figures out what is the direction that the user is pointing at.

If Pebble is held flat, the compass heading will be the angle between a vector to north and a vector going from the bottom to the top of Pebble in a plane parallel to the screen (the Y axis vector of the accelerometer). If the user lifts their arm so that Pebble is held vertical in front of them, compass heading will be relative to a vector going through Pebble (opposite to the Z axis vector of the accelerometer). If the user keeps bringing their arm up, effectively holding the Pebble upside down, the compass heading will be relative to a line from the top to the bottom of Pebble, in the plane of the screen (opposite to the Y axis vector of the accelerometer).

Code Samples

For available code samples, see Examples/watchapps/feature_compass.

Function Documentation

int compass_service_peek ( CompassHeadingData data)

Peek at the last recorded reading.

Parameters
[out]dataa pointer to a pre-allocated CompassHeadingData
Returns
Always returns 0 to indicate success.
int compass_service_set_heading_filter ( CompassHeading  filter)

Set the minimum angular change required to generate new compass heading events. The angular distance is measured relative to the last delivered heading event. Use 0 to be notified of all movements. Negative values and values > TRIG_MAX_ANGLE / 2 are not valid. The default value of this property is TRIG_MAX_ANGLE / 360.

Returns
0, success.
Non-Zero, if filter is invalid.
See Also
compass_service_subscribe
void compass_service_subscribe ( CompassHeadingHandler  handler)

Subscribe to the compass heading event service. Once subscribed, the handler gets called every time the angular distance relative to the previous value exceeds the configured filter.

Parameters
handlerA callback to be executed on heading events
See Also
compass_service_set_heading_filter
compass_service_unsubscribe
void compass_service_unsubscribe ( void  )

Unsubscribe from the compass heading event service. Once unsubscribed, the previously registered handler will no longer be called.

See Also
compass_service_subscribe

Data Structure Documentation

struct CompassHeadingData

Structure containing a single heading towards magnetic and true north.

Data Fields
CompassStatus compass_status indicates the current state of the Compass Service calibration
bool is_declination_valid true, if the current declination is known and applied to true_heading, false otherwise
CompassHeading magnetic_heading measured angle relative to magnetic north
CompassHeading true_heading measured angle relative to true north (or to magnetic north if declination is invalid)

Typedef Documentation

typedef int32_t CompassHeading

Represents an angle relative to a reference direction, e.g. (magnetic) north. The angle value is scaled linearly, such that a value of TRIG_MAX_ANGLE corresponds to 360 degrees or 2 PI radians. Thus, if heading towards north, north is 0, east is TRIG_MAX_ANGLE/4, south is TRIG_MAX_ANGLE/2, and so on.

typedef void(* CompassHeadingHandler)(CompassHeadingData heading)

Callback type for compass heading events.

Parameters
headingcopy of last recorded heading

Enumeration Type Documentation

Enum describing the current state of the Compass Service calibration.

Enumerator
CompassStatusDataInvalid 

Compass is calibrating: data is invalid and should not be used.

CompassStatusCalibrating 

Compass is calibrating: the data is valid but the calibration is still being refined.

CompassStatusCalibrated 

Compass data is valid and the calibration has completed.

Macro Definition Documentation

#define TRIGANGLE_TO_DEG (   trig_angle)    (((trig_angle) * 360) / TRIG_MAX_ANGLE)

Converts from a fixed point value representation of trig_angle to the equivalent value in degrees.