HMC5883L Electronic Compass Module: A Complete Guide to Principles, Advantages, and I2C Communication

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

// Define OLED screen parameters (128x64 resolution)
#define SCREEN_WIDTH 128
#define SCREEN_HEIGHT 64
Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, -1);

// Initialize HMC5883L compass
Adafruit_HMC5883_Unified mag = Adafruit_HMC5883_Unified(12345);

void setup() {
  Serial.begin(9600);
  
  // Initialize OLED screen
  if(!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) {  // Address may be 0x3D, adjust according to actual module
    Serial.println(F("OLED initialization failed! Check wiring or address."));
    for(;;); // Infinite loop on initialization failure
  }
  display.clearDisplay();
  display.setTextColor(SSD1306_WHITE);  // Set white text (OLED is monochrome)

  // Initialize compass
  if(!mag.begin()) {
    Serial.println(F("HMC5883L initialization failed! Check wiring."));
    for(;;); // Infinite loop on initialization failure
  }
}

void loop() {
  sensors_event_t event;
  mag.getEvent(&event);  // Get magnetic field data

  // Calculate heading angle (in degrees), atan2(y, x) gives radians, converted to degrees
  float heading = atan2(event.magnetic.y, event.magnetic.x) * 180 / M_PI;
  
  // Correct angle range to 0-360 degrees (atan2 may return -180~180)
  if(heading < 0) {
    heading += 360;
  }

  // Draw rotating compass (pass current heading angle)
  drawCompass(heading);
  
  delay(100);  // Control refresh rate to avoid screen flickering
}

// Compass drawing function (parameter: current heading angle in degrees)
void drawCompass(float heading) {
  display.clearDisplay();  // Clear screen buffer
  
  // Screen center coordinates
  int centerX = SCREEN_WIDTH / 2;
  int centerY = SCREEN_HEIGHT / 2;
  // Compass radius (adjust according to screen size, leaving border space)
  int radius = min(centerX, centerY) - 2;

  // Draw compass outer circle
  display.drawCircle(centerX, centerY, radius, SSD1306_WHITE);
  // Draw inner circle (decorative)
  display.drawCircle(centerX, centerY, radius/3, SSD1306_WHITE);

  // Draw direction markers (N/S/E/W)
  drawDirection(centerX, centerY, radius, 0, "N");    // North (0 degrees)
  drawDirection(centerX, centerY, radius, 90, "E");   // East (90 degrees)
  drawDirection(centerX, centerY, radius, 180, "S");  // South (180 degrees)
  drawDirection(centerX, centerY, radius, 270, "W");  // West (270 degrees)

  // Calculate pointer angle: compass needle always points north, needle rotates oppositely when module rotates
  float pointerAngle = -heading;  // Negative sign for reverse rotation compensation
  // Calculate pointer end coordinates (from center pointing north)
  int pointerLength = radius - 5;  // Pointer length (slightly shorter than radius)
  int x2 = centerX + cos(pointerAngle * M_PI / 180) * pointerLength;
  int y2 = centerY + sin(pointerAngle * M_PI / 180) * pointerLength;
  // Draw pointer (line from center to end)
  display.drawLine(centerX, centerY, x2, y2, SSD1306_WHITE);
  // Draw pointer tip (small triangle for better visual effect)
  int x3 = centerX + cos((pointerAngle + 5) * M_PI / 180) * (pointerLength - 8);
  int y3 = centerY + sin((pointerAngle + 5) * M_PI / 180) * (pointerLength - 8);
  int x4 = centerX + cos((pointerAngle - 5) * M_PI / 180) * (pointerLength - 8);
  int y4 = centerY + sin((pointerAngle - 5) * M_PI / 180) * (pointerLength - 8);
  display.fillTriangle(x2, y2, x3, y3, x4, y4, SSD1306_WHITE);

  // Display current angle value (centered at screen bottom)
  display.setCursor(centerX - 20, SCREEN_HEIGHT - 10);  // Adjust text position
  display.setTextSize(1);  // Text size (1 is default)
  display.print(heading, 0);  // Display integer angle
  display.print("°");

  display.display();  // Show buffer content on screen
}

// Helper function: draw direction markers and text
void drawDirection(int cx, int cy, int r, float angle, const char* text) {
  float rad = angle * M_PI / 180;  // Convert degrees to radians
  // Marker line end coordinates (outer circle)
  int x = cx + cos(rad) * r;
  int y = cy + sin(rad) * r;
  // Marker line start coordinates (indented 5 pixels inward)
  int x1 = cx + cos(rad) * (r - 5);
  int y1 = cy + sin(rad) * (r - 5);
  // Draw marker line
  display.drawLine(x1, y1, x, y, SSD1306_WHITE);
  // Draw direction text (position slightly inward to avoid going off-screen)
  int textX = cx + cos(rad) * (r - 8) - 4;  // -4 is for text centering offset
  int textY = cy + sin(rad) * (r - 8) - 4;
  display.setCursor(textX, textY);
  display.setTextSize(1);
  display.print(text);
}