GY-271 — цифровой компас (магнитометр)

GY-271 — цифровой компас (магнитометр)

Компонент опрашивает 3-осевой магнитометр на плате “GY-271” по I2C и вычисляет азимут (курс относительно магнитного севера). Под одним и тем же названием платы на рынке продаются два несовместимых чипа — оригинальный Honeywell HMC5883L и более новый QST QMC5883L. Драйвер сам определяет, какой из них на шине, и настраивает именно его — подробнее в THEORY.md.

Файлы

• include/Gy271Compass.h / src/Gy271Compass.cpp — драйвер.
• src/main.cpp — тестовый стенд: калибровка, расчёт азимута, Serial-команды.
• tools/compass_view.py — живая стрелка компаса на компьютере (см. раздел “Визуализация” ниже).
• THEORY.md — физика магнитометра, регистры обоих чипов, зачем нужна калибровка.
• WIRING.md — схема подключения.
• Lesson.md — методический план урока для учителя.

Подключение (кратко)

Полная схема — в WIRING.md.

Быстрый старт

1. Собрать схему по WIRING.md.
2. Прошить: pio run -e esp32dev -t upload.
3. Открыть Serial Monitor на 115200 бод.
4. При старте компонент сообщает, какой чип найден на плате (main.cpp:121-127) — QMC5883L или HMC5883L. Оба варианта поддерживаются одинаково, дальше работа не отличается.
5. Ввести команду c и вращать плату во всех плоскостях 30 секунд — это калибровка, без неё азимут считаться не будет (подробнее — THEORY.md, раздел «Калибровка»).
6. Команда r — разовое чтение X/Y/Z и азимута, h — только направление.

Визуализация

tools/compass_view.py рисует живую стрелку компаса на экране вместо чисел в Serial Monitor — так эффект калибровки виден сразу:

cd tools
pip install -r requirements.txt
python3 compass_view.py /dev/ttyUSB0

Serial Monitor прошивки на момент запуска скрипта должен быть закрыт. Подробнее — Lesson.md, блок практики.

Калибровка

Магнитометр искажается металлом рядом с платой (Hard-Iron/Soft-Iron эффекты) — эти искажения индивидуальны для каждой платы, монтажа и помещения. Поэтому драйвер не хранит калибровочные коэффициенты — только сырые X/Y/Z. Калибровка (поиск границ min/max по осям) реализована в тестовом стенде: main.cpp:66-100. Результат нужно вручную перенести в calibration в начале main.cpp (main.cpp:17-21) — как и пороги в компоненте APDS-9960, это подстраивается под конкретный экземпляр, а не берётся из библиотеки.

Магнитное склонение (MAGNETIC_DECLINATION_DEG, main.cpp:10) нужно подставить под свой регион — по умолчанию 0° (курс “магнитный”).

API драйвера

Используемые регистры

Полный разбор — в THEORY.md. Константы — Gy271Compass.h:53-77.

Известные ограничения

• Без калибровки (команда c) азимут не считается — драйвер честно сообщает об этом (computeHeadingDeg() возвращает -1).
• Точность падает рядом с металлическими предметами и электромоторами.
• Если датчик не отвечает ни на 0x0D, ни на 0x1E — проверьте проводку, см. WIRING.md.

Связанные материалы

• Пространство и положение — системы координат, курс и точка отсчёта; компас даёт угол $\theta$ для одометрии.
• Сигналы и данные — почему показания рядом с моторами искажаются и как с этим работать.
• MPU6050 — гироскоп быстрый, но уплывает; компас медленный, но абсолютный. Вместе они дают устойчивый курс.

Теория: как GY-271 находит север

1. Магниторезистивный эффект: как чип «чувствует» магнитное поле

Оба чипа, которые встречаются под платой “GY-271” (HMC5883L и QMC5883L), используют один и тот же физический принцип — анизотропный магниторезистивный эффект (AMR). Внутри чипа есть тонкие полоски пермаллоя (сплав никеля и железа), электрическое сопротивление которых меняется в зависимости от направления и силы внешнего магнитного поля. Три таких элемента расположены перпендикулярно друг другу (по осям X, Y, Z), поэтому чип может измерить не просто «есть поле или нет», а вектор магнитного поля в трёхмерном пространстве.

Магнитное поле Земли — как раз то поле, которое эти элементы улавливают. Зная его направление, можно вычислить, куда указывает «магнитный север».

2. Почему одна и та же плата бывает разной внутри

“GY-271” — это название платы-переходника, а не название чипа. Производители плат меняли начинку: старые платы несут оригинальный Honeywell HMC5883L, более новые — QST QMC5883L. Это разные производители, разные I2C-адреса и разные карты регистров — код, написанный под один чип, не будет работать с другим, если явно не учесть эту разницу.

