M5Stack

[M5Stack] Arduino ライブラリのAPIまとめ

更新日:

M5Stackには、Arduinoライブラリがあり、便利なAPIが用意されています。

これを知らずに、似たような処理を苦労して実装していることがありますので、一度目を通しておくと、コーディング時に、ふと、APIで用意されているかもと気がつくこともあると思います。

目を通しやすくするために、ArduinoライブラリのAPIの一覧を用意しました。活用ください。

スポンサードサーチ

ArduinoライブラリのAPI一覧

API一覧は、Arduino日本語リファレンスの内容を、一覧としてまとめたものです。

詳しく知りたい人は、Arduino日本語リファレンスを見てください。サンプルコードも書かれており、とてもわかり易いです。

M5Stackは、こうした情報が多いので、とても作りやすいです。

Arduino言語

API説明リンク
setup()setup()はArduinoボードの電源を入れたときやリセットしたときに、一度だけ実行されます。
変数やピンモードの初期化、ライブラリの準備などに使ってください。
setup()は省略できません。
Arduino日本語リファレンス
loop()setup()で初期値を設定したら、loop()に実行したいプログラムを書きます。
そのプログラムによってArduinoボードの動きをコントロールします。
loopという名前のとおり、この部分は繰り返し実行されます。
loop()は省略できません。
Arduino日本語リファレンス

スポンサードサーチ

シリアル通信

API説明リンク
Serial.begin(speed)シリアル通信のデータ転送レートをbps(baud)で指定します。
コンピュータと通信する際は、
次のレートから1つを選びます。
300, 1200, 2400, 4800, 9600, 14400, 19200, 28800, 38400, 57600, 115200
Arduino日本語リファレンス
Serial.end()シリアル通信を終了し、RXとTXを汎用の入出力ピンとして使えるようにします。
再度シリアル通信を有効にしたいときは、Serial.begin()をコールしてください。
Arduino日本語リファレンス
Serial.available()シリアルポートに何バイトのデータが到着しているかを返します。
すでにバッファに格納されているバイト数で、バッファは64バイトまで保持できます。
Arduino日本語リファレンス
Serial.read()受信データを読み込みます。
読み込み可能なデータの最初の1バイトを返します。
-1の場合は、データが存在しません (int)。
Arduino日本語リファレンス
Serial.readBytes()シリアルバッファから文字列をバッファに読み込む。Arduino日本語リファレンス
Serial.readBytesUntil()シリアルバッファから文字列をバッファに読み込む。この関数は終端文字を検出するか、指定した長さの文字列が読み込まれるか、タイムアウトすれば終了する。Arduino日本語リファレンス
Serial.readString()シリアルバッファから文字を読み込み文字列を作成する。Arduino日本語リファレンス
Serial.readStringUntil()シリアルバッファから文字を読み込み、文字列を作成する。この関数は終端文字を検出するか、指定した長さの文字列が読み込まれるか、タイムアウトすれば終了する。Arduino日本語リファレンス
Serial.setTimeout()シリアルデータ受信の最大待ち時間を設定する。Arduino日本語リファレンス
Serial.find()与えらえた長さの、目的となる文字列がシリアルバッファで見つかるまで、データを読み込む。Arduino日本語リファレンス
Serial.findUntil()与えらえた長さの、目的となる文字列がシリアルバッファで見つかるまで、もしくは、終端文字列が見つかるまで、データを読み込む。Arduino日本語リファレンス
Serial.peek()受信データを1バイト読み込みますが、
バッファ中の読み取り位置は変更しません。
つまり、peek()は同じ文字を繰り返し読み取ります。
読み込み可能なデータの最初の1バイトを返します。
-1の場合は、データが存在しません (int)。
Arduino日本語リファレンス
Serial.flush()データの送信がすべて完了するまで待ちます。
(Arduino 1.0より前のバージョンでは、受信バッファをクリアする仕様でした)。
Arduino日本語リファレンス
Serial.print(data, format)人が読むことのできる形式(ASCIIテキスト)でデータをシリアルポートへ出力します。
数値は1桁ずつASCII文字に変換されます。
浮動小数点数の場合は、小数点以下第2位まで出力するのがデフォルトの動作です。
バイト型のデータは1文字として送信されます。
文字列はそのまま送信されます。
・Serial.print(78) - "78"が出力
・Serial.print(1.23456) - "1.23"が出力
・Serial.print('N') - "N"が出力
・Serial.print("Hello world.") - "Hello world."と出力

