Bussola digitale Arduino: QMC5883L e HMC5883L (GY-271)
Bussola GY-271: QMC5883L o HMC5883L? Indirizzi I2C (0x0D, 0x1E), calcolo della direzione, declinazione, calibrazione e bussola OLED con Uno, ESP32, Pico.
Il modulo bussola per Arduino è un piccolo sensore di campo magnetico che dice alla tua scheda dove si trova il nord. Il modello più diffuso, il GY-271, misura il campo magnetico terrestre su tre assi; da questa misura puoi calcolare l'angolo di direzione (0–360 gradi), guidare la tua auto robot verso una direzione precisa, mostrare una bussola digitale su un display OLED o aggiungere l'orientamento a un progetto con GPS. Il modulo si collega con soli quattro fili tramite I2C e funziona con la stessa logica su Arduino Uno, ESP32 e Raspberry Pi Pico.
Ma questo modulo nasconde una sorpresa: nella maggior parte delle schede vendute come GY-271 non c'è più il chip HMC5883L di Honeywell, ma il chip QMC5883L di QST. I due chip sembrano quasi identici dall'esterno, ma hanno indirizzi I2C e registri diversi; per questo molti sketch trovati online danno l'errore "sensore non trovato". In questo articolo impari prima a capire quale chip hai sulla scheda, poi a calcolare correttamente l'angolo di direzione, ad aggiungere la declinazione magnetica e a ridurre l'errore a pochi gradi con la calibrazione.
Cos'è un modulo bussola digitale e come funziona?
Il cuore del modulo è un magnetometro, cioè un misuratore di campo magnetico. Il campo magnetico terrestre è piuttosto debole: in Italia la sua intensità totale è di circa 45–48 microtesla (0,45–0,48 gauss), mentre la componente orizzontale, parallela al suolo, è intorno ai 22–25 µT (1 gauss = 100 µT). Il chip, con sensori magnetoresistivi, misura le componenti di questo campo sugli assi X, Y e Z e fornisce ciascuna come numero intero con segno. Quando il modulo è parallelo al suolo, per la direzione bastano i valori X e Y: da queste due componenti ricavi l'angolo con la funzione atan2. L'asse Z serve invece per applicazioni avanzate come la compensazione dell'inclinazione e il rilevamento dei metalli.
| Caratteristica | QMC5883L | HMC5883L |
|---|---|---|
| Produttore | QST | Honeywell (produzione cessata) |
| Indirizzo I2C | 0x0D | 0x1E |
| Campo di misura | ±2 G oppure ±8 G | da ±0,88 G a ±8,1 G (8 livelli) |
| Risoluzione | 16 bit (12000 LSB/G a ±2 G, 3000 LSB/G a ±8 G) | 12 bit (1090 LSB/G a ±1,3 G) |
| Frequenza dati | 10, 50, 100, 200 Hz | 0,75–75 Hz (in modo continuo) |
| Alimentazione del chip | 2,16–3,6 V | 2,16–3,6 V |
| Alimentazione scheda GY-271 | 3–5 V (c'è un regolatore sulla scheda) | 3–5 V (c'è un regolatore sulla scheda) |
| Misura della temperatura | Sì (valore relativo) | No |
QMC5883L o HMC5883L? Come distinguere i due chip
Per anni l'HMC5883L è stato il chip bussola standard dell'elettronica hobbistica. Quando Honeywell ha interrotto la produzione, il mercato si è riempito del QMC5883L di QST. Poiché i venditori spesso non cambiano il nome del prodotto, è normalissimo trovare un QMC5883L sulla scheda acquistata come "HMC5883L". Il modo più sicuro per distinguerli è una scansione I2C: se sul bus compare l'indirizzo 0x0D hai un QMC5883L, se compare 0x1E hai un HMC5883L. Può aiutare anche leggere la scritta sul chip con una lente. Di recente su alcune schede si vede anche il QMC5883P con indirizzo 0x2C; la sua mappa dei registri è diversa, quindi i codici di questo articolo non funzionano direttamente con quel chip.
| Metodo | QMC5883L | HMC5883L |
|---|---|---|
| Indirizzo I2C | 0x0D | 0x1E |
| Scritta sul chip | DA 5883 | L883 |
| Registro di identificazione | Il registro 0x0D restituisce 0xFF | I registri 0x0A–0x0C restituiscono 'H', '4', '3' |
| Registri dei dati | 0x00–0x05 (in ordine X, Y, Z) | 0x03–0x08 (in ordine X, Z, Y) |
| Ordine dei byte | Prima il byte basso (LSB) | Prima il byte alto (MSB) |
| Modo all'accensione | Standby, non misura | Misura singola |
| Libreria comune | QMC5883LCompass | Adafruit HMC5883 Unified |
Collegamento del GY-271: Uno, ESP32 e Pico
| Pin GY-271 | Arduino Uno | ESP32 | Raspberry Pi Pico |
|---|---|---|---|
| VCC | 5V (o 3.3V) | 3V3 | 3V3 (pin 36) |
| GND | GND | GND | GND |
| SCL | A5 | GPIO 22 | GP5 (pin 7) |
| SDA | A4 | GPIO 21 | GP4 (pin 6) |
| DRDY | Non collegato | Non collegato | Non collegato |
La scheda GY-271 ha un regolatore a 3,3 V e le resistenze di pull-up per le linee I2C; per questo su Uno puoi alimentare il modulo dal pin 5V in sicurezza. Su ESP32 e Pico alimenta la scheda dal pin 3V3, così SDA e SCL restano a 3,3 V. Il pin DRDY (dato pronto) emette un segnale a ogni nuova misura; se non leggi i dati tramite interrupt puoi lasciarlo scollegato. La bussola può condividere la stessa linea con altri dispositivi I2C come un display OLED (0x3C) o un MPU-6050 (0x68), perché gli indirizzi non si sovrappongono. Per i dettagli su indirizzi e pull-up leggi l'articolo Cos'è l'I2C.
Passo dopo passo: la prima lettura della direzione (Arduino Uno)
- Inserisci il modulo nella breadboard; se possibile tienilo ad almeno 15–20 cm da motori, altoparlanti, magneti e grossi pezzi d'acciaio.
- Collega i fili VCC, GND, SCL e SDA come nella tabella e lascia libero il pin DRDY.
- Carica il codice qui sotto; non servono librerie aggiuntive, si usa solo la libreria Wire di Arduino.
- Apri il Monitor Seriale a 9600 baud; nella prima riga vedrai quale chip ha trovato il codice.
- Appoggia il modulo in piano sul tavolo e giralo lentamente su sé stesso; osserva i valori X e Y oscillare tra positivo e negativo e l'angolo crescere da 0 a 360.
- Se la bussola del tuo telefono indica il vero nord, punta la freccia X del modulo verso quel nord: l'angolo dovrebbe avvicinarsi a 0. Prima della calibrazione è normale uno scarto di 10–30 gradi.
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}| Codice / registro | Valore | Significato |
|---|---|---|
| QMC 0x0B | 0x01 | Periodo SET/RESET; valore consigliato dal datasheet |
| QMC 0x09 | 0x1D | OSR 512, campo ±8 G, 200 Hz, misura continua (0x0D per ±2 G) |
| HMC 0x00 | 0x70 | Media di 8 misure, frequenza dati 15 Hz |
| HMC 0x01 | 0x20 | Campo ±1,3 Ga, sensibilità 1090 LSB/Ga |
| HMC 0x02 | 0x00 | Modo di misura continua |
| Wire.endTransmission() == 0 | - | Se l'indirizzo risponde, il dispositivo è presente sul bus |
| atan2(y, x) × 180 / π | - | Angolo da −180 a +180 gradi ricavato dagli assi grezzi |
Come si calcola l'angolo di direzione?
Quando il modulo è in piano, il campo magnetico orizzontale terrestre si distribuisce tra gli assi X e Y. Se punti la freccia X verso nord, tutto il campo cade sull'asse X e Y si avvicina a zero; ruotando il modulo, la quota si sposta sull'asse Y. L'angolo di direzione si ricava con la formula θ = atan2(Y, X). Si usa atan2 invece del semplice atan(Y/X) perché atan2 guarda i segni dei due valori e distingue tutti e quattro i quadranti, e non dà errore di divisione per zero quando X è zero. Il risultato è in radianti tra −180 e +180 gradi: lo moltiplichi per 180/π per averlo in gradi e, se è negativo, aggiungi 360. Ciascuna delle otto direzioni principali occupa un settore di 45 gradi: tra 337,5 e 22,5 gradi c'è il Nord (N), tra 22,5 e 67,5 il Nord-Est (NE) e così via; l'operazione (angolo + 22,5) / 45 nel codice sceglie il settore giusto. Nota: i nomi delle direzioni nel codice sono abbreviazioni turche (K = Nord, D = Est, G = Sud, B = Ovest) e puoi sostituirli con N, E, S, W. Se girando il modulo in senso orario l'angolo diminuisce invece di aumentare, la disposizione degli assi della tua scheda è diversa: cambia il segno di Y e usa atan2(-y, x).
Cos'è la declinazione magnetica?
L'ago della bussola non indica il nord geografico (vero), ma quello magnetico. L'angolo tra i due si chiama declinazione magnetica e cambia con il luogo e con l'anno. In Italia la declinazione è verso est e oggi vale circa +2 gradi in Sardegna e nelle regioni occidentali e +4 o +5 gradi nel nord-est e in Puglia; il valore di 6 usato nel codice è quello di esempio per la Turchia, quindi sostituiscilo con il tuo. La formula di correzione è semplice: direzione vera = direzione magnetica + declinazione; la declinazione est è positiva, quella ovest negativa. Basta cercare il valore aggiornato del tuo luogo nel calcolatore del modello magnetico di NOAA o di un ente simile e scriverlo nella costante DECLINATION del codice. Se lo trovi in gradi e primi, convertilo in decimali: 5° 48' = 5 + 48/60 = 5,8 gradi. Poiché la declinazione si sposta di qualche primo d'arco all'anno, conviene ricontrollarla ogni pochi anni.
Calibrazione della bussola: hard iron e soft iron
Una bussola non calibrata, soprattutto al primo tentativo, può sbagliare di 20–40 gradi. Le cause sono due. Con l'effetto hard iron (ferro duro), magneti permanenti vicini al modulo, viti magnetizzate o componenti sulla scheda aggiungono a ogni misura un valore costante; se riporti X–Y in un grafico mentre giri il modulo, vedi il centro del cerchio spostato rispetto allo zero. Con l'effetto soft iron (ferro dolce), materiali come ferro e nichel vicini deformano il campo e trasformano il cerchio in un'ellisse. La soluzione è semplice: tieni il modulo in piano, nella posizione finale in cui starà nel progetto, giralo lentamente per due o tre giri e registra il valore minimo e massimo di ogni asse. Offset = (max + min) / 2 dà la correzione dell'hard iron, mentre scala = raggio medio / raggio dell'asse dà una semplice correzione del soft iron. Il codice qui sotto è per il QMC5883L, presente nella maggior parte delle schede; se usi un HMC5883L basta sostituire la funzione di lettura con la parte HMC del primo codice.
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}Il codice stampa ogni secondo i valori OFF e SCALE; continua a girare finché i numeri non cambiano più. Per esempio, se per X hai misurato un minimo di −680 e un massimo di 920, l'offset è (920 + (−680)) / 2 = 120 e il raggio è 800. Per Y, con minimo −1010 e massimo 550, l'offset è −230 e il raggio 780. Poiché il raggio medio è 790, le scale risultano 790 / 800 ≈ 0,988 e 790 / 780 ≈ 1,013. Nel codice principale correggi ogni lettura grezza come x = (x_grezzo − OFF_X) × SCALE_X; nell'esempio ESP32 qui sotto questi valori sono già scritti. Poiché nel campo ±8 G un gauss corrisponde a 3000 conteggi, un raggio di 800 equivale a circa 0,27 G di campo orizzontale, in linea con quanto atteso. Se sposti il modulo in un altro posto o aggiungi un pezzo di metallo vicino, ripeti la calibrazione.
Bussola su display OLED con ESP32

