bluetooth-trainer-expert

# Bluetooth Trainer Expert

This skill provides a proven workflow for developing biking fitness applications that interact with Smart Trainers (e.g., Wahoo KICKR, FTMS devices). It emphasizes a "Console First" approach to isolate connection and protocol logic before attempting UI integration.

## Core Philosophy

1.  **Console First**: Always prove the protocol logic in a simple C# Console Application (`BikeFitnessConsole`) before touching the main UI (WPF/MAUI).
2.  **Physical Verification**: Telemetry (Success/Fail responses) is insufficient for brake logic. You MUST ask the user to "Pedal and verify resistance change" to confirm the device actually engaged the magnet/motor.
3.  **Protocol Agnosticism**: Support both standard FTMS (`0x1826`) and legacy Wahoo (`0xA026...`) protocols.

## Phase 1: Diagnostic Console App

Create a lightweight console app to handle scanning, connection, and raw command testing.

**Key Features to Implement:**
-   **Scanner**: Filter for `0x1826` (FTMS), `0xA026` (Wahoo), and `0x1818` (Power).
-   **Service Explorer**: List all available Services and Characteristics to confirm UUIDs.
-   **Indication Handler**: **CRITICAL**. You must subscribe to `Indicate` on the Control Point characteristic *before* sending any write commands. Failure to do so often results in silent failures or "Attribute Not Found" errors on writes.

## Data Format (Endianness)

**Bluetooth LE GATT characteristics standardly use Little Endian byte order.**

-   **Reading**: When parsing multi-byte values (e.g., Speed, Power, Time), interpret the *least significant byte first*.
    -   Example: `0xE8 0x03` -> `0x03E8` -> `1000`.
-   **Writing**: When constructing commands (e.g., Target Watts, Grade), ensure you serialize `UInt16`/`Int16` values to Little Endian.
-   **Note**: While standard FTMS and common Wahoo OpCodes (`0x40-0x45`) follow Little Endian, always verify proprietary manufacturer-specific characteristics if behavior is unexpected.

## Phase 2: Protocol Identification & Control Points

Identify the correct Control Point (CP) for the device.

### 1. FTMS (Fitness Machine Service) - Preferred
*   **Service UUID**: `00001826-0000-1000-8000-00805f9b34fb`
*   **Control Point**: `00002ad9-0000-1000-8000-00805f9b34fb` (Fitness Machine Control Point)
*   **Init Sequence**:
    1.  Subscribe to CP Indications.
    2.  Send `0x00` (Request Control).
    3.  Send `0x07` (Start/Resume).

### 2. Wahoo Legacy (KICKR / SNAP)
*   **Service UUID**: `a026ee01-0a7d-4ab3-97fa-f1500f9feb8b`
*   **Control Point**: `a026e005-0a7d-4ab3-97fa-f1500f9feb8b` (Often hidden inside the Power Service `0x1818` on some firmware).
*   **Init Sequence**:
    1.  Subscribe to CP Indications.
    2.  Send `0x00` (Init/Unlock).

## Phase 3: OpCode Discovery Strategy

Different devices support different modes. Use the Console App to "Scan" OpCodes `0x40` through `0x45` by sending `[OpCode, 0x00]` and observing the Indication response.

*   **Response Format**: `01-OpCode-Result` (Where Result `01` = Success, `04` = Not Supported, `40` = Fail).
*   **Common OpCodes**:
    *   `0x40` **Level Mode**: 0-9 discrete levels. Basic.
    *   `0x41` **Resistance Mode**: 0-100% brake force. Most reliable.
    *   `0x42` **Sim Mode Enable**: Activates physics engine (Grade/Wind/Weight). **Warning**: Many older or lower-end devices (e.g., KICKR SNAP) return "Success" for params but FAIL (`0x40`) when trying to Enable this mode.
    *   `0x43` **Sim Parameters**: Sets Grade, Weight, Crr, Cw.

## Phase 4: "Fake" Simulation Mode (Grade Mapping)

If the device fails to support Native Sim Mode (`0x42`), you must implement **Grade-to-Resistance Mapping** in software to support "Hilly" or "Mountain" workouts.

**Recommended Mapping (User Calibrated):**
Map the visual "Grade %" to the device's "Resistance %" (OpCode `0x41`).

| Grade Input | Resistance Output | Feel |
| :--- | :--- | :--- |
| **-10%** | **0.0%** | Coasting / Free spin. |
| **0%** | **1.0%** | Flat road friction (light). |
| **20%** | **40.0%** | Steep climb. (Cap at 40% to avoid "brick wall"). |

**Logic:**
Use a piecewise linear function:
1.  **Downhill (-10 to 0)**: Interpolate 0.0 -> 0.01.
2.  **Uphill (0 to 20)**: Interpolate 0.01 -> 0.40.

## Phase 5: Telemetry

*   **Power**: Standard `0x2A63` (Cycling Power Measurement).
*   **Speed/Distance**: Often missing from FTMS on older devices. Calculate locally using **Wheel Revolutions** from the Power Measurement characteristic (Data bytes `flags & 0x10`).
    *   `Distance = WheelRevs * TireCircumference`
    *   `Speed = DeltaDistance / DeltaTime`
*   **Cadence**: Check `0x1816` (Speed & Cadence) or Crank Data in Power (`0x1818`).

## Checklist for Implementation

1.  [ ] **Console Test**: Can you connect and receive Indications?
2.  [ ] **OpCode Scan**: Which modes return `01` (Success)?
3.  [ ] **Physical Test**: Does sending `0x41 0x32` (50% res) make it hard to pedal?
4.  [ ] **Mapping**: Does -10% Grade feel like zero resistance?
5.  [ ] **UI**: Does the UI display Grade (not raw resistance) to the user?