smart-home/使用手册/手册指南/故障排除与维护指南.md

# ESP32智能火灾报警系统 - 故障排除与维护指南

## 🚨 常见故障诊断

### 1. 硬件故障

#### 🔋 电源问题

**故障现象：ESP32无法启动或频繁重启**
```
症状：
- 上电后无任何反应
- LED不亮或闪烁异常
- 串口无输出信息
- 设备频繁重启
```

**诊断步骤：**
```bash
1. 检查电源适配器输出电压
   万用表测量：应为5V ±0.25V
   
2. 检查ESP32供电电压
   测量VIN引脚：应为5V
   测量3.3V引脚：应为3.3V ±0.1V
   
3. 检查电流消耗
   正常工作电流：300-800mA
   异常高电流：>1.5A（可能短路）
   
4. 检查电源线连接
   确保VIN和GND连接牢固
   检查是否有虚焊或断线
```

**解决方案：**
```bash
□ 更换电源适配器（推荐5V/2A）
□ 检查并重新焊接电源连接
□ 添加电源滤波电容（100μF）
□ 检查是否有短路点
□ 使用万用表逐一排查连接
```

#### 🌡️ 传感器故障

**故障现象：传感器读数异常或无读数**
```
温度传感器故障：
- 读数始终为0或-127°C
- 读数跳变异常
- 无法检测到传感器

烟雾传感器故障：
- ADC读数始终为0或4095
- 对烟雾无反应
- 读数漂移严重

PIR传感器故障：
- 无法检测人体移动
- 持续输出高电平
- 检测距离异常短
```

**诊断步骤：**
```bash
# 温度传感器诊断
1. 检查供电电压（应为3.3V）
2. 检查数据线连接（GPIO18）
3. 检查上拉电阻（4.7kΩ）
4. 用万用表测试传感器输出

# 烟雾传感器诊断  
1. 检查供电电压（应为3.3V）
2. 检查模拟输出连接（GPIO19）
3. 测试传感器预热时间（需要20-30秒）
4. 检查传感器清洁度

# PIR传感器诊断
1. 检查供电电压（应为3.3V）
2. 检查数字输出连接（GPIO21）
3. 测试传感器灵敏度调节
4. 检查检测范围和角度
```

**解决方案：**
```bash
□ 重新连接传感器引脚
□ 更换损坏的传感器
□ 清洁传感器表面
□ 调整传感器位置和角度
□ 检查代码中的GPIO配置
□ 添加软件滤波算法
```

#### 📡 红外发射器故障

**故障现象：空调不响应红外控制**
```
症状：
- 空调完全无反应
- 只有部分按键有效
- 控制距离异常短
- 红外信号不稳定
```

**诊断步骤：**
```bash
1. 检查红外发射器供电
   测量VCC：应为3.3V
   
2. 检查信号连接
   确认DATA连接到GPIO4
   
3. 测试红外信号发射
   用手机摄像头观察红外LED
   应该看到紫色闪光
   
4. 检查发射距离和角度
   最佳距离：1-3米
   发射角度：对准空调接收窗口
   
5. 验证红外编码
   检查日志中的红外数据
   确认pattern数据正确
```

**解决方案：**
```bash
□ 重新连接红外发射器
□ 调整发射器位置和角度
□ 更换红外发射器模块
□ 检查GPIO4配置
□ 重新配对空调遥控器
□ 增加发射功率（如果支持）
```

### 2. 软件故障

#### 🌐 WiFi连接问题

**故障现象：无法连接WiFi或连接不稳定**
```
症状：
- 无法扫描到WiFi网络
- 连接后频繁断开
- 获取不到IP地址
- 网络速度异常慢
```

**诊断步骤：**
```bash
1. 检查WiFi配置
   SSID和密码是否正确
   WiFi频段是否为2.4GHz
   
2. 检查信号强度
   RSSI应该 > -70dBm
   距离路由器不超过10米（测试时）
   
3. 检查路由器设置
   是否启用MAC地址过滤
   是否限制设备数量
   DHCP是否正常工作
   
4. 检查ESP32日志
   查看WiFi连接错误信息
   检查IP地址分配情况
```

**解决方案：**
```bash
□ 重置WiFi配置（长按GPIO0按钮）
□ 手动设置静态IP地址
□ 更换WiFi网络或路由器
□ 调整ESP32位置改善信号
□ 更新WiFi驱动程序
□ 检查路由器固件版本
```

#### 📱 Android应用问题

**故障现象：应用崩溃或功能异常**
```
症状：
- 应用启动崩溃
- 无法发现ESP32设备
- 控制指令无响应
- 界面显示异常
```

