OpenSesame

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

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 script.

Software

  • OpenSesame (recent version)
  • Python with PyLSL: pip install pylsl

How it Works

  1. OpenSesame Experiment: Generates event markers during stimulus presentation and response collection
  2. LSL Monitoring: LabStreamingLayer provides real-time streaming of these markers with precise timestamps
  3. Mentalab Hypersync: Merges ExG data with event markers via LSL for wireless, high-precision synchronization

OpenSesame Experiment Structure

Based on the tree view shown, your experiment should follow this structure:

New experiment
├── experiment
    ├── init_lsl_script (Python script for LSL setup)
    └── loop
        └── sequence
            ├── sketchpad (stimulus presentation)
            ├── keyboard_response (response collection)
            └── push_to_lsl_script (marker transmission)

Step-by-Step Setup

1. Create the Experiment Structure

  1. New experiment: Start with a new OpenSesame experiment
  2. experiment: This is your main experiment block (currently selected in the tree)
  3. init_lsl_script: Add an inline_script item for LSL stream initialization
  4. loop: Add a loop item for trial repetition - Set its repeat value to some value higher than 1 (e.g. 10).
  5. sequence: Inside the loop, add a sequence item
  6. sketchpad: Add a sketchpad for stimulus presentation
  7. keyboard_response: Add a keyboard_response item for collecting keystrokes to initiate markers
  8. push_to_lsl_script: Add another inline_script for sending markers to the LSL stream

2. Configure the LSL Initialization Script

Item Name: init_lsl_script
Item Type: inline_script
Phase: Prepare

from pylsl import StreamInfo, StreamOutlet

# Create stream information
info = StreamInfo('opensesame_markers', 'Markers', 1, 0, 'string', 'os_marker_id')
outlet = StreamOutlet(info)

# Store outlet globally for access in other scripts
global lsl_outlet
lsl_outlet = outlet

3. Configure the Loop

Item Name: loop
Item Type: loop

  • This controls how many times your sequence runs
  • Set the number of trials e.g. 10
  • Configure any experimental variables for your use

4. Configure the Stimulus Presentation

Item Name: sketchpad
Item Type: sketchpad

  • Design your stimulus (text, images, etc.)
  • Set the duration to 0
  • This is where your experimental stimuli will be presented

5. Configure Response Collection

Item Name: keyboard_response
Item Type: keyboard_response

  • Configure it as you wish

6. Configure Marker Transmission Script

Item Name: push_to_lsl_script
Item Type: inline_script
Phase: Run

This script pushes keystrokes to the LSL stream.

global lsl_outlet

# Check if response was collected
if hasattr(var, 'response'):
    lsl_outlet.push_sample([str(var.response)])
    print(f"Sent marker: {var.response}")
else:
    print("Invalid action.")

Running the Experiment

Step 1: Start LSL Monitoring

  • Run your LSL listener script
  • Ensure it’s waiting for the stream

Step 2: Start streaming with hypersync suit

  • For synchronising your Mentalab Explore hardware with the stimulus presentation computer, please refer to the Hypersync instructions delivered to you with your Hypersync hardware.

Step 3: Run the Experiment in OpenSesame

  • Open your OpenSesame experiment
  • Run the experiment

Step 4: Check the received values in LSL monitoring

  • Use LabRecorder and select both the OpenSesame marker stream and your ExG data stream.
  • Optional: Use our LSL listener python script (see below) to check the received values in real-time.

Optional: Python Script for Listening to LSL Stream

Create a separate Python script to monitor the LSL stream:

from pylsl import StreamInlet, resolve_streams
import time

stream_name = "opensesame_markers"

print(f"Waiting for LSL stream '{stream_name}'...")
streams = []
while not streams:
    try:
        all_streams = resolve_streams()
        streams = [stream for stream in all_streams if stream.name() == stream_name]
        if not streams:
            print("No streams found, retrying...")
        time.sleep(0.1)
    except Exception as e:
        print(f"Error resolving stream: {e}")
        time.sleep(0.1)

print("Stream found. Connecting...")
inlet = StreamInlet(streams[0])

print("Listening for markers:")
try:
    while True:
        sample, timestamp = inlet.pull_sample(timeout=5.0)
        if sample:
            print(f"[{timestamp:.3f}] Marker received: {sample[0]}")
        else:
            print("Timeout — no marker received.")
except KeyboardInterrupt:
    print("\nStopping listener...")
except Exception as e:
    print(f"Error receiving data: {e}")

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