Componentes · 11 min de leitura

Módulo bússola para Arduino: guia do QMC5883L e HMC5883L (GY-271)

Seu GY-271 é QMC5883L ou HMC5883L? Endereços I2C (0x0D, 0x1E), direção com atan2, declinação, calibração e bússola em OLED, com código para Uno, ESP32 e Pico.

Um módulo bússola para Arduino é um pequeno sensor de campo magnético que informa à sua placa onde fica o norte. O modelo mais comum, o GY-271, mede o campo magnético da Terra em três eixos. A partir disso, você pode calcular a direção (0–360 graus) para guiar seu carrinho robô em um rumo definido, mostrar uma bússola digital em um display OLED ou acrescentar a direção ao seu projeto com GPS. O módulo se conecta com apenas quatro fios via I2C e funciona do mesmo jeito com Arduino Uno, ESP32 e Raspberry Pi Pico.

Mas este módulo guarda uma surpresa: a maioria das placas vendidas como GY-271 já não traz o chip HMC5883L da Honeywell, e sim o QMC5883L da QST. Os dois chips parecem quase idênticos por fora, mas os endereços I2C e os registradores são diferentes. Por isso, muitos sketches prontos dão “sensor não encontrado”. Neste post, você vai aprender a descobrir qual chip a sua placa tem, calcular a direção corretamente, somar a declinação magnética e reduzir o erro para poucos graus com a calibração.

O que é um módulo bússola digital e como ele funciona?

O coração do módulo é um magnetômetro, um sensor que mede campos magnéticos. O campo da Terra é bem fraco: na Turquia, a intensidade total fica em torno de 45–50 microtesla (0,45–0,5 gauss), e a componente horizontal, paralela ao chão, fica perto de 25 µT (1 gauss = 100 µT). O chip usa sensores magnetorresistivos para medir as componentes X, Y e Z do campo e entrega cada uma como um número inteiro com sinal. Com o módulo nivelado, X e Y bastam para achar a direção; o ângulo vem desses dois valores com a função atan2. O eixo Z é útil em aplicações avançadas, como compensação de inclinação e detecção de metais.

CaracterísticaQMC5883LHMC5883L
FabricanteQSTHoneywell (fora de produção)
Endereço I2C0x0D0x1E
Faixa de medição±2 G ou ±8 G±0,88 G a ±8,1 G (8 níveis)
Resolução16 bits (12000 LSB/G em ±2 G, 3000 LSB/G em ±8 G)12 bits (1090 LSB/G em ±1,3 G)
Taxa de dados10, 50, 100, 200 Hz0,75–75 Hz (modo contínuo)
Alimentação do chip2,16–3,6 V2,16–3,6 V
Alimentação da placa GY-2713–5 V (regulador na placa)3–5 V (regulador na placa)
Leitura de temperaturaSim (valor relativo)Não

QMC5883L ou HMC5883L? Como diferenciar os dois chips

Por muitos anos, o HMC5883L foi o chip de bússola padrão na eletrônica hobby. Quando a Honeywell parou a produção, o QMC5883L da QST tomou conta do mercado. Como os vendedores muitas vezes não mudam o nome do produto, é totalmente normal encontrar um QMC5883L em uma placa comprada como “HMC5883L”. O jeito mais seguro de saber é uma varredura I2C: se aparecer o endereço 0x0D no barramento, é um QMC5883L; se aparecer 0x1E, é um HMC5883L. Ler a marcação do chip com uma lupa também ajuda. Ultimamente, algumas placas trazem um QMC5883P no endereço 0x2C; o mapa de registradores dele é diferente, então o código deste post não funciona diretamente com ele.

