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

Мой первый запуск RTClib закончился, не начавшись: компилятор выдал RTClib.h: No such file or directory, хотя архив с GitHub я скачал и даже распаковал. Виноват был сам — папка лежала на рабочем столе, а не в libraries скетчбука. Второй заход уже скомпилировался, но вместо даты монитор выдал кашу из кракозябр: в скетче стояло 9600 бод, а окно монитора было настроено на 115200. Обе ловушки проходят за минуту, если знать порядок действий — его и зафиксируем в этом уроке.

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

Забавная деталь напоследок: пока библиотека не установлена, IDE подсвечивает именно строку include, а не то место, где вы объявляете объект. Первая ошибка всегда выглядит как проблема кода, а не окружения — я привык проверять установку библиотек раньше, чем перечитывать собственный скетч.

Правильный путь — менеджер библиотек самой IDE: меню Sketch → Include Library → Manage Libraries (сочетание Ctrl+Shift+I), в строке поиска набираем RTClib, выбираем релиз от Adafruit и жмём Install. IDE сама предложит доустановить зависимость — Adafruit BusIO, — соглашаемся, это не опция, а рабочая деталь: без неё компиляция упадёт с другим, менее очевидным сообщением. Пошагово весь механизм с скриншотами и тонкостями версий разобран в уроке про менеджер библиотек в один клик.

Можно и вручную: распаковать архив в папку libraries внутри скетчбука (Документы/Arduino/libraries) и перезапустить IDE. Способ рабочий, но каждый апдейт — снова руками, а версия может встать в противоречие с зависимостями. Менеджер обновляет всё одной кнопкой, поэтому для RTClib я с тех пор не делаю исключений.

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

После установки зафиксируйте, что вы получили: одна библиотека на три семейства чипов. В ней лежат классы RTC_DS1307, RTC_DS3231 и RTC_PCF8523 — разница для вашего кода только в имени объявляемого объекта. Везде ниже работаю с RTC_DS3231: он точный и самый ходовой на типовых модулях ZS-042.

Первая строка после создания объекта — rtc.begin(). Она поднимает шину I2C и стучится к чипу; если модуля нет или перепутаны провода, метод вернёт false, и у вас есть шанс напечатать внятное сообщение вместо молча глючной программы. Чип отвечает на адресе 0x68; сама шина и её два провода — тема урока I2C: два провода, а живая проверка адресов делается сканером из соседнего урока.

Вторая проверка — rtc.lostPower(). Внутри DS3231 живёт служебный флаг OSF: если основное питание пропадало и счёт времени останавливался, флаг поднимается и честно говорит «время мусорное, я его не вёл». Логика шапки получается такая: begin — потом если lostPower вернул true, ставим время заново, иначе молча работаем дальше. Именно эта ветка спасает от главной ловушки строки adjust — перезаписи честно сохранённых часов при каждой перепрошивке.

Сама установка выглядит одной строкой: rtc.adjust(DateTime(F(__DATE__), F(__TIME__))). Два служебных макроса компилятора разворачиваются в дату и время сборки скетча, а обёртка F() убирает строки во флеш — экономия ОЗУ на Atmega328 копеечная, но привычка хорошая: я разбирал её отдельно в уроке про макрос F и экономию памяти.

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

Вызов rtc.now() возвращает объект DateTime — снимок текущего момента. У снимка есть методы-геттеры: year(), month(), day(), hour(), minute(), second(). Все они возвращают числа, поэтому форматирование — на вашей стороне: функция print2 из скетча дописывает ведущий ноль, чтобы 9:05 не выглядело как 9:5. Числа вместо готовых строк — это удобно и для логики (сравнивать час с семью проще, чем парсить текст), и для графиков: пары вида имя=значение в выводе дружат с Serial Plotter.

Темп вывода подбирайте по задаче. Раз в секунду — для тикающих часов, раз в пять — когда дата нужна только в журнале. Каждая печать при 9600 бод стоит на строку около миллисекунды, поэтому и двадцать символов в цикле — это десятки миллисекунд тишины: не критично, но понимать масштаб стоит уже сейчас.

Если дата печатается, а время стоит на месте — не спешите обвинять чип: чаще всего loop() блокирован чем-то долгим, либо снимок сделан один раз в setup() и печатается по кругу. Вызов rtc.now() обязан стоять внутри loop() — иначе вы смотрите на фото, а не на живые часы.

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

Библиотека стоит, время стоит, дата идёт в монитор — каркас готов. Пара привычек из моей практики: копируйте шапку с проверками в каждый новый RTC-скетч целиком, а не переписывайте по памяти; и держите отдельный скетч-минимум из трёх строк для проверки нового модуля — если в нём begin молчит, виновато железо, а не ваша логика. Третья привычка — печатать в шапке версию библиотеки: когда через год найдёте скетч в архиве, эта строка объяснит, почему он ведёт себя иначе.

Следующий шаг — научиться работать с объектом DateTime по-настоящему: вытаскивать отдельные поля, переводить момент в unix-время, сравнивать и вычитать. Без этого даже идеальные часы остаются просто мигающей строкой, а с этим превращаются в инструмент планирования.