readme.md
Markdown · 106 lines
# 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.