smart-home/使用手册/手册指南/项目运行指南.md

# 智能家居火灾报警系统 - 项目运行指南

## 📋 项目概述

本项目是一个基于ESP32的智能火灾报警系统，包含以下核心功能：
- **火灾检测**：温度传感器、烟雾传感器、人体移动检测
- **红外控制**：空调遥控器功能，支持开关、温度、模式控制
- **433MHz通信**：RTM300-433M模块支持
- **WiFi连接**：支持SoftAP配置和云端数据上报
- **Android应用**：完整的移动端控制界面

## 🏗️ 项目结构

```
smart-home/
├── firefly_esp32/           # ESP32固件代码
│   ├── main/               # 主程序代码
│   ├── managed_components/ # ESP-IDF组件
│   └── sdkconfig          # ESP32配置文件
├── Smarthome_android/      # Android应用代码
│   └── app/               # Android应用主代码
├── cloud-backend-jdk8/     # 云端后台服务
├── python_test/           # Python测试脚本
└── ziyuan/               # SDK和资源文件
```

---

## 🔧 硬件运行指南

### 1. 硬件清单

#### 必需硬件：
- **ESP32开发板** (推荐ESP32-WROOM-32)
- **红外发射模块** (连接GPIO4)
- **温度传感器** (DS18B20或类似)
- **烟雾传感器** (MQ-2或类似)
- **人体红外传感器** (PIR)
- **蜂鸣器** (报警提示)
- **LED指示灯** (状态显示)
- **电源适配器** (5V/2A)

#### 可选硬件：
- **433MHz模块** (RTM300-433M)
- **雷达传感器** (距离检测)
- **外部天线** (提高WiFi信号)

### 2. 硬件连接图

```
ESP32 引脚连接：
┌─────────────────┬─────────────────┬─────────────────┐
│ ESP32 GPIO      │ 连接设备        │ 功能说明        │
├─────────────────┼─────────────────┼─────────────────┤
│ GPIO4           │ 红外发射器      │ 空调控制信号    │
│ GPIO2           │ LED指示灯       │ 状态显示        │
│ GPIO5           │ 蜂鸣器          │ 报警提示        │
│ GPIO18          │ 温度传感器      │ 火灾检测        │
│ GPIO19          │ 烟雾传感器      │ 烟雾检测        │
│ GPIO21          │ PIR传感器       │ 人体移动检测    │
│ GPIO22          │ 433MHz模块(SDA) │ 无线通信        │
│ GPIO23          │ 433MHz模块(SCL) │ 无线通信        │
│ GPIO0           │ 配置按钮        │ WiFi配置模式    │
│ 3.3V            │ 传感器电源      │ 供电            │
│ GND             │ 公共地线        │ 接地            │
└─────────────────┴─────────────────┴─────────────────┘
```

### 3. 硬件安装步骤

#### 步骤1：ESP32基础连接
```bash
1. 将ESP32开发板固定在面包板或PCB上
2. 连接电源线：5V → VIN，GND → GND
3. 连接USB数据线到电脑（用于烧录和调试）
```

#### 步骤2：传感器连接
```bash
# 温度传感器 (DS18B20)
VCC → 3.3V
GND → GND  
DATA → GPIO18

# 烟雾传感器 (MQ-2)
VCC → 3.3V
GND → GND
AOUT → GPIO19

# PIR人体传感器
VCC → 3.3V
GND → GND
OUT → GPIO21
```

#### 步骤3：红外发射器连接
```bash
# 红外发射器模块
VCC → 3.3V
GND → GND
DATA → GPIO4

注意：红外发射器需要对准空调接收窗口，距离建议1-3米
```

#### 步骤4：433MHz模块连接（可选）
```bash
# RTM300-433M模块
VCC → 3.3V
GND → GND
SDA → GPIO22
SCL → GPIO23
IRQ → GPIO25

注意：433MHz模块需要外接天线以提高通信距离
```

#### 步骤5：指示器连接
```bash
# LED指示灯
正极 → GPIO2
负极 → GND (通过220Ω电阻)

# 蜂鸣器
正极 → GPIO5
负极 → GND
```

### 4. 硬件测试验证

