Parts

HMC5883L compass (GY-271)

The Honeywell HMC5883L reads the magnetic field on three axes over I2C at 0x1E: the classic GY-271 digital compass board.

This part has a page of its own, with a note on using it and a circuit to try: the part page.

Aliases: HMC5883L, HMC5883, GY-271, GY-273, digital compass, three-axis magnetometer, Adafruit HMC5883 Unified. 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, Y over X, is the heading. Most GY-271 boards sold today carry a QMC5883L at 0x0D instead, with a different register map: if 0x1E is silent on your real board, look at the chip.

Pins

Pin What it does
VCC, GND Supply, 3 to 5 V; the board's regulator gives the chip 3.3 V.
SCL, SDA I2C at 0x1E (0x3C to write, 0x3D to read). The board carries 4.7 k pull-ups.
DRDY Goes low for 250 microseconds each time new data goes in. Optional.

Properties

heading, pitch and roll are how the board sits; the sliders turn and tip it. The probe follows the heading.

Reading it on an Arduino

With Adafruit's library, which Mokxi ships as Adafruit_HMC5883_U.h:

#include <Wire.h>
#include <Adafruit_Sensor.h>
#include <Adafruit_HMC5883_U.h>
Adafruit_HMC5883_Unified mag = Adafruit_HMC5883_Unified(12345);

void setup() {
  Serial.begin(9600);
  mag.begin();
}

void loop() {
  delay(500);
  sensors_event_t event;
  mag.getEvent(&event);
  float heading = atan2(event.magnetic.y, event.magnetic.x) * 180 / PI;
  if (heading < 0) heading += 360;
  Serial.println(heading);
}

begin() puts the chip in continuous mode at 15 Hz and the 1.3 gauss gain. The library turns counts into microtesla with its own 1100 and 980 counts a gauss rather than the datasheet's 1090, so X and Y read about 1% low and Z about 11% high, just as on a real board; the heading is not affected. The i2cdevlib HMC5883L.h class works too.

How it talks

Configuration A (0x00) sets the samples averaged, the output rate (0.75 to 75 Hz, 15 by default) and the self-test bias. Configuration B (0x01) sets the gain: 1370, 1090, 820, 660, 440, 390, 330 or 230 counts a gauss. The mode register (0x02) picks continuous, single or idle. The field is at 0x03 to 0x08, high byte first, in the order X, Z, Y, from -2048 to 2047, or -4096 when an axis overflows. The status register (0x09) has RDY and LOCK, and 0x0A to 0x0C read H43. The register pointer steps on after each byte and goes from 0x08 back to 0x03, so the data can be read again and again.

At power-on it makes one measurement and goes idle. In continuous mode the first sample lands two output periods after the mode is written, then one each period; a single measurement takes 6 ms. Once one data byte has been read, new data waits until all six have been read. The positive and negative bias modes are the self test: the outputs then hold only the bias field, about 452 counts on X and Y and 421 on Z at gain 5.

What it does not model

The averaging (there is no noise to average), the high-speed I2C bit, noise, offsets, hard and soft iron, nearby magnets, and the 50 ms the chip's analog side takes to wake.

Common mistakes

Reading X, Y, Z in that order from 0x03: the chip's order is X, Z, Y. Reading at once after switching to continuous mode: the first sample takes two periods, 133 ms at 15 Hz. Reading half the data and stopping: the outputs lock until the other bytes are read. Expecting a heading with the board tipped: a flat compass needs to lie flat, or tilt compensation from an accelerometer.