・Serial.print(78, BIN) - "1001110"が出力
・Serial.print(78, OCT) - "116"が出力
・Serial.print(78, DEC) - "78"が出力
・Serial.print(78, HEX) - "4E"が出力
・Serial.println(1.23456, 0) - "1"が出力
・Serial.println(1.23456, 2) - "1.23"が出力
・Serial.println(1.23456, 4) - "1.2346"が出力
Arduino日本語リファレンス
Serial.println(data, format)データの末尾にキャリッジリターン(ASCIIコード13あるいは'\r')と
ニューライン(ASCIIコード10あるいは'\n')を付けて送信します。
Serial.print()と同じフォーマットが使えます。
Arduino日本語リファレンス
Serial.write(val)シリアルポートにバイナリデータを出力します。
1バイトずつ、あるいは複数バイトの送信が可能です。
(数値を表す)文字として送信したい場合は、print()を使ってください。
Arduino日本語リファレンス

Stringクラス

API説明リンク
String()Stringクラスのインスタンスを生成します。
様々なデータ型から変換して、インスタンスを生成することができます。
数値からインスタンスを生成すると、
その値(10進数)をASCII文字で表現したものになります。
String thisString = String(13)
こうすると"13"という文字列がインスタンスに与えられます。
別の基数を用いることもできます。
String thisString = String(13, HEX)
16進数を指定すると"D"という文字列が与えられます。
String thisString = String(13, BIN)
2進数を指定したときの生成される文字列は"1011"です。
Arduino日本語リファレンス
string.charAt(n)文字列の先頭からn+1番目の文字を返します。Arduino日本語リファレンス
string.compareTo(string2)2つの文字列を比較します。
ABC順で見たとき、string2のほうが後ろに来るなら負の値、前に来るなら正の値を返します。
インスタンスとstring2が一致するときは0を返します。
string.concat(string2)文字列を連結します。
stringの末尾にstring2が付け加えられます。
string.endsWith(string2)stringの末尾がstring2のときtrueを返し、
そうでなければfalseを返します。
string.equals(string2)2つの文字列を比較し、一致するときtrueを返し、
そうでなければfalseを返します。
大文字小文字を区別します。
string.equalsIgnoreCase(string2)大文字小文字の区別をせず比較し、一致していればtrueを返し、
そうでなければfalseを返します。
helloとHELLOは一致するとみなされます。
string.getBytes(buf, len)文字列をbyte型の配列(buf)にコピーします。
lenはbufのサイズです(int)。
string.indexOf(val, from)文字列の中を先頭から検索し、
見つかった場合はその位置を返します(1文字目が0です)。
見つからなかったときは-1を返します。
valは探したい文字('a')または文字列("abc")です。
fromは検索を始める位置で、省略も可能です。
string.lastIndexOf(val, from)文字列の中を末尾から検索し、
見つかった場合はその位置を返します。
見つからなかったときは-1を返します。
valは探したい文字('a')または文字列("abc")です。
fromは検索を始める位置で、省略可能です。
string.length()文字数を返します。
string.replace(substring1, substring2)置換します。
substring1をsubstring2に置換した文字列を返します。
string.setCharAt(index, c)indexで指定した位置の文字をcに置き換えます。
stringの長さより大きいindexを指定した場合はなにも変化しません。
string.startsWith(string2)stringの先頭がstring2のときtrueを返し、
そうでなければfalseを返します。
string.substring(from, to)文字列の一部を返します。
toは省略可能で、
fromだけが指定されているときは、
from+1文字目から末尾までの文字列を返します。
toも指定されているときは、末尾ではなくtoまでを返します。
string.toCharArray(buf, len)文字列をbyte型の配列(buf)にコピーします。
lenはbufのサイズです(int)。
string.toLowerCase()大文字を小文字に変換します。
もとの文字列は変化しません。
string.toUpperCase()大文字を小文字に変換します。
もとの文字列は変化しません。
string.trim()先頭と末尾のスペースを取り除きます。
[] 要素へのアクセス配列と同じように指定した文字にアクセスできます。Arduino日本語リファレンス
+ 連結文字列を連結します。
string.concat()と同じ働きです。
== 比較2つの文字列を比較し、一致するときはtrueを、
異なるときはfalseを返します。
string.equals()と同じ意味です。

