ページ

▼

2016年9月14日水曜日

Arduino IDEのライブラリマネージャーでインストールできるライブラリを作る方法


ArduinoIDEのライブラリマネージャにライブラリを登録する機会があったので、自分なりの言葉でまとめて、方法を共有します。

Arduino本家の情報を参考にしてライブラリを作りたい方は、下記のページをご参照ください。
Arduino IDE 1.5: Library specification

ライブラリマネージャとは？

Arduino IDEに登録されたライブラリのダウンロードとインストールしてくれる便利機能です。

スケッチ -> ライブラリをインクルード -> ライブラリを管理 で開けます。
（英語版だと Sketch -> Include Library -> Manage Libraries）


作り方の全体像

今回はHalakeKitというライブラリを例にして、登録とメンテナンス方法を説明します。

  1. ディレクトリ（フォルダ）の作成
  2. プログラムファイルの作成
  3. プロパティファイルの作成
  4. サンプルプロジェクトの作成
  5. キーワードファイルの作成
  6. githubにアップロード
  7. READMEの作成
  8. バージョン1としてタグ付け、もしくはリリース
  9. Arduino IDEに登録申請
  10. ライブラリのアップデート

ディレクトリ（フォルダ）の作成

HalakeKitに関するディレクトリを作る前に、Arduinoのスケッチを配置するディレクトリにlibrariesというディレクトリを作ります。（既にあるならそれを使います。）
このlibrariesというディレクトリの中に配置されたライブラリはArduinoに認識されます。
[Arduino-sketch-dir]
 |- libraries

次に、HalakeKitのためのディレクトリ（libraries, src, examples）を下記の構成で作ります。
[Arduino-sketch-dir]
 |- libraries
    |- HalakeKit
       |- src
       |- examples

作ったディレクトリの中にファイルを作成していきます。

プログラムファイルの作成

ライブラリのヘッダファイル（HalakeKit.h）とプロブラム本体のファイル（HalakeKit.cpp）をsrcに作成します。
[Arduino-sketch-dir]
 |- libraries
    |- HalakeKit
       |- src
          |- HalakeKit.h
          |- HalakeKit.cpp

ヘッダファイルには、2回読みこまれた時のエラーを回避するために、先頭と末尾にライブラリ名に合わせて下記のような記述をすることをお勧めします。

先頭の記述 
#ifndef HalakeKit_h
#define HalakeKit_h

末尾の記述 
#endif

また、ライブラリはクラスになっていた方が使いやすいと個人的に思うので、ヘッダファイルにはクラスの定義を記述し、プログラム本体にはクラス関数の処理を記述する形式をお勧めします。

ヘッダファイルの参考:
HaLakeKit-Library/src/HalakeKit.h
プログラム本体の参考:
HaLakeKit-Library/src/HalakeKit.cpp

プロパティファイルの作成

ライブラリ作成に必須のファイルです。
[Arduino-sketch-dir]
 |- libraries
    |- HalakeKit
       |- library.properties

下記のように、ライブラリに関する情報を記述します。
HaLakeKit/library.properties 
name=HalakeKit
version=1.0.0
author=nyampass
maintainer=Tokusei Noborio, Asuki Kono
sentence=A library to control hakale kit.
paragraph=It can get information from an accel sensor and a push switch.
category=Sensors
url=https://robip.halake.com/halake-board.html
architectures=*

参考:
HaLakeKit-Library/library.properties

他のライブラリを利用するライブラリを作る場合は、dependsという行に依存するライブラリ名を記述しておくと、Arduino IDE（2019/9公開の1.8.10以後）などでインストールする際に関連ライブラリもインストールできます。

depends=Adafruit BusIO, LiquidCrystal

参考:
Adafruit-MAX31855-library/library.properties

サンプルプロジェクトの作成

サンプルプロジェクトが無くてもライブラリは公開できますが、あった方が利用者が気軽に試せるので、便利だと思います。

ライブラリをincludeして、実行できたプロジェクトをディレクトリごとexamplesディレクトリに配置すると、サンプルプロジェクトとしてライブラリに組み込まれます。
[Arduino-sketch-dir]
 |- libraries
    |- HalakeKit
       |- examples
          |- PrintAccerator
             |- PrintAccerator.ino

