efferent-ble-simulator

Efferent simuliert Bluetooth-Low-Energy-(BLE)-Peripheriegeräte über eine echte Funkverbindung (Linux BlueZ): FTMS-Smart-Trainer, Fahrrad-Leistungsmesser, Geschwindigkeits-/Trittfrequenzsensoren und Herzfrequenzsensoren. Es stellt einen MCP-Server (stdio oder HTTP) bereit, sodass KI-Agenten – und das mitgelieferte Web-Dashboard – Simulationen starten, konfigurieren und überwachen können, als würden sie einen echten Trainer steuern.

Funktionen

• 4 Gerätetypen über echte BLE-Funkverbindung: FTMS-Smart-Trainer (0x1826), Leistungsmesser (0x1818), Geschwindigkeit/Trittfrequenz (0x1816), Herzfrequenz (0x180D)

• Vollständige FTMS-Steuerpunkt-Unterstützung: Request Control / Start / Stop / Reset / Set Target Power / Set Resistance / Set Indoor Bike Simulation Params

• Dynamische Simulation: realistische Leistungs-/Trittfrequenzschwankungen + physikbasierte Geschwindigkeitsberechnung (Gewicht, Steigung, Crr, CdA), 5 Fahrszenarien inklusive des skriptbasierten ride_script

• Hot-Parameter-Update: Parameter während des Betriebs ändern – das verbundene Telefon behält die Verbindung und erhält die neuen Werte beim nächsten Notify (kein erneutes Koppeln)

• Benannte Konfigurationsprofile: bis zu 20 benannte Konfigurationen speichern / laden / umbenennen / löschen, gemeinsam genutzt von MCP und Dashboard

• 17 MCP-Tools für Agenten: Steuerung, Konfiguration, Konfigurationsprofile, Interaktionsregeln, Sitzungen, Protokolle, Live-Gerätestatus, Version

• Web-Dashboard (React + shadcn/ui): Status, Formulare, Ein-Klick-Fahrprofile, Interaktionsregeln, Sitzungs-/Konfigurationsverwaltung, Live-Protokoll-Seitenleiste

• Docker Compose-Bereitstellung mit einem Befehl (MCP + Dashboard + Skill-Datei über HTTP), langlaufend mit Health-Checks

• Versioniert: MCP serverInfo.version + ble_get_version ermöglichen Agenten die Erkennung von Updates

Related MCP server: pyBTMCP

Laufzeitumgebung

Architektur

┌──────────────┐   MCP protocol    ┌───────────────────────────┐
│ AI Agent /   │ ◄───────────────► │ MCP Server (HTTP :3300)   │
│ MCP Client   │  stdio / :3300    │ Web Dashboard (:3330)     │
│ (Claude,     │                   └────────────┬──────────────┘
│  Codex, pi)  │                                │ BlueZ D-Bus (system bus)
└──────────────┘                                ▼
                                     ┌───────────────────────────┐
                                     │ Host Linux BlueZ          │
                                     │ bluetoothd + BLE adapter  │
                                     │ (D-Bus policy, ≥ 5.87)    │
                                     └────────────┬──────────────┘
                                                  │ HCI / radio
                                                  ▼
                                     ┌───────────────────────────┐
                                     │ BLE advertisement + GATT  │
                                     │ FTMS / Power / CSC / HR   │
                                     └────────────┬──────────────┘
                                                  │
                                     ┌────────────▼──────────────┐
                                     │ Phone / Cycling App       │
                                     │ (Zwift, Garmin, Strava...)│
                                     └───────────────────────────┘

Gerätetypen

Schnellstart

Voraussetzungen

• Linux mit BlueZ ≥ 5.87 (bluetoothd) und einem BLE-fähigen Adapter

  BlueZ 5.86 hat einen Fehler bei der Werberegistrierung; bei Kernels mit strenger MGMT-Validierung schlägt jede RegisterAdvertisement fehl. Zuerst aktualisieren: sudo pacman -S bluez && sudo systemctl restart bluetooth (Arch) / sudo apt install bluez (Debian).

• Node.js ≥ 18

