Built-in project · Arduino Uno R3

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.

HMC5883L compass heading · Arduino Uno R3live0.000 s 0.00x
Click to open it in the editor
The circuit itself, running here on the simulator. Press what can be pressed; click anything else to open it in the editor.

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 pinConnects to
Compass, HMC5883L (GY-271) pin VCCArduino Uno R3 pin 5V
Compass, HMC5883L (GY-271) pin GNDArduino Uno R3 pin GND
Compass, HMC5883L (GY-271) pin SDAArduino Uno R3 pin A4
Compass, HMC5883L (GY-271) pin SCLArduino 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.

sketch.ino · Arduino Uno R3
// 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.