APDS-9960 — датчик приближения

APDS-9960 — датчик приближения (Proximity)

Компонент опрашивает оптический датчик APDS-9960 по I2C и отдаёт сырое значение приближения объекта (0-255). Работает и с оригинальным чипом Broadcom/Avago, и с распространённым на рынке клоном — подробнее о том, почему это важно и как их отличить, см. THEORY.md.

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

Файлы

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

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

Полная схема, включая важное примечание про пин VL, — в WIRING.md.

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

1. Собрать схему по WIRING.md.
2. Прошить: pio run -e esp32dev -t upload.
3. Открыть Serial Monitor на 115200 бод.
4. При старте датчик сообщает свой ID (см. main.cpp:19-29) — оригинал, известный клон или неопознанный чип. Любой из трёх статусов означает, что можно работать дальше.
5. Поднося руку к датчику, наблюдать изменение Prox: в мониторе.

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

Serial Monitor с текстовыми числами — не самый наглядный формат для группы учеников. tools/proximity_view.py читает тот же вывод и рисует живой график PDATA с линиями текущих порогов калибровки:

cd tools
pip install -r requirements.txt
python3 proximity_view.py /dev/ttyUSB0   # порт по умолчанию — /dev/ttyUSB0

Serial Monitor прошивки на момент запуска скрипта должен быть закрыт — иначе порт занят и Python не сможет его открыть. Подробнее, зачем нужен этот график и что на нём смотреть, — Lesson.md, блок IV.

Калибровка порогов

Драйвер намеренно не решает, какое значение считать “близко” — сырой разброс PDATA сильно отличается от экземпляра к экземпляру (см. THEORY.md, раздел “Проблема клонов”). Пороги THRESHOLD_NEAR/CLOSE/VERY_CLOSE заданы как пример в main.cpp:12-14 — их нужно подобрать под свой датчик, ориентируясь на реальные показания в Serial Monitor.

API драйвера

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

Полный разбор — в THEORY.md. Здесь только таблица соответствия коду (Apds9960.h:29-33):

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

• Диапазон значений PDATA — 0-255, но реальный “рабочий” диапазон зависит от конкретного экземпляра датчика (клоны, состояние оптики, засветка).
• Gesture и ALS/RGB не реализованы (см. выше).
• Если Prox всегда равен 0 при поднесённой руке — проверьте перемычку VL, см. WIRING.md.

Теория: как APDS-9960 «видит» приближение

1. Инфракрасный дальномер на пальцах

Внутри APDS-9960 спрятаны две вещи:

• ИК-светодиод — светит невидимым для человека светом с длиной волны 940 нм (для сравнения: видимый нам свет — это 400-700 нм, а 940 нм — уже глубоко в инфракрасном диапазоне, том самом, которым «светят» пульты от телевизора).
• Фотодиод — ловит отражённый от объекта свет.

Логика простая: чем ближе объект, тем больше ИК-света от него отражается обратно на фотодиод. Датчик не измеряет расстояние в сантиметрах напрямую — он измеряет интенсивность отражённого света и превращает её в число 0-255 через встроенный АЦП. Это число называется PDATA, и именно его возвращает readProximity() (Apds9960.cpp:21-23).

Важное следствие: PDATA — это не линейная шкала сантиметров. Тёмная матовая ткань отразит меньше света, чем светлая глянцевая поверхность, даже на одинаковом расстоянии. Поэтому пороги калибруются экспериментально (см. раздел 4), а не берутся по формуле «сантиметры → PDATA».

2. Как ESP32 разговаривает с датчиком: I2C

APDS-9960 подключается всего 4 проводами, из которых два — SDA и SCL — образуют шину I2C. Это «общая линия связи», на которой может сидеть сразу несколько устройств — у каждого свой адрес. У APDS-9960 адрес фиксированный:

static constexpr uint8_t kAddress = 0x39;

(Apds9960.h:29)

Когда ESP32 хочет что-то прочитать, она сначала «стучится» по этому адресу и называет номер регистра (ячейки памяти внутри чипа), а затем запрашивает данные. Это видно в readRegister() (Apds9960.cpp:44-53): сначала beginTransmission + write(reg), затем requestFrom, который запрашивает ответ.

Каждая I2C-транзакция может провалиться (обрыв провода, дребезг питания, неверная перемычка) — поэтому в драйвере проверяется код возврата endTransmission() (Apds9960.cpp:45-56): если он не 0, чтение или запись считается неудачной, и наружу возвращается false, а не тихо подставляется старое/нулевое значение.

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

Регистр — это именованная ячейка памяти внутри чипа: что-то среднее между переключателем и почтовым ящиком. Источник — датащит Broadcom/Avago APDS-9960 (AV02-4191EN), раздел «Register Descriptions».