MétodoQMC5883LHMC5883L
Endereço I2C0x0D0x1E
Marcação no chipDA 5883L883
Registrador de identificaçãoO registrador 0x0D retorna 0xFFOs registradores 0x0A–0x0C retornam 'H', '4', '3'
Registradores de dados0x00–0x05 (X, Y, Z, nessa ordem)0x03–0x08 (X, Z, Y, nessa ordem)
Ordem dos bytesByte baixo primeiro (LSB)Byte alto primeiro (MSB)
Modo ao ligarStandby, não medeModo de medição única
Biblioteca comumQMC5883LCompassAdafruit HMC5883 Unified
Bibliotecas para HMC, como a Adafruit HMC5883 Unified, procuram apenas o endereço 0x1E. Se a sua placa tiver um QMC5883L, você vai receber uma mensagem como “no HMC5883 detected” e achar que o módulo está com defeito. Não está; o chip é que é outro. Faça primeiro uma varredura I2C e depois use um código que converse com o endereço certo.

Ligação do GY-271: Uno, ESP32 e Pico

Pino do GY-271Arduino UnoESP32Raspberry Pi Pico
VCC5V (ou 3.3V)3V33V3 (pino 36)
GNDGNDGNDGND
SCLA5GPIO 22GP5 (pino 7)
SDAA4GPIO 21GP4 (pino 6)
DRDYNão conectadoNão conectadoNão conectado

A placa GY-271 tem um regulador de 3,3 V e resistores de pull-up nas linhas I2C, então é seguro alimentar o módulo pelo pino 5V do Uno. No ESP32 e no Pico, alimente a placa pelo pino 3V3 para que SDA e SCL fiquem em 3,3 V. O pino DRDY (dado pronto) sinaliza cada nova medição; você pode deixá-lo livre se não for ler por interrupção. A bússola pode dividir o mesmo barramento com outros dispositivos I2C, como um display OLED (0x3C) ou um MPU-6050 (0x68), porque os endereços não se chocam. Para detalhes sobre endereços e pull-ups, veja O que é I2C.

Passo a passo: sua primeira leitura de direção (Arduino Uno)

  1. Encaixe o módulo na protoboard e, se possível, deixe-o a pelo menos 15–20 cm de motores, alto-falantes, ímãs e peças grandes de aço.
  2. Ligue os fios VCC, GND, SCL e SDA como na tabela e deixe o pino DRDY livre.
  3. Carregue o código abaixo; não é preciso nenhuma biblioteca extra, só a biblioteca Wire do próprio Arduino.
  4. Abra o Monitor Serial em 9600 baud; a primeira linha mostra qual chip o código encontrou.
  5. Coloque o módulo deitado na mesa e gire-o devagar; observe os valores de X e Y oscilarem entre positivo e negativo e o ângulo ir de 0 a 360.
  6. Se a bússola do seu celular estiver configurada para mostrar o norte verdadeiro, aponte a seta X do módulo para esse norte; o ângulo deve se aproximar de 0. Um erro de 10–30 graus antes da calibração é normal.
