Brújula Digital Arduino: QMC5883L y HMC5883L (GY-271) Guía
¿Tu GY-271 lleva QMC5883L o HMC5883L? Direcciones I2C (0x0D, 0x1E), cálculo del rumbo, declinación, calibración y brújula OLED con Uno, ESP32 y Pico.
Un módulo de brújula para Arduino es un pequeño sensor de campo magnético que le dice a tu placa dónde está el norte. El modelo más común, el GY-271, mide el campo magnético terrestre en tres ejes; con esa medida puedes calcular el rumbo (0–360 grados) para guiar tu coche robot en una dirección concreta, mostrar una brújula digital en una pantalla OLED o añadir información de orientación a tu proyecto GPS. El módulo se conecta con solo cuatro cables por I2C y funciona con la misma lógica en Arduino Uno, ESP32 y Raspberry Pi Pico.
Pero este módulo tiene una sorpresa: la mayoría de las placas que se venden como GY-271 ya no llevan el chip HMC5883L de Honeywell, sino el QMC5883L de QST. Aunque por fuera los dos chips se ven casi iguales, sus direcciones I2C y sus registros son distintos, y por eso muchos códigos ya hechos dan el error "sensor no encontrado". En este artículo aprenderás primero a saber qué chip tiene tu placa, luego a calcular bien el rumbo, a añadir la declinación magnética y a reducir el error a unos pocos grados con la calibración.
¿Qué es un módulo de brújula digital y cómo funciona?
En el corazón del módulo hay un magnetómetro, es decir, un medidor de campo magnético. El campo magnético terrestre es bastante débil: en Turquía su intensidad total ronda los 45–50 microtesla (0,45–0,5 gauss) y su componente horizontal, paralela al suelo, unos 25 µT (1 gauss = 100 µT). El chip mide con sensores magnetorresistivos las componentes de ese campo en los ejes X, Y y Z y entrega cada una como un entero con signo. Con el módulo paralelo al suelo, para el rumbo basta con X e Y; con estas dos componentes obtienes el ángulo mediante la función atan2. El eje Z sirve para aplicaciones avanzadas como la compensación de inclinación y la detección de metales.
| Característica | QMC5883L | HMC5883L |
|---|---|---|
| Fabricante | QST | Honeywell (descatalogado) |
| Dirección I2C | 0x0D | 0x1E |
| Rango de medida | ±2 G o ±8 G | de ±0,88 G a ±8,1 G (8 escalones) |
| Resolución | 16 bits (12000 LSB/G a ±2 G, 3000 LSB/G a ±8 G) | 12 bits (1090 LSB/G a ±1,3 G) |
| Frecuencia de datos | 10, 50, 100, 200 Hz | 0,75–75 Hz (modo continuo) |
| Alimentación del chip | 2,16–3,6 V | 2,16–3,6 V |
| Alimentación de la placa GY-271 | 3–5 V (la placa lleva regulador) | 3–5 V (la placa lleva regulador) |
| Medida de temperatura | Sí (valor relativo) | No |
¿QMC5883L o HMC5883L? Cómo distinguir los dos chips
Durante muchos años el HMC5883L fue el chip de brújula estándar de la electrónica aficionada. Cuando Honeywell dejó de fabricarlo, el mercado se llenó con el QMC5883L de QST. Como los vendedores casi nunca cambian el nombre del producto, es muy normal que una placa comprada como "HMC5883L" lleve en realidad un QMC5883L. La forma más segura de distinguirlos es un escaneo I2C: si en el bus aparece la dirección 0x0D, es un QMC5883L; si aparece 0x1E, es un HMC5883L. También sirve leer con una lupa la serigrafía del chip. Últimamente algunas placas llevan además un QMC5883P con dirección 0x2C; su mapa de registros es distinto, así que el código de este artículo no funciona directamente con él.
| Método | QMC5883L | HMC5883L |
|---|---|---|
| Dirección I2C | 0x0D | 0x1E |
| Marcado en el chip | DA 5883 | L883 |
| Registro de identificación | El registro 0x0D devuelve 0xFF | Los registros 0x0A–0x0C devuelven 'H', '4', '3' |
| Registros de datos | 0x00–0x05 (en orden X, Y, Z) | 0x03–0x08 (en orden X, Z, Y) |
| Orden de bytes | Primero el byte bajo (LSB) | Primero el byte alto (MSB) |
| Modo al arrancar | En espera (standby), no mide | Modo de medida única |
| Librería habitual | QMC5883LCompass | Adafruit HMC5883 Unified |
Conexión del GY-271: Uno, ESP32 y Pico
| Pin del 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 | Sin conectar | Sin conectar | Sin conectar |
La placa GY-271 incluye un regulador de 3,3 V y resistencias pull-up para las líneas I2C, así que en el Uno es seguro alimentar el módulo desde el pin de 5V. En el ESP32 y la Pico alimenta la placa desde el pin 3V3 para que SDA y SCL se mantengan a 3,3 V. El pin DRDY (dato listo) emite una señal con cada nueva medida; puedes dejarlo libre si no vas a leer por interrupción. La brújula puede compartir el bus con otros dispositivos I2C como una pantalla OLED (0x3C) o un MPU-6050 (0x68), porque sus direcciones no chocan. Para más detalles sobre direcciones y pull-ups, consulta el artículo Qué es I2C.
Paso a paso: la primera lectura de rumbo (Arduino Uno)
- Pon el módulo en la protoboard; si es posible, mantenlo al menos a 15–20 cm de motores, altavoces, imanes y piezas grandes de acero.
- Conecta VCC, GND, SCL y SDA como en la tabla y deja el pin DRDY libre.
- Sube el código de abajo; no hace falta ninguna librería extra, solo la librería Wire del propio Arduino.
- Abre el Monitor Serie a 9600 baudios; en la primera línea verás qué chip ha encontrado el código.
- Pon el módulo plano sobre la mesa y gíralo despacio sobre sí mismo; observa cómo X e Y oscilan entre valores positivos y negativos y cómo el ángulo avanza de 0 a 360.
- Si la brújula de tu móvil indica el norte real, apunta la flecha X del módulo hacia ese norte; el ángulo debería acercarse a 0. Antes de calibrar es normal una desviación de 10–30 grados.
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}| Código / registro | Valor | Significado |
|---|---|---|
| QMC 0x0B | 0x01 | Periodo SET/RESET; valor recomendado por la hoja de datos |
| QMC 0x09 | 0x1D | OSR 512, rango ±8 G, 200 Hz, medida continua (0x0D para ±2 G) |
| HMC 0x00 | 0x70 | Promedio de 8 medidas, frecuencia de datos de 15 Hz |
| HMC 0x01 | 0x20 | Rango ±1,3 Ga, sensibilidad de 1090 LSB/Ga |
| HMC 0x02 | 0x00 | Modo de medida continua |
| Wire.endTransmission() == 0 | - | Si la dirección responde, el dispositivo está en el bus |
| atan2(y, x) × 180 / π | - | Ángulo entre −180 y +180 grados a partir de los ejes en bruto |
¿Cómo se calcula el rumbo?
Con el módulo plano, el campo magnético horizontal de la Tierra se reparte entre los ejes X e Y. Cuando apuntas la flecha X hacia el norte, todo el campo cae sobre el eje X y Y se acerca a cero; al girar el módulo, el reparto pasa al eje Y. El rumbo se obtiene con la fórmula θ = atan2(Y, X). Se usa atan2 en lugar del simple atan(Y/X) porque atan2 mira el signo de los dos valores y distingue los cuatro cuadrantes, y además no da error de división por cero cuando X vale cero. El resultado llega en radianes entre −180 y +180 grados; lo multiplicas por 180/π para pasarlo a grados y, si es negativo, sumas 360. Cada una de las ocho direcciones principales ocupa un sector de 45 grados: de 337,5 a 22,5 grados es Norte (N), de 22,5 a 67,5 es Noreste (NE), y así sucesivamente; la operación (ángulo + 22,5) / 45 del código elige el sector correcto. Si al girar el módulo en sentido horario el ángulo disminuye en vez de aumentar, la disposición de ejes de tu placa es distinta; cambiar el signo de Y y usar atan2(-y, x) lo soluciona.
¿Qué es la declinación magnética?
La aguja de la brújula no señala el norte geográfico (verdadero), sino el norte magnético. El ángulo entre ambos se llama declinación magnética y varía según el lugar y el año. En Turquía la declinación es hacia el este y hoy ronda los +5 grados en las provincias del oeste y los +7 grados en las del este; para Estambul y Ankara, 6 grados es un buen punto de partida. La corrección es sencilla: rumbo verdadero = rumbo magnético + declinación; la declinación este se escribe positiva y la oeste negativa. Basta con consultar el valor actual de tu zona en la calculadora del modelo magnético de la NOAA o de un organismo similar y escribirlo en la constante DECLINATION del código. Si te dan el valor en grados y minutos, pásalo a decimal: 5° 48' = 5 + 48/60 = 5,8 grados. Como la declinación se desplaza unos minutos de arco al año, conviene revisarla cada pocos años.
Calibración de la brújula: hard iron y soft iron
Una brújula sin calibrar puede equivocarse entre 20 y 40 grados, sobre todo en la primera prueba. Hay dos causas. En el efecto hard iron (hierro duro), imanes permanentes cercanos, tornillos magnetizados o componentes de la placa suman un valor fijo a cada medida; si dibujas X–Y mientras giras el módulo, verás que el centro del círculo se desplaza respecto al cero. En el efecto soft iron (hierro blando), materiales cercanos como el hierro y el níquel deforman el campo y convierten el círculo en una elipse. La solución es sencilla: con el módulo plano en su posición final dentro del proyecto, lo giras despacio dos o tres vueltas y vas guardando el valor mínimo y el máximo de cada eje. Offset = (máx + mín) / 2 corrige el hard iron, y escala = radio medio / radio del eje da una corrección sencilla del soft iron. El código siguiente es para el QMC5883L, que llevan la mayoría de las placas; si usas un HMC5883L, solo tienes que cambiar la función de lectura por la parte HMC del primer código.
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}El código escribe cada segundo los valores OFF y SCALE; sigue girando hasta que los números dejen de cambiar. Por ejemplo, si en X mides un mínimo de −680 y un máximo de 920, el offset es (920 + (−680)) / 2 = 120 y el radio 800. Si en Y el mínimo es −1010 y el máximo 550, el offset es −230 y el radio 780. Como el radio medio es 790, las escalas salen 790 / 800 ≈ 0,988 y 790 / 780 ≈ 1,013. En el código principal corriges cada lectura en bruto así: x = (x_bruto − OFF_X) × SCALE_X; en el ejemplo de ESP32 de abajo estos valores ya están escritos. Como en el rango ±8 G un gauss equivale a 3000 cuentas, un radio de 800 corresponde a un campo horizontal de unos 0,27 G, lo cual concuerda con lo esperado para Turquía. Si trasladas el módulo a otro sitio o añades cerca una pieza metálica nueva, repite la calibración.
Brújula con pantalla OLED y ESP32

