# ESP-InkFrame

**Repository Path**: chiyoooo/esp-ink-frame

## Basic Information

- **Project Name**: ESP-InkFrame
- **Description**: 电子相框项目包括固件前后端
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-30
- **Last Updated**: 2026-05-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ESP-InkFrame

这是仓库的主入口，根目录就是 ESP-IDF 工程目录；打开这个文件夹后，可以直接在根目录执行 `idf.py build`、`idf.py flash`、`idf.py monitor`，不需要再进入子目录。

## 目录结构

- `main/`、`components/`、`CMakeLists.txt`、`partitions.csv`、`sdkconfig*`
  - 固件主工程，保持在仓库根目录，方便直接用 ESP-IDF 编译和烧录。
- `configs/idf/`
  - 存放 `sdkconfig.defaults*`、CI 配置和各芯片模板配置，减少根目录杂项文件。
- `console/`
  - 当前正在使用的控制台工程，包含后端、前端、运行时目录和辅助脚本。
- `docs/`
  - 协议文档和运行策略说明。
- `archive/backup_ble_version/`
  - 旧 BLE 版本源码备份。
- `archive/legacy_tools/`
  - 早期调试页、旧版 Python 后端和历史运行数据，保留做参考，不再作为当前主流程入口。
- `references/ui/`
  - UI 参考稿和迁移资料。

## 根目录直接编译

首次打开工程或切换目标芯片后，可在仓库根目录执行：

```bash
idf.py set-target esp32s3
idf.py build
idf.py -p COM16 flash monitor
```

如果目标已经是 `esp32s3`，通常直接执行下面这条就可以：

```bash
idf.py build flash monitor
```

说明：

- 根目录保留的是当前生效的 `sdkconfig`
- `configs/idf/sdkconfig.defaults` 和 `configs/idf/sdkconfig.defaults.<target>` 会由顶层 CMake 自动加载
- `configs/idf/sdkconfig.ci*`、`configs/idf/sdkconfig.<xtal>.<target>` 主要作为模板和历史配置参考，不会被普通构建自动使用

如果你是用 VS Code 打开仓库根目录，也可以直接运行内置任务：

- `ESP-IDF: Build (root)`
- `ESP-IDF: Flash (root)`
- `ESP-IDF: Monitor (root)`
- `ESP-IDF: Build + Flash (root)`

## 当前版本特性

- 启动后自动连接 Wi-Fi
- 连接成功后使用 HTTP JSON 聚合心跳同步，默认心跳周期 20 秒
- 单次联网会话会尽量合并 `heartbeat`、`event`、`ack`、`full_status`
- 保留按键事件：短按、双击、长按开始、长按中、长按结束
- 已配置 GPIO 按键唤醒和定时唤醒，代码结构预留了未来“长周期任务 + 短周期联网窗口”扩展点

## 设备怎么配置 Wi-Fi

默认 Wi-Fi 已写入：

- SSID: `Gousun`
- Password: `hzh18960964436`

如果要修改，请执行：

```bash
idf.py menuconfig
```

然后进入：

```text
Sleepy Wi-Fi Poll Demo
```

可修改这些参数：

- `Wi-Fi SSID`
- `Wi-Fi Password`
- `Polling Server URL`
- `Device ID Override`
- `Poll Interval (ms)`

注意：

- `Polling Server URL` 需要改成你电脑在局域网里的地址，例如 `http://192.168.1.88:8000/poll`
- 不要填 `127.0.0.1`，那只代表 ESP32 自己

## 控制台怎么运行

当前推荐使用 `console/` 目录里的新结构。可以分别启动：

```bash
python console/backend/poll_server.py --host 0.0.0.0 --port 8000 --frontend-base-url http://127.0.0.1:8080
python console/scripts/serve_frontend.py --host 127.0.0.1 --port 8080
```

如果你希望一键拉起本地联调环境，也可以直接在仓库根目录运行：

```powershell
.\start_backends.ps1
```

## 设备轮询和服务器下发怎么测试

1. 让电脑和 ESP32 连接到同一个局域网
2. 在电脑上运行 `python console/backend/poll_server.py --host 0.0.0.0 --port 8000`
3. 查出电脑局域网 IP，例如 `192.168.1.88`
4. 在 `menuconfig` 里把 `Polling Server URL` 改成 `http://192.168.1.88:8000/poll`
5. 在仓库根目录编译烧录并打开串口：

```bash
idf.py build flash monitor
```

6. 观察串口日志，确认能看到：
   - Wi-Fi 连接成功
   - 开始轮询
   - 服务器返回内容
   - 按键事件日志
7. 在服务器终端输入一条消息，例如 `open_menu`
8. 等待下一次轮询，串口应出现 `【收到待下发】open_menu`

## 关键文件

- 固件入口：[main/main.c](./main/main.c)
- 按键管理：[main/button_manager.cpp](./main/button_manager.cpp)
- 工程配置：[main/Kconfig.projbuild](./main/Kconfig.projbuild)
- 后端入口：[console/backend/poll_server.py](./console/backend/poll_server.py)
- 前端入口：[console/frontend/landing/index.html](./console/frontend/landing/index.html)