Skip to content

README.md

Latest commit

 

History

History
139 lines (93 loc) · 3.82 KB

README.md

File metadata and controls

139 lines (93 loc) · 3.82 KB
Raw

mendi-ble-python

Python library for interfacing with Mendi fNIRS devices via Bluetooth Low Energy (BLE).

Overview

This library enables real-time streaming of brain oxygenation data (HbO/HbR) from Mendi's single-channel prefrontal cortex sensor. It was developed through systematic reverse engineering of the BLE protocol, discovering the device's unique request-response streaming mechanism.

Features

  • Device Discovery: Automatic detection of Mendi devices
  • Real-time Streaming: ~20Hz data acquisition using the discovered protocol
  • Browser Visualization: Interactive real-time graphs with Plotly
  • Robust Reconnection: Handles disconnections and phantom connections
  • Scoring Engine: Configurable activity scoring with multiple presets

Installation

# From PyPI (when published)
pip install mendi-ble

# From GitHub
pip install git+https://github.com/BioMycoBit/mendi-ble-python.git

# For development
git clone https://github.com/BioMycoBit/mendi-ble-python.git
cd mendi-ble-python
pip install -e ".[dev]"

Quick Start

Basic Streaming

import asyncio
from mendi_ble import MendiStream

async def main():
    async with MendiStream() as stream:
        async for sample in stream:
            print(f"HbO: {sample.hbo:.2f}, HbR: {sample.hbr:.2f}")

asyncio.run(main())

Visualization Example

# With real device
python examples/visualization_example.py

# With simulated data
python examples/visualization_example.py --simulate

Opens browser visualization at http://localhost:8050

How It Works

Through reverse engineering, we discovered that Mendi uses a unique BLE streaming pattern:

  1. Not Standard Streaming: Unlike typical BLE devices, Mendi doesn't continuously stream data
  2. Request-Response: Each data packet must be requested via descriptor write
  3. Optimal Timing: 2-second intervals between requests provides stable data flow

See docs/REVERSE_ENGINEERING_OVERVIEW.md for the full discovery journey.

Protocol Details

Service and Characteristics

SERVICE_UUID = "fc3eabb0-c6c4-49e6-922a-6e551c455af5"
CHAR_DATA = "fc3eabb5-c6c4-49e6-922a-6e551c455af5"  # Data stream

Data Packet Format

Position: 0  1  2  3  4  5  6  7  8
Value:    0a 03 08 XX 1d 10 01 18 01
                   ^^
                   Sensor value (varies with brain activity)

API Reference

Core Classes

  • MendiStream - High-level streaming interface
  • MendiClient - Low-level BLE client
  • MendiScanner - Device discovery
  • MendiPlotlyVisualizer - Real-time visualization

Data Models

  • MendiSample - Individual measurement (HbO, HbR, timestamp, quality)
  • Session - Complete session with baseline and metrics

Platform Support

  • Windows: Full functionality
  • macOS: Requires Bluetooth permissions
  • Linux: May need capabilities (sudo setcap)
  • WSL: No Bluetooth access (development only)

Contributing

Contributions welcome! Areas of interest:

  • Protocol documentation improvements
  • Additional device support
  • Performance optimizations
  • Cross-platform testing

Documentation

License

MIT License - See LICENSE file

Disclaimer

This is an unofficial library developed through reverse engineering. Not affiliated with or endorsed by Mendi.io. Use at your own risk.

Author

Brandon Taylor

Acknowledgments