Parts

QMC5883L compass (GY-271)

The QST QMC5883L reads the magnetic field on three axes over I2C at 0x0D: the chip on most GY-271 compass boards sold today.

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.