Codex Micro StopWatch 是一套面向 M5Stack StopWatch 和 Codex 桌面端 的开源固件与 macOS Bridge。它把圆形 AMOLED、触摸屏、两颗实体键、麦克风、IMU 和振动马达组合成一块随手可用的 Codex 控制面板：无需在多个窗口间寻找按钮，就能查看任务状态、切换会话、批准或拒绝请求、发送消息、控制推理强度、导航对话并进行语音输入。
这不是 OpenAI、M5Stack 或 Work Louder 的官方产品；它是社区项目。Codex、OpenAI、M5Stack、StopWatch、Work Louder 及相关名称和标识均属于各自权利人。
 |
 |
| 六会话状态面板 | 推理强度触控旋钮 |
照片中的显示方向取决于设备摆放方式；固件界面与两颗侧键的相对位置保持一致。
首页的六个环形触摸键对应 Codex 的六个 Agent 槽位。每个槽位会跟随桌面端显示当前状态：
- 空闲：白色
- 思考中：蓝色动态状态
- 已完成 / 有未读结果：绿色
- 等待批准或回复：橙色
- 错误：红色
- 空槽位：低亮度占位状态
直接点按某个圆键即可切换对应会话；快速双击同一会话还可将 Codex 带到前台。
按一下实体 A 键进入快捷操作页，可直接使用六个常用命令：
| 位置 | 功能 | 用途 |
|---|---|---|
| 12 点 | SEND | 发送当前输入框内容 |
| 2 点 | SPLIT | 从当前对话继续到新对话 |
| 4 点 | FAST | 切换 Fast 模式 |
| 6 点 | MIC | 按住说话，松开结束 |
| 8 点 | APPROVE | 批准当前请求 |
| 10 点 | DECLINE | 拒绝当前请求 |
两页的触摸键与实体键采用一致的按下/抬起反馈，连续操作仍能保持清晰、紧凑的触感。
中央区域会根据页面和 Codex 当前的旋钮设置自动承担不同功能：
- 首页轻点：发送输入框内容。
- 首页拖动：作为径向控制区使用。
- 首页长按：开始语音输入，松手结束。
- 快捷页 + Reasoning 模式：连续拖动调节
LOW / MED / HIGH / XHIGH / ULTRA五档推理强度。 - 快捷页 + Composer Navigation 模式：旋转移动输入焦点，长按确认。
- 快捷页 + Conversation Scroll 模式：作为轻量滚轮滚动对话。
- 快捷页 + Custom 模式：遵循 Codex 当前的自定义旋钮映射。
旋钮模式以 Mac 上 Codex 的设置为准，设备自动跟随，不会私自改写桌面端设置。
- 会话键、功能键、实体键、确认、拒绝、错误和完成事件都有可辨识的反馈。
- 推理强度跨档时有清晰刻度感；松手后的 UI 回弹只附带一次很轻的尾部触感，不会误读成第二次确认。
- 长时间滚动采用轻量离散脉冲，避免连续旋转变成持续嗡鸣。
- 可随时关闭震动，设置会保存在设备中。
- 优先使用 Codex 原生麦克风路径。
- 当原生路径不可用时，Bridge 可以接收 StopWatch 麦克风音频，调用 macOS 语音识别，并把文字填入 Codex 输入框。
- 支持普通话和英语识别。
- 识别结果只填入输入框，不会自动发送；最终发送仍由你确认。
- Bridge 会自动重连，并同步推理强度与 Codex 当前旋钮模式。
- 长按 A 键：将 Codex 窗口带到前台；Bridge 不可用时会回退到原生会话唤醒方式。
- 亮屏且 Bridge 在线时连续摇动设备：请求清空当前 Codex 输入框。只有 Codex 位于前台并能验证编辑焦点时才会执行，避免误删其他窗口内容。
| 无操作时间 | 状态 | 行为 |
|---|---|---|
| 1 分钟 | 变暗 | 降低 AMOLED 亮度 |
| 3 分钟 | 灭屏 | 关闭显示，降低运行功耗，保留 BLE 与触摸唤醒 |
| 10 分钟 | 连接待机 | 进一步关闭空闲音频资源，继续保留 BLE 与触摸 |
- 灭屏后的第一次触摸只负责唤醒，不会误触发命令。
- 插入外部电源且屏幕点亮时，绿色状态灯慢闪；拔线、灭屏和连接待机时熄灭。
- StopWatch 的状态灯是单色绿色 LED，无法按电量改变颜色。
| 项目 | 要求 |
|---|---|
| 开发板 | M5Stack StopWatch（SKU C152） |
| 芯片 | ESP32-S3R8 |
| 屏幕 | 1.75 英寸圆形 AMOLED 触摸屏 |
| 存储 | 16 MB Flash、8 MB PSRAM |
| 设备功能 | 两颗可编程按键、振动马达、麦克风、扬声器、BMI270 IMU、450 mAh 电池 |
| 固件工具 | PlatformIO Core 或 VS Code 的 PlatformIO IDE |
| 桌面端 | Codex 桌面端 |
| 可选 Bridge | macOS 13 或更高版本；完整体验建议使用当前版本 Codex |
固件直接使用 StopWatch 的显示、触摸、电源、音频、马达和传感器布局，不支持仅仅因为同为 ESP32-S3 就刷到 CoreS3、Dial、Core2、Cardputer、Atom、普通 ESP32-S3 开发板或其他 M5Stack 设备。移植到其他硬件需要重新适配。
官方硬件资料：M5Stack StopWatch 文档。
- 会话键、快捷命令、发送和基本状态显示依赖 Codex 的 Codex Micro 支持。
- 设备麦克风回退、摇动清空、精确推理强度回读、窗口唤醒和旋钮模式同步需要 macOS Bridge。
- Bridge 目前只面向 macOS；Windows 和 Linux 尚未提供 Bridge。
- Codex 桌面端更新可能改变本地状态或辅助功能行为；若某项集成功能失效，请先查看仓库 Issues。
| 操作 | A 键 | B 键 |
|---|---|---|
| 单击 | 在“会话页 / 快捷页”之间切换 | 发送当前输入框内容 |
| 双击 | 开启或关闭声音提示 | 开启或关闭震动反馈 |
| 长按 | 将 Codex 带到前台 | 按住说话，松开结束 |
单击需要等待约半秒来排除双击，因此页面切换或发送会在双击判定窗口结束后执行。B 键发送只保留按下时的触感，不会在延迟发送时再次反振。
- 查看六个槽位颜色，判断各会话当前状态。
- 点按槽位，切换到对应会话。
- 快速双击同一个槽位，将 Codex 带到前台。
- 轻点中央区域，发送当前输入框。
- 在中央区域拖动，使用径向控制。
- 长按中央区域进行语音输入，松手结束。
- 单击 A 键进入快捷页。
- 点按外围六个快捷键执行对应命令。
- 在中央旋钮上沿圆周拖动，控制 Codex 当前设置的旋钮功能。
- Reasoning 模式下，跨过档位时预览目标，松手后提交目标。
- Composer Navigation 模式下，长按中央旋钮可确认当前焦点。
- 再次单击 A 键返回会话页。
- 在 Codex 中打开目标对话并确保输入框可用。
- 长按 B 键、长按首页中央区域，或按住快捷页的 MIC。
- 看到录音动画后开始说话。
- 松开后等待识别结果写入输入框。
- 检查文字，确认无误后再按 B、轻点首页中央区域或按 SEND。
如果 Codex 原生语音通道在线，设备会优先使用它；否则在 Bridge 在线时自动使用 StopWatch 麦克风回退。
- 任何实体键或触摸都会刷新待机计时。
- 灭屏后，第一次触摸仅唤醒屏幕；松手后再点一次才会执行命令。
- 短按电源键可开机/复位；按 M5Stack 官方说明，快速双击电源键可关机。
- M5Stack StopWatch（C152）。
- 支持数据传输的 USB-C 线。
- 安装并登录 Codex 桌面端。
- 安装 Git 与 PlatformIO Core。
- 如需 Bridge 功能，准备一台 macOS 13+ 的 Mac，安装 Xcode Command Line Tools，并允许蓝牙、语音识别和辅助功能权限。
git clone https://github.com/huaxx-lab/codex-micro-stopwatch.git
cd codex-micro-stopwatch不想自行编译时，可直接打开 GitHub Releases 下载：
codex-micro-stopwatch-*-full.bin：完整合并固件，写入地址为0x0。codex-micro-stopwatch-*-firmware.zip：完整固件、分段镜像、刷写说明与许可证。Codex-Micro-Bridge-*-macOS-universal.zip：适用于 Apple Silicon 与 Intel Mac 的 Bridge。SHA256SUMS.txt：下载文件的 SHA-256 校验值。
Release 页面提供中英文安装说明。请只从本仓库 Release 下载，并在需要时使用校验文件确认完整性。
使用 Homebrew：
brew install platformio也可以按照 PlatformIO Core 官方安装说明 安装。
确认安装成功：
pio --version- 用 USB-C 数据线连接 StopWatch 与电脑。
- 长按电源键约 2 秒。
- 看到绿色 LED 亮起后松开。
- 查看串口：
pio device listmacOS 常见形式是 /dev/cu.usbmodem...，不同电脑上的数字会不同。Linux 通常是 /dev/ttyACM... 或 /dev/ttyUSB...；Windows 通常显示为 COM...。
pio run -e m5stack-stopwatch首次构建会下载已固定版本的依赖，需要联网。
PlatformIO 能自动识别唯一串口时：
pio run -e m5stack-stopwatch -t upload如果电脑上有多个串口，请显式指定：
pio run -e m5stack-stopwatch -t upload --upload-port /dev/cu.usbmodemXXXX把示例端口替换成 pio device list 显示的实际端口。上传结束出现校验成功并自动复位后即可拔线使用。
pio device monitor -b 115200 -p /dev/cu.usbmodemXXXX退出串口监视器通常使用 Ctrl+C。
找不到串口
- 确认使用的是数据线，不是仅充电线。
- 重新执行下载模式步骤：连接 USB-C，长按电源键约 2 秒，绿灯亮后松开。
- 换一个 USB 端口或数据线，再运行
pio device list。 - 关闭可能占用串口的监视器、Arduino IDE 或其他刷机工具。
上传过程中断
重新进入下载模式，再用 --upload-port 显式指定端口。不要在写入期间拔线。
固件已上传但 Codex 没有连接
- 确认电脑蓝牙已打开。
- 等待系统完成首次配对与设备枚举。
- 重新启动 Codex，或让 StopWatch 重新开机。
- 如果之前配对过其他固件版本，可在系统蓝牙设置中移除旧的
Codex Micro后重新连接。
Bridge 是一个常驻菜单栏的轻量应用。它负责设备麦克风回退、窗口唤醒、摇动清空、推理强度回读和旋钮模式同步；不安装 Bridge 时，原生会话键与快捷命令仍可使用。
Bridge 需要 Apple 的 Swift 编译工具。尚未安装 Xcode Command Line Tools 时先执行：
xcode-select --install按系统窗口完成安装后，在仓库根目录执行：
zsh mac-companion/build.sh默认安装位置：
~/Applications/Codex Micro Bridge.app
脚本使用 Xcode Command Line Tools 提供的 Swift 工具链，生成本地 ad-hoc 签名应用；它不是经过 Apple 公证的发行包。
open "$HOME/Applications/Codex Micro Bridge.app"菜单栏会出现波形麦克风图标。首次运行请按系统提示授予：
| 权限 | 用途 |
|---|---|
| 蓝牙 | 与 StopWatch 的附加 BLE 服务通信 |
| 语音识别 | 把 StopWatch 麦克风音频转换为文字 |
| 辅助功能 | 激活 Codex、填入文字并安全清空当前输入框 |
如果没有弹出辅助功能提示，可从 Bridge 菜单选择 “授予辅助功能权限”，或前往：
系统设置 → 隐私与安全性 → 辅助功能
开启 Codex Micro Bridge 后，退出并重新打开 Bridge。
首次切换到这个公开版 Bundle Identifier 时，macOS 可能会把它视为新的辅助功能客户端，需要重新授权一次。
- 查看当前连接或识别状态。
- 选择“重新连接”。
- 切换普通话或英语识别。
- 重新请求辅助功能权限。
- 退出 Bridge。
拉取新版本后重新执行：
git pull
zsh mac-companion/build.sh脚本会在临时目录构建完成后替换已安装应用。更新后重新打开即可。
在 macOS 中打开：
系统设置 → 通用 → 登录项
点击 +，选择 ~/Applications/Codex Micro Bridge.app。
先从菜单栏退出 Bridge，然后删除：
rm -rf "$HOME/Applications/Codex Micro Bridge.app"
rm -f "$HOME/Library/Logs/CodexMicroBridge.log"如不再使用，也可以在系统设置中移除对应的蓝牙、语音识别和辅助功能权限。
- 固件和 Bridge 都在本地运行，没有项目自建的云服务或遥测后台。
- Bridge 会读取 Codex 本地配置与状态，用于同步当前旋钮模式、当前对话和推理强度；不会修改旋钮配置文件。
- 语音识别优先请求 macOS 支持的设备端识别。实际是否完全离线取决于 macOS、语言包和系统可用性。
- 识别文本只在菜单栏短暂显示并填入 Codex，不写入 Bridge 日志。
- Bridge 的诊断日志位于
~/Library/Logs/CodexMicroBridge.log，有大小上限，不记录语音转写正文。 - 辅助功能权限仅用于 Codex 窗口激活、文本填入和经验证的输入框清空。
- 公开仓库不包含编译后的 Bridge 应用、私钥、证书、个人配置、语音数据或本机日志。
运行不需要硬件的完整契约测试：
zsh tests/run.sh构建生产固件：
pio run -e m5stack-stopwatch构建带硬件验收入口的测试固件：
pio run -e m5stack-stopwatch-test硬件验收脚本面向开发调试，需要官方设备工具包以及明确的串口环境变量，不是普通用户安装所必需。
.
├── assets/ README 图片
├── mac-companion/ macOS 菜单栏 Bridge 与测试
├── src/ StopWatch 固件
├── tests/ 设备、桌面映射与安全契约测试
├── partitions.csv ESP32-S3 Flash 分区
└── platformio.ini PlatformIO 构建配置
- 仅完整支持 M5Stack StopWatch C152。
- Bridge 目前仅支持 macOS。
- 状态灯为单色绿色，无法显示多种充电颜色。
- 为保持 BLE 会话，连接待机不会进入会断开 BLE 的深度睡眠。
- Codex 桌面端不是本项目的一部分，其更新可能改变本项目依赖的集成行为。
- macOS Bridge 使用本地 ad-hoc 签名，不是公证发行包；适合从源码自行构建。
- 本项目不包含 OpenAI 服务访问权限；你仍需要自行安装、登录并获得可用的 Codex 访问资格。
欢迎提交 Issue 和 Pull Request。报告问题时请尽量包含：
- StopWatch 固件提交版本。
- macOS 与 Codex 版本。
- 是否安装 Bridge。
- 可以复现问题的具体操作顺序。
- 与问题相关的串口日志或 Bridge 状态；提交前请先删除个人路径、对话内容、令牌和其他隐私信息。
不要在 Issue 中粘贴 GitHub Token、API Key、Cookie、完整 Codex 对话、语音内容或其他凭据。
本项目使用 MIT License 发布。
感谢：
- M5Stack StopWatch 提供圆形 AMOLED、触摸、音频、IMU 和马达硬件平台。
- M5Unified、M5GFX、M5PM1、M5IOE1 与 ArduinoJson 提供基础软件支持。
- freemicro 与 codex-micro-app 的公开研究帮助社区理解 Codex Micro 的设备能力。
- OpenAI Codex 提供 Codex 工具与相关生态。
由 huaxx-lab 制作。
如果项目对你有帮助，欢迎 ⭐ Star、反馈体验或参与改进。