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

Arduino言語

はじめに

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

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

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

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

Arduino IDE 1.5: Library specification · arduino/Arduino Wiki
Arduino IDE 1.x. Contribute to arduino/Arduino development by creating an account on GitHub.

ライブラリ構成

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

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

作成するもの①

● 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の4つの構成要素からなります。それぞれの構成要素間には、スペースを挿入し、その形式のリストを作成します。

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)
##########################################

まとめ

ここまで、ライブラリの作り方についてみてきました。

キーワード設定ファイルのRSYNTAXTEXTAREA_TOKENTYPEが不明瞭なのですが、基本的には、この流れで自作ライブラリができると思います。複雑なプログラムを作るときに活用できればプログラム構成をシンプルにでき、使いやすいプログラムが作成できるのではないでしょうか。

コメント

タイトルとURLをコピーしました