スポンサードサーチ

時間に関する関数

API説明リンク
millis()Arduinoボードがプログラムの実行を開始した時から現在までの時間を
ミリ秒単位で返します。
約50日間でオーバーフローし、ゼロに戻ります。
Arduino日本語リファレンス
micros()Arduinoボードがプログラムの実行を開始した時から現在までの時間を
マイクロ秒単位で返します。
約70分間でオーバーフローし、ゼロに戻ります。
16MHz動作のArduinoボードでは、
この関数の分解能は4マイクロ秒で、戻り値は常に4の倍数となります。
8MHzのボード(たとえばLilyPad)では、8マイクロ秒の分解能となります。
Arduino日本語リファレンス
delay(ms)プログラムを指定した時間だけ止めます。
単位はミリ秒です。
Arduino日本語リファレンス
delayMicroseconds(us)プログラムを指定した時間だけ一時停止します。
単位はマイクロ秒です。
数千マイクロ秒を超える場合はdelay関数を使ってください。
現在の仕様では、16383マイクロ秒以内の値を指定したとき、
正確に動作します。
この仕様は将来のリリースで変更されるはずです。
Arduino日本語リファレンス

変数の応用

API説明リンク
Staticstaticキーワードは変数と組み合わせて使います。
関数内でstaticを付けて宣言された変数はスタティック変数と呼ばれ、
通常のローカル変数とは異なる働きをします。
ローカル変数は関数が呼ばれるたびに生成と破棄が行われるのに対し、
スタティック変数は持続的で、関数が繰り返し呼ばれる間も値が保存されます。
スタティック変数は、関数が初めて呼ばれたときに1度だけ生成されます。
Arduino日本語リファレンス
volatilevolatileは変数を修飾するキーワードで、
型宣言の前に付けて、
コンパイラが変数を取り扱う方法を変更します。
具体的には、変数をレジスタではなくRAMからロードするよう、コンパイラに指示します。
ある条件では、レジスタに記憶された変数の値は不確かだからです。
変数をvolatileとして宣言する必要があるのは、
その変数がコントロールの及ばない別の場所(たとえば並行して動作するコード)で変更される可能性があるときです。
Arduinoの場合、そうした状況が当てはまるのは、
割り込みサービスルーチンと呼ばれる、割り込みに関連したコードだけです。
Arduino日本語リファレンス
constconstキーワードは変数の挙動を変える修飾子で、定数を表します。
constは変数を"read-only"にします。
つまり、型を持つ変数として使えますが、
値は変更できません。
const変数に代入しようとすると、
コンパイルエラーが発生します。
constキーワードを付けられた変数も、
他の変数と同様にスコープのルールに従います。
これが#defineよりもconstを使うほうが良い理由です。
Arduino日本語リファレンス
PROGMEMとFマクロFlashメモリ(プログラム領域)にデータを格納するための修飾子です。
Arduino UnoのSRAM は小さいため、
大きなデータはPROGMEMを使って Flashメモリから読み込みます。
PROGMEMキーワードは変数を宣言するときに使います。
pgmspace.hで定義されているデータ型だけを使用してください。
PROGMEMはpgmspace.hライブラリの一部です。
よって、このキーワードを使うときは、
まず次のようにして、
ライブラリをインクルードする必要があります。
#include <avr/pgmspace.h>
Arduino日本語リファレンス
Castcast演算子は変数の型を別の型に変換します。
また、計算において型を強制します。
Arduino日本語リファレンス
sizeofsizeof演算子は変数や配列のバイト数を返します。Arduino日本語リファレンス

