Boussole Arduino : QMC5883L et HMC5883L (GY-271), guide complet
Module boussole GY-271 : QMC5883L ou HMC5883L ? Adresses I2C (0x0D, 0x1E), calcul du cap, déclinaison, calibration et boussole OLED, code Uno, ESP32 et Pico.
Un module boussole Arduino est un petit capteur de champ magnétique qui indique à ta carte où se trouve le nord. Le modèle le plus répandu, le GY-271, mesure le champ magnétique terrestre sur trois axes ; à partir de cette mesure tu calcules un cap (0 à 360 degrés) pour guider ta voiture robot dans une direction précise, afficher une boussole numérique sur un écran OLED ou ajouter l'orientation à ton projet GPS. Le module se branche avec seulement quatre fils en I2C et fonctionne de la même façon avec Arduino Uno, ESP32 et Raspberry Pi Pico.
Mais ce module cache une surprise : sur la plupart des cartes vendues sous le nom GY-271, on ne trouve plus la puce HMC5883L de Honeywell, mais la puce QMC5883L de QST. Les deux puces se ressemblent presque de l'extérieur, mais leurs adresses I2C et leurs registres sont différents ; c'est pourquoi beaucoup de codes tout faits répondent « capteur introuvable ». Dans cet article, tu vas d'abord apprendre à savoir quelle puce est sur ta carte, puis à calculer correctement le cap, à ajouter la déclinaison magnétique et à ramener l'erreur à quelques degrés grâce à la calibration.
Qu'est-ce qu'un module boussole numérique et comment fonctionne-t-il ?
Au cœur du module se trouve un magnétomètre, c'est-à-dire un capteur de champ magnétique. Le champ magnétique terrestre est assez faible : en France, son intensité totale est d'environ 45 à 50 microteslas (0,45 à 0,5 gauss) et sa composante horizontale, parallèle au sol, de l'ordre de 20 µT (1 gauss = 100 µT). La puce mesure les composantes de ce champ sur les axes X, Y et Z avec des capteurs magnétorésistifs et fournit chacune sous forme d'entier signé. Quand le module est à plat, les valeurs X et Y suffisent pour le cap ; tu obtiens l'angle à partir de ces deux composantes avec la fonction atan2. L'axe Z sert pour des usages avancés comme la compensation d'inclinaison et la détection de métaux.
| Caractéristique | QMC5883L | HMC5883L |
|---|---|---|
| Fabricant | QST | Honeywell (production arrêtée) |
| Adresse I2C | 0x0D | 0x1E |
| Plage de mesure | ±2 G ou ±8 G | De ±0,88 G à ±8,1 G (8 niveaux) |
| Résolution | 16 bits (12000 LSB/G à ±2 G, 3000 LSB/G à ±8 G) | 12 bits (1090 LSB/G à ±1,3 G) |
| Fréquence de mesure | 10, 50, 100, 200 Hz | 0,75–75 Hz (en mode continu) |
| Alimentation de la puce | 2,16–3,6 V | 2,16–3,6 V |
| Alimentation de la carte GY-271 | 3–5 V (régulateur sur la carte) | 3–5 V (régulateur sur la carte) |
| Mesure de température | Oui (valeur relative) | Non |
QMC5883L ou HMC5883L ? Comment distinguer les deux puces
Pendant de nombreuses années, la HMC5883L a été la puce de boussole standard de l'électronique amateur. Quand Honeywell a arrêté la production, la QMC5883L de QST a envahi le marché. Comme les vendeurs ne changent souvent pas le nom du produit, il est tout à fait courant de recevoir une QMC5883L sur une carte achetée en tant que « HMC5883L ». Le moyen le plus sûr de les distinguer est un scan I2C : si l'adresse 0x0D apparaît sur le bus, c'est une QMC5883L ; si c'est 0x1E, c'est une HMC5883L. Lire l'inscription sur la puce à la loupe fonctionne aussi. Depuis peu, on voit aussi sur certaines cartes une QMC5883P à l'adresse 0x2C ; sa table de registres est différente, donc les codes de cet article ne fonctionnent pas directement avec elle.
| Méthode | QMC5883L | HMC5883L |
|---|---|---|
| Adresse I2C | 0x0D | 0x1E |
| Inscription sur la puce | DA 5883 | L883 |
| Registre d'identification | Le registre 0x0D renvoie 0xFF | Les registres 0x0A–0x0C renvoient 'H', '4', '3' |
| Registres de données | 0x00–0x05 (dans l'ordre X, Y, Z) | 0x03–0x08 (dans l'ordre X, Z, Y) |
| Ordre des octets | Octet de poids faible d'abord (LSB) | Octet de poids fort d'abord (MSB) |
| Mode au démarrage | Veille (standby), ne mesure pas | Mode mesure unique |
| Bibliothèque courante | QMC5883LCompass | Adafruit HMC5883 Unified |
Branchement du GY-271 : Uno, ESP32 et Pico
| Broche GY-271 | Arduino Uno | ESP32 | Raspberry Pi Pico |
|---|---|---|---|
| VCC | 5V (ou 3.3V) | 3V3 | 3V3 (broche 36) |
| GND | GND | GND | GND |
| SCL | A5 | GPIO 22 | GP5 (broche 7) |
| SDA | A4 | GPIO 21 | GP4 (broche 6) |
| DRDY | Non connectée | Non connectée | Non connectée |
La carte GY-271 possède un régulateur 3,3 V et des résistances de pull-up pour les lignes I2C ; alimenter le module depuis la broche 5V de l'Uno est donc sans risque. Sur l'ESP32 et le Pico, alimente la carte depuis la broche 3V3 pour que SDA et SCL restent à 3,3 V. La broche DRDY (données prêtes) signale chaque nouvelle mesure ; tu peux la laisser libre si tu ne lis pas par interruption. La boussole peut partager le même bus avec d'autres périphériques I2C comme un écran OLED (0x3C) ou un MPU-6050 (0x68), car leurs adresses ne se chevauchent pas. Pour les détails sur les adresses et les pull-up, consulte l'article Qu'est-ce que l'I2C.
Pas à pas : première lecture du cap (Arduino Uno)
- Enfonce le module sur la breadboard ; si possible, garde-le à au moins 15–20 cm des moteurs, haut-parleurs, aimants et grosses pièces en acier.
- Branche les fils VCC, GND, SCL et SDA comme dans le tableau et laisse la broche DRDY libre.
- Téléverse le code ci-dessous ; aucune bibliothèque supplémentaire n'est nécessaire, seule la bibliothèque Wire d'Arduino est utilisée.
- Ouvre le moniteur série à 9600 bauds ; sur la première ligne, tu vois quelle puce le code a trouvée.
- Pose le module à plat sur la table et fais-le tourner lentement sur lui-même ; observe les valeurs X et Y passer du positif au négatif et l'angle aller de 0 à 360.
- Si la boussole de ton téléphone est réglée sur le vrai nord, oriente la flèche X du module vers ce nord ; l'angle doit se rapprocher de 0. Avant la calibration, un écart de 10 à 30 degrés est normal.
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 / registre | Valeur | Signification |
|---|---|---|
| QMC 0x0B | 0x01 | Période SET/RESET ; valeur recommandée par la fiche technique |
| QMC 0x09 | 0x1D | OSR 512, plage ±8 G, 200 Hz, mesure continue (0x0D pour ±2 G) |
| HMC 0x00 | 0x70 | Moyenne de 8 mesures, fréquence de 15 Hz |
| HMC 0x01 | 0x20 | Plage ±1,3 Ga, sensibilité de 1090 LSB/Ga |
| HMC 0x02 | 0x00 | Mode de mesure continue |
| Wire.endTransmission() == 0 | - | Si l'adresse répond, l'appareil est présent sur le bus |
| atan2(y, x) × 180 / π | - | Angle compris entre −180 et +180 degrés à partir des axes bruts |
Comment calculer le cap ?
Quand le module est à plat, le champ magnétique horizontal de la Terre se répartit entre les axes X et Y. Si tu orientes la flèche X vers le nord, tout le champ tombe sur l'axe X et Y tend vers zéro ; en tournant le module, une part passe sur l'axe Y. Le cap se calcule avec la formule θ = atan2(Y, X). On utilise atan2 plutôt que atan(Y/X) parce qu'atan2 regarde le signe des deux valeurs pour distinguer les quatre quadrants et ne provoque pas de division par zéro quand X vaut zéro. Le résultat arrive en radians entre −180 et +180 degrés ; tu le multiplies par 180/π pour passer en degrés et tu ajoutes 360 s'il est négatif. Chacune des huit directions principales couvre un secteur de 45 degrés : de 337,5 à 22,5 degrés c'est le Nord (K), de 22,5 à 67,5 le Nord-Est (KD), et ainsi de suite ; l'opération (angle + 22,5) / 45 du code choisit le bon secteur (les lettres du code sont les initiales turques : K = Nord, D = Est, G = Sud, B = Ouest). Si l'angle diminue quand tu tournes le module dans le sens des aiguilles d'une montre, la disposition des axes de ta carte est différente ; change le signe de Y et utilise atan2(-y, x) pour régler le problème.
Qu'est-ce que la déclinaison magnétique ?
L'aiguille d'une boussole indique le nord magnétique, pas le nord géographique (vrai). L'angle entre les deux s'appelle la déclinaison magnétique et varie selon l'endroit et l'année. En France métropolitaine, la déclinaison est aujourd'hui faible : environ +1 degré à l'est et un peu plus de 0 à l'ouest, selon la région ; pour une valeur précise, consulte un calculateur. La formule de correction est simple : cap vrai = cap magnétique + déclinaison ; la déclinaison est positive à l'est et négative à l'ouest. Il te suffit de chercher la valeur actuelle de ton lieu dans le calculateur de modèle magnétique de la NOAA ou d'un organisme équivalent et de l'écrire dans la constante DECLINATION du code (le code de l'exemple utilise 6,0, une valeur d'exemple à adapter). Si tu trouves la valeur en degrés et minutes, convertis-la en décimal : 5° 48' = 5 + 48/60 = 5,8 degrés. Comme la déclinaison dérive de quelques minutes d'arc par an, il est bon de la vérifier tous les quelques années.
Calibration de la boussole : hard iron et soft iron
Une boussole non calibrée peut se tromper de 20 à 40 degrés, surtout au premier essai. Il y a deux causes. Avec l'effet hard iron (fer dur), des aimants permanents proches du module, des vis magnétisées ou des composants de la carte ajoutent une valeur constante à chaque mesure ; si tu traces les valeurs X–Y en tournant le module, tu vois le centre du cercle décalé par rapport à zéro. Avec l'effet soft iron (fer doux), des matériaux voisins comme le fer et le nickel déforment le champ et transforment le cercle en ellipse. La solution est simple : tiens le module à plat dans sa position finale dans le projet, fais-le tourner lentement de deux ou trois tours et enregistre le minimum et le maximum de chaque axe. Décalage = (max + min) / 2 corrige l'effet hard iron, et échelle = rayon moyen / rayon de l'axe donne une correction soft iron simple. Le code ci-dessous est pour la QMC5883L, présente sur la plupart des cartes ; si tu utilises une HMC5883L, il suffit de remplacer la fonction de lecture par la partie HMC du premier code.
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}Le code affiche chaque seconde les valeurs OFF et SCALE ; continue à tourner jusqu'à ce que les nombres ne changent plus. Par exemple, si tu as mesuré −680 au minimum et 920 au maximum pour X, le décalage est (920 + (−680)) / 2 = 120 et le rayon 800. Pour Y, avec −1010 au minimum et 550 au maximum, le décalage est −230 et le rayon 780. Le rayon moyen étant 790, les échelles valent 790 / 800 ≈ 0,988 et 790 / 780 ≈ 1,013. Dans le code principal, tu corriges chaque lecture brute sous la forme x = (x_brut − OFF_X) × SCALE_X ; dans l'exemple ESP32 ci-dessous, ces valeurs sont déjà écrites. Comme 1 gauss correspond à 3000 unités sur la plage ±8 G, un rayon de 800 représente un champ horizontal d'environ 0,27 G, ce qui est cohérent avec la valeur attendue en Europe. Si tu déplaces le module ou si tu ajoutes une pièce métallique à proximité, refais la calibration.
Boussole sur écran OLED avec l'ESP32

