Skip to content
SenSE-Lab-OSUPublic

About

Yet Another Motionsense Service utility

Resources

Stars

3 stars

Watchers

2 watching

Forks

Repository files navigation

title YAMS
emoji 🍠
colorFrom purple
colorTo purple
sdk gradio
sdk_version 5.15.0
app_file yams/__main__.py
pinned false
license mit

YAMS

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 msense plugin; YAMS just picks the tab layout and the branding. Multi-sensor users want PLASMA directly.

Quickstart

Pre-compiled version

The Windows installer is unsigned, so Windows SmartScreen may ask for confirmation. For the portable zip, extract the whole folder before running the executable.

Development

  1. (optional) create a dedicated conda environment
    • conda create -n yams python=3.12 && conda activate yams
  2. Config liblsl
    • conda install -c conda-forge liblsl
  3. Install YAMS from source; its dependency fetches PLASMA v2.2.4
    • git clone https://github.com/SenSE-Lab-OSU/YAMS.git
    • cd YAMS && git checkout v2 && pip install -e .
  4. Launch YAMS
    • python -m yams (or the yams console 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.

(Deprecated) Windows

Python 3.12 or newer is needed

  1. Download setup scripts
  2. Run the installation script
    • Run the script by double-click the install.bat file
    • The script will perform any necessary setup
  3. Start the app
    • by double-click the start_yams.bat file
    • Once the initialization is completed, you will see a messge similar to: * Running on local URL: http://127.0.0.1:7860
  4. Access the application

(Deprecated) MacOS / Linux

  1. Download scripts/unix to a desired location
  2. Run run.sh to install and start the app

General usage

Connect and record

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.

Download onboard data

Refer to Extract onboard data

Extract raw data

Refer to Data Extraction Feature

Build guide

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

Updating version numbers

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.

Instructions

(advanced) running data extraction in command line

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 archives

Common 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_format to 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.

Roadmap

  • 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

Acknowledgement

About

Yet Another Motionsense Service utility

Resources

Stars

3 stars

Watchers

2 watching

Forks

Releases

Packages

Used by

Contributors

Languages