Arduino.ru
Данный документ описывает создание библиотеки для Arduino. Объяснение начнется с написания скетча передачи кода Морзе посредством светодиода. Затем будет показано как конвертировать скетч в библиотеку. Это позволит другим пользователям легко использовать созданный код, обновлять и дополнять его.
Скетч, воспроизводящий код Морзе:
int pin = 13; void setup() < pinMode(pin, OUTPUT); >void loop() < dot(); dot(); dot(); dash(); dash(); dash(); dot(); dot(); dot(); delay(3000); >void dot() < digitalWrite(pin, HIGH); delay(250); digitalWrite(pin, LOW); delay(250); >void dash()
Данный скетч посредством мигания светодиода на выводе 13 выдает сигнал SOS.
Скетч содержит ряд частей кода, которые необходимо будет перенести в библиотеку. Во-первых, это функции dot() и dash(), которые управляют миганием светодиода. Во-вторых, это переменная ledPin, определяющая какой порт ввод/вывода использовать. И наконец, вызов функции pinMode(), устанавливающий режим вывода на используемом порту ввода/вывода.
Процесс конвертации скетча в библиотеку.
Библиотека содержит два файла: заголовочный файл (с расширением .h) и файлы реализации (с расширением .cpp). Заголовочный файл содержит характеристики библиотеки, т.е. список всего что содержится в ней. Создаваемый заголовочный файл будет называться Morse.h. Для дальнейшей работы с заголовочным файлом необходимо просмотреть содержание файла реализации.
Заголовочный файл содержит класс, в котором объявляются функций и используемые переменные:
class Morse < public: Morse(int pin); void dot(); void dash(); private: int _pin; >;
Класс в данном случае это набор функций и переменных, объеденных в одном месте. Функции и переменные могут быть публичными (public), что означает общий доступ к ним всех, кто использует библиотеку, или частными (private), что означает доступ к ним только внутри класса. Каждый класс имеет специальную функцию конструктор, которая используется для создания экземпляра класса. Конструктор имеет тоже имя, что и класс, но не имеет типа возвращаемого значения.
Также заголовочный файл содержит еще несколько дополнительных строк. Во-первых, это директива #include, которая дает доступ к стандартным типам и постоянным языка программирования Arduino (директива по умолчанию добавляется к каждому скетчу, но не к библиотеке). Директива выглядит следующим образом (и находится выше объявления класса):
#include "WProgram.h"
В версиях Arduino 1.0 и выше нужно еще добавить:
#include Arduino.h
Также принято заключать содержимое заголовочного файла в следующую конструкцию:
#ifndef Morse_h #define Morse_h // директивы #include и код помещается здесь #endif
Это предотвращает повторное подключение нашей библиотеки, если кто-то по ошибке дважды подключит библиотеку директивой #include.
В начале кода библиотеки принято помещать комментарий о ее предназначении, авторе, дате и лицензии на библиотеку.
Готовый заголовочный файл содержит:
/* Morse.h - Library for flashing Morse code. Created by David A. Mellis, November 2, 2007. Released into the public domain. */ #ifndef Morse_h #define Morse_h #include "WProgram.h" class Morse < public: Morse(int pin); void dot(); void dash(); private: int _pin; >; #endif
Рассмотрим файл реализации Morse.cpp.
В начале кода находятся несколько директив #include. Данными директивами разрешается доступ к стандартным функциям Arduino и к характеристикам в головном файле библиотеки:
#include "WProgram.h" #include "Morse.h"
Далее по коду находится конструктор. Он используется для создания экземпляра создаваемого класса. В данном случае пользователь задает номер используемого порта ввода/вывода через параметр. Порта устанавливается в режим вывода, а номер сохраняется в частной переменной для использования в других функциях:
Morse::Morse(int pin)
Код Morse:: означает, что функция принадлежит классу Morse. Нижний пробел в начале имени переменной _ pin — принятое обозначение для частных переменных. Вообще, имя может быть любое, но согласно принятым конвенциям именования для частных переменных принято использовать префикс «_». Это также позволяет отличить от аргумента функции (в данном случае pin).
Далее код, который конвертируется в библиотеку из изначального скетча, добавилось только Morse:: и изменилось имя переменной с pin, на _pin:
void Morse::dot() < digitalWrite(_pin, HIGH); delay(250); digitalWrite(_pin, LOW); delay(250); >void Morse::dash()
Общепринято помещать некоторые поясняющие комментарии в начале кода файла реализации. Полный код библиотеки:
/* Morse.cpp — Library for flashing Morse code. Created by David A. Mellis, November 2, 2007. Released into the public domain. */ #include «WProgram.h» #include «Morse.h» Morse::Morse(int pin) < pinMode(pin, OUTPUT); _pin = pin; >void Morse::dot() < digitalWrite(_pin, HIGH); delay(250); digitalWrite(_pin, LOW); delay(250); >void Morse::dash()
Использование библиотеки.
Во-первых, необходимо создать папку Morse в подпапке libraries директории блокнота. Во-вторых, требуется скопировать файлы Morse.h и Morse.cpp в созданную папку. После запуска программы Arduino в меню Sketch > ImportLibrary будет находиться библиотека Morse. Библиотека будет компилироваться совместно со скетчами, использующими ее. Если при компиляции библиотеки возникли проблемы, то необходимо проверить, чтобы ее файлы были с расширениями .cpp и .h (не должно быть никаких дополнительных расширений .pde и .txt).
Изначальный скетч, переписанный с использованием созданной библиотеки, будет выглядеть следующим образом:
#include Morse morse(13); void setup() < >void loop()
Несколько отличий от изначального скетча:
Во-первых, добавлена директивы #include в начало скетча. Таким образом определяется доступность библиотеки Morse и ее подключение. Неиспользуемую библиотеку можно удалить, убрав директиву #include.
Во-вторых, создается экземпляр класса Morse, называемый morse:
Morse morse(13);
При выполнении данной строки (перед выполнением функции setup()) вызывается конструктор для класса Morse и принимает аргумент, данный в примере (13).
При этом функция setup() ничего не содержит, т.к. вызов функции pinMode() произошел внутри библиотеки (когда был создан экземпляр класса).
В-третьих, для вызова функций dot() и dash() необходимо прибавить префикс morse. – имя используемого экземпляра. Может быть несколько экземпляров класса Morse, каждый со своим номером порта, хранящимся в локальной переменной _pin. Вызовом функции конкретного экземпляра определяются какие переменные, используются во время вызова. При наличии следующих двух строк:
Morse morse(13); Morse morse2(12);
внутри вызова morse2.dot(), переменная _pin будет иметь значение 12.
К сожалению автоматическая подсветка кода не работает с подключаемыми библиотеками. Для того чтобы подсветка заработала необходимо создать файл с названием keywords.txt. Пример:
Morse KEYWORD1 dash KEYWORD2 dot KEYWORD2
Напротив каждой строки через табуляцию стоит зарезервированное слово, и опять через табуляцию тип слова. Классы соответствуют зарезервированному слову KEYWORD1 и окрашены в оранжевый цвет; функции – KEYWORD2 и окрашены в коричневый. Для распознавания слов необходимо перезапустить среду разработки Arduino.
Созданную библиотеку желательно всегда сопровождают примером ее применения. Для этого создается папка examples в директории Morse. Затем копируется созданный ранее скетч SOS в данную папку. (Файл скетча можно найти через меню Sketch > ShowSketchFolder). После перезапуска Arduino в меню File > Sketchbook > Examples будет находиться пункт Library-Morse, содержащий пример. Также необходимо добавить комментарии о том, как лучше использовать библиотеку.
Установка библиотек в Arduino IDE
Многие скетчи (программы) работают с библиотеками. Библиотека облегчает работу с определённым модулем или одним из типов модулей. Например, если Вы хотите вывести текст на LCD дисплей без подключения библиотеки, то Вам нужно передать ему несколько байт команд и данных, что займет несколько строк кода, а главное, что Вам нужно знать тип микроконтроллера под управлением которого работает LCD дисплей, назначение команд которыми он управляется, знать архитектуру его памяти, адреса и назначение регистров, для чего потребуется найти и перечитать его datasheet. В то время как при написании кода с использованием библиотеки (например LiquidCrystal_I2C.h) Вы сможете вывести текст на дисплей вызвав всего одну функцию библиотеки: lcd.print(«my text»);
Перед тем как начать пользоваться методами и функциями библиотеки, её нужно скачать (загрузить на Ваш компьютер), установить (разместить в нужной папке) и подключить (вставить текст «#include » в скетч).
Скачивание библиотеки:
Если в наших уроках, описаниях или примерах используется библиотека, то мы указываем ссылку на скачивание этой библиотеки. Все наши библиотеки находятся в zip архиве, но не спешите доставать файлы из архива, это может не понадобиться, т.к. Arduino IDE сама может распаковывать архивы и размещать библиотеки в нужных папках (см. дальше).
Если Вы скачали архив библиотеки с сайта не указывая путь для сохранения файла, то скаченный (загруженный) Вами файл скорее всего находится в папке: Этот компьютер > Загрузки.
Установка библиотеки:
После того как Вы скачали (загрузили) библиотеку на свой компьютер, её нужно установить. Установить библиотеку можно вручную или сделать это средствами Arduino IDE:
Установка библиотеки средствами Arduino IDE:
Войдите в меню: Скетч > Подключить библиотеку > Добавить .ZIP библиотеку. .
В появившемся окне нажмите на иконку «Этот компьютер» и выберите папку «Загрузки». Если при скачивании ZIP архива с сайта, Вы указывали путь для сохранения файла, то вместо папки «Загрузки» укажите путь к файлу.
Выберите ZIP файл библиотеки, который Вы скачали. Название файла может не соответствовать названию библиотеки. После чего нажмите на кнопку «Открыть» (Open).
На этом установка библиотеки завершена, можно приступить к её подключению в скетч.
Установка библиотеки вручную:
Распакуйте скаченный Вами ZIP архив и поместите папку (имя папки обычно совпадает с названием библиотеки) из данного архива в папку: Этот компьютер > Документы > Arduino > libraries.
Если во время копирования Arduino IDE была запущена (открыта), то нужно закрыть все окна этой программы, после чего запустить (открыть) Arduino IDE и можно приступать к подключению библиотеки в скетч.
Примечание: папка libraries есть не только по указанному выше пути, но и в папке программы Arduino IDE (где находится файл arduino .exe). Скопировав библиотеку в эту папку, она тоже установится, но Мы не рекомендуем это делать. Дело в том, что программа Arduino IDE постоянно развивается и количество её версий постоянно растёт. Если Вы захотите установить новую версию Arduino IDE, то библиотеки находящиеся в папке Этот компьютер > Документы > Arduino > libraries, будут доступны и в старой, и в новой (установленной) версии Arduino IDE, а библиотеки находящиеся в папке libraries программы Arduino IDE старой версии (которая была установлена ранее) будут доступны только в ней (пока Вы их не скопируете в новую).
Подключение библиотеки:
Для того чтобы подключить библиотеку, нужно написать всего одну строку в начале скетча: «#include «, например:
#include // Подключение библиотеки iarduino_4LED для работы с 4 сегментными LED индикаторами.
Некоторые библиотеки работают используя методы и функции других библиотек, тогда нужно подключать две библиотеки, сначала подключается та, методы и функции которой использует вторая, например:
#include // Подключение библиотеки Wire для работы с шиной I2C #include // Подключение библиотеки LiquidCrystal_I2C для работы с LCD дисплеем по шине I2C // Библиотека LiquidCrystal_I2C использует методы и функции библиотеки Wire
Для работы с большинством библиотек, нужно создать объект (экземпляр класса библиотеки), через который будут доступны их функции и методы, например:
LiquidCrystal_I2C lcd(0x27,20,4); // lcd это объект библиотеки LiquidCrystal_I2C // через объект обращаются к функциям и методам библиотеки
Вместо lcd можно написать любое слово или сочетание букв и цифр, это название объекта через который можно обращаться к методам и функциям библиотеки. Если Вместо lcd Вы написали myLCD, то и ко всем методам и функциям библиотеки LiquidCrystal_I2C, нужно обращаться через указанное Вами имя объекта, например: myLCD.print(«my text»);
Примеры из библиотек:
Большинство библиотек содержат примеры. Это небольшие скетчи (программы) которые раскрывают функционал библиотеки. Наиболее удобный способ просмотра примеров, с помощью средств Arduino IDE. Выберите пункт меню: Файл > Примеры, откроется список с названиями библиотек у которых есть примеры. Наведите курсор на название библиотеки и Вы увидите список примеров содержащихся в ней, клик на примере приведёт к появлению нового окна Arduino IDE со скетчем примера.
Альтернативный способ просмотра примеров заключается в запуске файлов скетчей из папки:
путь > libraries > название библиотеки > examples > название примера.
Поиск библиотек:
Библиотеки можно искать самостоятельно, а можно воспользоваться функционалом Arduino IDE.
Выберите пункт меню: Скетч > Подключить библиотеку > Управлять библиотеками. .
Откроется «Менеджер библиотек», в котором можно найти интересующую Вас библиотеку введя её название в строку поиска, дополнительно можно установить пункты «Тип» и «Тема».
Нажатие на описании библиотеки приведёт к появлению вкладки «Версия» и кнопки «Установка». После нажатия на кнопку «Установка» можно приступать к подключению библиотеки в скетч «#include «.
Как сделать библиотеку для ардуино
Как только вы освоитесь с программным обеспечением Ардуино и в совершенстве овладеете стандартными функциями, вам наверняка захочется расширить возможности вашего Ардуино с помощью дополнительных библиотек.
Что такое библиотека?
Библиотека — это набор функций, предназначенных для того, чтобы максимально упростить работу с различными датчиками, ЖК-экранами, модулями и пр. Например, встроенная библиотека LiquidCrystal позволяет легко взаимодействовать с символьными LCD-экранами. Существуют сотни дополнительных библиотек, которые можно скачать в Интернете. Стандартные библиотеки Ардуино и ряд наиболее часто используемых дополнительных библиотек перечислены в справке. Но перед тем, как использовать дополнительные библиотеки, необходимо сперва установить их.
Как установить библиотеку
Чаще всего библиотеки выкладываются в виде ZIP-архива или просто папки. Название этой папки является названием библиотеки. Внутри папки будет файл с расширением .cpp, файл с расширением .h, а также текстовый файл keywords.txt, папка с примерами examples и другие файлы, требуемые библиотекой.
Автоматическая установка
Начиная с версии 1.0.5, устанавливать сторонние библиотеки можно прямо в среде разработки.
Не распаковывайте скачанный архив с библиотекой — оставьте его, как есть.
В среде разработки Ардуино выберите меню Sketch > Import Library. В самом верху выпадающего списка выберите пункт Add Library (Добавить библиотеку).
Появится диалоговое окно, предлагающее вам выбрать библиотеку, которую вы хотели бы добавить. Перейдите к скачанному zip-файлу и откройте его.
Снова откройте меню Sketch > Import Library. Вы должны увидеть новую библиотеку в самом низу выпадающего списка. Теперь библиотеку можно использовать в программах.
zip-файл будет уже распакован в директории libraries внутри вашей рабочей папки Ардуино.
Примечание: после выполнения указанных действий библиотеку можно будет полноценно использовать в своих программах, однако примеры из установленной библиотеки появятся в меню File > Examples только после перезапуска среды Ардуино.
Установка вручную
Перед установкой библиотеки закройте среду разработки Ардуино.
Затем распакуйте ZIP-архив с библиотекой. Допустим, вы устанавливаете библиотеку «ArduinoParty» — распакуйте файл ArduinoParty.zip. В нем должна быть папка ArduinoParty с файлами ArduinoParty.cpp и ArduinoParty.h. (Если файлы с расширением .cpp и .h лежат не в папке, то необходимо ее создать. В данном случае вам нужно создать папку с именем ArduinoParty и перенести в нее все файлы из ZIP-архива, например — ArduinoParty.cpp и ArduinoParty.h).
Перетащите папку ArduinoParty в директорию с библиотеками Ардуино. В Windows она будет лежать примерно здесь: «My Documents\Arduino\libraries», у пользователей Mac — здесь: «Documents/Arduino/libraries», а в Linux-системах директория «libraries» будет внутри рабочей папки со скетчами.
После перемещения ваша директория с библиотеками должна выглядеть примерно так (под Windows):
My Documents\Arduino\libraries\ArduinoParty\ArduinoParty.cpp My Documents\Arduino\libraries\ArduinoParty\ArduinoParty.h My Documents\Arduino\libraries\ArduinoParty\examples .
Documents/Arduino/libraries/ArduinoParty/ArduinoParty.cpp Documents/Arduino/libraries/ArduinoParty/ArduinoParty.h Documents/Arduino/libraries/ArduinoParty/examples .
и аналогично на Linux.
Помимо файлов .cpp и .h здесь могут быть и другие файлы — просто убедитесь, что все они теперь лежат здесь.
(Если файлы .cpp и .h расположены в корне папки «libraries» или вложены внутрь еще одной папки, то скачанная библиотека работать не будет. Например:
Documents\Arduino\libraries\ArduinoParty.cpp and Documents\Arduino\libraries\ArduinoParty\ArduinoParty\ArduinoParty.cpp
— не рабочий пример.)
Перезапустите среду Ардуино. Убедитесь, что новая библиотека появилась в меню Sketch->Import Library.
Вот и все! Вы установили библиотеку!
В основе этого урока лежит текст автора Limor Fried.
Текст данного руководства опубликован под лицензией Creative Commons Attribution-ShareAlike 3.0. Примеры кода, встречающиеся в руководстве, являются свободным контентом.
Создание собственной библиотеки для Arduino
Arduino использует C++, поэтому, библиотеку придётся писать на этом языке. Для новой библиотеки нужно создать дополнительный класс с кодом, который будет взаимодействовать с устройством.
Нам понадобится один заголовочный файл .h, в котором будет описан ваш класс с функциями, константами. А также второй файл .cpp, в котором все эти объявленные функции и константы реализуются.
Для начала создадим в папке ..\libraries собственную папку с именем библиотеки, например, Kitty.
Внутри папки Kitty создаём файлы kitty.h и kitty.cpp.
Библиотеки нужно писать на C++. Если внутри нашей библиотеки используем какие-нибудь функции или объекты из стандартной библиотеки Arduino, то следует подключать соответствующий заголовочный файл Arduino.h.
#include "Arduino.h"
Есть два используемых способа создания класса. Если экземпляр класса может быть только один, то объявляется экземпляр в этом же .h-файле. Примеры таких классов — HardwareSerial, Serial.
Заголовочный файл не содержит выполняемого кода, а лишь определяет имена классов и методов в библиотеке.
Полностью заголовочный файл будет следующего содержания.
/* Kitty.h - Library for cats. Created by Alexander Klimov, December 12, 2018. Released into the public domain. */ #ifndef kitty_h #define kitty_h #include "Arduino.h" class Kitty < public: Kitty(); void init(); void meow(); private: int _counter; >; #endif
Команда #ifndef предотвращает многократный импорт библиотеки.
Закрытый раздел private содержит переменную. В нашем примере она просто для демонстрации и не используется.
В общедоступном разделе public указаны конструкторы и методы.
Теперь реализуем созданные функции в файле kitty.cpp:
#include "Arduino.h" #include "kitty.h" // конструктор вызывается всегда при создании экземпляра класса Kitty Kitty::Kitty() < >void Kitty::init() < Serial.begin(9600); >// просто говорим "Meow" void Kitty::meow()
Теперь нужно перезапустить Arduino IDE, если она у вас была запущена. Откройте меню Sketch | Include Library. Если всё было сделано правильно, то увидите собственную библиотеку.
После создания библиотеки вы можете вносить изменения, которые будут учитываться автоматически.
Если выбрать свою библиотеку, то в скетче появится строка:
#include
Это означает, что библиотека подключена и мы можем её использовать в скетче.
#include Kitty kitty; // создаём экземпляр нашего класса void setup() < kitty.init(); >void loop() < kitty.meow(); // мяукаем в Serial Monitor delay(1000); >
Запускаем скетч, открываем Serial Monitor и наблюдаем за мяуканьем кота. Жрать просит!
Правилом хорошего тона считается создать дополнительный файл keywords.txt и папку examples.
Файл keywords.txt содержит объявления ключевых слов вашей библиотеки, имена типов, методов, функций, констант. Это поможет редактору раскрасить указанные слова соответствующими цветами. Синтаксис файла (в качестве разделителя используйте TAB):
####################################### # Syntax Coloring Map For Kitty ####################################### ####################################### # Datatypes (KEYWORD1) ####################################### Kitty KEYWORD1 ####################################### # Methods and Functions (KEYWORD2) ####################################### meow KEYWORD2 init KEYWORD2 ####################################### # Constants (LITERAL1) #######################################
Перезапустите Arduino IDE ещё раз. Теперь названия вашего класса и её функций будут подсвечены.
В папке examples создаются примеры использования в формате pde. Создайте необходимый скетч, переименуйте его в нужный формат и снова перезапустите IDE. Примеры станут доступны для использования.
О созданной библиотеке можно сообщить сообществу на сайте playground.arduino.cc/Main/LibraryList. Можно создать zip-архив или выложить на GitHub.