C++ (Arduino IDE)
1#include <Wire.h>
2#include <math.h>
3
4const uint8_t QMC_ADDR = 0x0D;   // QMC5883L adresi / QMC5883L address
5const uint8_t HMC_ADDR = 0x1E;   // HMC5883L adresi / HMC5883L address
6const float DECLINATION = 6.0;   // manyetik sapma, doğu + / magnetic declination, east +
7
8uint8_t chipAddr = 0;
9
10bool devicePresent(uint8_t addr) {
11  Wire.beginTransmission(addr);
12  return Wire.endTransmission() == 0;   // 0 = cihaz cevap verdi / 0 = device acknowledged
13}
14
15void writeReg(uint8_t addr, uint8_t reg, uint8_t val) {
16  Wire.beginTransmission(addr);
17  Wire.write(reg);
18  Wire.write(val);
19  Wire.endTransmission();
20}
21
22bool readAxes(int16_t &x, int16_t &y, int16_t &z) {
23  uint8_t startReg = (chipAddr == QMC_ADDR) ? 0x00 : 0x03;
24  Wire.beginTransmission(chipAddr);
25  Wire.write(startReg);
26  if (Wire.endTransmission() != 0) return false;
27  if (Wire.requestFrom(chipAddr, (uint8_t)6) != 6) return false;
28  uint8_t b[6];
29  for (uint8_t i = 0; i < 6; i++) b[i] = Wire.read();
30  if (chipAddr == QMC_ADDR) {          // X, Y, Z; önce düşük bayt / LSB first
31    x = (int16_t)((uint16_t)b[1] << 8 | b[0]);
32    y = (int16_t)((uint16_t)b[3] << 8 | b[2]);
33    z = (int16_t)((uint16_t)b[5] << 8 | b[4]);
34  } else {                             // X, Z, Y; önce yüksek bayt / MSB first
35    x = (int16_t)((uint16_t)b[0] << 8 | b[1]);
36    z = (int16_t)((uint16_t)b[2] << 8 | b[3]);
37    y = (int16_t)((uint16_t)b[4] << 8 | b[5]);
38  }
39  return true;
40}
41
42const char* directionName(float h) {
43  static const char* const names[] = {"K", "KD", "D", "GD", "G", "GB", "B", "KB"};
44  return names[(int)((h + 22.5) / 45.0) % 8];   // 45 derecelik dilimler / 45 degree sectors
45}
46
47void setup() {
48  Serial.begin(9600);
49  Wire.begin();
50  if (devicePresent(QMC_ADDR)) {
51    chipAddr = QMC_ADDR;
52    writeReg(QMC_ADDR, 0x0B, 0x01);   // SET/RESET periyodu / SET/RESET period
53    writeReg(QMC_ADDR, 0x09, 0x1D);   // sürekli, 200 Hz, ±8 G, OSR 512 / continuous, 200 Hz, ±8 G, OSR 512
54    Serial.println(F("QMC5883L bulundu (0x0D)"));
55  } else if (devicePresent(HMC_ADDR)) {
56    chipAddr = HMC_ADDR;
57    writeReg(HMC_ADDR, 0x00, 0x70);   // 8 örnek ortalama, 15 Hz / 8-sample average, 15 Hz
58    writeReg(HMC_ADDR, 0x01, 0x20);   // ±1,3 Ga kazanç / ±1.3 Ga gain
59    writeReg(HMC_ADDR, 0x02, 0x00);   // sürekli ölçüm / continuous measurement
60    Serial.println(F("HMC5883L bulundu (0x1E)"));
61  } else {
62    Serial.println(F("Pusula bulunamadi / Compass not found"));
63    while (true) {}
64  }
65}
66
67void loop() {
68  int16_t x, y, z;
69  if (readAxes(x, y, z)) {
70    float heading = atan2((float)y, (float)x) * 180.0 / PI;   // radyandan dereceye / radians to degrees
71    heading += DECLINATION;
72    if (heading < 0) heading += 360.0;
73    if (heading >= 360.0) heading -= 360.0;
74    Serial.print(F("X: ")); Serial.print(x);
75    Serial.print(F("  Y: ")); Serial.print(y);
76    Serial.print(F("  Z: ")); Serial.print(z);
77    Serial.print(F("  Yon: ")); Serial.print(heading, 1);
78    Serial.print(F(" derece "));
79    Serial.println(directionName(heading));
80  }
81  delay(250);
82}
Código / registradorValorSignificado
QMC 0x0B0x01Período de SET/RESET; o valor recomendado pelo datasheet
QMC 0x090x1DOSR 512, faixa de ±8 G, 200 Hz, medição contínua (0x0D para ±2 G)
HMC 0x000x70Média de 8 medições, taxa de dados de 15 Hz
HMC 0x010x20Faixa de ±1,3 Ga, sensibilidade de 1090 LSB/Ga
HMC 0x020x00Modo de medição contínua
Wire.endTransmission() == 0 (teste de presença)-Se o endereço respondeu, o dispositivo está no barramento
atan2(y, x) × 180 / π (ângulo em graus)-Ângulo de −180 a +180 graus a partir dos eixos brutos