Su ESP32 funziona lo stesso codice Wire; i pin I2C sono GPIO 21 (SDA) e GPIO 22 (SCL), e la bussola e il display OLED da 0,96 pollici si collegano alla stessa linea. Il codice applica i valori di calibrazione, leviga X e Y con un semplice filtro passa-basso e mostra a sinistra un ago che ruota e a destra i gradi con la lettera della direzione. Il filtro si applica agli assi e non all'angolo perché la media degli angoli intorno al passaggio tra 359 e 0 gradi darebbe per errore circa 180. Il trattino in alto sullo schermo indica il fronte del dispositivo, mentre l'ago indica il nord; quando ruoti il dispositivo l'ago gira nel verso opposto, proprio come una vera bussola. Per installare le librerie del display leggi l'articolo Display OLED (SSD1306).
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}Bussola con MicroPython su Raspberry Pi Pico
Sul Pico basta la classe machine.I2C di MicroPython, non serve un file driver a parte. Il codice elenca prima gli indirizzi presenti sul bus con i2c.scan(), scrive le impostazioni in base al chip trovato e legge i sei byte in un colpo solo con readfrom_mem. Poiché in MicroPython i byte arrivano senza segno, per i valori superiori a 32767 devi sottrarre 65536 per ottenere numeri negativi. Per la calibrazione scrivi nelle costanti del codice i valori OFF e SCALE trovati con Arduino. Se sei alle prime armi con MicroPython, gli articoli Le basi di MicroPython e Cos'è Raspberry Pi Pico sono un buon inizio.
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)Compensazione dell'inclinazione: perché il modulo deve stare in piano
La direzione calcolata solo con gli assi X e Y è corretta soltanto quando il modulo è parallelo al suolo. A latitudini medie come quelle italiane il campo magnetico entra nel terreno con un'inclinazione di circa 55–60 gradi; per questo la componente verticale (Z) è nettamente maggiore di quella orizzontale. Se inclini il modulo di 10 gradi, parte della componente Z si mescola a X o Y e la direzione può spostarsi con un errore fino a 15 gradi. Per i dispositivi portatili o che oscillano la soluzione è la compensazione dell'inclinazione: con un accelerometro MPU-6050 ricavi gli angoli di rollio (roll) e beccheggio (pitch) e ruoti i valori del magnetometro sul piano orizzontale. Per progetti semplici come un'auto robot o una scatola fissa, spesso basta montare il modulo in piano e ben saldo sul corpo.
Idee di progetto con il modulo bussola
- Auto robot che mantiene la rotta: insegna alla tua auto robot a girare verso un angolo stabilito e ad andare dritta; metti il modulo su un'asta di plastica lontano dai motori.
- Guida verso una meta con GPS: calcola con un GPS NEO-6M l'angolo verso la destinazione e mostra sul display, con una freccia, la differenza rispetto alla bussola.
- Bussola con ago a servo: fai ruotare il braccio di un servomotore in modo che indichi sempre il nord, comunque giri la scatola.
- Indicatore della direzione della Qibla: scrivi nel codice l'angolo della Qibla della tua città e ruota la freccia sul display OLED rispetto a questo angolo invece che al nord.
- Orientamento del pannello solare: verifica con la bussola che il pannello guardi nella direzione giusta nel sistema di inseguimento solare.
- Bastone che indica la direzione: aggiungi al progetto del bastone intelligente una modalità che dà una breve vibrazione quando l'utente si volta verso nord.
- Rilevatore di magneti e metalli: calcola l'intensità totale del campo dai tre assi e fai suonare un buzzer quando il valore sale all'improvviso.
Errori comuni e soluzioni
| Sintomo | Causa probabile | Soluzione |
|---|---|---|
| Errore "No HMC5883 detected" | Sulla scheda c'è un QMC5883L | Usa il codice con indirizzo 0x0D o la libreria QMC5883LCompass |
| Nessun indirizzo nella scansione I2C | SDA e SCL invertiti, manca l'alimentazione o il filo è interrotto | Controlla i fili e misura la tensione sul pin VCC |
| X, Y, Z sempre 0 o mai variabili | Il QMC5883L all'avvio è in standby | Scrivi nel registro 0x09 l'impostazione di misura continua (0x1D) |
| L'angolo non copre tutti i 360 gradi | L'offset hard iron è troppo grande | Fai la calibrazione e sottrai i valori OFF |
| Girando in senso orario l'angolo diminuisce | Disposizione degli assi diversa sulla scheda | Usa atan2(-y, x) |
| Con il motore acceso la direzione si sposta | Magnete del motore e cavi ad alta corrente | Sposta il modulo di 15–20 cm, su un'asta |
| Inclinando il modulo la direzione devia | Manca la compensazione dell'inclinazione | Monta il modulo in piano o compensa con un MPU-6050 |
Una volta riconosciuto il chip giusto e fatta la calibrazione, il modulo bussola GY-271 è uno dei modi più economici per dare un senso dell'orientamento ai tuoi progetti. Per mostrare la direzione puoi usare un LCD I2C o un display OLED, per trasformarla in movimento un servo, un motore passo-passo o un'auto robot. Nell'app BlueGrays trovi display, motori e progetti robotici passo dopo passo con schemi e codice, e puoi aggiungere facilmente il modulo bussola a questi progetti.
Domande frequenti
Il mio modulo GY-271 ha un QMC5883L o un HMC5883L?
Il modo più semplice è fare una scansione I2C: se compare l'indirizzo 0x0D hai un QMC5883L, se compare 0x1E hai un HMC5883L. Puoi guardare anche la scritta sul chip: di solito sul QMC5883L c'è DA 5883, sull'HMC5883L L883. Oggi la grande maggioranza delle schede GY-271 in vendita monta il QMC5883L.
La libreria HMC5883L funziona con il QMC5883L?
No. I due chip hanno indirizzo I2C, indirizzi dei registri, ordine dei byte e valori di configurazione diversi; la libreria HMC cerca l'indirizzo 0x1E e non trova il QMC5883L. Per il QMC5883L devi usare una libreria come QMC5883LCompass o un codice scritto direttamente con Wire.
Perché la bussola per Arduino indica la direzione sbagliata?
La causa più frequente è la mancata calibrazione: magneti e parti metalliche vicine aggiungono un offset alla misura e possono spostare l'angolo di decine di gradi. Anche il modulo inclinato, la vicinanza a motori e cavi con corrente e la declinazione magnetica non aggiunta causano errori. Montare il modulo in piano e calibrarlo nella posizione finale di solito riduce l'errore a pochi gradi.
Quanto vale la declinazione magnetica in Italia?
In Italia la declinazione magnetica è verso est e oggi è all'incirca tra 2 e 5 gradi: più piccola nelle regioni occidentali, più grande in quelle orientali. Poiché il valore cambia lentamente negli anni, per un risultato preciso conviene consultare un calcolatore aggiornato del modello magnetico terrestre.
Il modulo bussola GY-271 funziona a 5 V?
Sì, poiché sulla scheda GY-271 c'è un regolatore a 3,3 V, al pin VCC si possono dare 3–5 V e la scheda si collega direttamente ad Arduino Uno. Il chip in sé lavora a 3,3 V; su ESP32 e Raspberry Pi Pico è meglio alimentare la scheda dal pin 3V3.
Il modulo bussola misura correttamente se è inclinato?
La direzione calcolata solo con gli assi X e Y è corretta soltanto quando il modulo è parallelo al suolo. Poiché alle nostre latitudini il campo magnetico entra nel suolo con un'inclinazione di circa 55–60 gradi, anche una piccola inclinazione può spostare la direzione di 10–15 gradi. Nei dispositivi portatili serve la compensazione dell'inclinazione con un accelerometro come l'MPU-6050.
Progetti da realizzare dopo questo articolo
Vedi tutti i progetti
Utilizzo dello schermo LCD con I2C
Regala al tuo Arduino uno schermo tutto suo e fagli scrivere il primo messaggio.

