使い方

API リファレンスといくつかのサンプルスクリプトがあります。
これらスクリプトを実際に動かし中身を覗くことで Gorilla API を理解出来るはずです。

このチュートリアルでは SerialPort クラスの基本的な使い方について説明します。

  1. PHPMake 名前空間
  2. ポートを開く
  3. ポートを設定する
  4. データの読み込み
  5. データの書き込み
  6. ポートを閉じる
  7. サンプルコード

PHPMake 名前空間

バージョン 0.5.0 以降において、 PHPMake という名前空間を導入しました。
以下のチュートリアルにおいて SerialPort クラスを PHPMake¥SerialPort と読み替えるか、
クラス使用前に use PHPMake¥SerialPort as SerialPort; のステートメントを挿入する必要があります。
後者の方が変更が少なく簡便です。

ポートを開く

シリアルポートに対する操作を行う前に SerialPort クラスのインスタンスを作り、ポートを開く必要があります。
一つの方法は、コンストラクタにポートを指定して開きます。

$port = new SerialPort('COM3');

別の方法として SerialPort::open() を用いることもできます。

$port = new SerialPort();
$port->open('COM3');

ボーレート

SerialPort::setBaudRate() メソッドを用いてボーレートを設定します。

$port->setBaudRate(SerialPort::BAUD_RATE_9600);

引数には SerialPort のクラス定数 SerialPort::BAUD_RATE_* を用います。
もしくはこのクラス定数を用いずに整数リテラルを指定することもできます。ただし、指定した値がクラス定数 SerialPort::BAUD_RATE_* に存在しない場合、例外がスローされます。

$port->setBaudRate(9600);

フロー制御

SerialPort::setFlowControl() を用いてフロー制御の方法を決定します。

$port->setFlowControl(SerialPort::FLOW_CONTROL_NONE);

引数には次のいずれかを指定します。

  • SerialPort::FLOW_CONTROL_NONE
    フロー制御なし
  • SerialPort::FLOW_CONTROL_SOFT
    ソフトウェアフロー制御
  • SerialPort::FLOW_CONTROL_HARD
    ハードウェアフロー制御

読み込みタイムアウト

データを読み込む方法は大きく2つの方法に分類できます。これらの方法は SerialPort::read() がどのようにタイムアウトするのかを決定します。

カノニカル入力モード

カノニカル入力モードは改行文字が送信されてくるまで読み込みを続け、呼び出し元に制御を戻しません(ブロックします)。改行文字が送信されてきたらそれまでに受け取った末尾の改行文字までを含むデータを返します。

$port->setCanonical(true);

カノニカルモードでは VTIME, VMIN (後述)の設定は無視されます。

非カノニカル入力モード

非カノニカル入力モードでの読み込みタイムアウトはデータ中の改行文字の有無に関わらず、 VTIME, VMIN という2つの値によって決定されます。

VTIME
VTIME はデータを待ち受ける時間です。VTIME が取り得る値は 0 から 255 までで 1/10 秒単位で指定します。 VTIME に 100 を指定した場合、10秒間データを待ち受けます。
VMIN
VMIN は最低限読み込むデータサイズ(バイト数)を示します。

非カノニカル入力モードでは VTIME, VMIN の組み合わせにより、4通りのタイムアウトがあります。

VTIME = 0 かつ VMIN = 0 の場合
$port->setCanonical(false)
        ->setVTime(0)->setVMin(0);

この場合では SerialPort::read() は次のように振る舞います。

  • 読み込み可能なデータがあれば、それをすぐに返す
  • 読み込み可能なデータがない場合、何も読み込まずすぐに呼び出し元に制御を戻す

つまりこの場合では、読み込み時にブロックを行いません。

VTIME > 0 かつ VMIN = 0 の場合
$port->setCanonical(false)
        ->setVTime(1)->setVMin(0);

この設定で SerialPort::read() は次のように振る舞います。

  • 読み込み可能なデータがあればそれを読み込み、呼び出し元に戻る
  • 読み込み可能なデータがない場合、データが送られてくのを VTIME だけ待ち、その間ブロックする。
  • VTIME を過ぎてデータがない場合、何も読み込まずに呼び出し元に戻る。
VTIME = 0 かつ VMIN > 0 の場合
$port->setCanonical(false)
        ->setVTime(0)->setVMin(1);

この設定では SerialPort::read() は最低 VMIN バイト読み込むまで呼び出し元に制御を戻しません。

VTIME > 0 かつ VMIN > 0 の場合
$port->setCanonical(false)
        ->setVTime(1)->setVMin(1);

データを VMIN だけ受け取るか、次のデータ読み込みまでに VTIME 以上費やした場合に呼び出し元に戻ります。
VTIME を計るタイマーは1バイト目のデータが来て初期化されます。つまり1バイト目のデータがいつまでたっても来ないなら、無期限にブロックされます。
1バイト目を受け取り、 VTIME 内に受信データの合計サイズが VMIN かそれ以上になった時点で、受信データを返し、制御は呼び出し元に戻ります。
一方 VTIME 内に受信データの合計サイズが VMIN を満たさなかった場合、少なくともその時点までに受け取ったデータを返し、制御は呼び出し元に戻ります。

データの読み込み

SerialPort::read() によりデータ読み込みを行います。

$data = $port->read(256);

引数には読み込むデータのバイト数を指定します。
このバイト数は最大であり、実際に読み込まれるデータはこのバイト数に達しない場合もあります。
読み込まれたデータのサイズは strlen($data) を用いて確認できます。

$dataSize = strlen($data);

データの書き込み

書き込みは SerialPort::write() を用います。引数には書き込むデータを指定します。
SerialPort::write() は与えられたデータの書き込みを試み、実際に書きこまれたデータのバイト数を返します。

$written = $port->write('hello');

ポートを閉じる

SerialPort::close メソッドにより使用しなくなったポートを閉じます。

$port->close();

ポートを閉じて後に SerialPort::read()SerialPort::setBaudRate() といったメソッドを実行することはできません。その際には再びポートを開く必要があります。

$port->close();
$port->open('COM3');
$port->setBaudRate(SerialPort::BAUD_RATE_9600);

サンプルコード

上述した一連の流れを示したサンプルプログラムを以下に示します。

<?php
/* シリアルポートを開きます */
$port = new SerialPort('COM3');

/* ボーレートを 9600 に設定します */
$port->setBaudRate(SerialPort::BAUD_RATE_9600);

/* フロー制御は行いません */
$port->setFlowControl(SerialPort::FLOW_CONTROL_NONE);

/* 
 * データの読み込みにカノニカル入力モードを用いません。
 * この設定では SerialPort::read() は
 * 最低1バイト読み込むまで呼び出し元に制御を戻しません。
 */
$port->setCanonical(false)
        ->setVTime(0)->setVMin(1);

/* データを送信します。 */
$written = $port->write('hello');

/* 
 * 最大256バイトまでデータを読み込みます。
 * 上で行った読み込みタイムアウトの設定と合わせると、
 * SerialPort::read() は次のように振る舞います。
 * 
 * - 最低1バイト読み込むまでブロックする
 * - 最大256バイト読み込む
 * 
 * 実際に読み込まれたデータのサイズは 
 * strlen($data) 
 * などとして求められます。
 */
$data = $port->read(256);
$dataSize = strlen($data);
var_dump($data);

/* ポートを閉じます */
$port->close();

 
Set your Twitter account name in your settings to use the TwitterBar Section.