Библиотеки Arduino IDE: установка, обновление и решение конфликтов

Библиотека — это чужой код, который избавляет от необходимости писать своё. Работа с дисплеем, датчиком температуры или сервоприводом умещается в три строки именно потому, что кто-то уже разобрался с их протоколом. Ниже — три способа поставить библиотеку, где она физически лежит, как обновлять и что делать, когда компилятор её не находит.

Что такое библиотека

С точки зрения Arduino IDE библиотека — это папка с исходниками и файлом-описанием library.properties. Внутри обычно так:

Servo/
|-- library.properties   описание: имя, версия, автор, архитектуры
|-- src/
|   |-- Servo.h          заголовок — его и подключают в скетче
|   +-- Servo.cpp        реализация
+-- examples/            готовые скетчи, попадают в File → Examples

В скетче библиотека подключается директивой #include с именем заголовочного файла:

#include <Servo.h>

Угловые скобки означают «ищи в системных путях и в папке libraries», кавычки — «ищи рядом со скетчем». Для установленных библиотек всегда используются угловые скобки.

Способ 1: менеджер библиотек

Основной способ — он же самый безопасный, потому что IDE сама следит за версиями и зависимостями.

1. Откройте Sketch → Include Library → Manage Libraries (Скетч → Подключить библиотеку → Управлять библиотеками) или нажмите на иконку книг на боковой панели в Arduino IDE 2.x.
2. Введите в поиск название или задачу — например, DHT sensor или OLED SSD1306.
3. Выберите нужную библиотеку, при необходимости укажите версию в выпадающем списке и нажмите Install.

Если у библиотеки есть зависимости, IDE предложит поставить их тоже — соглашайтесь. Отказ приведёт к ошибке компиляции при первом же #include.

Способ 2: установка из ZIP-архива

Так ставят библиотеки с GitHub, которых нет в менеджере.

1. На странице проекта нажмите Code → Download ZIP. Архив скачается с именем вида MyLibrary-master.zip.
2. В Arduino IDE: Sketch → Include Library → Add .ZIP Library.
3. Выберите скачанный архив. IDE распакует его в папку libraries сама.

Распаковывать архив вручную перед этим не нужно — среда ждёт именно .zip.

Способ 3: вручную

Иногда проще положить папку самому — например, когда библиотека лежит в вашем же репозитории или её прислали архивом без структуры.

Скопируйте папку библиотеки в каталог libraries и перезапустите Arduino IDE — список библиотек читается при старте.

Точный путь виден в настройках: File → Preferences → Sketchbook location. Папка libraries лежит внутри указанного каталога.

Требование одно: внутри папки должен быть заголовочный файл — либо прямо в корне, либо в подпапке src. Если после копирования библиотека не появилась, почти всегда дело во вложенности: распространённая ошибка — папка MyLibrary/MyLibrary/src вместо MyLibrary/src.

Встроенные библиотеки

Часть библиотек ставить не нужно — они приходят вместе с пакетом платы. Wire для I2C, SPI, EEPROM, WiFi и Preferences для ESP32 уже на месте сразу после установки пакета плат.

Такие библиотеки лежат не в вашей папке libraries, а внутри каталога пакета — там же, где компилятор. Трогать их руками не нужно: они обновляются вместе с пакетом платы через Boards Manager.

Отсюда следует практическое правило: если #include <WiFi.h> не находится, проблема не в библиотеках, а в том, что не выбрана плата ESP32 или не установлен её пакет. Разбор — в статье про настройку Arduino IDE для ESP32.

Обновление и удаление

Обновить библиотеку можно из того же менеджера: у установленных с доступной новой версией появляется кнопка Update. В Arduino IDE 2.x есть фильтр Type → Updatable, который показывает сразу все такие библиотеки.

Удалить через интерфейс можно только те, что ставились менеджером — кнопкой Remove. Библиотеки, добавленные из ZIP или вручную, удаляются только удалением папки из libraries с последующим перезапуском IDE.

Несколько версий одной библиотеки

Знакомое предупреждение при компиляции:

Multiple libraries were found for "OneWire.h"
  Used: /Users/me/Documents/Arduino/libraries/OneWire
  Not used: /Applications/Arduino.app/.../libraries/OneWire

Это не ошибка, а сообщение о выборе. Среда нашла несколько библиотек с одним и тем же заголовком и объяснила, какую взяла. Приоритет такой: сначала библиотеки из вашей папки libraries, потом те, что пришли с пакетом платы.

Проблема начинается, когда выбрана не та. Симптом характерный: компилятор ругается на функцию, которая в документации точно есть. Решение — удалить лишнюю копию, оставив одну.

Библиотеки и архитектура платы

В library.properties есть поле architectures. Оно перечисляет, для каких платформ библиотека предназначена: avr, esp32, samd, * для любых.

Если библиотека написана только под AVR, на ESP32 она либо не соберётся, либо соберётся и не заработает. Типичный пример — работа с таймерами и регистрами напрямую: у ATmega328P и ESP32 они устроены совершенно по-разному.

Менеджер библиотек показывает совместимость: при выбранной плате ESP32 несовместимые библиотеки помечаются или скрываются. Это ещё одна причина ставить библиотеки уже после того, как выбрана плата.

Ошибка «No such file or directory»

Самая частая ошибка вокруг библиотек выглядит так:

sketch.ino:1:10: fatal error: DHT.h: No such file or directory
 #include <DHT.h>
          ^~~~~~~

Проверяйте по порядку:

1. Библиотека установлена? Откройте менеджер и убедитесь, что рядом с ней стоит отметка об установке.
2. Имя файла совпадает? Регистр важен на macOS и Linux: #include <dht.h> не найдёт DHT.h. Windows такое прощает — отсюда «у автора работало».
3. Папка на месте? Загляните в libraries и проверьте, что заголовочный файл лежит в корне папки или в src, а не на два уровня глубже.
4. IDE перезапущена? После ручного копирования — обязательно.
5. Выбрана плата? Для WiFi.h, Preferences.h и других библиотек из пакета платы сначала должна быть выбрана сама плата.

Остальные ошибки компиляции разобраны отдельно — в статье про ошибки Arduino IDE.

Где искать библиотеки

• Менеджер библиотек — первое место. Всё, что там есть, прошло минимальную проверку и имеет описание.
• Arduino Library Reference — каталог тех же библиотек с документацией и примерами.
• GitHub — для свежих версий и того, что в каталог не попало. Смотрите на дату последнего коммита и количество открытых issue: заброшенная библиотека под новую версию ядра может не собраться.

Что дальше

• Разбор ошибок компиляции и загрузки — Ошибки Arduino IDE.
• Основы языка и структура скетча — Язык Arduino.
• Установка пакета плат ESP32 — Настройка Arduino IDE для работы с ESP32.