Добавление библиотеки в реестр

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

Написание библиотеки #

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

Хорошие практики:

• Примеры из библиотеки должны компилироваться и работать без ошибок и предупреждений
• Нужно минимизировать риск пересечения имён в библиотеке с другими библиотеками или программой - оборачивать инструменты в классы или namespace, использовать префиксы с названием библиотеки для define-констант, типов данных и отдельных функций, использовать enum class для глобально объявленных перечислений
• Код библиотеки должен быть читаемым и не содержать "магических чисел" - все константы (адреса регистров, размеры, прочие числа) должны быть вынесены в начало файла списком дефайнов

// MyLibrary.h
#pragma once
#include <Arduino.h>

#define MYLIB_CONST1 123
#define MYLIB_CONST2 456

namespace mylib {
// функции...
}

enum class MyConst {
    //...
};

class MyClass {
    //...
};

Публикация на GitHub #

Библиотека должна быть загружена на GitHub и оформлена в виде отдельного репозитория (страница библиотеки), одна библиотека - один репозиторий. Для работы с GitHub нужно зарегистрироваться на GitHub.

GitHub Desktop #

Для удобства работы с GitHub рекомендуется использовать официальное приложение GitHub Desktop. Скачать, установить, войти в аккаунт.

Создаём репозиторий - его копия будет храниться в указанной папке:

• License - лицензия проекта, обычно используют MIT или GPL, почитать подробнее можно например здесь или здесь
• Можно поставить галочку на создание файла readme

После этого можно открыть папку библиотеки в проводнике и работать с ней. Если установлен VS Code - можно сразу открывать в нём для редактирования.

Загрузка изменений происходит в два действия - Commit и Push:

• Commit добавляет изменения локально, они пропадают из списка изменений. Можно сделать несколько коммитов с разными комментариями для разных файлов. Название коммита - обязательно
• Push отправляет все коммиты на сервер
• Если репозиторий ещё не опубликован - будет доступна опция Publish. В ней нужно подтвердить название и описание библиотеки, а также снять галочку "сделать репозиторий приватным"

После этого библиотека станет доступна на GitHub. Локальную папку хранить не обязательно - репозиторий всегда можно скачать при помощи действия Clone:

Структура библиотеки #

Библиотека содержит непосредственно файл/файлы с кодом, а также некоторые дополнительные файлы и папки:

• examples - папка с примерами. Должна содержать папки с примерами, в которых находятся одноимённые скетчи с расширением .ino
• src - папка с файлами библиотеки. Вместо этого файлы библиотеки могут располагаться в корне репозитория
• keywords.txt - файл с ключевыми словами для подсветки синтаксиса в Arduino IDE v1.x
• README.md - описание библиотеки. Этот файл открывается на главной странице репозитория
• library.properties - файл с информацией о библиотеке для реестра. Обязательный файл

Полную спецификацию можно почитать здесь.

library.properties #

Минимальный пример:

name=MyLibrary
version=1.0.0
author=AlexGyver <[email protected]>
maintainer=AlexGyver <[email protected]>
sentence=Краткое описание
paragraph=Полное описание
category=Категория
url=https://github.com/GyverLibs/MyLibrary
architectures=*

Все поля и требования к их содержанию описаны здесь. Основные:

• name - имя библиотеки, будет отображаться в менеджере библиотек:
  • Не должно начинаться с arduino - это официальные библиотеки
  • Должно быть уникальным. Проверить совпадения можно в поиске по реестру на официальном сайте
  • Не обязательно должно совпадать с именем репозитория
• version - версия в формате semver
• architectures - платформа, на которой работает библиотека, могут быть перечислены через запятую ,. Примеры:
  • * - все платформы
  • avr
  • esp8266
  • esp32
• category - категория библиотеки, одна из списка: Display, Communication, Signal Input/Output, Sensors, Device Control, Timing, Data Storage, Data Processing, Other
• depends - зависимости от других библиотек, если есть - они установятся автоматически при установке основной библиотеки через менеджер библиотек. Указываются списком через запятую ,, например GTL,GyverDB,StringUtils

keywords.txt #

Стандартный пример с комментариями (их можно удалить):

#######################################
# Syntax Coloring Map For MyLibrary
#######################################

#######################################
# Datatypes (KEYWORD1)
#######################################

Foo KEYWORD1
Bar KEYWORD1

#######################################
# Methods and Functions (KEYWORD2)
#######################################

foo KEYWORD2
bar KEYWORD2

#######################################
# Constants (LITERAL1)
#######################################

some_const  LITERAL1

README.md #

Оформляется на языке разметки Markdown, спецификацию с примерами можно посмотреть здесь.

Добавление в реестр #

Для добавления в общий реестр библиотека должна быть загружена в репозиторий и соответствовать описанным выше требованиям. Добавление библиотеки - это добавление ссылки на репозиторий в файл с общим списком библиотек через его редактирование и дальнейший pull request на аккаунт arduino.

Создание релиза #

Перейти в раздел Releases и нажать Create a new release. Указать версию (должна соответствовать версии в library.properties, для первого релиза например 1.0.0) и опционально описание:

Первое добавление с аккаунта #

Если это самое первое добавление библиотеки с вашего аккаунта на GitHub - нужно создать fork реестра: перейти в репозиторий реестра arduino/library-registry и нажать fork, затем Create fork:

Теперь на вашем аккаунте появится репозиторий library-registry:

Последующие добавления #

Открываем свою копию репозитория реестра, как на картинке выше. Если с момента последнего добавления реестр успел обновиться - его нужно синхронизировать со своей копией:

После этого переходим к редактированию файла repositories.txt:

Добавляем ссылку на репозиторий своей библиотеки в любое место, например сверху, и жмём Commit changes два раза:

После этого возвращаемся на главную страницу форка (на своём аккаунте) и делаем Pull request:

Бот проверит репозиторий на соответствие требованиям, в случае нарушений он подробно их опишет - нужно будет исправить. Если всё в порядке - через несколько секунд появится сообщение об успешном добавлении библиотеки в реестр:

Обновление библиотеки #

Для обновления библиотеки достаточно увеличить версию в library.properties, загрузить новые файлы в репозиторий и выпустить релиз с соответствующим кодом версии.

Краткая информация по ведению версий (система Semver):

• Версия указывается в формате x.x или x.x.x
• Версия может только увеличиваться при обновлениях, например 1.0.0 -> 1.0.1 -> 1.2.0 -> 2.0.0
• Принято увеличивать младшую цифру версии (x.x.X) при небольших изменениях, среднюю (x.X.x) при крупных обновлениях без нарушения совместимости с предыдущими версиями, старшую (X.x.x) - при несовместимых изменениях

Добавление в реестр PIO #

Библиотеки из Arduino-реестра автоматически становятся доступны для установки и автоматически обновляются в реестре PlatformIO.

Если добавленная в Arduino-реестр библиотека не появилась в реестре PIO, то скорее всего в нём уже есть другая библиотека с таким же именем. В этом случае библиотеку всё равно можно добавить в реестр PIO - нужно открыть репозиторий в VS Code и ввести команду pio pkg publish в консоли PIO, согласиться y на добавление. Библиотека не будет обновляться автоматически с выходом нового релиза - нужно отправлять обновление этой же командой.

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

• Набор GyverKIT – наш большой стартовый набор Arduino, продаётся в России
• Каталог ссылок на дешёвые Ардуины, датчики, модули и прочие железки с AliExpress
• Обратная связь – сообщить об ошибке в уроке или предложить дополнение по тексту ([email protected])
• Поддержать автора за работу над уроками