Adafruit GFX и SSD1306: установка и первый скетч

Скетч с OLED-экраном из первого попавшегося гайда отказался собираться у меня на середине: компилятор остановился на строке include и выдал Adafruit_GFX.h: No such file or directory. Я первым делом грешил на железо — переподключил провода, прогнал сканер шины, переткнул модуль в другую макетку. Провода были ни при чём: не хватало библиотеки, о которой в гайде ни слова. Автор ставил её настолько давно, что забыл упомянуть, — а я час искал обрыв в схеме.

Вторая грабля ждала сразу после установки. Менеджер библиотек спросил, поставить ли зависимости, и я, торопясь, ответил отказом. Скетч даже собрался, но на плате ушёл в бесконечную перезагрузку, и я снова подозревал экран, пока не открыл список установленных библиотек: одна из трёх отсутствовала.

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

Adafruit GFX — графическое ядро, общее для доброй дюжины дисплеев: OLED на SSD1306 и SH110X, цветные TFT на ST7735 и ILI9341, даже некоторые модули электронной бумаги. Шрифты, координатная сетка, setCursor, print и графические примитивы живут именно здесь, и программный интерфейс у всех экранов один: выучил один раз — рисуешь на любом. Практический вывод для нас: текстовый код из этого раздела без единого изменения перенесётся на цветной TFT, если однажды проект перерастёт монохром. Ядро обновляется вместе с драйверами, и его интерфейс стабильнее самого железа: код, написанный сегодня под SSD1306, соберётся и с завтрашней версией библиотеки.

Adafruit_SSD1306 — драйвер конкретного контроллера. Он знает, какими командами инициализировать SSD1306, где у того видеопамять и как переливать кадр по I2C. Внутри он опирается на GFX и добавляет своё: begin(), буфер кадра и display(). Пара «ядро плюс драйвер» повторяется по всей экосистеме Adafruit — Adafruit_ST7735, Adafruit_SH110X, Adafruit_SSD1325 — механика всюду одинаковая, меняется только нижний слой команд.

Третья участница, Adafruit BusIO, — обёртка над Wire и SPI: транзакции шины, чтение и запись регистров. Когда-то этот код лежал внутри каждого драйвера, потом его вынесли в общую библиотеку, и с тех пор свежие версии драйверов требуют её отдельной установкой. Отсюда железное правило: ставите драйвер дисплея — соглашайтесь на все зависимости, которые менеджер предлагает кнопкой Install all. Экономия десяти секунд оборачивается часом непонятных падений.

Версии тоже живут своей жизнью. В старых скетчах из интернета цвета называются BLACK и WHITE, в новых — SSD1306_BLACK и SSD1306_WHITE; работают оба написания, но если чужой код не собирается, первым делом сравните свою версию библиотеки с той, под которую он писан, — это второй по частоте источник ошибок после отсутствующих зависимостей.

Установка занимает минуту. Инструменты → Управлять библиотеками (Ctrl+Shift+I), в фильтре набираете ssd1306, находите Adafruit SSD1306 от Adafruit, жмёте Install — и соглашаетесь, когда менеджер спросит про зависимости: одним махом встанут Adafruit GFX и Adafruit BusIO. Сам механизм мы уже прогоняли в уроке про менеджер библиотек — там же про версии, обновления и ручную установку архива. Если хотите понять, что вообще происходит, когда вы ставите библиотеку, — это разобрано в уроке про библиотеки в IDE.

Проверка, что всё встало: Файл → Примеры → Adafruit SSD1306 — там лежат примеры вроде ssd1306_128x64_i2c. Откройте, соберите: компиляция без ошибок означает, что все заголовки нашлись, а значит, и ваш скетч соберётся. Если пример вдруг не собирается, сверьте версию в карточке библиотеки с минимальной из README — авторы примеров обычно указывают её там. Если фильтр ничего не находит, проверьте, что тип поиска — All, и набирайте коротко: фильтр чувствителен к лишним словам вроде arduino и oled.

Для PlatformIO всё то же самое одной строкой в platformio.ini: lib_deps = adafruit/Adafruit SSD1306 — зависимости PlatformIO подтягивает сам и без вопросов. А в Arduino IDE 2.x окно менеджера то же, к чему мы привыкли: поиск, кнопка, готово.

И привычка, которая экономит вечера: сразу после установки залейте штатный пример на плату без единой правки. Это одновременный тест библиотек и железа — заставка мелькнула, значит, связка жива, и все дальнейшие проблемы будут только вашим кодом. Такой тест снимает половину вопросов, с которыми новички уходят на форумы.

Конструктор Adafruit_SSD1306 display(128, 64, &Wire, -1) ничего не включает — он только описывает экран. Первые два аргумента — размеры в пикселях: для модуля 128×32 их придётся поменять, иначе низ кадра окажется за краем памяти, потому что размеры описывают буфер, а не стекло. Третий — шина, через которую идёт общение, четвёртый — пин Reset: минус один значит, что сброс общий с платой. Всю настоящую работу делает begin(SSD1306_SWITCHCAPVCC, 0x3C): первый аргумент — питать контроллер от внутренней накачки заряда, второй — адрес на шине.

Внутри begin происходит три вещи: контроллер получает стартовые команды, в ОЗУ платы выделяются 1024 байта под буфер кадра и на экран заливается фирменная заставка Adafruit. Заставка — бесплатный тест: мелькнула, значит, шина жива, адрес верный, библиотеки работают. Тёмный экран после begin — проблема железная, и начинать надо со сканера I2C-адресов, а не с правки кода: два провода шины тоже иногда перепутаны.

После begin заставку затираем: clearDisplay, курсор в начало, текст, display(). Обратите внимание на пустой loop() в скетче выше: надпись рисуется один раз в setup, и дальше экран хранит её сам — контроллер SSD1306 непрерывно показывает содержимое собственной памяти и в участии Arduino не нуждается. Звать display() каждую итерацию цикла не нужно; когда это действительно требуется и что происходит в буфере между вызовами — тема следующего урока про буфер и display(). Слово «каркас» здесь не для красоты: сохраните скетч под коротким именем — за месяц раздела он обрастёт зонами и превратится в дашборд, а начинать каждый новый экран с пустого файла скучно.

Мелочь, которая сбивает: begin() сам вызывает Wire.begin(), отдельно шину стартовать не нужно. Если на той же шине висят часы или датчик, их инициализацию ставьте после begin() экрана — порядок не критичен, но единый шаблон setup() на все проекты избавляет от забытых инициализаций.

Каркас готов и проверен: библиотеки на месте, begin проходит, надпись на экране. Дальше по разделу — модель работы буфера: что именно делают clearDisplay и display(), почему кадр уходит целиком и откуда берётся дрожь, если торопиться с обновлениями. Скелет из этого урока сохраните в отдельный файл: он станет точкой старта всех экранов раздела, от дашбордов до меню. А если захочется копнуть саму шину — обратная дорога в раздел про Wire: экран будет отличным тихим клиентом для будущих экспериментов с мастером и слейвом.

Домашнее задание: установите связку вместе с зависимостями, залейте каркас и дождитесь заставки и надписи. Потом поменяйте в конструкторе 64 на 32 и посмотрите, что станет с текстом на модуле 128×64: нижняя половина покажет мусор старого кадра заставки — наглядное доказательство, что размеры в конструкторе описывают буфер, а не стекло. Верните 64 на место и двигайтесь дальше.