Sur l'ESP32, le même code Wire fonctionne ; les broches I2C sont GPIO 21 (SDA) et GPIO 22 (SCL), et la boussole comme l'écran OLED 0,96 pouce se branchent sur le même bus. Le code applique les valeurs de calibration, lisse X et Y avec un simple filtre passe-bas, puis affiche une aiguille de boussole qui tourne à gauche de l'écran, et le cap en degrés avec la lettre de direction à droite. Le filtre est appliqué aux axes et non à l'angle pour éviter que, lors du passage entre 359 et 0 degré, la moyenne des angles ne tombe par erreur autour de 180. Le petit trait en haut de l'écran indique l'avant de l'appareil et l'aiguille indique le nord ; quand tu tournes l'appareil, l'aiguille tourne dans l'autre sens, exactement comme une vraie boussole. Pour l'installation des bibliothèques d'écran, consulte l'article Écran 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}Boussole MicroPython avec le Raspberry Pi Pico
Sur le Pico, la classe machine.I2C de MicroPython suffit, aucun fichier de pilote séparé n'est nécessaire. Le code liste d'abord les adresses du bus avec i2c.scan(), écrit les réglages selon la puce trouvée et lit les six octets d'un coup avec readfrom_mem. Comme les octets arrivent non signés en MicroPython, tu dois soustraire 65536 aux valeurs supérieures à 32767 pour obtenir des nombres négatifs. Pour la calibration, il te suffit d'écrire dans les constantes du code les valeurs OFF et SCALE trouvées avec l'Arduino. Si tu débutes avec MicroPython, les articles Bases de MicroPython et Qu'est-ce que le Raspberry Pi Pico sont un bon point de départ.
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)Compensation d'inclinaison : pourquoi le module doit rester à plat
Le cap calculé uniquement avec les axes X et Y n'est juste que si le module est parallèle au sol. Aux latitudes moyennes comme celles de la France, le champ magnétique pénètre dans le sol avec une inclinaison d'environ 60 à 65 degrés ; la composante verticale (Z) est donc nettement plus grande que la composante horizontale. Quand le module est incliné de 10 degrés, une partie de la composante Z se mélange à l'axe X ou Y et le cap peut dériver d'une erreur allant jusqu'à 15 degrés. Pour les appareils tenus à la main ou qui bougent, la solution est la compensation d'inclinaison : avec un accéléromètre MPU-6050, tu obtiens les angles de roulis (roll) et de tangage (pitch) et tu ramènes les valeurs du magnétomètre dans le plan horizontal. Pour des projets simples comme une voiture robot ou un boîtier fixe, monter le module à plat et solidement sur le châssis suffit souvent.
Idées de projets avec le module boussole
- Voiture robot qui garde son cap : apprends à ta voiture robot à tourner vers un angle donné et à rouler droit ; place le module sur un mât en plastique, loin des moteurs.
- Guidage vers un point avec GPS : calcule le cap de la cible avec le GPS NEO-6M et affiche la différence avec la boussole sous forme de flèche à l'écran.
- Boussole à aiguille servo : fais tourner le bras d'un servomoteur pour qu'il pointe toujours vers le nord, quelle que soit la façon dont tu tournes le boîtier.
- Indicateur de direction de la Qibla : écris l'angle de la Qibla de ta ville dans le code et fais tourner la flèche de l'écran OLED selon cet angle au lieu du nord.
- Orientation de panneau solaire : vérifie avec la boussole que le panneau est bien orienté dans un système de suivi solaire.
- Canne qui indique la direction : ajoute à un projet de canne intelligente un mode qui donne une courte vibration quand l'utilisateur se tourne vers le nord.
- Détecteur d'aimants et de métaux : calcule l'intensité totale du champ à partir des trois axes et fais sonner un buzzer quand la valeur augmente brusquement.
Erreurs fréquentes et solutions
| Symptôme | Cause probable | Solution |
|---|---|---|
| Erreur "No HMC5883 detected" | La carte contient une QMC5883L | Utilise le code à l'adresse 0x0D ou la bibliothèque QMC5883LCompass |
| Aucune adresse dans le scan I2C | SDA et SCL inversés, pas d'alimentation ou fil coupé | Vérifie les fils, mesure la tension sur la broche VCC |
| X, Y, Z toujours à 0 ou qui ne changent jamais | La QMC5883L est en veille au démarrage | Écris le réglage de mode continu (0x1D) dans le registre 0x09 |
| L'angle ne balaie pas les 360 degrés | Le décalage hard iron est trop grand | Fais la calibration et retire les valeurs OFF |
| L'angle diminue quand je tourne dans le sens horaire | La disposition des axes de la carte est différente | Utilise atan2(-y, x) |
| Le cap dérive quand le moteur tourne | Aimant du moteur et fils à fort courant | Éloigne le module de 15–20 cm, sur un mât |
| Le cap dérive quand je l'incline | Pas de compensation d'inclinaison | Monte le module à plat ou compense avec un MPU-6050 |
Une fois que tu as identifié la bonne puce et fait une calibration, le module boussole GY-271 est l'un des moyens les moins chers de donner un sens de l'orientation à tes projets. Pour afficher le cap, tu peux utiliser un écran LCD I2C ou OLED, et pour transformer le cap en mouvement, un servomoteur, un moteur pas à pas ou une voiture robot. Dans l'application BlueGrays, tu trouveras ces projets d'écran, de moteur et de robot avec schémas de montage et codes pas à pas, et tu pourras facilement y ajouter le module boussole.
Questions fréquentes
Mon module GY-271 contient-il une QMC5883L ou une HMC5883L ?
Le plus simple est de faire un scan I2C : si l'adresse 0x0D apparaît, c'est une QMC5883L ; si c'est 0x1E, c'est une HMC5883L. Tu peux aussi lire l'inscription sur la puce : en général DA 5883 pour la QMC5883L et L883 pour la HMC5883L. Aujourd'hui, la grande majorité des cartes GY-271 vendues contiennent une QMC5883L.
Une bibliothèque HMC5883L fonctionne-t-elle avec une QMC5883L ?
Non. Les deux puces ont des adresses I2C, des registres, un ordre d'octets et des valeurs de configuration différents ; la bibliothèque HMC cherche l'adresse 0x1E et ne trouve pas la QMC5883L. Pour la QMC5883L, tu dois utiliser une bibliothèque comme QMC5883LCompass ou un code écrit directement avec Wire.
Pourquoi ma boussole Arduino indique-t-elle un mauvais cap ?
La cause la plus fréquente est l'absence de calibration : des aimants et des pièces métalliques proches ajoutent un décalage à la mesure et peuvent faire dériver l'angle de dizaines de degrés. Un module incliné, la proximité de moteurs et de fils parcourus par du courant, ou l'oubli de la déclinaison magnétique provoquent aussi des erreurs. Monter le module à plat et le calibrer dans sa position finale ramène généralement l'erreur à quelques degrés.
Quelle est la déclinaison magnétique en France ?
En France métropolitaine, la déclinaison magnétique est faible et change lentement : elle est actuellement de l'ordre de 0 à 2 degrés vers l'est selon la région, un peu plus forte à l'est du pays. Comme la valeur évolue au fil des années, il faut consulter un calculateur de modèle magnétique récent pour obtenir un résultat précis pour ta ville.
Le module boussole GY-271 fonctionne-t-il en 5 V ?
Oui, comme la carte GY-271 possède un régulateur 3,3 V, tu peux appliquer 3–5 V sur la broche VCC et la brancher directement à un Arduino Uno. La puce elle-même fonctionne en 3,3 V ; sur l'ESP32 et le Raspberry Pi Pico, le mieux est d'alimenter la carte depuis la broche 3V3.
Le module boussole mesure-t-il correctement quand il est incliné ?
Le cap calculé uniquement avec les axes X et Y n'est juste que si le module est parallèle au sol. Comme le champ magnétique pénètre dans le sol avec une inclinaison d'environ 60 degrés sous nos latitudes, même une petite inclinaison peut décaler le cap de 10 à 15 degrés. Pour les appareils tenus à la main, il faut faire une compensation d'inclinaison avec un accéléromètre comme le MPU-6050.
Projets à réaliser après cet article
Voir tous les projets
Utilisation de l'écran LCD avec I2C
Offre un écran à ton Arduino et fais-lui écrire son premier message. L'écran LCD à deux lignes se branche avec seulement quelques fils ; un bonjour s'affiche sur la ligne du haut, puis un deuxième…

