GY-271 Compass (QMC5883L) with an ESP32 DevKit V1
A 3-axis magnetometer compass module on QST's QMC5883L, ±8 gauss range and 1° to 2° heading accuracy over I2C.
On the ESP32 DevKit V1 the GY-271 runs from 3V3 with SDA on GPIO21 and SCL on GPIO22, which compass.init() picks up because it calls Wire.begin() itself. Its QMC5883L chip is a 2.16 V to 3.6 V part, and with VCC on 3V3 its 2.2 kOhm pull-ups hold the bus at the ESP32's own 3.3 V.
Wiring the GY-271 Compass (QMC5883L) to the ESP32 DevKit V1
Pin by pin.
| GY-271 Compass (QMC5883L) | ESP32 DevKit V1 |
|---|---|
| VCC | 3V3 |
| GND | GND |
| SDA | GPIO21 (D21) |
| SCL | GPIO22 (D22) |
What to know on the ESP32 DevKit V1
- Keep VCC on 3V3, not VIN: the module's pull-ups go to VCC, so 5 V on VCC would put 5 V on GPIO21 and GPIO22, above the ESP32's VDD + 0.3 V input limit.Espressif ESP32 Series Datasheet v5.3, p. 52
- To use other pins, call Wire.begin(sda, scl) before compass.init(); the ESP32 routes I2C to any GPIO through its GPIO matrix, but the input-only GPIO34 to GPIO39 cannot drive SCL or SDA.Espressif ESP32 Series Datasheet v5.3, p. 37; Espressif ESP32 Series Datasheet v5.3, p. 61
- Mount the compass away from the DevKit's USB cable, any motor and the servo wires: a heading of 1° to 2° accuracy is easily lost to a nearby current or magnet.QST QMC5883L datasheet Rev A, p. 2
GY-271 Compass (QMC5883L) code for the ESP32 DevKit V1
Compiled for esp32:esp32:esp32 on 2026-10-30.
// GY-271 Compass (QMC5883L) on ESP32 DevKit V1: wiring and a free simulation at https://www.tinkered.ai/components/gy-271/esp32
// lib_deps = mprograms/QMC5883LCompass
#include <QMC5883LCompass.h>
QMC5883LCompass compass;
const char* const POINTS[16] = {"N", "NNE", "NE", "ENE", "E", "ESE", "SE", "SSE", "S", "SSW", "SW", "WSW", "W", "WNW", "NW", "NNW"};
void setup() {
Serial.begin(9600);
compass.init(); // Wire.begin(), then continuous 200 Hz, ±8 G
Serial.println("Compass ready");
}
void loop() {
compass.read();
int x = compass.getX();
int y = compass.getY();
int z = compass.getZ();
int heading = compass.getAzimuth(); // -180..179
if (heading < 0) heading += 360; // 0..359, clockwise from magnetic north
// the 16-point name: 22.5° each, N centred on 0
const char* point = POINTS[(int)((heading + 11.25) / 22.5) % 16];
Serial.print("heading ");
Serial.print(heading);
Serial.print(" ");
Serial.print(point);
Serial.print(" x ");
Serial.print(x);
Serial.print(" y ");
Serial.print(y);
Serial.print(" z ");
Serial.println(z);
delay(250);
}
GY-271 Compass (QMC5883L) on the ESP32 DevKit V1: questions
Why does my HMC5883L library find nothing on the ESP32?
The GY-271 sold today carries a QMC5883L at address 0x0D (QST datasheet, p. 13), not an HMC5883L at 0x1E. Use the QMC5883LCompass library, as the page does.
Is the heading true north on the ESP32?
No, magnetic north. Add your location's declination with setMagneticDeclination(), and keep the board level.
Keep going
This guide as plain Markdown. /components/gy-271/esp32.md