MNE Scan Deployment

Guidance for taking MNE Scan from a developer workstation to a real measurement environment. Covers the differences between a lab install and a clinical / regulated install, the on-disk layout that the application expects, calibration files, FIFF output retention, and the runtime errors most commonly seen in production.

Lab vs. Clinical Install

MNE-CPP is research software (LGPL-3.0). It is not a medical device and must not be relied on for clinical diagnosis. Anything described under "Clinical" below is about good-citizen practices when you co-locate MNE Scan next to a regulated acquisition system, not a claim of medical-device compliance.

Concern	Lab install	Clinical / shared-lab install
Install location	Per-user ($HOME/mne-cpp)	System-wide read-only prefix (/opt/mne-cpp or C:\Program Files\mne-cpp)
Updates	Pulled by individual users	Promoted from a staging install; recorded with a known git SHA / release tag
User accounts	Single shared login	One OS account per operator, with the install prefix mounted read-only
Vendor drivers	Installed ad-hoc	Pinned to a known driver version, documented in the lab runbook
Output retention	At operator's discretion	Written to a fixed, monitored directory (see below)
Network	Open	Acquisition VLAN only; no inbound public access to mne_rt_server or LSL ports
Logs	stdout / console	Captured to a rotating file (mne_scan.log) and archived with the FIFF output

On-Disk Layout

After installation (binary or source-built with cmake --install), the prefix has the following structure:

<prefix>/
├── bin/                   # Application executables (mne_scan, mne_analyze,
│                          #   mne_rt_server, mne_show_fiff, …)
├── lib/                   # Shared MNE-CPP libraries (mne_fiff, mne_fs, …)
├── plugins/               # Sensor / Algorithm / IO plugins loaded by mne_scan
│   ├── mne_scan/          #   one shared library per plugin from
│   │                      #   src/applications/mne_scan/plugins/
│   └── mne_analyze/
├── resources/             # Coil definitions, default config files, sample data
│   ├── general/           #   coil_def.dat, FreeSurfer fsaverage assets
│   ├── mne_scan_plugins/  #   per-plugin defaults (e.g. hpi coil presets)
│   └── data/MNE-sample-data/  # optional; the sample dataset
└── doc/                   # Offline copy of this manual (if shipped)

Notes:

• mne_scan discovers plugins by scanning plugins/mne_scan/ at startup. Removing a shared library from this directory disables that plugin without rebuilding.
• The vendor SDK libraries (TMSiSDK.dll, eego-SDK.dll, gUSBamp_x64.lib runtime, …) must be locatable by the dynamic linker. On Windows the simplest layout is to place them next to mne_scan.exe in bin/. On Linux / macOS prefer the system loader path (/usr/local/lib, /Library/Frameworks) over LD_LIBRARY_PATH overrides.
• Do not mix plugins from different builds in plugins/mne_scan/. The plugin ABI is not stabilised; mismatched binaries will silently load and then crash on the first signal exchange.

Required Calibration Files

The exact set depends on the pipeline:

File	Required when	Default location	Notes
coil_def.dat	Any MEG forward / source-localisation step	resources/general/coil_def.dat	Shipped with MNE-CPP; do not edit. Custom coils must be appended in a separate file.
HPI coil-frequency preset (hpi.json)	Continuous HPI with the hpi plugin	src/applications/mne_scan/plugins/hpi/hpi.json (built into the plugin)	Edit and rebuild only if your site uses non-standard coil frequencies.
Forward solution (*-fwd.fif)	rtcmne source localisation	Per-subject, generated offline via mne_forward_solution or rtfwd	Path is configured per session in the rtcmne Preferences tab.
Noise covariance (*-cov.fif)	rtcmne source localisation	Per-subject, generated by mne_compute_raw_inverse or by the live covariance plugin	A degenerate covariance prevents rtcmne from initialising.
Inverse operator (*-inv.fif)	Offline reuse of an online session	Written by the offline pipeline	Not required at acquisition time.
Vendor calibration (*.elc electrode layout, EEGoSports license file)	EEGoSports impedance widget	C:\Users\<User>\Documents\Eego\ for legacy licenses; loaded interactively for ELC layouts	See EEGoSports.

Keep a per-site copy of every calibration file under version control alongside the lab runbook. When a recording is reviewed later, the calibration set in effect at the time of recording is the only authoritative reference.

FIFF Output Retention

The writetofile plugin produces one FIFF file per pipeline Run. Recommended handling:

• Naming. Configure the file pattern to embed subject ID, session ID, and a UTC timestamp; avoid local time to prevent ambiguous filenames around DST transitions.
• Atomicity. A FIFF file is only valid after the operator presses Stop (the closing tags are flushed at that point). Treat any file produced by a non-graceful shutdown as truncated and re-record if possible.
• Integrity check. Run mne_show_fiff <file> immediately after Stop. The output must end with FIFF_BLOCK_END for the top-level FIFFB_MEAS. Truncated files will report a parser error and should be quarantined.
• Retention. Keep raw FIFFs at the source-of-truth resolution for the lifetime defined by your site's data-management policy (typical research lab: indefinite; clinical-adjacent: at least the regulatory minimum for the study). Derived files (averages, source estimates) can be regenerated and should never be the only stored copy.
• Backup. At least one off-host copy. FIFF files are append-only during a recording but become read-only afterwards, so a daily rsync of the output directory is sufficient.
• Provenance. Archive the MNE-CPP version (mne_scan --version), the plugin set in plugins/mne_scan/, and the calibration file set used. Without these, a recording is not reproducible.

Troubleshooting Common Runtime Errors

Symptom in the Log dock	Likely cause	Fix
Failed to load plugin <name>: cannot open shared object file	Vendor SDK library not on the loader path	Copy the SDK *.dll / *.so next to mne_scan (Windows) or into a directory included in the system loader path (Linux / macOS). Do not rely on LD_LIBRARY_PATH for production.
<sensor> init failed: device not found	Amplifier off, not enumerated, or claimed by another process	Power-cycle the amplifier, close any vendor utility that may hold the device, restart mne_scan.
FiffSimulator: connection refused	mne_rt_server not running or wrong host/port	Start mne_rt_server first; verify host 127.0.0.1 and port 4217 (default) in the Connection tab.
FtBuffer: header read timed out	Producer (e.g. neuromag2ft) not yet pushing data	Start the producer before the FieldTrip-side consumer; confirm the buffer port (default 1972) is reachable.
LSL: no streams discovered	UDP multicast blocked between hosts	Put MNE Scan and the LSL outlet on the same VLAN, or unblock multicast on the network.
HPI: insufficient coil amplitude	HPI coils disabled in the recording, or coil-frequency preset wrong for the system	Confirm coil energising on the acquisition console; verify hpi.json matches the site's coil frequencies.
rtcmne: covariance matrix is singular	Empty-room recording too short, or noise covariance not yet stabilised	Wait until the live covariance plugin reports a positive-definite estimate, or supply a pre-computed *-cov.fif.
writetofile: cannot open output for writing	Output directory missing or read-only	Pre-create the directory, ensure the OS user running mne_scan has write permission.
MNE Scan exits silently a few seconds after pressing Run	Plugin ABI mismatch — plugins/mne_scan/ mixed with binaries from a different build	Reinstall: replace the entire plugins/mne_scan/ directory from a single build artefact set.

See Also

• Hardware Support Matrix
• Quickstart
• MNE Scan overview