Como a direção é calculada?

Com o módulo nivelado, o campo magnético horizontal da Terra se divide entre os eixos X e Y. Quando você aponta a seta X para o norte, todo o campo cai em X e Y se aproxima de zero; conforme você gira o módulo, a parcela passa para Y. A direção é dada por θ = atan2(Y, X). Usamos atan2 em vez de um simples atan(Y/X) porque o atan2 olha o sinal dos dois valores para distinguir os quatro quadrantes e não divide por zero quando X é zero. O resultado sai em radianos, entre −180 e +180 graus; multiplique por 180/π para converter em graus e some 360 se for negativo. Cada uma das oito direções principais ocupa um setor de 45 graus: de 337,5 a 22,5 graus é Norte (N), de 22,5 a 67,5 é Nordeste (NE), e assim por diante; a operação (ângulo + 22,5) / 45 no código escolhe o setor certo. Se o ângulo diminuir quando você gira o módulo no sentido horário, a disposição dos eixos da sua placa é diferente; inverta o sinal de Y e use atan2(-y, x) para corrigir.

O que é declinação magnética?

A agulha de uma bússola aponta para o norte magnético, não para o norte geográfico (verdadeiro). O ângulo entre os dois se chama declinação magnética e muda conforme o local e o ano. Na Turquia, a declinação é para leste e hoje fica em torno de +5 graus nas províncias do oeste e de +7 graus no leste; 6 graus é um bom ponto de partida para Istambul e Ancara. A fórmula de correção é simples: direção verdadeira = direção magnética + declinação, com leste positivo e oeste negativo. Basta consultar o valor atual da sua localização na calculadora de modelo magnético da NOAA ou de um órgão semelhante e escrevê-lo na constante DECLINATION do código. Se encontrar o valor em graus e minutos, converta para decimal: 5° 48' = 5 + 48/60 = 5,8 graus. A declinação varia alguns minutos de arco por ano, então vale conferir a cada poucos anos.

Calibração da bússola: hard iron e soft iron

Uma bússola sem calibração pode errar 20–40 graus, principalmente na primeira tentativa. Há duas causas. No efeito hard iron (ferro duro), ímãs permanentes perto do módulo, parafusos magnetizados ou componentes da placa somam um valor constante a cada leitura; se você plotar os valores X–Y enquanto gira o módulo, verá o centro do círculo deslocado do zero. No efeito soft iron (ferro doce), materiais próximos como ferro e níquel distorcem o campo e transformam o círculo em uma elipse. A solução é simples: segure o módulo nivelado na posição final que ele terá no projeto, gire-o devagar por duas ou três voltas e registre o mínimo e o máximo de cada eixo. Offset = (max + min) / 2 dá a correção de hard iron, e escala = raio médio / raio do eixo dá uma correção simples de soft iron. O código abaixo é para o QMC5883L, presente na maioria das placas; se você usa um HMC5883L, basta trocar a função de leitura pela parte do HMC do primeiro sketch.

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

O código imprime os valores de OFF e SCALE a cada segundo; continue girando até os números pararem de mudar. Por exemplo, se você mediu mínimo de −680 e máximo de 920 em X, o offset é (920 + (−680)) / 2 = 120 e o raio é 800. Se Y tem mínimo de −1010 e máximo de 550, o offset é −230 e o raio é 780. Como o raio médio é 790, as escalas ficam 790 / 800 ≈ 0,988 e 790 / 780 ≈ 1,013. No código principal, você corrige cada leitura bruta como x = (bruto_x − OFF_X) × SCALE_X; no exemplo do ESP32 abaixo, esses valores já estão preenchidos. Como 1 gauss equivale a 3000 contagens na faixa de ±8 G, um raio de 800 significa um campo horizontal de cerca de 0,27 G, o que bate com o esperado para a Turquia. Se você mudar o módulo de lugar ou colocar uma nova peça metálica por perto, repita a calibração.

