Documentation of Compass Heading is not clear

[martinwork]

Describe the bug
Arising from support ticket https://support.microbit.org/helpdesk/tickets/93700 (private)

Looking at https://makecode.microbit.org/reference/input/compass-heading

Different numbers mean north, east, south, and west

"... doesn't say which numbers mean what, or what the orientation of the board needs to be for this to work."

Or which dimension of the micro:bit is the way it's "facing".

"It would probably be helpful for students if that information was on the page, otherwise it isn't obvious unless you test it yourself."

When you run a program that in the simulator, click and drag the compass needle on the screen to change the compass heading.

The simulator micro:bit logo serves to set the heading, but I don't think it acts as a compass needle, pointing north. When set to 90, to simulate the micro:bit facing east, the logo pointer direction is south.

This program finds the compass heading and then shows a letter that means whether the micro:bit is facing north (N), south (S), east (E), or west (W).

The program used to show letters, but now shows arrows. The arrows can be mistaken for an attempt to simulate a compass needle pointing north. The first arrows version worked that way.. When micro:bit is facing east, the arrow points south. Maybe letters are easier to understand?

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)

Currently, calibration is automatic only after a full flash.

Looking at https://makecode.microbit.org/device

Does the compass make it possible to detect the direction it is moving in? It could be facing north and moving southeast. I guess the magnetometer could be used to monitor movement near to a local magnetic field?

Looking at https://makecode.microbit.org/projects/compass

During calibration, the micro:bit should be held flat then smoothly tilted around it's centre, not shaken as in the video on this page.

[bfinio]

Does the compass make it possible to detect the direction it is moving in? It could be facing north and moving southeast. I guess the magnetometer could be used to monitor movement near to a local magnetic field?

The magnetometer gives the X, Y, and Z magnetic field strength in microtesla (uT). Using it as a "compass" with the compass heading block only works if 1) it's held flat (so the Earth's magnetic field is in the XY plane) and 2) there are no other nearby magnetic field sources affecting the reading. Moving around in a constant magnetic field while keeping the microbit orientation constant won't change the XYZ readings at all, so won't tell you anything about motion. i.e. if the microbit is pointing north, the readings won't change if you slide it east or west while keeping it pointed north. But yes, if there's a local magnetic field gradient due to the presence of a nearby magnet, you can detect relative motion between the microbit and the magnet.

[martinwork]

I think it's confusing to use "compass" and "magnetometer" interchangeably. The magnetometer detects magnetic fields, and a compass heading can be calculated from magnetometer measurements of the Earth’s magnetic field.

Something I had forgotten that might be worth mentioning is that the compass heading is "tilt compensated".
https://github.com/lancaster-university/codal-core/blob/master/source/driver-models/Compass.cpp#L361

The calculation uses the accelerometer to take account of the micro:bit not being level, but its value will jump if the micro:bit is moved (accelerated).

This example includes calculations without tilt compensation.
https://makecode.microbit.org/_cAW5RE353JY1

The horizontal one should match compass heading, and could be useful if the micro:bit is level but moving. The vertical one might be useful when the micro:bit is vertical.