ドキュメンテーション

最新のリリースでは、このページがまだ翻訳されていません。 このページの最新版は英語でご覧になれます。

イベントとコールバック

はじめに

"イベント" を使用することで、シリアル ポート アプリケーションの能力やフレキシビリティを拡張できます。イベントは、条件が満たされた後に発生し、1 つまたは複数のコールバックを引き起こす場合があります。

シリアル ポート オブジェクトがデバイスに接続されている場合は、イベントを使用してメッセージの表示、データの表示、データの解析などのアクションを実行します。コールバックは "コールバック プロパティ" および "コールバック関数" を使用して制御されます。すべてのイベント タイプには関連するコールバック プロパティがあります。コールバック関数は、ユーザー独自のアプリケーションのニーズに合うように構成した MATLAB® 関数です。

コールバック関数名を対応するコールバック プロパティの値として指定することで、特定のイベントが発生するときにコールバックを実行します。

例 — イベントとコールバックについて

この例では、バイトを利用可能なイベントが発生した場合に、コールバック関数 instrcallback を使用してメッセージをコマンド ラインに表示します。イベントは、終端子が読み取られたときに生成されます。

s = serial('COM1');
s.BytesAvailableFcnMode = 'terminator';
s.BytesAvailableFcn = @instrcallback;
fopen(s)
fprintf(s,'*IDN?')
out = fscanf(s);

MATLAB に以下のように表示されます。

BytesAvailable event occurred at 17:01:29 for the object: 
Serial-COM1.

シリアル ポート セッションを終了します。

fclose(s)
delete(s)
clear s

組み込み関数 instrcallback のコードを確認するには、type コマンドを使用します。

イベント タイプとコールバック プロパティ

次の表では、シリアル ポート イベント タイプとコールバック プロパティについて説明します。この表は 2 列 9 行で構成されています。最初の列 (イベント タイプ) にある 2 番目の項目 (利用可能なバイト) は、行 2 ~ 4 に適用されます。また、最初の列にある最後の項目 (タイマー) は、行 8 および 9 に適用されます。

イベント タイプとコールバック プロパティ

イベント タイプ関連するプロパティ

ブレーク割り込み

BreakInterruptFcn

利用可能なバイト

BytesAvailableFcn

BytesAvailableFcnCount

BytesAvailableFcnMode

エラー

ErrorFcn

出力が空

OutputEmptyFcn

ピン ステータス

PinStatusFcn

タイマー

TimerFcn

TimerPeriod

ブレーク割り込みイベント

ブレーク割り込みイベントは、シリアル ポートによってブレーク割り込みが発生した直後に生成されます。シリアル ポートは、受信データが 1 文字に対する送信時間よりも長く非アクティブ状態であるときにブレーク割り込みを生成します。

このイベントは、BreakInterruptFcn プロパティに対して指定されたコールバック関数を実行します。同期および非同期の読み取りおよび書き込み操作に対して生成できます。

バイト利用可能なイベント

バイト利用可能なイベントは、事前に決定されたバイト数が入力バッファー内で利用可能になった直後か、BytesAvailableFcnMode プロパティで指定されて終端子が読み取られた直後に生成されます。

BytesAvailableFcnModebyte である場合、BytesAvailableFcnCount で指定されたバイト数が入力バッファーに格納されるたびに、バイト利用可能なイベントは BytesAvailableFcn プロパティに対して指定されたコールバック関数を実行します。BytesAvailableFcnModeterminator である場合、コールバック関数は Terminator プロパティで指定された文字が読み取られるたびに実行します。

このイベントは、非同期の読み取り操作中にのみ生成されます。

エラー イベント

エラー イベントは、エラーが発生した直後に生成されます。

このイベントは、ErrorFcn プロパティに対して指定されたコールバック関数を実行します。非同期の読み取りまたは書き込み操作中にのみ生成できます。

エラー イベントは、タイムアウトの発生時に生成されます。タイムアウトは、読み取りまたは書き込み操作が Timeout プロパティで指定した時間内に終了しなかった場合に発生します。エラー イベントは、無効なプロパティ値の設定などの構成エラーに対して生成されません。

