# game-pilot

**Repository Path**: narcijie/game-pilot

## Basic Information

- **Project Name**: game-pilot
- **Description**: Game Pilot 是一个 PC 与外设之间的桌面桥接项目。Host 端运行在 Windows 桌面，负责采集电脑状态并通过串口发送 JSON Lines 数据；Device 端运行在 ESP32-S3-EYE 开发板上，负责接收、解析并在板载屏幕上图形化展示这些指标。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-22
- **Last Updated**: 2026-04-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Game Pilot

Game Pilot 是一个 PC 与外设之间的桌面桥接项目。Host 端运行在 Windows 桌面，负责采集电脑状态并通过串口发送 JSON Lines 数据；Device 端运行在 ESP32-S3-EYE 开发板上，负责接收、解析并在板载屏幕上图形化展示这些指标。

当前仓库包含两个工程：

- `host/`：Qt 6 + C++ 桌面端应用。
- `device/`：ESP-IDF + LVGL 的 ESP32-S3-EYE 固件。

## 功能概览

- Windows 桌面端后台常驻托盘运行。
- 通过串口向外设发送 UTF-8 JSON Lines 指标帧。
- 采集 CPU、内存、网络、磁盘、系统、电源、音频、前台窗口、进程、GPU、温度、显示亮度等指标。
- 集成 PresentMon，用于可选采集前台游戏 FPS。
- ESP32-S3-EYE 通过 USB Serial/JTAG 接收数据。
- Device 端在 240x240 LCD 上分页展示指标，并尽量使用进度条等图形控件。
- 支持基础反向控制协议：音量、静音、播放/暂停、上一首、下一首。

## 目录结构

```text
game-pilot/
  host/                    Qt 6 桌面端
  device/                  ESP32-S3-EYE 固件
  tools/presentmon/        随 host 集成的 PresentMon
```

## Host 构建

依赖：

- Windows
- Qt 6，需包含 `Core`、`Widgets`、`SerialPort`、`Test`
- CMake
- Ninja
- MinGW 或兼容 Qt kit 的 C++ 编译器

示例：

```powershell
cmake -S host -B host\build -G Ninja -DCMAKE_BUILD_TYPE=Release -DQt6_DIR=C:\Qt\6.8.3\mingw_64\lib\cmake\Qt6
cmake --build host\build --config Release
$env:PATH="C:\Qt\6.8.3\mingw_64\bin;C:\mingw64\bin;$env:PATH"
ctest --test-dir host\build --output-on-failure
```

构建完成后，`PresentMon.exe` 会自动复制到 `GamePilot.exe` 同目录，用于 FPS 采集。

## Device 构建与烧录

依赖：

- ESP32-S3-EYE 开发板
- ESP-IDF 5.4.x
- USB 连接开发板，使用 USB Serial/JTAG

示例：

```powershell
& C:\Users\Administrator\esp\v5.4.1\esp-idf\export.ps1
idf.py -C device set-target esp32s3
idf.py -C device build
idf.py -C device -p COM15 flash
```

烧录后，在 host 设置中选择 ESP32-S3-EYE 枚举出的 COM 口即可开始传输。

## 串口协议

协议采用 UTF-8 JSON Lines：一行一个 JSON 对象，以 `\n` 结尾。

指标帧示例：

```json
{"type":"metrics","version":1,"seq":123,"ts":1710000000000,"payload":{"cpu":{"usage":12.3},"memory":{"usage":50.0},"network":{"rxBps":20480,"txBps":4096}}}
```

反控命令示例：

```json
{"type":"command","version":1,"id":"cmd-001","command":"volume_up","args":{"step":5}}
```

响应示例：

```json
{"type":"ack","version":1,"id":"cmd-001","ok":true}
```

更完整的协议说明见 `host/docs/protocol.md`。

## FPS 采集

FPS 指标依赖 PresentMon。仓库已集成官方 x64 console 版本：

