Модуль компаса для Arduino: QMC5883L и HMC5883L (GY-271)
В твоём GY-271 стоит QMC5883L или HMC5883L? I2C-адреса (0x0D, 0x1E), расчёт направления через atan2, магнитное склонение, калибровка и компас на OLED-дисплее с кодом для Uno, ESP32 и Pico.
Модуль компаса для Arduino — это маленький датчик магнитного поля, который подсказывает твоей плате, где находится север. Самая распространённая модель, GY-271, измеряет магнитное поле Земли по трём осям. По этим данным можно вычислить направление (0–360 градусов), чтобы вести робота-машинку в заданную сторону, показать цифровой компас на OLED-дисплее или добавить данные о направлении в твой GPS-проект. Модуль подключается всего четырьмя проводами по I2C и одинаково работает с Arduino Uno, ESP32 и Raspberry Pi Pico.
Но у этого модуля есть сюрприз: на большинстве плат, которые продаются как GY-271, стоит уже не чип HMC5883L от Honeywell, а QMC5883L от QST. Снаружи два чипа выглядят почти одинаково, но I2C-адреса и регистры у них разные, поэтому многие готовые скетчи выдают «датчик не найден». В этой статье ты узнаешь, как определить, какой чип стоит на твоей плате, правильно вычислить направление, учесть магнитное склонение и с помощью калибровки снизить ошибку до нескольких градусов.
Что такое модуль цифрового компаса и как он работает?
Сердце модуля — магнитометр, датчик, измеряющий магнитное поле. Поле Земли довольно слабое: в Турции его полная напряжённость составляет около 45–50 микротесла (0,45–0,5 гаусса), а горизонтальная составляющая, параллельная земле, — около 25 µT (1 гаусс = 100 µT). Чип с помощью магниторезистивных датчиков измеряет составляющие поля по осям X, Y и Z и выдаёт каждую как целое число со знаком. Пока модуль лежит горизонтально, для определения направления достаточно X и Y; угол из них получают функцией atan2. Ось Z пригодится для продвинутых задач вроде компенсации наклона и обнаружения металла.
| Параметр | QMC5883L | HMC5883L |
|---|---|---|
| Производитель | QST | Honeywell (снят с производства) |
| I2C-адрес | 0x0D | 0x1E |
| Диапазон измерения | ±2 G или ±8 G | от ±0,88 G до ±8,1 G (8 ступеней) |
| Разрешение | 16 бит (12 000 LSB/G при ±2 G, 3000 LSB/G при ±8 G) | 12 бит (1090 LSB/G при ±1,3 G) |
| Частота данных | 10, 50, 100, 200 Hz | 0,75–75 Hz (в непрерывном режиме) |
| Питание чипа | 2,16–3,6 V | 2,16–3,6 V |
| Питание платы GY-271 | 3–5 V (на плате есть стабилизатор) | 3–5 V (на плате есть стабилизатор) |
| Измерение температуры | Есть (относительное значение) | Нет |
QMC5883L или HMC5883L? Как отличить два чипа
Много лет HMC5883L был стандартным чипом компаса в любительской электронике. Когда Honeywell прекратила производство, рынок заполнил QMC5883L от QST. Продавцы часто не меняют название товара, поэтому найти QMC5883L на плате, купленной как «HMC5883L», — совершенно обычное дело. Самый надёжный способ проверить — I2C-сканирование: если на шине виден адрес 0x0D, это QMC5883L; если 0x1E — HMC5883L. Помогает и чтение маркировки на чипе через лупу. В последнее время на некоторых платах встречается QMC5883P с адресом 0x2C; у него другая карта регистров, поэтому код из этой статьи с ним напрямую не заработает.
| Способ | QMC5883L | HMC5883L |
|---|---|---|
| I2C-адрес | 0x0D | 0x1E |
| Маркировка на чипе | DA 5883 | L883 |
| Регистр идентификации | Регистр 0x0D возвращает 0xFF | Регистры 0x0A–0x0C возвращают 'H', '4', '3' |
| Регистры данных | 0x00–0x05 (по порядку X, Y, Z) | 0x03–0x08 (по порядку X, Z, Y) |
| Порядок байтов | Сначала младший байт (LSB) | Сначала старший байт (MSB) |
| Режим при включении | Ожидание (standby), не измеряет | Режим однократного измерения |
| Популярная библиотека | QMC5883LCompass | Adafruit HMC5883 Unified |
Подключение GY-271: Uno, ESP32 и Pico
| Пин GY-271 | Arduino Uno | ESP32 | Raspberry Pi Pico |
|---|---|---|---|
| VCC | 5V (или 3.3V) | 3V3 | 3V3 (пин 36) |
| GND | GND | GND | GND |
| SCL | A5 | GPIO 22 | GP5 (пин 7) |
| SDA | A4 | GPIO 21 | GP4 (пин 6) |
| DRDY | Не подключается | Не подключается | Не подключается |
На плате GY-271 есть стабилизатор на 3,3 V и подтягивающие резисторы для линий I2C, поэтому на Uno модуль можно безопасно питать от пина 5V. На ESP32 и Pico питай плату от пина 3V3, чтобы SDA и SCL оставались на уровне 3,3 V. Пин DRDY (данные готовы) сигнализирует о каждом новом измерении; если чтение по прерыванию не нужно, его можно оставить свободным. Компас может делить одну шину с другими I2C-устройствами, например с OLED-дисплеем (0x3C) или MPU-6050 (0x68), потому что их адреса не совпадают. Подробнее об адресах и подтяжке читай в статье Что такое I2C.
Пошагово: первое измерение направления (Arduino Uno)
- Вставь модуль в макетную плату и по возможности держи его не ближе 15–20 см от моторов, динамиков, магнитов и крупных стальных деталей.
- Подключи провода VCC, GND, SCL и SDA, как в таблице, а пин DRDY оставь свободным.
- Загрузи код ниже; дополнительные библиотеки не нужны, используется только встроенная библиотека Arduino Wire.
- Открой монитор порта на скорости 9600 бод; в первой строке видно, какой чип нашёл код.
- Положи модуль ровно на стол и медленно поворачивай его; смотри, как значения X и Y колеблются между плюсом и минусом, а угол идёт от 0 до 360.
- Если компас в телефоне настроен показывать истинный север, направь стрелку X на модуле на этот север; угол должен приблизиться к 0. До калибровки ошибка в 10–30 градусов — это нормально.
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}| Код / регистр | Значение | Смысл |
|---|---|---|
| QMC 0x0B | 0x01 | Период SET/RESET; значение, рекомендованное даташитом |
| QMC 0x09 | 0x1D | OSR 512, диапазон ±8 G, 200 Hz, непрерывное измерение (0x0D для ±2 G) |
| HMC 0x00 | 0x70 | Среднее из 8 измерений, частота данных 15 Hz |
| HMC 0x01 | 0x20 | Диапазон ±1,3 Ga, чувствительность 1090 LSB/Ga |
| HMC 0x02 | 0x00 | Режим непрерывного измерения |
| Wire.endTransmission() == 0 (проверка ответа) | - | Если адрес ответил, устройство есть на шине |
| atan2(y, x) × 180 / π (в градусах) | - | Угол от −180 до +180 градусов по «сырым» значениям осей |
Как вычисляется направление?
Пока модуль лежит горизонтально, горизонтальное магнитное поле Земли распределяется между осями X и Y. Если направить стрелку X на север, всё поле приходится на X, а Y стремится к нулю; при повороте модуля доля смещается на Y. Направление находят по формуле θ = atan2(Y, X). Вместо простого atan(Y/X) используется atan2, потому что atan2 смотрит на знаки обоих значений, различает все четыре четверти и не делит на ноль, когда X равен нулю. Результат получается в радианах в диапазоне от −180 до +180 градусов; чтобы перевести его в градусы, умножают на 180/π, а если он отрицательный, прибавляют 360. Каждое из восьми основных направлений занимает сектор в 45 градусов: от 337,5 до 22,5 градуса — Север (N), от 22,5 до 67,5 — Северо-восток (NE) и так далее; операция (угол + 22.5) / 45 в коде выбирает нужный сектор. Если при повороте модуля по часовой стрелке угол уменьшается, у твоей платы другое расположение осей; поменяй знак Y и используй atan2(-y, x).
Что такое магнитное склонение?
Стрелка компаса указывает на магнитный север, а не на географический (истинный). Угол между ними называется магнитным склонением, и он зависит от места и года. В Турции склонение восточное и сегодня составляет около +5 градусов в западных провинциях и около +7 градусов на востоке; для Стамбула и Анкары 6 градусов — хорошая отправная точка. Формула поправки простая: истинное направление = магнитное направление + склонение, восточное склонение записывается со знаком плюс, западное — со знаком минус. Просто узнай актуальное значение для своего места в калькуляторе магнитной модели NOAA или похожей организации и впиши его в константу DECLINATION в коде. Если значение дано в градусах и минутах, переведи его в десятичную дробь: 5° 48' = 5 + 48/60 = 5,8 градуса. Склонение смещается на несколько угловых минут в год, поэтому раз в несколько лет его стоит проверять.
Калибровка компаса: hard iron и soft iron
Некалиброванный компас может ошибаться на 20–40 градусов, особенно при первой попытке. Причин две. При эффекте hard iron («жёсткое железо») постоянные магниты рядом с модулем, намагниченные винты или детали на плате добавляют к каждому измерению постоянную величину; если нарисовать график значений X–Y при вращении модуля, будет видно, что центр окружности смещён от нуля. При эффекте soft iron («мягкое железо») расположенные рядом материалы вроде железа и никеля искривляют поле и превращают окружность в эллипс. Решение простое: держи модуль горизонтально в том положении, в котором он будет стоять в проекте, медленно поверни его два-три раза и запиши минимум и максимум по каждой оси. Смещение = (max + min) / 2 даёт поправку на hard iron, а масштаб = средний радиус / радиус оси — простую поправку на soft iron. Код ниже написан для QMC5883L, который стоит на большинстве плат; если у тебя HMC5883L, просто замени функцию чтения на часть для HMC из первого скетча.
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}Код каждую секунду выводит значения OFF и SCALE; продолжай вращать модуль, пока числа не перестанут меняться. Например, если для X получен минимум −680 и максимум 920, смещение равно (920 + (−680)) / 2 = 120, а радиус — 800. Если у Y минимум −1010 и максимум 550, смещение −230, а радиус 780. Средний радиус равен 790, поэтому масштабы получаются 790 / 800 ≈ 0,988 и 790 / 780 ≈ 1,013. В основном коде каждое «сырое» значение исправляется так: x = (raw_x − OFF_X) × SCALE_X; в примере для ESP32 ниже эти значения уже вписаны. Поскольку в диапазоне ±8 G 1 гаусс соответствует 3000 отсчётов, радиус 800 означает горизонтальное поле около 0,27 G, что совпадает с ожидаемым для Турции. Если модуль переносится в другое место или рядом появляется новая металлическая деталь, повтори калибровку.
Компас на OLED-дисплее с ESP32

