Arduino.ru
Написание библиотеки для Arduino
Данный документ описывает создание библиотеки для Arduino. Объяснение начнется с написания скетча передачи кода Морзе посредством светодиода. Затем будет показано как конвертировать скетч в библиотеку. Это позволит другим пользователям легко использовать созданный код, обновлять и дополнять его.
Скетч, воспроизводящий код Морзе:
Данный скетч посредством мигания светодиода на выводе 13 выдает сигнал SOS.
Скетч содержит ряд частей кода, которые необходимо будет перенести в библиотеку. Во-первых, это функции dot() и dash(), которые управляют миганием светодиода. Во-вторых, это переменная ledPin, определяющая какой порт ввод/вывода использовать. И наконец, вызов функции pinMode(), устанавливающий режим вывода на используемом порту ввода/вывода.
Процесс конвертации скетча в библиотеку.
Библиотека содержит два файла: заголовочный файл (с расширением .h) и файлы реализации (с расширением .cpp). Заголовочный файл содержит характеристики библиотеки, т.е. список всего что содержится в ней. Создаваемый заголовочный файл будет называться Morse.h. Для дальнейшей работы с заголовочным файлом необходимо просмотреть содержание файла реализации.
Заголовочный файл содержит класс, в котором объявляются функций и используемые переменные:
Класс в данном случае это набор функций и переменных, объеденных в одном месте. Функции и переменные могут быть публичными (public), что означает общий доступ к ним всех, кто использует библиотеку, или частными (private), что означает доступ к ним только внутри класса. Каждый класс имеет специальную функцию конструктор, которая используется для создания экземпляра класса. Конструктор имеет тоже имя, что и класс, но не имеет типа возвращаемого значения.
Также заголовочный файл содержит еще несколько дополнительных строк. Во-первых, это директива #include, которая дает доступ к стандартным типам и постоянным языка программирования Arduino (директива по умолчанию добавляется к каждому скетчу, но не к библиотеке). Директива выглядит следующим образом (и находится выше объявления класса):
В версиях Arduino 1.0 и выше нужно еще добавить:
Также принято заключать содержимое заголовочного файла в следующую конструкцию:
Это предотвращает повторное подключение нашей библиотеки, если кто-то по ошибке дважды подключит библиотеку директивой #include.
В начале кода библиотеки принято помещать комментарий о ее предназначении, авторе, дате и лицензии на библиотеку.
Готовый заголовочный файл содержит:
Рассмотрим файл реализации Morse.cpp.
В начале кода находятся несколько директив #include. Данными директивами разрешается доступ к стандартным функциям Arduino и к характеристикам в головном файле библиотеки:
Далее по коду находится конструктор. Он используется для создания экземпляра создаваемого класса. В данном случае пользователь задает номер используемого порта ввода/вывода через параметр. Порта устанавливается в режим вывода, а номер сохраняется в частной переменной для использования в других функциях:
Код Morse:: означает, что функция принадлежит классу Morse. Нижний пробел в начале имени переменной _ pin — принятое обозначение для частных переменных. Вообще, имя может быть любое, но согласно принятым конвенциям именования для частных переменных принято использовать префикс «_». Это также позволяет отличить от аргумента функции (в данном случае pin).
Далее код, который конвертируется в библиотеку из изначального скетча, добавилось только Morse:: и изменилось имя переменной с pin, на _pin:
Общепринято помещать некоторые поясняющие комментарии в начале кода файла реализации. Полный код библиотеки:
Использование библиотеки.
Во-первых, необходимо создать папку Morse в подпапке libraries директории блокнота. Во-вторых, требуется скопировать файлы Morse.h и Morse.cpp в созданную папку. После запуска программы Arduino в меню Sketch > ImportLibrary будет находиться библиотека Morse. Библиотека будет компилироваться совместно со скетчами, использующими ее. Если при компиляции библиотеки возникли проблемы, то необходимо проверить, чтобы ее файлы были с расширениями .cpp и .h (не должно быть никаких дополнительных расширений .pde и .txt).
Изначальный скетч, переписанный с использованием созданной библиотеки, будет выглядеть следующим образом:
Несколько отличий от изначального скетча:
Во-первых, добавлена директивы #include в начало скетча. Таким образом определяется доступность библиотеки Morse и ее подключение. Неиспользуемую библиотеку можно удалить, убрав директиву #include.
Во-вторых, создается экземпляр класса Morse, называемый morse:
При выполнении данной строки (перед выполнением функции setup()) вызывается конструктор для класса Morse и принимает аргумент, данный в примере (13).
При этом функция setup() ничего не содержит, т.к. вызов функции pinMode() произошел внутри библиотеки (когда был создан экземпляр класса).
В-третьих, для вызова функций dot() и dash() необходимо прибавить префикс morse. – имя используемого экземпляра. Может быть несколько экземпляров класса Morse, каждый со своим номером порта, хранящимся в локальной переменной _pin. Вызовом функции конкретного экземпляра определяются какие переменные, используются во время вызова. При наличии следующих двух строк:
внутри вызова morse2.dot(), переменная _pin будет иметь значение 12.
К сожалению автоматическая подсветка кода не работает с подключаемыми библиотеками. Для того чтобы подсветка заработала необходимо создать файл с названием keywords.txt. Пример:
Напротив каждой строки через табуляцию стоит зарезервированное слово, и опять через табуляцию тип слова. Классы соответствуют зарезервированному слову KEYWORD1 и окрашены в оранжевый цвет; функции – KEYWORD2 и окрашены в коричневый. Для распознавания слов необходимо перезапустить среду разработки Arduino.
Созданную библиотеку желательно всегда сопровождают примером ее применения. Для этого создается папка examples в директории Morse. Затем копируется созданный ранее скетч SOS в данную папку. (Файл скетча можно найти через меню Sketch > ShowSketchFolder). После перезапуска Arduino в меню File > Sketchbook > Examples будет находиться пункт Library-Morse, содержащий пример. Также необходимо добавить комментарии о том, как лучше использовать библиотеку.
Источник
Библиотека для ардуино своими руками
Этот документ поможет разобраться, как создавать библиотеки для Ардуино. Сначала будет рассмотрена программа, генерирующая сигналы азбуки Морзе, а затем даны пояснения, как вынести ее функции в отдельную библиотеку. Использование библиотек позволяет другим людям использовать написанный вами код, а также легко обновлять его по мере выхода новых версий вашей библиотеки.
Начнем с программы, генерирующий простой сигнал азбуки Морзе:
Если запустить эту программу, то можно убедиться, что она подает сигнал SOS (сигнал бедствия) светодиодом, подключенным к 13 выводу.
В программе есть несколько участков, которые нам необходимо объединить в библиотеку. Во-первых, конечно же, это функции dot() и dash(), которые и формируют сигнал. Во-вторых, это переменная pin, которая используется функциями для того, чтобы знать, с каким именно выводом необходимо работать. И, наконец, в программе есть вызов функции pinMode(), которая заставляет работать указанный вывод в качестве выхода.
Пора бы сделать из нашей программы библиотеку!
Для этого вам понадобится, по меньшей мере, два файла: заголовочный файл (с расширением .h) и файл с исходным кодом (с расширением .cpp). Заголовочный файл представляет собой описание библиотеки: чаще всего, это просто список всего, что в ней есть. Файл-исходник содержит непосредственно программный код библиотеки. Назовем нашу библиотеку «Morse», соответственно, наш заголовочный файл будет «Morse.h». Давайте посмотрим, что внутри этого файла. Поначалу содержимое файла может показаться вам немного странным, однако все станет на свои места, как только вы увидите исходник, идущий «в комплекте».
Структура заголовочного файла представляет собой набор строк, каждая из которых соответствует одной функции библиотеки. Эти строки находятся внутри класса, который также может включать в себя все необходимые переменные:
Класс — это просто набор функций и переменных, собранных в одном месте. Эти функции и переменные могут быть общедоступными (public) — т.е. могут вызываться людьми, работающими с вашей библиотекой, или внутренними (private) — которые видны только в пределах самого класса. У каждого класса есть специальная функция, называемая конструктором (constructor), которая предназначена для создания экземпляра (instance) класса. Конструктор имеет такое же имя, как и класс, и не возвращает никаких значений.
Помимо этого, есть еще несколько деталей, которые необходимо включить в заголовочный файл. Одна из них — это оператор #include, который позволяет подключить к нашей библиотеке стандартные типы и константы языка Ардуино (такой оператор добавляется автоматически в коде обычных программ, но в библиотеке его нужно дописать самому). Он выглядит примерно так (и располагается перед объявлением показанного выше класса):
И последнее: общепринято заключать все содержимое заголовочного файла в странную конструкцию:
По сути, это предотвращает возможные проблемы на случай, если кто-то подключит вашу библиотеку дважды.
В завершение, наверху библиотеки обычно располагают комментарий, содержащий название библиотеки, краткое описание того, что она делает, автора, дату создания и тип лицензии.
Давайте взглянем на заголовочный файл и посмотрим, что у нас получилось:
А теперь давайте разберем содержимое исходного файла — Morse.cpp.
Вначале файла идет несколько операторов #include, которые предоставляют остальной программе доступ к стандартным функциям Ардуино и к объявлениям функций внутри заголовочного файла:
Затем идет конструктор, который описывает, что должно произойти, когда кто-то создаст экземпляр вашего класса. В данном случае пользователь указывает, какой именно вывод он хотел бы использовать. Мы конфигурируем этот вывод в качестве выхода и сохраняем его во внутреннюю переменную для последующего использования в других функциях:
В этом коде есть непонятные моменты. Во-первых, конструкция Morse:: перед именем функции. Это значит, что функция является частью класса Morse. То же самое вы увидите при объявлении других функций этого класса. Второй момент — это знак подчеркивания в имени нашей внутренней private-переменной, _pin. Вообще-то эта переменная может иметь любой имя, главное, чтобы она соответствовала имени, объявленному в заголовочном файле. Добавление подчеркивания перед именем переменной — это общепринятая методика, применяющаяся для того, чтобы явно отличать private-переменные. Кроме того, подчеркивание позволяет программе отличить private-переменную от аргумента функции (pin в данном случае).
Далее идет сам код из первоначальной программы (ну наконец-то!). Он выглядит абсолютно точно так же, за исключением приставки Morse:: перед именами функций и переменной _pin вместо pin:
В завершение, хорошим тоном считается добавление комментария в начале исходного файла. Посмотрим что получилось:
И это все, что необходимо сделать (есть еще некоторые возможности, но мы поговорим о них чуть позже). Теперь попробуем нашу библиотеку в действии.
Прежде всего, создайте папку Morse в директории libraries внутри вашей рабочей папки с проектами. Скопируйте или переместите файлы Morse.h и Morse.cpp в созданную папку. Теперь запустите среду разработки Ардуино — в меню Sketch > Import Library вы должны увидеть библиотеку Morse. Она будет автоматически компилироваться вместе с использующими ее программами. Если этого не произойдет — проверьте ее расширение и убедитесь, что файл действительно имеет формат .cpp или .h (без дополнительных расширений вроде .pde или .txt, например).
Попробуем переписать нашу старую программу «SOS» с использованием новой библиотеки:
По сравнению с предыдущей версией в программе появилось несколько отличий (кроме того факта, что часть кода перенесена в библиотеку).
Во-первых, мы добавили оператор #include в начало программы, который включает библиотеку Morse в отправляемый плате код. Поэтому, если в программе библиотека больше не используется, желательно удалить #include для экономии памяти микроконтроллера.
Во-вторых, теперь мы создаем экземпляр класса Morse с именем morse:
При выполнении этой строки (а фактически, это произойдет даже до функции setup()) будет вызван конструктор класса Morse, которому будет передан указанный здесь аргумент (в данном случае 13).
Обратите внимание, что теперь наша функция setup() пуста, поскольку вызов pinMode() в данном случае происходит внутри библиотеки (при создании экземпляра класса).
Ну и наконец, вызов функций dot() и dash() теперь необходимо предварять префиксом morse. — именем того экземпляра, который мы хотим использовать. Мы можем создать несколько экземпляров класса Morse, каждый со своим выводом, хранимым во внутренней переменной _pin только в пределах этого экземпляра. Указывая определенный экземпляр класса при вызове функции, мы тем самым задаем, переменными какого экземпляра должна оперировать та или иная функция. То есть, если у нас два экземпляра:
то внутри функции morse2.dot() переменная _pin будет равна 12.
При написании новой программы, вы, наверняка заметите, что среда разработки не распознает и не подсвечивает элементы созданной нами библиотеки. К сожалению, IDE Ардуино не умеет автоматически распознавать и интерпретировать то, что мы объявили внутри библиотеки (кстати, было бы хорошо добавить эту функцию), поэтому ей нужно немного помочь. Для этого создайте файл keywords.txt в директории Morse и запишите в него следующее:
Каждая строка должна содержать ключевое слово, символ табуляции (не пробелы) и тип ключевого слова. Классы подсвечиваются оранжевым и должны иметь тип KEYWORD1; функции — коричневым и должны быть типа KEYWORD2. Для того, чтобы внесенные изменения вступили в силу, необходимо перезапустить среду Ардуино.
Также неплохо было бы снабдить библиотеку примером работы с ней. Для этого, создайте папку examples в директории Morse и переместите (либо скопируйте) в нее папку с нашей программой (назовем ее SOS). (Отыскать программу можно с помощью команды Sketch > Show Sketch Folder). Если вы перезапустите среду Ардуино (честно слово, это в последний раз) — то увидите пункт Library-Morse в меню File > Sketchbook > Examples с вашим примером. Можете добавить немного комментариев, объясняющих, как пользоваться вашей библиотекой.
Если вы захотите посмотреть готовую библиотеку (с примером и ключевыми словами) — можно сказать ее отсюда: Morse.zip.
На сегодня, пожалуй, это все, но в ближайшее время возможно появится расширенное руководство по созданию библиотек. А тем временем, если у вас возникнут проблемы или появятся предложения, пожалуйста, пишите их на форум.
Источник