独自のライブラリを作成してみる

はじめに
ライブラリ構成
プロパティファイル
1. プロパティファイル形式
キーワードファイル
1. キーワードファイル形式
ライブラリの例
まとめ

はじめに

ここでは、ライブラリを自分で作成し、そのライブラリをプログラムに組み込む方法を記載します。

Arduino IDEを起動してsetup()とloop()関数に処理を書けば動作は可能です。

LEDを点滅させるというような簡単なプログラムであれば、それで済むかと思いますが、プログラム行数が増えてきて複雑になってくるとひとつのファイルですべて完結するというのはプログラムの可読性や保守性、等々、問題になってきます。そこで、機能ごとにライブラリを作成して、それを呼び出してプログラムを実行する構成にするため、そのやり方を勉強してみたいと思います。

ライブラリ仕様については、こちらに公開されています。この内容をまとめていますので、詳細は、そちらを参照してみてください。ここでは、ライブラリrev.2.2(Arduino IDEバージョン1.8.10から実装)での記載とします。

Arduino IDE 1.5: Library specification

Arduino IDE 1.x. Contribute to arduino/Arduino development by creating an account on GitHub.

ライブラリ構成

ライブラリ構成は、３つのフォルダと２つの設定ファイル、および、ライブラリプログラムからなります。

自身で作成したライブラリフォルダ（ルートフォルダ）の下（この例では、libTestフォルダ）にexamplesフォルダ、extrasフォルダ、srcフォルダを作成します。さらに、keywords.txt、libray.propertiesという２つの設定ファイルを作成します。ルートフォルダ名は、英数字で始まり、スペース、下線、ドット、ダッシュが使用できます。また、最大で６３文字までの名前を付けることができます。

作成するもの①

● srcフォルダ

● examplesフォルダ

● extrasフォルダ

● keywords.txtファイル

●libray.propertiesファイル

ライブラリプログラムの配置は、作成したsrcフォルダの直下になります。ソースファイルとヘッダファイルをここに置きます。この例では、ファイル名をtestとしています。

サンプルプログラムを作成する場合は、examplesフォルダの下にサンプルプログラムと同じ名前のフォルダを作成し、その下にサンプルプログラムを置きます。この例では、examplesフォルダの下にtestフォルダを作成し、作成したtestフォルダの中にtest.inoというサンプルプログラムを置いています。

ここでのサンプルプログラムは、Arduino IDEのスケッチ例に表示され、これを実行することで、作成したサンプルプログラムがIDEに読み込まれます。

作成するもの②

● ライブラリのソースファイルとヘッダファイル

　⇒srcフォルダ内に作成

●サンプルプログラム

　⇒examplesフォルダにサンプルプログラムと同じ名前のフォルダを作成しそのフォルダ内に作成

extrasフォルダは、ライブラリ作成者によってドキュメントを保管するために使用されます。サポート文書などを入れる場合は、ここに置きます。Arduino IDEは、このフォルダ内のものに関しては、何もしません。

これで、ライブラリを構成するものの枠組み作りは完了です。ここから、個別の中身をみていきます。

プロパティファイル

Arduino IDEのライブラリマネージャは、プロパティファイルによりライブラリとその依存関係を検索します。それによりライブラリのインストールが可能となります。プロパティファイルは、libray.propertiesという名前で作成し、ライブラリフォルダのルートに配置します。

プロパティファイル形式

libray.propertiesファイルは、key=valueという形式のプロパティリストで作成されます。各プロパティは、UTF-8でエンコーディングされます。keyの一覧を表にまとめます。オプションのものは、任意になります。

name	ライブラリの名前を記述します。英数字、スペース、下線、ドット、ダッシュが使用できます。スペース、数字、Arduinoから始まる名前は不可です。
version	ライブラリのバージョンを記述します。バージョンは、[メジャー].[マイナー].[パッチ] で定義されます。
author	作成者の名前／ニックネームとメールアドレスをカンマ区切りで記述します。メールアドレスの記述は必須ではありません。
maintainer	保守者の名前とメールアドレスを記述します。
sentence	ライブラリの目的の説明文を記述します。
paragraph	ライブラリの詳細説明文を記述します。
category	ライブラリのカテゴリを以下の中から選択し記述します。 Uncategorized (デフォルト) Display Communication Signal Input/Output Sensors Device Control Timing Data Storage Data Processing Other
url	ライブラリのプロジェクトURLを記述します。例えば、GitHubページのURLなどになります。ここでの定義は、ライブラリマネージャの詳細のリンクに使用されます。
architectures	ライブラリでサポートされているアーキテクチャのリストをカンマ区切りで記述します。デフォルトは、* です。 * は、すべてのアーキテクチャに一致する場合に使用されます。ここに記述したリストと一致しないアーキテクチャのボードに対してライブラリがコンパイルを実行した場合、警告メッセージが表示されます。
depends	【オプション】[IDE1.8.10より利用可能] ライブラリを使用する上で必要なライブラリのリストをカンマ区切りで記述します。ライブラリマネージャは、ここで記述したライブラリのインストールを提案します。
dot_a_linkage	【オプション】[IDE1.6.0/arduino-builder1.0.0-beta13より利用可能] trueに設定されると、ライブラリは、アーカイブファイル(.aファイル)を使ってコンパイルします。最初にすべてのソースファイルは、オブジェクトファイル(.oファイル)にコンパイルされます。次にすべてのオブジェクトファイルをアーカイブファイルに保存し、それをリンカ命令に含めます。
includes	【オプション】[IDE1.6.10より利用可能] #include<…>としてスケッチに追加するファイルリストをカンマ区切りで記述します。
precompiled	【オプション】[Arduino IDE 1.8.6/arduino-builder 1.4.0より利用可能] trueに設定するとアーカイブファイル(.aファイル)および共有オブジェクトファイル(.soファイル)の使用を許可します。
idflags	【オプション】[Arduino IDE 1.8.6/arduino-builder 1.4.0より利用可能] 追加するリンカフラグを記述します。例： ldflags = -lm