#### 基础功能测试：
```bash
1. 上电测试：LED应该闪烁，表示系统启动
2. WiFi测试：长按GPIO0按钮，进入配置模式
3. 传感器测试：用打火机测试烟雾传感器
4. 红外测试：对准空调测试遥控功能
```

---

## 💻 软件环境搭建

### 1. ESP32开发环境

#### 安装ESP-IDF 5.5.2：
```bash
# Windows环境
1. 下载ESP-IDF 5.5.2安装包
2. 安装到：D:\Espressif5.5.2\
3. 配置环境变量：
   - IDF_PATH=D:\Espressif5.5.2\Espressif\frameworks\esp-idf-v5.5.2
   - 添加到PATH：D:\Espressif5.5.2\Espressif\tools\

# 验证安装
idf.py --version
```

#### ESP32项目配置：
```bash
cd d:\XinJiaPo\Firefly_code\smart-home\firefly_esp32

# 配置项目
idf.py menuconfig

# 重要配置项：
- Component config → ESP32-specific → CPU frequency → 240 MHz
- Component config → FreeRTOS → Tick rate → 1000 Hz
- Component config → Wi-Fi → WiFi Task Core ID → Core 1
- Partition Table → Custom partition table CSV → partitions.csv
```

### 2. Android开发环境

#### 安装要求：
```bash
- Android Studio 2023.1+
- JDK 11+
- Android SDK API 34
- Gradle 8.11.1
```

#### 项目配置：
```bash
cd d:\XinJiaPo\Firefly_code\smart-home\Smarthome_android\Smarthome_android

# 同步项目
./gradlew sync

# 编译项目
./gradlew assembleDebug
```

### 3. Python测试环境

#### 安装依赖：
```bash
pip install requests
pip install pyserial
pip install json
```

---

## 🚀 系统部署流程

### 1. ESP32固件烧录

#### 编译固件：
```bash
cd d:\XinJiaPo\Firefly_code\smart-home\firefly_esp32

# 清理构建
idf.py fullclean

# 编译固件
idf.py build

# 烧录固件
idf.py -p COM3 flash

# 监控日志
idf.py -p COM3 monitor
```

#### 烧录验证：
```bash
# 查看启动日志
I (0) cpu_start: Starting scheduler on APP CPU.
I (1000) MAIN: 🔥 智能火灾报警系统启动
I (1010) WIFI: WiFi初始化完成
I (1020) HTTP: HTTP服务器启动在端口80
```

### 2. Android应用安装

#### 编译APK：
```bash
cd d:\XinJiaPo\Firefly_code\smart-home\Smarthome_android\Smarthome_android

# 编译Debug版本
./gradlew assembleDebug

# APK位置：
app/build/outputs/apk/debug/app-debug.apk
```

#### 安装到设备：
```bash
# 通过ADB安装
adb install app/build/outputs/apk/debug/app-debug.apk

# 或者直接拷贝APK到手机安装
```

### 3. 系统配置

#### WiFi配置：
```bash
1. 长按ESP32的GPIO0按钮3秒
2. ESP32进入SoftAP模式，LED快速闪烁
3. 手机连接WiFi：ESP32-Config
4. 浏览器打开：192.168.4.1
5. 输入家庭WiFi信息并保存
6. ESP32重启后自动连接WiFi
```

#### 设备配对：
```bash
1. 打开Android应用
2. 点击"添加设备"
3. 扫描局域网中的ESP32设备
4. 选择设备并完成配对
5. 测试空调控制功能
```

---

## 🔍 功能测试指南

### 1. 火灾报警测试

#### 温度报警测试：
```bash
# 使用热风枪或打火机加热温度传感器
# 预期结果：
- 温度超过60°C时触发报警
- 蜂鸣器响起
- LED红灯闪烁
- Android应用收到报警推送
```

#### 烟雾报警测试：
```bash
# 在烟雾传感器附近点燃纸张
# 预期结果：
- 检测到烟雾时触发报警
- 蜂鸣器响起
- LED红灯闪烁
- 云端收到报警数据
```

### 2. 红外控制测试

#### 空调控制测试：
```bash
# 在Android应用中测试：
1. 点击"电源"按钮 → 空调开关
2. 点击"温度+"按钮 → 温度上升
3. 点击"温度-"按钮 → 温度下降
4. 点击"模式"按钮 → 制冷/制热/除湿循环
5. 点击"风量"按钮 → 风量调节

# 验证方法：
- 观察空调面板显示变化
- 检查ESP32日志输出
- 确认红外信号发送成功
```

