Skip to main content

External Compass Orientation

Almost every GPS module for drones has a magnetometer — a compass — built into it. The autopilot needs that compass to know which way the aircraft is facing, which is what makes position hold, return-to-home and waypoint navigation work rather than drift in circles.

There is a catch. The compass chip is soldered onto the module at whatever angle the board designer chose, and the module is then bolted onto your airframe at whatever angle your build allows. The firmware has no way to discover either angle on its own, so you have to tell it — and that is what the orientation parameter does.

Get it wrong and nothing looks broken. Calibration completes, the compass reports a heading, no error appears. The heading is simply wrong by a fixed amount, and the aircraft flies toward the wrong place in an auto mode.

Using the flight controller's built-in compass?

Then none of this applies. Leave the orientation parameter at its default and just run a compass calibration. This page is about an external compass — the one inside a GPS or RTK module.

The reference orientation​

Everything below is defined against one standard way of mounting the module: seen from above with the nose pointing away from you, the module's printed label reads normally and its connector faces the tail.

If that is how your module sits, take the value straight from the tables. If you had to rotate it to fit the frame, add the rotation:

The four mounting rotations of a GPS compass module and how each changes the orientation value

Module rotated (viewed from above)Value to use
Reference — connector to the tailthe table value
90° clockwise — connector to the lefttable value + 90°
180° — connector to the nosetable value + 180°
270° clockwise — connector to the righttable value + 270°

Values wrap at 360°. On ArduPilot, a module whose table value is YAW270, mounted 90° clockwise, needs 270 + 90 = 360 → NONE, not YAW360.

What each firmware calls it​

ArduPilot​

The parameter is COMPASS_ORIENT.

ArduPilot tries to work this out for you: automatic orientation detection is on by default, and during a compass calibration it compares the external compass against a working internal compass to deduce the external one's rotation. When the flight controller has a usable internal compass, this generally just works.

When it does not have one — an AIO board, or a board whose internal compass you have disabled — there is nothing to compare against, and you must turn auto-detection off and set COMPASS_ORIENT by hand.

PX4​

The parameter is CAL_MAGx_ROT, where x is the magnetometer instance number. Most aircraft carry a single external compass, so find the instance that corresponds to it and set that one.

PX4 has an equivalent auto-detection option, SENS_MAG_AUTOROT, with the same limitation: on a board with no internal magnetometer it typically cannot arrive at the right answer even when enabled. On an AIO board running PX4, set CAL_MAGx_ROT manually from the tables.

INAV and Betaflight​

These two work differently, and there is a step before the parameter.

Both ship two builds per board:

  • intmag — for a board with an internal magnetometer
  • extmag — for a board using an external one

A GPS or RTK module's compass is only used by an extmag build. Flash intmag and the compass will not appear at all, whatever you do in the configurator — this is the first thing to check when INAV or Betaflight refuses to see a compass that is definitely wired correctly.

Neither firmware auto-detects orientation on an extmag build, so the alignment always has to be set by hand from the tables.

Orientation values​

Values are for the reference orientation described above. For a rotated mount, add 90° per clockwise step.

GPS modules with a patch antenna​

FirmwareMG-A01M10G-5883MG-902MG-903
ArduPilot COMPASS_ORIENTYAW90YAW270YAW90YAW270
PX4 CAL_MAGx_ROTROTATION_PITCH_180ROTATION_ROLL_180ROTATION_PITCH_180ROTATION_ROLL_180_YAW_90
INAVCW 0° flipCW 180° flipCW 0° flipCW 270° flip
BetaflightCW 0° flipCW 180° flipCW 0° flipCW 270° flip

Specifications and wiring for these four: GPS Module User Manual.

Dual-band GNSS and RTK modules​

The MG-F10 series and the whole MA-RTK family share one set of values:

FirmwareMG-F10-A · MG-F10-C · MA-RTK-AIR-626 · MA-RTK-AIR-F9P · MA-RTK-AIR-982
ArduPilot COMPASS_ORIENTROLL180_YAW270
PX4 CAL_MAGx_ROTROTATION_YAW_90
INAVCW 90°
BetaflightCW 90°

Rotated mounts follow the same rule — on ArduPilot the roll component stays and the yaw advances: ROLL180_YAW270 → ROLL180 → ROLL180_YAW90 → ROLL180_YAW180 for each further 90° clockwise.

