YAMS logo

YAMS

Yet Another MotionSenSE Service utility — run collections on the wristband, pull data off it, and turn raw sensor binaries into CSV.

YAMS 2.0 · PLASMA 2.2.4Windows & macOSPython 3.12+MIT licensed

What it does

One app for the whole capture workflow

YAMS opens in your browser as a set of tabs. Each one covers a stage of working with the MotionSenSE wristband, from starting a collection to getting analysis-ready CSVs.

⌚️ MotionSenSE controller

Run a collection

Scan for wristbands, select one or more to connect, then start and stop recording while watching collection state live.

📂 File downloader

Pull data off the device

Browse onboard sessions and download them, optionally extracting to CSV in the same step.

🛠️ Data extractor

Binaries to CSV

Point it at a folder of .bin files and get one CSV per sensor per subject.

🛠️ Data extractor pro

Zip in, zip out

Drop in a zip of device folders and get an extracted archive back, without unpacking by hand.

📊 Data viewer

Check it before you trust it

Plot extracted signals to confirm a capture looks right before it reaches your analysis.

⏱️ Clock Sync

Align the clocks

Reconcile device time against reference timestamps so streams line up across devices.

📋 UUID extractor

Read device identity

Pull serial numbers, firmware versions and identifiers out of connected wristbands.

📒 Extensions

Devices & sessions

Manage the device registry and the subject/session encoding table used to name outputs.

Install

Three ways to get it

If you just want to use YAMS, take the first one — it needs no Python at all.

Prebuilt app

No Python installation needed. On Windows, use the installer or portable zip.

YAMS_Windows_x64_Setup.exe for Windows, YAMS_MacOS_arm64 for Apple silicon Macs. Intel Macs are not covered by the prebuilt build — use pip or source instead.

Download the latest release →

From PyPI

If you already work in Python.

pip install -U yams-util
python -m yams

From source

For development, or to run unreleased changes.

git clone https://github.com/SenSE-Lab-OSU/YAMS.git
cd YAMS
git checkout v2
pip install -e .
conda install -c conda-forge liblsl
python -m yams
Don't skip liblsl. The Lab Streaming Layer library is a native dependency that pip cannot supply. Installing it from conda-forge is the step most source installs miss, and without it the app fails at startup.

However you install it, YAMS starts a local server and opens your browser at http://127.0.0.1:7860. Nothing leaves your machine.

Usage

From wristband to CSV

The normal arc of a study session, in four steps.

  1. Collect

    In ⌚️ MotionSenSE controller, scan, select the wristbands to connect, and start the collection. Data is written to onboard flash, so the devices do not need to stay in range once recording has begun.

  2. Download

    In 📂 File downloader, pick the sessions you want and pull them off the device. Tick Extract data after download to get CSVs in the same pass. See Extract onboard data for the full walkthrough.

  3. Extract

    Or extract separately in 🛠️ Data extractor: give it an input folder of .bin files and an output folder. Record formats are detected automatically, so there is normally nothing to configure.

  4. Verify

    Open the result in 📊 Data viewer, and read README.txt in the output folder — it records how every single file was decoded.

Data extraction

Formats are detected, not assumed

The wristband has written six different on-disk record layouts over its life, and the firmware version recorded on the device is not always right about which one you have. YAMS reads the layout out of the file itself.

New in 1.6. PPG, IMU and ECG layouts are each detected from file contents, per file. Captures whose uuid.txt is stale or missing entirely now extract correctly with no flags at all — previously they produced silently wrong numbers.

Run it from the command line:

python -m yams.data_extraction -i path/to/binaries -o path/to/output

Or inspect what would happen first, without writing anything:

python -m yams.data_extraction -i path/to/binaries --dry_run

The options you are most likely to need:

FlagDefaultWhat it does
--dry_runoffReport the layout resolved for every binary and exit
--validate_with_uuidoffCross-check detection against uuid.txt and report disagreements
--ppg_formatautoForce a PPG layout, or version for the pre-1.6 behaviour
--save_formatcsvcsv or pickle
--modedirdir for a folder of binaries, batch for a folder of zips

Every flag, all six record layouts, how detection works and how it is measured: Data Extraction reference →