begin() в этом драйвере (Gy271Compass.cpp:5-20) устроен как последовательная проверка: сначала пробуем адрес 0x0D (QMC5883L), и если чип по этому адресу подтверждает свой ID — работаем с ним. Если нет — пробуем 0x1E (HMC5883L). Так один и тот же код работает с любой платой, которая реально попадёт в руки, без необходимости знать заранее, какая именно версия куплена.

3. Регистры, которые мы используем

Источники: датащит QST QMC5883L (Rev. 1.0/B, раздел “Register Map”) и датащит Honeywell “3-Axis Digital Compass IC HMC5883L” (регистровая карта).

QMC5883L (адрес 0x0D)

HMC5883L (адрес 0x1E)

Перестановка Y и Z для HMC5883L — не ошибка драйвера, а особенность датащита Honeywell: если читать байты подряд как X,Y,Z, компас будет «врать» по оси Z. Драйвер делает эту перестановку один раз внутри readRawHmc5883(), поэтому наружу (readRaw()) обе версии чипа отдают показания в одинаковом порядке X, Y, Z — вызывающему коду не нужно знать, какой чип реально на плате.

4. Калибровка Hard-Iron: без неё никак

Идеальный магнитометр в идеальном мире при повороте на 360° нарисует на графике X-Y идеальную окружность с центром в точке (0,0). В реальности рядом с чипом почти всегда есть металл — дорожки платы, корпус ESP32, крепёж — и эти предметы либо намагничены сами (Hard-Iron искажение — сдвигает центр окружности от нуля), либо искажают проходящее через них магнитное поле (Soft-Iron искажение — превращает окружность в эллипс).

Простой и понятный на школьном уровне способ скомпенсировать Hard-Iron — найти реальные границы (минимум и максимум) показаний по X и Y при полном повороте платы, и потом «сжать» эти границы обратно в диапазон -1..1:

x_calibrated = (x_raw - x_min) / (x_max - x_min) * 2 - 1

Именно так это реализовано в тестовом стенде: startCalibration() и updateCalibration() (main.cpp:66-100) в течение 30 секунд ищут xMin/xMax/yMin/yMax, а computeHeadingDeg() (main.cpp:39-52) применяет эту формулу перед расчётом угла. Soft-Iron (эллипс) эта простая калибровка не устраняет полностью, но для школьного проекта точности в несколько градусов обычно достаточно.

Калибровочные границы не хранятся в драйвере — они зависят от конкретной платы, её крепления и того, что рядом с ней в момент калибровки. Драйвер отдаёт только сырые показания; калибровка — задача тестового стенда, которую нужно повторить, если сильно изменилось окружение датчика (например, плату перенесли на металлический корпус робота).

5. От вектора поля к азимуту

Зная скомпенсированные X и Y, направление на магнитный север — это угол вектора (X, Y) на плоскости, который вычисляется через atan2:

heading = atan2(y_calibrated, x_calibrated)

atan2 (в отличие от обычного atan) сразу учитывает знаки обеих координат и возвращает угол во всех четырёх четвертях, поэтому не нужно вручную разбирать случаи “X отрицательный” и т.п. — main.cpp:45.

6. Магнитное склонение: магнитный север ≠ географический

Магнитный полюс Земли не совпадает с географическим полюсом, поэтому магнитометр указывает не совсем туда, куда показывает компас на карте. Разница между ними — магнитное склонение — зависит от того, где вы находитесь, и медленно меняется год от года. Готового универсального значения нет: MAGNETIC_DECLINATION_DEG в main.cpp:10 нужно подставить под свой регион (например, по данным magnetic-declination.com) — компонент намеренно не содержит “зашитого” значения для одного конкретного города.

Подключение GY-271

Схема

     ESP32                    GY-271
  ┌───────────┐             ┌─────────────┐
  │       3V3 ├─────────────┤ VCC         │
  │       GND ├─────────────┤ GND         │
  │    GPIO21 ├─────────────┤ SDA         │
  │    GPIO22 ├─────────────┤ SCL         │
  └───────────┘             └─────────────┘

Всего 4 провода — питание и шина I2C. Пины I2C_SDA/I2C_SCL заданы в main.cpp:4-5 — при необходимости смените их под свою распиновку.

Таблица пинов

Датчик рассчитан на питание 3.3V — не подавайте 5V, это может повредить чип.

Подтяжка линий I2C

На большинстве готовых модулей GY-271 подтягивающие резисторы SDA/SCL к 3.3V уже впаяны на плату. Если используете «голый» чип без модуля-переходника, добавьте резисторы порядка 4.7 кОм самостоятельно.

Какой чип на моей плате?