En el ESP32 funciona el mismo código con Wire; los pines I2C son GPIO 21 (SDA) y GPIO 22 (SCL), y la brújula y la pantalla OLED de 0,96 pulgadas se conectan al mismo bus. El código aplica los valores de calibración, suaviza X e Y con un sencillo filtro paso bajo, y muestra a la izquierda una aguja de brújula que gira y a la derecha los grados y la letra de la dirección. El filtro se aplica a los ejes y no al ángulo para evitar que, en el salto entre 359 y 0 grados, el promedio de los ángulos salga erróneamente cerca de 180. La pequeña marca de la parte superior de la pantalla indica el frente del dispositivo y la aguja señala el norte; al girar tú el dispositivo, la aguja gira en sentido contrario, igual que una brújula real. Para instalar las librerías de la pantalla, consulta el artículo Pantalla 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}Brújula con Raspberry Pi Pico y MicroPython
En la Pico basta con la clase machine.I2C de MicroPython; no hace falta ningún archivo de controlador aparte. El código lista primero con i2c.scan() las direcciones del bus, escribe la configuración según el chip que encuentra y lee los seis bytes de una vez con readfrom_mem. Como en MicroPython los bytes llegan sin signo, tienes que convertir a negativo los valores mayores de 32767 restándoles 65536. Para la calibración, escribe en las constantes del código los valores OFF y SCALE que obtuviste en Arduino. Si estás empezando con MicroPython, los artículos Fundamentos de MicroPython y Qué es la Raspberry Pi Pico son un buen comienzo.
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)Compensación de inclinación: por qué el módulo debe estar plano
El rumbo calculado solo con los ejes X e Y es correcto cuando el módulo está paralelo al suelo. En latitudes medias como las de Turquía, el campo magnético entra en el suelo con una inclinación de unos 55–60 grados, por lo que la componente vertical (Z) es claramente mayor que la horizontal. Si inclinas el módulo 10 grados, parte de la componente Z se mezcla con X o Y y el rumbo puede desviarse hasta 15 grados. En dispositivos de mano o que se balancean, la solución es la compensación de inclinación: con un acelerómetro MPU-6050 obtienes los ángulos de alabeo (roll) y cabeceo (pitch) y giras los valores del magnetómetro al plano horizontal. En proyectos sencillos, como un coche robot o una caja fija, normalmente basta con montar el módulo plano y firme en el chasis.
Ideas de proyectos con el módulo de brújula
- Coche robot que mantiene el rumbo: enseña a tu coche robot a girar hasta un ángulo determinado y a ir recto; coloca el módulo lejos de los motores, en un mástil de plástico.
- Guiado hacia un destino con GPS: calcula con el GPS NEO-6M el rumbo hacia el destino y muestra la diferencia con la brújula como una flecha en pantalla.
- Brújula con aguja de servo: haz girar el brazo de un servomotor para que apunte siempre al norte, por mucho que gires la caja.
- Buscador de la dirección de La Meca (alquibla): escribe en el código el ángulo de la alquibla de tu ciudad y haz que la flecha de la OLED gire según ese ángulo en lugar del norte.
- Orientación de paneles solares: comprueba con la brújula si el panel mira en la dirección correcta en un sistema de seguimiento solar.
- Bastón que indica la dirección: añade al proyecto de bastón inteligente un modo que dé una vibración corta cuando el usuario se gire hacia el norte.
- Detector de imanes y metales: calcula la intensidad total del campo con los tres ejes y haz sonar un zumbador cuando el valor suba de golpe.
Errores frecuentes y cómo solucionarlos
| Síntoma | Causa probable | Solución |
|---|---|---|
| Error "No HMC5883 detected" | La placa lleva un QMC5883L | Usa el código con dirección 0x0D o la librería QMC5883LCompass |
| No aparece ninguna dirección en el escaneo I2C | SDA y SCL invertidos, sin alimentación o cable roto | Revisa los cables y mide la tensión en el pin VCC |
| X, Y, Z siempre a 0 o sin cambiar | El QMC5883L arranca en modo de espera | Escribe la configuración de modo continuo (0x1D) en el registro 0x09 |
| El ángulo no recorre los 360 grados completos | El offset hard iron es demasiado grande | Calibra y resta los valores OFF |
| Al girar en sentido horario el ángulo disminuye | La disposición de ejes de la placa es distinta | Usa atan2(-y, x) |
| El rumbo se desvía cuando funciona el motor | Imán del motor y cables de alta corriente | Aleja el módulo 15–20 cm, a un mástil |
| El rumbo se desvía al inclinar | No hay compensación de inclinación | Monta el módulo plano o compensa con un MPU-6050 |
Una vez que has reconocido el chip correcto y lo has calibrado, el módulo de brújula GY-271 es una de las formas más baratas de dar sentido de orientación a tus proyectos. Para mostrar el rumbo puedes usar una pantalla LCD I2C u OLED, y para convertirlo en movimiento un servo, un motor paso a paso o un coche robot. En la app de BlueGrays encontrarás paso a paso estos proyectos de pantallas, motores y robots, con esquemas y códigos, y podrás añadirles fácilmente el módulo de brújula.
Preguntas frecuentes
¿Mi módulo GY-271 lleva un QMC5883L o un HMC5883L?
Lo más fácil es hacer un escaneo I2C: si aparece la dirección 0x0D es un QMC5883L, y si aparece 0x1E es un HMC5883L. También puedes mirar el marcado del chip: el QMC5883L suele llevar DA 5883 y el HMC5883L, L883. Hoy en día la inmensa mayoría de las placas GY-271 que se venden llevan el QMC5883L.
¿Funciona una librería de HMC5883L con el QMC5883L?
No. Los dos chips tienen distinta dirección I2C, distintos registros, distinto orden de bytes y distintos valores de configuración; la librería HMC busca la dirección 0x1E y no encuentra el QMC5883L. Para el QMC5883L debes usar una librería como QMC5883LCompass o un código escrito directamente con Wire.
¿Por qué mi módulo de brújula para Arduino marca mal el rumbo?
La causa más habitual es no haber calibrado; los imanes y las piezas metálicas cercanas suman un offset a la medida y pueden desviar el ángulo decenas de grados. También influyen que el módulo esté inclinado, la cercanía de motores y cables con corriente, y no haber añadido la declinación magnética. Montar el módulo plano y calibrarlo en su posición final suele reducir el error a unos pocos grados.
¿Cuántos grados de declinación magnética hay en Turquía?
En Turquía la declinación magnética es hacia el este y hoy ronda entre 5 y 7 grados; es menor en las provincias del oeste y mayor en las del este. Para Estambul y Ankara se pueden usar unos 6 grados. Como el valor cambia lentamente con los años, para un resultado exacto hay que consultar una calculadora actualizada del modelo magnético.
¿Funciona el módulo de brújula GY-271 con 5 V?
Sí. Como la placa GY-271 lleva un regulador de 3,3 V, al pin VCC se le pueden dar entre 3 y 5 V y la placa se puede conectar directamente a un Arduino Uno. El chip en sí funciona a 3,3 V; en el ESP32 y la Raspberry Pi Pico lo más correcto es alimentar la placa desde el pin 3V3.
¿Mide bien el módulo de brújula si se sostiene inclinado?
El rumbo calculado solo con los ejes X e Y es correcto cuando el módulo está paralelo al suelo. Como en Turquía el campo magnético entra en el suelo con una inclinación de unos 55–60 grados, incluso una pequeña inclinación puede desviar el rumbo 10–15 grados. En dispositivos de mano hay que compensar la inclinación con un acelerómetro como el MPU-6050.
Proyectos para hacer después de leer esto
Ver todos los proyectos
Uso de la pantalla LCD con I2C
Dale a tu Arduino su propia pantalla y haz que escriba su primer mensaje. La pantalla LCD de dos líneas se conecta con solo unos pocos cables; primero aparece un saludo en la línea de arriba, luego…

