# photo-frame

**Repository Path**: yookoo/photo-frame

## Basic Information

- **Project Name**: photo-frame
- **Description**: 基于esp32的电子墨水屏相册
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-02-23
- **Last Updated**: 2026-02-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ESP32-S3 电子墨水屏数码相框

一个基于 ESP32-S3 的电子墨水屏数码相框项目，支持通过 WiFi 从服务器获取图片并自动显示。项目包含客户端（ESP32-S3）和服务器端（Spring Boot）两部分。

## 项目结构

```
photo-frame/
├── esp32s3-client/          # ESP32-S3 客户端
│   ├── src/
│   │   ├── Config.h/cpp          # 配置管理
│   │   ├── DisplayManager.cpp    # 显示管理
│   │   ├── EPDDriver.cpp         # 墨水屏驱动
│   │   ├── Network.cpp           # 网络连接
│   │   ├── WebServer.cpp         # Web 服务器
│   │   └── main.cpp              # 主程序
│   ├── platformio.ini            # PlatformIO 配置
│   └── include/                  # 头文件
│
└── img-provider-server/     # 图片提供服务器
    ├── src/main/
    │   ├── java/
    │   │   └── org/example/imgproviderserver/
    │   │       ├── controller/   # 控制器
    │   │       ├── service/      # SMB 服务
    │   │       └── config/       # 配置类
    │   └── resources/
    │       ├── application.yml   # 应用配置
    │       └── templates/        # FreeMarker 模板
    ├── pom.xml                   # Maven 配置
    └── SMB_USAGE.md              # SMB 使用说明
```

## 功能特性

### ESP32-S3 客户端

- 🖥️ **电子墨水屏显示**：支持高分辨率墨水屏显示（800x480）
- 📶 **WiFi 连接**：自动连接到指定 WiFi 网络
- 🌐 **Web 配置界面**：可通过浏览器配置 WiFi 和服务器参数
- 🔄 **随机图片展示**：支持按钮切换和自动刷新
- ⚙️ **配置持久化**：使用 NVS 存储配置参数
- 📡 **图片下载**：从服务器获取并显示图片

### 图片服务器

- 📁 **SMB/CIFS 支持**：访问局域网共享文件夹
- 🌍 **REST API**：提供文件列表和图片访问接口
- 🖼️ **图片预览**：支持浏览器浏览图片
- 📤 **文件下载**：直接提供图片文件下载

## 硬件要求

### ESP32-S3 客户端

- **开发板**：ESP32-S3-DevKitM-1
- **墨水屏**：3.97 英寸4色电子墨水屏（800x480 分辨率） 型号: GDEM0397F81
- **存储**：16MB Flash + 8MB PSRAM
- **按钮**：GPIO0 按键
- **LED**：GPIO1 指示灯

### 引脚定义

| 功能 | GPIO 引脚 |
|------|----------|
| 按钮输入 | GPIO 0 |
| LED 输出 | GPIO 1 |

## 软件依赖

### ESP32-S3 客户端

- **PlatformIO**：开发环境
- **Arduino Framework**：开发框架
- **ArduinoJson 7.0+**：JSON 解析

### 图片服务器

- **Java 17+**：运行环境
- **Maven 3.6+**：构建工具
- **Spring Boot 4.0.2**：Web 框架
- **jcifs-ng 2.1.10**：SMB 客户端库

## 快速开始

### 1. 配置图片服务器

#### 修改配置文件

编辑 `img-provider-server/src/main/resources/application.yml`：

```yaml
smb:
  server: 192.168.1.100      # SMB 服务器地址
  port: 445                   # SMB 端口
  share: photos               # 共享文件夹名称
  username: guest             # 用户名
  password: ""                # 密码
  domain: ""                  # 域（可选）
```

#### 启动服务器

```bash
cd img-provider-server
mvn spring-boot:run
```

服务器将在 `http://localhost:8080` 启动。

#### API 接口

- **获取文件列表**：`GET /api/smb/files?path=/`
- **获取图片**：`GET /api/smb/image?path=/photo.jpg`
- **文件浏览**：`http://localhost:8080/browser`

### 2. 编译并上传 ESP32-S3 固件

```bash
cd esp32s3-client
pio run
pio run --target upload
```

### 3. 配置 ESP32-S3

#### 方法一：Web 配置界面

1. 启动 ESP32-S3，连接到 WiFi 热点（以 "PhotoFrame-" 开头）
2. 打开浏览器访问 `192.168.4.1`
3. 配置以下参数：
   - WiFi SSID：你的 WiFi 网络名称
   - WiFi 密码：WiFi 密码
   - 服务器 IP：图片服务器地址
   - 服务器端口：8080
   - SMB 路径：图片文件夹路径
   - 刷新间隔：自动刷新时间（分钟，0 为禁用）

#### 方法二：串口配置

通过串口监视器（115200 波特率）查看状态和手动切换图片。

### 4. 使用说明

- **显示随机图片**：按下 GPIO0 按钮
- **串口命令**：
  - `next`：显示下一张随机图片
  - `list`：显示文件列表
- **自动刷新**：根据配置的时间间隔自动切换图片
- **Web 配置**：访问 `http://<ESP32-IP>` 查看和修改配置

## SMB 文件服务器配置

详细的 SMB 配置说明请参考 [SMB_USAGE.md](img-provider-server/SMB_USAGE.md)。

### Windows 设置共享文件夹

1. 右键点击要共享的文件夹 → 属性 → 共享
2. 点击"共享..."按钮
3. 选择用户并设置权限（建议使用 Guest 用户）
4. 确保防火墙允许文件共享

### Linux/NAS 设置共享文件夹

在 Samba 配置文件（`/etc/samba/smb.conf`）中添加：

```ini
[photos]
  path = /path/to/photos
  browseable = yes
  read only = yes
  guest ok = yes
  create mask = 0777
```

## 项目截图

### ESP32-S3 串口输出

```
========== EPD Photo Frame Start ==========
Setting up pins...
Connecting to WiFi...
WiFi connected! IP: 192.168.1.50
Getting file list...
Found 156 files
Displaying random image...
========== Ready ==========
Web config: http://192.168.1.50
```

## 常见问题

### ESP32-S3 无法连接 WiFi

- 检查 WiFi SSID 和密码是否正确
- 确认 WiFi 信号强度
- 查看串口输出获取详细错误信息

### 无法获取图片列表

- 检查服务器 IP 和端口配置
- 确认服务器已启动
- 检查 SMB 共享路径是否正确
- 查看服务器日志

### 墨水屏显示异常

- 检查 SPI 连接是否正确
- 确认墨水屏驱动初始化成功
- 查看串口错误信息

## 开发说明

### ESP32-S3 客户端开发

- 使用 PlatformIO 进行开发
- 主循环处理 Web 服务器、按钮和自动刷新
- 图片数据缓冲区大小：96KB (800x480 / 4)

### 服务器端开发

- 使用 Spring Boot + Maven
- SMB 服务封装在 `SmbService` 类中
- FreeMarker 模板用于 Web 界面

## 许可证

本项目采用 MIT 许可证。

## 贡献

欢迎提交 Issue 和 Pull Request！

## 作者

Created with ❤️ for photo enthusiasts