pebble
  • Tutorials
  • Get the SDK
  • Guides
  • Documentation
  • Examples
  • Community
  • Blog
  • More
Privacy
Cookies
Publish

Pebble C API

  • Pebble C API
  • Pebble JavaScript API
  • PebbleKit JS
  • PebbleKit iOS
  • PebbleKit Android
  • Foundation
    • App
    • App Communication
    • App Glance
    • AppMessage
    • AppSync
    • AppWorker
    • DataLogging
    • DataStructures
      • UUID
    • Dictation
    • Dictionary
    • Event Service
      • AccelerometerService
      • AppFocusService
      • BatteryStateService
      • CompassService
      • ConnectionService
      • HealthService
      • TickTimerService
    • Exit Reason
    • Internationalization
    • Launch Reason
    • Logging
    • Math
    • Memory Management
    • Platform
    • Resources
      • File Formats
    • Storage
    • Timer
    • Wakeup
    • Wall Time
    • WatchInfo
    • Rocky
  • Graphics
    • Draw Commands
    • Drawing Paths
    • Drawing Primitives
    • Drawing Text
    • Fonts
    • Graphics Context
    • Graphics Types
      • Color Definitions
  • User Interface
    • Animation
      • PropertyAnimation
    • Clicks
    • Layers
      • ActionBarLayer
      • BitmapLayer
      • MenuLayer
      • RotBitmapLayer
      • ScrollLayer
      • SimpleMenuLayer
      • StatusBarLayer
      • TextLayer
    • Light
    • Preferences
    • UnobstructedArea
    • Vibes
    • Window
      • ActionMenu
      • NumberWindow
    • Window Stack
  • Standard C
    • Format
    • Locale
    • Math
    • Memory
    • String
    • Time

CompassService

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. It also 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.

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 Determining Direction guide.

For available code samples, see the feature-compass example.

Function Documentation

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

handler

A callback to be executed on heading events

See Also

compass_service_set_heading_filter
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
int compass_service_peek(CompassHeadingData * data)

Peek at the last recorded reading.

Parameters

data (out)

a pointer to a pre-allocated CompassHeadingData

Returns

Always returns 0 to indicate success.

Data Structure Documentation

struct CompassHeadingData

Structure containing a single heading towards magnetic and true north.

Data Fields

CompassHeading magnetic_heading

Measured angle that increases counter-clockwise from magnetic north (use int clockwise_heading = TRIG_MAX_ANGLE - heading_data.magnetic_heading; for example to find your heading clockwise from magnetic north).

CompassHeading true_heading

Currently same value as magnetic_heading (reserved for future implementation).

CompassStatus compass_status

Indicates the current state of the Compass Service calibration.

bool is_declination_valid

Currently always false (reserved for future implementation).

Enum Documentation

  • SDK 3
  • SDK 4
enum CompassStatus

Enum describing the current state of the Compass Service calibration.

Enumerators

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.

enum CompassStatus

Enum describing the current state of the Compass Service.

Enumerators

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.

Typedef Documentation

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.

typedef void(* CompassHeadingHandler)(CompassHeadingData heading)

Callback type for compass heading events.

Parameters

heading

copy of last recorded heading

Need some help?

Functions

  • compass_service_set_heading_filter
  • compass_service_subscribe
  • compass_service_unsubscribe
  • compass_service_peek

Data Structures

  • CompassHeadingData

Enums

  • CompassStatus

Typedefs

  • CompassHeading
  • CompassHeadingHandler

Getting Help

Do you have questions about the Pebble SDK?

Do you need some help understanding something on this page?

You can either take advantage of our awesome developer community and check out the SDK Help forums, or you can send us a message through the website!