Используем библиотеки

Библиотеки являются очень мощным инструментом при работе с Ардуино, особенно для новичка. Библиотека является файлом (набором файлов), содержащим точно такой же С++ код, на котором мы пишем скетч. Мы можем подключить библиотеку в свой код и использовать возможности, которые она даёт, а вариантов там весьма много: готовые "инструменты" для работы с внешними датчиками и модулями, для работы с внутренней периферией микроконтроллера (таймеры, АЦП, память), библиотеки различных математических инструментов и многое многое другое. Мой личный список интересных библиотек, составленный за годы работы с платформой, можно посмотреть здесь.

Прелесть работы с библиотекой заключается в том, что нам необязательно знать, каким образом работает код внутри неё, мы просто пользуемся готовыми инструментами, которые предоставил разработчик. Очень часто к библиотекам есть описание/документация и примеры использования.

Хотите написать свою библиотеку? Читайте урок.

Как установить библиотеку

Как я уже говорил, библиотека это набор текстовых файлов с кодом. Библиотеку можно установить двумя способами: из официального репозитория или вручную. У Ардуино есть своя база библиотек (около 4000), которые можно устанавливать и обновлять прямо из Arduino IDE при помощи встроенного менеджера библиотек. Это удобно, но в этом списке есть не все существующие библиотеки. Переходим в Скетч/Подключить библиотеку/Управлять библиотеками... Откроется менеджер библиотек, в котором можно найти и в один клик установить библиотеку из списка.
Ручная установка библиотеки подразумевает перемещение папки с библиотекой в папку, в которой Arduino IDE будет эту библиотеку искать. Таких папок две: одна находится в папке с программой:

  • 64-битная версия Windows – C:\Program Files (x86)\Arduino\libraries\
  • 32-битная версия Windows – C:\Program Files\Arduino\libraries\

Вторая находится по пути, указанному в настройках. По умолчанию это Документы/Arduino. Я рекомендую устанавливать библиотеки в папку с программой, так как этот путь не содержит кириллицы и проблем с ним никогда не возникнет. Перемещать библиотеку в папку библиотек нужно так, чтобы в папке с названием библиотеки были файлы библиотеки (файлы с расширениями .h, .cpp, файл keywords, папка examples...).

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

Где брать библиотеки?

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

Большинство библиотек публикуется на GitHub, у неподготовленного человека могу возникнуть проблемы со скачиванием файлов с этого ресурса. Допустим, вы наткнулись на какую-то интересную библиотеку и захотели её скачать. Например, IRLremote - библиотека для работы с ИК приёмниками. Неважно, в какую папку репозитория вы попали - всегда можно нажать на название библиотеки (Имя автора/Название репозитория) и попасть на главную страницу:   С главной страницы можно скачать весь репозиторий как архив, нажав Clone or download, затем Download ZIP. Данный способ универсален для всех библиотек.
Таким образом вы скачаете исходный код библиотеки, в котором могут быть не относящиеся к самой библиотеке файлы. Большинство авторов выпускают релизы, которые находятся во вкладке Releases:   Со вкладки Releases можно загрузить архив с библиотекой нужной версии   Также GitHub позволяет открыть для чтения или скачать единичный файл из репозитория. Для этого нужно открыть файл и нажать кнопку Raw

Решение конфликтов

Если Arduino IDE найдёт на компьютере несколько одинаковых библиотек, будет конфликт. Об этом сообщается в логе компиляции предупреждением: "несколько библиотек найдено... используется то, не используется сё". Если вы ставили некоторые библиотеки через менеджер, они будут воевать с библиотеками, установленными вручную в папку с программой. Где вообще лежат библиотеки?

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

Конфликтовать могут и ядра, поэтому решением всех проблем может стать чистая установка Arduino IDE с удалением остатков от предыдущей версии. Удаляем программу через "Установку и удаление программ" и вручную сносим папки:

  • Папка с программой
    • 64-битная версия Windows – C:\Program Files (x86)\Arduino\libraries\
    • 32-битная версия Windows – C:\Program Files\Arduino\libraries\
  • Документы\Arduino\
  • C:\Users\username\AppData\Local\Arduino15\

