Documentation

// HMC5883L (GY-273) Compass - Arduino Example
// SDA -> A4, SCL -> A5, VCC -> 5V, GND -> GND
// Library: "Adafruit HMC5883 Unified" (+ Adafruit Unified Sensor)

#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);

  if (!mag.begin()) {
    Serial.println("HMC5883L not found at 0x1E - check wiring.");
    Serial.println("(If an I2C scan shows 0x0D, you have a QMC5883L.)");
    while (1);
  }
  Serial.println("Compass ready - rotate the board slowly.");
}

void loop() {
  sensors_event_t event;
  mag.getEvent(&event);

  // Heading from the horizontal components (board held flat)
  float heading = atan2(event.magnetic.y, event.magnetic.x);

  // Add your local magnetic declination here (radians)
  // Example: +3 degrees = 0.052 rad
  // heading += 0.052;

  if (heading < 0) heading += 2 * PI;
  float degrees = heading * 180 / PI;

  Serial.print("X: ");
  Serial.print(event.magnetic.x);
  Serial.print(" uT  Y: ");
  Serial.print(event.magnetic.y);
  Serial.print(" uT  |  Heading: ");
  Serial.print(degrees, 1);
  Serial.println(" deg");

  delay(500);
}

// HMC5883L (GY-273) Compass - ESP32 Example
// SDA -> GPIO 21, SCL -> GPIO 22, VCC -> 3V3, GND -> GND
// Library: "Adafruit HMC5883 Unified" (+ Adafruit Unified Sensor)

#include <Wire.h>
#include <Adafruit_Sensor.h>
#include <Adafruit_HMC5883_U.h>

Adafruit_HMC5883_Unified mag = Adafruit_HMC5883_Unified(12345);

void setup() {
  Serial.begin(115200);
  Wire.begin(21, 22);   // SDA, SCL

  if (!mag.begin()) {
    Serial.println("HMC5883L not found at 0x1E - check wiring.");
    while (1) delay(10);
  }
  Serial.println("Compass ready - rotate the board slowly.");
}

void loop() {
  sensors_event_t event;
  mag.getEvent(&event);

  float heading = atan2(event.magnetic.y, event.magnetic.x);
  if (heading < 0) heading += 2 * PI;

  Serial.printf("X: %.1f uT  Y: %.1f uT  |  Heading: %.1f deg\n",
                event.magnetic.x, event.magnetic.y,
                heading * 180 / PI);
  delay(500);
}

#!/usr/bin/env python3
# HMC5883L (GY-273) Compass - Raspberry Pi Example
# SDA -> GPIO 2 (pin 3), SCL -> GPIO 3 (pin 5), VCC -> 3.3V (pin 1)
# Setup: enable I2C in raspi-config, then: pip3 install smbus2

import math
import time
from smbus2 import SMBus

ADDR = 0x1E   # HMC5883L (0x0D would be a QMC5883L - different chip!)

bus = SMBus(1)

# Config A: 8 samples averaged, 15 Hz output  -> 0x70
bus.write_byte_data(ADDR, 0x00, 0x70)
# Config B: gain +/-1.3 gauss (default)       -> 0x20
bus.write_byte_data(ADDR, 0x01, 0x20)
# Mode: continuous measurement                -> 0x00
bus.write_byte_data(ADDR, 0x02, 0x00)
time.sleep(0.1)

def read_axes():
    # Data registers start at 0x03, order is X, Z, Y (big endian)
    data = bus.read_i2c_block_data(ADDR, 0x03, 6)
    def s16(hi, lo):
        v = (hi << 8) | lo
        return v - 65536 if v > 32767 else v
    x = s16(data[0], data[1])
    z = s16(data[2], data[3])
    y = s16(data[4], data[5])
    return x, y, z

print("Compass ready - rotate the board slowly (Ctrl+C to stop)")

try:
    while True:
        x, y, z = read_axes()

        heading = math.atan2(y, x)
        # Add your local magnetic declination here (radians)
        if heading < 0:
            heading += 2 * math.pi

        print("X: {:6d}  Y: {:6d}  Z: {:6d}  |  Heading: {:5.1f} deg".format(
            x, y, z, math.degrees(heading)))
        time.sleep(0.5)

except KeyboardInterrupt:
    print("Stopped by user")
finally:
    bus.close()

# HMC5883L (GY-273) Compass - Pico MicroPython Example
# SDA -> GP0, SCL -> GP1 (I2C0), VCC -> 3V3(OUT), GND -> GND
# No library needed - reads the registers directly.

from machine import Pin, I2C
import math
import time

ADDR = 0x1E   # HMC5883L (0x0D would be a QMC5883L - different chip!)

i2c = I2C(0, sda=Pin(0), scl=Pin(1), freq=400000)

if ADDR not in i2c.scan():
    raise RuntimeError("HMC5883L not found at 0x1E - check wiring "
                       "(0x0D in the scan means QMC5883L)")

# Config A: 8 samples averaged, 15 Hz  |  Config B: +/-1.3 Ga  |  Mode: continuous
i2c.writeto_mem(ADDR, 0x00, b'\x70')
i2c.writeto_mem(ADDR, 0x01, b'\x20')
i2c.writeto_mem(ADDR, 0x02, b'\x00')
time.sleep_ms(100)

def s16(hi, lo):
    v = (hi << 8) | lo
    return v - 65536 if v > 32767 else v

print("Compass ready - rotate the board slowly")

while True:
    # Data registers start at 0x03, order is X, Z, Y (big endian)
    d = i2c.readfrom_mem(ADDR, 0x03, 6)
    x = s16(d[0], d[1])
    z = s16(d[2], d[3])
    y = s16(d[4], d[5])

    heading = math.atan2(y, x)
    if heading < 0:
        heading += 2 * math.pi

    print("X:", x, " Y:", y, " Z:", z,
          " |  Heading: {:.1f} deg".format(math.degrees(heading)))
    time.sleep(0.5)