Bauteile · 10 Min. Lesezeit

Kompassmodul Arduino: QMC5883L und HMC5883L (GY-271) nutzen

GY-271 Kompassmodul: QMC5883L oder HMC5883L? I2C-Adressen (0x0D, 0x1E), Kurs berechnen, Deklination, Kalibrierung und OLED-Kompass mit Uno, ESP32 und Pico.

Ein Arduino-Kompassmodul ist ein kleiner Magnetfeldsensor, der deinem Board sagt, wo Norden ist. Das verbreitetste Modell, das GY-271, misst das Erdmagnetfeld in drei Achsen. Daraus berechnest du den Kurs (0–360 Grad), steuerst dein Roboterauto in eine bestimmte Richtung, zeigst einen digitalen Kompass auf dem OLED an oder ergänzt dein GPS-Projekt um eine Richtungsangabe. Das Modul wird mit nur vier Drähten per I2C angeschlossen und funktioniert mit Arduino Uno, ESP32 und Raspberry Pi Pico nach demselben Prinzip.

Das Modul hat aber eine Überraschung: Auf den meisten Platinen, die als GY-271 verkauft werden, sitzt heute nicht mehr der HMC5883L von Honeywell, sondern der QMC5883L von QST. Äußerlich sehen sich beide Chips fast gleich, doch I2C-Adresse und Registeraufbau unterscheiden sich, weshalb viele fertige Sketches mit "Sensor nicht gefunden" abbrechen. In diesem Beitrag lernst du zuerst, welcher Chip auf deiner Platine sitzt, dann den Kurs richtig zu berechnen, die magnetische Deklination zu addieren und den Fehler per Kalibrierung auf wenige Grad zu drücken.

Was ist ein digitales Kompassmodul und wie funktioniert es?

Im Herzen des Moduls arbeitet ein Magnetometer, also ein Magnetfeldsensor. Das Erdmagnetfeld ist recht schwach: In Mitteleuropa beträgt die Gesamtstärke etwa 45–50 Mikrotesla (0,45–0,5 Gauß), die horizontale Komponente liegt bei rund 20 µT (1 Gauß = 100 µT). Der Chip misst mit magnetoresistiven Sensoren die Komponenten in X-, Y- und Z-Richtung und liefert jede als vorzeichenbehaftete Ganzzahl. Liegt das Modul waagerecht, genügen X und Y für den Kurs; aus beiden Werten ermittelst du den Winkel mit der Funktion atan2. Die Z-Achse ist für fortgeschrittene Anwendungen wie Neigungskompensation und Metallerkennung nützlich.

EigenschaftQMC5883LHMC5883L
HerstellerQSTHoneywell (Produktion eingestellt)
I2C-Adresse0x0D0x1E
Messbereich±2 G oder ±8 G±0,88 G bis ±8,1 G (8 Stufen)
Auflösung16 Bit (12000 LSB/G bei ±2 G, 3000 LSB/G bei ±8 G)12 Bit (1090 LSB/G bei ±1,3 G)
Datenrate10, 50, 100, 200 Hz0,75–75 Hz (im Dauermessmodus)
Versorgung des Chips2,16–3,6 V2,16–3,6 V
Versorgung der GY-271-Platine3–5 V (Regler auf der Platine)3–5 V (Regler auf der Platine)
TemperaturmessungJa (relativer Wert)Nein

QMC5883L oder HMC5883L? So unterscheidest du die Chips

Der HMC5883L war viele Jahre der Standard-Kompasschip der Hobbyelektronik. Nachdem Honeywell die Produktion eingestellt hatte, übernahm der QMC5883L von QST den Markt. Weil Händler den Produktnamen meist nicht ändern, ist es völlig normal, dass auf einer als "HMC5883L" gekauften Platine ein QMC5883L sitzt. Am sichersten unterscheidest du die Chips mit einem I2C-Scan: Erscheint auf dem Bus die Adresse 0x0D, ist es ein QMC5883L, bei 0x1E ein HMC5883L. Auch die Beschriftung auf dem Chip hilft, wenn du sie mit einer Lupe liest. In letzter Zeit tauchen auf manchen Platinen auch QMC5883P mit der Adresse 0x2C auf; ihre Registerbelegung ist anders, daher funktionieren die Sketches in diesem Beitrag damit nicht direkt.

MethodeQMC5883LHMC5883L
I2C-Adresse0x0D0x1E
Aufdruck auf dem ChipDA 5883L883
KennungsregisterRegister 0x0D liefert 0xFFRegister 0x0A–0x0C liefern 'H', '4', '3'
Datenregister0x00–0x05 (der Reihe nach X, Y, Z)0x03–0x08 (der Reihe nach X, Z, Y)
Byte-ReihenfolgeZuerst das niederwertige Byte (LSB)Zuerst das höherwertige Byte (MSB)
Zustand nach dem EinschaltenStandby, misst nichtEinzelmessmodus
Verbreitete BibliothekQMC5883LCompassAdafruit HMC5883 Unified
HMC-Bibliotheken wie Adafruit HMC5883 Unified suchen nur die Adresse 0x1E. Sitzt auf deiner Platine ein QMC5883L, bekommst du eine Meldung wie "no HMC5883 detected" und hältst das Modul für defekt. Das Modul ist nicht kaputt, der Chip ist nur ein anderer. Mach zuerst einen I2C-Scan und nutze dann Code, der mit der richtigen Adresse arbeitet.