"Внутри" библиотеки

Библиотека, в зависимости от объема кода и настроения программиста, может быть оформлена как очень компактно, так и подробно, с кучей файлов и дополнительных папок. Рассмотрим классический состав библиотеки. Для удобства работы рекомендую включить видимость расширений файлов (Windows).

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

  • название_библиотеки.h - заголовочный файл, самый главный файл библиотеки. Он настолько главный, что библиотека может состоять только из него одного. Находится обычно в корне библиотеки, либо в папке src (source, исходник). В этом файле обычно перечислены все классы/методы/функции/типы данных, находится информация о библиотеке, часто встречается расширенное описание для каждого метода или функции. Часто заголовочный файл является мини-документацией на библиотеку.
  • Файл с расширением .cpp - файл реализаци, в котором находится основной исполнительный код программы. Обычно идёт парой к своему заголовочному .h файлу, т.е. название_библиотеки.cpp.
  • keywords.txt - файл, в котором перечислены подсвечиваемые в коде названия функций, методов и прочих рабочих имён библиотеки.
  • Файл library.properties содержит информацию о библиотеке для менеджера библиотек (название, версия, автор, категория и проч.)
  • Папка src - в этой папке могут находиться основные файлы библиотеки (.h, .cpp, .c).
  • Папка examples - папка с примерами использования библиотеки. Помимо перечисленных файлов и папок в папке с библиотекой могут находиться и другие служебные файлы и папки, иногда можно встретить даже полную документацию в виде текстовых файлов или html страниц.

Как работать с библиотекой?

Допустим, вы купили какой то модуль или датчик, загуглили по нему информацию, нашли статью с примером. Примеры обычно простенькие, показать как подключается и работает. Скачали библиотеку из статьи, попробовали, всё работает. Что дальше? Дальше следует открыть папку с библиотекой и посмотреть официальные примеры, разобраться как они работают и что умеют. Примеры находятся в папке examples в папке с библиотекой. Примеры обычно не раскрывают всех возможностей библиотеки, поэтому открываем и читаем заголовочный файл, который название_библиотеки.h. В нем можно найти буквально список инструментов библиотеки, очень часто с описанием для каждого. Вооружившись этой информацией, можно выжать из инструмента все возможности, которые ему прописал разработчик библиотеки.

Давайте рассмотрим стандартную библиотеку Servo, я думаю большинство с ней уже работали (смотри мой видеоурок по работе с Servo). Посмотрим примеры, которые лежат в папке с библиотекой:

Knob.ino
/*
 Controlling a servo position using a potentiometer (variable resistor)
 by Michal Rinott <http://people.interaction-ivrea.it/m.rinott>

 modified on 8 Nov 2013
 by Scott Fitzgerald
 http://www.arduino.cc/en/Tutorial/Knob
*/

#include <Servo.h>

Servo myservo;  // create servo object to control a servo

int potpin = 0;  // analog pin used to connect the potentiometer
int val;    // variable to read the value from the analog pin

void setup() {
  myservo.attach(9);  // attaches the servo on pin 9 to the servo object
}

void loop() {
  val = analogRead(potpin);            // reads the value of the potentiometer (value between 0 and 1023)
  val = map(val, 0, 1023, 0, 180);     // scale it to use it with the servo (value between 0 and 180)
  myservo.write(val);                  // sets the servo position according to the scaled value
  delay(15);                           // waits for the servo to get there
}
Sweep.ino
/* Sweep
 by BARRAGAN <http://barraganstudio.com>
 This example code is in the public domain.

 modified 8 Nov 2013
 by Scott Fitzgerald
 http://www.arduino.cc/en/Tutorial/Sweep
*/

#include <Servo.h>

Servo myservo;  // create servo object to control a servo
// twelve servo objects can be created on most boards

int pos = 0;    // variable to store the servo position

void setup() {
  myservo.attach(9);  // attaches the servo on pin 9 to the servo object
}