Schermo LCD I2C per ESP32 (16x2)
In questo progetto colleghiamo un display LCD 16x2 a caratteri all'ESP32 tramite I2C per mostrare del testo. Con l'I2C bastano 2 pin dati (SDA e SCL) invece dei 6+ pin di un collegamento parallelo classico. Il codice scrive un messaggio fisso sulla prima riga e un contatore che sale ogni secondo sulla seconda. All'avvio uno scanner I2C stampa l'indirizzo del display sul Serial Monitor (di solito 0x27 o 0x3F).

ESP32 HTTPClient + API meteo (con display OLED SSD1306)
L'ESP32 effettua via internet una chiamata REST a un'API meteo (wttr.in) con HTTPClient.h. A differenza della versione con LCD I2C, qui usiamo un display OLED SSD1306 (128×64), con testo grande e icone vettoriali per una resa più ricca. Sette icone meteo (sole, pioggia, neve e altre) vengono disegnate al volo, senza file bitmap.

ESP32 Deep Sleep — Risparmio della batteria (OLED + contatore in RTC RAM)
La modalità Deep Sleep dell'ESP32 spegne la CPU e quasi tutte le periferiche e riduce il consumo a circa 10µA, un aspetto cruciale per i dispositivi IoT a batteria. Il progetto usa tre sorgenti di risveglio: un timer (15 s), un pin esterno (EXT0, il pulsante su GPIO 33) e un pin touch (T0/GPIO 4). I contatori marcati con RTC_DATA_ATTR restano salvati durante il deep sleep.

Utilizzo del servomotore
Il braccio di un piccolo servomotore ruota a turno in tre posizioni: tutto all'inizio, esattamente a metà e tutto alla fine, aspettando due secondi a ogni fermata.

Utilizzo del motore passo-passo
Un motore che gira passo dopo passo, esattamente quanto vuoi tu, come la lancetta di un orologio.

Auto controllata via Bluetooth con L298N
Trasforma il telefono in un telecomando e guida la tua auto robot. L'Arduino riceve tramite un modulo Bluetooth i comandi di un'app di controllo remoto sul telefono e fa girare le ruote con un driver…

Robot che evita gli ostacoli
Che ne dite di costruire un veicolo intelligente che trova la propria strada? L'Obstacle Avoiding Robot scruta costantemente l'ambiente circostante grazie al sensore a ultrasuoni posto davanti a lui.
Altri articoli
App BlueGrays
Costruisci questo circuito passo passo sul telefono
Schema, codice ed elenco componenti in un’unica schermata. Oltre 500 progetti Arduino, ESP32 e Pico da realizzare.
Inquadra con il telefono
Punta la fotocamera sul codice: si apre lo store del tuo telefono.
oppure apri lo store