スポンサードサーチ

データ型

API説明リンク
booleanブール型はtrueかfalseどちらか一方の値を持ちます。Arduino日本語リファレンス
char1つの文字を記憶するために1バイトのメモリを消費する型です。
文字は'A'のように、シングルクオーテーションで囲って表記します。
(複数の文字=文字列の場合はダブルクオーテーションを使い、"ABC"のようになります)。
文字は数値として記憶されます。
これは、文字を計算の対象として扱えることを意味します。
たとえば、ASCIIコードにおける大文字のAは65なので、'A'+1 は66となります。
文字から数値への変換については、Serial.printの項で、より詳しく説明されています。
char型は符号付きの型(signed)で、
-128から127までの数値として扱われます。
符号なし(unsiged)の1バイトが必要なときは、byte型を使ってください。
Arduino日本語リファレンス
unsigned char符号無しのデータ型で1バイトのメモリを占有します。
0から255までの値を扱うことができます。
byte型と等しい型です。
Arduinoプログラミングにおけるスタイルの一貫性を保つため、byte型を使うほうが良いでしょう。
Arduino日本語リファレンス
bytebyte型は0から255までの8bitの数値を格納します。
符号無しのデータ型で、これは負の数値は扱えないという意味です。
Arduino日本語リファレンス

int (整数型)
int型(整数型)は、数値の記憶にもっともよく使われる型です。
ArduinoUnoやLeonardoでは2バイトを使って格納され、
値の範囲は-32768から32767までです。
32ビットマイコンを搭載するArduinoDueでは4バイトで格納され、
値の範囲は-2,147,483,648から2,147,483,647までとなります。
int型は負の数を「2の補数」と呼ばれるテクニックで表現します。
最上位のビットは符号ビットともいわれ、
負の値であることをしめすフラグです。
残りのビットは反転してから1を加算します。
Arduinoが期待どおりの挙動をしてくれるので、
負の数の取り扱いについて、ユーザが細部を気にする必要はありません。
ただし、ビットシフト演算(>>)を使用してしまうと、やっかいな問題が生じるかもしれません。
Arduino日本語リファレンス
unsigned int (符号なし整数型)unsigned int型は、2バイトの値を格納する点ではint型と同じですが、
負の数が扱えず、0から65535までの正の数だけを格納します。
符号付き整数型と符号なし整数型の違いは、最上位ビットの解釈の違いです。
Arduino日本語リファレンス

word
word型は符号無し16ビットの数です。
0から65535までを格納できます。
Arduino日本語リファレンス
long (long整数型)long型の変数は32ビット(4バイト)に拡張されており、
-2,147,483,648から2,147,483,647までの数値を格納できます。
Arduino日本語リファレンス
unsigned long (符号なしlong整数型)unsigned long型の変数は32ビット(4バイト)の数値を格納します。
通常のlong型と違い、負の数は扱えません。
値の範囲は0から4,294,967,295(2の32乗 - 1)です。
Arduino日本語リファレンス
float (浮動小数点型)浮動小数点を持つ数値のためのデータ型です。
つまり、小数が扱えます。
整数よりも分解能が高いアナログ的な値が必要なときに使います。
使用可能な値の範囲は3.4028235E+38から-3.4028235E+38までで、
32ビット(4バイト)のサイズです。
浮動小数点数には誤差があるので、
比較に用いるとおかしな結果になるかもしれません。
かわりに、差の絶対値が十分小さいことをチェックしたほうがいいでしょう。
また、浮動小数点型の計算は整数型にくらべてとても時間がかかります。
タイミングが重要な処理で、速いループが必要なときには使用しないほうがいいでしょう。
Arduino日本語リファレンス
double (倍精度浮動小数点型)Arduino Unoのdouble型はfloat型と同一の実装で、
この型を使っても精度は向上しません。
double型を含むコードをArduinoへ移植する際は注意してください。
Arduino Dueにおけるdouble型は8バイト(64 bit)の精度です。
Arduino日本語リファレンス

