| title | YAMS |
|---|---|
| emoji | 🍠 |
| colorFrom | purple |
| colorTo | purple |
| sdk | gradio |
| sdk_version | 5.15.0 |
| app_file | yams/__main__.py |
| pinned | false |
| license | mit |
Yet Another Motionsense Service utility
YAMS 2.0 is a thin, MSense-only front-end for PLASMA v2.2.4. All acquisition, BLE and analysis code lives in PLASMA's
msenseplugin; YAMS just picks the tab layout and the branding. Multi-sensor users want PLASMA directly.
- Windows x64: download the installer. A portable zip is also available.
- macOS Apple Silicon: download the executable from Releases.
The Windows installer is unsigned, so Windows SmartScreen may ask for confirmation. For the portable zip, extract the whole folder before running the executable.
- (optional) create a dedicated conda environment
conda create -n yams python=3.12 && conda activate yams
- Config
liblslconda install -c conda-forge liblsl
- Install YAMS from source; its dependency fetches PLASMA v2.2.4
git clone https://github.com/SenSE-Lab-OSU/YAMS.gitcd YAMS && git checkout v2 && pip install -e .
- Launch YAMS
python -m yams(or theyamsconsole script)
To develop PLASMA alongside YAMS, clone PLASMA next to YAMS, check out
v2.2.4, install it with pip install -e ../PLASMA, then install YAMS with
pip install -e . --no-deps so the local PLASMA checkout remains active.
When run from source, state (device config, gyro-bias, yams-data/ recordings,
session log) lives in the working directory. Packaged apps use PLASMA's per-user
app-data directory. Set PLASMA_HOME to choose a different location.
Python 3.12 or newer is needed
- Download setup scripts
- Download the scripts/windows folder and save it in your desired folder
- Run the installation script
- Run the script by double-click the
install.batfile - The script will perform any necessary setup
- Run the script by double-click the
- Start the app
- by double-click the
start_yams.batfile - Once the initialization is completed, you will see a messge similar to:
* Running on local URL: http://127.0.0.1:7860
- by double-click the
- Access the application
- Open a web browser and navigate to http://127.0.0.1:7860 or the URL displayed in the prompt.
- Download scripts/unix to a desired location
- Run
run.shto install and start the app
In MotionSenSE controller, press Search Bluetooth devices, select one or
more discovered wristbands, then press Connect selected. Start and
Stop control the connected set. To change that set, select wristbands and
press Connect selected again. The Danger zone erases flash on the
connected set after you enter code 68 and enable the erase control.
YAMS remembers the selection in its MSense configuration automatically; you do not need to edit a device table before connecting.
Refer to Extract onboard data
Refer to Data Extraction Feature
plasma-app ships a PyInstaller hook (auto-discovered once it is pip installed),
so the specs carry no hand-maintained hidden-import list.
pip install -e ".[build]"- macOS:
pyinstaller app_macos.spec --noconfirm→dist/YAMS_MacOS_arm64 - Windows:
pyinstaller app_windows.spec --noconfirm→dist/YAMS_Windows_x64/ - Windows installer:
ISCC.exe /DMyAppVersion=2.0.0 packaging\windows\yams_installer.iss→dist/YAMS_Windows_x64_Setup.exe
When adopting a new PLASMA release, change its tag in both pyproject.toml
(the YAMS package dependency) and requirements.txt (source/HF installs).
Update the PLASMA version shown in this README and docs/index.html, then
install the new dependency and run the tests and app startup check.
When releasing a new YAMS version, change yams/__init__.py and the
expected version in tests/test_smoke.py. Update the YAMS version shown in
this README and docs/index.html, plus the manual ISCC.exe example above.
CI reads yams.__version__ automatically for the Windows installer. Run the
build workflow manually and check its smoke tests before creating a release
tag.
The extraction toolkit now lives in PLASMA. python -m yams.data_extraction is a
thin shim for python -m plasma.devices.msense.extract:
python -m yams.data_extraction -i "data_in" -o "data_out" # single folder of .bin
python -m plasma.devices.msense.extract batch -i "zips" -o "out" # folder of .zip archivesCommon options (pass to the dir form above):
| Flag | Default | Description |
|---|---|---|
-i, --in_dir |
(required) | Directory containing .bin files |
-o, --out_dir |
./ |
Output directory |
--save_format |
csv |
Output format: csv or pickle |
--ignore_id |
off | Skip subject/session ID parsing; use raw filenames |
--legacy_fs |
off | Use 25 Hz clock for CDCT (uncommon, old devices) |
--force_new_format |
off | Force v4.7.0+ binary layout regardless of uuid.txt version |
Data type detection — the extractor scans the input folder and processes whichever file types are present:
| File pattern | Sensor | Output |
|---|---|---|
[id]ac*.bin |
IMU (AccX/Y/Z, QuatX/Y/Z, ENMO) | [id]ac.csv |
[id]ppg*.bin |
PPG (ir1, ir2, g1, g2) | [id]ppg.csv |
[id]ecg*.bin |
MAX30001 ECG (ECG, ETAG, PTAG) | [id]ecg.csv |
A single run extracts all types present. Missing types are silently skipped.
Examples:
# Wristband (AC + PPG) — firmware auto-detected from uuid.txt
python -m yams.data_extraction -i "data/subject01" -o "out/subject01"
# Wristband on v4.7.0+ firmware (force if uuid.txt is absent or reports wrong version)
python -m yams.data_extraction -i "data/subject01" -o "out/subject01" --force_new_format
# ECG only folder (e.g. data/260708_ecg containing ecg*.bin)
python -m yams.data_extraction -i "data/260708_ecg" -o "out/ecg" --ignore_id
# Mixed folder with both wristband and ECG files
python -m yams.data_extraction -i "data/session01" -o "out/session01" --force_new_format --ignore_id
# Save as pickle, skip ID parsing
python -m yams.data_extraction -i "data/subject01" -o "out/subject01" --save_format pickle --ignore_id
# Batch extract a folder of zip archives
python -m plasma.devices.msense.extract batch -i "data_in" -o "out"Notes:
- The device version is read automatically from
uuid.txt. If v4.7.0+, the new binary layout (uint32 PPG, quaternion IMU, 32-bit counter at 512 Hz) is used for AC/PPG; otherwise the legacy layout is used. Use--force_new_formatto override. - ECG binary format (
ecg*.bin) is always parsed the same way regardless of firmware version — it uses 12-byte CRC-validated frames with a 512 Hz sequence counter. - ECG output columns:
ECG(signed 18-bit ADC count),ETAG(0 = valid sample, 2 = leads off),PTAG,Counter,CDCT,Datetime.
- Device data transfer
- Device data post processing
- format conversion
- visualization
- simple data collection utilities
- LSL support
- Auto reconnect
- Selected file download
- Advanced device monitoring [ ] global state: active connection, active outlet, ctl status [ ] BAT monitoring [ ] storage monitoring
- Conceptualization: MPADA
- BT control adapted from MotionSenseHRV-BioImpedance-Interface .
- icon designed by Mihimihi