# shahua **Repository Path**: xunli/shahua ## Basic Information - **Project Name**: shahua - **Description**: 这是沙画制作的嵌入式代码 - **Primary Language**: C++ - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2025-07-10 - **Last Updated**: 2025-12-31 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 🎨 ESP32-WROOM-32E 沙画绘图机控制系统 ## 📋 项目概述 这是一个基于ESP32-WROOM-32E的智能沙画绘图机控制系统，采用极坐标绘图方式，使用28BYJ-48步进电机驱动。系统支持WiFi控制、SD卡图案文件加载、实时绘图和智能回零等功能。 ## ✨ 主要特性 ### 🎯 核心功能 - **极坐标绘图系统** - 基于角度(θ)和半径(ρ)的精确绘图 - **智能回零功能** - 支持限位开关检测和强制归零 - **图案文件支持** - 加载.thr格式图案文件进行绘图 - **暂停/继续功能** - 绘图过程中可随时暂停和恢复 - **WiFi网络控制** - 支持智能配网和远程控制 ### 🔧 技术特点 - **双控制器架构** - StepperController负责回零，MotionController负责绘图 - **实时补偿算法** - 角度轴转动时自动补偿半径轴位置误差 - **多模式绘图** - 支持流式模式和传统模式绘图 - **UTF-8中文支持** - 完整的中文调试信息显示 ## 🛠️ 硬件配置 ### 主控制器 - **主板**: ESP32-WROOM-32E-N4 (38个GPIO) - **电机**: 28BYJ-48步进电机 × 2 - **驱动**: ULN2003驱动板 × 2 - **存储**: SD卡模块 (SPI接口) - **指示**: WS2812 LED灯带 + 状态LED ### 引脚配置 (ESP32-WROOM-32E) ```cpp // 角度轴电机 (THETA) #define THETA_IN1_PIN 14 #define THETA_IN2_PIN 27 #define THETA_IN3_PIN 26 #define THETA_IN4_PIN 25 #define THETA_HOME_PIN 32 // 限位开关 // 半径轴电机 (RHO) #define RHO_IN1_PIN 16 #define RHO_IN2_PIN 4 #define RHO_IN3_PIN 15 #define RHO_IN4_PIN 13 #define RHO_HOME_PIN 33 // 限位开关 // SD卡 SPI接口 #define SD_MISO_PIN 19 #define SD_SCK_PIN 18 #define SD_MOSI_PIN 23 #define SD_CS_PIN 5 // 系统控制 #define STATUS_LED_PIN 2 // 状态LED #define WS2812_PIN 21 // WS2812灯带 #define WFRS_BUTTON_PIN 17 // WiFi重置按钮 ``` ## 📂 项目结构 ``` 📁 shahua_ESP32_32E/ ├── 📁 src/ # 源代码目录 │ ├── main.cpp # 主程序入口 │ ├── command_executor.cpp # 统一命令执行器 │ ├── motion_controller.cpp # 运动控制核心 │ ├── pattern_loader.cpp # 图案文件处理 │ ├── serial_command_handler.cpp # 串口命令处理 │ ├── wifi_manager.cpp # WiFi连接管理 │ ├── mqtt_manager.cpp # MQTT通信管理 │ ├── led_manager.cpp # LED硬件驱动 │ ├── led_control_center.cpp # LED业务逻辑 │ ├── device_state_manager.cpp # 设备状态管理 │ └── button_manager.cpp # 物理按键处理 ├── 📁 include/ # 头文件目录 │ ├── pin_config.h # ESP32-WROOM-32E引脚配置 │ ├── command_executor.h # 命令执行器接口 │ ├── motion_controller.h # 运动控制接口 │ ├── pattern_loader.h # 图案加载接口 │ ├── serial_command_handler.h # 串口处理接口 │ ├── wifi_manager.h # WiFi管理接口 │ ├── mqtt_manager.h # MQTT管理接口 │ ├── led_manager.h # LED硬件接口 │ ├── led_control_center.h # LED业务接口 │ ├── device_state_manager.h # 状态管理接口 │ └── button_manager.h # 按键管理接口 ├── 📁 docs/ # 完整文档体系 │ ├── PROJECT_ARCHITECTURE.md # 🏗️ 系统架构详解 │ ├── DEVELOPMENT_GUIDE.md # 🛠️ 开发指南和规范 │ ├── PROJECT_SUMMARY.md # 📈 项目总结报告 │ ├── COMMAND_REFERENCE.md # 📋 命令参考手册 │ ├── WIRING_GUIDE.md # 🔌 硬件接线指南 │ ├── PROJECT_CONFIG.md # ⚙️ 配置说明文档 │ ├── QUICK_START.md # 🚀 快速开始指南 │ ├── MQTT_MANAGER_GUIDE.md # 🌐 MQTT功能指南 │ └── ESP32_MIGRATION_SUMMARY.md # 🔄 硬件平台迁移记录 ├── 📁 json/ # 配置文件 │ ├── pattern.json # 图案配置模板 │ └── emqxsl-ca.crt # MQTT SSL证书 └── platformio.ini # PlatformIO项目配置 ``` ## 🚀 快速开始 ### 1. 环境准备 ```bash # 安装PlatformIO pip install platformio # 克隆项目 git clone cd shahua_ESP32_32E ``` ### 2. 编译上传 ```bash # 编译项目 pio run # 上传到ESP32-WROOM-32E pio run --target upload # 监视串口输出 pio device monitor ``` ### 3. 硬件连接 参考 [docs/WIRING_GUIDE.md](docs/WIRING_GUIDE.md) 完成硬件接线。 ### 4. 首次使用操作步骤 #### 🔌 连接设备 1. 使用USB线连接ESP32-WROOM-32E到电脑 2. 打开串口监视器，设置波特率为 **115200** 3. 系统启动后会显示初始化信息 #### 🏠 必须先归零 ```bash # 首次使用必须执行归零操作 home ``` 等待归零完成（约30-60秒），系统会自动找到两个限位开关的位置。 #### 🎨 开始绘图 ```bash # 查看可用图案文件 list # 系统已自动加载第一个图案，直接开始绘制 start # 或者加载指定图案 load heart_fixed.thr start ``` #### ⚡ 常用操作 ```bash status # 查看系统状态 stop # 暂停绘图 start # 继续绘图 position # 查看当前位置 list # 查看所有图案文件 ``` ### 5. WiFi配网（可选） #### 方法1: 物理按键配网 1. 长按 **GPIO17** 按键2秒 2. 系统重启进入配网模式 3. 手机连接WiFi热点: **"沙画绘图机"** 4. 浏览器打开: `192.168.4.1` 5. 输入WiFi信息完成配网 #### 方法2: 串口命令配网 ```bash config # 启动配网模式 # 手机连接热点: "沙画绘图机" # 浏览器配置: 192.168.4.1 ``` #### 方法3: 直接连接 ```bash wifi MyWiFi 12345678 # 直接连接指定WiFi webserver # 启动Web服务器 ``` ### 6. 完整使用流程示例 ```bash # === 开机后的完整操作流程 === # 1. 系统启动，等待初始化完成 # 2. 执行归零（首次使用必须） home # 3. 查看可用图案 list # 4. 加载心形图案 load heart_fixed.thr # 5. 开始绘制 start # 6. 绘制完成后，可以重复或切换图案 start # 重复绘制当前图案 load circle_fixed.thr # 切换到圆形图案 start # 绘制圆形 # 7. 查看系统状态 status # 8. 设置参数优化（可选） setspeed 400 # 设置绘图速度 setaccel 800 # 设置加速度 ``` ### ⚠️ 重要提醒 1. **首次使用必须归零**: 开机后必须先执行 `home` 命令 2. **串口波特率**: 115200，支持中文显示 3. **SD卡格式**: FAT32格式，存放.thr图案文件 4. **按键功能变更**: 物理按键仅用于WiFi配网，绘图控制改为串口命令 5. **安全操作**: 异常时立即输入 `stop` 命令暂停 6. **电机保护**: 长时间不用可执行 `disable` 禁用电机 ## 🎮 控制命令 ### 🚀 快速命令（新手必读） ```bash help # 显示所有可用命令 home # 🏠 归零操作（首次使用必须） start # 🎨 开始绘图 stop # ⏸️ 暂停绘图 list # 📂 查看图案文件 status # 📊 查看系统状态 ``` ### 📋 完整命令分类 #### 🏠 基础控制 ```bash home # 智能回零 start/draw # 开始绘图 stop # 暂停绘图 status/s # 查看系统状态 help/h # 显示帮助 ``` #### 🎨 图案管理 ```bash list # 列出SD卡图案文件 load <文件名> # 加载图案文件 load heart_fixed.thr # 示例：加载心形图案 ``` #### 🔧 运动控制 ```bash move <θ> <ρ> # 移动到极坐标位置 moveto <θ步> <ρ步> # 移动到步数位置 position # 查看当前位置 enable # 启用电机 disable # 禁用电机 ``` #### ⚙️ 参数设置 ```bash setspeed <速度> # 设置运动速度 (1-1000步/秒) setaccel <加速度> # 设置加速度 (1-2000步/秒²) compensation <系数> # 设置补偿系数 (0.0-1.0) rotsteps <步数> # 设置角度轴每圈步数 radsteps <步数> # 设置半径轴最大步数 ``` #### 🌐 WiFi功能 ```bash config # 启动WiFi配网模式 wifi <密码> # 手动连接WiFi wifireset # 清除WiFi配置 webserver # 启动Web服务器 download <文件> # 下载图案文件到SD卡 defaults # 下载默认图案包 ``` #### 💡 LED控制 ```bash ledon # 启用WS2812灯带 ledoff # 禁用WS2812灯带 brightness <0-255> # 设置灯带亮度 ``` #### 🔍 性能监控 ```bash taskinfo # 显示双核任务信息 coreinfo # 显示CPU核心状态 meminfo # 显示内存使用情况 sdinfo # 显示SD卡信息 ``` 完整命令列表请参考 [docs/COMMAND_REFERENCE.md](docs/COMMAND_REFERENCE.md) ## 🎨 图案文件格式 图案文件采用.thr格式，每行包含一个点的极坐标： ``` θ ρ 0.000 0.200 0.785 0.200 1.571 0.200 ... ``` - **θ**: 角度（弧度制，0-2π） - **ρ**: 半径（0-1相对范围） ## 🔧 系统配置 ### 电机参数 ```cpp ROTATION_STEPS_PER_REV = 8200; // 角度轴每圈步数 RADIUS_MAX_STEPS = 4400; // 半径轴最大步数 MAX_SPEED_SPS = 300; // 最大速度(步/秒) COMPENSATION_FACTOR = 0.25; // 补偿系数 ``` ### WiFi配置 - 支持自动智能配网 - 默认AP名称: `沙画绘图机` - 配网页面: `192.168.4.1` - 支持Web控制界面 ## 🛠️ 开发指南 ### 项目文档 - **[项目架构详解](docs/PROJECT_ARCHITECTURE.md)** - 深入了解系统架构设计 - **[开发指南](docs/DEVELOPMENT_GUIDE.md)** - 完整的开发环境和规范 - **[命令参考](docs/COMMAND_REFERENCE.md)** - 所有可用命令的详细说明 - **[接线指南](docs/WIRING_GUIDE.md)** - 硬件连接和配置 ### 核心架构概览 ```mermaid graph TB subgraph "用户接口层" A[串口命令] B[MQTT远程控制] C[Web界面控制] D[物理按键] end subgraph "命令处理层" E[CommandExecutor
统一命令执行器] end subgraph "业务逻辑层" F[MotionController
运动控制器] G[PatternLoader
图案加载器] H[DeviceStateManager
状态管理器] end subgraph "硬件抽象层" I[LEDManager
LED驱动] J[AccelStepper
电机驱动] K[SD卡接口] end A --> E B --> E C --> E D --> E E --> F E --> G E --> H F --> J G --> K H --> I ``` ### 快速开发入门 1. **克隆项目**: `git clone [项目URL]` 2. **环境配置**: 按照 [开发指南](docs/DEVELOPMENT_GUIDE.md) 配置开发环境 3. **理解架构**: 阅读 [项目架构](docs/PROJECT_ARCHITECTURE.md) 了解系统设计 4. **添加功能**: 参考开发指南中的模块开发规范 5. **测试验证**: 使用内置的调试和测试工具 ## 📊 性能参数 (ESP32-WROOM-32E) - **CPU频率**: 240MHz (双核) - **可用内存**: ~320KB - **Flash存储**: 4MB - **绘图精度**: ±0.1mm - **最大绘图速度**: 500步/秒 (相比ESP32-C3提升67%) - **角度分辨率**: 0.022°/步 - **半径分辨率**: 0.0125mm/步 - **SD卡支持**: ✅ 完整支持 - **WS2812灯带**: ✅ 完整支持 - **WiFi范围**: 100米（开放环境） - **同时连接数**: 最多4个客户端 ## 🐛 故障排除 ### 常见问题 1. **回零失败** - 检查限位开关连接，或使用强制归零 2. **绘图位置偏移** - 重新执行回零操作 3. **WiFi连接失败** - 重启设备或重新配网 4. **电机不转** - 检查电源和引脚连接 5. **SD卡读取失败** - 检查SD卡格式(FAT32)和SPI连接 6. **WS2812不亮** - 检查电源电压和数据线连接 详细故障排除请参考 [docs/PROJECT_CONFIG.md](docs/PROJECT_CONFIG.md) ## 📝 更新日志 ### v2.4.0 (2025-09-18) - 架构优化和文档完善版 🎉 - 🏗️ **架构重构**: 完成模块化架构设计，分层清晰，职责明确 - 📚 **文档体系**: 新增PROJECT_ARCHITECTURE.md、DEVELOPMENT_GUIDE.md、PROJECT_SUMMARY.md - 🔧 **命令统一**: CommandExecutor统一处理串口和MQTT命令，消除代码重复 - 💡 **LED架构**: 实现LEDControlCenter业务逻辑 + LEDManager硬件驱动双层架构 - 🛡️ **状态管理**: DeviceStateManager提供线程安全的统一状态管理 - 🌐 **网络优化**: MQTT集成CommandExecutor，支持绘图过程中的网络任务处理 - 🔍 **调试优化**: 优化串口输出频率，改善用户体验 - 📖 **代码规范**: 统一代码风格、注释规范和错误处理机制 ### v2.3.0 (2025-08-25) - ESP32-WROOM-32E升级版 - 🎉 **硬件平台升级**: 从ESP32-C3FH4迁移到ESP32-WROOM-32E - ✅ **SD卡支持**: 完整恢复SD卡图案文件读取功能 - ✅ **性能提升**: CPU频率从160MHz提升到240MHz - ✅ **内存优化**: 可用内存从245KB提升到320KB - ✅ **LED增强**: 完整的WS2812灯带控制功能 - ✅ **引脚优化**: 充分利用ESP32-WROOM-32E的38个GPIO - ✅ **Web服务器**: 支持浏览器远程控制 - ✅ **MQTT通信**: 完整的MQTT远程控制功能 ### v2.2.0 (2025-01-31) - ESP32-C3版本 - ✅ 修复回零超时强制归零功能 - ✅ 实现暂停/继续绘图功能 - ✅ 修复位置同步问题 - ✅ 优化电机控制逻辑 - ✅ 完善中文调试信息 ### v2.0.0 - 基础架构版本 - 🎉 重构双控制器架构 - 🎉 添加智能WiFi配网 - 🎉 实现图案文件系统 ## 📄 许可证 本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件 ## 🤝 贡献指南 欢迎提交 Issue 和 Pull Request！ 1. Fork 本仓库 2. 创建特性分支 (`git checkout -b feature/AmazingFeature`) 3. 提交更改 (`git commit -m 'Add some AmazingFeature'`) 4. 推送到分支 (`git push origin feature/AmazingFeature`) 5. 创建 Pull Request ## 📞 联系方式 - 项目维护者: [您的名字] - 邮箱: [您的邮箱] - 项目链接: [GitHub仓库地址] --- ⭐ 如果这个项目对您有帮助，请给它一个星标！