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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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