# esp32c3mini-qmc5883p-compass-heading

> 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.

- Author: Mikrobot.pl
- Platform: ESP32
- Board: ESP32C3 Dev Module (`esp32:esp32:esp32c3`)
- SDK version: 3.3.6
- Tags: #esp32c3, #example, #compass, #magnetometer, #logs, #supermini
- Created: 2026-10-15
- Updated: 2026-10-15
- Favorites: 1, forks: 2
- Project page (view, flash from the browser, fork): https://flashesp.com/explore/NzdB8NC5BFLTOs18nGmak
- Download all sources (zip): https://flashesp.com/api/public-projects/NzdB8NC5BFLTOs18nGmak/download-sources/

## Source files

- [main.ino (7.2 KB)](https://flashesp.com/explore/NzdB8NC5BFLTOs18nGmak/files/BZ6J8QP7yXtRJ79m1pJSK.md)
- readme.md (3.8 KB)

## README

# ESP32-C3 SuperMini + QMC5883P Compass (I2C)

<p align="center">
  <img src="https://i.imgur.com/kcf5y2a.jpeg" width="500">
</p>

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:

```cpp
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:

```cpp
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:

```cpp
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.
