纯 Rust 开发的 UI 框架和 UI 系统（ESP32-S3）

README

# 纯 Rust 开发的 UI 框架和 UI 系统（ESP32-S3）

> 当前版本：[`v0.11.8-20261021`](https://github.com/HWYWL/HiveBox/releases/latest) —— 版本号怎么读见下方「版本号规则」

## 📖 项目简介

这个项目是为 微雪 ESP32-S3-Touch-AMOLED-2.16 触屏开发板开发的纯 Rust UI 系统。

项目基于 **ESP-IDF v6.1** 构建。  

- **测试平台**：目前固件仅在 **微雪 ESP32-S3-Touch-AMOLED-2.16** 上进行过测试。
- **可移植性**：应用与 UI 框架与硬件解耦，移植仅需适配屏幕刷新、触摸输入及 `pomelo-hal` 外设 Trait。
- **产品官方文档**：[微雪 ESP32-S3-Touch-AMOLED-2.16 文档](https://docs.waveshare.net/ESP32-S3-Touch-AMOLED-2.16)

### 基于 pomelo-ui 深度定制

本项目是 [**pomelo-ui**](https://github.com/pomelos-on-sale/pomelo-ui) 的深度定制版，两者的关系写在这里，以免读的人以为这套界面是从零写的：

- **上游 [pomelo-ui](https://github.com/pomelos-on-sale/pomelo-ui) 提供框架**：`ui-framework/` 下的 iced 移植、渲染后端（`iced-pomelo-gfx`）、软件光栅器（`pomelo-gfx`）、字体资产与烘焙工具（`pomelo-font`）、图标库（`pomelo-material-symbols`），以及它们各自的设计与文档。
- **本项目在框架之上做定制**：板级固件与板级驱动（`pomelo-firmware/`）、外设抽象与模拟后端（`pomelo-hal/`）、应用（`pomelo-apps/`）、应用共享控件（`pomelo-widgets/`），以及界面本身 —— 具体每一条见下方「版本时间线」。
- **上游的名字与目录都保留**：`ui-framework/` 的结构、各组件的 `README.md` 与 `LICENSE`、`pomelo-*` 的命名照旧，便于与上游逐项对照。上游组件按需做最小的修改（例如字体子集补字），这类改动同样在这里可见。

---

## 📷 界面预览

下面都是**真机屏幕**（480×480 AMOLED）的实拍，不是设计稿。每张都按 160×160 显示 —— 图都写死了宽度，不然表格会按每格说明文字的长短把列宽分得不一样，图片也就跟着一大一小；原图是 480×480，点开可以看细节：

| 桌面 | 设置 · 读数面板 | 设置 · 主列表 | 设置 · 系统信息 |
| :---: | :---: | :---: | :---: |
| <img src="https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/9bc5070292de862310d04bd2.png" width="160" alt="桌面"> | <img src="https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/cc1274cae4d80f5d3699cc7f.png" width="160" alt="读数面板"> | <img src="https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/f94776fad7d99f815e8d2498.png" width="160" alt="设置主列表"> | <img src="https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/0ac675cd829a0a54b6baca0b.png" width="160" alt="系统信息"> |
| 状态栏、四个应用与分页点（这张是两页七个应用那版的实拍，现在是两页十五个） | 三个环 + 芯片与固件卡，页脚是编译/系统时间与已启动 | 无线网络、内存、存储、电池、主题、日期与时间 | 规格与读数分开：操作系统一栏说明来源，固件版本是镜像自报 |

| 音乐播放器 | 网页管理 | 终端 | 计算器 |
| :---: | :---: | :---: | :---: |
| <img src="https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/d5050cf83ac4b0c478620472.png" width="160" alt="音乐播放器"> | <img src="https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/284d83c9cad9d6d0ef00fe3b.png" width="160" alt="网页管理"> | <img src="https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/fd9057b02a7bf2d3c30823b9.png" width="160" alt="终端"> | <img src="https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/93b3ab71c0add2288de03c42.png" width="160" alt="计算器"> |
| 读 TF 卡里的音乐，列表点击播放，进度与音量可直接拖动 | 板子自己起 HTTP 服务，同一网络里用浏览器打开 | 触屏键盘输入，板内命令行 | 用 iced 自带控件写的计算器 |

| 时钟 | 概览 | 电池（电量日志） | 文件管理 |
| :---: | :---: | :---: | :---: |
| <img src="https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/39cbc7ed33aa9f85ec563d62.png" width="160" alt="时钟"> | <img src="https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/385572cfc30989a868658fb8.png" width="160" alt="概览"> | <img src="https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/cf849e1c3b4842b8b43e400c.png" width="160" alt="电池"> | <img src="https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/1b4260c2bbaf7c824bb22582.png" width="160" alt="文件管理"> |
| 一枚表盘带秒针，下面是大号数字时间与日期；同一个磁贴里还有番茄钟与闹钟两页 | 五张卡一屏：电池、无线网络、存储（内部 + 存储卡），下面还有内存与服务器；右上角是「重新检测」 | 页头写着「电池」，磁贴上叫「电量日志」；顶部是过热警示条，下面电量卡 + 放电曲线，充电中不给剩余时间估算 | 内部 / 存储卡两个卷，路径与目录项，底部五个动作：新建文件夹、重命名、复制、粘贴、删除 |

| 天气 | 信道地图 | 游戏 |
| :---: | :---: | :---: |
| <img src="https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/8c1a3555eebd566637d94038.png" width="160" alt="天气"> | <img src="https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/b321cb753c17719e5a9b7661.png" width="160" alt="信道地图"> | <img src="https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/90c1d44ccdd44f1fe01b2e5f.png" width="160" alt="游戏"> |
| 打开先按 IP 定位到城市（页眉写着地名，这张是广州），再取**当地**的现在与未来几天；「数据来自 Open-Meteo」是服务名 —— 它不要密钥也不要账号 | 十三个信道的压力图，加一条建议信道（这里是 6）；下面还有信号分布（每行 10 dBm）与网络列表，5 GHz 照列但不参与算术 | 一个磁贴打开的是**游戏列表**，点进去才是棋盘；加第二款游戏不用再占一个桌面磁贴，每局用开机时长当种子 |

---

## 🚀 快速上手

### 1. 拿到代码

```bash
git clone https://github.com/HWYWL/HiveBox.git
cd HiveBox
```

上游框架组件（`ui-framework/`）在本仓库里是普通目录，会跟着主仓库一起下来，不需要 `--recurse-submodules`。上游项目本身见 [pomelo-ui](https://github.com/pomelos-on-sale/pomelo-ui)。

### 2. 在 PC 上跑起来（不需要板子）

```bash
cd pomelo-apps
cargo run -p app-launcher   # 整机界面：桌面、状态栏、应用切换
cargo run -p calculator     # 单个应用
```

Q 键为返回键，W 键为退出键。读数来自桌面模拟后端（`pomelo-hal/src/sim/`），所以不接板子也能看到完整界面。

### 3. 刷到板子上

板子：**微雪 ESP32-S3-Touch-AMOLED-2.16**。

#### 3.1 直接刷现成固件（推荐：不用装 ESP-IDF 和 Rust 工具链）

到 [**Releases**](https://github.com/HWYWL/HiveBox/releases/latest) 下载 `hivebox-firmware-*.bin`，用 USB 连上板子，然后：

```bash
pip install esptool
esptool --chip esp32s3 --port COM3 --baud 921600 write_flash 0x0 hivebox-firmware-<版本>.bin
```

- **烧到 `0x0`**：这个 `.bin` 是**合并镜像**（bootloader + 分区表 + 应用），一条命令写完，不用管偏移。
- **同一页挂着的 `hivebox-ota-*.bin` 不要下载了往 `0x0` 刷**：它是**应用镜像**，一份槽里的东西，没有 bootloader 和分区表，写进 `0x0` 板子起不来。它和 `bin/manifest.json` 是给**板子自己下**的 —— 「更新」应用里点「固件」那一行的「安装」，它会把这个镜像写进另一个固件槽，重启就换过去了。
- **刷机本身不碰你的数据**：数据分区从 `0xC20000` 才开始，而合并镜像只覆盖 `0x0` 到约 `0x5C0000`（两个固件槽里也只写了 `ota_0`）。
- **但 `v0.9.0` 这一版要重新连 Wi-Fi**：内置存储从 `0xB00000` 挪到了 `0xC20000`（它前面多了一个 6 MB 的固件槽），新的文件系统是空的 —— Wi-Fi 密码、服务器列表、音乐设置、存在内置存储里的文件都要**重配一次**。它们没被删，只是换了位置之后不再被读，但对你的体感是一样的。**以后不会再有这种事**：分区表安定下来了，之后都是普通更新。SD 卡完全不受影响。
- 想回到出厂状态，先 `esptool --chip esp32s3 --port COM3 erase_flash`，再刷一次。
- `--port` 换成你自己的串口：Windows 是 `COM3` 这类（设备管理器 → 端口），Linux 是 `/dev/ttyACM0`，macOS 是 `/dev/tty.usbmodem*`。
- 正常情况下 esptool 会用 DTR/RTS 自动让板子进下载模式；连不上时按住 **BOOT** 键再插 USB。

#### 3.2 从源码编译烧录（改代码时用）

先装工具链：

- **ESP-IDF v6.1**（或兼容版本）
- **Rust Xtensa 工具链**：`cargo install espup && espup install`

然后是：

```bash
cd pomelo-firmware/firmware

./flash.sh          # Linux/macOS：默认串口 /dev/ttyACM0，结尾会进 monitor（Ctrl+] 退出）
./flash.sh COM3     # Windows：把串口当第一个参数传进去
```

`flash.sh` 在找不到 `idf.py` 时会去 source `$IDF_PATH`（默认 `~/.espressif/v6.1/esp-idf`）的 export 脚本；ESP-IDF 装在别处就先 `export IDF_PATH=...`。不想用脚本也可以直接：

```bash
idf.py -p COM3 flash monitor   # 编译 + 烧录 + 串口日志
idf.py -p CO