Advanced Compass Setup

This article provides advanced guidance for how to setup the system compass(es) and advanced compass related features.


Users who have only internal compasses or an external compass using the UBlox GPS + Compass Module (recommended) and have mounted it in the default orientation can usually perform a simple “Onboard Calibration” as described in Compass Calibration).


Accurately setting up the compass is critical because it is the primary source of heading information. Without an accurate heading the vehicle will not move in the correct direction in autopilot modes (i.e. AUTO, LOITER, PosHold, RTL, etc). This can lead to circling (aka “toiletbowling”) or fly-aways.

ArduPilot currently allows up to three compasses to be connected. Only one compass (specified using the COMPASS_PRIMARY parameter) is used for navigation. While many autopilots have an internal compass or compasses, many will instead use an external compass. This provides more reliable data than an internal compass because of the separation from other electronics. See Autopilot Hardware Options for details about the specific autopilot to determine how many built-in compasses the autopilot may have, if any.

Most users will only need to select compass configuration and perform the Basic Compass Calibration but details are also given on the less-used CompassMot and Manual Declination. Most of this configuration can be performed from the Mission Planner’s Initial Setup | Mandatory Hardware | Compass screen. Other ground stations may have similar features.


The article is Copter-focused but the instructions are equally applicable to Plane and Rover (except where marked).

Configuration settings

The Mission Planner Compass Setup screen can be found in menu Initial Setup | Mandatory Hardware | Compass in the sidebar. This screen is used for setting almost all compass configuration and tuning parameters.


Mission Planner: Compass Calibration

Quick configuration for Pixhawk

Mission Planner supports automatic configuration of almost all parameters for the Pixhawk autopilot boards. If it is a Pixhawk autopilot, select the button Pixhawk/PX4. You may be prompted for a specific ArduPilot version.

Configuration for non-Pixhawk Autopilots

  • First determine how many on-board compasses the autopilot includes and enable those compasses. For example, if two compasses are integrated on-board, check the “Use this compass” box for Compass 1 and 2, and make sure that “External compass” boxes are unchecked. If you chose not use one of the internal compasses, then do not check its “Use this compass” box.
  • If using an external compass, check the appropriate the appropriate “Use this compass” box. It should be the one following the internal compasses, whether being used, or not. If your external compass is in a non-standard orientation, you can manually select the orientation (aligned with IMU orientation)in the combo box (change from ROTATION_NONE). See the Checking Compass Orientation Section below. However, ArduPilot 4.0 and later firmware versions will automatically determine orientation when the Onboard Mag Calibration routine is run. When externally connected, the COMPASS_ORIENT parameter is independent of the AHRS_ORIENTATION board orientation option.
  • The AHRS_ORIENTATION must be set correctly for the compass calibration to be successful. In addition,the Accelerometer Calibration should be completed before the Compass Calibration.

Most users will then only need to press the OnBoard Mag Calibration button and perform a Onboard Calibration.

Checking Compass Orientation

  • Ensure your AHRS_ORIENTATION parameter is correct. This will ensure that your internal compass’ orientation will be correct
  • When rotating your aircraft through all axes each of the compasses should move in the same direction, and should be of approximately the same values
  • Northern Hemisphere: - Z-component should be positive - when pitching the vehicle down, the X component should increase in value - when rolling the vehicle right, the Y component should increase in value
  • Southern Hemisphere: - Z-component should be negative - when pitching the vehicle down, the X component should decrease in value - when rolling the vehicle right, the Y component should decrease in value

These should be correct for any on-board compasses, since the orientation is defined in the autopilots definition file for the firmware.

General settings

The general settings apply to all compasses connected to the autopilot controller:

  • Enable compasses: determines whether whether (any) compasses are enabled. If enabled the autopilot will use the primary compass for heading data, otherwise the heading will be estimated from GPS. Enabling this checkbox corresponds to setting parameter MAG_ENABLE=1.


    Compasses should always be enabled for Copter/Rover, but may be

    disabled (not recommended) for Plane.

  • Primary Compass: specifies which compass ArduPilot will use for heading data (only one compass is used for navigation). Normally this will be set to the first compass (“Compass1”). This selection list corresponds to setting the parameter COMPASS_PRIMARY to a value from 0 to 2 (compasses are 0 indexed, even though labelled in the screen from 1 to 3).

  • Obtain declination automatically: sets the declination based on lookup tables following GPS lock. Users can override this default behaviour; after deselecting the checkbox (COMPASS_AUTODEC=0) they can manually enter declination in COMPASS_DEC.

  • Automatically learn offsets: See Automatic Offset Learning section below.

Compass specific settings

The settings that are specific to each compass are grouped together. Some settings are only visible when the compass is enabled.

  • Use this compass: This checkbox enables a particular compass for use by the autopilot. Each checkbox corresponds to a COMPASS_USEx parameter (where x is 0 to 2, depending on the compass).


    Even if multiple COMPASS_USEx parameters are set to 1, the

    autopilot will still only uses the primary compass (COMPASS_PRIMARY).

  • Externally mounted: Set whether or not a particular compass is externally mounted (corresponds to COMPASS_EXTERNAL=1). If the compass is internal it uses the autopilot’s orientation (AHRS_ORIENTATION). If the compass is external, the orientation may differ from the autopilot (set using the selection list discussed next)

  • Compass orientation: sets the compass orientation for externally mounted compasses. The value is saved as a COMPASS_ORIENTx parameter.