Écran LCD I2C ESP32 (16x2)
Dans ce projet, on relie un écran LCD 16x2 caractères à l'ESP32 en I2C pour afficher du texte. Grâce à l'I2C, 2 broches de données (SDA et SCL) suffisent, au lieu des 6+ broches d'un branchement parallèle classique. Le code affiche un message fixe sur la première ligne et un compteur qui augmente chaque seconde sur la deuxième. Au démarrage, un scanner I2C écrit l'adresse de l'écran dans le Serial Monitor (souvent 0x27 ou 0x3F).

ESP32 HTTPClient + API météo (avec écran OLED SSD1306)
L'ESP32 appelle par Internet une API météo (wttr.in) en REST avec HTTPClient.h. Contrairement à la version LCD I2C, on utilise ici un écran OLED SSD1306 (128×64), avec un grand texte et des icônes vectorielles pour un affichage plus riche. Sept icônes météo (soleil, pluie, neige et plus) sont dessinées à la volée, sans fichier bitmap.

Mode veille profonde de l'ESP32 — Économie de batterie (OLED + compteur RAM RTC)
Le mode Deep Sleep de l'ESP32 coupe le CPU et la plupart des périphériques et réduit la consommation à environ 10µA, un point clé pour les objets IoT sur batterie. Ce projet utilise trois sources de réveil : un minuteur (15 s), une broche externe (EXT0, le bouton sur GPIO 33) et une broche tactile (T0/GPIO 4). Les compteurs marqués RTC_DATA_ATTR sont conservés pendant le deep sleep.

Utilisation du servomoteur
Le bras d'un petit servomoteur tourne tour à tour vers trois positions : tout au début, pile au milieu et tout au bout, en attendant deux secondes à chaque arrêt.

Utilisation du moteur pas à pas
Un moteur qui tourne pas à pas, exactement autant que tu le veux, comme l'aiguille d'une horloge.

Voiture contrôlée par Bluetooth avec L298N
Transforme ton téléphone en télécommande et pilote ta propre voiture robot. L'Arduino reçoit, via un module Bluetooth, les ordres d'une appli de télécommande sur ton téléphone et fait tourner les…

Robot évitant les obstacles
Que diriez-vous de construire un véhicule intelligent qui trouve son propre chemin ?
Autres articles
Application BlueGrays
Réalise ce montage pas à pas sur ton téléphone
Schéma, code et liste des composants sur un seul écran. Plus de 500 projets Arduino, ESP32 et Pico à réaliser.
Scanne avec ton téléphone
Pointe l’appareil photo vers le code : la boutique d’applications de ton téléphone s’ouvre.
ou ouvre la boutique

