PLASMA: Platform for LSL-based Acquisition of Sensor Metrics and Analytics
📖 Operator handbook: https://yuyichang.github.io/PLASMA/ — install, configure, pair MSense wristbands, run a session, read the memo panel, recover from faults.
| Platform | Architecture | Download |
|---|---|---|
| macOS | Apple Silicon (arm64) | Download .dmg |
| Windows | x64 | Download Installer .exe |
| Linux | x64 | Download .tar.gz |
| Linux | ARM64 | Download .tar.gz |
For other packages and previous versions, see GitHub Releases.
macOS: brew install --cask yuyichang/plasma/plasma is the recommended
way to get PLASMA — no Python, no liblsl, no Gatekeeper dance. Windows:
scoop bucket add plasma https://github.com/YuyiChang/scoop-plasma then
scoop install plasma does the same, without the SmartScreen warning. See
Install & first launch
for that and every other install path (prebuilt binaries, PyPI, from source).
To run from source instead:
conda create -n plasma python=3.12conda activate plasmapip install -e ".[all]"— or a lean subset, e.g.".[msense]"/".[qb2,pupil]"python -m plasma(or theplasmaconsole script)
pip install -r requirements.txt still works — it's a shim for -e .[all,build,test].
Want a double-clickable icon instead of running plasma from a terminal?
pip install -e ".[desktop]" then plasma-install-shortcut — see
Install & first launch.
Writable state (device config, gyro-bias calibration, data/ recordings, session
log) location, in order: $PLASMA_HOME if set → a per-user app-data dir when
running as a packaged app (~/Library/Application Support/PLASMA on macOS,
%LOCALAPPDATA%\PLASMA on Windows, ~/.local/share/plasma on Linux) → the
working directory when running from source. Resolved once at import — set
PLASMA_HOME before launching to override.
pip install "plasma-app[msense] @ git+https://github.com/YuyiChang/PLASMA@v2.0.0"
The distribution is plasma-app; the import package is plasma. Extras map to
plugins: msense, qb2, pupil, shimmer, obs (and all).
- Multiple QB2 LiDARs configurable with individual addresses, optional keys, and enable switches; point clouds share the session recording folder — QB2 recording & review
- the built-in LSL→XDF recorder captures every stream on the default
liblsl session, so a concurrent
pytestrun or another lab tool leaks into the recording; re-Initialize doesn't fully tear down old outlets. Direction (SessionID scoping, outlet lifecycle):docs/reference/lsl-lifecycle-and-scoping.md - interactive=false on ses/sub when collection started
- linux aarch64 build —
PLASMA_Linux_arm64for Jetson Orin (JetPack 6); CI jobbuild-linux-arm64 - infrequent stream (e.g., PLASMA journaler) shows green after recording stop
- doc for msense workflow with better screenshots
- memo
stagetransition logic optimization (e.g., timing of "ready to start" msg wrt sensor init status)
Every sensor is a plugin: a PlasmaDevice subclass plus a registration entry in
plasma/plugins.py. Core code never imports a concrete device.
full guide:
plasma/devices/README.mdbase class:PlasmaDeviceinplasma/devices/template.pyreference package (config section + tabs + multi-unit):plasma/devices/msense/
The playbook is a MkDocs Material site under docs/, deployed to GitHub Pages
by .github/workflows/docs.yml on every push to main.
pip install -e ".[docs]" # mkdocs-material + mkdocs-glightbox + playwright
mkdocs serve # preview at http://127.0.0.1:8000
Screenshots (docs/assets/screenshots/*.png, Git LFS) are regenerated by a
Playwright script that drives PLASMA with the simulated MSense device:
brew install git-lfs && git lfs install # one-time
python scripts/capture_screenshots.py # ~4 min; needs Google Chrome
It uses PLASMA_HOME=~/Library/Application Support/PLASMA by default so the
paths shown in the memo panel match a packaged install; pass --home /tmp/x for
a disposable run.