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.