# ESP32S3-Ebook-Reader

**Repository Path**: wangwei-2022/esp32-s3-ebook-reader

## Basic Information

- **Project Name**: ESP32S3-Ebook-Reader
- **Description**: 这是一个基于ESP32S3的桌面时钟阅读器项目
- **Primary Language**: C++
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-08-12
- **Last Updated**: 2026-08-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

[PCB的链接](https://oshwhub.com/the-cat-of-wolf-of-home/project_rsoypymy)
# ESP32-S3 电子书阅读器项目

基于 YD-ESP32-S3 N16R8（16MB Flash，8MB PSRAM）的电子书阅读器项目。纯Vibe Coding。

## 硬件规格

<<<<<<< HEAD
| 组件 | 规格 |
|------|------|
| 开发板 | YD-ESP32-S3 N16R8 |
| Flash | 16MB |
| PSRAM | 8MB |
| 屏幕 | ST7789 TFT LCD (320x240 横向模式) |
| 温湿度传感器 | DHT22（模块） |
| 旋转编码器 | EC11（立插15mm） |
| SD卡 | SPI接口，支持 FAT32 |
=======
- **开发板**: YD-ESP32-S3 N16R8
- **Flash**: 16MB
- **PSRAM**: 8MB
- **屏幕**: ST7789 TFT LCD (320x240 横向模式)（无PWM调光）
- **温湿度传感器**: DHT22（模块）
- **旋转编码器**: EC11（立插15mm）
- **SD卡**: SPI接口，支持 FAT32（可能需要飞线）

##注意事项

- **您的SD读卡器极有可能对不齐外壳
- **请自行设计键帽与旋钮帽（旋钮卡槽顶部距离旋钮帽底部6mm）
- **您的屏幕背光方式极有可能与该项目不一致

##快速开始

- **准备硬件**
- **下载仓库与Adruino IDE**
- **下载必备库**（请向下翻页查看）
- **选择ESP32S3**
- **将ESP32连接至电脑，使用Adruino IDE编译上传**
- **如果需要转换小说为专用.eb文件夹格式，转换器位于/epub-to-eb/ （注意，该转换器支支持转换epub格式）**
>>>>>>> 8f22fb400d6d718f7739580268404ecd8a501eb8

## 硬件引脚定义

| 功能 | GPIO | 备注 |
|------|------|------|
| TFT_SCK | 13 | |
| TFT_MOSI | 12 | |
| TFT_MISO | 11 | |
| TFT_CS | 17 | |
| TFT_DC | 16 | |
| TFT_RST | 15 | |
| TFT_BL | 18 | 背光控制（100k电阻上拉） |
| SD_CS | 14 | |
| EC11_A | 4 | |
| EC11_B | 5 | |
| EC11_SW | 6 | |
| BTN_PREV | 10 | |
| BTN_NEXT | 9 | |
| BTN_OK | 8 | |
| BTN_MODE | 7 | |
| DHT22 | 21 | |
| ADC_BAT | 35 | |
=======
| TFT_SCK | 13 ||
| TFT_MOSI | 12 ||
| TFT_MISO | 11 ||
| TFT_CS | 17 ||
| TFT_DC | 16 ||
| TFT_RST | 15 ||
| TFT_BL | 18 (背光控制) | 当前使用的是100k电阻上拉短接屏幕触点，如果您的屏幕不一致，请自行修改代码与PCB |
| SD_CS | 14 |
| EC11_A | 4 |
| EC11_B | 5 |
| EC11_SW | 6 |
| BTN_PREV | 10 |
| BTN_NEXT | 9 |
| BTN_OK | 8 |
| BTN_MODE | 7 |
| DHT22 | 21 |
| ADC_BAT | 35 |

## 项目结构

```
ESP32_S3_Ebook_Reader/
├─ ESP32_S3_Ebook_Reader.ino    # 主程序入口
├─ Config.h                     # 全局配置（引脚、常量、配色）
├─ Button.h/.cpp                # 按键驱动（基于OneButton库）
├─ EC11.h/.cpp                  # EC11旋转编码器驱动（基于PCNT）
├─ DHT22.h/.cpp                 # DHT22温湿度传感器驱动
├─ ClockManager.h/.cpp          # 时钟管理（基于NTPClient库）
├─ TimerManager.h/.cpp          # 倒计时/正计时管理
├─ SDCardManager.h/.cpp         # SD卡管理器（挂载、目录创建）
├─ EbookParser.h/.cpp           # .eb格式电子书解析器（基于TinyXML2）
├─ BookManager.h/.cpp           # 书架管理（扫描、进度保存）
├─ FileBrowser.h/.cpp           # 文件浏览器（目录浏览）
├─ Recorder.h/.cpp              # 温湿度CSV记录器
├─ SettingsManager.h/.cpp       # 设置管理器（配置持久化）
├─ IconManager.h/.cpp           # 图标管理器（C数组加载）
├─ UIManager.h/.cpp             # UI管理器（页面切换、双缓冲渲染）
├─ EncodingUtils.h/.cpp         # 编码工具（GBK/UTF-8/UTF-16转换）
├─ SDModules.h/.cpp             # SD模块统一测试入口
├─ u8g2_font_custom.h           # 自定义字体数据
├─ icons.h                      # 图标定义
├─ icons_data.h                 # 图标数据数组
├─ epub-To-eb/                  # EPUB转.eb格式转换器
│   ├─ epubtoeb.py              # 主转换器（支持批量转换）
│   └─ fix_eb_format.py         # 格式修复工具
└─ UILib/                       # UI组件库（LVGL实验版本）
    ├─ astra/                   # Astra UI框架
    └─ hal/                     # 硬件抽象层
```

## 文件详细说明

### 主程序入口

**ESP32_S3_Ebook_Reader.ino**
- 程序入口点，包含 `setup()` 和 `loop()`
- 初始化所有硬件模块和管理器
- 主循环调用各模块的 `update()` 方法
- 执行 UI 渲染和输入处理

### 配置文件

**Config.h**
- 全局常量定义（版本号、屏幕尺寸、颜色配置）
- 引脚定义（屏幕、SD卡、按键、传感器）
- 功能开关宏（`ENABLE_BUTTONS`, `ENABLE_WIFI` 等）
- 调试模式开关（`DEBUG_SERIAL_OUTPUT`）
- 默认 WiFi 凭据

### 硬件驱动模块

**Button.h/.cpp**
- 按键管理类，基于 **OneButton** 第三方库
- 支持短按、长按事件检测
- 内置防抖处理（`BUTTON_DEBOUNCE_TIME`）
- 提供 `update()` 和 `isPressed()` 方法

**EC11.h/.cpp**
- EC11 旋转编码器驱动，基于 **FastInterruptEncoder** 库
- 使用 ESP32 硬件 PCNT 计数，非软件模拟
- 支持旋转增量检测和按下事件
- 内置去抖和状态转换查找表

**DHT22.h/.cpp**
- DHT22 温湿度传感器驱动
- 非阻塞式读取，避免阻塞主循环
- 提供温度、湿度获取方法
- 带超时处理和错误检测

### 系统服务模块

**ClockManager.h/.cpp**
- 时钟管理类，基于 **NTPClient** 第三方库
- NTP 网络时间同步（非阻塞模式）
- 本地时间缓存，减少 `localtime()` 调用
- 支持时区配置和手动校时
- 每小时自动校准时间

**TimerManager.h/.cpp**
- 倒计时和正计时管理
- 基于 `millis()` 的非阻塞计时
- 支持暂停、继续、重置操作
- 提供时间格式化输出

**SettingsManager.h/.cpp**
- 设置配置管理
- 配置持久化到 SPIFFS（`config.dat`）
- 支持 WiFi 凭据、屏幕亮度、默认页面等设置
- 提供恢复出厂设置功能

**Recorder.h/.cpp**
- 温湿度数据记录器
- CSV 格式存储，按年月日分目录
- 支持自动记录和手动触发
- 文件路径：`/rec/年/月/日.csv`

### 存储和文件模块

**SDCardManager.h/.cpp**
- SD 卡管理器
- SPI 总线初始化和 SD 卡挂载
- 自动创建必要目录（`/books`, `/fonts`, `/rec`）
- 文件系统操作封装（打开、读取、写入）
- WiFi 凭据存储（`/wifi.dat`）

**FileBrowser.h/.cpp**
- 文件浏览器组件
- 目录遍历和文件列表管理
- 支持文件夹和文件区分
- 提供导航和选择功能

**EncodingUtils.h/.cpp**
- 字符编码转换工具
- GBK → UTF-8 转换（使用查表法优化）
- UTF-16 → UTF-8 转换
- 提供缓冲区 API，减少动态内存分配
- 支持空指针检查和边界安全

### 阅读器模块

**EbookParser.h/.cpp**
- `.eb` 格式电子书解析器，基于 **TinyXML2** 第三方库
- 解析 `introduction.ebl` 获取书籍元信息（标题、作者、卷章结构）
- 解析 `chapter.*.ebl` 获取章节内容
- 生成页面索引，支持分页显示
- 进度保存/加载（`progress.dat`）

**BookManager.h/.cpp**
- 书架管理类
- SD 卡书籍扫描（`.eb` 文件夹和 `.txt` 文件）
- 书籍信息管理（标题、作者、进度）
- 章节列表构建和管理
- 阅读进度保存/恢复
- 页面读取和分页计算

### UI 模块

**UIManager.h/.cpp**
- UI 管理器，核心渲染引擎
- ST7789 屏幕驱动和双缓冲渲染（PSRAM帧缓冲）
- 8 个页面管理：时钟、书架、阅读器、倒计时、秒表、文件、设置、关于
- 按键和旋钮输入处理
- 侧边菜单和页面切换动画
- 局部刷新优化，减少屏幕闪烁

**IconManager.h/.cpp**
- 图标管理器
- 图标数据加载（C数组格式）
- 图标绘制和缓存
- 提供图标 ID 到数据的映射

### 测试和工具模块

**SDModules.h/.cpp**
- SD 模块统一测试入口
- 用于测试 SD 卡和文件系统功能
- 提供调试接口

**u8g2_font_custom.h**
- 自定义字体数据
- 基于 U8g2 字体格式
- 包含中文字体支持

**icons.h / icons_data.h**
- 图标定义和数据数组
- 位图格式图标
- 用于 UI 界面显示

### EPUB 转换工具

**epub-To-eb/epubtoeb.py**
- EPUB 文件转 `.eb` 格式转换器
- 支持单文件转换和批量转换模式
- 提取 EPUB 元信息（标题、作者）
- 解析章节结构，生成章节文件
- 支持封面提取
- 输出标准 XML 格式（兼容 TinyXML2）

**epub-To-eb/fix_eb_format.py**
- `.eb` 文件夹格式修复工具
- 将旧格式（`</>`）转换为标准 XML 格式（`</tag>`）
- 自动修复空卷名问题（填充 "正文"）
- 修复进度文件中的错误章节文件名
- 支持批量修复多个 `.eb` 文件夹

### UI 组件库（实验版本）

**UILib/astra/**
- LVGL 9.x 框架实验版本
- 包含 LVGL 配置和驱动
- 当前未被主程序使用

**UILib/hal/**
- 硬件抽象层
- 屏幕和输入设备驱动
- 用于 LVGL 实验版本

## 第三方库依赖

| 库名 | 用途 | 安装方式 |
|------|------|----------|
| OneButton | 按键防抖和事件处理 | Arduino IDE 库管理器搜索 "OneButton" |
| NTPClient | NTP 时间同步 | Arduino IDE 库管理器搜索 "NTPClient"（Fabrice Weinberg） |
| TinyXML2 | XML 解析 | Arduino IDE 库管理器搜索 "TinyXML2"（Lee Thomason） |
| FastInterruptEncoder | EC11 编码器硬件计数 | Arduino IDE 库管理器搜索 "FastInterruptEncoder" |
| Adafruit GFX Library | 图形渲染基础 | Arduino IDE 库管理器搜索 "Adafruit GFX" |
| Adafruit ST7789 Library | ST7789 屏幕驱动 | Arduino IDE 库管理器搜索 "Adafruit ST7789" |
| U8g2_for_Adafruit_GFX | U8g2 字体支持 | Arduino IDE 库管理器搜索 "U8g2_for_Adafruit_GFX" |
| ESP32 Arduino Core | ESP32 硬件支持 | 开发板管理器安装 "ESP32 by Espressif Systems" |

## 编译步骤（Arduino IDE）

1. **配置开发板支持**
   - 首选项 → 附加开发板管理器网址：
     ```
     https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
     ```
   - 安装 ESP32 by Espressif Systems（版本 3.3.10 或更高）

2. **安装第三方库**
   - 在库管理器中搜索并安装上述所有依赖库

3. **配置开发板设置**
   - 开发板：ESP32S3 Dev Module
   - USB Mode：Hardware CDC and JTAG (USB-OTG)
   - PSRAM：OPI PSRAM
   - Flash Mode：QIO 80MHz
   - Flash Size：16MB
   - CPU Frequency：240MHz

4. **编译上传**
   - 连接 ESP32 到电脑
   - 点击编译按钮
   - 点击上传按钮

## SD 卡文件结构

```
SD卡根目录/
├─ books/             # 书籍目录
│   ├─ 书籍名.eb/     # .eb格式书籍（文件夹）
│   │   ├─ introduction.ebl    # 书籍元信息（XML格式）
│   │   ├─ chapter.1.正文.ebl  # 章节文件（XML格式）
│   │   ├─ chapter.2.正文.ebl  # 章节文件
│   │   └─ progress.dat        # 阅读进度（XML格式）
│   └─ 书籍名.txt     # TXT格式书籍
├─ fonts/             # 字体文件目录
├─ rec/               # 温湿度记录目录
│   └─ 年/月/日.csv   # CSV格式记录文件
└─ config.dat         # 设置配置文件
```

## 已实现功能

### 硬件驱动
- ✅ 按键驱动（OneButton，短按/长按）
- ✅ EC11 旋转编码器（FastInterruptEncoder，硬件 PCNT）
- ✅ DHT22 温湿度传感器（非阻塞读取）

### 通信模块
- ✅ WiFi 连接（非阻塞状态机，自动重连）
- ✅ NTP 时间同步（NTPClient，每小时校准）
- ✅ 串口调试输出

### 存储模块
- ✅ SD 卡初始化和挂载（SPI 共享总线）
- ✅ 自动创建目录
- ✅ .eb 格式电子书解析（TinyXML2）
- ✅ TXT 格式电子书支持
- ✅ 阅读进度保存/恢复
- ✅ 温湿度 CSV 记录

### UI 系统
- ✅ ST7789 屏幕驱动（320x240 横向模式）
- ✅ 双缓冲渲染（PSRAM 帧缓冲）
- ✅ U8g2 中文字体显示
- ✅ 8 个功能页面
- ✅ 侧边菜单和页面切换
- ✅ 局部刷新优化
- ✅ WiFi 扫描与密码输入
- ✅ 设置页面（多级菜单、长文本滚动）

### 阅读器
- ✅ .eb 格式电子书阅读（分章节加载）
- ✅ 章节选择器
- ✅ 阅读进度自动保存
- ✅ 卷章结构支持

## 使用说明

### WiFi 连接
1. 按下 MODE 键打开菜单
2. 选择"设置"进入设置页面
3. 进入"WiFi设置"菜单
4. 选择"扫描WiFi"搜索可用网络
5. 选择目标网络并输入密码

### 页面导航
```
时钟 → 书架 → 阅读器 → 倒计时 → 秒表 → 文件 → 设置 → 时钟
```

### 按键功能

| 按键 | 短按功能 |
|------|----------|
| PREV | 上一页 |
| NEXT | 下一页 |
| OK | 确认/进入 |
| MODE | 返回时钟页面/关闭菜单 |

### EC11 旋钮功能
- 旋转：上下选择
- 按下：确认/进入

## 开发指南

### 功能开关宏

在 `Config.h` 中通过宏控制功能启用：

```cpp
#define ENABLE_BUTTONS      // 按键驱动
#define ENABLE_EC11         // 旋钮驱动
#define ENABLE_DHT22        // 温湿度传感器
#define ENABLE_WIFI         // WiFi功能
#define ENABLE_SCREEN       // 屏幕驱动
#define ENABLE_UI           // UI系统
#define ENABLE_CLOCK        // 时钟管理
#define ENABLE_TIMER        // 计时器
#define ENABLE_BOOK_MANAGER // 电子书管理
#define ENABLE_FILE_BROWSER // 文件浏览器
#define ENABLE_SD           // SD卡功能
```

### 调试模式

启用调试输出：

```cpp
#define DEBUG_SERIAL_OUTPUT
```

串口波特率：115200

### EPUB 转换

使用 `epub-To-eb/epubtoeb.py` 转换 EPUB 文件：

```bash
python epubtoeb.py
```

支持批量转换模式，选择包含多个 EPUB 文件的文件夹即可。

### 格式修复

使用 `epub-To-eb/fix_eb_format.py` 修复旧格式 `.eb` 文件夹：

```bash
python fix_eb_format.py
```

修复内容：
- 将旧格式 `</>` 转换为标准 XML 格式
- 修复空卷名问题（自动填充 "正文"）
- 修复进度文件中的错误章节文件名

## 常见问题

### 1. SPI 总线冲突
SD 卡和屏幕共用 SPI 总线，必须先初始化屏幕再初始化 SD 卡。

### 2. 屏幕颜色异常
ST7789 是 BGR 面板，需使用 `SWAP_RB` 宏交换 R 和 B 通道。

### 3. 内存溢出
大数组使用 `ps_malloc()` 在 PSRAM 中分配，避免栈上分配大内存。

### 4. 中文显示乱码
使用 `u8g2_font_unifont_t_chinese3` 字体，确保编码为 UTF-8。

### 5. SD 卡无法挂载
检查 SD 卡格式（FAT32），确保 CS 引脚连接正确。

## 许可证

Apache License 2.0