Значения kPPulseDefault = 0x10 и kControlDefault = 0xD0 (Apds9960.h:52-53) — это не «магия из даташита», а рабочая конфигурация (16 импульсов, средняя мощность ИК-диода и усиление x5), которая на практике даёт стабильные показания у большинства модулей на рынке. Если ваш датчик видит слишком близко или слишком далеко — это первое место для эксперимента.

4. Проблема клонов: когда чип «врёт» о себе

У каждого чипа есть регистр ID (0x92), по которому программа может проверить: «это точно тот чип, для которого я написана?». По даташиту оригинальный APDS-9960 должен ответить 0xAB.

Но на массовом рынке продаются модули с чипом, который отвечает 0xA8 — это не значит, что модуль сломан или это подделка, которая не работает. Это другая ревизия/клон того же по сути кристалла, который прекрасно измеряет приближение, но «представляется» другим именем. Классические библиотеки для оригинального APDS-9960 при виде 0xA8 обычно отказываются работать, потому что жёстко проверяют id == 0xAB.

Драйвер этого компонента устроен иначе — begin() не проваливается из-за неожиданного ID, а просто запоминает, что реально ответил чип (Apds9960.cpp:12-14). main.cpp при старте показывает три возможных статуса: оригинал, известный клон, или неопознанный чип — и в любом из трёх случаев proximity продолжает работать (main.cpp:19-29).

5. Калибровка: почему пороги — не часть драйвера

Пороги THRESHOLD_NEAR/CLOSE/VERY_CLOSE находятся не в Apds9960.h, а в main.cpp (main.cpp:12-14). Это осознанное решение: разброс сырых значений PDATA между экземплярами датчика (даже одной партии) достаточно большой, чтобы «зашитые» пороги подошли одному ученику и были бесполезны для другого. Драйвер честно отдаёт то, что измерил чип, а решение «что считать близко» — задача калибровки под конкретное железо и условия освещения в классе.

Числа в Serial Monitor скачут и их трудно оценить на глаз — нагляднее увидеть это на графике: tools/proximity_view.py рисует PDATA во времени вместе с линиями порогов, см. README.md, раздел «Визуализация».

6. Задержка после включения

После записи PON=1 в ENABLE чипу нужно время, чтобы «прогреться» — стабилизировать питание ИК-светодиода и АЦП. Даташит описывает только внутренние тайминги самого цикла измерения, а не время «безопасного» первого чтения после включения на реальном (не всегда качественном) модуле. Поэтому в begin() используется практический запас kPowerOnWarmupMs = 200 (Apds9960.h:58) — это эмпирическое значение с запасом, а не цифра из даташита.

Подключение APDS-9960

Схема

     ESP32                    APDS-9960
  ┌───────────┐             ┌─────────────┐
  │       3V3 ├─────────────┤ VCC         │
  │       GND ├─────────────┤ GND         │
  │    GPIO21 ├─────────────┤ SDA         │
  │    GPIO22 ├─────────────┤ SCL         │
  │     GPIO2 ├──[R 220Ω]──[LED]──┐        │
  │           │                  │        │
  │       GND ├──────────────────┘        │
  └───────────┘             └─────────────┘

GPIO2 со светодиодом — опционально, только для визуальной индикации приближения в тестовом стенде (main.cpp). Для самого датчика достаточно четырёх проводов VCC/GND/SDA/SCL.

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

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

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

Линиям SDA/SCL нужны подтягивающие резисторы к 3.3V (обычно 4.7 кОм), иначе шина не будет держать логическую единицу и обмен будет нестабильным. На большинстве готовых модулей APDS-9960 эти резисторы уже впаяны на плату — отдельно добавлять их нужно, только если вы используете «голый» чип без модуля-переходника.

Примечание про пин VL

Если при правильно собранной схеме Prox в Serial Monitor всегда равен 0 — проверьте напряжение на пине VL модуля. Если там 0V, соедините VL перемычкой с VCC. На большинстве современных модулей это соединение уже выполнено на заводе, но на части партий — нет, и датчик в таком случае физически не включает ИК-подсветку, хотя по I2C отвечает нормально.

Про пин INT

Для proximity-режима в этом компоненте пин прерывания (INT) не используется — опрос данных идёт напрямую через регистр PDATA методом polling (см. main.cpp:44), без аппаратных прерываний по порогу. Можно оставить его неподключённым.

План занятия: «Детектив в коде» — APDS-9960

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

Цель занятия: собрать рабочий датчик приближения, столкнуться с реальной инженерной проблемой (чип «врёт» о своём ID) и решить её через прямую работу с регистрами, а не просто скопировать готовый код.

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