参考:
HaLakeKit-Library/examples/

キーワードファイルの作成

無くてもライブラリは動きますが、keyword.txtに定義した文はArduino IDE上で強調されるので、ライブラリが使いやすくなります。
なお、定義するキーワードとキーワードタイプはタブで余白を作る必要があります。
スペースでは動きませんでした。

ファイルの場所
[Arduino-sketch-dir]
 |- libraries
    |- HalakeKit
       |- keywords.txt

keywords.txt 
#######################################
# Syntax Coloring Map for HaLakeKit
#######################################

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

HaLakeKit KEYWORD1

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

begin KEYWORD2
accel_x KEYWORD2
accel_y KEYWORD2
accel_z KEYWORD2
accel_comp KEYWORD2
accel_print_xyz KEYWORD2
switch_pushed KEYWORD2

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

before


after


参考:
Arduino開発環境用の「ライブラリ」を作成してみる
HaLakeKit-Library/keywords.txt

githubにアップロード

Arduino IDEのライブラリマネージャから呼び出せるライブラリの登録申請をするには、ライブラリがgithubのpublicなリポジトリとして公開されている必要があります。

githubにアップロードするために、ライブラリをgitのプロジェクトにします。
cd [Arduino-sketch-dir]/libraries/HalakeKit
git init
git add -A
git commit "Initial commit"

githubでライブラリのリポジトリを作成してください。
Create a new repository

リポジトリができたら、ライブラリのgitプロジェクトとgithubのリポジトリを紐付けます。
git remote add origin git@github.com:[作ったリポジトリ名]

プロジェクトをpush（アップロード）します。
git push origin master

READMEの作成

READMEが無くてもライブラリは登録できますが、あった方が利用者にとって便利なので、使ってもらいやすくなると思います。

参考:
HaLakeKit-Library/readme.md
HaLakeKit-Libraryreadme.md raw

バージョン1としてタグ付け、もしくはリリース

gitコマンドでタグ付けする方法

下記のコマンドでバージョン1.0.0としてタグ付けできます。
git tag 1.0.0
git push origin 1.0.0

githubのGUIでタグ付け・リリースする方法

githubでリリースすると、タグ付けとリリースが同時に行われます。

プロジェクトのリリースをクリックしてタグとリリースの一覧を開きます。


何もリリースが無いので、最初のリリースを作ります。


バージョンを入力してpublishすると、タグ付けとリリースができます。
バージョンは「1.0.0」「1.0」「v1.0.0」「v1.0」など、好きな形式をお使いください。


Arduino IDEに登録申請

Arduino IDEのissuesに自分のライブラリを登録して欲しい旨のissueを作成します。
受理されれば、ライブラリマネージャからライブラリが検索できるようになります。

参考:
[Library Manager] Please add HalakeKit-library

ライブラリのアップデート

ライブラリに機能の追加や機能の修正などの変更を行った場合、library.propertiesのバージョンを変更して新しいバージョンとしてタグを切りれば、古いバージョンのダウンロードをサポートしながらアップデートができます。

コードのバージョンアップとコミット

HaLakeKit/library.properties 
version=1.0.1


git add -A
git commit -m "Modify something"
git push origin master

タグ付け、もしくはリリース

gitのコマンドでタグ付けする場合

git tag 1.0.1
git push origin 1.0.1

githubのGUIでタグ付け・リリースする場合

Releaseページの「Draft a New Release」からバージョン1.0.1をリリースしてください。


確認

処理がうまくいくと、ライブラリマネージャで新しいバージョンを確認できます。


登録方法の共有は以上です。
説明に不備がある場合、宜しければコメントやお問い合わせでお知らせください。
この情報が役に立てば嬉しいです。

更新履歴

2016/11/23
「キーワードファイルの作成」を追加しました。
githubのGUIでのリリース方法の説明を追加しました。

2019/10/01
記事のタイトルを「Arduino IDEにライブラリを登録する方法」から「Arduino IDEのライブラリマネージャーでインストールできるライブラリを作る方法」に変更しました。

2020/04/26
library.propertiesにdependsとして依存するライブラリを記述できるようになったことが分かったので、設定方法を追加しました。
at

0 件のコメント :

コメントを投稿