出力が空のイベント

出力が空のイベントは、出力バッファーが空になった直後に生成されます。

このイベントは、OutputEmptyFcn プロパティに対して指定されたコールバック関数を実行します。非同期の書き込み操作中にのみ生成できます。

ピン ステータス イベント

ピン ステータス イベントは、CD、CTS、DSR または RI ピンの状態 (ピンの値) が変化した直後に生成されます。これらのピンの説明は、シリアル ポート信号とピン割り当てを参照してください。

このイベントは、PinStatusFcn プロパティに対して指定されたコールバック関数を実行します。同期および非同期の読み取りおよび書き込み操作に対して生成できます。

タイマー イベント

タイマー イベントは、TimerPeriod プロパティで指定した時間が経過したときに生成されます。時間は、シリアル ポート オブジェクトがデバイスに接続された時点からの相対時間です。

このイベントは、TimerFcn プロパティに対して指定されたコールバック関数を実行します。システムの処理速度が大幅に低下した場合や、TimerPeriod 値が小さすぎる場合は、一部のタイマー イベントが処理されないことがあるため、注意してください。

イベント情報への対応

コールバック関数またはレコード ファイルのイベント情報に対応できます。イベント情報は、2 つのフィールド Type および Data を使用してコールバック関数に格納されます。Type フィールドにはイベント タイプ、Data フィールドにはイベント固有の情報がそれぞれ含まれます。コールバック関数の作成と実行に示すように、これらの 2 つのフィールドはコールバック関数のヘッダーで定義する構造体に関連付けられます。データとイベント情報のレコード ファイルへの記録に関しては、デバッグ: 情報をディスクに記録を参照してください。

次の表に、Type フィールドおよび Data フィールドのイベント タイプと値を示します。この表は 3 列 15 行で構成されています。最初の列 (イベント タイプ) の項目は以下のように複数の行にまたがっています。

ブレーク割り込み: 行 1 および 2

利用可能なバイト: 行 3 および 4

エラー: 行 5 ~ 7

出力が空: 行 8 および 9

ピン ステータス: 行 10 ~ 13

タイマー: 行 14 および 15

イベント情報

イベント タイプフィールドフィールドの値

ブレーク割り込み

Type

BreakInterrupt

Data.AbsTime

日-月-年、時間:分:秒

利用可能なバイト

Type

BytesAvailable

Data.AbsTime

日-月-年、時間:分:秒

エラー

Type

Error

Data.AbsTime

日-月-年、時間:分:秒

Data.Message

エラー文字列

出力が空

Type

OutputEmpty

Data.AbsTime

日-月-年、時間:分:秒

ピン ステータス

Type

PinStatus

Data.AbsTime

日-月-年、時間:分:秒

Data.Pin

CarrierDetectClearToSendDataSetReady または RingIndicator

Data.PinValue

on または off

タイマー

Type

Timer

Data.AbsTime

日-月-年、時間:分:秒

次のトピックでは、Data フィールドの値について説明します。

AbsTime フィールド

AbsTime フィールドは、すべてのイベントに対して定義され、イベントが発生した絶対時間を示します。絶対時間は、clock 形式で返されます。日-月-年、時間:分:秒。

Pin フィールド

ピン ステータス イベントは Pin フィールドを使用して、CD、CTS、DSR または RI ピンによって状態が変更されたかどうかを示します。これらのピンの説明は、シリアル ポート信号とピン割り当てを参照してください。

PinValue フィールド

ピン ステータス イベントは PinValue フィールドを使用して、CD、CTS、DSR または RI ピンの状態を示します。使用できる値は on または off です。

Message フィールド

このエラー イベントは Message フィールドを使用して、エラー発生時に生成される説明的なメッセージを格納します。

コールバック関数の作成と実行

特定のイベント タイプの発生時に実行されるコールバック関数を指定するには、関連するコールバック プロパティの値としてファイル名を設定します。コールバック関数は、関数ハンドルまたは文字列 cell 配列要素として指定できます。関数ハンドルについての詳細は、関数ハンドルの作成を参照してください。

たとえば、デバイスから終端子が読み取られるたびにコールバック関数 mycallback を実行するには次のようにします。