### 3. 网络功能测试

#### WiFi连接测试：
```bash
# 检查ESP32日志：
I (5000) WIFI: WiFi连接成功
I (5010) WIFI: IP地址: 192.168.1.100
I (5020) HTTP: HTTP服务器启动成功
```

#### 云端通信测试：
```bash
# 使用Python脚本测试：
cd d:\XinJiaPo\Firefly_code\smart-home\python_test
python test_cloud_alarm_integration.py

# 预期结果：
- 成功连接云端服务器
- 报警数据上传成功
- 收到服务器响应
```

---

## 🛠️ 故障排除

### 1. 硬件问题

#### ESP32无法启动：
```bash
问题：上电后无反应
解决：
1. 检查电源电压（应为5V/2A）
2. 检查USB线连接
3. 按下RST按钮重启
4. 检查GPIO0是否被误触发
```

#### 传感器无读数：
```bash
问题：传感器数据为0或异常
解决：
1. 检查传感器供电（3.3V）
2. 检查信号线连接
3. 用万用表测试传感器输出
4. 更换传感器模块
```

#### 红外控制无效：
```bash
问题：空调不响应红外信号
解决：
1. 检查红外发射器方向
2. 减少发射距离（1-2米）
3. 检查GPIO4连接
4. 重新配对空调遥控器
```

### 2. 软件问题

#### 编译错误：
```bash
问题：ESP32编译失败
解决：
1. 检查ESP-IDF版本（需要5.5.2）
2. 清理构建：idf.py fullclean
3. 检查sdkconfig配置
4. 更新组件：idf.py update-dependencies
```

#### WiFi连接失败：
```bash
问题：无法连接WiFi
解决：
1. 检查WiFi密码正确性
2. 确认WiFi为2.4GHz频段
3. 重置WiFi配置：长按GPIO0按钮
4. 检查路由器MAC过滤设置
```

#### Android应用崩溃：
```bash
问题：应用启动崩溃
解决：
1. 检查Android版本兼容性
2. 清除应用数据和缓存
3. 重新安装APK
4. 查看logcat日志定位问题
```

### 3. 网络问题

#### 设备发现失败：
```bash
问题：Android应用找不到ESP32设备
解决：
1. 确认手机和ESP32在同一WiFi网络
2. 检查路由器防火墙设置
3. 手动输入ESP32 IP地址
4. 重启路由器和设备
```

#### 云端通信失败：
```bash
问题：无法上传报警数据
解决：
1. 检查网络连接
2. 验证云端服务器状态
3. 检查防火墙设置
4. 使用Python脚本测试API
```

---

## 📊 性能监控

### 1. 系统监控指标

#### ESP32性能监控：
```bash
# 内存使用情况
I (10000) HEAP: 剩余内存: 180KB/320KB

# CPU使用率
I (10010) CPU: CPU使用率: 45%

# WiFi信号强度
I (10020) WIFI: RSSI: -45dBm (信号良好)

# 传感器读取频率
I (10030) SENSOR: 传感器更新频率: 1Hz
```

#### 网络性能监控：
```bash
# HTTP响应时间
平均响应时间: 50ms
最大响应时间: 200ms

# 数据上传成功率
上传成功率: 98.5%
重试次数: 平均1.2次
```

### 2. 日志分析

#### 关键日志标识：
```bash
🔥 - 系统启动和关键事件
✅ - 操作成功
⚠️ - 警告信息
❌ - 错误信息
🎯 - 调试信息
```

#### 日志文件位置：
```bash
ESP32日志：通过串口监控获取
Android日志：adb logcat | grep "Esp32JsBridge"
云端日志：服务器日志文件
```

---

## 📝 维护指南

### 1. 定期维护

#### 每周检查：
```bash
1. 检查设备运行状态
2. 清理传感器灰尘
3. 检查网络连接稳定性
4. 测试报警功能
```

#### 每月维护：
```bash
1. 更新固件版本
2. 备份配置数据
3. 检查硬件连接
4. 性能数据分析
```

### 2. 版本更新

