Aliases: GY-271, QMC5883, digital compass module, three-axis magnetometer.
Flat on the bench it reads the Earth's field: about 20 microtesla toward magnetic north
and 45 down, at mid-northern latitudes. atan2 of the two horizontal readings is the
heading, which is all a compass sketch does.
Which chip is on my GY-271?
Boards sold as "GY-271" or "HMC5883L" carried Honeywell's HMC5883L until it was
discontinued; most now carry the QMC5883L, which has a different address and register
map. Run an I2C scanner: 0x0D is a QMC5883L, 0x1E an HMC5883L. A sketch written for
the other chip finds nothing.
Pins
| Pin | What it does |
|---|---|
VCC, GND |
Supply, 3 to 5 V on the board, which has its own 3.3 V regulator. |
SCL, SDA |
I2C, up to 400 kHz. The board carries the pull-ups. |
DRDY |
High while a new sample waits; reading the data takes it low. |
Properties
heading, pitch and roll are how the board sits; the sliders turn and tip it.
Reading it on an Arduino
With the QMC5883LCompass library (MPrograms), which Mokxi ships as QMC5883LCompass.h:
#include <QMC5883LCompass.h>
QMC5883LCompass compass;
void setup() {
Serial.begin(9600);
compass.init();
}
void loop() {
compass.read();
int azimuth = compass.getAzimuth();
char dir[3];
compass.getDirection(dir, azimuth);
Serial.print(azimuth);
Serial.print(" ");
Serial.print(dir[0]);
Serial.print(dir[1]);
Serial.println(dir[2]);
delay(250);
}
getAzimuth() is -180 to 180 degrees, 0 when the board's X arrow points north.
getDirection() fills three characters, " N", "NNE" and so on, with no terminator.
How it talks
Control register 1 (0x09) sets the mode (standby or continuous), the data rate (10,
50, 100 or 200 Hz), the range (2 gauss at 12000 counts a gauss, or 8 at 3000) and the
oversampling. The datasheet's setup is 0x01 into the SET/RESET period register
(0x0B), then 0x1D into 0x09. The status register (0x06) has DRDY (new data),
OVL (an axis past -32768 or 32767) and DOR (a sample was skipped). The field is at
0x00 to 0x05, low byte first; the register address steps on by itself, so one read
of six bytes from 0x00 gets all three axes. Control register 2 (0x0A) has the soft
reset, the pointer roll-over and the switch that turns the DRDY pin off. The chip ID
(0x0D) reads 0xFF.
What it does not model
Noise, offsets, the oversampling filter and the SET/RESET period's effect (both are
stored and read back), nearby magnets and the hard iron of a robot chassis. The
temperature registers' offset is not calibrated on the real chip, only their 100 counts a
degree, so the model reads 0 and holds still.
Common mistakes
Reading zeros: the chip powers up in standby until continuous mode is written to 0x09.
A heading that jumps or sits still: reading only some of the six data registers locks
them until 0x05 is read. The heading is off by tens of degrees: magnetic north is not
true north, so set the declination for your town, and calibrate away the board's own
offsets.