Bússola em um display OLED com o ESP32

Display OLED I2C de 0,96 polegada
O display OLED I2C de 0,96 polegada (0x3C) divide o mesmo barramento I2C com o módulo bússola (0x0D) sem nenhum problema.

O mesmo código com Wire funciona no ESP32; os pinos I2C são GPIO 21 (SDA) e GPIO 22 (SCL), e a bússola e o display OLED de 0,96 polegada se ligam ao mesmo barramento. O código aplica os valores de calibração, suaviza X e Y com um filtro passa-baixa simples e mostra uma agulha de bússola girando à esquerda da tela e os graus e a letra da direção à direita. Aplicamos o filtro aos eixos, e não ao ângulo, para que a média de ângulos na virada de 359 para 0 grau não dê erradamente algo perto de 180. O tracinho no alto da tela marca a frente do dispositivo e a agulha aponta para o norte; quando você gira o dispositivo, a agulha gira no sentido oposto, como uma bússola de verdade. Para instalar as bibliotecas do display, veja 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}

Bússola em MicroPython com o Raspberry Pi Pico

No Pico, a classe machine.I2C do MicroPython é suficiente; não é preciso nenhum arquivo de driver separado. O código primeiro lista os endereços do barramento com i2c.scan(), escreve as configurações para o chip que encontrar e lê seis bytes de uma vez com readfrom_mem. Como os bytes chegam sem sinal no MicroPython, é preciso subtrair 65536 dos valores acima de 32767 para transformá-los em números negativos. Para a calibração, basta colocar nas constantes do código os valores de OFF e SCALE que você encontrou no Arduino. Se você está começando com MicroPython, Fundamentos de MicroPython e O que é o Raspberry Pi Pico são bons pontos de partida.

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)

Compensação de inclinação: por que o módulo precisa ficar nivelado?

Uma direção calculada só com os eixos X e Y está correta apenas enquanto o módulo estiver paralelo ao chão. Em latitudes médias como a da Turquia, o campo magnético entra no solo com uma inclinação de cerca de 55–60 graus, então a componente vertical (Z) é claramente maior que a horizontal. Quando o módulo inclina 10 graus, parte da componente Z vaza para X ou Y e a direção pode desviar com um erro de até 15 graus. Em dispositivos de mão ou que balançam, a solução é a compensação de inclinação: você obtém os ângulos de roll (rolagem) e pitch (arfagem) com um acelerômetro MPU-6050 e rotaciona os valores do magnetômetro para o plano horizontal. Em projetos simples, como um carrinho robô ou uma caixa fixa, muitas vezes basta montar o módulo nivelado e bem firme na estrutura.

Ideias de projetos com o módulo bússola

  • Carrinho robô que mantém o rumo: ensine seu carrinho robô a virar para um ângulo definido e andar em linha reta; monte o módulo em uma haste de plástico, longe dos motores.
  • Navegação GPS até um alvo: calcule o rumo até o alvo com um GPS NEO-6M e mostre a diferença em relação à bússola como uma seta no display.
  • Bússola com ponteiro servo: gire o braço de um servo motor para que ele sempre aponte para o norte, não importa como você gire a caixa.
  • Localizador da qibla: escreva no código o ângulo da qibla da sua cidade e gire a seta no OLED de acordo com esse ângulo em vez do norte.
  • Orientação de painel solar: use a bússola para conferir se o painel está voltado para a direção certa em um sistema seguidor solar.
  • Bengala que indica a direção: acrescente ao projeto da bengala inteligente um modo que dá uma vibração curta quando o usuário fica de frente para o norte.
  • Detector de ímãs e metais: calcule a intensidade total do campo a partir dos três eixos e acione um buzzer quando o valor subir de repente.

Erros comuns e como corrigir

