This guide details how to synchronize your Mentalab Explore device with OpenSesame experiments, focusing on high-precision synchronization of event markers using LabStreamingLayer (LSL) in combination with Mentalab Hypersync. This is the recommended approach for robust and accurate data alignment.

Legacy wired trigger methods are listed at the bottom.

Prerequisites

Before starting, ensure you have the following hardware and software:

Hardware

Mentalab Explore Pro Device: An Explore Pro biosignal acquisition system. Mentalab Hypersync Add-on: This hardware is essential for accurately synchronizing LSL markers from OpenSesame with the Explore device’s data stream. Computer: To run OpenSesame, LSL, and data recording software.

Software

OpenSesame: A recent version of OpenSesame. Python: OpenSesame’s scripting language. PyLSL (pylsl): The Python library for LabStreamingLayer. Install via pip:

pip install pylsl

This method uses LSL to transmit event markers from your OpenSesame experiment. This guide contains instructions for sending LSL markers from your OpenSesame experiment. For all following steps, please refer to the Hypersync instructions delivered to you with your Hypersync hardware.

How it Works

OpenSesame Experiment: Your OpenSesame script generates experimental events (e.g., stimulus onset, response).
PyLSL Markers: At each event, Python sends an event marker via an LSL stream.
Mentalab Hypersync: The Mentalab Hypersync suite is used to merge ExG data with the event markers via LSL. Please follow the instructions delivered to you with your Hypersync hardware.

Python Code Snippets for LSL You will typically use two inline_script items: one at the beginning of your experiment for setup, and others throughout your experiment to send markers.

1. Setup inline_script (at the beginning of the experiment)

Place an inline_script item (e.g., named lsl_setup) at the very beginning of your experiment sequence.

In the Prepare phase of this inline_script, add the following Python code to import necessary pylsl classes and define your stream information:

# Import necessary pylsl classes
from pylsl import StreamInfo, StreamOutlet

# Define the stream information for markers
marker_stream_info = StreamInfo(name='OpenSesameExperimentMarkers', # A recognizable name (e.g., 'OpenSesameExperimentMarkers')
                                type='Markers',                     # Conventionally 'Markers'
                                channel_count=1,                    # 1 for single integer markers
                                nominal_srate=0.0,                  # 0.0 for irregular events
                                channel_format='int32',             # 'int32' for integer markers
                                source_id='YourExperimentUniqueID') # A unique ID for this stream source

# Create the LSL outlet and store it in the experiment object for later access
exp.marker_outlet = StreamOutlet(marker_stream_info)
print("LSL Marker Outlet created. Stream Name: OpenSesameExperimentMarkers")

2. Sending Markers inline_script (during trials/events)

Place an inline_script item at the exact point in your trial sequence where you want to send a marker (e.g., immediately before a stimulus presentation or after a response).

In the Run phase of this inline_script, add the following Python code:

# Access the LSL outlet stored in the experiment object
marker_outlet = exp.marker_outlet

# Define your marker value
# This can be a fixed integer, an OpenSesame variable, or a combination
label_value = 11 # Example: 11 for a target stimulus
# or, if you have an OpenSesame variable named 'stim_type':
# label_value = var.stim_type

# Push the marker to the LSL stream
marker_outlet.push_sample([label_value]) # Send LSL marker for stimulus onset (argument must be a list or tuple)
print(f"LSL Marker Sent: {label_value}")

It’s critical to send the marker as close as possible to the event’s actual occurrence (e.g., immediately after the sketchpad or sampler item that presents the stimulus).

These steps will create an LSL Marker stream that can be recorded using LabRecorder.
To ensure accurate synchronisation, you must use Mentalab Hypersync and follow the instructions provided alongside your Hypersync hardware.

Alternative (Legacy) Methods: Wired Triggers

While LSL with Hypersync is preferred as it enables fully wireless and highly accurate event marking, direct wired connections are also possible. Please refer to our Event Triggers page for further information.

Copyright © 2025 Mentalab