void loop() {
  for (pos = 0; pos <= 180; pos += 1) { // goes from 0 degrees to 180 degrees
    // in steps of 1 degree
    myservo.write(pos);              // tell servo to go to position in variable 'pos'
    delay(15);                       // waits 15ms for the servo to reach the position
  }
  for (pos = 180; pos >= 0; pos -= 1) { // goes from 180 degrees to 0 degrees
    myservo.write(pos);              // tell servo to go to position in variable 'pos'
    delay(15);                       // waits 15ms for the servo to reach the position
  }
}

Из этих примеров мы узнали, что есть класс Servo, и нужно создать объект этого класса. В блоке setup() мы можем указать, к какому пину подключена серво (метод attach()), и можем повернуть серво на нужный угол (в градусах) при помощи метода write(). Это в принципе всё, что мы узнали из официального примера.

Теперь откроем заголовочный файл Servo.h, который находится в папке src:

Servo.h
#define Servo_VERSION           2     // software version of this library

#define MIN_PULSE_WIDTH       544     // the shortest pulse sent to a servo  
#define MAX_PULSE_WIDTH      2400     // the longest pulse sent to a servo 
#define DEFAULT_PULSE_WIDTH  1500     // default pulse width when servo is attached
#define REFRESH_INTERVAL    20000     // minumim time to refresh servos in microseconds 

#define SERVOS_PER_TIMER       12     // the maximum number of servos controlled by one timer 
#define MAX_SERVOS   (_Nbr_16timers  * SERVOS_PER_TIMER)

#define INVALID_SERVO         255     // flag indicating an invalid servo index

#if !defined(ARDUINO_ARCH_STM32F4)

typedef struct  {
  uint8_t nbr        :6 ;             // a pin number from 0 to 63
  uint8_t isActive   :1 ;             // true if this channel is enabled, pin not pulsed if false 
} ServoPin_t   ;  

typedef struct {
  ServoPin_t Pin;
  volatile unsigned int ticks;
} servo_t;

class Servo
{
public:
  Servo();
  uint8_t attach(int pin);           // attach the given pin to the next free channel, sets pinMode, returns channel number or 0 if failure
  uint8_t attach(int pin, int min, int max); // as above but also sets min and max values for writes. 
  void detach();
  void write(int value);             // if value is < 200 its treated as an angle, otherwise as pulse width in microseconds 
  void writeMicroseconds(int value); // Write pulse width in microseconds 
  int read();                        // returns current pulse width as an angle between 0 and 180 degrees
  int readMicroseconds();            // returns current pulse width in microseconds for this servo (was read_us() in first release)
  bool attached();                   // return true if this servo is attached, otherwise false 
private:
  uint8_t servoIndex;               // index into the channel data for this servo
  int8_t min;                       // minimum is this value times 4 added to MIN_PULSE_WIDTH    
  int8_t max;                       // maximum is this value times 4 added to MAX_PULSE_WIDTH   
};

Что мы можем узнать из этого кода? Достаточно много всего интересного!

  • Минимальный импульс - 544 мкс
  • Максимальный импульс - 2400 мкс
  • Стандартный импульс после attach() - 1500 мкс - значит серво повернётся на соответствующий угол после подключения!
  • Максимальное количество серво можно узнать, выведя дефайн MAX_SERVOS в порт (Serial.print(MAX_SERVOS);) - для Arduino NANO это будет 12 штук
  • В классе Servo мы можем увидеть методы, которые не были раскрыты в примерах:
    • Версия attach() с возможностью указать мин. и макс. длину импульса вручную
    • detach() - отключить серво от управления
    • writeMicroseconds() - подать управляющий сигнал в мкс, а не в градусах
    • read() - считать текущее положение серво (последнее отправленное через write())
    • И некоторые другие

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

 

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

5 1 голос
Рейтинг статьи
Обновлено
Подписаться
Уведомить о
guest

10 комментариев
Старые
Новые Популярные
Межтекстовые Отзывы
Посмотреть все комментарии
Прокрутить вверх