Compass heading is wrong: magnetometer calibration, hard iron and tilt

Rotate the sensor through every direction to calibrate it. Keep it away from motors, wires with current and steel.

What the message means

Nearby metal and magnets add a fixed offset, and current in wires adds a changing field. The heading then points the wrong way.

Fix it in this order

1. Run the calibration routine and turn the robot slowly through all orientations.
2. Store the offsets and subtract them from each reading.
3. Mount the sensor on a mast, away from motors and the battery.
4. Keep power wires twisted and away from the sensor.
5. Use tilt compensation with the accelerometer when the robot is not level.
6. Check the local magnetic declination if you need true north.

Why it happens

The compass in the MPU9250 is a separate AK8963 chip inside the package, and it measures the local magnetic field, which is the Earth’s field plus everything near the sensor. Fixed magnetic parts on the robot, such as steel screws and motor magnets, add a constant offset called hard-iron error. Soft magnetic metal bends the field and stretches the readings into an ellipse, called soft-iron error. Turning the robot through all orientations while logging the minimum and maximum of each axis lets you estimate and subtract both.

Motor and battery wires carry current, and current makes its own field, which is why the heading shifts when the motors run. Magnetic north is also not true north; the difference, called declination, depends on where you are, so look up the value for your location if you need true north.

If you see this, do this

Related

gyro drift, sensor mounting.

Last reviewed: November 2026. These are the usual causes and the order that finds them fastest. Test on your own board; clones and cables differ.