Skip to content

March 4, 2012


Compass App

by Colin

In this tutorial we will access the Compass feature from PhoneGap. With this feature we can obtain the direction that the device is pointing to.

To demonstrate the use of this feature I built an application that acts as a Compass, it points to the North. This only works on the device.

End result:

This tutorial has be done on a Mac and tested on a HTC Desire running Android 2.2. This doesn’t really matter as what we do is cross platform but it’s informative.

Download the source code and let’s begin.

The compass sensor detects the direction that the device is pointing. It is measured in degrees from 0 to 359.99.


<!DOCTYPE html>

<!– jQuery Mobile Setup –>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="libs/" />
<script type="text/javascript" charset="utf-8" src="libs/jquery-1.7.1.min.js"></script>
<script type="text/javascript" charset="utf-8" src="libs/"></script>
<!– PhoneGap Setup –>
<script type="text/javascript" charset="utf-8" src="libs/phonegap-1.4.1.js"></script>

<link rel="stylesheet" href="css/style.css" />
<script type="text/javascript" charset="utf-8" src="js/script.js"></script>

<div data-role="page" id="compass">
<div data-role="header" data-position="fixed">
<div data-role="content">
<a href="#" id="showNorthBtn" data-role="button">Which way is North?</a>
<div id="arrow"><img src="img/round_arrow_right.png"></div>
<a href="#" id="startBtn" data-role="button">Start</a>
<a href="#" id="stopBtn" data-role="button">Stop</a>

First set up the jQuery, jQuery Mobile framework and PhoneGap so we can have a nice interface for our app. In case you forgot how to do this follow the Basic cross-platform mobile app with jQuery Mobile and PhoneGap one more time.

The structure of our page is simple, we have a header where we set up our application’s title and the content content area where we have three buttons and an arrow image which will point to north when the buttons are tapped.

The JavaScript code:

window.addEventListener(‘load’, function(){
// Wait for PhoneGap to load
document.addEventListener("deviceready", onDeviceReady, false);
}, false);

// The watch id references the current `watchHeading`
var watchID = null;

// PhoneGap is ready
function onDeviceReady() {
var showNorthBtn = $(‘#showNorthBtn’);
var startBtn = $(‘#startBtn’);
var stopBtn = $(‘#stopBtn’);{
navigator.compass.getCurrentHeading(onSuccess, onError);

// Start watching the compass
function startWatch() {

// Update compass every 2 seconds
var options = { frequency: 2000 };

watchID = navigator.compass.watchHeading(onStartSuccess, onError, options);

// Stop watching the compass
function stopWatch() {
if (watchID) {
watchID = null;

// onStartSuccess
function onStartSuccess(heading) {
var arrow = $(‘#arrow’);
var arrowOrientation = 360 – heading.magneticHeading;
‘-webkit-transform’,’rotate(‘ + arrowOrientation + ‘deg)’

// onSuccess: Get the current heading
function onSuccess(heading) {
var arrow = $(‘#arrow’);
var arrowOrientation = 360 – heading.magneticHeading;
‘-webkit-transform’,’rotate(‘ + arrowOrientation + ‘deg)’

// onError: Failed to get the heading
function onError(compassError) {
alert(‘Compass Error: ‘ + compassError.code);

The Compass is accessed through the navigator.compass.getCurrentHeading(compassSuccess, compassError, compassOptions); method. If it returns success the compassSuccess callback function is triggered else the compassError callback function is triggered returning an error, you can also add other options such as frequency and pass it to the compassOptions as arguments.

In our case when the “Which way is North?” button is pressed the onSuccess() function calculates the North position and performs a rotation to the image.

To calculate the position of North I used the following formula: var arrowOrientation = 360 - heading.magneticHeading;. With heading.magneticHeading we obtain the degrees of our devices current position. With these coordinates I am able to rotate the arrow image in the direction North is.

When you press the Start button the onStartSuccess() function is called and the arrow will change it’s position live with a 1 second frequency that we set. To stop this process press the Stop button.

That’s all. Good luck!

2 Comments Post a comment
  1. alibaba
    Jun 30 2012

    access forbidden to download the file. Can you re enable it back?

    • noise
      Jun 30 2012

      Now it should work. Please test if you can download the archive.


Leave a Reply


Note: HTML is allowed. Your email address will never be published.

Subscribe to comments