# bluetooth2-virtual-device-esp32

**Repository Path**: hagedr/bluetooth2-virtual-device-esp32

## Basic Information

- **Project Name**: bluetooth2-virtual-device-esp32
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-24
- **Last Updated**: 2026-10-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GamepadBridge ESP32

用 ESP32 替代手机 App：蓝牙手柄 → ESP32 → Wi‑Fi WebSocket → 车机虚拟手柄。

协议与 `xunishoubing` 手机端一致。详见 [docs/功能清单与实现逻辑.md](docs/功能清单与实现逻辑.md)。

## 硬件

- 经典 ESP32（ESP32-WROOM-32 / DevKitC，经典蓝牙 + BLE + Wi‑Fi）——默认环境 `esp32dev`
  - 已验证：ESP32-D0WDQ6，CH340 串口，Xbox One 手柄
- ESP32-S3 可用环境 `esp32s3`，但只有 BLE，只支持 BLE 手柄
- 板载 LED：GPIO2（状态指示）
- BOOT 键 GPIO0：上电按住或运行时长按约 2.5s → 配网页

## 烧录

1. USB 连接 ESP32
2. **双击 `烧录.bat`**（会自动编译并上传）
3. 需要看日志时双击 `串口监视.bat`

命令行等价：

```bash
pio run -t upload              # 经典 ESP32（默认 esp32dev）
pio run -e esp32s3 -t upload   # ESP32-S3
pio device monitor
```

注意：

- `platformio.ini` 中 `esp32dev` 写死了 `upload_port = COM5`，换电脑或换口要改这里
- `烧录.bat` 设置了代理 `http://127.0.0.1:7897`，首次下载工具链前要先开代理
- 若报 `Wrong boot mode detected (0x13)`：按住 BOOT，点一下 RST/EN，松开 RST 后保持 BOOT 再烧
- `platformio.ini` 使用 `pio-framework-bluepad32`，不要改回普通 `lib_deps` 拉 Bluepad32

## 首次配网

1. 板子开热点 `GamepadBridge`，密码 `12345678`
2. 手机连热点，浏览器打开 `http://192.168.4.1`
3. 填写：车机同网 Wi‑Fi SSID/密码、端口（默认 `11882`）；**车机 IP 可留空**（自动扫描同网段）
4. 保存后板子重启；找到车机后会把 IP 写入 Flash，下次优先用缓存 IP

## 指示灯

快闪 = 0.2s 亮/灭；慢闪 = 1.5s 亮/灭。

| 灯 | 含义 |
|----|------|
| 慢闪 | 开机 |
| 连续快闪 | 配网模式 |
| 2 快闪 + 停 1s | 正在连 Wi‑Fi |
| 3 快闪 + 停 1s | Wi‑Fi 已连，等手柄 |
| 4 快闪 + 停 1s | 手柄已连，WS 未通 |
| 5 快闪 + 停 1s | WS 已连，未拿到玩家名 |
| 常亮 | 全部就绪，可正常玩 |
| 0.1s 极快闪 | 错误 |

## 串口状态

| 日志 | 含义 |
|------|------|
| `[WIFI] Connecting` | 连车机热点/局域网 |
| `[PAD] RF coex: prefer BT` | 未连手柄，蓝牙优先（便于配对） |
| `[PAD] Connected` | 蓝牙手柄已连 |
| `[WS] Connected` / `Joined, player=...` | WebSocket 成功并拿到玩家名 |
| `[STATUS] JOINED` | LED 常亮，可操作 |

配对过程中出现 `SDP device = NULL`、`sdp_query_timeout` 等是蓝牙库日志，只要最后出现 `[PAD] Connected` 即可。

## 多手柄

一块板只连 1 只手柄。车机按源 IP 区分玩家，多玩家请用多块板。

## 验收对照

按文档第六节：配网页 → Wi‑Fi → 手柄 → WS 玩家名 → 游戏内按键响应 → 断线重连 / 长按重配。