**诊断步骤：**
```bash
1. 检查应用日志
   adb logcat | grep "com.archesens.android"
   
2. 检查网络连接
   手机和ESP32是否在同一网络
   
3. 检查权限设置
   网络权限是否已授予
   
4. 检查SDK版本兼容性
   Android版本是否支持
   
5. 测试网络通信
   使用浏览器访问ESP32 IP地址
```

**解决方案：**
```bash
□ 清除应用数据和缓存
□ 重新安装APK
□ 检查Android版本兼容性
□ 手动输入ESP32 IP地址
□ 重启手机和ESP32设备
□ 更新应用到最新版本
```

#### 🔧 编译和烧录问题

**故障现象：代码编译失败或烧录失败**
```
编译错误：
- 找不到头文件
- 链接错误
- 内存不足错误

烧录错误：
- 无法识别设备
- 烧录中断
- 校验失败
```

**诊断步骤：**
```bash
1. 检查开发环境
   ESP-IDF版本：5.5.2
   Python版本：3.12
   
2. 检查项目配置
   sdkconfig是否正确
   CMakeLists.txt是否完整
   
3. 检查串口连接
   COM端口是否正确
   波特率设置：460800
   
4. 检查USB驱动
   设备管理器中是否识别ESP32
```

**解决方案：**
```bash
□ 重新安装ESP-IDF环境
□ 清理并重新编译项目
□ 更换USB数据线
□ 安装或更新USB驱动
□ 降低烧录波特率到115200
□ 手动进入下载模式
```

### 3. 网络通信故障

#### 🌍 云端通信问题

**故障现象：无法上传报警数据到云端**
```
症状：
- HTTP请求超时
- 服务器返回错误
- 数据格式错误
- 认证失败
```

**诊断步骤：**
```bash
1. 检查网络连接
   ping 云端服务器IP
   
2. 检查防火墙设置
   端口30088是否开放
   
3. 检查数据格式
   JSON格式是否正确
   
4. 检查服务器状态
   使用curl测试API接口
   
5. 检查认证信息
   设备ID是否正确
```

**解决方案：**
```bash
□ 检查网络防火墙设置
□ 验证云端服务器状态
□ 修正数据格式错误
□ 更新API接口地址
□ 重新生成设备认证信息
□ 增加重试机制
```

## 🔍 高级诊断工具

### 1. 硬件测试工具

#### 万用表测试清单：
```bash
电压测试：
□ 电源输入：5V ±0.25V
□ ESP32 3.3V输出：3.3V ±0.1V
□ 传感器供电：3.3V ±0.1V
□ GPIO输出电压：0V/3.3V

电阻测试：
□ 温度传感器上拉电阻：4.7kΩ ±5%
□ LED限流电阻：220Ω ±5%
□ 各连接点通断测试

电流测试：
□ 系统总电流：300-800mA
□ 各模块单独电流测试
```

#### 示波器测试（如果可用）：
```bash
信号测试：
□ GPIO4红外信号波形
□ I2C通信信号（SDA/SCL）
□ UART通信信号
□ PWM信号波形
```

### 2. 软件调试工具

#### ESP32调试命令：
```bash
# 内存信息
esp_get_free_heap_size()
esp_get_minimum_free_heap_size()

# 任务信息
vTaskList()
vTaskGetRunTimeStats()

# WiFi信息
esp_wifi_get_config()
esp_wifi_sta_get_ap_info()

# 系统信息
esp_get_idf_version()
esp_restart_get_reason()
```

#### 日志分析脚本：
```python
# log_analyzer.py
import re
import sys
from datetime import datetime

def analyze_esp32_log(log_file):
    """分析ESP32日志文件"""
    errors = []
    warnings = []
    memory_usage = []
    
    with open(log_file, 'r', encoding='utf-8') as f:
        for line in f:
            # 提取错误信息
            if 'ERROR' in line or '❌' in line:
                errors.append(line.strip())
            
            # 提取警告信息
            elif 'WARN' in line or '⚠️' in line:
                warnings.append(line.strip())
            
            # 提取内存使用信息
            elif 'Free heap' in line:
                match = re.search(r'Free heap: (\d+)', line)
                if match:
                    memory_usage.append(int(match.group(1)))
    
    # 生成报告
    print(f"日志分析报告 - {datetime.now()}")
    print(f"错误数量: {len(errors)}")
    print(f"警告数量: {len(warnings)}")
    
    if memory_usage:
        print(f"内存使用: 最小 {min(memory_usage)} bytes, "
              f"最大 {max(memory_usage)} bytes, "
              f"平均 {sum(memory_usage)//len(memory_usage)} bytes")
    
    # 显示最近的错误
    if errors:
        print("\n最近的错误:")
        for error in errors[-5:]:
            print(f"  {error}")

if __name__ == "__main__":
    if len(sys.argv) > 1:
        analyze_esp32_log(sys.argv[1])
    else:
        print("用法: python log_analyzer.py <log_file>")
```

