# COLMI Smart Ring Toolkit & Cross-Platform MCP Server

[![Python Version](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20macOS%20%7C%20Windows-brightgreen.svg)]()
[![Protocol: MCP](https://img.shields.io/badge/Protocol-Model%20Context%20Protocol%20(MCP)-purple.svg)](https://modelcontextprotocol.io/)
[![Tests Passing](https://img.shields.io/badge/tests-20%20passed-success.svg)]()
[![Privacy](https://img.shields.io/badge/Privacy-100%25%20Local%20%26%20Cloudless-orange.svg)]()

> **The definitive open-source toolkit, reverse-engineered Bluetooth Low Energy (BLE) protocol specification, and Model Context Protocol (MCP) server for COLMI R02, COLMI R03, and compatible smart rings.** Connect physical health rings directly to AI agents (Claude Desktop, Cursor, Antigravity, VS Code) without vendor clouds, accounts, or subscriptions.

---

## 🔍 Search Keywords & Supported Hardware

**Supported Devices**:
- **COLMI R02 & COLMI R03** Smart Rings
- **COLMI R01, R04, R05, R06, R07, R08, R10** family
- **QRing OEM Variants**: KSIX Ring, boAt Ring, Blaupunkt, VK-5098, MERLIN, Hello Ring, RING1, TR-R02, OneRing, BOK.
- **SoC Families**: BlueX Micro RF03 / RF03-01 (ARM Cortex-M0) & Realtek RTL8762E / RTL8762ESF (ARM Cortex-M4F, RT02R revision).

**Comparative Ecosystem**:
- **Oura Ring (Gen 2, Gen 3, Ring 4)**
- **Ultrahuman Ring AIR**
- **RingConn (Gen 1 & Gen 2)**
- **Samsung Galaxy Ring**

**Tags & Topic Index**:
`colmi`, `colmi-r02`, `colmi-r03`, `smart-ring`, `oura-alternative`, `mcp-server`, `model-context-protocol`, `claude-desktop`, `cursor-ai`, `antigravity`, `bluetooth-le`, `ble`, `qring`, `reverse-engineering`, `local-first`, `biometrics`, `heart-rate-variability`, `hrv`, `sleep-staging`, `hypnogram`, `accelerometer`, `firmware`.

---

## 🌐 Is it Cross-Platform?

**YES, 100% Cross-Platform!**

The toolkit and MCP server run natively on **Linux**, **macOS**, and **Windows 10/11**:

```
                       Cross-Platform Architecture
                       
                   ┌───────────────────────────────────┐
                   │    colmi-smart-ring MCP Server    │
                   └─────────────────┬─────────────────┘
                                     │
                                     ▼
                   ┌───────────────────────────────────┐
                   │   bleak Cross-Platform Engine     │
                   └─────────────────┬─────────────────┘
                                     │
         ┌───────────────────────────┼───────────────────────────┐
         ▼                           ▼                           ▼
 ┌───────────────┐           ┌───────────────┐           ┌───────────────┐
 │     Linux     │           │     macOS     │           │    Windows    │
 ├───────────────┤           ├───────────────┤           ├───────────────┤
 │ • BlueZ DBus  │           │ • Native Core │           │ • Windows.    │
 │ • Systemd /   │           │   Bluetooth   │           │   Devices.    │
 │   Raspberry Pi│           │ • Apple Silicon/│           │   Bluetooth   │
 │ • dbus-fast   │           │   Intel Mac   │           │   (WinRT BLE) │
 └───────────────┘           └───────────────┘           └───────────────┘
```

1. **Bluetooth Layer (`bleak`)**: Automatically selects the native OS Bluetooth subsystem:
   - **Linux**: Speaks directly to the Linux BlueZ daemon via asynchronous DBus sockets.
   - **macOS**: Communicates through Apple's native `CoreBluetooth` framework on both Apple Silicon (M1/M2/M3/M4) and Intel Macs.
   - **Windows**: Interfaces with the native `Windows.Devices.Bluetooth` Universal Windows Runtime (WinRT) APIs.
2. **MCP Protocol Layer (`mcp 2.x`)**: Operates over standard input/output (`stdio`), supported identically across all operating systems.
3. **No External Cloud Dependencies**: Communicates directly from your computer to the ring on your finger over local 2.4 GHz radio.

---

## ⚡ Feature Overview

- 🤖 **Model Context Protocol (MCP) Server**: Exposes 8 native tools to AI agents (`scan_rings`, `get_ring_status`, `blink_ring`, `sync_time`, `get_daily_activity`, `get_sleep_and_recovery`, `read_realtime_vitals`, `get_motion_sample`).
- 🔋 **Device Health & Battery**: Real-time battery %, charging state, hardware revision (`RY03_V3.0`), firmware version (`RY03_3.00.22`).
- 💡 **Physical Bidirectional Alerts**: Let your AI assistant physically blink the optical LEDs on your ring (`blink_ring`) when code finishes compiling or tests pass.
- 💤 **Sleep Staging & Hypnogram**: Reads multi-night sleep data (Deep, REM, Light, Awake) via the Big Data channel (`0xBC` / ID `0x27`).
- 📊 **Insight Engine (Recovery Score 0–100)**: Computes clinical-grade Recovery Scores, sleep efficiency, and Resting Heart Rate Nadir timing locally.
- 🏃 **Step & Activity Telemetry**: Daily cumulative steps, estimated calories, and distance.
- 🎮 **Raw 3-Axis Accelerometer (12-bit)**: Stream real-time motion at 25–350 Hz with pitch, roll, vector magnitude, and tap detection for gesture control or MIDI.
- 🔒 **Zero Telemetry / 100% Privacy**: No QRing app, no Chinese cloud servers, no account registration.

---

## 🚀 Quickstart Installation

### 1. Clone & Install

```bash
git clone https://github.com/orviwan/mcp-for-colmi-smartring.git
cd mcp-for-colmi-smartring

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .
```

---

## 🤖 Configuring with AI Assistants (Claude Desktop / Cursor)

### A. Claude Desktop

Edit your Claude Desktop configuration file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "smart-ring": {
      "command": "/path/to/Colmi/.venv/bin/python",
      "args": ["/path/to/Colmi/tools/colmi_mcp.py"],
      "env": {
        "PYTHONPATH": "/path/to/Colmi",
        "COLMI_RING_ADDRESS": "31:31:43:30:A9:00"
      }
    }
  }
}
```
*(Tip: If you omit `COLMI_RING_ADDRESS`, the server will automatically scan and bind to whichever ring is closest).*

### B. Cursor IDE

In Cursor Settings $\rightarrow$ Features $\rightarrow$ MCP Servers (or in `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "smart-ring": {
      "command": "/path/to/Colmi/.venv/bin/python",
      "args": ["/path/to/Colmi/tools/colmi_mcp.py"],
      "env": {
        "PYTHONPATH": "/path/to/Colmi"
      }
    }
  }
}
```

---

## 🛠️ MCP Tools Reference (What the AI Can Do)

| Tool Name | Parameters | Description |
| :--- | :--- | :--- |
| `scan_rings` | `timeout_seconds` (default: 4.0) | Scans for nearby rings and returns names, addresses, and RSSI. |
| `get_ring_status` | `address` (optional) | Reads battery percentage, charging state, hardware & firmware revisions. |
| `blink_ring` | `address` (optional) | Physically pulses green optical sensor LEDs twice (locator or notification chime). |
| `sync_time` | `address` (optional) | Synchronizes ring's internal RTC clock with computer's clock. |
| `get_daily_activity` | `address`, `days_ago` (default: 0) | Returns cumulative steps, calories (kcal), and distance (m). |
| `get_sleep_and_recovery`| `address` (optional) | Pulls sleep hypnogram and calculates **Recovery Score (0–100)** with sleep stage breakdown. |
| `read_realtime_vitals` | `address`, `metric`, `duration_seconds` | Takes an active optical pulse (Heart Rate BPM or SpO2 %). |
| `get_motion_sample` | `address` (optional) | Samples 3-axis accelerometer for 2s (X/Y/Z g-forces, pitch, roll, magnitude). |

---

## 💻 Standalone Command-Line Tools

You can also run all tools directly from your terminal:

```bash
# 1. Scan for nearby rings
colmi-scanner
# (or: python tools/colmi_scanner.py)

# 2. Query status & battery
colmi-reader --address 31:31:43:30:A9:00 --info --battery --set-time

# 3. Blink finder LED
colmi-reader --address 31:31:43:30:A9:00 --blink

# 4. Stream real-time 3-axis motion & tap detector
colmi-accel --address 31:31:43:30:A9:00

# 5. Record accelerometer samples to CSV for ML/gesture training
colmi-accel --address 31:31:43:30:A9:00 --csv my_gesture.csv

# 6. Run the Biometric Insight & Recovery Scoring Engine (Demo Simulation)
colmi-insights --demo
```

---

## 📚 Deep-Dive Documentation Index

| Documentation Guide | Contents |
| :--- | :--- |
| [**Smart Ring MCP Server Guide**](docs/smart_ring_mcp_server.md) | Full architectural specification, JSON-RPC schemas, and Claude/Cursor conversation scenarios. |
| [**Biometric Insights Matrix**](docs/biometric_insights_matrix.md) | Physiological reference matrix comparing smart ring insights: HRV (RMSSD vs proxy), Resting Heart Rate nadir timing, sleep architecture, sleep apnea (ODI), temperature deviation, and custom recovery scoring formulas. |
| [**Hardware Architecture Deep Dive**](docs/colmi_hardware_deep_dive.md) | Teardown analysis, physical specifications, SoC variants (BlueX RF03 vs Realtek RTL8762E), sensors (STK8321, VC30F), battery systems, and SWD debug pads. |
| [**BLE Protocol Specification**](docs/colmi_ble_protocol_spec.md) | Byte-level wire protocol specification: 16-byte packet framing, checksum calculation, command tables (`0x01`–`0xA1`), Big Data service (`0xBC`), sleep stage hypnograms, and OTA DFU firmware updates. |
| [**Smart Ring Industry Comparison**](docs/smart_ring_industry_comparison.md) | Master comparison matrix across COLMI, Oura Ring 3/4, Ultrahuman Ring AIR, RingConn Gen 1/2, and Samsung Galaxy Ring. Details sensor arrays, pricing, subscription models, cloud APIs, and BLE hackability. |
| [**Open-Source Ecosystem Directory**](docs/open_source_ecosystem.md) | Survey of GitHub projects, Python/Go/TypeScript tools, Web Bluetooth apps, custom firmware patches (FasterRawValuesMOD, Nosh118 Low-Latency, 352Hz overdrive), and privacy analysis. |
| [**Sensor Capabilities & Clinical Validity**](docs/sensor_capabilities_and_validity.md) | Biophysical principles of smart ring sensors, AC/DC PPG signal decomposition, optical pulse oximetry, HRV proxy analysis, and debunking fake metrics (blood pressure, blood glucose, ECG). |
| [**Guide: Getting Started with Python**](docs/guides/getting_started_with_python.md) | Step-by-step tutorial on connecting to the ring, querying battery, synchronizing time, and streaming real-time heart rate using Python and `bleak`. |
| [**Guide: Raw Accelerometer & Gestures**](docs/guides/raw_accelerometer_and_gestures.md) | How to stream raw 12-bit 3-axis motion data, calculate pitch/roll/g-force, detect taps and wave gestures, and map tilt to virtual mice or MIDI controllers. |
| [**Guide: Privacy & Cloudless Setup**](docs/guides/privacy_and_cloudless_setup.md) | How to ditch the proprietary QRing app and set up a 100% private, self-hosted telemetry pipeline with SQLite, VictoriaMetrics, Home Assistant, and Grafana. |

---

## 🧪 Automated Testing

The repository includes a comprehensive `pytest` test suite with 20 unit tests verifying packet framing, 8-bit checksum algorithms, 12-bit signed accelerometer math, sleep hypnogram decoders, and MCP tool registrations:

```bash
PYTHONPATH=. pytest -v tests/
```

---

## 🙏 Attributions & Prior Art

This project builds directly upon the reverse-engineering breakthroughs, packet logs, and hardware teardowns conducted by the open-source smart ring research community. We gratefully credit the following upstream projects and authors:

- **Aaron Christophel ([@atc1441](https://github.com/atc1441))**: Reverse-engineering the BlueX Micro RF03 SoC, STK8321 accelerometer, VC30F optical sensor, SWD pinouts, and creating the `FasterRawValuesMOD` firmware patch and Web Bluetooth flasher ([atc1441/ATC_RF03_Ring](https://github.com/atc1441/ATC_RF03_Ring)).
- **Wesley Ellis ([@tahnok](https://github.com/tahnok))**: Developing the foundational Python BLE client, discovering the 16-byte packet structure and 8-bit checksum algorithm ([tahnok/colmi_r02_client](https://github.com/tahnok/colmi_r02_client)).
- **Tony Smith ([@smittytone](https://github.com/smittytone))**: Discovering and reverse-engineering the Big Data GATT channel (`DE5BF728...`) for multi-night sleep hypnograms and 24-hour SpO2 max/min records ([smittytone/RingCLI](https://github.com/smittytone/RingCLI)).
- **Puxtril ([@Puxtril](https://github.com/Puxtril))**: Documenting the complete QRing opcode catalog, device settings, and response schemas reverse-engineered from the COLMI R03 ([Puxtril/colmi-docs](https://github.com/Puxtril/colmi-docs)).
- **Nosh118 ([@Nosh118](https://github.com/Nosh118))**: Discovering the Realtek RTL8762ESF / RT02R hardware revision, QRing DFU OTA transfer protocol, and motion-to-MIDI mapping ([Nosh118/colmi-ring-tools](https://github.com/Nosh118/colmi-ring-tools)).
- **Robin O'JW ([@robinojw](https://github.com/robinojw))**: TypeScript implementation, modular BLE adapters, and test fixture references ([robinojw/openring](https://github.com/robinojw/openring)).
- **Cyril Zakka, MD ([@cyrilzakka](https://github.com/cyrilzakka))**: Native iOS companion app connecting COLMI rings to Apple HealthKit with 100% local privacy ([cyrilzakka/Halo-iOS](https://github.com/cyrilzakka/Halo-iOS)).
- **CitizenOneX ([@CitizenOneX](https://github.com/CitizenOneX))**: 12-bit accelerometer two's complement decoding and wave gesture detection ([CitizenOneX/colmi_r0x_controller](https://github.com/CitizenOneX/colmi_r0x_controller)).
- **Juan Perez ([@perezjuanj](https://github.com/perezjuanj))**: Research into RingConn Gen 2 BLE protocol ([perezjuanj/OpenCircuit](https://github.com/perezjuanj/OpenCircuit)).

See [ATTRIBUTIONS.md](ATTRIBUTIONS.md) for full license notices and upstream project details.

---

## 📄 License

This project is licensed under the permissive **MIT License** — see the [LICENSE](LICENSE) file for details.