Pebble Foundation Classes  0.2.0
C++ for Pebble
Classes | Typedefs | Enumerations | Functions
CompassService
Foundation » EventService
Collaboration diagram for CompassService:

Classes

struct  CompassHeadingData
 Structure containing a single heading towards magnetic and true north. More...
 

Typedefs

typedef int32_t CompassHeading
 
typedef void(* CompassHeadingHandler) (CompassHeadingData heading)
 
typedef int32_t CompassHeading
 
typedef void(* CompassHeadingHandler) (CompassHeadingData heading)
 

Enumerations

enum  CompassStatus {
  CompassStatusUnavailable = -1, CompassStatusDataInvalid = 0, CompassStatusCalibrating, CompassStatusCalibrated,
  CompassStatusUnavailable = -1, CompassStatusDataInvalid = 0, CompassStatusCalibrating, CompassStatusCalibrated
}
 Enum describing the current state of the Compass Service. More...
 
enum  CompassStatus {
  CompassStatusUnavailable = -1, CompassStatusDataInvalid = 0, CompassStatusCalibrating, CompassStatusCalibrated,
  CompassStatusUnavailable = -1, CompassStatusDataInvalid = 0, CompassStatusCalibrating, CompassStatusCalibrated
}
 Enum describing the current state of the Compass Service. More...
 

Functions

int compass_service_set_heading_filter (CompassHeading filter)
 
void compass_service_subscribe (CompassHeadingHandler handler)
 
void compass_service_unsubscribe (void)
 
int compass_service_peek (CompassHeadingData *data)
 

Detailed Description

\brief 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 \ref CompassHeading,
that is an angle to north. It also
provides magnetic north and information about its status and accuracy through the \ref
CompassHeadingData structure. The API is designed to also provide true north in a future
release.

Note that not all platforms have compasses. To check for the presence of a compass at
compile time for the current platform use the `PBL_COMPASS` define.

To learn more about the Compass Service and how to use it, read the
<a href="https://developer.getpebble.com/guides/pebble-apps/sensors/magnetometer/">
Determining Direction</a> guide.

For available code samples, see the
<a href="https://github.com/pebble-examples/feature-compass">feature-compass</a> example.

Typedef Documentation

◆ CompassHeading [1/2]

typedef int32_t CompassHeading

Represents an angle relative to get 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, west is TRIG_MAX_ANGLE/4, south is TRIG_MAX_ANGLE/2, and so on.

◆ CompassHeading [2/2]

typedef int32_t CompassHeading

Represents an angle relative to get 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, west is TRIG_MAX_ANGLE/4, south is TRIG_MAX_ANGLE/2, and so on.

◆ CompassHeadingHandler [1/2]

typedef void(* CompassHeadingHandler) (CompassHeadingData heading)

Callback type for compass heading events

Parameters
headingcopy of last recorded heading

◆ CompassHeadingHandler [2/2]

typedef void(* CompassHeadingHandler) (CompassHeadingData heading)

Callback type for compass heading events

Parameters
headingcopy of last recorded heading

Enumeration Type Documentation

◆ CompassStatus [1/2]

enum CompassStatus

Enum describing the current state of the Compass Service.

Enumerator
CompassStatusUnavailable 

The Compass Service is unavailable.

CompassStatusDataInvalid 

Compass is calibrating: data is invalid and should not be used Data will become valid once calibration is complete

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.

CompassStatusUnavailable 

The Compass Service is unavailable.

CompassStatusDataInvalid 

Compass is calibrating: data is invalid and should not be used Data will become valid once calibration is complete

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.

◆ CompassStatus [2/2]

enum CompassStatus

Enum describing the current state of the Compass Service.

Enumerator
CompassStatusUnavailable 

The Compass Service is unavailable.

CompassStatusDataInvalid 

Compass is calibrating: data is invalid and should not be used Data will become valid once calibration is complete

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.

CompassStatusUnavailable 

The Compass Service is unavailable.

CompassStatusDataInvalid 

Compass is calibrating: data is invalid and should not be used Data will become valid once calibration is complete

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.

Function Documentation

◆ compass_service_peek()

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.

◆ compass_service_set_heading_filter()

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

◆ 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

◆ 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