Внешне платы GY-271 с HMC5883L и QMC5883L почти неотличимы, а распиновка у них одинаковая — схема подключения не зависит от того, какой чип реально установлен. Драйвер сам определяет чип программно при begin() (см. README.md), поэтому на этапе подключения достаточно просто собрать схему выше.

План занятия: «Какой чип у меня на самом деле?» — GY-271

Формат: один урок 40-45 минут. Аудитория — 14-17 лет, базовое знакомство с Arduino/C++ и ESP32 приветствуется, но не обязательно.

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

Блок I. Физика (7-10 минут)

Вопрос классу: «Как в смартфоне работает компас, если там нет магнитной стрелки?»

• Внутри GY-271 — не стрелка, а чип, чувствительный к магнитному полю Земли по трём осям (X, Y, Z).
• Принцип — анизотропный магниторезистивный эффект: полоски сплава внутри чипа меняют электрическое сопротивление под действием магнитного поля.
• Подробности — THEORY.md, раздел 1.

Блок II. Детектив: какой чип у меня на плате? (10 минут)

• Схема подключения — 4 провода, показать WIRING.md.
• Завязка: платы называются одинаково — “GY-271”, — но внутри могут стоять разные чипы разных производителей: Honeywell HMC5883L (старее) или QST QMC5883L (новее). У них разные I2C-адреса (0x1E и 0x0D) и разные внутренние “языки” (наборы регистров).
• Запускаем код, смотрим, что печатает main.cpp при старте — какой чип реально нашёлся (main.cpp:121-127). У кого-то в классе будет один чип, у кого-то другой — и оба варианта работают одинаково, потому что драйвер сам разобрался, с кем говорит (Gy271Compass.cpp:5-20).
• Обсудить: почему это вообще возможно — драйвер просто пробует один адрес, потом другой, и по ответному “паспорту” чипа (ID-регистру) понимает, кто перед ним.

Блок III. Почему компас “врёт” без калибровки (12-15 минут)

• Ввести команду r — читаем сырые X/Y/Z. Положить плату неподвижно и повернуть её на 90°, 180° — посмотреть, как меняются числа.
• Объяснить Hard-Iron искажение: рядом с чипом всегда есть металл (дорожки платы, USB-разъём ESP32), который сам немного “магнитит” и сдвигает показания. Из-за этого без калибровки азимут будет посчитан неверно.
• Ввести команду c — 30 секунд вращать плату во всех плоскостях. Показать на экране, как программа ищет минимум и максимум по X и Y (main.cpp:77-100).
• Обсудить формулу компенсации (перевод в диапазон -1..1) — THEORY.md, раздел 4. Не обязательно требовать от всех вывести формулу самостоятельно — важно понимание “зачем” и “что происходит на экране во время вращения”.

Блок IV. Калибровка и практика

• Запустить tools/compass_view.py — живая стрелка компаса на экране вместо строк текста:

  cd tools
  pip install -r requirements.txt
  python3 compass_view.py <порт>
  (Serial Monitor прошивки на это время нужно закрыть.)
• До калибровки — стрелка дёргается и врёт. После калибровки (c) — стрелка стабильно указывает в одну сторону при повороте платы. Это самый наглядный момент занятия — эффект калибровки виден сразу на графике.
• Каждый переносит свои значения xMin/xMax/yMin/yMax, полученные после калибровки, в константы main.cpp (main.cpp:17-21).
• По желанию — подобрать магнитное склонение для своего города (magnetic-declination.com) и подставить в MAGNETIC_DECLINATION_DEG (main.cpp:10), чтобы курс показывал именно географический север, а не магнитный.

Вопросы для обсуждения

1. Почему один и тот же код работает с разными платами GY-271? Драйвер не считает заранее, какой чип должен быть — он пробует оба известных I2C-адреса и по ID-регистру определяет, кто ответил.

2. Зачем нужна калибровка, если чип и так измеряет магнитное поле? Металл рядом с датчиком (плата, корпус, крепёж) искажает измерения предсказуемым, но индивидуальным для каждой сборки образом. Калибровка компенсирует именно эти искажения, а не недостатки самого чипа.

3. Почему для HMC5883L данные читаются в порядке X, Z, Y, а не X, Y, Z? Так устроен физический порядок регистров в этом конкретном чипе по даташиту производителя — это не ошибка, а особенность железа, которую нужно знать и явно учитывать в коде.

4. Почему магнитное склонение не зашито в компонент одним числом? Оно зависит от географического положения и медленно меняется во времени — единственное “правильное” число для всех не существует.

Материалы для раздачи

• Схема подключения из WIRING.md.
• Таблицы регистров обоих чипов из THEORY.md.
• Готовый шаблон кода (src/main.cpp) — ученики фокусируются на калибровке и склонении, а не на написании драйвера с нуля.