Компоненты · 9 мин чтения

Модуль компаса для 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 пригодится для продвинутых задач вроде компенсации наклона и обнаружения металла.

ПараметрQMC5883LHMC5883L
ПроизводительQSTHoneywell (снят с производства)
I2C-адрес0x0D0x1E
Диапазон измерения±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 Hz0,75–75 Hz (в непрерывном режиме)
Питание чипа2,16–3,6 V2,16–3,6 V
Питание платы GY-2713–5 V (на плате есть стабилизатор)3–5 V (на плате есть стабилизатор)
Измерение температурыЕсть (относительное значение)Нет

QMC5883L или HMC5883L? Как отличить два чипа

Много лет HMC5883L был стандартным чипом компаса в любительской электронике. Когда Honeywell прекратила производство, рынок заполнил QMC5883L от QST. Продавцы часто не меняют название товара, поэтому найти QMC5883L на плате, купленной как «HMC5883L», — совершенно обычное дело. Самый надёжный способ проверить — I2C-сканирование: если на шине виден адрес 0x0D, это QMC5883L; если 0x1E — HMC5883L. Помогает и чтение маркировки на чипе через лупу. В последнее время на некоторых платах встречается QMC5883P с адресом 0x2C; у него другая карта регистров, поэтому код из этой статьи с ним напрямую не заработает.

СпособQMC5883LHMC5883L
I2C-адрес0x0D0x1E
Маркировка на чипеDA 5883L883
Регистр идентификацииРегистр 0x0D возвращает 0xFFРегистры 0x0A–0x0C возвращают 'H', '4', '3'
Регистры данных0x00–0x05 (по порядку X, Y, Z)0x03–0x08 (по порядку X, Z, Y)
Порядок байтовСначала младший байт (LSB)Сначала старший байт (MSB)
Режим при включенииОжидание (standby), не измеряетРежим однократного измерения
Популярная библиотекаQMC5883LCompassAdafruit HMC5883 Unified
Библиотеки для HMC, например Adafruit HMC5883 Unified, ищут только адрес 0x1E. Если на твоей плате QMC5883L, появится сообщение вроде «no HMC5883 detected» (HMC5883 не обнаружен), и покажется, что модуль сломан. Он исправен, просто чип другой. Сначала выполни I2C-сканирование, а потом используй код, который обращается к правильному адресу.

Подключение GY-271: Uno, ESP32 и Pico

Пин GY-271Arduino UnoESP32Raspberry Pi Pico
VCC5V (или 3.3V)3V33V3 (пин 36)
GNDGNDGNDGND
SCLA5GPIO 22GP5 (пин 7)
SDAA4GPIO 21GP4 (пин 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)

  1. Вставь модуль в макетную плату и по возможности держи его не ближе 15–20 см от моторов, динамиков, магнитов и крупных стальных деталей.
  2. Подключи провода VCC, GND, SCL и SDA, как в таблице, а пин DRDY оставь свободным.
  3. Загрузи код ниже; дополнительные библиотеки не нужны, используется только встроенная библиотека Arduino Wire.
  4. Открой монитор порта на скорости 9600 бод; в первой строке видно, какой чип нашёл код.
  5. Положи модуль ровно на стол и медленно поворачивай его; смотри, как значения X и Y колеблются между плюсом и минусом, а угол идёт от 0 до 360.
  6. Если компас в телефоне настроен показывать истинный север, направь стрелку X на модуле на этот север; угол должен приблизиться к 0. До калибровки ошибка в 10–30 градусов — это нормально.
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}
Код / регистрЗначениеСмысл
QMC 0x0B0x01Период SET/RESET; значение, рекомендованное даташитом
QMC 0x090x1DOSR 512, диапазон ±8 G, 200 Hz, непрерывное измерение (0x0D для ±2 G)
HMC 0x000x70Среднее из 8 измерений, частота данных 15 Hz
HMC 0x010x20Диапазон ±1,3 Ga, чувствительность 1090 LSB/Ga
HMC 0x020x00Режим непрерывного измерения
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 из первого скетча.

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}

