compass Heading

Find which direction on a compass the micro:bit is facing.

The micro:bit measures the compass heading from 0 to 359 degrees with its magnetometer chip. Different numbers mean North, East, South, and West.

input.compassHeading()

Returns

• a number from 0 to 359 degrees, which means the compass heading. If the compass isn’t ready, it returns -1003.

Compass points

In history, a compass was a device that pointed in the direction of the magnetic North Pole. A needle or or a spot on a moving dial was magnetically attracted to the pole. Using a circular card or diagram arranged with direction indications you could align the indicator with the mark that meant “North” and see which direction the heading you wanted was in.

Magnetic compass
by Evan Amos, Public Domain

The compass pointer (needle) is always pointing to magnetic North. The compass dial might not have alignment with the needle. Once the needle is aligned with the dial, the compass will show what the direction is for a heading. The basic 4 compass points are North (W), East (E), South (S), and West (W). These are also called the Four Cardinal Directions.

In the compass examples below, the needle is pointing toward magnetic North. Next, the needle becomes aligned with the “N” symbol. If you wanted to walk East, you would take the compass and turn it so the “E” symbol is pointing directly ahead of you. While you walk East, keep the needle aligned with the “N” symbol.

Needle Heading	Compass Aligned

Directions and degrees

Modern compasses also use degree markings along with direction symbols. The compass dial shows degree markings from 0° to 360°.

The degree markings map to directions. Below is a list of directions and their degree values.

Besides the 4 Cardinal Directions, there are Intercardinal Directions like Northeast (shown in the list above). Additionally, there are direction names between the Cardinal and Intercardinal ones. One of these is North-Northeast (NNE) whose degree value is 22.5° and another is West-Southwest (WSW) at 247.5°.

basic.forever(function () {
    basic.showNumber(input.compassHeading())
    basic.pause(5000)
})

Examples

Digital compass

Display the current compass heading in degrees 0 - 359.

basic.forever(function () {
    basic.showNumber(input.compassHeading())
    basic.pause(1000)
})

Analog compass

Find the compass heading and then show an arrow that means whether the micro:bit is facing north (🠉), south (🠋), east (🠊), or west (🠈).

let degrees = 0
basic.forever(() => {
    degrees = input.compassHeading()
    if (degrees < 45) {
        basic.showArrow(ArrowNames.North)
    } else if (degrees < 135) {
        basic.showArrow(ArrowNames.East)
    } else if (degrees < 225) {
        basic.showArrow(ArrowNames.South)
    } else if (degrees < 315) {
        basic.showArrow(ArrowNames.West)
    } else {
        basic.showArrow(ArrowNames.North)
    }
})

Calibration

Every time you start to use the compass (for example, if you have just turned the micro:bit on), the micro:bit will start a calibrate compass (adjust itself). The calibration step will ask you to draw a fill pattern on the screen by tilting the micro:bit.

If you are calibrating or using the compass near metal, it might confuse the micro:bit.

input.onButtonPressed(Button.AB, () => {
    input.calibrateCompass();
})

See also

acceleration, calibrate compass