Pantalla LCD I2C para ESP32 (16x2)
En este proyecto conectamos una pantalla LCD de caracteres 16x2 al ESP32 por I2C para mostrar texto. Con I2C bastan 2 pines de datos (SDA y SCL), en lugar de los 6+ pines de una conexión paralela clásica. El código escribe un mensaje fijo en la primera línea y un contador que sube cada segundo en la segunda. Al arrancar, un escáner I2C muestra la dirección de la pantalla en el Serial Monitor (normalmente 0x27 o 0x3F).

ESP32 HTTPClient + API del tiempo (con pantalla OLED SSD1306)
El ESP32 hace una llamada REST por internet a una API del tiempo (wttr.in) con HTTPClient.h. A diferencia de la versión con LCD I2C, aquí usamos una pantalla OLED SSD1306 (128×64), con letra grande e iconos vectoriales para una vista más rica. Siete iconos del tiempo (soleado, lluvia, nieve y más) se dibujan al momento, sin archivos bitmap.

Modo de suspensión profunda del ESP32 — Ahorro de batería (OLED + contador en RTC RAM)
El modo Deep Sleep del ESP32 apaga la CPU y la mayoría de los periféricos y reduce el consumo a unos 10µA, algo clave para dispositivos IoT con batería. Este proyecto usa tres fuentes de activación: un temporizador (15 s), un pin externo (EXT0, el botón en GPIO 33) y un pin táctil (T0/GPIO 4). Los contadores marcados con RTC_DATA_ATTR se conservan durante el deep sleep.

Uso del servomotor
El brazo de un pequeño servomotor gira por turnos a tres posiciones: al principio del todo, justo al centro y al final del todo, esperando dos segundos en cada parada.

Uso del motor paso a paso
Un motor que gira paso a paso, justo lo que tú quieras, como la aguja de un reloj.

Coche controlado por Bluetooth con L298N
Convierte tu móvil en un mando y conduce tu propio coche robot. El Arduino recibe por un módulo Bluetooth las órdenes de una app de control remoto en el móvil y mueve las ruedas con un controlador de…

Robot para evitar obstáculos
¿Qué le parece construir un vehículo inteligente que encuentre su propio camino? El Robot Evitador de Obstáculos explora constantemente su entorno gracias al sensor ultrasónico que lleva delante.
Más artículos
App BlueGrays
Monta este circuito paso a paso en tu teléfono
Esquema, código y lista de piezas en una sola pantalla. Más de 500 proyectos de Arduino, ESP32 y Pico listos para montar.
Escanea con tu teléfono
Apunta la cámara al código y se abrirá la tienda de apps de tu teléfono.
o ábrela en la tienda