Код каждую секунду выводит значения 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

OLED-дисплей 0,96 дюйма с I2C
OLED-дисплей 0,96 дюйма с I2C (0x3C) без проблем делит одну шину I2C с модулем компаса (0x0D).

На ESP32 работает тот же код на Wire; пины I2C — GPIO 21 (SDA) и GPIO 22 (SCL), компас и OLED-дисплей 0,96 дюйма подключаются к одной шине. Код применяет калибровочные значения, сглаживает X и Y простым фильтром нижних частот и показывает слева на экране вращающуюся стрелку компаса, а справа — градусы и букву направления. Фильтр применяется к осям, а не к углу, чтобы при переходе через 359–0 градусов среднее значение углов ошибочно не получалось около 180. Короткая линия вверху экрана обозначает переднюю сторону устройства, а стрелка указывает на север; когда устройство поворачивается, стрелка вращается в обратную сторону, как у настоящего компаса. Как установить библиотеки для дисплея, читай в статье 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}

Компас на MicroPython с Raspberry Pi Pico

На Pico достаточно класса machine.I2C из MicroPython, отдельный файл драйвера не нужен. Сначала код выводит список адресов на шине через i2c.scan(), записывает настройки для найденного чипа и читает шесть байтов за раз через readfrom_mem. В MicroPython байты приходят без знака, поэтому из значений больше 32767 нужно вычесть 65536, чтобы получить отрицательные числа. Для калибровки просто впиши в константы в коде значения OFF и SCALE, найденные на Arduino. Если MicroPython для тебя в новинку, хорошо начать со статей Основы MicroPython и Что такое Raspberry Pi Pico.

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)

Компенсация наклона: почему модуль должен лежать ровно?

Направление, вычисленное только по осям 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
Во время тестов показания может сбить даже металлический стол, динамик ноутбука, телефон или ферритовое кольцо на USB-кабеле. Калибровку и тесты проводи в том положении и с тем подключением, которые будут у модуля в проекте: компас, идеально откалиброванный на столе, внутри робота может снова начать ошибаться.

Когда чип опознан и откалиброван, модуль компаса 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
AR-32Новичок
Premium

LCD-экран с I2C

Дай своему Arduino собственный экран и заставь его написать первое сообщение. Двухстрочный LCD-экран подключается всего несколькими проводами; в верхней строке появляется приветствие, затем второе…

4.8(53)
70
I2C LCD-дисплей (16x2) на ESP32
ES-17Средний
Premium

I2C LCD-дисплей (16x2) на ESP32

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

4.9(23)
40
ESP32 HTTPClient + API погоды (с OLED-дисплеем SSD1306)
ES-32Продвинутый
Premium

ESP32 HTTPClient + API погоды (с OLED-дисплеем SSD1306)

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

4.3(10)
22
Глубокий сон ESP32: экономия батареи (OLED + счётчик в RTC RAM)
ES-33Продвинутый
Premium

Глубокий сон ESP32: экономия батареи (OLED + счётчик в RTC RAM)

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

4.3(10)
16
Работа с сервоприводом
AR-35Новичок
Premium

Работа с сервоприводом

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

4.7(48)
67
Работа с шаговым мотором
AR-67Средний
Premium

Работа с шаговым мотором

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

4.5(31)
42
Машинка на L298N с управлением по Bluetooth
AR-80Продвинутый
Premium

Машинка на L298N с управлением по Bluetooth

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

5.0(39)
66
Робот, объезжающий препятствия
AR-81Продвинутый
Premium

Робот, объезжающий препятствия

Как насчёт того, чтобы собрать умную машину, которая сама находит дорогу? Робот, объезжающий препятствия, постоянно осматривает всё вокруг благодаря ультразвуковому датчику спереди.

5.0(38)
49