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

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

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

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

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

void setup() {
}

void loop() {
}

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

Так как мы пишем на C/C++, то можем пользоваться некоторыми библиотеками для этих языков, например алгоритмами шифрования или какими-то математическими инструментами. Также есть и специальные библиотеки под Arduino-фреймворк - большинство из них работают на всех поддерживаемых платформах (МК и платах). На момент написания урока в официальном реестре содержится ~7500 библиотек! Arduino - народная и открытая платформа, поэтому кто угодно может написать свою библиотеку и добавить её в реестр (урок о добавлении в реестр) - она появится в списке библиотек и будет доступна для установки через менеджер библиотек в IDE.

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

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

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

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

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

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

Arduino IDE устанавливается со стандартным набором библиотек, также каждая платформа и её компилятор содержат свой набор стандартных и системных библиотек:

• Стандартные общие библиотеки - Папка с программой/libraries
  • 64-битная версия Windows – C:/Program Files (x86)/Arduino/libraries/
  • 32-битная версия Windows – C:/Program Files/Arduino/libraries/
• Установленные через менеджер + стандартный набор - Документы/Arduino/libraries
• Библиотеки для конкретной платформы:
  • Стандартная AVR Arduino - C:/Program Files (x86)/Arduino/hardware/arduino/avr/libraries
  • Другие платформы - C:/Users/username/AppData/Local/Arduino15/packages/платформа/hardware/платформа/версия/libraries

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

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

Менеджер библиотек #

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

Вручную #

Для установки вручную у вас должен быть скачан архив с библиотекой - с сайта разработчика или с 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, мы уже используем библиотеку. Работая со строками или используя математические функции - тоже. Да, это всё можно написать своими руками, но вряд-ли получится лучше, чем десятилетиями отлаженный и оптимизированный код стандартных библиотек.

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