1. Native Installation

npm install
npm run setup     # sudo — installs D-Bus policy, enables bluetoothd, verifies GATT
npm run build
npm run start:http   # HTTP mode on :3300 (or npm start for stdio)

npm run setup schreibt /etc/dbus-1/system.d/ble-simulator.conf – erforderlich für GATT-Registrierung ohne Root-Rechte (ohne diese Datei wirbt das Gerät, kann aber nicht verbunden werden).

2. Docker Compose (empfohlen für Server)

bash scripts/docker-up.sh     # host prep (sudo, once) + build + start

Kompilierungsfreier Build (better-sqlite3 vorkompiliertes Binärpaket); bei eingeschränkten Netzwerken einen Mirror verwenden:

NPM_REGISTRY=https://registry.npmmirror.com \
BETTER_SQLITE3_BINARY_HOST_MIRROR=https://registry.npmmirror.com/-/binary/better-sqlite3 \
bash scripts/docker-up.sh

Verwaltung: bash scripts/docker-up.sh status|logs|down

MCP-Tools (17)

Beispiel

{
  "method": "tools/call",
  "params": {
    "name": "ble_start",
    "arguments": {
      "deviceType": "ftms",
      "ftms": { "simulation": { "enabled": true, "scenario": { "type": "ride_script" } } }
    }
  }
}

Dynamische Simulation

Aktivieren über simulation bei FTMS / Leistungsmesser / CSC:

"simulation": {
  "enabled": true,
  "riderWeightKg": 75, "bikeWeightKg": 8, "crr": 0.004, "cdA": 0.35,
  "fatigueFactor": 0.0005, "cadenceCoupling": "proportional", "microPauseProbability": 0.008,
  "autoStart": true,
  "scenario": { "type": "ride_script" }
}

Szenarien

• steady – nur natürliche Mikroschwankungen

• freeride (Standard) – Grundleistung driftet ±20 % alle 60–180 s

• intervals – Wechsel zwischen hoher und niedriger Leistung

• warmup_main_cooldown – Aufwärmen → Hauptteil → Ausfahren

• ride_script – skriptgesteuerte Fahrt: eine Abfolge von Fahraktionen (start / cruise / climb / sprint / coast / stop), jeweils mit Zielleistung, Steigung und optionaler Trittfrequenz; startet automatisch, wiederholt sich mit repeat: true, stop setzt Leistung/Trittfrequenz/Geschwindigkeit auf null. phases weglassen, um das integrierte Standard-Skript zu verwenden.

Hot-Update & Stabile Seriennummer

• Hot-Update: ble_configure während des Betriebs + gleicher Gerätetyp wendet Parameter direkt an – das verbundene Telefon behält die Verbindung und erhält aktualisierte Werte beim nächsten Notify. Ein Wechsel des Gerätetyps startet weiterhin neu (neue Seriennummer erzwingt erneutes Erkennen).

• Stabile Seriennummer: SIM_SERIAL_STABLE=1 hält die Seriennummer über Sitzungen desselben Typs stabil (SIM001-FTMS), sodass ein Telefon nach Stopp/Start ohne Vergessen des Geräts erneut verbinden kann.

Umgebungsvariablen

Quellcode-Struktur

src/
├── index.ts             # entry, lifecycle
├── mcp-server.ts        # 17 MCP tool definitions & handlers
├── ble-controller.ts    # BlueZ D-Bus lifecycle, advertisement, hot-update
├── database.ts          # SQLite layer (sessions / saved_configs / logs)
├── config.ts            # config merge & defaults
├── version.ts           # version single-source
├── simulator.ts         # HeartRate / Battery simulators
├── cycling-simulator.ts # power/cadence simulators + physics + ride_script engine
└── devices/             # heart-rate / cycling-power / csc / ftms GATT devices

Der BLE-Peripheriezugriff läuft über den Host-BlueZ-D-Bus (der Container mountet den Host-D-Bus-Socket). Siehe docs/design/*.md für Entwurfsdokumente.

Lizenz

MIT © BLE-Simulator-Mitwirkende