SintomaCausa provávelSolução
Erro “No HMC5883 detected”A placa tem um QMC5883LUse um código para o endereço 0x0D ou a biblioteca QMC5883LCompass
Nenhum endereço na varredura I2CSDA e SCL invertidos, sem alimentação ou fio rompidoConfira os fios e meça a tensão no pino VCC
X, Y, Z sempre 0 ou nunca mudamO QMC5883L fica em standby ao ligarEscreva a configuração de modo contínuo (0x1D) no registrador 0x09
O ângulo não percorre os 360 graus completosO offset de hard iron é grande demaisCalibre e subtraia os valores de OFF
O ângulo diminui ao girar no sentido horárioA disposição dos eixos da placa é diferenteUse atan2(-y, x)
A direção desvia quando o motor funcionaÍmãs do motor e fios de alta correnteAfaste o módulo 15–20 cm, em uma haste
A direção erra quando o módulo inclinaSem compensação de inclinaçãoMonte o módulo nivelado ou compense com um MPU-6050
Durante os testes, até uma mesa de metal, o alto-falante de um notebook, um celular ou o anel de ferrite de um cabo USB podem desviar a leitura. Faça a calibração e os testes na posição final e com a fiação final que o módulo terá no projeto; uma bússola perfeitamente calibrada na mesa pode voltar a desviar depois de colocada dentro do robô.

Depois de identificar o chip certo e calibrá-lo, o módulo bússola GY-271 é um dos jeitos mais baratos de dar senso de direção aos seus projetos. Para mostrar a direção, você pode usar um display LCD I2C ou OLED; para transformá-la em movimento, um servo, um motor de passo ou um carrinho robô. No app BlueGrays, você encontra esses projetos com display, motor e robô, com esquema do circuito e código passo a passo, e pode acrescentar o módulo bússola a eles com facilidade.

Perguntas frequentes

Meu GY-271 tem um QMC5883L ou um HMC5883L?

O jeito mais fácil é uma varredura I2C: se aparecer o endereço 0x0D, é um QMC5883L; se aparecer 0x1E, é um HMC5883L. Você também pode olhar a marcação do chip; o QMC5883L costuma trazer DA 5883 e o HMC5883L, L883. A grande maioria das placas GY-271 vendidas hoje tem o QMC5883L.

Uma biblioteca do HMC5883L funciona com o QMC5883L?

Não. Os dois chips têm endereço I2C, endereços de registradores, ordem dos bytes e configurações diferentes; uma biblioteca para HMC procura o endereço 0x1E e não encontra o QMC5883L. Para o QMC5883L, você precisa de uma biblioteca como a QMC5883LCompass ou de um código escrito diretamente com Wire.

Por que meu módulo bússola do Arduino mostra a direção errada?

A causa mais comum é a falta de calibração; ímãs e peças metálicas próximas somam um offset à leitura e podem deslocar o ângulo em dezenas de graus. Módulo inclinado, proximidade de motores e fios com corrente e não somar a declinação magnética também causam erros. Montar o módulo nivelado e calibrá-lo na posição final normalmente reduz o erro para poucos graus.

Qual é a declinação magnética na Turquia?

Na Turquia, a declinação magnética é para leste e hoje fica aproximadamente entre 5 e 7 graus; é menor nas províncias do oeste e maior no leste. Cerca de 6 graus funciona para Istambul e Ancara. Como o valor muda devagar com os anos, consulte uma calculadora de modelo magnético atualizada para um resultado exato.

O módulo bússola GY-271 funciona com 5 V?

Sim. Como a placa GY-271 tem um regulador de 3,3 V, você pode aplicar 3–5 V no pino VCC e ligar a placa diretamente a um Arduino Uno. O chip em si funciona com 3,3 V; no ESP32 e no Raspberry Pi Pico, o ideal é alimentar a placa pelo pino 3V3.

O módulo bússola mede corretamente quando está inclinado?

