efferent-ble-simulator

Efferent имитирует периферийные устройства Bluetooth Low Energy (BLE) через реальный радиоканал (Linux BlueZ): умные тренажёры FTMS, велосипедные измерители мощности, датчики скорости/каденса и мониторы сердечного ритма. Он предоставляет MCP-сервер (stdio или HTTP), благодаря чему AI-агенты — и встроенная веб-панель — могут запускать, настраивать и контролировать симуляции так, как если бы управляли реальным тренажёром.

Возможности

• 4 типа устройств через реальный BLE-радиоканал: умный тренажёр FTMS (0x1826), велосипедная мощность (0x1818), скорость/каденс (0x1816), сердечный ритм (0x180D)

• Полная поддержка контрольной точки FTMS: Request Control / Start / Stop / Reset / Set Target Power / Set Resistance / Set Indoor Bike Simulation Params

• Динамическая симуляция: реалистичный дрейф мощности/каденса + физическая модель скорости (вес, уклон, Crr, CdA), 5 сценариев езды, включая скриптовый ride_script

• Горячее обновление параметров: изменение параметров на лету — подключённый телефон сохраняет соединение и получает новые значения при следующем notify (без повторного сопряжения)

• Именованные пресеты конфигураций: сохранение / загрузка / переименование / удаление до 20 именованных конфигураций, общих для MCP и панели

• 17 MCP-инструментов для агентов: управление, настройка, пресеты конфигураций, правила взаимодействия, сессии, логи, живое состояние устройства, версия

• Веб-панель (React + shadcn/ui): статус, формы, шаблоны езды в один клик, правила взаимодействия, управление сессиями/конфигурациями, боковая панель живых логов

• Docker Compose — развёртывание одной командой (MCP + панель + файл навыка по HTTP), длительная работа с проверками работоспособности

• Версионирование: MCP serverInfo.version + ble_get_version позволяют агентам обнаруживать обновления

Related MCP server: pyBTMCP

Среда выполнения

Архитектура

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

Типы устройств

Быстрый старт

Предварительные требования

• Linux с BlueZ ≥ 5.87 (bluetoothd) и адаптером с поддержкой BLE

  В BlueZ 5.86 есть ошибка регистрации рекламных объявлений; на ядрах со строгой проверкой MGMT каждый RegisterAdvertisement завершается ошибкой. Обновитесь заранее: sudo pacman -S bluez && sudo systemctl restart bluetooth (Arch) / sudo apt install bluez (Debian).

• Node.js ≥ 18

1. Нативная установка

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 записывает /etc/dbus-1/system.d/ble-simulator.conf — обязательно для регистрации GATT без прав root (без него устройство транслируется, но к нему нельзя подключиться).

2. Docker Compose (рекомендуется для серверов)

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

Сборка без компиляции (готовый бинарник better-sqlite3); в ограниченных сетях используйте зеркало:

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

Управление: bash scripts/docker-up.sh status|logs|down

MCP-инструменты (17)

Пример

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

Динамическая симуляция

Включается через simulation для 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" }
}

Сценарии

• steady — только естественная микро-вариация

• freeride (по умолчанию) — базовая мощность дрейфует ±20% каждые 60–180 с

• intervals — чередование высокой/низкой мощности

• warmup_main_cooldown — разминка → основная часть → заминка

• ride_script — скриптовая езда: последовательность действий (start / cruise / climb / sprint / coast / stop), каждое с целевой мощностью, уклоном и опциональным каденсом; автозапуск, зацикливание с repeat: true, stop обнуляет мощность/каденс/скорость. Опустите phases, чтобы использовать встроенный скрипт по умолчанию.

Горячее обновление и стабильный серийный номер

• Горячее обновление: ble_configure во время работы + тот же тип устройства применяет параметры на месте — подключённый телефон сохраняет соединение и получает обновлённые значения при следующем notify. Смена типа устройства всё равно вызывает перезапуск (новый серийный номер вынуждает повторное обнаружение).

• Стабильный серийный номер: SIM_SERIAL_STABLE=1 сохраняет серийный номер стабильным между сессиями одного типа (SIM001-FTMS), поэтому телефон может переподключиться после stop/start без удаления устройства.

Переменные окружения

Структура исходного кода

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-периферии осуществляется через D-Bus хост-сервиса BlueZ (контейнер монтирует сокет D-Bus хоста). См. docs/design/*.md — записи о проектировании.

Лицензия

MIT © BLE Simulator Contributors