# ISphere多功能传感器系统 - 软件固件开发需求文档
## 一、项目概述
### 1.1 项目背景
我们开发了一款基于ESP32-PICO-D4的多功能传感器设备，硬件已完成设计和生产，现需要专业团队开发完整的固件和配套软件系统。
### 1.2 项目目标
开发一套完整的传感器数据采集、传输、存储和可视化系统，实现：
- 实时采集传感器数据（压力、温度、加速度、陀螺仪）
- 通过WiFi进行数据传输
- 提供Web界面进行实时监控和配置
- 支持本地存储和云端数据同步
- 提供PC端配置工具
## 二、硬件配置
### 2.1 硬件架构
采用模块化设计，包含5块PCB板：
| 模块 | 核心组件 | 功能说明 |
|------|----------|----------|
| 主控板 | ESP32-PICO-D4 | WiFi通信、数据处理 |
| 压力传感器板 | MS583730BA01-50 | 高精度压力和温度测量 |
| 姿态传感器板 | BMI270 | 6轴IMU（加速度+陀螺仪）|
| 电源板 | 电源管理电路 | 3.3V稳压供电 |
| 下载板 | USB转UART | 固件下载和调试 |
✅ 传感器数据手册
---
## 三、软件功能需求
### 3.1 核心功能模块
#### 3.1.1 传感器数据采集模块
**功能要求：**
- [ ] MS583730BA01-50压力传感器驱动
- 实现I2C通信
- 温度补偿算法
- 精度：±1mbar
- 采样率：可配置（10-200Hz）
- [ ] BMI270 IMU传感器驱动
- 实现I2C通信
- 完整的初始化序列（包括NVM配置加载）
- 加速度和陀螺仪数据读取
- 数据单位转换（m/s²、rad/s）
- 可选的传感器校准功能
- [ ] 数据同步机制
- 统一时间戳
- 多传感器数据对齐
- 采样率可配置
**技术要求：**
- 使用FreeRTOS任务管理
- I2C总线共享处理
- 错误检测和恢复机制
#### 3.1.2 WiFi通信模块
**功能要求：**
- [ ] WiFi连接管理
- STA模式（连接到路由器）
- AP模式（配置模式，用于首次配置）
- AP+STA混合模式
- 自动重连机制
- 信号强度监测
- [ ] 网络配置
- Web配置界面（AP模式下）
- 配置信息持久化存储（NVS）
- 支持多个WiFi网络保存
**技术要求：**
- WiFi事件处理
- 网络状态LED指示
- 超时处理和重试机制
#### 3.1.3 数据管理模块
**功能要求：**
- [ ] 本地数据缓冲
- 循环缓冲区（至少1000个数据点）
- 内存管理优化
- 数据丢失保护
- [ ] 文件存储系统
- 数据保存为CSV格式
- 自动文件分片（1MB/文件）
- 文件系统：FAT（基于SPI Flash）
- 存储空间管理
- [ ] 云端数据同步
- HTTP/HTTPS上传
- 可配置的上传间隔
- 批量数据打包
- 断点续传支持
- 失败重试机制
**技术要求：**
- NVS存储配置参数
- SPIFFS或FATFS文件系统
- JSON数据格式
- 异步上传机制
#### 3.1.4 Web服务器模块
**功能要求：**
- [ ] HTTP服务器
- 静态页面服务
- RESTful API接口
- 响应式Web界面
- 移动端适配
- [ ] WebSocket实时通信
- 实时数据推送
- 支持多客户端连接
- 心跳保活机制
- [ ] Web功能页面
- 实时数据显示（数字和图表）
- 系统状态监控
- WiFi配置界面
- 传感器参数配置
- 数据导出功能
- 云端上传配置
- OTA固件升级（可选）
**技术要求：**
- 使用ESP-IDF HTTP服务器组件
- Chart.js实现数据可视化
- 前端框架建议：原生JavaScript或Vue.js
- 界面美观、操作简便
### 3.2 辅助功能
#### 3.2.1 系统管理
- [ ] 配置管理：所有参数可配置并持久化
- [ ] 固件升级：支持OTA无线升级
- [ ] 日志系统：分级日志输出到串口
- [ ] 错误处理：完善的异常捕获和恢复
- [ ] 看门狗：系统死锁检测和重启
#### 3.2.2 电源管理
- [ ] 低功耗模式：待机时降低功耗
- [ ] 电源监控：电压检测（可选）
- [ ] 唤醒机制：按键或定时唤醒
#### 3.2.3 状态指示
- [ ] LED指示灯控制
- WiFi未连接：慢闪（1Hz）
- WiFi连接中：快闪（5Hz）
- WiFi已连接：常亮
- 数据传输：闪烁
- 错误状态：特殊模式
---
## 四、数据接口规范
### 4.1 传感器数据格式
**JSON格式（WebSocket/HTTP）：**
```json
{
"timestamp": 1234567890,
"pressure": 1013.25,
"temperature": 25.6,
"accel_x": 0.123,
"accel_y": -0.456,
"accel_z": 9.789,
"gyro_x": 1.23,
"gyro_y": -4.56,
"gyro_z": 7.89
}
```
**CSV格式（文件存储）：**
```csv
timestamp,pressure,temperature,accel_x,accel_y,accel_z,gyro_x,gyro_y,gyro_z
1234567890,1013.25,25.6,0.123,-0.456,9.789,1.23,-4.56,7.89
```
### 4.2 RESTful API接口
**基础URL：** `http://{设备IP}`
| 接口 | 方法 | 功能 | 请求参数 | 返回数据 |
|------|------|------|----------|----------|
| `/api/status` | GET | 获取设备状态 | 无 | JSON: 系统状态 |
| `/api/data` | GET | 获取最新数据 | 无 | JSON: 传感器数据 |
| `/api/history` | GET | 获取历史数据 | start, end, limit | JSON: 数据数组 |
| `/api/export` | GET | 导出数据 | format=csv/json | 文件下载 |
| `/api/config` | GET | 获取配置 | 无 | JSON: 配置参数 |
| `/api/config` | POST | 更新配置 | JSON配置 | JSON: 成功/失败 |
| `/api/wifi` | POST | WiFi配置 | ssid, password | JSON: 成功/失败 |
| `/api/cloud` | POST | 云端配置 | JSON配置 | JSON: 成功/失败 |
| `/api/clear` | POST | 清除数据 | 无 | JSON: 成功/失败 |
| `/api/restart` | POST | 重启设备 | 无 | JSON: 成功/失败 |
### 4.3 WebSocket接口
**连接URL：** `ws://{设备IP}/ws`
**消息格式：**
```json
{
"type": "data",
"payload": {
"timestamp": 1234567890,
"pressure": 1013.25,
...
}
}
```
---
## 五、配套PC工具需求
### 5.1 WiFi配置工具
**平台：** Python 3.8+（跨平台）
**功能：**
- [ ] 串口扫描和连接
- [ ] 交互式WiFi配置
- [ ] 设备状态查看
- [ ] 命令行和图形界面两种模式
**技术栈：**
- PySerial（串口通信）
- tkinter或PyQt5（GUI，可选）
### 5.2 数据监控工具
**平台：** Python 3.8+（跨平台）
**功能：**
- [ ] 实时数据显示
- [ ] 数据可视化（曲线图）
- [ ] 数据记录到本地CSV文件
- [ ] 设备数据导出
- [ ] 批量设备管理（可选）
**技术栈：**
- requests（HTTP通信）
- websocket-client（WebSocket）
- matplotlib（数据可视化）
- pandas（数据处理）
---
## 六、开发环境和工具要求
### 6.1 固件开发
**必需：**
- ESP-IDF 5.3.1或更高版本
- CMake构建系统
- Git版本控制
**推荐：**
- VSCode + ESP-IDF插件
- 或 ESP-IDF命令行工具
### 6.2 编程语言
- 固件：C语言（ESP-IDF框架）
- Web前端：HTML + CSS + JavaScript
- PC工具：Python 3.8+
### 6.3 代码规范
- 遵循ESP-IDF编码规范
- 清晰的函数和变量命名
- 完善的代码注释（中英文均可）
- 模块化设计，便于维护
---
## 七、交付物要求
### 7.1 源代码
- [ ] 完整的ESP-IDF项目源码
- [ ] Web前端源码（HTML/CSS/JS）
- [ ] Python配置工具源码
- [ ] 构建脚本和配置文件
- [ ] .gitignore和版本控制配置
### 7.2 编译固件
- [ ] 可烧录的.bin固件文件
- [ ] 烧录说明和脚本
- [ ] 分区表配置
### 7.3 文档
- [ ] **用户手册**
- 硬件连接说明
- 首次配置步骤
- Web界面使用说明
- 常见问题排查
- [ ] **开发文档**
- 系统架构说明
- 模块功能说明
- API接口文档
- 代码结构说明
- [ ] **部署文档**
- 开发环境搭建
- 编译和烧录步骤
- 配置和测试流程
### 7.4 测试
- [ ] 基本功能测试报告
- [ ] 传感器精度测试
- [ ] WiFi连接稳定性测试
- [ ] 长时间运行测试（24小时+）
- [ ] Web界面兼容性测试
---
## 八、技术支持和培训
### 8.1 技术支持
- 提供硬件测试板2-3套供开发使用
- 提供现有测试代码和技术资料
- 开发过程中的技术答疑支持
### 8.2 培训要求
- 源码讲解和答疑（1-2次，线上或线下）
- 二次开发指导
- 问题排查培训
---
## 九、项目周期和里程碑
### 建议开发周期：6-8周
**第1-2周：**
- [ ] 开发环境搭建
- [ ] 传感器驱动开发和测试
- [ ] I2C通信验证
**第3-4周：**
- [ ] WiFi通信模块开发
- [ ] 数据管理模块开发
- [ ] 基本功能联调
**第5-6周：**
- [ ] Web服务器开发
- [ ] 前端界面开发
- [ ] 云端同步功能
**第7周：**
- [ ] PC配套工具开发
- [ ] 整体功能测试
- [ ] Bug修复
**第8周：**
- [ ] 文档编写
- [ ] 最终测试
- [ ] 项目交付
---
## 十、质量要求
### 10.1 性能指标
- 数据采样率：支持10-200Hz可配置
- 数据延迟：传感器到Web界面 < 100ms
- WiFi连接时间：< 10秒
- 系统稳定性：连续运行7天无重启
- 内存占用：< 150KB RAM
- Flash占用：< 2MB
### 10.2 稳定性要求
- 传感器读取成功率：> 99.9%
- WiFi重连成功率：> 95%
- 数据不丢失（内存缓冲保护）
- 异常自动恢复
### 10.3 用户体验
- Web界面响应快速（< 500ms）
- 操作简单直观
- 错误提示清晰
