Своя библиотека Arduino: .h, .cpp, keywords.txt

Мой класс Button кочевал по скетчам копипастой уже третий год, и однажды подвал сделал то, что не сделал ни один компилятор: я поднял окно антидребезга со штатных пятидесяти до сотни миллисекунд для окисленных контактов — и внёс правку в три скетча из четырёх. Четвёртый, гаражные ворота, остался на пятидесяти и продолжал отстреливать двойные нажатия. Класс был хорош: сломалась логистика одной правки, размазанной по четырём файлам. Библиотека — способ хранить правку в одном месте и раздавать её пересборкой.

Разбирать библиотеку с нуля в IDE — карту папок, установку ZIP, подсветку — соседний курс уже сделал в уроке про сборку библиотеки за полчаса. Здесь — взгляд с другой стороны, со стороны компилятора: чем .ino отличается от .cpp, откуда берутся три самых частых сообщения при выносе кода в заголовок и реализацию, и почему у зрелых библиотек настройка железа живёт в begin(), а не в конструкторе.

Оговорка про симулятор ниже: движок не исполняет классы и не подключает пользовательские include, поэтому в симе библиотечная логика показана функциями на глобальных переменных — ровно та промежуточная ступень, из которой библиотека и вырастает. Полный Knopka.h и Knopka.cpp — в основном блоке для живой платы.

Скетч .ino среда дорабатывает за вас: подставляет include Arduino.h, генерирует прототипы функций, чтобы вызовы работали до объявления. Файл .cpp — отдельная единица трансляции, и среда ничего в него не добавляет: ни Arduino.h, ни прототипов. Отсюда первый классический промах новичка-автора: класс проверен в скетче, вынесен в Knopka.cpp — и компилятор внезапно не знает, что такое byte, millis или digitalRead. В .ino эти имена приходят сами, в .cpp их приносит только #include <Arduino.h> в заголовке библиотеки — и это не стилистика, а требование.

Раскладка такая: Knopka.h — интерфейс, класс с полями и перечнем методов; Knopka.cpp — реализация с префиксами Knopka::; guards #ifndef/#define/#endif страхуют от двойного включения заголовка. Короткий метод вроде isLow() из одной строки можно писать прямо в теле класса — компилятор разворачивает его на месте вызова; длинные тела уходят в .cpp. Мой ориентир по цене: вызов метода из .cpp добавляет пару тактов на call/ret — для кнопки с окном в сто миллисекунд это шум, а код читается как чужая библиотека, а не как общая тетрадь.

Третья деталь, которая экономит вечера: кавычки против угловых скобок. #include "Knopka.h" ищет заголовок рядом с файлом, #include <Arduino.h> — в стандартных путях. Путаница здесь не смертельна, но сообщения компилятора о ненайденном файле читаются хуже всего, когда ищешь сбой в коде, а он в точке над i.

Читаем по слоям. Guards построены на имени KNOPKA_H: первое включение ставит класс в файл, повторное — проскакивает мимо пустым. Кавычки в .cpp привязывают include к соседней папке, угловые скобки — к ядру. Конструктор только копирует аргументы в поля; pinMode ушёл в begin(); дефолтное окно 100 мс объявлено в заголовке — новые скетчи получают новое окно без единой правки вызовов, а вызовы Knopka(2, 50) с явным числом остаются при своих пятидесяти: контракт сохранён для тех, кому старое окно подходит.

Тело changed() в .cpp — обычный вызов метода, и это осознанный размен: пара тактов на прыжок против тела, размноженного по каждому вызову. isLow() остался в классе: одна строка с одним сравнением разворачивается на месте, и выносить её в .cpp значило бы терять такты на пустом месте. Поля как были приватными, так и остались: потребителю не нужно знать про lastReading — интерфейс из трёх методов закрывает всё.

keywords.txt в листинге — минимальный набор: класс в KEYWORD1, методы в KEYWORD2. Табуляция как разделитель, поддержка в IDE 2 и грабли формата — всё это уже разобрано в уроке про то, как чужие библиотеки подключаются из IDE, дублировать не буду; здесь файл приведён, чтобы библиотека из листинга собиралась до последней буквы.

Глобальные объекты создаются до main(): ещё не отработала инициализация ядра, Timer0 не тикает, millis() вернёт нули, Serial не поднят. Конструктор библиотеки, вызывающий Serial.begin или печатающий приветствие, выполнится в этот мёртвый период — и то, что на Uno pinMode из конструктора чаще всего «срабатывает», лишь маскирует ловушку: на других платах и ядрах порядок инициализации другой, и код молча ведёт себя по-разному. Отсюда контракт, по которому живут зрелые библиотеки: конструктор копирует простые аргументы, всё железо — в begin(), который пользователь зовёт в setup() в правильном порядке.

Мой личный билет в этот клуб: мигалка-объект с Serial.begin внутри конструктора печатала мусор один раз из трёх перезагрузок. Причина вскрылась не в коде класса, а в порядке запуска: на момент конструктора UART ещё не существовал. Перенос в begin() сделал поведение детерминированным — и заодно освободил конструктор от единственной обязанности, которую он выполнять не имел права. Если ваш класс считает время через millis() в конструкторе — вы храните мусор в поле lastChange с первой секунды жизни объекта: механика переполнения и отсчётов разобрана в уроке про переполнение millis.

Вторая половина контракта — что библиотека берёт на себя. Окно антидребезга у мягких и окисленных контактов — тема урока про механику дребезга: тактильным кнопкам хватает 50 мс, подвальным герконам просится 100. Дефолтный аргумент в заголовке делает это знание частью библиотеки: правка одной строки в Knopka.h раздаётся всем скетчам пересборкой — тот сценарий с воротами, с которого начался урок, больше не повторится.

Когда классу место в отдельной вкладке, а когда в библиотеке: вкладка — деталь конкретного скетча, умирает вместе с ним; библиотека переживает проекты. Мой рубеж сместился с «третьего копипаста» соседнего курса на более честный: второй скетч, которому нужен тот же класс. Два скетча — уже система, а не совпадение, и правка, размноженная на два файла, к четвёртому обязательно забудется. Проверка интерфейса у меня та же, что у соседей: новый скетч пишется без подглядывания в Knopka.cpp — что потребовало подглядывания, промах интерфейса, а не слабая память.

Дистрибуция коротко: папка со всеми файлами переносится в sketchbook — карта папок в уроке про структуру sketchbook, раскладка версий и дубликатов в уроке про ZIP-установку. Примеры в examples/ добавьте сразу: подпапка с именем скетча внутри, тот самый Vorota.ino из листинга — через полгода ваш собственный пример покажет быстрее, чем чтение собственной реализации. Домашнее: добавьте в Knopka метод pressedFor(), возвращающий millis() - lastChange, пока кнопка нажата, и второй пример KnopkaDveri с сигналом при удержании дольше двух секунд.