Использование библиотек

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

Компилятор содержит свой набор "стандартных" библиотек - для работы с памятью и строками, а также математические функции, типы данных и некоторые другие инструменты - эти библиотеки доступны "из коробки". Существуют и внешние библиотеки - например для датчика температуры, дисплея, алгоритма шифрования или протокола связи. Основная идея библиотеки в том, что она не связана с конкретным проектом - это универсальный инструмент, который можно использовать в разных программах. По сути Arduino - тоже в своём роде библиотека: в Arduino IDE автоматически подключается файл Arduino.h, в других IDE его нужно подключать вручную. Из него нам становятся доступны функции и прочие инструменты Ардуино-фреймворка, разобранные в рамках данного раздела уроков и в справочнике.

#include <Arduino.h>    // подключение "библиотеки" Arduino

void setup() {
}

void loop() {
}

Arduino-библиотеки #

Так как мы пишем на C/C++, то можем пользоваться некоторыми библиотеками для этих языков, например алгоритмами шифрования или математическими инструментами. Также есть специальные библиотеки под Arduino-фреймворк. Одни из них переносимы между многими платформами, другие завязаны на конкретную архитектуру, периферию или плату - совместимость нужно смотреть в описании и library.properties. В официальном реестре находятся тысячи библиотек (10'000 на момент написания урока). Arduino - народная и открытая платформа, поэтому разработчик может добавить свою библиотеку в реестр (урок о добавлении в реестр) - она появится в списке и станет доступна через менеджер библиотек IDE.

В среде Arduino существуют библиотеки для огромного количества популярных модулей и датчиков, причём как официальные от производителя, так и разные варианты от энтузиастов. Также библиотеки можно найти для большого количества программируемых микросхем, не оформленных в виде "модуля". Но есть и минусы - пользовательские библиотеки не всегда написаны хорошо и оптимально, а иногда и вовсе содержат баги и ошибки.

Большинство Arduino-библиотек распространяется с исходным кодом, но встречаются и смешанные варианты с заранее скомпилированными закрытыми компонентами. Возможность изменения и распространения определяет лицензия конкретной библиотеки.

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

• В реестре библиотек по названию модуля или чипа
• В поисковике по названию модуля с добавлением слова "Arduino", например lcd 1602 arduino - библиотека для дисплея 1602

Большая часть библиотек находится на GitHub - это сайт для хранения программ с открытым исходным кодом - проектов, библиотек, приложений, примеров и т.д. Страница проекта на GitHub называется репозиторием. Если библиотека есть в реестре - она есть и на GitHub: именно оттуда скачаются файлы библиотеки при установке через менеджер библиотек. Некоторых библиотек нет ни в реестре, ни на GitHub - они лежат на сайтах своих разработчиков, обычно это какие-то старые библиотеки, их нужно устанавливать вручную.

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

Библиотеки могут находиться в нескольких местах:

• Установленные пользователем и через менеджер - в папке libraries внутри Sketchbook, на Windows по умолчанию это Документы/Arduino/libraries
• Библиотеки конкретной платформы - внутри установленного пакета платы, на Windows обычно в AppData/Local/Arduino15/packages/...
• Библиотеки, поставляемые вместе с конкретной версией IDE или ядра

Точный путь зависит от версии IDE, операционной системы и настроенной папки Sketchbook. Редактировать библиотеки внутри пакетов платы не стоит - обновление может перезаписать изменения.

Установка библиотек #

Arduino IDE работает с библиотеками по принципу "общая папка со всеми библиотеками". Если в разных проектах требуются разные, несовместимые друг с другом версии одной библиотеки, то для компиляции программы придётся удалять и устанавливать нужную версию библиотеки перед сменой проекта. Для более комфортной работы рекомендуется использовать PlatformIO IDE - в ней библиотеки хранятся индивидуально в папке каждого проекта.

Встроенный менеджер библиотек #

В Arduino IDE есть встроенный менеджер библиотек, позволяющий установить библиотеку из реестра в один клик, а также обновить, удалить или установить конкретную версию. "Установка" просто скачает папку с библиотекой в Документы/Arduino/libraries (Windows):

"Внешний" менеджер библиотек #

Предлагаю своё решение проблемы с блокировками - программу ArdulibsManager. Она позволяет точно так же качать и обновлять библиотеки из официального реестра, но в обход сервисов Arduino - список библиотек, как и сами библиотеки, хранятся на GitHub. Программа совместима с Arduino IDE v1 и v2 и просто качает и читает библиотеки в той же папке, что и они.

Скачать свежую версию:

• Windows 64 bit: релиз, Яндекс.Диск
• Windows 32 bit: релиз, Яндекс.Диск

Вручную #

Для установки вручную у вас должен быть скачан архив с библиотекой - с сайта разработчика или с GitHub. Для скачивания самой свежей версии библиотеки с GitHub нужно открыть главную страницу репозитория, нажать Code/Download ZIP:

Для скачивания конкретной версии нужно перейти в раздел релизов Releases, найти нужную версию, раскрыть Assets и нажать Source code (zip) - скачается архив с библиотекой нужной версии:

Далее полученный архив можно установить через меню в IDE - она сама распакует его в папку с библиотеками:

Либо распаковать архив и положить его в Документы/Arduino/libraries (Windows) так, чтобы файлы библиотеки были сразу в папке с названием библиотеки, без подпапки:

Использование #

Структура #

• src папка с файлами самой библиотеки. Может отсутствовать, тогда файлы библиотеки лежат прямо в папке библиотеки
• examples - папка с примерами в формате .ino, чтобы их можно было открыть сразу в Arduino IDE
• README.md - описание библиотеки, содержимое этого файла отображается на главной странице репозитория. Может содержать документацию или ссылку на неё
• library.properties - системный текстовый файл с информацией о библиотеке для менеджера библиотек

Примеры #

После установки библиотеки её примеры появляются в списке примеров Arduino IDE:

Иногда бывает удобно изучать примеры онлайн - для этого достаточно открыть их в репозитории библиотеки на GitHub:

Подключение #

Библиотеки подключаются при помощи директивы #include с указанием нужного файла в <угловых скобках>. Какой именно нужен файл - смотрите в примерах к библиотеке: она может содержать несколько файлов, которые подключаются отдельно в зависимости от нужных инструментов.

Например - встроенная библиотека для известных вам String-строк. Она уже подключена внутри главного файла Arduino.h, поэтому для использования строк нам не нужно дополнительно её подключать. Но это можно сделать ещё раз - ничего страшного не случится:

#include <WString.h>

Документация #

Не все библиотеки содержат документацию или примеры, в которых раскрыты все возможности. В этом случае можно открыть исходник - часто там содержатся комментарии к инструментам библиотеки. Начинать надо с файла, который подключается в программу.

Класс #

Откройте WString.h (Ctrl+клик в IDE или в репозитории ядра). В нём мы увидим класс String, в котором перечислены все методы, некоторые даже содержат поясняющие комментарии.

Так как String - это класс, то для создания объекта будет использован конструктор. Смотрим, какие есть:

String(const char *cstr = "");
String(const String &str);
String(const __FlashStringHelper *str);

String(char c);
String(unsigned char, unsigned char base=10);
String(int, unsigned char base=10);
String(unsigned int, unsigned char base=10);
String(long, unsigned char base=10);
String(unsigned long, unsigned char base=10);
String(float, unsigned char decimalPlaces=2);
String(double, unsigned char decimalPlaces=2);

Отсюда видно, из каких типов данных можно создать строку, у некоторых есть дополнительные параметры. Если ничего не передавать в конструктор - будет создана пустая строка (самый первый конструктор - параметр по умолчанию ""). Можно создать сколько угодно экземпляров класса - по сути это просто переменные:

String s1;
String s2(1234);

Ниже находится список методов, которые можно применять к объекту строки. Например unsigned int length() - длина строки. Методы применяются через точку:

String s1;
String s2(1234);

Serial.println(s1.length());    // 0
Serial.println(s2.length());    // 4

Таким образом можно получить полное представление о возможностях библиотеки, в том числе недокументированных - например в той же библиотеке String для ESP8266 есть глобально созданная переменная emptyString - пустая строка, которой можно пользоваться в своих целях.

Другой пример - библиотека с функциями, например стандартная math.h. Откройте её - там будет набор математических функций, которыми можно пользоваться после подключения библиотеки в программу.

Библиотеки - это плохо #

В Сети можно часто встретить мнение, что библиотеки - это плохо и нужно писать без них. Так обычно пишут новички, которые ещё вчера мигали светодиодом. По сути, используя фреймворк Arduino, мы уже используем библиотеку. Работая со строками или используя математические функции - тоже. Да, это всё можно написать своими руками, но вряд ли получится лучше, чем десятилетиями отлаженный и оптимизированный код стандартных библиотек.

Что касается всяких "железок" - код для работы с ними всё равно придётся оборачивать в некий модуль, иначе проект превратится в кодовое полотно низкого качества, которое сложно дорабатывать и поддерживать. Также этот модуль можно будет использовать для другого проекта с этой железкой. Таким образом мы просто напишем свою библиотеку, вместо того, чтобы использовать чужую. Будет ли она лучше - вопрос открытый.

Дополнительно #

Полезные страницы #

• Набор GyverKIT – наш большой стартовый набор Arduino, продаётся в России
• Каталог ссылок на дешёвые Ардуины, датчики, модули и прочие железки с AliExpress
• Обратная связь – сообщить об ошибке в уроке или предложить дополнение по тексту (alex@alexgyver.ru)
• Поддержать автора за работу над уроками