GY-271 anschließen: Uno, ESP32 und Pico

GY-271-PinArduino UnoESP32Raspberry Pi Pico
VCC5V (oder 3.3V)3V33V3 (Pin 36)
GNDGNDGNDGND
SCLA5GPIO 22GP5 (Pin 7)
SDAA4GPIO 21GP4 (Pin 6)
DRDYNicht anschließenNicht anschließenNicht anschließen

Auf der GY-271-Platine sitzen ein 3,3-V-Regler und Pull-up-Widerstände für die I2C-Leitungen; deshalb kannst du das Modul am Uno gefahrlos am 5V-Pin betreiben. Beim ESP32 und Pico versorgst du die Platine über den 3V3-Pin, damit SDA und SCL auf 3,3 V bleiben. Der DRDY-Pin (Data Ready) meldet jede neue Messung; wenn du nicht per Interrupt lesen willst, lässt du ihn frei. Der Kompass kann sich den Bus mit anderen I2C-Geräten wie einem OLED (0x3C) oder einem MPU-6050 (0x68) teilen, da die Adressen nicht kollidieren. Details zu Adressen und Pull-ups findest du im Beitrag Was ist I2C.

Schritt für Schritt: die erste Kursmessung (Arduino Uno)

  1. Stecke das Modul auf das Breadboard und halte es möglichst mindestens 15–20 cm von Motoren, Lautsprechern, Magneten und größeren Stahlteilen entfernt.
  2. Verbinde VCC, GND, SCL und SDA wie in der Tabelle und lass den DRDY-Pin frei.
  3. Lade den folgenden Sketch hoch; du brauchst keine zusätzliche Bibliothek, nur die in Arduino enthaltene Wire-Bibliothek.
  4. Öffne den Seriellen Monitor mit 9600 Baud; in der ersten Zeile siehst du, welchen Chip der Code gefunden hat.
  5. Lege das Modul flach auf den Tisch und drehe es langsam um die eigene Achse; beobachte, wie X und Y zwischen positiven und negativen Werten wechseln und der Winkel von 0 auf 360 wächst.
  6. Ist dein Handykompass auf den echten Norden eingestellt, richte den X-Pfeil auf dem Modul danach aus; der Winkel sollte gegen 0 gehen. Vor der Kalibrierung sind Abweichungen von 10–30 Grad normal.
