peterroe/magpie-usage-display

选用指南

AI 根据 README 整理 · 2026/10/20 19:46:42

使用方式

通过 PlatformIO 编译烧录固件，运行 macOS Python Companion 通过 BLE 连接开发板，支持触摸和按键操作。

查看 README 依据

``` 默认只访问本机 `http://127.0.0.1:3425`。可通过 `MAGPIE_URL` 环境变量或 `--magpie-url` 参数覆盖。 ## 1. 获取代码 ```bash git clone https://github.com/peterroe/magpie-usage-display.git cd magpie-usage-display ``` ## 2. 准备 PlatformIO 推荐在项目目录创建独立 Python 环境： ```bash python3 -m venv .pio-venv source .pio-venv/bin/activate python -m pip install --upgrade pip platformio ``` 确认使用的是项目环境： ```bash which pio pio --version ``` `which pio` 应优先显示项目中的 `.pio-venv/bin/pio`。 ## 3. 编译固件 ```bash pio run ``` 成功后固件位于： ```text .pio/build/esp32-s3-touch-amoled-216/firmware.bin ``` ## 4. 连接并烧录开发板 用 USB-C 数据线连接开发板，查看串口：

```bash ls /dev/cu.* ``` 找到类似 `/dev/cu.usbmodem11201` 的端口，然后上传： ```bash pio run -t upload --upload-port /dev/cu.usbmodem11201 ``` 请将端口替换为你的实际设备。 如果找不到端口或无法连接： 1. 拔下 USB-C。 2. 按住开发板左侧 `BOOT`。 3. 保持按住并重新插入 USB-C。 4. 等待约 2 秒后松开。 5. 重新运行 `ls /dev/cu.*` 和上传命令。 烧录成功后设备会自动重启，未连接 Companion 时显示 `OFFLINE`。 ## 5. 验证 Magpie 数据 确保 Magpie 正在运行，然后执行： ```bash ./companion/run.sh --once ``` 成功时会输出一行 BLE v4 JSON 快照。该命令只读取数据，不连接蓝牙。 ## 6. 启动 Companion ```bash ./companion/run.sh ``` 首次运行会自动创建 `companion/.venv` 并安装 `bleak`。macOS 询问蓝牙权限时 请选择允许。 ### 首次配对 只有尚未绑定的设备才会显示六位验证码： 1. 开发板显示六位数字。

2. 在 macOS 蓝牙配对框中输入相同数字。 3. 收到第一包数据后状态变为 `ONLINE`。 后续连接会复用绑定密钥，不再要求输入验证码。 需要换电脑或重新配对时，在设备正常运行状态下长按左侧 `BOOT` 约 3 秒。看到 `PAIRING CLEARED` 后设备会重启。不要在上电时按住 BOOT，否则会进入下载模式。 ## 7. 后台自动运行 先完成一次手动配对，再停止手动运行的 Companion： ```bash python3 companion/install_launch_agent.py ``` 卸载： ```bash python3 companion/install_launch_agent.py --uninstall ``` 日志位于： ```text ~/Library/Logs/MagpieUsageDisplay/companion.log ~/Library/Logs/MagpieUsageDisplay/companion.log.1 ``` LaunchAgent 进程可能需要在“系统设置 → 隐私与安全性 → 蓝牙”中单独授权。 ## 操作 面对屏幕、三个实体键位于顶部时： | 位置 | 按键 | 行为 | |---|---|---|

部署要求

需要 Waveshare ESP32-S3-Touch-AMOLED-2.16 开发板、支持数据传输的 USB-C 线、macOS、Python 3.9+、PlatformIO，以及已安装并正在运行的 Magpie。

查看 README 依据

- 设备快捷操作：聚焦 Magpie、立即刷新 Context 页面只展示 Magpie 公共网关 API 能提供的真实统计，不复制 macOS App 内部尚未公开的 Context 评分。 ## 硬件与系统要求 - [Waveshare ESP32-S3-Touch-AMOLED-2.16](https://www.waveshare.com/esp32-s3-touch-amoled-2.16.htm) - 支持数据传输的 USB-C 线 - macOS - Python 3.9+；构建 ESP32 固件推荐 Python 3.11 - 已安装并正在运行的 Magpie - PlatformIO 目前只验证了上述开发板和 macOS。 ## 工作原理 ```text Magpie http://127.0.0.1:3425 ├─ /v1/magpie/quotas ├─ /v1/magpie/usage └─ /v1/magpie/usage/requests │ ▼ macOS Python Companion │ 加密 BLE ▼ ESP32-S3 + LVGL + AMOLED

已知限制

Companion 仅支持 macOS，只验证了 Waveshare ESP32-S3-Touch-AMOLED-2.16 开发板，固件没有 OTA 升级需 USB 烧录。

查看 README 依据

按 `Control-C` 退出。烧录前需要先关闭串口监视器。 ## 开发与测试 ```bash python3 -m unittest discover -s companion/tests -v pio run ``` BLE v4 协议见 [docs/BLE_PROTOCOL.md](docs/BLE_PROTOCOL.md)。 ## 安全与隐私 - ESP32 不保存 Magpie 凭据、请求正文或会话内容 - BLE 状态与命令特征要求加密访问 - 设备只允许 `focus_magpie` 和 `refresh` 两个语义操作 - 不接受任意 shell 命令或 prompt 安全问题请参阅 [SECURITY.md](SECURITY.md)。 ## 限制 - Companion 当前仅支持 macOS - 只验证了 Waveshare ESP32-S3-Touch-AMOLED-2.16 - 固件没有 OTA，升级需要 USB 烧录 - Context 页面使用公共 API 聚合数据，不包含 Magpie App 内部评分 ## 许可证与商标 代码使用 [MIT License](LICENSE)。原项目版权和第三方字体声明保留在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。