На ESP32 работает тот же код на Wire; пины I2C — GPIO 21 (SDA) и GPIO 22 (SCL), компас и OLED-дисплей 0,96 дюйма подключаются к одной шине. Код применяет калибровочные значения, сглаживает X и Y простым фильтром нижних частот и показывает слева на экране вращающуюся стрелку компаса, а справа — градусы и букву направления. Фильтр применяется к осям, а не к углу, чтобы при переходе через 359–0 градусов среднее значение углов ошибочно не получалось около 180. Короткая линия вверху экрана обозначает переднюю сторону устройства, а стрелка указывает на север; когда устройство поворачивается, стрелка вращается в обратную сторону, как у настоящего компаса. Как установить библиотеки для дисплея, читай в статье 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}Компас на MicroPython с Raspberry Pi Pico
На Pico достаточно класса machine.I2C из MicroPython, отдельный файл драйвера не нужен. Сначала код выводит список адресов на шине через i2c.scan(), записывает настройки для найденного чипа и читает шесть байтов за раз через readfrom_mem. В MicroPython байты приходят без знака, поэтому из значений больше 32767 нужно вычесть 65536, чтобы получить отрицательные числа. Для калибровки просто впиши в константы в коде значения OFF и SCALE, найденные на Arduino. Если MicroPython для тебя в новинку, хорошо начать со статей Основы MicroPython и Что такое Raspberry Pi Pico.
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)Компенсация наклона: почему модуль должен лежать ровно?
Направление, вычисленное только по осям X и Y, верно лишь тогда, когда модуль параллелен земле. На средних широтах, как в Турции, магнитное поле входит в землю под наклоном около 55–60 градусов, поэтому вертикальная составляющая (Z) заметно больше горизонтальной. При наклоне модуля на 10 градусов часть составляющей Z попадает на X или Y, и направление может уйти с ошибкой до 15 градусов. Для ручных или раскачивающихся устройств решение — компенсация наклона: с помощью акселерометра MPU-6050 определяются углы крена (roll) и тангажа (pitch), и значения магнитометра поворачиваются на горизонтальную плоскость. Для простых проектов вроде робота-машинки или неподвижной коробки часто достаточно закрепить модуль ровно и надёжно на корпусе.
Идеи проектов с модулем компаса
- Робот-машинка, держащая курс: научи своего робота-машинку поворачивать на заданный угол и ехать прямо; закрепи модуль на пластиковой стойке подальше от моторов.
- Навигация к цели по GPS: вычисли направление на цель с помощью GPS NEO-6M и покажи разницу с компасом стрелкой на дисплее.
- Компас со стрелкой на сервоприводе: поворачивай качалку сервопривода так, чтобы она всегда указывала на север, как бы ни поворачивалась коробка.
- Определитель направления на киблу: впиши в код угол киблы для своего города и поворачивай стрелку на OLED по этому углу вместо севера.
- Ориентация солнечной панели: проверяй компасом, что панель в солнечном трекере смотрит в нужную сторону.
- Трость, подсказывающая направление: добавь в проект умной трости режим, который даёт короткую вибрацию, когда пользователь поворачивается к северу.
- Детектор магнитов и металла: вычисли полную напряжённость поля по трём осям и включай зуммер, когда значение резко растёт.
Частые ошибки и как их исправить
| Симптом | Вероятная причина | Решение |
|---|---|---|
| Ошибка «No HMC5883 detected» | На плате стоит QMC5883L | Используй код для адреса 0x0D или библиотеку QMC5883LCompass |
| При I2C-сканировании нет ни одного адреса | SDA и SCL перепутаны, нет питания или оборван провод | Проверь провода и измерь напряжение на пине VCC |
| X, Y, Z всегда 0 или не меняются | QMC5883L при включении находится в режиме ожидания | Запиши настройку непрерывного режима (0x1D) в регистр 0x09 |
| Угол не проходит все 360 градусов | Слишком большое смещение hard iron | Выполни калибровку и вычитай значения OFF |
| При повороте по часовой стрелке угол уменьшается | У платы другое расположение осей | Используй atan2(-y, x) |
| Направление уплывает, когда работает мотор | Магниты мотора и провода с большим током | Перенеси модуль на 15–20 см дальше, на стойку |
| При наклоне направление сбивается | Нет компенсации наклона | Закрепи модуль ровно или компенсируй с помощью MPU-6050 |
Когда чип опознан и откалиброван, модуль компаса GY-271 становится одним из самых дешёвых способов дать проектам чувство направления. Для вывода направления подойдёт I2C LCD или OLED-дисплей, а чтобы превратить его в движение — сервопривод, шаговый двигатель или робот-машинка. В приложении BlueGrays есть такие проекты с дисплеями, моторами и роботами с пошаговыми схемами и кодом, и к ним легко добавить модуль компаса.
Частые вопросы
Какой чип в моём GY-271: QMC5883L или HMC5883L?
Проще всего выполнить I2C-сканирование: если виден адрес 0x0D, это QMC5883L, если 0x1E — HMC5883L. Можно также посмотреть маркировку на чипе: на QMC5883L обычно написано DA 5883, на HMC5883L — L883. На подавляющем большинстве плат GY-271, которые продаются сегодня, стоит QMC5883L.
Работает ли библиотека для HMC5883L с QMC5883L?
Нет. У двух чипов разные I2C-адреса, адреса регистров, порядок байтов и настройки; библиотека для HMC ищет адрес 0x1E и не находит QMC5883L. Для QMC5883L нужна библиотека вроде QMC5883LCompass или код, написанный напрямую на Wire.
Почему модуль компаса на Arduino показывает неправильное направление?
Самая частая причина — отсутствие калибровки: магниты и металлические детали рядом добавляют к показаниям смещение и могут сдвинуть угол на десятки градусов. К ошибкам приводят также наклон модуля, близость к моторам и проводам с током и неучтённое магнитное склонение. Если закрепить модуль ровно и откалибровать его в окончательном положении, ошибка обычно снижается до нескольких градусов.
Какое магнитное склонение в Турции?
В Турции магнитное склонение восточное и сегодня составляет примерно от 5 до 7 градусов: в западных провинциях меньше, на востоке больше. Для Стамбула и Анкары можно использовать около 6 градусов. Значение медленно меняется с годами, поэтому для точного результата загляни в актуальный калькулятор магнитной модели.
Работает ли модуль компаса GY-271 от 5 V?
Да. На плате GY-271 есть стабилизатор на 3,3 V, поэтому на пин VCC можно подавать 3–5 V и подключать плату напрямую к Arduino Uno. Сам чип работает от 3,3 V; на ESP32 и Raspberry Pi Pico лучше питать плату от пина 3V3.
Правильно ли измеряет модуль компаса при наклоне?
Направление, вычисленное только по X и Y, верно лишь тогда, когда модуль параллелен земле. В Турции магнитное поле входит в землю под наклоном около 55–60 градусов, поэтому даже небольшой наклон может сдвинуть направление на 10–15 градусов. Для ручных устройств нужна компенсация наклона с помощью акселерометра, например MPU-6050.
Что собрать после прочтения
Все проекты
LCD-экран с I2C
Дай своему Arduino собственный экран и заставь его написать первое сообщение. Двухстрочный LCD-экран подключается всего несколькими проводами; в верхней строке появляется приветствие, затем второе…