例

name=WebServer
version=1.0.0
author= xxx xxx@xxx.com
maintainer=zzz zzz@zzz.com
sentence=A library that makes coding a Webserver a breeze.
paragraph=Supports HTTP1.1 and you can do GET and POST.
category=Communication
url=http://example.com/
architectures=avr
includes=WebServer.h
depends=ArduinoHttpClient

キーワードファイル

keywords.txtという名前のファイルには、ライブラリのキーワードリストを記述します。ここで記述したキーワードを含むライブラリをスケッチで使用するとArduino IDEは、そのキーワードを色付けして表示します。

キーワードファイル形式

keywords.txtは、KEYWORD,KEYWORD_TOKENTYPE,REFERENCE_LINK,RSYNTAXTEXTAREA_TOKENTYPEの４つの構成要素からなります。それぞれの構成要素間には、スペースを挿入し、その形式のリストを作成します。

KEYWORD

色付けしたいワードを記述します。

KEYWORD_TOKENTYPE

KEYWORD1,KEYWORD2,KEYWORD3,LITERAL1,LITERAL2の何れかのタイプを記述します。

KEYWORD_TOKENTYPE	使用目的
KEYWORD1	データタイプ
KEYWORD2	関数
KEYWORD3	構造体
LITERAL1	定数
LITERAL2	ー

REFERENCE_LINK

このフィールドは、カーソルがそのキーワード上にあるとき、[右クリック] > [リファレンスで検索] または、[ヘルプ] > [リファレンスで検索]によって開かれるArduino言語の参照ページを指定するものです。独自のキーワードであればArduino言語の参照に該当するワードはないので特に記述しなくてもよいです。

RSYNTAXTEXTAREA_TOKENTYPE

Arduino IDE 1.6.5以降では、このフィールドはKEYWORD_TOKENTYPEをオーバーライドします。いまひとつ使い方がわかっていないのですが、このフィールドは使用せず、KEYWORD_TOKENTYPEで設定すればよいかと思います。

ライブラリの例

ここでは、Arduino IDEをインストールするとデフォルトでインストールされるStepperライブラリの例を記載します。ライブラリは、Arduino IDEのインストールフォルダの中にあるlibrariesフォルダにあります。

Stepperライブラリ構成

 Stepper/
 Stepper/library.properties
 Stepper/keywords.txt
 Stepper/README.adoc
 Stepper/src/
 Stepper/src/Stepper.h
 Stepper/src/Stepper.cpp
 Stepper/src/ServoTimers.h
 Stepper/examples/
 Stepper/examples/MotorKnob/MotorKnob.ino
 Stepper/examples/stepper_oneRevolution/stepper_oneRevolution.ino
 Stepper/examples/stepper_oneStepAtATime/stepper_oneStepAtATime.ino
 Stepper/examples/stepper_speedControl/stepper_speedControl.ino

library.properties

 name=Stepper
 version=1.1.3
 author=Arduino
 maintainer=Arduino info@arduino.cc
 sentence=Allows Arduino boards to control a variety of stepper motors. 
 paragraph=This library allows you to control unipolar or bipolar stepper motors. To use it you will need a stepper motor, and the appropriate hardware to control it.
 category=Device Control
 url=http://www.arduino.cc/en/Reference/Stepper
 architectures=*

keywords.txt

##########################################
# Syntax Coloring Map For Test
##########################################
##########################################
# Datatypes (KEYWORD1)
##########################################

  Stepper    KEYWORD1    Stepper

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

  step             KEYWORD2
  setSpeed    KEYWORD2
  version        KEYWORD2
 
##########################################
#  Instances (KEYWORD2)
##########################################
 
 direction    KEYWORD2
 speed        KEYWORD2

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