efferent-ble-simulator

Efferent simula dispositivos periféricos Bluetooth Low Energy (BLE) a través de una radio real (Linux BlueZ): rodillos inteligentes FTMS, potenciómetros de ciclismo, sensores de velocidad/cadencia y pulsómetros de frecuencia cardíaca. Expone un servidor MCP (stdio o HTTP) para que los agentes de IA — y el panel web incluido — puedan iniciar, configurar y supervisar simulaciones como si controlaran un rodillo real.

Características

• 4 tipos de dispositivo sobre radio BLE real: rodillo inteligente FTMS (0x1826), potencia de ciclismo (0x1818), velocidad/cadencia (0x1816), frecuencia cardíaca (0x180D)

• Soporte completo del punto de control FTMS: Request Control / Start / Stop / Reset / Set Target Power / Set Resistance / Set Indoor Bike Simulation Params

• Simulación dinámica: deriva de potencia/cadencia realista + modelo de velocidad basado en física (peso, pendiente, Crr, CdA), 5 escenarios de rodaje, incluido el ride_script con guion

• Actualización de parámetros en caliente: cambia los parámetros mientras se ejecuta — el teléfono conectado mantiene su enlace y recibe los nuevos valores en la siguiente notificación (sin re-vinculación)

• Presets de configuración con nombre: guardar / cargar / renombrar / eliminar hasta 20 configuraciones con nombre, compartidas entre MCP y el panel

• 17 herramientas MCP para agentes: control, configuración, presets de configuración, reglas de interacción, sesiones, registros, estado del dispositivo en vivo, versión

• Panel web (React + shadcn/ui): estado, formularios, plantillas de rodaje con un clic, reglas de interacción, gestión de sesiones/configuraciones, panel lateral de registros en vivo

• Docker Compose de despliegue con un solo comando (MCP + Panel + archivo de Skill por HTTP), de larga duración con comprobaciones de salud

• Versionado: serverInfo.version de MCP + ble_get_version permiten a los agentes detectar actualizaciones

Related MCP server: pyBTMCP

Entorno de ejecución

Arquitectura

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

Tipos de dispositivo

Inicio rápido

Requisitos previos

• Linux con BlueZ ≥ 5.87 (bluetoothd) y un adaptador compatible con BLE

  BlueZ 5.86 tiene un error de registro de anuncios; en kernels con validación MGMT estricta, cada RegisterAdvertisement falla. Actualiza primero: sudo pacman -S bluez && sudo systemctl restart bluetooth (Arch) / sudo apt install bluez (Debian).

• Node.js ≥ 18

1. Instalación nativa

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 escribe /etc/dbus-1/system.d/ble-simulator.conf — necesario para el registro GATT sin root (sin él, el dispositivo anuncia pero no se puede conectar).

2. Docker Compose (recomendado para servidores)

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

Compilación sin compilar (binario precompilado de better-sqlite3); en redes restringidas usa un espejo:

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

Gestión: bash scripts/docker-up.sh status|logs|down

Herramientas MCP (17)

Ejemplo

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

Simulación dinámica

Actívala mediante simulation en 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" }
}

Escenarios

• steady — solo micro-variación natural

• freeride (predeterminado) — la potencia base varía ±20 % cada 60–180 s

• intervals — alternancia de potencia alta/baja

• warmup_main_cooldown — calentamiento → parte principal → enfriamiento

• ride_script — rodaje con guion: una secuencia de acciones de rodaje (start / cruise / climb / sprint / coast / stop), cada una con potencia objetivo, pendiente y cadencia opcional; se autoinicia, se repite con repeat: true, stop pone potencia/cadencia/velocidad a cero. Omite phases para usar el guion predeterminado integrado.

Actualización en caliente y serial estable

• Actualización en caliente: ble_configure mientras se ejecuta + mismo tipo de dispositivo aplica los parámetros en el lugar — el teléfono conectado mantiene su enlace y recibe los valores actualizados en la siguiente notificación. Los cambios de tipo de dispositivo siguen reiniciando (un serial nuevo obliga a redescubrir).

• Serial estable: SIM_SERIAL_STABLE=1 mantiene el serial estable entre sesiones del mismo tipo (SIM001-FTMS), de modo que un teléfono puede reconectarse tras detener/iniciar sin olvidar el dispositivo.

Variables de entorno

Estructura del código fuente

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

El acceso al periférico BLE se realiza a través del D-Bus de BlueZ del host (el contenedor monta el socket D-Bus del host). Consulta docs/design/*.md para los registros de diseño.

Licencia

MIT © BLE Simulator Contributors