C++ (Arduino IDE)
1#include <Wire.h>
2#include <math.h>
3
4const uint8_t QMC_ADDR = 0x0D;   // QMC5883L adresi / QMC5883L address
5const uint8_t HMC_ADDR = 0x1E;   // HMC5883L adresi / HMC5883L address
6const float DECLINATION = 6.0;   // manyetik sapma, doğu + / magnetic declination, east +
7
8uint8_t chipAddr = 0;
9
10bool devicePresent(uint8_t addr) {
11  Wire.beginTransmission(addr);
12  return Wire.endTransmission() == 0;   // 0 = cihaz cevap verdi / 0 = device acknowledged
13}
14
15void writeReg(uint8_t addr, uint8_t reg, uint8_t val) {
16  Wire.beginTransmission(addr);
17  Wire.write(reg);
18  Wire.write(val);
19  Wire.endTransmission();
20}
21
22bool readAxes(int16_t &x, int16_t &y, int16_t &z) {
23  uint8_t startReg = (chipAddr == QMC_ADDR) ? 0x00 : 0x03;
24  Wire.beginTransmission(chipAddr);
25  Wire.write(startReg);
26  if (Wire.endTransmission() != 0) return false;
27  if (Wire.requestFrom(chipAddr, (uint8_t)6) != 6) return false;
28  uint8_t b[6];
29  for (uint8_t i = 0; i < 6; i++) b[i] = Wire.read();
30  if (chipAddr == QMC_ADDR) {          // X, Y, Z; önce düşük bayt / LSB first
31    x = (int16_t)((uint16_t)b[1] << 8 | b[0]);
32    y = (int16_t)((uint16_t)b[3] << 8 | b[2]);
33    z = (int16_t)((uint16_t)b[5] << 8 | b[4]);
34  } else {                             // X, Z, Y; önce yüksek bayt / MSB first
35    x = (int16_t)((uint16_t)b[0] << 8 | b[1]);
36    z = (int16_t)((uint16_t)b[2] << 8 | b[3]);
37    y = (int16_t)((uint16_t)b[4] << 8 | b[5]);
38  }
39  return true;
40}
41
42const char* directionName(float h) {
43  static const char* const names[] = {"K", "KD", "D", "GD", "G", "GB", "B", "KB"};
44  return names[(int)((h + 22.5) / 45.0) % 8];   // 45 derecelik dilimler / 45 degree sectors
45}
46
47void setup() {
48  Serial.begin(9600);
49  Wire.begin();
50  if (devicePresent(QMC_ADDR)) {
51    chipAddr = QMC_ADDR;
52    writeReg(QMC_ADDR, 0x0B, 0x01);   // SET/RESET periyodu / SET/RESET period
53    writeReg(QMC_ADDR, 0x09, 0x1D);   // sürekli, 200 Hz, ±8 G, OSR 512 / continuous, 200 Hz, ±8 G, OSR 512
54    Serial.println(F("QMC5883L bulundu (0x0D)"));
55  } else if (devicePresent(HMC_ADDR)) {
56    chipAddr = HMC_ADDR;
57    writeReg(HMC_ADDR, 0x00, 0x70);   // 8 örnek ortalama, 15 Hz / 8-sample average, 15 Hz
58    writeReg(HMC_ADDR, 0x01, 0x20);   // ±1,3 Ga kazanç / ±1.3 Ga gain
59    writeReg(HMC_ADDR, 0x02, 0x00);   // sürekli ölçüm / continuous measurement
60    Serial.println(F("HMC5883L bulundu (0x1E)"));
61  } else {
62    Serial.println(F("Pusula bulunamadi / Compass not found"));
63    while (true) {}
64  }
65}
66
67void loop() {
68  int16_t x, y, z;
69  if (readAxes(x, y, z)) {
70    float heading = atan2((float)y, (float)x) * 180.0 / PI;   // radyandan dereceye / radians to degrees
71    heading += DECLINATION;
72    if (heading < 0) heading += 360.0;
73    if (heading >= 360.0) heading -= 360.0;
74    Serial.print(F("X: ")); Serial.print(x);
75    Serial.print(F("  Y: ")); Serial.print(y);
76    Serial.print(F("  Z: ")); Serial.print(z);
77    Serial.print(F("  Yon: ")); Serial.print(heading, 1);
78    Serial.print(F(" derece "));
79    Serial.println(directionName(heading));
80  }
81  delay(250);
82}
Code / RegisterWertBedeutung
QMC 0x0B0x01SET/RESET-Periode; vom Datenblatt empfohlener Wert
QMC 0x090x1DOSR 512, ±8-G-Bereich, 200 Hz, Dauermessung (0x0D für ±2 G)
HMC 0x000x70Mittelwert aus 8 Messungen, 15 Hz Datenrate
HMC 0x010x20±1,3-Ga-Bereich, 1090 LSB/Ga Empfindlichkeit
HMC 0x020x00Dauermessmodus
Wire.endTransmission() == 0-Antwortet die Adresse, ist das Gerät am Bus
atan2(y, x) × 180 / π-Winkel zwischen −180 und +180 Grad aus den Rohachsen

Wie wird der Kurs berechnet?

Liegt das Modul flach, verteilt sich das horizontale Erdmagnetfeld auf die X- und Y-Achse. Zeigt der X-Pfeil nach Norden, fällt das gesamte Feld auf die X-Achse und Y geht gegen null; beim Drehen wandert der Anteil auf die Y-Achse. Der Kurs ergibt sich aus der Formel θ = atan2(Y, X). Wir nehmen atan2 statt des einfachen atan(Y/X), weil atan2 die Vorzeichen beider Werte auswertet und so alle vier Quadranten unterscheidet und bei X = 0 keine Division durch null verursacht. Das Ergebnis kommt als Bogenmaß zwischen −180 und +180 Grad; du multiplizierst mit 180/π und addierst 360, wenn es negativ ist. Jede der acht Hauptrichtungen deckt einen 45-Grad-Sektor ab: 337,5 bis 22,5 Grad ist Norden (N), 22,5 bis 67,5 Nordost (NO) und so weiter; die Rechnung (Winkel + 22,5) / 45 im Code wählt den richtigen Sektor. Nimmt der Winkel beim Drehen im Uhrzeigersinn ab statt zu, ist die Achsenanordnung deiner Platine anders; dreh das Vorzeichen von Y um und nutze atan2(-y, x).

Was ist die magnetische Deklination?

Die Kompassnadel zeigt nicht zum geografischen (wahren) Norden, sondern zum magnetischen Norden. Den Winkel dazwischen nennt man magnetische Deklination; sie hängt von Ort und Jahr ab. In Deutschland ist die Deklination östlich und liegt derzeit grob bei +3 bis +5 Grad, in Österreich und der Schweiz ähnlich; als Startwert sind 4 Grad brauchbar. Die Korrektur ist einfach: wahrer Kurs = magnetischer Kurs + Deklination; östliche Deklination wird positiv, westliche negativ eingesetzt. Den aktuellen Wert für deinen Standort findest du beim NOAA oder einem ähnlichen Magnetmodell-Rechner; trage ihn in die Konstante DECLINATION im Code ein. Bekommst du den Wert in Grad und Minuten, wandle ihn in Dezimalgrad um: 5° 48' = 5 + 48/60 = 5,8 Grad. Weil sich die Deklination jedes Jahr um einige Bogenminuten verschiebt, lohnt sich eine Kontrolle alle paar Jahre. Im Beispielcode steht der Wert 6,0, den du an deinen Ort anpassen musst.

Kompass-Kalibrierung: Hard Iron und Soft Iron