I2C LCD-дисплей (16x2) на ESP32
В этом проекте символьный LCD-экран 16x2 подключается к ESP32 по протоколу I2C и выводит текст. Благодаря I2C экраном можно управлять всего двумя пинами данных (SDA и SCL), не тратя 6+ пинов, как при классическом параллельном подключении. Код печатает постоянное сообщение в первой строке и счётчик, растущий каждую секунду, во второй. Кроме того, при запуске работает сканер I2C, который выводит адрес дисплея в монитор порта.

ESP32 HTTPClient + API погоды (с OLED-дисплеем SSD1306)
В этом проекте ESP32 через HTTPClient.h делает вызов REST API к сервису погоды (wttr.in). В отличие от прошлой версии с I2C LCD, здесь используется OLED SSD1306 (128×64), который позволяет крупные шрифты, векторные значки и богатую картинку на одном экране. Семь векторных значков погоды (солнечно, переменная облачность, облачно, дождь, снег, гроза, туман) рисуются во время работы (растровые файлы не нужны). Температура выводится крупными цифрами.

Глубокий сон ESP32: экономия батареи (OLED + счётчик в RTC RAM)
Режим глубокого сна (Deep Sleep) у ESP32 снижает потребление до ~10 µA, выключая процессор и большую часть периферии, — это важно для IoT-устройств на батарейках. В этом проекте используются три источника пробуждения: таймер (15 секунд), внешний пин (EXT0 — кнопка GPIO 33) и касание (T0/GPIO 4). Переменные с RTC_DATA_ATTR сохраняются во время глубокого сна — счётчики загрузок, пробуждений по таймеру и по кнопке ведутся непрерывно.

Работа с сервоприводом
Рычаг маленького сервопривода по очереди поворачивается в три положения: до упора в начало, ровно на середину и до упора в конец, задерживаясь на каждой остановке на две секунды.

Работа с шаговым мотором
Мотор, который поворачивается шаг за шагом ровно настолько, насколько нужно, как стрелка часов.

Машинка на L298N с управлением по Bluetooth
Преврати телефон в пульт и управляй своей машинкой-роботом. Arduino получает команды из приложения-пульта на телефоне через Bluetooth-модуль и вращает колёса через драйвер моторов; машинка едет…

Робот, объезжающий препятствия
Как насчёт того, чтобы собрать умную машину, которая сама находит дорогу? Робот, объезжающий препятствия, постоянно осматривает всё вокруг благодаря ультразвуковому датчику спереди.
Другие статьи
Приложение BlueGrays
Собери эту схему шаг за шагом в телефоне
Схема подключения, код и список деталей на одном экране. 500+ проектов на Arduino, ESP32 и Pico готовы к сборке.
Наведи камеру телефона
Наведи камеру на код — откроется магазин приложений на телефоне.
или открыть магазин