### 3. 网络诊断工具

#### 网络连接测试脚本：
```python
# network_test.py
import requests
import socket
import time
import json

def test_esp32_connection(ip_address):
    """测试ESP32网络连接"""
    base_url = f"http://{ip_address}"
    
    print(f"测试ESP32连接: {ip_address}")
    
    # 1. Ping测试
    try:
        socket.create_connection((ip_address, 80), timeout=5)
        print("✅ TCP连接成功")
    except Exception as e:
        print(f"❌ TCP连接失败: {e}")
        return False
    
    # 2. HTTP状态测试
    try:
        response = requests.get(f"{base_url}/api/status", timeout=10)
        print(f"✅ HTTP状态: {response.status_code}")
        print(f"   响应时间: {response.elapsed.total_seconds():.2f}s")
    except Exception as e:
        print(f"❌ HTTP请求失败: {e}")
    
    # 3. 功能接口测试
    test_endpoints = [
        "/api/sensors",
        "/api/alarm/status",
        "/api/system/info"
    ]
    
    for endpoint in test_endpoints:
        try:
            response = requests.get(f"{base_url}{endpoint}", timeout=5)
            print(f"✅ {endpoint}: {response.status_code}")
        except Exception as e:
            print(f"❌ {endpoint}: {e}")
    
    # 4. 空调控制测试
    try:
        data = {"keyType": "POWER"}
        response = requests.post(
            f"{base_url}/api/ac/control",
            headers={"Content-Type": "application/json"},
            data=json.dumps(data),
            timeout=10
        )
        print(f"✅ 空调控制测试: {response.status_code}")
    except Exception as e:
        print(f"❌ 空调控制测试失败: {e}")

if __name__ == "__main__":
    # 自动发现ESP32设备
    import subprocess
    
    # 扫描局域网中的ESP32设备
    for i in range(1, 255):
        ip = f"192.168.1.{i}"
        try:
            result = subprocess.run(['ping', '-n', '1', '-w', '1000', ip], 
                                  capture_output=True, text=True)
            if result.returncode == 0:
                # 尝试连接HTTP服务
                try:
                    response = requests.get(f"http://{ip}/api/status", timeout=2)
                    if response.status_code == 200:
                        print(f"发现ESP32设备: {ip}")
                        test_esp32_connection(ip)
                        break
                except:
                    continue
        except:
            continue
    else:
        print("未发现ESP32设备，请手动指定IP地址")
```

## 🛠️ 预防性维护

### 1. 定期检查清单

#### 每周检查（5分钟）：
```bash
□ 检查设备运行状态LED
□ 测试报警功能（用打火机测试烟雾传感器）
□ 检查WiFi连接状态
□ 查看Android应用连接状态
□ 检查电源适配器温度
```

#### 每月检查（30分钟）：
```bash
□ 清洁传感器表面灰尘
□ 检查所有连接线是否松动
□ 测试所有空调控制功能
□ 检查系统日志是否有异常
□ 备份重要配置数据
□ 检查固件版本是否需要更新
```

#### 每季度检查（2小时）：
```bash
□ 全面功能测试
□ 性能数据分析
□ 硬件连接重新检查
□ 软件版本更新
□ 安全漏洞检查
□ 文档更新
```

### 2. 维护工具和脚本

