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


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

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

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


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

Ручная установка библиотеки подразумевает перемещение папки с библиотекой в папку, в которой Arduino IDE будет эту библиотеку искать. Таких папок две: одна находится в папке с программой (C:\Program Files (x86)\Arduino\libraries), и вторая находится по пути, указанному в настройках. По умолчанию это Документы/Arduino. Я рекомендую устанавливать библиотеки в папку с программой, так как этот путь не содержит кириллицы и проблем с ним никогда не возникнет. Перемещать библиотеку в папку библиотек нужно так, чтобы в папке с названием библиотеки были файлы библиотеки (файлы с расширениями .h, .cpp, файл keywords, папка examples…).

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


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

Большинство библиотек публикуется на сайте GitHub, у неподготовленного человека могу возникнуть проблемы со скачиванием файлов с этого ресурса. Допустим, вы наткнулись на какую-то интересную библиотеку и захотели её скачать. Например, IRLremote – библиотека для работы с ИК приёмниками. Неважно, в какую папку репозитория вы попали – всегда можно нажать на название библиотеки (Имя автора/Название репозитория) и попасть на главную страницу репозитория.

С главной страницы можно скачать весь репозиторий как архив, нажав Clone or download, затем Download ZIP. Данный способ универсален для всех библиотек.

Таким образом вы скачаете исходный код библиотеки, в котором могут быть не относящиеся к самой библиотеке файлы. Большинство авторов выпускают релизные версии библиотек, которые находятся во вкладке Releases:

Со вкладки Releases можно загрузить архив с библиотекой нужной версии

Также GitHub позволяет открыть для чтения или скачать единичный файл из репозитория. Для этого нужно открыть файл и нажать кнопку Raw

“Внутри” библиотеки


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

<название библиотеки>.h – заголовочный файл, самый главный файл библиотеки. Он настолько главный, что библиотека может состоять только из него одного. Находится обычно в корне библиотеки, либо в папке src (source, исходник). В этом файле обычно перечислены все классы/методы/функции/типы данных, находится информация о библиотеке, часто встречается расширенное описание для каждого метода или функции. Очень часто главный заголовочный файл является мини-документацией на библиотеку. Библиотека может иметь многофайловую структуру с большим количеством заголовочных файлов, но главный заголовочный файл всегда один, он имеет такое же название, как папка с библиотекой.

Файл с расширением .cpp – файл реализаци, в котором находится основной исполнительный код программы. Обычно идёт парой к своему заголовочному .h файлу, т.е. <название библиотеки>.cpp.

keywords.txt – файл, в котором перечислены подсвечиваемые в Arduino IDE (выделенные другим цветом) в коде названия функций, методов и прочих рабочих имён библиотеки.

Файл library.properties – файл, содержащий информацию о библиотеке для агрегаторов и менеджеров библиотек (название, версия, автор, категория и проч.)

Папка src – в этой папке могут находиться основные файлы библиотеки (.h, .cpp, .c).

Папка examples – папка с примерами использования библиотеки.

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

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


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

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

Посмотрим примеры, которые лежат в папке с библиотекой:

/*
 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
 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 (я прикладываю весь код после описания)

#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())
    • И некоторые другие 

*Длина импульса – сервопривод управляется ШИМ сигналом с определённой длиной импульса, длина эта на максимальный и минимальный угол поворота серво отличается у разных производителей (минимум – 450-600, максимум – 2000-2400), поэтому библиотека серво является очень универсальным инструментом!

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

Важные страницы


  • Каталог ссылок на дешёвые Ардуины, датчики, модули и прочие железки с AliExpress у проверенных продавцов
  • Подборка библиотек для Arduino, самых интересных и полезных, официальных и не очень
  • Полная документация по языку Ардуино, все встроенные функции и макро, все доступные типы данных
  • Сборник полезных алгоритмов для написания скетчей: структура кода, таймеры, фильтры, парсинг данных
  • Видео уроки по программированию Arduino с канала “Заметки Ардуинщика” – одни из самых подробных в рунете
Последнее обновление Сентябрь 03, 2019
2019-09-03T21:05:38+03:00