Betaflight support for these arrived in December 2025

Betaflight builds from December 2025 onward include the driver for the compass in the MG-903, MG-F10 and MA-RTK modules. Earlier builds will not detect them regardless of wiring or alignment.

AIO flight controllers need this done by hand​

MicoAir's AIO boards — flight controller and ESC on one board — have no internal compass. That single fact changes the procedure, because it removes the reference that ArduPilot's and PX4's auto-detection depend on.

ArduPilot on an AIO board​

  1. Connect the flight controller in MicoConfigurator.
  2. Go to Sensors → Compass.
  3. Turn off automatic orientation detection.
  4. Set COMPASS_ORIENT by hand from the table above.
  5. Run a compass calibration.
  6. Check that the heading shown in the ground station matches where the nose actually points.

PX4 on an AIO board​

  1. Connect the flight controller in MicoConfigurator.
  2. Go to Sensors → Compass.
  3. Turn off automatic orientation detection.
  4. Set CAL_MAGx_ROT by hand from the table above.
  5. Run a full compass calibration.
  6. Check the heading against the real nose direction.

INAV or Betaflight on an AIO board​

  1. Flash the extmag build for your board.
  2. Connect the INAV or Betaflight configurator.
  3. Confirm the external compass is detected.
  4. Set the alignment by hand from the table above.
  5. Save and reboot the flight controller.
  6. Run a compass calibration.
  7. Check the heading against the real nose direction.

In all three cases you are done when: calibration completes, the displayed heading matches the nose, and turning the aircraft moves the heading the same way.

Verify it with a phone​

The quickest honest check needs nothing but the compass app already on your phone.

  1. Open the phone's compass.
  2. Hold the phone flat with its top pointing the same way as the aircraft's nose.
  3. Read the phone's heading, and read the heading in your ground station.
  4. Turn the aircraft slowly, keeping the phone aligned with the nose as you go.

The two readings should agree, and should change together in the same direction. Check near 0°, 90°, 180° and 270° rather than at one angle only — some errors only show up on part of the circle.

Only once the heading is right should you arm and fly.

A calibrated compass can still be a wrong compass

Compass calibration and compass orientation fix different problems. Calibration removes the magnetic distortion caused by your airframe; orientation tells the firmware which way the sensor is facing. A perfectly calibrated compass with the wrong orientation reports a confident, stable, wrong heading — and the aircraft will fly on it.

Easily confused points​

Different modules from the same maker need different values. The M10G-5883 and the MG-A01 are both u-blox M10 modules with a QMC5883L compass, and they need YAW270 and YAW90 respectively. Never copy a value from another module.

Orientation is not the same as calibration. Both are required, and each is useless without the other.

"Auto-detect" needs something to compare against. It works by checking the external compass against an internal one. No internal compass, no auto-detection — which is exactly the case on AIO boards, where people most expect it to work.

intmag and extmag are different firmware, not a setting. In INAV and Betaflight this is chosen when you flash, not in the configurator.

A 90/180/270° error is an orientation problem; a wandering heading is an interference problem. A constant offset means a wrong parameter. A heading that drifts when you push the throttle means the compass is too close to the power wiring.

The flight controller's own orientation parameter is a separate setting. ArduPilot's AHRS_ORIENTATION describes how the board is mounted. Setting that when you meant COMPASS_ORIENT breaks the whole attitude estimate, not just the heading.

Troubleshooting​

SymptomLikely cause
Compass not detected at allOn INAV/Betaflight: intmag firmware flashed instead of extmag. On any firmware: the I2C pair (SCL/SDA) not connected or swapped.
Calibration will not completeToo much magnetic interference, or the module is loose and moving relative to the airframe.
Heading off by exactly 90°, 180° or 270°Wrong orientation value — recheck the table for your exact module and mounting rotation.
Heading turns the wrong wayThe module is mounted mirrored or flipped relative to what the value assumes; re-examine which face is up.
Heading drifts with throttleMagnetic interference from battery leads, ESCs or motors. Move the compass further away, then recalibrate.
Auto-detect sets an obviously wrong valueThe board has no usable internal compass to compare against. Turn auto-detect off and set the value manually.

Written and maintained by the Robofusion engineering team.