
Websocket トリガー
Websocket Trigger は、実行中の研究が WebSocket 接続を通じてメッセージを受信したときに発火します。これにより、ローカルスクリプト、記録デバイス、または外部サーバーがブラウザの外部で何かが発生した瞬間に研究内でイベントを開始できます。
概要
Websocket Trigger はトリガー選択メニューの API/External Trigger カテゴリにリストされています。Send to Websocket Action と共に、Labvanced の外部で実行されるソフトウェアと研究との双方向通信を提供します。
一般的な使用例
Websocket Trigger は、研究の外部からの信号が研究内での出来事を変更すべき場所で使用されます。
- LSL マーカーの受信: ローカルの Python スクリプトが別の Lab Streaming Layer デバイスからマーカーを研究に渡し、研究はそれを自分のタイムスタンプの隣に記録できます。全体の概要については EEG & Hardware Integrations を参照してください。
- クローズドループとバイオフィードバックデザイン: 生理的信号を処理するスクリプトが閾値を超えるたびにメッセージを送信し、研究は応じて刺激を変更します。
- 外部処理: サーバーが研究から送信されたデータを分析し、研究が表示または記録する結果(例えば、分類やスコア)を返します。
仕組み
Websocket Trigger にアクセスするには、タスクエディタで Event System を開き、新しいイベントを作成します。API/External Trigger カテゴリの下で Websocket Trigger を選択します。
トリガーを使用する前に、研究設定で接続を有効にします:
Settingsタブを開きます。Special Featuresドロップダウンを開き、Websocket Connectionセクションを見つけます。- それを有効にするオプションをチェックし、次に
WebSocket AddressとPortを入力します。デフォルトはws://localhostと8081で、研究と同じコンピュータ上で実行されているスクリプトに接続します。
ダイアログには以下が含まれます:
| オプション | 説明 |
|---|---|
Websocket Address | 研究設定からのアドレスを表示します。ここでは編集できません。 |
Port | 研究設定からのポートを表示します。ここでは編集できません。 |
trigger / message | このイベントを発火させるメッセージラベルです。受信メッセージのラベルがこのテキストと正確に一致する場合にトリガーが発火します。すべての受信メッセージで発火させるには any を入力します。 |
研究が開始されると、Labvanced は入力したアドレスとポートへの接続を開きます。設定で接続が有効になっていない場合、接続は開かれず、トリガーは決して発火しません。
トリガーは、イベントを含むフレームが表示されている間のみリッスンします。別のフレームが表示されている間に届いたメッセージはこのイベントを開始しません。研究がメッセージに反応すべきすべてのフレームにイベントを配置してください。
any を持つイベントはすべてのメッセージに対して発火します。同じフレームの別のイベントが特定のラベルを使用すると、そのラベルを持つメッセージが届くと両方のイベントが発火します。
送信プログラムが提供するもの
トリガーは、Labvanced の外部でプログラムがメッセージを送信した場合にのみ発火します。そのプログラムは通常、同じコンピュータ上の短いスクリプトで、研究が接続する WebSocket サーバーを実行しています。送信される各メッセージには 2 つの部分があります:
- ラベル: トリガーはこれを
trigger / messageフィールドと比較します。一致するとイベントが発火し、ラベルはMessage値として利用可能になります。 - コンテンツ: スクリプトが渡したい任意の値、たとえばマーカー値や測定値です。これは
Data値として利用可能です。
スクリプトを書いている人にとって、各メッセージは msg フィールドのラベルと value フィールドの内容を含む JSON オブジェクトです。GitHub の Labvanced WebSocket API リポジトリ にあるサンプルスクリプトは、この方法で LSL マーカーを送受信し、良い出発点となります。接続設定の詳細については、WebSocket API ガイドを参照してください。
トリガー特有の値
トリガーが発火した後、次の値がイベントのアクションで利用可能になります。これらは Trigger (Websocket Trigger) の下の Value-Select Menu から選択できます。
| 値 | 説明 |
|---|---|
Message | 受信メッセージのラベルです。メッセージのタイプを区別するために使用します。特に any を使用するイベント内で。 |
Data | 受信メッセージのコンテンツです。数値、文字列、リストなどの任意の JSON 値を保持でき、Set / Record Variable Action で変数に保存できます。 |
Trigger Timestamp (Unixtime) | トリガーが発火した時刻、ミリ秒での Unix 時間。 |
Trigger Time (From Frame Onset) | フレームの開始からトリガーが発火する瞬間までのミリ秒。 |
ワークフローヒント
- スクリプトを研究を開始する前に起動してください。接続は研究の開始時に開かれます。
- データ収集を行う前に、スクリプトと同じコンピュータ上で走っている研究を使用して接続をテストしてください。デフォルトの
ws://localhostは、そのコンピュータ上のプログラムにしか到達しません。 - メッセージのラベルは短く、一貫性を持たせて、スクリプトと研究間で一致させてください。完全一致で比較されるため
Markerとmarkerは異なるメッセージです。 - メッセージのタイミングが分析にとって重要な場合は、
Trigger Time (From Frame Onset)とDataを一緒に記録します。
研究と例のシナリオ
別のデバイスからマーカーを受信する。 LSL Receive Marker ライブラリの研究では、外部デバイスによって生成されたマーカーがローカルの Python スクリプトに届き、そこから Websocket Trigger を通じて研究に渡されます。研究はその後、マーカー値を記録します。ライブラリ内の Inspect オプションを使用してイベント設定を確認してください。
双方向メッセージング。 Socket Connection Example ライブラリの研究では、Send to Websocket アクションで研究からメッセージを送信し、このトリガーでその返信に反応します。