The OFFSETS (COMPASS_OFFSx) and and MOT (COMPASS_MOT) parameters are populated by the live calibration and CompasMot procedures (see the calibration sections below).

Live calibration of offsets


This method is no longer recommended for recent versions of ArduPilot that support Onboard Calibration. See the basic calibration page here.

Live calibration calculates offsets to compensate for “hard iron” distortions.

  1. Click the Live Calibration button.

    A window should pop-up showing you the state of the live calibration. This shows a sphere for each compass with a red dot showing where the compass is pointing and six “white dot” targets around the sphere. You rotate the vehicle so that the red dot reaches each white dot and causes it to disappear.


    Mission Planner: Live Compass Calibration

    As you rotate the vehicle you will notice the red dot moves and (perhaps confusingly) the sphere itself also rotates. A colored trail is left behind wherever the compass has already been: high values (> 400) will turn yellow and may indicate magnetic interference. Offsets > 600 will turn red and generate a warning.

  2. Hold the vehicle in the air and rotate it slowly so that each side (front, back, left, right, top and bottom) points down towards the earth for a few seconds in turn.


    Compass Calibration Positions (shown for Copter, but true for all vehicles)

  3. The calibration will automatically complete when it has data for all the positions. At this point, another window will pop up telling you that it is saving the newly calculated offsets. These are displayed on the main screen below each associated compass.


    In Copter-3.2.1 and later offsets are considered acceptable

    provided their combined “length” is less than 600 (i.e. sqrt(offset_x^2+offset_y^2+offset_Z^2) < 600). Prior to Copter 3.2.1 the recommendation was that the absolute value of each offset be less than 150 (i.e. -150 < offset < 150).

The video below is from earlier versions of the calibration routine but may still produce good offsets.

Manual declination

By default the declination is looked up in a compressed table when the vehicle first achieves GPS lock. This method is accurate to within 1 degree (which should be sufficient) but if you wish to use the uncompressed declination:

  • Open the Declination Website.

  • It should automatically figure out your location based on you IP address or you can enter your location

  • Uncheck the Obtain declination automatically checkbox and manually enter the declination (highlighted in red in the image above) into the mission planner’s declination field. In this example, we would enter “14” Degrees and “13” Minutes.

  • As soon as your cursor exits the field (i.e by pressing Tab) the value will be converted to decimal radians and saved to the COMPASS_DEC parameter.

Tuning declination in-flight

Although we do not believe this is ever necessary, you can manually tune the declination in flight using the Channel 6 tuning knob on your transmitter by following these steps:

  1. Connect your Pixhawk (or other board) to the Mission Planner

  2. Go to the Software | Copter Pids screen

  3. Set the Ch6 Opt to “Declination”, Min to “0.0” and Max to “3.0”. This will give a tunable range of -30 to +30 degrees. Set Max to “2.0” to tune from -20 to +20 degrees, etc.

  4. Check the declination is updating correctly when turning the channel 6 tuning knob to it’s maximum position, go to Config/Tuning | Standard Params screen, press the Refresh Params button and ensuring that COMPASS_DEC is 0.523 (this is 30 degrees expressed in radians)

  5. Fly your copter in Loiter mode in at least two directions and ensure that after a fast forward flight you do not see any circling (also known as “toilet bowling”).

  6. If you find it’s impossible to tune away the circling then it’s likely you will require an external compass or GPS+compass module (some of these)

Automatic Offset Calibration

In the 4.0 releases of ArduPilot, an automatic offset learning feature is available. The COMPASS_LEARN parameter determines how this feature works.

  • If set to 3, the offsets will be learned automatically during flight, be saved, and this parameter reset to 0. Position control modes (Loiter, Auto, etc.) should not be used while the offsets are being learned.


Setting COMPASS_LEARN to 1 or 2 is not recommended. These modes are deprecated and are either non-functional, or still in development.

The procedure for COMPASS_LEARN = 3 is:

  1. set COMPASS_LEARN = 3. The message “CompassLearn: Initialised” will appear on the MP’s message tab (it does not appear in red letters on the HUD).
  2. “Bad Compass” will appear but this is nothing to be worried about. We will hopefully make this disappear before the final release.
  3. Arm and drive/fly the vehicle around in whatever mode you like, do some turns “CompassLearn: have earth field” should appear on MP’s message tab and then eventually “CompassLearn: finished”.
  4. If you want you can check the COMPASS_LEARN parameter has been set back to zero (you may need to refresh parameters to see this) and the COMPASS_OFS_X/Y/Z values will have changed.
  5. This method can also be evoked using the RCxOPTION for “Compass Learn”. It will activate when the channel goes above 1800uS and automatically complete and save.

Compass error messages

  • Compass Health: The compass has not sent a signal for at least half a second.
  • Compass Variance: In the EKF solution, compass heading disagrees with the heading estimate from other inertial sensors. Clicking the EKF button on the Mission Planner HUD will show the magnitude of the error.
  • Compass Not Calibrated: The compass needs to be calibrated.
  • Compass Offsets High: One of your compass offsets exceeds 600, indicating likely magnetic interference. Check for sources of interference and try calibrating again.