Ein unkalibrierter Kompass kann sich, besonders beim ersten Versuch, um 20–40 Grad irren. Dafür gibt es zwei Ursachen. Beim Hard-Iron-Effekt addieren Dauermagnete in der Nähe, magnetisierte Schrauben oder Bauteile auf der Platine jedem Messwert einen festen Betrag; trägst du X und Y beim Drehen in ein Diagramm ein, siehst du, dass der Kreismittelpunkt nicht bei null liegt. Beim Soft-Iron-Effekt verbiegen Eisen oder Nickel in der Nähe das Feld und machen aus dem Kreis eine Ellipse. Die Lösung ist einfach: Halte das Modul in seiner endgültigen Einbaulage flach, drehe es langsam zwei bis drei Runden und notiere für jede Achse den kleinsten und größten Wert. Offset = (max + min) / 2 liefert den Hard-Iron-Anteil, Skalierung = mittlerer Radius / Achsenradius eine einfache Soft-Iron-Korrektur. Der folgende Sketch gilt für den QMC5883L, der auf den meisten Platinen sitzt; hast du einen HMC5883L, ersetze die Lesefunktion durch den HMC-Teil aus dem ersten Sketch.

C++ (Arduino IDE)
1#include <Wire.h>
2
3const uint8_t QMC_ADDR = 0x0D;
4int16_t minX = 32767, maxX = -32768;
5int16_t minY = 32767, maxY = -32768;
6unsigned long samples = 0;
7unsigned long lastPrint = 0;
8
9void qmcInit() {
10  Wire.beginTransmission(QMC_ADDR);
11  Wire.write(0x0B); Wire.write(0x01);    // SET/RESET periyodu / SET/RESET period
12  Wire.endTransmission();
13  Wire.beginTransmission(QMC_ADDR);
14  Wire.write(0x09); Wire.write(0x1D);    // sürekli, 200 Hz, ±8 G / continuous, 200 Hz, ±8 G
15  Wire.endTransmission();
16}
17
18bool qmcRead(int16_t &x, int16_t &y, int16_t &z) {
19  Wire.beginTransmission(QMC_ADDR);
20  Wire.write(0x00);
21  if (Wire.endTransmission() != 0) return false;
22  if (Wire.requestFrom(QMC_ADDR, (uint8_t)6) != 6) return false;
23  uint8_t b[6];
24  for (uint8_t i = 0; i < 6; i++) b[i] = Wire.read();
25  x = (int16_t)((uint16_t)b[1] << 8 | b[0]);
26  y = (int16_t)((uint16_t)b[3] << 8 | b[2]);
27  z = (int16_t)((uint16_t)b[5] << 8 | b[4]);
28  return true;
29}
30
31void setup() {
32  Serial.begin(9600);
33  Wire.begin();
34  qmcInit();
35  Serial.println(F("Modulu duz tutup yavasca 2-3 tur cevir / Rotate it flat, slowly, 2-3 turns"));
36}
37
38void loop() {
39  int16_t x, y, z;
40  if (qmcRead(x, y, z)) {
41    if (x < minX) minX = x;
42    if (x > maxX) maxX = x;
43    if (y < minY) minY = y;
44    if (y > maxY) maxY = y;
45    samples++;
46  }
47  if (samples > 50 && millis() - lastPrint > 1000) {
48    lastPrint = millis();
49    float offX = ((long)maxX + minX) / 2.0;   // hard iron ofseti / hard iron offset
50    float offY = ((long)maxY + minY) / 2.0;
51    float dX = ((long)maxX - minX) / 2.0;     // eksen yarıçapı / axis radius
52    float dY = ((long)maxY - minY) / 2.0;
53    float avg = (dX + dY) / 2.0;              // ortalama yarıçap / average radius
54    Serial.print(F("OFF_X=")); Serial.print(offX, 1);
55    Serial.print(F("  OFF_Y=")); Serial.print(offY, 1);
56    if (dX > 0 && dY > 0) {
57      Serial.print(F("  SCALE_X=")); Serial.print(avg / dX, 3);
58      Serial.print(F("  SCALE_Y=")); Serial.print(avg / dY, 3);
59    }
60    Serial.println();
61  }
62  delay(20);
63}

Der Sketch gibt jede Sekunde die OFF- und SCALE-Werte aus; drehe weiter, bis sich die Zahlen nicht mehr ändern. Hast du zum Beispiel für X ein Minimum von −680 und ein Maximum von 920 gemessen, ist der Offset (920 + (−680)) / 2 = 120 und der Radius 800. Für Y mit Minimum −1010 und Maximum 550 ergibt sich ein Offset von −230 und ein Radius von 780. Der mittlere Radius ist 790, also werden die Skalierungen 790 / 800 ≈ 0,988 und 790 / 780 ≈ 1,013. Im Hauptsketch korrigierst du jeden Rohwert nach x = (Roh_x − OFF_X) × SCALE_X; im ESP32-Beispiel unten sind diese Werte schon eingetragen. Da im ±8-G-Bereich 1 Gauß 3000 Zählern entspricht, bedeutet ein Radius von 800 ein horizontales Feld von rund 0,27 G, was zum erwarteten Wert für Mitteleuropa passt. Setzt du das Modul an einen anderen Ort oder bringst ein neues Metallteil in die Nähe, kalibriere erneut.

