esp32c3mini-qmc5883p-compass-heading
Project Information
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.
Source Files (2)
Download AllREADME
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.honly (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.