HMC5883L compass heading on an Arduino Uno
An HMC5883L on a GY-271 board reads the Earth’s field, and the serial monitor prints the heading and its point of the compass twice a second. The whole build, an Arduino Uno and 1 more part, runs here in your browser on the firmware below; open it in the editor to change the wiring or the code and run it again.
Teaching? Assign it to your class in one click.
Beginner About 10 minutes to build and run. Runs in your browser. Free, and no account needed.
The parts retail for about $31. On Mokxi they're free.
What you'll learn
- Sensors
- School
- Using the Compass
- Difficulty: Beginner
- Time: About 10 minutes
- Board: Arduino Uno R3
- Parts: 2
How it works
An HMC5883L on a GY-271 board reads the Earth’s field, and the serial monitor prints the heading and its point of the compass twice a second.
Arduino Uno R3 runs the sketch below. The circuit around it: Compass, HMC5883L (GY-271). delay waits 500 milliseconds. Serial.begin opens the serial port at 9600 baud.
Parts list
2 parts, plus the jumper wires. They retail for about $31; on Mokxi they're free.
Wiring table
Every connection, pin by pin, read from the circuit itself. Each row joins the pin on the left to the pin on the right, by a jumper wire or a breadboard strip.
| Part and pin | Connects to |
|---|---|
| Compass, HMC5883L (GY-271) pin VCC | Arduino Uno R3 pin 5V |
| Compass, HMC5883L (GY-271) pin GND | Arduino Uno R3 pin GND |
| Compass, HMC5883L (GY-271) pin SDA | Arduino Uno R3 pin A4 |
| Compass, HMC5883L (GY-271) pin SCL | Arduino Uno R3 pin A5 |
The code
The firmware exactly as the editor opens it. Change a line there and press Run: it compiles in the browser.
// A compass heading from an HMC5883L on a GY-271 board.
//
// The HMC5883L measures the magnetic field along three axes. Lying flat,
// the Earth's field points north along X and Y, so atan2(Y, X) is the angle
// between the board's X arrow and magnetic north: the heading.
//
// GY-271 SDA, SCL -> SDA, SCL (A4, A5) VCC -> 5V, GND -> GND
//
// Twice a second the sketch prints the field in micro-Tesla and the heading
// with its point of the compass. Drag the heading slider while it runs; the
// pitch and roll sliders tip the board, and the heading goes wrong, because
// a flat compass needs to lie flat.
//
// THINGS TO TRY. Set the gain to HMC5883_MAGGAIN_8_1: the counts get coarser
// but the heading stays put. Then add your local declination (the angle
// between magnetic and true north) to the heading for true north.
#include <Wire.h>
#include <Adafruit_Sensor.h>
#include <Adafruit_HMC5883_U.h>
Adafruit_HMC5883_Unified mag = Adafruit_HMC5883_Unified(12345);
const char *const POINTS[] = {"N", "NE", "E", "SE", "S", "SW", "W", "NW"};
void setup() {
Serial.begin(9600);
if (!mag.begin()) {
Serial.println("No HMC5883L at 0x1E: check SDA and SCL.");
while (1) {}
}
Serial.println("HMC5883L compass at 0x1E");
}
void loop() {
// Continuous mode measures 15 times a second; the first sample lands
// 2/15 s after begin(), so wait before reading.
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;
int point = (int)((heading + 22.5) / 45) % 8;
Serial.print("X: ");
Serial.print(event.magnetic.x, 1);
Serial.print(" Y: ");
Serial.print(event.magnetic.y, 1);
Serial.print(" Z: ");
Serial.print(event.magnetic.z, 1);
Serial.print(" uT heading ");
Serial.print(heading, 0);
Serial.print(" degrees ");
Serial.println(POINTS[point]);
}
Code walkthrough
The key functions of the sketch, and what each one does.
setup sketch.ino
Runs once when the board starts. It gets the pins and libraries ready.
void setup() {
Serial.begin(9600);
if (!mag.begin()) {
Serial.println("No HMC5883L at 0x1E: check SDA and SCL.");
while (1) {}
}
Serial.println("HMC5883L compass at 0x1E");
}loop sketch.ino
Runs over and over for as long as the board has power. This is where the project does its work.
void loop() {
// Continuous mode measures 15 times a second; the first sample lands
// 2/15 s after begin(), so wait before reading.
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;
int point = (int)((heading + 22.5) / 45) % 8;
Serial.print("X: ");
Serial.print(event.magnetic.x, 1);
Serial.print(" Y: ");
Serial.print(event.magnetic.y, 1);
Serial.print(" Z: ");
Serial.print(event.magnetic.z, 1);
Serial.print(" uT heading ");
Serial.print(heading, 0);
Serial.print(" degrees ");
Serial.println(POINTS[point]);
}Troubleshooting
The usual mistakes with this circuit, and the fix for each.
- Upload fails or nothing runs after wiring pins 0 and 1 to a module. Arduino Uno R3
Pins 0 and 1 are the USB serial port. Move the module to other pins, or unplug it while uploading. Also check the right board is selected. - Pins misbehave or the board resets when you power motors or servos from it. Arduino Uno R3
Each I/O pin gives about 20 mA, 40 mA max. Power motors and servos from their own supply and join its ground to the Uno's GND.
Change it and keep it
Open it in the editor, change the circuit or the code, and keep your version in a free account.