Kompass mit OLED-Anzeige am ESP32

0,96-Zoll-I2C-OLED-Display
0,96-Zoll-I2C-OLED-Display (0x3C); es teilt sich problemlos denselben I2C-Bus mit dem Kompassmodul (0x0D).

Auf dem ESP32 läuft derselbe Wire-Code; die I2C-Pins sind GPIO 21 (SDA) und GPIO 22 (SCL), und Kompass und 0,96-Zoll-OLED hängen am selben Bus. Der Sketch wendet die Kalibrierwerte an, glättet X und Y mit einem einfachen Tiefpassfilter und zeigt links eine drehende Kompassnadel, rechts den Winkel in Grad und den Himmelsrichtungsbuchstaben. Wir filtern die Achsen statt des Winkels, damit beim Übergang zwischen 359 und 0 Grad der Mittelwert der Winkel nicht fälschlich bei etwa 180 landet. Der kurze Strich oben am Kreis zeigt die Vorderseite des Geräts, die Nadel zeigt nach Norden; drehst du das Gerät, dreht sich die Nadel in die Gegenrichtung, genau wie bei einem echten Kompass. Zur Installation der Display-Bibliotheken schau in den Beitrag OLED-Display (SSD1306).

C++ (Arduino IDE)
1#include <Wire.h>
2#include <Adafruit_GFX.h>
3#include <Adafruit_SSD1306.h>
4#include <math.h>
5
6Adafruit_SSD1306 display(128, 64, &Wire, -1);
7
8const uint8_t QMC_ADDR = 0x0D;
9const float DECLINATION = 6.0;                  // şehrine göre değiştir / change for your city
10const float OFF_X = 120.0, OFF_Y = -230.0;      // kalibrasyon kodundan / from calibration sketch
11const float SCALE_X = 0.988, SCALE_Y = 1.013;
12
13float fx = 0, fy = 0;                           // filtrelenmiş eksenler / filtered axes
14bool firstRead = true;
15
16void qmcInit() {
17  Wire.beginTransmission(QMC_ADDR);
18  Wire.write(0x0B); Wire.write(0x01);           // SET/RESET periyodu / SET/RESET period
19  Wire.endTransmission();
20  Wire.beginTransmission(QMC_ADDR);
21  Wire.write(0x09); Wire.write(0x1D);           // sürekli, 200 Hz, ±8 G / continuous, 200 Hz, ±8 G
22  Wire.endTransmission();
23}
24
25bool qmcRead(int16_t &x, int16_t &y, int16_t &z) {
26  Wire.beginTransmission(QMC_ADDR);
27  Wire.write(0x00);
28  if (Wire.endTransmission() != 0) return false;
29  if (Wire.requestFrom(QMC_ADDR, (uint8_t)6) != 6) return false;
30  uint8_t b[6];
31  for (uint8_t i = 0; i < 6; i++) b[i] = Wire.read();
32  x = (int16_t)((uint16_t)b[1] << 8 | b[0]);
33  y = (int16_t)((uint16_t)b[3] << 8 | b[2]);
34  z = (int16_t)((uint16_t)b[5] << 8 | b[4]);
35  return true;
36}
37
38const char* directionName(float h) {
39  static const char* const names[] = {"K", "KD", "D", "GD", "G", "GB", "B", "KB"};
40  return names[(int)((h + 22.5f) / 45.0f) % 8];
41}
42
43void setup() {
44  Serial.begin(115200);
45  Wire.begin(21, 22);                           // SDA = GPIO 21, SCL = GPIO 22
46  qmcInit();
47  if (!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) {
48    Serial.println(F("OLED bulunamadi / OLED not found"));
49    for (;;) delay(1000);
50  }
51  display.setTextColor(SSD1306_WHITE);
52}
53
54void loop() {
55  int16_t rx, ry, rz;
56  if (!qmcRead(rx, ry, rz)) { delay(100); return; }
57
58  float x = (rx - OFF_X) * SCALE_X;             // kalibrasyonu uygula / apply calibration
59  float y = (ry - OFF_Y) * SCALE_Y;
60  if (firstRead) { fx = x; fy = y; firstRead = false; }
61  fx = 0.8f * fx + 0.2f * x;                    // basit alçak geçiren filtre / simple low-pass filter
62  fy = 0.8f * fy + 0.2f * y;
63
64  float heading = atan2f(fy, fx) * 180.0f / PI + DECLINATION;
65  if (heading < 0) heading += 360.0f;
66  if (heading >= 360.0f) heading -= 360.0f;
67
68  display.clearDisplay();
69  const int cx = 32, cy = 32, r = 30;
70  display.drawCircle(cx, cy, r, SSD1306_WHITE);
71  display.drawFastVLine(cx, 0, 4, SSD1306_WHITE);   // cihazın ön yönü / device forward mark
72
73  float a = heading * PI / 180.0f;
74  int nx = cx - (int)(24 * sinf(a));            // kuzeyi gösteren uç / tip pointing north
75  int ny = cy - (int)(24 * cosf(a));
76  int sx = cx + (int)(12 * sinf(a));            // güney ucu / south tail
77  int sy = cy + (int)(12 * cosf(a));
78  display.drawLine(sx, sy, nx, ny, SSD1306_WHITE);
79  display.fillCircle(nx, ny, 3, SSD1306_WHITE);
80  display.fillCircle(cx, cy, 2, SSD1306_WHITE);
81
82  display.setTextSize(2);
83  display.setCursor(72, 10);
84  display.print((int)(heading + 0.5f) % 360);
85  display.drawCircle(display.getCursorX() + 3, 12, 2, SSD1306_WHITE);   // derece işareti / degree sign
86  display.setCursor(72, 38);
87  display.print(directionName(heading));
88  display.display();
89  delay(100);
90}

