movesense-py

Python toolkit for Movesense BLE sensor devices — data collection, real-time streaming, visualization, and physics-based signal analysis.

What You Need

• Hardware: A Movesense sensor (HR+, Medical, or Active)
• Computer: macOS, Linux, or Windows with Bluetooth Low Energy support
• Python: 3.11 or newer
• Package manager: uv (recommended) or pip

Installation

git clone https://github.com/sensein/movesense-py.git
cd movesense-py

# Install with uv (recommended)
uv venv && uv pip install -e .

# Or with pip
pip install -e .

# Optional: ML models (PyTorch, scikit-learn)
uv pip install -e ".[ml]"

Find your device serial number (printed on the sensor, or visible in the Movesense Showcase app) and save it:

echo "MSN=YOUR_SERIAL_HERE" > .env

Quick Start

1. Check device connection

movesense status

This shows battery level, firmware version, and whether the device is logging.

2. Record data

# Configure which sensors to log
movesense config /Meas/Ecg/200/mV /Meas/IMU9/52 /Meas/Temp /Meas/HR

# Start recording to device flash
movesense start

# ... wear the sensor ...

# Stop and download
movesense stop
movesense fetch

Data is saved to ~/dbp/data/movesense/{serial}/{date}/ as Zarr v3 + CSV.

3. View and control in browser

movesense serve

Opens a web viewer at http://127.0.0.1:8585 with:

• Stored data: Browse historical recordings with ECharts — stacked channels, synchronized zoom/pan, adaptive time axis
• Settings panel (⚙): Connect to device, configure logging channels, start/stop recording, download logs, erase memory
• Live streaming (▶/⏸/⏹): Real-time BLE data in a sliding window with configurable stream channels
• Device control: All operations via WebSocket — busy overlays during long operations, confirmation dialogs for destructive actions

4. Stream live data

# Stream ECG to terminal for 30 seconds
movesense live /Meas/Ecg/200/mV -d 30

Or use the browser viewer: click ⚙ → Connect → select stream channels → click ▶ for real-time multi-channel visualization.

CLI Reference

Command	Description
movesense status	Device info, battery, datalogger state
movesense config <paths...>	Configure measurement channels
movesense start	Start logging to device flash
movesense stop	Stop logging
movesense fetch	Download data → SBEM → JSON → Zarr v3 + CSV
movesense live <paths...> [-d sec]	Real-time BLE data streaming
movesense erase	Erase device memory (with confirmation)
movesense serve [--port N] [--data-dir PATH]	Start data server

All commands accept -s <serial> or read MSN from .env. Use -V for verbose logging.

Available Sensors

Path	Rates (Hz)	Description
/Meas/Ecg/{rate}/mV	125, 200, 250, 500, 512	ECG in millivolts
/Meas/Acc/{rate}	13, 26, 52, 104, 208, 416, 833	Accelerometer (x, y, z)
/Meas/Gyro/{rate}	13, 26, 52, 104, 208, 416, 833	Gyroscope (x, y, z)
/Meas/Magn/{rate}	13, 26, 52, 104, 208	Magnetometer (x, y, z)
/Meas/IMU6/{rate}	same as Acc	Accelerometer + Gyroscope
/Meas/IMU9/{rate}	same as Acc	Acc + Gyro + Magnetometer
/Meas/Temp	~1	Temperature (Kelvin)
/Meas/HR	event-driven	Heart rate (bpm) + RR intervals

Data Server

# Default: port 8585, reads from ~/dbp/data/movesense/
movesense serve

# Custom port and data directory
movesense serve --port 9000 --data-dir /path/to/data

# LAN access
movesense serve --host 0.0.0.0

The server prints a URL with an auth token on startup. API docs at /docs (auto-generated by FastAPI).

Viewer Architecture

The viewer uses a server-driven WebSocket protocol. The UI (viewer.js, ~400 lines) is a thin renderer — all data resolution, device control, and state management happen server-side.

Stored mode: Server queries DeviceStore Zarr via timeline API, pushes data at the right resolution for the current zoom level. Pre-fetches adjacent windows for instant panning.

Live mode: Server connects to BLE device via StreamManager, forwards parsed packets as data messages. Live data is also written to a stream/ group in DeviceStore for later review.

Device control: Connect, config, record, fetch, erase — all via WebSocket messages with busy overlays and confirmation dialogs.

Physio Library

Reusable signal processing algorithms at src/movesense/physio/. Designed to be portable to senselab.

Classical Algorithms

Module	Capabilities
dsp.py	Bandpass/lowpass/highpass filters, envelope, peak detection, zero-crossing, RMS, PSD
ecg.py	R-peak detection (Pan-Tompkins, Elgendi, Hamilton, ensemble), bSQI, HRV (SDNN, RMSSD, pNN50)
motion.py	Activity/rest classification, posture change, motion artifact detection
quality.py	ECG signal quality index
orientation.py	Madgwick filter (ACC+GYRO → quaternion), posture estimation
segmentation.py	PELT change-point detection, multi-stream segmentation, Matrix Profile motifs
pipeline.py	Multi-stream analysis orchestrator
events.py	Event model with JSON persistence and CSV export

Learned Models (PyTorch, MPS/CUDA/CPU)

Module	Models
learned/ssm.py	S4 layer, BioSSM (bidirectional state-space model)
learned/causal.py	Granger causality, cross-channel discovery, transfer entropy
learned/multimodal.py	Multi-scale ChannelEncoder, CrossModalAttention, MultiModalFusion
learned/pinn.py	PirateNet (adaptive residual PINN), PhysicsGRU (constrained dynamics), ResidualAttention
learned/symbolic.py	KAN layer (B-spline edges), PhysicsKAN (equation discovery)

See docs/sota-physio-ml.md for research references and cross-domain applications.

Testing

uv run python -m pytest tests/ -v

200+ tests covering CLI, Zarr conversion, server API, scanner, WebSocket viewer protocol, device control, Playwright UI, ECG processing, motion analysis, events, segmentation, protocol validation, and all learned models.

Documentation

• Movesense API Reference — Device REST API, measurement paths, protocol details
• SOTA Physics-Based ML — Research references, model architectures, cross-domain applications

License

Original Movesense Python datalogger tool by Movesense/Suunto. Extended with server, physio library, and ML models. See upstream: https://bitbucket.org/movesense/python-datalogger-tool