Uma direção calculada só com X e Y está correta apenas enquanto o módulo estiver paralelo ao chão. Como o campo magnético entra no solo com uma inclinação de cerca de 55–60 graus na Turquia, até uma pequena inclinação pode deslocar a direção em 10–15 graus. Em dispositivos de mão, é preciso fazer a compensação de inclinação com um acelerômetro como o MPU-6050.

Ver todos os projetos
Uso do display LCD com I2C
AR-32Iniciante
Premium

Uso do display LCD com I2C

Dê ao seu Arduino um display próprio e faça-o escrever sua primeira mensagem. O display LCD de duas linhas é conectado com poucos fios; primeiro aparece uma saudação na linha de cima, depois uma…

4.8(53)
70
Display LCD I2C com ESP32 (16x2)
ES-17Intermediário
Premium

Display LCD I2C com ESP32 (16x2)

Neste projeto, exibimos texto conectando um display LCD de 16x2 caracteres ao ESP32 pelo protocolo I2C. Com o I2C, controlamos o display usando apenas dois pinos de dados (SDA e SCL), dispensando o uso de seis ou mais pinos da conexão paralela tradicional. O código mostra uma mensagem fixa na primeira linha e um contador que aumenta a cada segundo na segunda linha. Na inicialização, também executamos um scanner I2C para mostrar o endereço do display no Monitor Serial (geralmente 0x27 ou 0x3F).

4.9(23)
40
ESP32 HTTPClient + API de clima (com display OLED SSD1306)
ES-32Avançado
Premium

ESP32 HTTPClient + API de clima (com display OLED SSD1306)

Neste projeto, usamos o ESP32 para fazer uma chamada REST à API de clima wttr.in pela internet com HTTPClient.h. Diferentemente da versão anterior com LCD I2C, aqui usamos um display OLED SSD1306 (128×64), que permite usar fontes grandes, ícones vetoriais e uma apresentação visual rica em uma única tela. Sete ícones vetoriais de condições do tempo (ensolarado, parcialmente nublado, nublado, chuvoso, com neve, com tempestade e com neblina) são desenhados durante a execução, sem arquivos bitmap.

4.3(10)
22
ESP32 em sono profundo — Economia de bateria (OLED + contador na RAM RTC)
ES-33Avançado
Premium

ESP32 em sono profundo — Economia de bateria (OLED + contador na RAM RTC)

O modo de sono profundo do ESP32 reduz o consumo de corrente para ~10 µA ao desligar a CPU e a maioria dos periféricos, sendo essencial para dispositivos IoT alimentados por bateria. Neste projeto, usamos três fontes de despertar: um temporizador (15 segundos), um pino externo (EXT0 — botão no GPIO 33) e toque (T0/GPIO 4). As variáveis marcadas com RTC_DATA_ATTR são preservadas durante o sono profundo, mantendo os contadores de inicializações e de despertares por temporizador e botão.

4.3(10)
16
Uso de servo motor
AR-35Iniciante
Premium

Uso de servo motor

O braço de um pequeno servo motor gira para três posições em sequência: o início, o meio e o fim do percurso, esperando dois segundos em cada parada.

4.7(48)
67
Uso do motor de passo
AR-67Intermediário
Premium

Uso do motor de passo

Um motor que gira passo a passo, exatamente o quanto você quer, como o ponteiro de um relógio.

4.5(31)
42
Carrinho controlado por Bluetooth com L298N
AR-80Avançado
Premium

Carrinho controlado por Bluetooth com L298N

Transforme seu celular em um controle remoto e dirija seu próprio carrinho robô.

5.0(39)
66
Robô que desvia de obstáculos
AR-81Avançado
Premium

Robô que desvia de obstáculos

Que tal construir um veículo inteligente que encontra seu próprio caminho? O robô que desvia de obstáculos monitora o ambiente constantemente com o sensor ultrassônico na parte da frente.

5.0(38)
49