Kompass mit MicroPython am Raspberry Pi Pico

Auf dem Pico genügt die Klasse machine.I2C von MicroPython, eine separate Treiberdatei brauchst du nicht. Der Code listet zuerst mit i2c.scan() die Adressen am Bus auf, schreibt die Einstellungen passend zum gefundenen Chip und liest mit readfrom_mem alle sechs Bytes auf einmal. Da MicroPython die Bytes vorzeichenlos liefert, musst du Werte über 32767 durch Abziehen von 65536 in negative Zahlen umwandeln. Für die Kalibrierung trägst du die OFF- und SCALE-Werte aus dem Arduino-Sketch in die Konstanten ein. Wenn du neu bei MicroPython bist, sind MicroPython-Grundlagen und Was ist der Raspberry Pi Pico ein guter Einstieg.

MicroPython
1from machine import Pin, I2C
2import math
3import time
4
5i2c = I2C(0, sda=Pin(4), scl=Pin(5), freq=400000)
6QMC = 0x0D
7HMC = 0x1E
8DECLINATION = 6.0                  # manyetik sapma, doğu + / magnetic declination, east +
9OFF_X, OFF_Y = 0.0, 0.0            # kalibrasyon ofsetleri / calibration offsets
10SCALE_X, SCALE_Y = 1.0, 1.0        # kalibrasyon ölçekleri / calibration scales
11
12found = i2c.scan()
13print("I2C:", [hex(a) for a in found])
14
15if QMC in found:
16    addr = QMC
17    i2c.writeto_mem(QMC, 0x0B, bytes([0x01]))   # SET/RESET periyodu / SET/RESET period
18    i2c.writeto_mem(QMC, 0x09, bytes([0x1D]))   # sürekli, 200 Hz, ±8 G / continuous, 200 Hz, ±8 G
19elif HMC in found:
20    addr = HMC
21    i2c.writeto_mem(HMC, 0x00, bytes([0x70]))   # 8 ortalama, 15 Hz / 8 samples, 15 Hz
22    i2c.writeto_mem(HMC, 0x01, bytes([0x20]))   # ±1,3 Ga kazanç / ±1.3 Ga gain
23    i2c.writeto_mem(HMC, 0x02, bytes([0x00]))   # sürekli mod / continuous mode
24else:
25    raise OSError("Pusula bulunamadi / Compass not found")
26
27def to_int16(v):
28    return v - 65536 if v > 32767 else v
29
30def read_xyz():
31    if addr == QMC:
32        b = i2c.readfrom_mem(QMC, 0x00, 6)      # X, Y, Z; önce düşük bayt / LSB first
33        x = to_int16(b[1] << 8 | b[0])
34        y = to_int16(b[3] << 8 | b[2])
35        z = to_int16(b[5] << 8 | b[4])
36    else:
37        b = i2c.readfrom_mem(HMC, 0x03, 6)      # X, Z, Y; önce yüksek bayt / MSB first
38        x = to_int16(b[0] << 8 | b[1])
39        z = to_int16(b[2] << 8 | b[3])
40        y = to_int16(b[4] << 8 | b[5])
41    return x, y, z
42
43NAMES = ("K", "KD", "D", "GD", "G", "GB", "B", "KB")
44
45while True:
46    x, y, z = read_xyz()
47    x = (x - OFF_X) * SCALE_X
48    y = (y - OFF_Y) * SCALE_Y
49    heading = (math.degrees(math.atan2(y, x)) + DECLINATION) % 360
50    name = NAMES[int((heading + 22.5) // 45) % 8]
51    print("Yon: {:.1f} derece {}".format(heading, name))
52    time.sleep(0.2)

Neigungskompensation: Warum das Modul flach liegen muss

Ein nur aus X und Y berechneter Kurs stimmt, solange das Modul parallel zum Boden liegt. In mittleren Breiten wie Mitteleuropa tritt das Magnetfeld mit einer Neigung von etwa 65–68 Grad in den Boden ein; deshalb ist die vertikale (Z) Komponente deutlich größer als die horizontale. Kippst du das Modul um 10 Grad, mischt sich ein Teil der Z-Komponente in X oder Y, und der Kurs kann um bis zu 15 Grad abweichen. Bei handgehaltenen oder wackelnden Geräten hilft die Neigungskompensation: Mit einem MPU-6050-Beschleunigungssensor bestimmst du Roll- und Nickwinkel und drehst die Magnetometerwerte in die Horizontalebene. Bei einfachen Projekten wie einem Roboterauto oder einer festen Box reicht es oft, das Modul flach und stabil am Gehäuse zu montieren.

Projektideen mit dem Kompassmodul

  • Roboterauto mit Kurshaltung: Bring deinem Roboterauto bei, einen bestimmten Winkel anzufahren und geradeaus zu fahren; montiere das Modul fern von den Motoren auf einem Kunststoffmast.
  • Zielführung mit GPS: Berechne mit dem NEO-6M GPS den Kurs zum Ziel und zeige die Differenz zum Kompass als Pfeil auf dem Display.
  • Kompass mit Servo-Zeiger: Drehe den Arm eines Servomotors so, dass er immer nach Norden zeigt, egal wie du die Box drehst.
  • Qibla-Finder: Trage den Qibla-Winkel deines Ortes in den Code ein und drehe den Pfeil auf dem OLED statt nach Norden nach diesem Winkel.
  • Solarpanel-Ausrichtung: Prüfe in einer Solar-Tracking-Anlage mit dem Kompass, ob das Panel in die richtige Richtung zeigt.
  • Richtungsansagender Blindenstock: Erweitere das Projekt Intelligenter Stock um einen Modus, der kurz vibriert, wenn der Nutzer nach Norden zeigt.
  • Magnet- und Metalldetektor: Berechne aus den drei Achsen die Gesamtfeldstärke und lass einen Buzzer ertönen, wenn der Wert plötzlich steigt.

Häufige Fehler und ihre Lösungen

SymptomMögliche UrsacheLösung
Fehler "No HMC5883 detected"Auf der Platine sitzt ein QMC5883LCode mit Adresse 0x0D oder die Bibliothek QMC5883LCompass verwenden
Im I2C-Scan erscheint keine AdresseSDA und SCL vertauscht, keine Versorgung oder KabelbruchKabel prüfen, Spannung am VCC-Pin messen
X, Y, Z sind immer 0 oder ändern sich nichtDer QMC5883L ist nach dem Einschalten im StandbyDauermessmodus (0x1D) in Register 0x09 schreiben
Der Winkel deckt nicht die vollen 360 Grad abHard-Iron-Offset ist zu großKalibrieren und die OFF-Werte abziehen
Beim Drehen im Uhrzeigersinn nimmt der Winkel abAchsenanordnung der Platine ist andersatan2(-y, x) verwenden
Beim Laufen der Motoren driftet der KursMotormagnete und stromführende KabelModul 15–20 cm entfernt auf einen Mast setzen
Beim Kippen weicht der Kurs abKeine NeigungskompensationModul flach montieren oder mit dem MPU-6050 kompensieren
Beim Testen können ein Metalltisch, der Lautsprecher eines Laptops, ein Handy und sogar der Ferritkern an einem USB-Kabel die Messung verfälschen. Kalibriere und teste in der Einbaulage, in der das Modul später im Projekt sitzt, und mit der endgültigen Verkabelung; ein auf dem Tisch perfekt kalibrierter Kompass kann im Inneren des Roboters wieder abweichen.

Das GY-271-Kompassmodul ist, sobald du den richtigen Chip erkannt und es einmal kalibriert hast, eine der günstigsten Möglichkeiten, deinen Projekten einen Richtungssinn zu geben. Zur Anzeige des Kurses kannst du ein I2C-LCD oder OLED nutzen, um ihn in Bewegung umzusetzen Servo, Schrittmotor oder ein Roboterauto. In der BlueGrays-App findest du solche Display-, Motor- und Roboterprojekte Schritt für Schritt mit Schaltplan und Code, und das Kompassmodul lässt sich leicht dazu ergänzen.

Häufige Fragen

Sitzt auf meinem GY-271 ein QMC5883L oder ein HMC5883L?

Am einfachsten machst du einen I2C-Scan: Erscheint die Adresse 0x0D, ist es ein QMC5883L, bei 0x1E ein HMC5883L. Du kannst auch auf den Aufdruck des Chips schauen; beim QMC5883L steht meist DA 5883, beim HMC5883L L883. Auf den meisten heute verkauften GY-271-Platinen sitzt ein QMC5883L.

Funktioniert eine HMC5883L-Bibliothek mit dem QMC5883L?

Nein. I2C-Adresse, Registeradressen, Byte-Reihenfolge und Einstellwerte der beiden Chips sind verschieden; die HMC-Bibliothek sucht die Adresse 0x1E und findet den QMC5883L nicht. Für den QMC5883L brauchst du eine Bibliothek wie QMC5883LCompass oder Code, der direkt mit Wire geschrieben ist.

Warum zeigt mein Arduino-Kompassmodul die falsche Richtung an?

Die häufigste Ursache ist fehlende Kalibrierung; Magnete und Metallteile in der Nähe addieren einen Offset und können den Winkel um Dutzende Grad verschieben. Auch ein schief liegendes Modul, die Nähe zu Motoren und stromführenden Kabeln sowie eine nicht berücksichtigte Deklination führen zu Fehlern. Das Modul flach zu montieren und in der Endlage zu kalibrieren senkt den Fehler meist auf wenige Grad.

Wie groß ist die magnetische Deklination in Deutschland?

In Deutschland ist die Deklination östlich und liegt derzeit grob zwischen 3 und 5 Grad; im Westen etwas kleiner, im Osten etwas größer. Für eine erste Näherung kannst du etwa 4 Grad verwenden. Da sich der Wert über die Jahre langsam ändert, solltest du für ein genaues Ergebnis einen aktuellen Magnetmodell-Rechner befragen.

Funktioniert das GY-271-Kompassmodul mit 5 V?

Ja, da auf der GY-271-Platine ein 3,3-V-Regler sitzt, kannst du an VCC 3–5 V anlegen und die Platine direkt an den Arduino Uno anschließen. Der Chip selbst arbeitet mit 3,3 V; beim ESP32 und Raspberry Pi Pico versorgst du die Platine am besten über den 3V3-Pin.

Misst ein Kompassmodul auch richtig, wenn es schräg gehalten wird?

Ein nur aus X und Y berechneter Kurs stimmt nur, wenn das Modul parallel zum Boden liegt. Da das Magnetfeld in Mitteleuropa mit etwa 65 Grad Neigung in den Boden eintritt, kann schon eine kleine Schräglage den Kurs um 10–15 Grad verschieben. Bei handgehaltenen Geräten brauchst du eine Neigungskompensation mit einem Beschleunigungssensor wie dem MPU-6050.

Alle Projekte ansehen
Verwendung des LCD-Bildschirms mit I2C
AR-32Anfänger
Premium

Verwendung des LCD-Bildschirms mit I2C

Gib deinem Arduino ein eigenes Display und lass es seine erste Nachricht schreiben.

4.8(53)
70
ESP32 I2C-LCD-Display (16×2)
ES-17Mittel
Premium

ESP32 I2C-LCD-Display (16×2)

In diesem Projekt schließen wir ein 16x2-Zeichen-LCD über I2C an den ESP32 an und zeigen Text an. Dank I2C reichen 2 Datenpins (SDA und SCL) statt der 6+ Pins einer klassischen Parallelverbindung. Der Code schreibt eine feste Nachricht in die erste Zeile und einen sekündlich steigenden Zähler in die zweite. Beim Start gibt ein I2C-Scanner die Adresse des Displays im Serial Monitor aus (meist 0x27 oder 0x3F).

4.9(23)
40
ESP32 HTTPClient + Wetter-API (mit SSD1306-OLED-Display)
ES-32Fortgeschritten
Premium

ESP32 HTTPClient + Wetter-API (mit SSD1306-OLED-Display)

Der ESP32 ruft über das Internet mit HTTPClient.h eine Wetter-API (wttr.in) per REST auf. Anders als die I2C-LCD-Version nutzt dieses Projekt ein SSD1306-OLED (128×64) mit großer Schrift und Vektor-Icons für eine reichere Darstellung. Sieben Wetter-Icons (sonnig, Regen, Schnee und mehr) werden ohne Bitmap-Dateien direkt gezeichnet.

4.3(10)
22
ESP32 Deep Sleep – Batteriesparmodus (OLED + RTC-RAM-Zähler)
ES-33Fortgeschritten
Premium

ESP32 Deep Sleep – Batteriesparmodus (OLED + RTC-RAM-Zähler)

Im Deep-Sleep-Modus schaltet der ESP32 die CPU und die meisten Peripheriegeräte ab und senkt den Strom auf etwa 10µA, entscheidend für batteriebetriebene IoT-Geräte. Das Projekt nutzt drei Weckquellen: einen Timer (15 s), einen externen Pin (EXT0, Taster an GPIO 33) und einen Touch-Pin (T0/GPIO 4). Mit RTC_DATA_ATTR markierte Zähler bleiben im Deep Sleep erhalten.

4.3(10)
16
Verwendung von Servomotoren
AR-35Anfänger
Premium

Verwendung von Servomotoren

Der Arm eines kleinen Servomotors dreht sich nacheinander in drei Stellungen: ganz an den Anfang, genau in die Mitte und ganz ans Ende, mit jeweils zwei Sekunden Pause.

4.7(48)
67
Verwendung von Schrittmotoren
AR-67Mittel
Premium

Verwendung von Schrittmotoren

Ein Motor, der sich Schritt für Schritt genau so weit dreht, wie du willst, wie der Zeiger einer Uhr.

4.5(31)
42
Bluetooth-gesteuertes Auto mit L298N
AR-80Fortgeschritten
Premium

Bluetooth-gesteuertes Auto mit L298N

Mach dein Handy zur Fernbedienung und steuere dein eigenes Roboterauto. Der Arduino empfängt über ein Bluetooth-Modul die Befehle einer Fernsteuer-App auf dem Handy und treibt die Räder über einen…

5.0(39)
66
Roboter zur Hindernisvermeidung
AR-81Fortgeschritten
Premium

Roboter zur Hindernisvermeidung

Wie wäre es, ein intelligentes Fahrzeug zu bauen, das seinen Weg selbst findet? Der Obstacle Avoiding Robot scannt dank des Ultraschallsensors vor ihm ständig seine Umgebung.

5.0(38)
49