文字列(配列)
文字列(string)は2つの方法で表現できます。
ここでは、char型の配列とヌル終端で表される従来型の文字列を説明します。
arduino-0019以降でコアの一部となったもうひとつの方法については、Stringクラスの項を参照してください。
Arduino日本語リファレンス
配列配列(array)は変数の集まりで、インデックス番号(添え字)を使ってアクセスされます。Arduino日本語リファレンス
void一般的なArduinoプログラミングにおいて、voidキーワードは関数の定義にだけ使われます。
voidはその関数を呼び出した側になんの情報も返さないことを示します。
Arduino日本語リファレンス

数学的な関数

API説明リンク
min(x, y)2つの数値のうち、小さいほうの値を返します。Arduino日本語リファレンス
max(x, y)2つの数値のうち、大きいほうの値を返します。Arduino日本語リファレンス
abs(x)絶対値を計算します。Arduino日本語リファレンス
constrain(x, a, b)数値を指定した範囲のなかに収めます。Arduino日本語リファレンス

map(value, fromLow, fromHigh, toLow, toHigh)
数値をある範囲から別の範囲に変換します。
fromLowと同じ値を与えると、toLowが返り、
fromHighと同じ値ならtoHighとなります。
その中間の値は、2つの範囲の大きさの比に基づいて計算されます。
そのほうが便利な場合があるので、この関数は範囲外の値も切り捨てません。
ある範囲のなかに収めたい場合は、constrain関数と併用してください。
範囲の下限を上限より大きな値に設定できます。
そうすると値の反転に使えます。
例 y = map(x, 1, 50, 50, 1);
範囲を指定するパラメータに負の数を使うこともできます。
例 y = map(x, 1, 50, 50, -100);
map関数は整数だけを扱います。
計算の結果、小数が生じる場合、小数部分は単純に切り捨てられます。
Arduino日本語リファレンス
pow(base, exponent)べき乗の計算をします。
小数も使えます。
指数関数的な値や曲線が必要なときに便利です。
Arduino日本語リファレンス
sqrt(x)平方根を求めます。Arduino日本語リファレンス
sq()数値の二乗を計算する。Arduino日本語リファレンス

三角関数

API説明リンク
sin(rad)正弦(sine)を計算します。
角度の単位はラジアンで、結果は-1から1の範囲です。
Arduino日本語リファレンス
cos(rad)余弦(cosine)を計算します。
角度の単位はラジアンで、結果は-1から1の範囲です。
Arduino日本語リファレンス
tan(rad)正接(tangent)を計算します。
角度の単位はラジアンです。
Arduino日本語リファレンス

乱数に関する関数

API説明リンク
randomSeed(seed)randomSeed関数は疑似乱数ジェネレータを初期化して、
乱数列の任意の点からスタートします。
この乱数列はとても長いものですが、
常に同一です。
random関数がスケッチを実行するたびに
異なった乱数列を発生することが重要な場合、
未接続のピンをanalogReadした値のような、
真にランダムな数値と組み合わせて
randomSeedを実行してください。
逆に、疑似乱数が毎回同じ数列を作り出す性質を利用する場合は、
randomSeedを毎回同じ値で実行してください。
Arduino日本語リファレンス
random(min, max)疑似乱数を生成します。Arduino日本語リファレンス

まとめ

今回は、M5StackのArduinoライブラリのAPIの一覧を紹介しました。

-M5Stack
-,

Copyright© ラズパイの実 , 2020 All Rights Reserved Powered by STINGER.