```text
tools/presentmon/PresentMon.exe
```

Host 启动后会优先从 `GamePilot.exe` 同目录查找 `PresentMon.exe`。如果未找到，也会尝试：

- 环境变量 `GAME_PILOT_PRESENTMON`
- 系统 `PATH`

如果 PresentMon 不可用，Device 会显示类似 `FPS: presentmon_missing`。如果前台程序没有产生可捕获帧，Device 会显示 `waiting_for_frames`。

## Device 显示页面

Device 端会自动轮播页面：

- `Core`：CPU、内存、磁盘使用率、网络与磁盘速度。
- `System`：主机名、用户名、系统版本、架构、运行时长。
- `Power / Audio`：电量、音量、前台窗口。
- `Processes`：Top 5 进程 CPU 占用。
- `Advanced`：Display、GPU、Thermal、FPS。

百分比和可量化指标会优先使用进度条展示；长文本会单行省略，避免屏幕堆叠。

## 常见问题

### Device 显示 `stale`

表示超过 3 秒没有收到新的 metrics。检查 host 是否运行、串口是否选对、通信是否启用。

### GPU、亮度或温度不可用

这些指标依赖 Windows 原生 API、PDH 或 WMI。不同硬件和驱动暴露程度不一样。无法获取时协议会发送：

```json
{"available":false,"reason":"not_supported"}
```

### FPS 不显示

确认：

- `PresentMon.exe` 位于 `GamePilot.exe` 同目录。
- 游戏窗口在前台。
- Host 设置中启用了 `Foreground game FPS (PresentMon)`。
- 某些游戏或权限场景可能需要以管理员权限运行 host。

### 烧录时 COM 口被占用

关闭 host，或暂停串口通信后再运行：

```powershell
idf.py -C device -p COM15 flash
```

## 开发验证

Host：

```powershell
cmake --build host\build --config Release
ctest --test-dir host\build --output-on-failure
```

Device：

```powershell
idf.py -C device build
```

## 本机构建脚本

仓库提供 PowerShell 脚本用于本机一键构建和收集产物：

```powershell
Copy-Item scripts\env.example.ps1 scripts\env.local.ps1
notepad scripts\env.local.ps1
powershell -ExecutionPolicy Bypass -File scripts\build-and-collect.ps1
```

本机环境文件 `scripts/env.local.ps1` 用于配置 Qt、MinGW、ESP-IDF、设备 COM 口和输出目录；该文件已被 `.gitignore` 忽略。示例文件 `scripts/env.example.ps1` 可提交共享。

常用命令：

```powershell
# 完整清理构建并收集
powershell -ExecutionPolicy Bypass -File scripts\build-and-collect.ps1 -Clean

# 只构建 host
powershell -ExecutionPolicy Bypass -File scripts\build.ps1 -SkipDevice

# 只构建 device
powershell -ExecutionPolicy Bypass -File scripts\build.ps1 -SkipHost

# 构建并烧录 device
powershell -ExecutionPolicy Bypass -File scripts\build.ps1 -SkipHost -FlashDevice

# 只烧录 device，默认会先构建
powershell -ExecutionPolicy Bypass -File scripts\flash-device.ps1

# 烧录现有固件并打开 monitor
powershell -ExecutionPolicy Bypass -File scripts\flash-device.ps1 -SkipBuild -Monitor

# 仅收集现有构建产物
powershell -ExecutionPolicy Bypass -File scripts\collect-artifacts.ps1
```

收集结果会生成在 `dist/game-pilot-<timestamp>/`：

```text
dist/game-pilot-<timestamp>/
  host/      GamePilot.exe、PresentMon、Qt runtime
  device/    app、bootloader、partition table、flash_args
  docs/      README 和协议文档
  manifest.txt
```

## License

本仓库目前未声明统一项目许可证。`tools/presentmon/` 下的 PresentMon 使用其上游许可证，许可证文本已随工具一并保留。