
Websocket Trigger
The Websocket Trigger fires when your running study receives a message over its WebSocket connection. It lets a local script, a recording device, or an external server start an event in your study at the moment something happens outside the browser.
Table of Contents
Overview
The Websocket Trigger is listed under the API/External Trigger category in the trigger selection menu. Together with the Send to Websocket Action, it gives a study two-way communication with software running outside Labvanced.
Common Use Cases
The Websocket Trigger is used wherever a signal from outside the study should change what happens in the study.
- Receiving LSL markers: a local Python script passes a marker from another Lab Streaming Layer device into the study, so the study can record it next to its own timestamps. See EEG & Hardware Integrations for the full picture.
- Closed-loop and biofeedback designs: a script that processes a physiological signal sends a message whenever a threshold is crossed, and the study changes the stimulus in response.
- External processing: a server analyzes data sent from the study and returns a result, such as a classification or a score, that the study then displays or records.
How It Works
To access the Websocket Trigger, open the Event System in the Task Editor and create a new event. Under the API/External Trigger category, select Websocket Trigger.
Before the trigger can be used, enable the connection in the study settings:
- Open the
Settingstab. - Open the
Special Featuresdrop-down and find theWebsocket Connectionsection. - Check the option to enable it, then enter the
WebSocket Addressand thePort. The defaults arews://localhostand8081, which connect to a script running on the same computer as the study.
The dialog contains the following:
| Option | Description |
|---|---|
Websocket Address | Shows the address from your study settings. It cannot be edited here. |
Port | Shows the port from your study settings. It cannot be edited here. |
trigger / message | The message label that fires this event. The trigger fires when the label of an incoming message matches this text exactly. Enter any to fire on every incoming message. |
When the study starts, Labvanced opens the connection to the address and port you entered. If the connection is not enabled in the settings, no connection is opened and the trigger never fires.
The trigger listens only while the frame that contains the event is displayed. A message that arrives while a different frame is displayed does not start this event. Put the event on every frame where the study should react to the message.
An event with any fires for every message. If another event on the same frame uses a specific label, both events fire when a message with that label arrives.
What the Sending Program Provides
The trigger only fires if a program outside Labvanced sends it a message. That program, usually a short script on the same computer, runs the WebSocket server that the study connects to. Each message it sends has two parts:
- A label: the trigger compares it with the
trigger / messagefield. When they match, the event fires, and the label is available as theMessagevalue. - Content: any value the script wants to pass along, such as a marker value or a measurement. It is available as the
Datavalue.
For the person writing the script, each message is a JSON object with the fields msg for the label and value for the content. The example scripts in the Labvanced WebSocket API repository on GitHub send and receive LSL markers this way and are a good starting point. For the connection setup, see the WebSocket API guide.
Trigger-Specific Values for Websocket Trigger
After the trigger fires, the following values are available in the actions of the event. Select them through the Value-Select Menu under Trigger (Websocket Trigger).
| Value | Description |
|---|---|
Message | The label of the received message. Use it to tell message types apart, especially in an event that uses any. |
Data | The content of the received message. It can hold any JSON value, such as a number, a string, or a list, and can be stored in a variable with the Set / Record Variable Action. |
Trigger Timestamp (Unixtime) | The time at which the trigger fired, in Unix time with milliseconds. |
Trigger Time (From Frame Onset) | The time in milliseconds from the start of the frame to the moment the trigger fired. |
Workflow Tips
- Start your script before you start the study. The connection is opened when the study starts.
- Test the connection with the study running on the same computer as the script before you collect data. The default
ws://localhostonly reaches programs on that computer. - Keep message labels short and consistent between the script and the study. The match is exact, so
Markerandmarkerare different messages. - Record
Trigger Time (From Frame Onset)together withDatawhen the timing of the message matters for analysis.
Studies & Example Scenarios
Receiving a marker from another device. In the LSL Receive Marker library study, a marker produced by an external device reaches a local Python script, which passes it to the study through a Websocket Trigger. The study then records the marker value. Use the Inspect option in the library to see the event setup.
Two-way messaging. The Socket Connection Example library study sends a message out of the study with the Send to Websocket action and reacts to the replies with this trigger.
Further Reading
Send to Websocket Action
The paired action for sending a message or a variable out of the study.
WebSocket API
How to connect a study to a local script or an external server.
Value Select Menu
How to reference trigger-specific values in your actions.
Events Overview
A full introduction to the trigger-and-action logic system in Labvanced.