Quickstart — 15-minute integration

This guide walks you through your first working integration: install the SDK, connect an EEG amplifier via Lab Streaming Layer (LSL), calibrate a session, and stream decoded motor-imagery commands.

Prerequisites

Python ≥ 3.9 (tested on 3.10, 3.11, 3.12)
An EEG amplifier with LSL support (8–32 channels, C3/Cz/C4 required)
Synaptiq SDK license key (from your developer portal)
numpy ≥ 1.24, scipy ≥ 1.10, pylsl ≥ 1.16

Step 1 — Install the SDK

terminal

# Install from the Synaptiq package registry
pip install synaptiq

# Verify installation
python -c "import synaptiq; print(synaptiq.__version__)"
# Expected: 0.9.2

The SDK ships with pre-built native extensions for Windows x64, Linux x86_64, and macOS arm64/x86_64. No compilation required.

Step 2 — Connect your EEG amplifier

Synaptiq reads EEG via Lab Streaming Layer (LSL). Start your amplifier's LSL stream before creating a session. Most clinical-grade amplifiers support LSL via their companion software or open-source drivers.

connect_eeg.py

import synaptiq

# Synaptiq will search for an LSL EEG stream on the network
session = synaptiq.Session(
    device="lsl",      # Use LSL for acquisition
    channels=16,     # Number of EEG channels
    srate=500,       # Sampling rate in Hz
    license_key="YOUR_LICENSE_KEY"
)

# Verify connection and signal quality
quality = session.check_signal_quality()
print(f"Signal quality: {quality.grade} ({quality.impedance_kΩ_avg:.1f} kΩ avg)")

Step 3 — Calibrate the session

Calibration collects labeled motor-imagery epochs to train the CSP/Riemannian classifier for this participant. The default protocol is 60 trials × 2 classes, ~8 minutes total.

calibrate.py

# Run guided calibration — shows instruction prompts
result = session.calibrate(
    classes=["left_hand", "right_hand"],
    trials_per_class=60,
    epoch_duration_s=4.0,
    rest_duration_s=2.5
)

print(f"Calibration accuracy: {result.cv_accuracy:.1%}")
# Expected: 0.88–0.96 for good electrode contact

# Save calibration for future sessions (enables Euclidean alignment)
session.save_calibration("./calibration_patient_001.snpq")

Step 4 — Start the decode stream

Once calibrated, decode_stream() runs the full pipeline in a background thread. Commands arrive via the callback as Command objects with label, confidence, and latency fields.

decode.py

import time

def on_command(cmd):
    # cmd.label: 'left_hand' | 'right_hand' | 'rest'
    # cmd.confidence: 0.0–1.0 (use >0.7 threshold for device output)
    # cmd.latency_ms: end-to-end decode latency
    print(f"[{cmd.latency_ms:.0f}ms] {cmd.label} conf={cmd.confidence:.2f}")

# Blocks until session.stop() is called
session.decode_stream(callback=on_command)

# In a real integration, stop after therapy session ends
time.sleep(3600)
session.stop()

Step 5 — Route commands to your device

For production integration, replace the print callback with a device output driver. The SDK ships with built-in output adapters for the most common interfaces.

full_integration.py

from synaptiq.output import UDPOutput, SerialOutput, DigitalIOOutput

# Route to multiple outputs simultaneously
session.add_output(UDPOutput(host="192.168.1.50", port=5005))
session.add_output(SerialOutput(port="/dev/ttyUSB0", baud=115200))

# Only output commands above confidence threshold
session.set_confidence_threshold(0.72)

# Load prior session calibration for Euclidean alignment
session.load_calibration("./calibration_patient_001.snpq")

session.decode_stream()

Next steps: read the API Reference for the full method and parameter list, or the Signal Pipeline guide to understand and tune the preprocessing parameters for your electrode configuration.