# codex-touch-controller **Repository Path**: Bobby123456/codex-touch-controller ## Basic Information - **Project Name**: codex-touch-controller - **Description**: ESP32-P4 7 英寸触屏 Codex 控制器,支持 USB/BLE、板载音频、动态背景与额度同步。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-24 - **Last Updated**: 2026-08-28 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Codex Touch Controller 基于 **ESP32-P4-WIFI6-Touch-LCD-7B** 的 7 英寸触屏 Codex 控制器。项目在 ESP32-P4 上实现触控界面、Codex Micro 兼容输入、USB/BLE 传输、板载音频与动态背景;Windows 后台程序 `CodexBoardAudio` 负责自定义 BLE 音频桥接、电脑/板载麦克风切换、CLIProxyAPI 额度同步、电脑信息采集(硬件指标、网速、天气)和娱乐窗口控制。 > 本项目复现的是 Codex Micro 的功能与协议行为,并非 OpenAI 或 Work Louder 官方产品。 ## 背景资源预览 ![内置动态背景资源预览](components/codex_ui/assets/codex_background_preview.png) 该图片是内置动态背景资源的静态预览,实际设备界面会在背景上叠加控制器、状态、额度和设置页面。 ## 已实现功能 - 1024×600 LVGL 三页触控界面:控制页、额度页和电脑信息中心页。 - Agent、Action、编码器、编码器短按/长按和二维摇杆控制。 - 编码器左右拖动映射 `ENC_CW` / `ENC_CC`,手势互斥并阻止误翻页。 - USB Vendor HID 与 BLE HID 传输仲裁。 - ESP32-C6 作为 ESP32-P4 的无线协处理器。 - 板载麦克风采集,经自定义 BLE GATT 音频协议发送到电脑。 - 电脑默认麦克风与板载麦克风可在屏幕上切换。 - 板载扬声器开关和 0~100 音量调节。 - 动态视频背景与独立循环音乐,使用 PPA/硬件显示流水线合成。 - CLIProxyAPI 多账号、额度、Fast 模式和重置确认状态同步。 - 电脑信息中心:CPU/GPU 使用率与温度、内存占用、活动网卡实时网速、时间日期和城市天气,由电脑采集后经 BLE 同步到板端显示。 - 抖音、哔哩哔哩一键启动/隐藏/恢复,老板键一键隐藏娱乐窗口、静音并切换到 Trae CN。 - `CodexBoardAudio` 后台托盘、自动重连和“登录时、最高权限”计划任务静默自启。 ## 系统组成 | 模块 | 职责 | | --- | --- | | ESP32-P4 | UI、业务逻辑、音频采集/播放、USB Device、BLE Host 和状态管理 | | ESP32-C6-MINI-1 | 通过 ESP-Hosted/Hosted HCI 为 P4 提供蓝牙控制器能力 | | 7 英寸触摸屏 | 控制器、额度监控、电脑信息中心、设置、麦克风和扬声器操作 | | `CodexBoardAudio` | Windows BLE 音频桥接、虚拟麦克风输出、CPA 状态同步、电脑信息采集和娱乐窗口控制 | | VB-CABLE | 将桥接程序输出注册为 Windows 可选择的录音设备 | | CLIProxyAPI | 提供账号配置、额度查询和可用的账号管理操作 | 板载麦克风使用的是项目自定义 BLE GATT 音频协议,不会由 Windows 直接识别为标准蓝牙麦克风,因此使用板载语音时必须运行 `CodexBoardAudio` 并安装 VB-CABLE。 ## 工程结构 ```text codex-touch-controller/ ├─ components/ │ ├─ codex_audio/ # 板载麦克风、音频缓冲、编码和处理 │ ├─ codex_ble/ # BLE HID、生命周期和自定义 BLE 音频 │ ├─ codex_core/ # 协议、输入映射、状态、RPC、桌面快照和传输仲裁 │ ├─ codex_frame_broker/ # 显示帧所有权与交换 │ ├─ codex_media/ # 动态背景、媒体包和扬声器策略 │ ├─ codex_realtime/ # 实时性能统计 │ ├─ codex_ui/ # LVGL 页面、触控、手势、中文字库和 PPA 合成 │ └─ codex_usb/ # TinyUSB Vendor HID ├─ host/ │ └─ ble-virtual-microphone/ │ ├─ CodexBleAudio.App/ # CodexBoardAudio 托盘程序:音频、电脑信息采集和娱乐窗口控制 │ └─ CodexBleAudio.Core/# 音频、协议、路由、桌面快照和 CPA 核心逻辑 ├─ main/ # 组件装配、任务和应用生命周期 ├─ tools/ # 字体和媒体包生成工具 ├─ docs/ # 架构和功能设计记录 ├─ partitions.csv # 32 MB Flash 分区表 ├─ sdkconfig # 当前已验证的 ESP32-P4 配置 └─ sdkconfig.defaults # ESP-IDF 默认配置补充 ``` `managed_components/` 由 ESP-IDF Component Manager 根据 `dependencies.lock` 恢复,不纳入 Git。 ## 环境要求 ### 固件 - ESP-IDF 5.5.x,本机已验证版本为 5.5.2。 - Windows PowerShell 或 ESP-IDF PowerShell。 - ESP32-P4-WIFI6-Touch-LCD-7B。 - 可传输数据的 USB 线。 - 完整烧录需要 32 MB Flash,并会写入独立的 `media` 分区。 ### Windows 后台程序 - Windows 10 2004 或更新版本,推荐 Windows 11。 - .NET 8 SDK;仅运行 framework-dependent 发布包时至少需要 .NET 8 Desktop Runtime。 - Windows 蓝牙功能可用,并允许应用访问 BLE 设备。 - [VB-CABLE](https://vb-audio.com/Cable/);程序会查找名为 `CABLE Input` 的播放设备。 - 如需额度同步,需要可用的 CLIProxyAPI `config.yaml` 和账号凭据目录。 - 如需电脑信息中心,允许 Windows 定位权限并保持联网(天气查询使用 Open-Meteo)。 ## 构建与烧录固件 ### 1. 打开 ESP-IDF 环境 在已经激活 ESP-IDF 5.5 的 PowerShell 中进入工程: ```powershell cd D:\path\to\codex-touch-controller ``` 本机 ESP-IDF 安装在 `D:\esp-if\v5.5.2\esp-idf` 时,也可以执行: ```powershell & D:\esp-if\v5.5.2\esp-idf\export.ps1 ``` ### 2. 构建 ```powershell idf.py build ``` 首次构建会根据 `dependencies.lock` 下载 `managed_components/`。 ### 3. 查找串口 ```powershell Get-CimInstance Win32_SerialPort | Select-Object DeviceID, Description ``` 串口可能随 USB 接口变化,不要长期写死。本机开发时曾使用 `COM33`,下方统一使用 `COMx` 表示实际端口。 ### 4. 完整烧录 ```powershell idf.py -p COMx flash ``` 完整 `flash` 会同时写入: - bootloader; - 分区表; - `codex_touch_controller.bin`; - `components/codex_media/assets/summer_background.cdxm` 媒体分区。 只更新应用程序且媒体包没有变化时可使用: ```powershell idf.py -p COMx app-flash ``` ### 5. 查看串口日志 ```powershell idf.py -p COMx monitor ``` 按 `Ctrl+]` 退出监视器。 ## 构建与运行 CodexBoardAudio ### 1. 安装依赖 先安装 .NET 8 SDK 和 VB-CABLE。安装 VB-CABLE 后,Windows 播放设备中应能看到 `CABLE Input`,录音设备中应能看到 `CABLE Output`。 ### 2. 构建 ```powershell cd host\ble-virtual-microphone\CodexBleAudio.App dotnet restore dotnet build -c Release ``` ### 3. 直接运行 ```powershell dotnet run -c Release ``` 程序启动后常驻系统托盘,同一时间只允许一个实例。托盘菜单提供: - 当前连接、麦克风来源和电脑信息同步状态; - 立即重连; - 立即刷新电脑信息; - 恢复全部隐藏窗口; - 配置抖音、哔哩哔哩和 Trae CN 程序路径; - 管理员静默开机自启; - 退出。 “管理员静默开机自启”通过 Windows 计划任务实现:确认 UAC 后创建“登录时、最高权限”计划任务,并清理旧版 Run 注册表自启项。日志写入: ```text %LOCALAPPDATA%\CodexBoardAudio\bridge.log ``` ### 4. 发布可执行目录 ```powershell dotnet publish -c Release -r win-x64 --self-contained false -o publish ``` 然后运行: ```powershell .\publish\CodexBoardAudio.exe ``` `publish/`、`bin/` 和 `obj/` 是可重新生成的中间产物,不纳入 Git。 ## 配置 CLIProxyAPI 额度同步 `CodexBoardAudio` 会读取 CLIProxyAPI 的: - `config.yaml`; - `auth-dir` 指向的账号凭据目录; - `host` 和 `port`; - 最多六个可识别账号的额度状态。 推荐通过用户级环境变量明确指定配置文件,避免依赖本机目录结构: ```powershell [Environment]::SetEnvironmentVariable( "CODEX_BOARD_CPA_CONFIG", "D:\path\to\CLIProxyAPI\config.yaml", "User" ) ``` 设置后退出并重新启动 `CodexBoardAudio`。程序连接板子后会立即同步一次,此后每分钟刷新一次。 板端可执行的账号启停、Fast 模式和额度重置会由电脑端完成。额度重置使用 60 秒有效的二次确认,账号凭据和访问令牌不会发送到板子。 ## 电脑信息中心与娱乐控制 第三页“电脑信息中心”由电脑端统一采集、板端纯显示: - CPU/GPU 使用率与温度:`CodexBoardAudio` 通过 LibreHardwareMonitor 读取,约 2 秒刷新;读不到的传感器显示“不可用”,不伪造数值。 - 内存:显示已用容量、总容量和百分比。 - 网速:取活动物理网卡的实时上传/下载速率,排除回环和虚拟隧道接口。 - 时间日期:电脑每分钟同步一次,板端按本地单调时钟递增。 - 天气:Windows 定位获取城市(经纬度只留在电脑端,不上板),经 Open-Meteo 查询后按固定中文文案显示;定位关闭或服务失败时显示对应提示并保留最后一次成功数据。 快照以 JSON 协议(`v.oai.desktop_snapshot`)经自定义 BLE 桥接链路发送,板端操作以 `v.oai.desktop_command` 回传。这些命令不经过 Codex 官方 HID 通道。 第三页提供三个控制入口: - **抖音 / 哔哩哔哩**:未运行时自动发现路径并启动;可见时真正隐藏窗口(`ShowWindow(SW_HIDE)`,不结束进程)并静音其音频会话;再次点击恢复窗口和原音量。自动发现失败时可在托盘菜单手动指定路径。 - **老板键**:第一次按下隐藏全部娱乐窗口、静音并启动或切换到 Trae CN;再次按下恢复本次被隐藏的窗口和音量。托盘菜单的“恢复全部隐藏窗口”可兜底恢复。 `CodexBoardAudio` 以管理员权限运行时才能隐藏/恢复窗口和配置计划任务;启动普通桌面应用(抖音、B站、Trae CN)时通过 Explorer Shell 降权,避免它们继承管理员权限。 ## 麦克风与语音 ### 使用电脑麦克风 1. 在板端选择“电脑麦克风”。 2. `CodexBoardAudio` 读取 Windows 默认录音设备。 3. 音频写入 VB-CABLE 的 `CABLE Input`。 4. 在 Codex 客户端中选择 `CABLE Output` 作为麦克风。 切换 Windows 默认麦克风后,建议重新启动 `CodexBoardAudio`,让程序重新选择默认录音设备。 ### 使用板载麦克风 1. 确保板端蓝牙已开启并已与 Windows 配对。 2. 保持 `CodexBoardAudio` 在后台运行。 3. 在板端选择“板载麦克风”。 4. 板端采集音频并通过自定义 BLE GATT 发送给桥接程序。 5. 桥接程序解码后写入 VB-CABLE。 6. Codex 客户端继续使用 `CABLE Output`。 无论选择电脑还是板载麦克风,Codex 客户端都使用同一个 `CABLE Output`,切换来源时无需反复修改客户端录音设备。 ## USB 与蓝牙 - USB Vendor HID 需要连接到支持 USB Device/OTG 的板端接口,并使用数据线连接电脑。 - BLE 由板载 ESP32-C6 提供控制器能力,P4 运行 Host 和业务逻辑。 - USB 成功枚举时业务传输优先使用 USB,避免 USB 与 BLE 重复发送控制事件。 - USB 不可用时可以继续使用 BLE 控制和 `CodexBoardAudio`。 - 屏幕上的蓝牙开关会真实启停 BLE 生命周期;关闭后音频桥接和 BLE 控制都会断开。 - 板载音频是自定义 BLE 服务,不是 Windows 标准 HFP 或 LE Audio 麦克风。 ## 媒体包 动态背景和循环音乐存放在独立 `media` 分区,当前资源为: ```text components/codex_media/assets/summer_background.cdxm ``` 重新生成媒体包需要 `ffmpeg` 和 `ffprobe`: ```powershell .\tools\build_summer_media.ps1 ` -SourceVideo "D:\path\to\background.mp4" ` -AudioSource "D:\path\to\music.mp3" ` -OutputFile ".\components\codex_media\assets\summer_background.cdxm" ` -FrameRate 30 ` -DurationSeconds 10 ` -JpegQuality 14 ` -TransparencyPercent 0 ``` 生成完成后使用完整 `idf.py -p COMx flash` 更新媒体分区。 ## 核心数据流 ```text 触摸/旋钮/摇杆 │ ▼ codex_ui ──► codex_core ──► USB Vendor HID / BLE HID ──► Codex 客户端 │ ├──► codex_media ──► LCD + 板载扬声器 │ └──► codex_audio ──► 自定义 BLE Audio ──► CodexBoardAudio │ CLIProxyAPI ──► CodexBoardAudio ──► 额度状态/控制 ────┤ │ 硬件/网速/天气 ─► CodexBoardAudio ─► 桌面快照 ────────┤ (板端命令反向回传) ▼ VB-CABLE / Codex ``` UI、媒体和通信通过队列、帧代理与状态快照解耦。视频帧与 UI 分层后由 PPA/显示流水线完成合成,避免 BLE 状态变化或启动阶段引起整页闪烁。 ## 常见问题 ### CodexBoardAudio 显示“缺少 VB-CABLE” 确认 Windows 播放设备中存在 `CABLE Input`。安装或重装 VB-CABLE 后重新启动程序。 ### 板端已连接,但额度不显示 1. 检查 `CODEX_BOARD_CPA_CONFIG` 是否指向真实的 `config.yaml`。 2. 检查 CLIProxyAPI 是否正在运行。 3. 检查 `config.yaml` 中的 `auth-dir`。 4. 查看 `%LOCALAPPDATA%\CodexBoardAudio\bridge.log`。 5. 在托盘菜单中点击“立即重连”。 ### 电脑信息中心不更新 1. 确认 `CodexBoardAudio` 正在运行且 BLE 已连接。 2. 托盘菜单点击“立即刷新电脑信息”。 3. 硬件指标读不到时对应项会显示“不可用”,属正常降级。 4. 查看桥接日志 `%LOCALAPPDATA%\CodexBoardAudio\bridge.log`。 ### 天气显示“暂不可用”或提示开启定位 1. 确认 Windows 定位服务已开启,并允许应用访问位置。 2. 确认电脑可访问 Open-Meteo 天气服务。 3. 天气恢复后会自动刷新;过期数据会保留显示并标记。 ### 抖音/哔哩哔哩/老板键没有反应 1. 确认 `CodexBoardAudio` 以管理员权限运行,窗口隐藏/恢复需要管理员权限。 2. 自动发现路径失败时,在托盘菜单“配置程序路径”中手动选择程序。 3. 窗口被隐藏后可在托盘菜单点击“恢复全部隐藏窗口”兜底。 ### 板载麦克风无声音 1. 确认板端选择的是“板载麦克风”。 2. 确认 `CodexBoardAudio` 托盘状态为“板载麦克风”。 3. 确认 Codex 客户端录音设备为 `CABLE Output`。 4. 确认蓝牙未关闭且 Windows 配对记录正常。 5. 查看桥接日志中是否存在 BLE 音频或 VB-CABLE 错误。 ### 电脑麦克风切换后仍使用旧设备 程序在启动录音时选择 Windows 默认麦克风。退出 `CodexBoardAudio`,修改 Windows 默认录音设备后重新启动。 ### `idf.py build` 找不到组件 确认网络可用、ESP-IDF 版本为 5.5.x,并保留 `dependencies.lock`。删除损坏的 `managed_components/` 后重新执行 `idf.py build`。 ### USB 没有被电脑枚举 确认连接的是支持 Device/OTG 的板端接口,并更换确认支持数据传输的 USB 线。普通供电口或 USB 转串口不能替代 USB Device 接口。 ## 安全与边界 - 板端只保存必要设置和脱敏状态,不保存 OAuth Token、完整账号 ID 或 CLIProxyAPI 管理信息。 - 电脑定位经纬度只留在 `CodexBoardAudio` 内存中,不发送到板子、不写入日志;板端只收到城市名和天气数据。 - 账号凭据修改由 `CodexBoardAudio` 在电脑本地完成,并使用 UTF-8 无 BOM 原子写入。 - 额度重置必须经过板端二次确认。 - 自定义 BLE 音频依赖电脑端桥接,无法只修改板端就成为 Windows 标准蓝牙麦克风。 - 当前工程主要面向 Windows;电脑端程序使用 WinRT BLE、Windows Forms 和 NAudio。 ## 设计文档 详细设计记录位于 [`docs/`](docs/),主要包括: - 触控与显示实时架构; - PPA 视频/UI 合成; - 启动屏闪修复; - 官方控件和旋钮手势; - BLE 虚拟麦克风; - CPA 额度、字体和音量同步; - 动态背景和扬声器策略; - 电脑信息中心与老板键、娱乐应用启动位置修复、常见城市字库覆盖(`docs/superpowers/specs/`)。 从 [`docs/2026-08-22-codex-touch-controller-design.md`](docs/2026-08-22-codex-touch-controller-design.md) 可以开始了解整体协议与模块划分。