AgentRing-EPD

English · 简体中文

AgentRing 电子墨水屏桌面副屏硬件固件 (EPD)
经典蓝牙 SPP / USB 串口双通道通讯 · 4.2寸三色墨水屏 · AI 配额色环常显监控

---

项目简介

agentRing-EPD 是 AgentRing 硬件生态中的电子墨水屏（E-Paper Display）桌面副屏固件。

它兼容复用 agentRing-Android 协议规范，通过 经典蓝牙 SPP (Serial Port Profile) 或 USB 串口 接收 Codex、Antigravity、Cursor 等 AI 编程助手的额度数据，并在 4.2 寸黑白红三色墨水屏上保持超低功耗常显。

核心特性

• 双通道数据接收 (BT SPP + USB Serial)：
  • 经典蓝牙 SPP：基于 RFCOMM (UUID 0x1101)，广播服务名 AgentRingDisplay，默认广播名 AgentRing-EPD-xx（构建期自动生成 2 位随机十六进制后缀，避免多设备环境同名冲突），支持 SSP (Simple Secure Pairing) 免 PIN 码无缝配对。
  • USB 串口调试：支持通过 USB CDC/UART（波特率 115200）直接推送换行符 \n 分隔的 JSON 数据流，便于电脑端有线连接或本地调试。
• 4.20 英寸 3 色屏（黑白红）深度适配：
  • 分辨率 400×300（驱动芯片 SSD1619 / GxEPD2_420c_Z96）。
  • 智能变化检测（Change Detection）：仅当配额数据发生变动时触发墨水屏全刷，杜绝不必要的 ~13s 频繁刷新。
• 纯色环极简四列布局 (Rings Only)：
  • 支持多达 4 个 AI Provider（Codex、Antigravity、Antigravity 3rd、Cursor）并列展示。
  • 外圈：纯黑（BLACK）主额度环，带圆角端点。
  • 内圈：纯红（RED）次额度环（双环 Provider），带圆角端点。
  • 未完成/用尽环轨：1px 细线描边 + 同色点散列填充（((x & 1) == 0 && (y & 1) == 0)）呈现平滑灰度质感，彻底消除空白缺口，保证额度用尽时的视觉辨识度。
• 引脚灵活定义：默认引脚映射与通用 ESP32 墨水屏驱动板兼容：

  #define EPD_CS     5
  #define EPD_DC     16
  #define EPD_RST    17
  #define EPD_BUSY   4

---

硬件连接

墨水屏引脚	ESP32 GPIO	说明
CS	GPIO 5	片选 (Chip Select)
DC	GPIO 16	数据 / 命令选择
RST	GPIO 17	复位信号
BUSY	GPIO 4	忙信号
SCK / CLK	GPIO 18	VSPI 时钟
DIN / MOSI	GPIO 23	VSPI 主机输出从机输入
VCC	3.3V	供电（严禁接 5V）
GND	GND	接地

---

编译与烧录

本项目基于 PlatformIO 构建。

1. 编译与上传

# 编译并烧录至 ESP32
pio run -e epd_420c_z96 -t upload

# 监控串口日志
pio device monitor -b 115200

2. 自定义蓝牙设备名称 (可选)

为了避免多台设备处于同一空间或多人办公时蓝牙名称混淆冲突，固件在构建时默认会自动生成带 2 位随机十六进制后缀的名称（如 AgentRing-EPD-3A、AgentRing-EPD-F2）。

如果你希望给设备指定固定或更有辨识度的专属名称（如 AgentRing-EPD-Desk），可在编译烧录前通过环境变量 AGENTRING_BT_NAME 自由指定：

# 临时指定设备名称进行编译与烧录
AGENTRING_BT_NAME="AgentRing-EPD-Desk" pio run -e epd_420c_z96 -t upload

# 或者在终端中导出环境变量
export AGENTRING_BT_NAME="AgentRing-EPD-Desk"
pio run -e epd_420c_z96 -t upload

注意：Mac 端 AgentRing 宿主程序会通过名称包含 AgentRing（不区分大小写）自动发现并连接设备，因此自定义名称时请务必保留 AgentRing- 或 AgentRing-EPD- 前缀（例如 AgentRing-EPD-Pro、AgentRing-EPD-01 等）。

3. 模拟数据推送测试

仓库内附带 Python 测试脚本 tools/test_sender.py，可通过 USB 串口向设备直接发送实时模拟数据：

# 发送 4-Provider 模拟数据进行屏幕刷新测试
python3 tools/test_sender.py --port /dev/cu.usbserial-140 --providers 4

---

目录结构

agentRing-EPD/
├── platformio.ini                    # PlatformIO 构建配置 (包含 GxEPD2, U8g2_for_Adafruit_GFX, ArduinoJson)
├── scripts/
│   └── pre_build.py                  # 构建预处理脚本
├── include/
│   ├── board_pins.h                  # 默认引脚定义 (CS:5, DC:16, RST:17, BUSY:4)
│   ├── display_config.h              # 屏幕规格配置
│   ├── model/
│   │   └── agent_ring_models.h       # 数据模型定义与变化检测
│   └── version.h                     # 固件版本号
├── src/
│   ├── main.cpp                      # 引导入口、主循环与双通道调度
│   ├── bt/
│   │   ├── bt_manager.h              # 经典蓝牙 SPP 管理器
│   │   └── bt_manager.cpp
│   ├── protocol/
│   │   ├── payload_parser.h          # JSON 数据流协议解析器 (兼容 Android 端)
│   │   └── payload_parser.cpp
│   └── display/
│       ├── display_manager.h         # 墨水屏管理器与环形渲染器
│       ├── display_manager.cpp
│       └── drivers/
│           ├── GxEPD2_420c_Z96.h     # 400x300 三色屏驱动
│           └── GxEPD2_420c_Z96.cpp
└── tools/
    └── test_sender.py                # USB 串口测试发送脚本

---

开源协议

本项目基于 MIT 许可证 开源。