s.BytesAvailableFcnMode = 'terminator';
s.BytesAvailableFcn = @mycallback;

または、1 つの cell 配列としてコールバック関数を指定できます。

s.BytesAvailableFcn = {'mycallback'};

コールバック関数には 2 つ以上の入力引数が必要です。1 番目の引数は、シリアル ポート オブジェクトです。2 番目の引数は、表イベント情報に示すようなイベント情報を取得する変数です。このイベント情報は、コールバック関数が実行されるイベントのみに適用されます。mycallback 用の関数ヘッダーは、次のとおりです。

function mycallback(obj,event)

コールバック関数とパラメーターを cell 配列の要素として設定することで、追加パラメーターをコールバック関数に渡します。たとえば、MATLAB 変数 timemycallback に渡すには次のようにします。

time = datestr(now,0);
s.BytesAvailableFcnMode = 'terminator';
s.BytesAvailableFcn = {@mycallback,time};

または、1 つの cell 配列の文字列としてコールバック関数を指定できます。

s.BytesAvailableFcn = {'mycallback',time};

対応する関数ヘッダーは以下のとおりです。

function mycallback(obj,event,time)

追加パラメーターをコールバック関数に渡す場合は、関数ヘッダーの 2 つの必須の引数の後に設定しなければなりません。

メモ

コールバック関数を文字列として指定することもできます。この場合、コールバックは MATLAB ワークスペースで評価され、コールバック関数の入力引数には必要条件はありません。

エラー後のコールバック関数の有効化

コールバック関数の実行中にエラーが発生すると、次のような状態が発生します。

  • コールバック関数は自動的に無効になります。

  • コールバック関数が無効であることを示す警告がコマンド ラインに表示されます。

同じコールバック関数を有効にするには、コールバック プロパティを同じ値に設定するか、関数 fclose を使用してオブジェクトを切断します。別のコールバック関数を使用する場合は、コールバック プロパティを新しい値に構成するとコールバックが有効になります。

例 — イベントとコールバックの使用

この例では、バイトを利用可能なイベントまたは出力が空のイベントが発生した場合に、コマンド ラインにイベント関連情報を表示するためにコールバック関数 instrcallback を使用します。

  1. シリアル ポート オブジェクトの作成 — シリアル ポート COM1 に関連するシリアル ポート オブジェクト s を作成します。

    s = serial('COM1');
  2. プロパティの設定 — バイトを利用可能なイベントまたは出力が空のイベントが発生した場合に、コールバック関数 instrcallback が実行されるように s を設定します。instrcallback ではシリアル ポート オブジェクトとイベント情報を入力引数として渡す必要があるため、コールバック関数は関数ハンドルとして指定されます。

    s.BytesAvailableFcnMode = 'terminator';
    s.BytesAvailableFcn = @instrcallback;
    s.OutputEmptyFcn = @instrcallback;
  3. デバイスへの接続 — s を Tektronix® TDS 210 オシロスコープに接続します。ReadAsyncMode プロパティの既定値は continuous であるため、データは機器から読み取り可能になるとすぐに入力バッファーに非同期的に返されます。

    fopen(s)
  4. データの書き込みと読み取り — RS232? コマンドをオシロスコープに非同期的に書き込みます。このコマンドは、RS-232 設定をクエリし、ボー レート、ソフトウェア フロー制御設定、ハードウェア フロー制御設定、パリティ タイプおよび終端子を返します。

    fprintf(s,'RS232?','async')

    instrcallback は、RS232? コマンドが送信された後で終端子が読み取られると呼び出されます。次のような結果が表示されます。

    OutputEmpty event occurred at 17:37:21 for the object: 
    Serial-COM1.
    
    BytesAvailable event occurred at 17:37:21 for the object: 
    Serial-COM1.

    入力バッファーからデータを読み取ります。

    out = fscanf(s)
    out =
    9600;0;0;NONE;LF
  5. 切断とクリーンアップ — s が不要になったら、機器から切断し、メモリおよび MATLAB ワークスペースから削除します。

    fclose(s)
    delete(s)
    clear s