#### 自动健康检查脚本：
```python
# health_check.py
import requests
import json
import smtplib
from email.mime.text import MIMEText
from datetime import datetime

class ESP32HealthChecker:
    def __init__(self, esp32_ip, email_config=None):
        self.esp32_ip = esp32_ip
        self.base_url = f"http://{esp32_ip}"
        self.email_config = email_config
        self.issues = []
    
    def check_connectivity(self):
        """检查网络连接"""
        try:
            response = requests.get(f"{self.base_url}/api/status", timeout=10)
            if response.status_code != 200:
                self.issues.append(f"HTTP状态异常: {response.status_code}")
        except Exception as e:
            self.issues.append(f"网络连接失败: {e}")
    
    def check_sensors(self):
        """检查传感器状态"""
        try:
            response = requests.get(f"{self.base_url}/api/sensors", timeout=5)
            if response.status_code == 200:
                data = response.json()
                
                # 检查温度传感器
                if data.get('temperature', 0) < -50 or data.get('temperature', 0) > 100:
                    self.issues.append("温度传感器读数异常")
                
                # 检查烟雾传感器
                if data.get('smoke', 0) < 0 or data.get('smoke', 0) > 4095:
                    self.issues.append("烟雾传感器读数异常")
                    
        except Exception as e:
            self.issues.append(f"传感器检查失败: {e}")
    
    def check_memory(self):
        """检查内存使用"""
        try:
            response = requests.get(f"{self.base_url}/api/system/info", timeout=5)
            if response.status_code == 200:
                data = response.json()
                free_heap = data.get('free_heap', 0)
                
                if free_heap < 50000:  # 小于50KB
                    self.issues.append(f"内存不足: {free_heap} bytes")
                    
        except Exception as e:
            self.issues.append(f"内存检查失败: {e}")
    
    def send_alert(self):
        """发送告警邮件"""
        if not self.issues or not self.email_config:
            return
        
        subject = f"ESP32健康检查告警 - {datetime.now().strftime('%Y-%m-%d %H:%M')}"
        body = f"发现以下问题:\n\n" + "\n".join(f"- {issue}" for issue in self.issues)
        
        msg = MIMEText(body, 'plain', 'utf-8')
        msg['Subject'] = subject
        msg['From'] = self.email_config['from']
        msg['To'] = self.email_config['to']
        
        try:
            with smtplib.SMTP(self.email_config['smtp_server'], 587) as server:
                server.starttls()
                server.login(self.email_config['username'], self.email_config['password'])
                server.send_message(msg)
            print("告警邮件发送成功")
        except Exception as e:
            print(f"邮件发送失败: {e}")
    
    def run_check(self):
        """运行完整健康检查"""
        print(f"开始健康检查 - {datetime.now()}")
        
        self.check_connectivity()
        self.check_sensors()
        self.check_memory()
        
        if self.issues:
            print("发现问题:")
            for issue in self.issues:
                print(f"  ❌ {issue}")
            self.send_alert()
        else:
            print("✅ 系统状态正常")

# 使用示例
if __name__ == "__main__":
    # 邮件配置（可选）
    email_config = {
        'smtp_server': 'smtp.gmail.com',
        'username': 'your_email@gmail.com',
        'password': 'your_password',
        'from': 'your_email@gmail.com',
        'to': 'admin@company.com'
    }
    
    checker = ESP32HealthChecker("192.168.1.100", email_config)
    checker.run_check()
```

### 3. 备份和恢复

#### 配置备份脚本：
```bash
#!/bin/bash
# backup_config.sh

BACKUP_DIR="./backups/$(date +%Y%m%d_%H%M%S)"
mkdir -p "$BACKUP_DIR"

echo "开始备份配置..."

# 备份ESP32配置
cp firefly_esp32/sdkconfig "$BACKUP_DIR/"
cp firefly_esp32/partitions.csv "$BACKUP_DIR/"

# 备份Android配置
cp -r Smarthome_android/app/src/main/assets "$BACKUP_DIR/"

# 备份重要脚本
cp -r python_test "$BACKUP_DIR/"

# 创建备份说明
cat > "$BACKUP_DIR/README.txt" << EOF
备份时间: $(date)
ESP32固件版本: $(git describe --tags)
Android应用版本: $(grep versionName Smarthome_android/app/build.gradle.kts)
备份内容:
- ESP32配置文件
- Android应用配置
- Python测试脚本
EOF

echo "备份完成: $BACKUP_DIR"
```

## 📞 技术支持和联系方式

### 紧急故障处理流程：
1. **立即处理**：系统完全无法工作
2. **优先处理**：核心功能异常（火灾报警失效）
3. **正常处理**：次要功能问题（红外控制异常）
4. **计划处理**：性能优化和功能增强

### 故障报告模板：
```
故障报告
========
报告时间: [YYYY-MM-DD HH:MM]
报告人: [姓名]
设备信息: [ESP32 MAC地址/Android设备型号]

故障描述:
[详细描述故障现象]

复现步骤:
1. [步骤1]
2. [步骤2]
3. [步骤3]

环境信息:
- ESP32固件版本: [版本号]
- Android应用版本: [版本号]
- 网络环境: [WiFi信息]
- 硬件配置: [传感器型号等]

已尝试的解决方案:
[列出已经尝试过的解决方法]

日志信息:
[粘贴相关日志]

附件:
[截图、日志文件等]
```

### 维护记录模板：
```
维护记录
========
维护时间: [YYYY-MM-DD HH:MM]
维护人员: [姓名]
维护类型: [预防性维护/故障维修/升级更新]

维护内容:
[详细记录维护操作]

发现问题:
[记录发现的问题]

解决方案:
[记录采取的解决措施]

测试结果:
[记录测试验证结果]

下次维护建议:
[提出下次维护的建议]
```

---

**重要提醒**：
1. 遇到问题时不要慌张，按步骤排查
2. 详细记录故障现象和解决过程
3. 定期进行预防性维护
4. 保持系统和文档的及时更新
5. 建立完善的备份和恢复机制

**文档版本**：v1.0  
**最后更新**：2026年2月26日