Back to Explorer

esp32c3mini-qmc5883p-compass-heading

Project Information

Author

Mikrobot.pl

Board

ESP32C3 Dev Module

SDK Version

3.3.6

Platform

ESP32

Created

Updated

Description

Read magnetometer data from a QMC5883P over I2C on an ESP32 C3 Super Mini, convert raw readings to µT, and print a tilt-uncompensated heading (0–360°) to the Serial Monitor. Includes optional magnetic declination correction.

Flash to Device

Login required: You need to login or create an account to flash this project.

Sorry, your browser doesn't support Web Serial.Web Serial requires HTTPS.

README

ESP32-C3 SuperMini + QMC5883P Compass (I2C)

This project reads a QMC5883P magnetometer via I2C on an ESP32-C3 SuperMini, converts the raw sensor values into microtesla (µT), calculates a compass heading (0–360°), and prints everything to the Serial Monitor.

Hardware

  • ESP32-C3 SuperMini development board
  • QMC5883P magnetometer module (I2C)

Important: the QMC5883P is not interchangeable with the far more common QMC5883L or HMC5883L modules. All three use different I2C addresses and register maps. Run an I2C scanner first — this sketch only works with a device answering at 0x2C.

Chip I2C address
HMC5883L (Honeywell, discontinued) 0x1E
QMC5883L (QST) 0x0D
QMC5883P (QST) 0x2C

Wiring (ESP32-C3 SuperMini ↔ QMC5883P)

Use the I2C pins defined in the sketch:

  • SDA → GPIO8
  • SCL → GPIO9
  • VCC → 3V3
  • GND → GND
  • DRDY → not connected (optional data-ready interrupt, unused here)

Power the module from 3V3, not 5V. The ESP32-C3 is a 3.3V part and the module's I2C pull-ups are referenced to its own regulator output.

SuperMini pin notes

Two pins on this board have a secondary function worth knowing about:

  • GPIO8 also drives the onboard blue LED. It will flicker during I2C traffic — this is normal and does not affect communication.
  • GPIO9 is wired to the BOOT button. Do not press it while the sketch is running; it pulls SCL low and breaks the transfer.

If you see unstable readings or intermittent read errors, move the bus to two unused pins — the ESP32-C3 GPIO matrix allows any pair:

constexpr int I2C_SDA = 5;
constexpr int I2C_SCL = 6;

Software

Arduino IDE setup

  • Board: ESP32C3 Dev Module
  • USB CDC On Boot: Enabled — required. The C3 uses native USB instead of a UART bridge; with this disabled the Serial Monitor stays blank no matter what the sketch prints.
  • Serial speed: 115200
  • Libraries: uses built-in Wire.h only (no extra library required)

Upload troubleshooting

If the board does not appear as a serial port, enter download mode manually: hold BOOT, tap RESET, release BOOT.

Configuration

I2C address

The sketch uses the QMC5883P default address:

  • 0x2C

Measurement range

The sketch configures the sensor for ±8 Gauss and scales accordingly:

constexpr float UT_PER_LSB = 100.0f / 3750.0f;  // 3750 LSB/G, 1 G = 100 µT

The QMC5883P also supports ±2 G, ±12 G and ±30 G. If you change the range in CONFIG_REG, update UT_PER_LSB to match the new sensitivity or the µT values will be wrong.

Magnetic declination

Set DECLINATION_DEG to your local magnetic declination (in degrees) to get a true-north heading:

constexpr float DECLINATION_DEG = 6.5f;  // approx. for south-eastern Poland

Leave it at 0.0f for a magnetic-north heading. Declination varies by location and drifts slowly over time — look up the current value for your coordinates.

Output

The Serial Monitor prints:

  • X/Y/Z magnetic field in µT
  • Heading in degrees

Example:

X:12.34  Y:-5.67  Z:44.12 uT  |  Heading: 123°

Notes / Limitations

  • Heading is calculated from X/Y only (no tilt compensation). If the sensor is not held level, the heading will be inaccurate — tilt of a few degrees already shifts the result noticeably.
  • Calibration is mandatory for usable results. Hard-iron and soft-iron distortion from nearby steel, motors, battery packs and current-carrying wires can introduce errors of tens of degrees. Calibrate with the module mounted in its final position, not on the bench.
  • Keep the module as far as practical from motors, speakers, magnets and high-current traces.