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.
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.
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:
magnetic_heading
field and use a webservice to retrieve the declination at your current location.true_heading
field. This field will contain the magnetic heading if declination is not available, or the true heading if declination is available. The field is_declination_valid
will be true when declination is available. You can use this information to tell the user whether you are showing magnetic north or true north.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:
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).
For available code samples, see Examples/watchapps/feature_compass
.
int compass_service_peek | ( | CompassHeadingData * | data) |
Peek at the last recorded reading.
[out] | data | a pointer to a pre-allocated CompassHeadingData |
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.
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.
handler | A callback to be executed on heading events |
void compass_service_unsubscribe | ( | void | ) |
Unsubscribe from the compass heading event service. Once unsubscribed, the previously registered handler will no longer be called.
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 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.
heading | copy of last recorded heading |
enum CompassStatus |
Enum describing the current state of the Compass Service calibration.
#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.