efferent-ble-simulator

Efferent simulates Bluetooth Low Energy (BLE) peripheral devices over a real radio (Linux BlueZ): FTMS smart trainers, cycling power meters, speed/cadence sensors and heart rate monitors. It exposes an MCP server (stdio or HTTP) so AI agents — and the bundled Web dashboard — can start, configure and monitor simulations as if controlling a real trainer.

Features

• 4 device types over real BLE radio: FTMS smart trainer (0x1826), Cycling Power (0x1818), Speed/Cadence (0x1816), Heart Rate (0x180D)

• Full FTMS control point support: Request Control / Start / Stop / Reset / Set Target Power / Set Resistance / Set Indoor Bike Simulation Params

• Dynamic simulation: human-like power/cadence drift + physics-based speed model (weight, grade, Crr, CdA), 5 riding scenarios including the scripted ride_script

• Hot parameter update: change params while running — the connected phone keeps its link and receives new values on the next notify (no re-pair)

• Named config presets: save / load / rename / delete up to 20 named configs, shared between MCP and Dashboard

• 17 MCP tools for agents: control, configure, config presets, interaction rules, sessions, logs, live device state, version

• Web dashboard (React + shadcn/ui): status, forms, one-click ride templates, interaction rules, session/config management, live log side-panel

• Docker Compose one-command deployment (MCP + Dashboard + Skill file over HTTP), long-running with health checks

• Versioned: MCP serverInfo.version + ble_get_version let agents detect updates

Related MCP server: pyBTMCP

Runtime Environment

Architecture

┌──────────────┐   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...)│
                                     └───────────────────────────┘

Device Types

Quick Start

Prerequisites

• Linux with BlueZ ≥ 5.87 (bluetoothd) and a BLE-capable adapter

  BlueZ 5.86 has an advertisement-registration bug; on kernels with strict MGMT validation every RegisterAdvertisement fails. Upgrade first: sudo pacman -S bluez && sudo systemctl restart bluetooth (Arch) / sudo apt install bluez (Debian).

• Node.js ≥ 18

1. Native install

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 writes /etc/dbus-1/system.d/ble-simulator.conf — required for non-root GATT registration (without it the device advertises but cannot be connected).

2. Docker Compose (recommended for servers)

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

Zero-compile build (better-sqlite3 prebuilt binary); on restricted networks use a mirror:

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

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

MCP Tools (17)

Example

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

Dynamic Simulation

Enable via simulation on FTMS / CyclingPower / 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" }
}

Scenarios

• steady — natural micro-variation only

• freeride (default) — base power drifts ±20% every 60–180s

• intervals — high/low power alternation

• warmup_main_cooldown — warmup → main → cooldown

• ride_script — scripted ride: a sequence of riding actions (start / cruise / climb / sprint / coast / stop), each with target power, grade and optional cadence; auto-starts, loops with repeat: true, stop zeroes power/cadence/speed. Omit phases to use the built-in default script.

Hot Update & Stable Serial

• Hot update: ble_configure while running + same device type applies params in place — the connected phone keeps its link and receives updated values on the next notify. Device-type changes still restart (new serial forces re-discovery).

• Stable serial: SIM_SERIAL_STABLE=1 keeps the serial stable across same-type sessions (SIM001-FTMS), so a phone can reconnect after stop/start without forgetting the device.

Environment Variables

Source Layout

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

BLE peripheral access runs over the host BlueZ D-Bus (the container mounts the host D-Bus socket). See docs/design/*.md for design records.

License

MIT © BLE Simulator Contributors