# M5Renderer

**Repository Path**: genvex/m5-renderer

## Basic Information

- **Project Name**: M5Renderer
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-01
- **Last Updated**: 2026-09-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# M5Paper EPUB Reader

给 M5Paper（ESP32-D0WDQ6-V3 + IT8951E 540×960 墨水屏 + GT911 触摸）自写的开源 EPUB 阅读器固件。

基于 **M5Unified + M5GFX**（M5Stack 官方驱动）+ 移植 **CrossPoint Reader** 的 EPUB 解析引擎。

> 作者: genvex
> 创建: 2026-08-30
> 许可证: MIT
> 状态: **M10 完成**（Activity 架构 + DP 断行算法 PASS）

## 为什么自写

- KOReader 官方不支持 M5Paper（不在官方支持列表）
- CrossPoint Reader 只支持 Xteink X3/X4（硬件完全不同）
- M5Paper 有 520KB SRAM + **8MB PSRAM**，比 Xteink（380KB 无 PSRAM）宽松太多
- 可复用 CrossPoint 成熟的 EPUB 解析代码（36K 行 C++）
- M5Unified 提供统一 API（显示/触摸/按键/音频/传感器）

## 硬件规格

| 项 | M5Paper |
|---|---|
| SoC | ESP32-D0WDQ6-V3（双核 LX6 240MHz） |
| SRAM | 520KB |
| **PSRAM** | **8MB Quad** |
| Flash | 16MB |
| 墨水屏 | IT8951E 540×960（4.7"） |
| 触摸 | GT911 电容触摸 |
| 按键 | 旋转拨号 ×3（BtnA/BtnB/BtnC） |
| RTC | BM8563 |

## 技术栈

- **框架**: Arduino for ESP32（PlatformIO）
- **UI/驱动**: M5Unified 0.2.21 + M5GFX 0.2.28（M5Stack 官方）
- **EPUB 解析**: 移植自 CrossPoint Reader（lib/Epub 36K 行）
- **字体**: CrossPoint EpdFont（138K 行，CJK fallback）
- **JSON**: ArduinoJson 7.4.3

## 开发环境

```bash
# 安装 PlatformIO CLI
pip install platformio

# 拉库 + 编译
cd m5paper-epub-reader/
pio run -e m5paper

# 烧录 (需要 M5Paper USB 连接)
pio run -t upload -e m5paper

# 串口监视 (115200)
pio device monitor -e m5paper
```

## 项目结构

```
m5paper-epub-reader/
├── .comet/changes/m5paper-epub-reader/intent.md   # 关卡 B 设计先行文档
├── .gitignore
├── platformio.ini                                  # PlatformIO 配置
├── src/
│   └── main.cpp                                    # M1 Hello World (260 行)
└── README.md
```

## 里程碑

| 阶段 | 内容 | 工期 | 状态 |
|---|---|---|---|
| **M1** | 环境搭建 + Hello World | 2 天 | ✅ **DONE** |
| M2 | EPUB 解析移植（CrossPoint lib/Epub） | 3 天 | ✅ **DONE** |
| M3 | EpdFont 集成 + 渲染 | 1 周 | ✅ **DONE** |
| M4 | 翻页 + 目录 + 触摸 + 书签 | 3 天 | ✅ **DONE** |
| M5 | 持久化 + 设置 + 自动保存 | 2 天 | ✅ **DONE** |
| M6 | 优化 + 收尾 | 2 天 | ✅ **DONE** |
| M7 | DP 断行算法 + CJK 优化 | 2 天 | ✅ **DONE** |
| M8 | 图片内联接口 (预留) | 1 天 | ✅ **DONE** |
| M9 | 字体缓存 (已优化) | 1 天 | ✅ **DONE** |
| M10 | Activity 架构重构 | 3 天 | ✅ **DONE** |

**总计**: 约 3 周（15 天）

## M1 验证结果

```
RAM:   [=         ]   7.8% (used 25468 bytes from 327680 bytes)
Flash: [===       ]  34.7% (used 454285 bytes from 1310720 bytes)
Build: SUCCESS (34.25s)
```

**关键 API**:
- `M5.begin()` — 初始化 M5Unified（自动检测 M5Paper + 所有外设）
- `M5.Display.printf()` — 墨水屏渲染（epd_mode_t::epd_quality 最高质量）
- `M5.Touch.getCount()` + `M5.Touch.getDetail(0).x/y` — 触摸
- `M5.BtnA/BtnB/BtnC.wasPressed()` — 按键
- `M5.Log.printf()` — 统一日志（串口/显示/回调）

**关键坑**:
- M5GFX 0.2.28 移除了 `fonts[]` 和 `setFreeFonts()`，用 `printf` 直接输出
- 不要设 `ARDUINO_USB_CDC_ON_BOOT=1`（M5Paper 是 ESP32，用 UART 不用 USB CDC，会破坏 Serial 符号）
- `pio install` 命令在新版 PlatformIO 已移除，用 `pio run` 自动拉库

## 设计先行

按 AGENTS.md 关卡 B 走设计先行，方案文档见:
- `.comet/changes/m5paper-epub-reader/intent.md`

## 代码复用

**从 CrossPoint Reader 移植**（~178K 行）:
- `lib/Epub`（36K，EPUB 解析核心）
- `lib/ZipFile`（716，ZIP 解压）
- `lib/JsonParser`（610，JSON）
- `lib/EpdFont`（138K，字体引擎，含 CJK fallback）
- `lib/Utf8`（485，UTF-8 工具）
- `Activity` 基类 + `ActivityManager`（503，状态机）

**需要重写**（~3750 行）:
- HAL 层（freeink-sdk → M5Unified）
- 显示封装（M5GFX API 包装）
- 输入抽象（触摸 + 按键统一 InputEvent）
- EpdFont 集成（EpdFont 字体数据 → M5GFX 渲染管线）
- Home Activity（书库浏览，触摸 + 按键）
- Settings Activity（字号/行距/TTF 路径）

## 参考

- [CrossPoint Reader](https://github.com/crosspoint-reader/crosspoint-reader)（MIT, 7.4k Star）— EPUB 解析代码来源
- [M5Unified](https://github.com/m5stack/M5Unified) — M5Stack 官方驱动
- [M5GFX](https://github.com/m5stack/M5GFX) — 显示驱动
- [M5Paper 文档](https://docs.m5stack.com/en/core/m5paper) — 硬件规格
- 本仓 `references/external/crosspoint-reader/` — CrossPoint 源码

## 许可证

MIT