#### ESP32固件更新：
```bash
cd d:\XinJiaPo\Firefly_code\smart-home\firefly_esp32

# 拉取最新代码
git pull origin main

# 编译新固件
idf.py build

# OTA更新（推荐）
python simple_ota.ps1

# 或串口更新
idf.py -p COM3 flash
```

#### Android应用更新：
```bash
cd d:\XinJiaPo\Firefly_code\smart-home\Smarthome_android\Smarthome_android

# 更新版本号
# 编辑 app/build.gradle.kts
versionCode = 2
versionName = "1.1.0"

# 编译新版本
./gradlew assembleRelease
```

---

## 📞 技术支持

### 联系信息
- **项目负责人**：[原开发者姓名]
- **技术文档**：项目根目录下的各种.md文件
- **代码仓库**：Git仓库地址
- **问题反馈**：GitHub Issues或内部问题跟踪系统

### 常用命令速查
```bash
# ESP32相关
idf.py build                 # 编译固件
idf.py -p COM3 flash        # 烧录固件
idf.py -p COM3 monitor      # 监控日志
idf.py menuconfig           # 配置项目

# Android相关
./gradlew assembleDebug     # 编译Debug版本
./gradlew assembleRelease   # 编译Release版本
adb install app-debug.apk   # 安装APK
adb logcat                  # 查看日志

# Python测试
python test_cloud_alarm_integration.py  # 云端测试
python test_ir_control.py              # 红外测试
python wifi_config_simple.py           # WiFi配置
```

---

## ⚠️ 重要注意事项

1. **安全警告**：
   - 火灾报警系统仅作为辅助设备，不能替代专业消防设备
   - 定期测试系统功能，确保正常工作
   - 传感器需要定期校准和清洁

2. **电气安全**：
   - 使用合适的电源适配器（5V/2A）
   - 避免短路和过载
   - 在潮湿环境中注意防水

3. **网络安全**：
   - 定期更新固件以修复安全漏洞
   - 使用强密码保护WiFi网络
   - 监控异常网络活动

4. **数据隐私**：
   - 了解数据上传和存储政策
   - 定期备份重要配置数据
   - 注意个人隐私保护

---

## 📚 相关文档

本项目包含以下详细指南文档：

### 核心文档：
- **[项目运行指南.md](./项目运行指南.md)** - 本文档，项目总体概述
- **[硬件接线详细指南.md](./硬件接线详细指南.md)** - 详细的硬件连接和电路图
- **[软件配置详细指南.md](./软件配置详细指南.md)** - 开发环境和软件配置
- **[故障排除与维护指南.md](./故障排除与维护指南.md)** - 故障诊断和维护流程

### 专项文档：
- **[433MHz_使用指南.md](./433MHz_使用指南.md)** - 433MHz模块配置和使用
- **[WiFi省电测试指南.md](./WiFi省电测试指南.md)** - WiFi功耗管理
- **[ESP32编译烧录指南.md](./ESP32编译烧录指南.md)** - 固件编译和烧录

### 技术文档：
- **[SDK_data_hex转红外脉冲算法详解.md](./SDK_data_hex转红外脉冲算法详解.md)** - 红外信号处理算法
- **[diagnose_ir_system.md](./diagnose_ir_system.md)** - 红外系统诊断
- **各种修复和优化文档** - 项目根目录下的其他.md文件

### 快速参考：

#### 🚀 快速启动流程：
1. **硬件连接** → 参考《硬件接线详细指南》
2. **软件配置** → 参考《软件配置详细指南》
3. **固件烧录** → 参考《ESP32编译烧录指南》
4. **功能测试** → 参考本文档的测试章节
5. **故障排除** → 参考《故障排除与维护指南》

#### 📞 获取帮助：
- **硬件问题** → 查看硬件接线详细指南
- **软件问题** → 查看软件配置详细指南  
- **网络问题** → 查看WiFi配置相关文档
- **功能异常** → 查看故障排除与维护指南

---

**文档版本**：v1.0  
**最后更新**：2026年2月26日  
**适用版本**：ESP32固件v2.1.0，Android应用v1.0.0

**文档完整性检查**：
- ✅ 项目运行指南.md
- ✅ 硬件接线详细指南.md  
- ✅ 软件配置详细指南.md
- ✅ 故障排除与维护指南.md