Installation¶

One-time setup to get the toolbox running on your own machine. This is the canonical copy of these steps — README.md in the repository keeps only the bare command block and a pointer here, so there is exactly one place this can drift.

Prerequisites¶

A git client to clone the repository — Git for Windows, GitHub Desktop, or an editor's built-in git support all work. (The conda environment created below pulls its own git binary in, so nothing later — the test suite, analysis provenance stamps — depends on whichever client you used to clone, or on it being on your system PATH.)
conda or a conda-compatible installer (e.g. Miniforge). The toolbox is developed and tested against one named environment, ssvep, built from environment.yml.
A machine that can open a desktop window (the GUI needs a display; a headless machine can still run the test suite and offline analysis scripts).

Install¶

Which repository to clone

The URL below is the toolbox's own source repository, which is not yet public ahead of its first release. If you were given a different repository URL — a course or teaching copy — clone that one instead and skip straight to cd; everything after that step is identical.

git clone https://github.com/ssvep-toolbox/ssvep-toolbox.git
cd ssvep-toolbox
conda env create -f environment.yml
conda activate ssvep
pip install -e . --no-deps
pytest -q -n auto

If conda env create stops with Preparing transaction: failed and an error about conda-launchers/cli-64.exe (Windows, recent Miniforge), see Troubleshooting: one command fixes it.

If the last line runs and finishes without failures, the install is good — that is the whole verification step. It is the full suite: run serially (plain pytest -q) it takes a very long time, so -n auto spreads it over one process per CPU core (pytest-xdist is part of the environment). Run it from the repository root, with the ssvep environment activated, any time you want to confirm the install still works (after a git pull, for instance).

Next, set up the graphics. Before you show a participant anything, read Graphics and display setup: vsync, G-SYNC and FreeSync, HDR, which monitor is the stimulus display, and integrated versus dedicated graphics. The defaults on most computers are wrong for a flicker stimulus.

Why `pip install -e . --no-deps`, exactly like that¶

-e (editable): the package is installed as a link back to this checkout rather than copied into the environment. Some of the toolbox's own path resolution depends on that — for example, the run-manifest reader locates schemas/ relative to the installed package's location, which only resolves correctly when the install is the checkout. A non-editable install (pip install .) breaks that lookup.

--no-deps: environment.yml already resolves every dependency you need — some (numpy, scipy, mne-base, PySide6, …) as conda packages from conda-forge, the rest (pyglet, pylsl, brainflow, …) through its own nested pip: section, which conda still solves and installs as part of creating the environment — resolved together as one consistent set. (It does not pin most versions — only python=3.11 and setuptools<81, the latter because brainflow still imports pkg_resources, which setuptools removed in 81. So the guarantee is internal consistency at solve time, not reproducibility across dates.) Running a plain pip install -e . afterward, without --no-deps, lets pip re-resolve those same packages from PyPI on top of what conda already installed. The two can build the same library differently (a different BLAS backend behind numpy is the one that bites hardest), and a mixed install can import cleanly and then fail the moment it does real work — see Troubleshooting for what that failure looks like when it happens at launch. --no-deps keeps every dependency the one environment.yml already resolved, whichever channel it came from.

If you ever reinstall without --no-deps by mistake, undo it the same way you'd fix any mixed environment: conda env remove -n ssvep and recreate it from environment.yml, then reinstall with the flag. There is no reliable partial fix once pip has overwritten a conda-built package.

The environment's git and the "Select a credential helper" window (Windows)¶

The git that environment.yml installs is conda's own build, not Git for Windows, and out of the box it is configured to ask which credential helper to use: the first time it needs to sign in to a remote (a git pull of a private repository from an activated ssvep shell, or the toolbox's own lab setup cloning toolbox/), it opens a small "Select a credential helper" window. It may open on a different monitor or behind other windows, and git waits until it is answered, so a pull just hangs, and lab setup from the GUI can freeze the whole window while it waits (#299). It can also ask twice in a row: once to read a credential, once to save it.

Choose manager (Git Credential Manager, the same helper Git for Windows uses, so it finds a GitHub sign-in you already have) and tick the box that makes it permanent. The choice is written into the environment's own git configuration, so it is asked once per environment, and again after the environment is recreated or its git package is updated (either rewrites that configuration).

Launching¶

Installing gives you three entry points. All three open the same window, on the same starting tab (Build run) — there's one unified app, not separate design/run programs:

ssvep-toolbox    # the desktop launcher: a splash screen, then the window (no console output on Windows)
ssvep-design     # identical to ssvep-toolbox, run from a terminal instead of a shortcut
ssvep-run        # the same window again, plus optional CLI flags (--serial-port, --board)

Run any of them from an activated ssvep shell. For what to do once it opens, see Getting started.

Desktop shortcut (Windows)¶

python scripts/create_desktop_shortcut.py

This writes an SSVEP Toolbox.lnk to the Desktop, pointing at the installed launcher, with the app's own icon (the icon ships committed in the repository; there is no need to regenerate it unless you are changing the icon design itself, via scripts/make_icon.py). Right-click it afterward to Pin to taskbar / Pin to Start if you want it there permanently.

The shortcut runs a console-less process — it cannot print anything, so if it ever fails silently, see Troubleshooting rather than guessing.

What a fresh clone does and doesn't know about you¶

A clone with no further setup runs generically: no institution stamped into recordings, no push destination, no pre-filled operator, mains frequency recorded as unknown rather than assumed. That is deliberate — nothing about installing or running the toolbox requires you to be part of any particular lab — and it is what Getting started is written against.

The first time you launch, the app notices there's no site profile (config/site.local.json) and asks, once, whether to set one up — "Use generic…" is the right answer for this walkthrough and for any machine that isn't a lab deployment; it writes a generic profile so you aren't asked again. If you are setting up a lab deployment (an institution, an ethics approval, a server to push to, an approved operator list), that prompt's "Set up a profile…" is where it starts — see Site profile for what each field does.

If something goes wrong¶

Troubleshooting covers the startup and acquisition failures that have actually happened, what caused each one, and what the toolbox now does about it.