# icutool-esp32-tft

**Repository Path**: plusboy/icutool-esp32-tft

## Basic Information

- **Project Name**: icutool-esp32-tft
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-26
- **Last Updated**: 2026-05-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ICUTOOL ESP32-S3 + ST7796

一个基于 `PlatformIO + ESP-IDF` 的 ESP32-S3 项目，目标功能：

- WiFi 未配置或连接失败时，自动开启热点配网
- 提供 Web 后台，使用固定密钥访问
- 支持上传 `480x320` BMP 图片作为壁纸
- 支持按色值设置纯色背景
- 支持从 `SPIFFS` 加载项目内置的中文抗锯齿字体，统一渲染天气、启动提示、新闻等中文混排文本
- 屏幕实时显示当前时间：`2026-04-25 22:20:11`

## 先改这里

请先按你的硬件连线修改 [include/app_config.h](include/app_config.h) 里的 LCD 引脚：

- `LCD_PIN_MOSI`
- `LCD_PIN_SCLK`
- `LCD_PIN_CS`
- `LCD_PIN_DC`
- `LCD_PIN_RST`
- `LCD_PIN_BK_LIGHT`

后台密钥也在这个文件里：

- `APP_ADMIN_KEY`

## Web 功能

设备启动后：

1. 如果没有保存 WiFi，或者连接失败，会开启热点 `ICUTOOL-Setup`
2. 连接热点后访问 `http://192.168.4.1/`
3. 保存 WiFi 后，设备会尝试连接路由器
4. 后台页面地址为 `/admin`

后台提供：

- 设置背景颜色
- 上传 BMP 壁纸并立即应用
- 用浏览器当前时间同步设备时间

## 壁纸要求

- 格式：`BMP`
- 分辨率：`480x320`
- 建议使用无压缩 `24-bit` 或 `32-bit` BMP
- 上传完成后会立即转成 `wallpaper.rgb565`，原始 `upload.bmp` 临时文件会自动删除，避免与字体文件一起长期占用 `SPIFFS`

## 更换 GIF 宠物动画

时钟卡片分割线下方的小狗动画不是在板子上直接解 `GIF`，而是先在电脑上离线转成 C 头文件，再由固件做局部刷新显示。当前运行时依赖这几个文件：

- 源动画资源：你自己的 `*.gif`
- 转换脚本：[tools/gif_to_clock_pet.py](tools/gif_to_clock_pet.py)
- 生成结果：[src/dashboard_clock_pet_asset.h](src/dashboard_clock_pet_asset.h)
- 动画绘制与局部刷新逻辑：[src/dashboard_clock.c](src/dashboard_clock.c)、[src/display.c](src/display.c)

### 为什么这样做

- ESP32 不需要实时解 `GIF`，运行时更稳定
- 可以把所有帧统一裁切、缩放、量化到小调色板，节省 Flash
- 动画走单独的 `CLOCK_PET` 局部刷新，不会带着时间一起闪
- 当前绘制逻辑已经针对屏闪做过优化：动态刷新时不会先清整块区域，而是直接整帧覆盖写入

### 一次完整替换流程

1. 把新的 `gif` 放到仓库里，例如根目录或 `project_assets/`
2. 如需预览裁切结果，先运行一次脚本并生成预览图
3. 确认效果后，让脚本直接覆盖 `src/dashboard_clock_pet_asset.h`
4. 重新编译并烧录固件

### 安装脚本依赖

脚本依赖 `Pillow`。首次使用可在本机安装：

```bash
pip install -r tools/requirements.txt
```

### 最常用命令

下面这条命令会：

- 自动计算 `gif` 在所有帧上的可见区域
- 按时钟卡片宠物区允许的最大尺寸缩放
- 统一做 8 色调色板量化
- 输出新的 [src/dashboard_clock_pet_asset.h](src/dashboard_clock_pet_asset.h)
- 顺手生成一张预览图，便于确认裁切和缩放结果

```bash
python tools/gif_to_clock_pet.py ^
  1cc8e5f9c05d50d37b090ca3138d1d2a.gif ^
  --output src/dashboard_clock_pet_asset.h ^
  --preview dog_preview.png
```

如果你在 PowerShell 里执行，也可以写成一行：

```powershell
python tools/gif_to_clock_pet.py .\1cc8e5f9c05d50d37b090ca3138d1d2a.gif --output .\src\dashboard_clock_pet_asset.h --preview .\dog_preview.png
```

### 重要参数

- `--crop left,top,right,bottom`
  当自动裁切不理想时，手动指定裁切区域
- `--max-width 178`
  宠物动画允许的最大宽度
- `--max-height 100`
  宠物动画允许的最大高度
- `--colors 8`
  调色板颜色数，不包含透明色；数值越大越接近原图，但生成头文件也会更大
- `--alpha-threshold 16`
  透明像素阈值
- `--preview path.png`
  生成所有帧的预览拼图

### 当前这只狗的参考命令

这次项目里使用的原始 `gif` 是根目录的 `1cc8e5f9c05d50d37b090ca3138d1d2a.gif`。如果你想尽量复现这次效果，可以直接用：

```powershell
python tools/gif_to_clock_pet.py .\1cc8e5f9c05d50d37b090ca3138d1d2a.gif --crop 20,73,390,416 --max-width 178 --max-height 100 --colors 8 --output .\src\dashboard_clock_pet_asset.h --preview .\dog_preview.png
```

这里的 `20,73,390,416` 是这张图在 10 帧上的联合可见边界框，我已经验证过。

### 编译验证

替换完成后，按仓库当前约定运行：

```powershell
"$env:USERPROFILE\.platformio\penv\Scripts\pio.exe" run
```

如果编译通过，再烧录：

```powershell
"$env:USERPROFILE\.platformio\penv\Scripts\pio.exe" run -t upload
```

### 调整建议

- 如果动画看起来偏小，优先调大 `--max-height`，再看是否需要提高 `--max-width`
- 如果动画边缘发灰或细节丢失，可以把 `--colors` 调到 `12` 或 `16`
- 如果更换后又出现屏闪，优先检查是不是帧尺寸太大、颜色过多，或者是否误改了 [src/dashboard_clock.c](src/dashboard_clock.c) 里的局部刷新路径
- 如果新 `gif` 是细线条像素风，也可以后续把脚本改成 `NEAREST` 缩放，这会比当前默认的 `LANCZOS` 更硬朗

## 编译

```bash
platformio run
```

## 资源文件系统

中文字体资源位于 `data/fonts/puhui16.bin`，运行时会从 `SPIFFS` 加载。

首次烧录或更新字体资源后，除了刷固件，还要额外刷一次文件系统镜像：

```bash
platformio run -t buildfs
platformio run -t uploadfs
```

串口启动日志里应能看到：

- `PSRAM: total=... free=...`
- `loaded font /spiffs/fonts/puhui16.bin ...`

如果字体文件缺失，系统会打印告警并回退到最小 ASCII 兜底显示，不会直接崩溃。

## 烧录

```bash
platformio run -t upload
platformio device monitor
```


MQTT topic 和 payload 约定如下：

icutool/esp32s3-monitor/weather
{"temp_cur":26,"temp_high":31,"temp_low":22,"description":"Cloudy","city":"Shenzhen","icon_type":1}
icutool/esp32s3-monitor/system/cpu
{"percent":37}
icutool/esp32s3-monitor/system/memory
{"percent":62,"used_mb":5080,"total_mb":8192}
icutool/esp32s3-monitor/news
{"category":"TECH","headline":"AI edge device dashboard switched to MQTT","summary":"Each screen region now updates only when its own topic arrives.","time_ago":"just now"}