Componenti · 11 min di lettura

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.

CaratteristicaQMC5883LHMC5883L
ProduttoreQSTHoneywell (produzione cessata)
Indirizzo I2C0x0D0x1E
Campo di misura±2 G oppure ±8 Gda ±0,88 G a ±8,1 G (8 livelli)
Risoluzione16 bit (12000 LSB/G a ±2 G, 3000 LSB/G a ±8 G)12 bit (1090 LSB/G a ±1,3 G)
Frequenza dati10, 50, 100, 200 Hz0,75–75 Hz (in modo continuo)
Alimentazione del chip2,16–3,6 V2,16–3,6 V
Alimentazione scheda GY-2713–5 V (c'è un regolatore sulla scheda)3–5 V (c'è un regolatore sulla scheda)
Misura della temperaturaSì (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.

MetodoQMC5883LHMC5883L
Indirizzo I2C0x0D0x1E
Scritta sul chipDA 5883L883
Registro di identificazioneIl registro 0x0D restituisce 0xFFI registri 0x0A–0x0C restituiscono 'H', '4', '3'
Registri dei dati0x00–0x05 (in ordine X, Y, Z)0x03–0x08 (in ordine X, Z, Y)
Ordine dei bytePrima il byte basso (LSB)Prima il byte alto (MSB)
Modo all'accensioneStandby, non misuraMisura singola
Libreria comuneQMC5883LCompassAdafruit HMC5883 Unified
Le librerie HMC come Adafruit HMC5883 Unified cercano solo l'indirizzo 0x1E. Se sulla tua scheda c'è un QMC5883L ricevi un messaggio tipo "no HMC5883 detected" e pensi che il modulo sia rotto. Il modulo non è rotto, ha solo un chip diverso. Fai prima una scansione I2C, poi usa il codice che parla con l'indirizzo giusto.

Collegamento del GY-271: Uno, ESP32 e Pico

Pin GY-271Arduino UnoESP32Raspberry Pi Pico
VCC5V (o 3.3V)3V33V3 (pin 36)
GNDGNDGNDGND
SCLA5GPIO 22GP5 (pin 7)
SDAA4GPIO 21GP4 (pin 6)
DRDYNon collegatoNon collegatoNon 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)

  1. Inserisci il modulo nella breadboard; se possibile tienilo ad almeno 15–20 cm da motori, altoparlanti, magneti e grossi pezzi d'acciaio.
  2. Collega i fili VCC, GND, SCL e SDA come nella tabella e lascia libero il pin DRDY.
  3. Carica il codice qui sotto; non servono librerie aggiuntive, si usa solo la libreria Wire di Arduino.
  4. Apri il Monitor Seriale a 9600 baud; nella prima riga vedrai quale chip ha trovato il codice.
  5. 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.
  6. 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.
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}
Codice / registroValoreSignificato
QMC 0x0B0x01Periodo SET/RESET; valore consigliato dal datasheet
QMC 0x090x1DOSR 512, campo ±8 G, 200 Hz, misura continua (0x0D per ±2 G)
HMC 0x000x70Media di 8 misure, frequenza dati 15 Hz
HMC 0x010x20Campo ±1,3 Ga, sensibilità 1090 LSB/Ga
HMC 0x020x00Modo 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.

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}

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

0,96-inch I2C OLED display
Display OLED I2C da 0,96 pollici (0x3C): condivide senza problemi la stessa linea I2C con il modulo bussola (0x0D).

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).

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}

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.

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)

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

SintomoCausa probabileSoluzione
Errore "No HMC5883 detected"Sulla scheda c'è un QMC5883LUsa il codice con indirizzo 0x0D o la libreria QMC5883LCompass
Nessun indirizzo nella scansione I2CSDA e SCL invertiti, manca l'alimentazione o il filo è interrottoControlla i fili e misura la tensione sul pin VCC
X, Y, Z sempre 0 o mai variabiliIl QMC5883L all'avvio è in standbyScrivi nel registro 0x09 l'impostazione di misura continua (0x1D)
L'angolo non copre tutti i 360 gradiL'offset hard iron è troppo grandeFai la calibrazione e sottrai i valori OFF
Girando in senso orario l'angolo diminuisceDisposizione degli assi diversa sulla schedaUsa atan2(-y, x)
Con il motore acceso la direzione si spostaMagnete del motore e cavi ad alta correnteSposta il modulo di 15–20 cm, su un'asta
Inclinando il modulo la direzione deviaManca la compensazione dell'inclinazioneMonta il modulo in piano o compensa con un MPU-6050
Durante i test, un tavolo metallico, l'altoparlante del portatile, il telefono e perfino il nucleo di ferrite del cavo USB possono alterare la misura. Fai la calibrazione e i test nella posizione finale in cui il modulo sarà usato e con il cablaggio definitivo; una bussola calibrata alla perfezione sul tavolo può sbagliare di nuovo una volta installata dentro il robot.

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.

Vedi tutti i progetti
Utilizzo dello schermo LCD con I2C
AR-32Principiante
Premium

Utilizzo dello schermo LCD con I2C

Regala al tuo Arduino uno schermo tutto suo e fagli scrivere il primo messaggio.

4.8(53)
70
Schermo LCD I2C per ESP32 (16x2)
ES-17Intermedio
Premium

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).

4.9(23)
40
ESP32 HTTPClient + API meteo (con display OLED SSD1306)
ES-32Avanzato
Premium

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.

4.3(10)
22
ESP32 Deep Sleep — Risparmio della batteria (OLED + contatore in RTC RAM)
ES-33Avanzato
Premium

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.

4.3(10)
16
Utilizzo del servomotore
AR-35Principiante
Premium

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.

4.7(48)
67
Utilizzo del motore passo-passo
AR-67Intermedio
Premium

Utilizzo del motore passo-passo

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

4.5(31)
42
Auto controllata via Bluetooth con L298N
AR-80Avanzato
Premium

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…

5.0(39)
66
Robot che evita gli ostacoli
AR-81Avanzato
Premium

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.

5.0(38)
49