Заводим разговор с вопроса: «Как ваш телефон понимает, что вы поднесли его к уху, и гасит экран?» — это тот же тип датчика.

• Показать электромагнитный спектр: видимый свет (400-700 нм) и ИК (940 нм у нашего датчика). Свет пульта от телевизора — тот же диапазон.
• Принцип: ИК-светодиод светит → отражается от объекта → фотодиод ловит → чем больше отражённого света, тем ближе объект.
• Подробности — THEORY.md, разделы 1.

Блок II. I2C и «детективная» завязка (10 минут)

• Схема подключения — 4 провода, показать WIRING.md.
• I2C как «общая линия с адресами»: наш датчик отвечает на 0x39.
• Сюжетный поворот: запускаем код, печатаем ID датчика — и он не совпадает с тем, что написано в даташите (0xAB)! Многие датчики на руках у учеников ответят 0xA8. Это не брак — это другая ревизия чипа на рынке.
• Обсудить: почему готовые библиотеки для APDS-9960 часто отказываются работать с такими модулями? (Они жёстко проверяют ID и останавливаются, если он не совпал.) Наш драйвер устроен иначе — см. Apds9960.cpp:12-14: он не паникует из-за незнакомого ID, а просто запоминает его и продолжает работу.

Блок III. Регистры и код (12-15 минут)

• Регистр — ячейка памяти внутри чипа, которой можно управлять напрямую. Таблица регистров — THEORY.md, раздел 3.
• Разобрать begin() построчно (Apds9960.cpp:5-19): выключили → прочитали ID → настроили мощность ИК-диода и импульсы → включили → подождали прогрев.
• Запустить прошивку, открыть Serial Monitor, увидеть живые цифры Prox:.
• Обсудить, почему readRegister/writeRegister проверяют код возврата endTransmission() (Apds9960.cpp:45-56) — провод может отвалиться в любой момент, и код должен это заметить, а не молча показывать последнее старое значение.

Блок IV. Калибровка и практика (10-15 минут)

• Запустить живой график tools/proximity_view.py на проекторе или на компьютере каждого ученика (pip install -r requirements.txt, затем python3 proximity_view.py <порт>, Serial Monitor прошивки при этом должен быть закрыт). Числа в тексте скачут и их трудно оценить на глаз — на графике сразу видно, где реально проходит рука относительно линий порогов.
• Задание классу: поднести руку на разных расстояниях, посмотреть на график.
• Обсудить, почему у соседа по парте кривая идёт иначе (разные экземпляры клонов, разная одежда/цвет руки, освещение в кабинете).
• Каждый подбирает свои THRESHOLD_NEAR/CLOSE/VERY_CLOSE в main.cpp:12-14 и добивается, чтобы линии порогов на графике проходили там, где удобно, а светодиод зажигался в нужный момент.
• Мини-кейсы для тех, кто закончил раньше:
  • Бесконтактный «выключатель» — датчик за листом бумаги/пластика.
  • Сигнализация: пищит/мигает, если рука дольше 2 секунд в зоне CLOSE.

Вопросы для обсуждения (можно использовать как проверку понимания)

1. Почему стандартная библиотека может не заработать сразу? Потому что она жёстко проверяет ID устройства (регистр 0x92) и останавливается, если он не совпал с ожидаемым. Наш драйвер этого не делает — см. блок II.

2. Зачем мы сами пишем в регистры PPULSE и CONTROL, а не полагаемся на настройки «по умолчанию»? Чтобы управлять физическими параметрами — мощностью ИК-подсветки и усилением приёмника — напрямую, а не гадать, что выставил производитель.

3. Почему пороги NEAR/CLOSE/VERY_CLOSE не зашиты в драйвер, а лежат в main.cpp? Потому что разброс сырых значений между экземплярами датчика большой — один порог не подойдёт всем. Калибровка — это часть работы с конкретным железом, а не константа библиотеки.

4. Почему в этом компоненте нет распознавания жестов? Инженерный компромисс: жесты требуют FIFO и заметно больше кода, а на клонах, которые чаще всего встречаются, работают нестабильно. Мы выбрали то, что стабильно работает на 100%, вместо красивой, но капризной функции.

Адаптация по уровню класса

• 7-8 класс: регистры — «магические числа», которые просто нужно оставить как есть. Фокус — собрать схему и подобрать пороги в main.cpp.
• 9-10 класс: добавить обсуждение датащита и протокола I2C — почему адрес 0x39, что такое beginTransmission/requestFrom.
• 11 класс / профиль: разобрать readRegister/writeRegister целиком, обсудить обработку ошибок шины и что означает isAlive() (Apds9960.cpp:32-34) — как отличить «объект далеко» от «датчик отвалился».

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

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