smart-home/使用手册/手册指南/软件配置详细指南.md

# ESP32智能火灾报警系统 - 软件配置详细指南

## 🖥️ 开发环境配置

### 1. ESP-IDF 5.5.2 安装配置

#### Windows环境安装：
```bash
# 1. 下载ESP-IDF 5.5.2离线安装包
下载地址：https://dl.espressif.com/dl/esp-idf/

# 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\
- D:\Espressif5.5.2\Espressif\python_env\idf5.5_py3.12_env\Scripts\

# 4. 验证安装
打开命令行执行：
idf.py --version
# 应该显示：ESP-IDF v5.5.2
```

#### 初始化ESP-IDF环境：
```bash
# 每次开发前执行（或添加到系统启动脚本）
D:\Espressif5.5.2\Espressif\frameworks\esp-idf-v5.5.2\export.ps1

# 验证环境
echo $IDF_PATH
which idf.py
```

### 2. ESP32项目配置

#### 项目结构说明：
```
firefly_esp32/
├── CMakeLists.txt          # 项目构建配置
├── sdkconfig              # ESP32配置文件
├── partitions.csv         # 分区表配置
├── main/                  # 主程序代码
│   ├── CMakeLists.txt     # 主程序构建配置
│   ├── app_main.cpp       # 主程序入口
│   ├── Module/            # 功能模块
│   │   ├── AlarmManager.cpp    # 报警管理
│   │   ├── NetworkManager.cpp  # 网络管理
│   │   ├── SensorManager.cpp   # 传感器管理
│   │   └── IRController.cpp    # 红外控制
│   └── include/           # 头文件
└── managed_components/    # ESP-IDF组件
```

#### 重要配置文件详解：

##### sdkconfig 关键配置：
```bash
# CPU和内存配置
CONFIG_ESP32_DEFAULT_CPU_FREQ_240=y
CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ=240
CONFIG_ESP_MAIN_TASK_STACK_SIZE=8192

# WiFi配置
CONFIG_ESP32_WIFI_STATIC_RX_BUFFER_NUM=10
CONFIG_ESP32_WIFI_DYNAMIC_RX_BUFFER_NUM=32
CONFIG_ESP32_WIFI_TX_BUFFER_TYPE=1
CONFIG_ESP32_WIFI_DYNAMIC_TX_BUFFER_NUM=32

# FreeRTOS配置
CONFIG_FREERTOS_HZ=1000
CONFIG_FREERTOS_TASK_FUNCTION_WRAPPER=y
CONFIG_FREERTOS_CHECK_STACKOVERFLOW_CANARY=y

# 分区表配置
CONFIG_PARTITION_TABLE_CUSTOM=y
CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions.csv"

# 日志配置
CONFIG_LOG_DEFAULT_LEVEL_INFO=y
CONFIG_LOG_MAXIMUM_LEVEL_VERBOSE=y
```

##### partitions.csv 分区配置：
```csv
# Name,   Type, SubType, Offset,  Size,    Flags
nvs,      data, nvs,     0x9000,  0x6000,
phy_init, data, phy,     0xf000,  0x1000,
factory,  app,  factory, 0x10000, 0x1F0000,
storage,  data, spiffs,  0x200000,0x200000,
```

### 3. 项目编译配置

#### 编译环境设置：
```bash
cd d:\XinJiaPo\Firefly_code\smart-home\firefly_esp32

# 设置目标芯片
idf.py set-target esp32

# 配置项目（打开配置菜单）
idf.py menuconfig
```

#### menuconfig 重要配置项：

##### 1. Component config → ESP32-specific：
```
CPU frequency: 240 MHz
Main XTAL frequency: 40 MHz
RTC clock source: External 32kHz crystal
```

##### 2. Component config → Wi-Fi：
```
WiFi Task Core ID: Core 1
Max number of WiFi static RX buffers: 10
Max number of WiFi dynamic RX buffers: 32
Type of WiFi TX buffers: Dynamic
Max number of WiFi dynamic TX buffers: 32
WiFi AMPDU TX: Enabled
WiFi AMPDU RX: Enabled
```

##### 3. Component config → FreeRTOS：
```
Tick rate (Hz): 1000
Task watchdog timeout period (seconds): 5
Idle Task watchdog timeout period (seconds): 5
Enable task function wrapper: Yes
Check for stack overflow: Canary method
```

##### 4. Component config → HTTP Server：
```
Max HTTP Request Header Length: 1024
Max HTTP Response Header Length: 1024
Max HTTP URI Length: 512
```

##### 5. Component config → mDNS：
```
mDNS Hostname: esp32-fire-alarm
mDNS Instance Name: Fire Alarm System
```

### 4. 编译和烧录

#### 完整编译流程：
```bash
# 1. 清理之前的构建
idf.py fullclean

# 2. 编译项目
idf.py build

# 3. 检查编译结果
ls build/
# 应该看到：
# - bootloader/bootloader.bin
# - partition_table/partition-table.bin  
# - smart-home.bin (主程序)

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

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

#### 烧录参数说明：
```bash
# 完整烧录命令（包含所有分区）
esptool.py --chip esp32 --port COM3 --baud 460800 write_flash \
  0x1000 build/bootloader/bootloader.bin \
  0x8000 build/partition_table/partition-table.bin \
  0x10000 build/smart-home.bin

# 仅更新应用程序（开发时常用）
idf.py -p COM3 app-flash
```

## 📱 Android开发环境配置

### 1. Android Studio配置

#### 系统要求：
```
- Android Studio 2023.1.1+
- JDK 11 或更高版本
- Android SDK API Level 34
- Gradle 8.11.1
- 最小内存：8GB RAM
- 推荐内存：16GB RAM
```

#### Android Studio安装配置：
```bash
# 1. 下载Android Studio
https://developer.android.com/studio

# 2. 安装SDK组件
Tools → SDK Manager → SDK Platforms:
- Android 14 (API level 34) ✓
- Android 13 (API level 33) ✓
- Android 12 (API level 32) ✓

Tools → SDK Manager → SDK Tools:
- Android SDK Build-Tools 34.0.0 ✓
- Android Emulator ✓
- Android SDK Platform-Tools ✓
- Intel x86 Emulator Accelerator (HAXM installer) ✓
```

### 2. 项目配置

#### Gradle配置文件：

##### build.gradle.kts (Project level)：
```kotlin
plugins {
    id("com.android.application") version "8.11.1" apply false
    id("org.jetbrains.kotlin.android") version "1.9.10" apply false
}
```

##### build.gradle.kts (App level)：
```kotlin
android {
    namespace = "com.archesens.android"
    compileSdk = 34

    defaultConfig {
        applicationId = "com.archesens.android"
        minSdk = 24
        targetSdk = 34
        versionCode = 1
        versionName = "1.0"
        
        multiDexEnabled = true
        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }

    buildTypes {
        release {
            isMinifyEnabled = false
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
    }
    
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }
}

dependencies {
    implementation("androidx.core:core-ktx:1.12.0")
    implementation("androidx.appcompat:appcompat:1.6.1")
    implementation("com.google.android.material:material:1.11.0")
    implementation("androidx.constraintlayout:constraintlayout:2.1.4")
    
    // MultiDex支持
    implementation("androidx.multidex:multidex:2.0.1")
    
    // 网络请求
    implementation("com.squareup.okhttp3:okhttp:4.12.0")
    
    // JSON解析
    implementation("com.google.code.gson:gson:2.10.1")
    
    // Tiqiaa SDK
    implementation(files("libs/TiqiaaSDKPlugin.aar"))
    implementation(files("libs/tiqiaa-remote-1.0.0.jar"))
}
```

##### proguard-rules.pro：
```proguard
# Tiqiaa SDK保护规则
-keep class com.tiqiaa.** { *; }
-keepclassmembers class com.tiqiaa.** { *; }

# 枚举类保护
-keepclassmembers enum com.tiqiaa.remote.enums.** {
    public static **[] values();
    public static ** valueOf(java.lang.String);
}

# 反射调用保护
-keepclassmembers class * {
    @android.webkit.JavascriptInterface <methods>;
}

# 网络请求保护
-keep class com.archesens.android.Esp32JsBridge { *; }
-keepclassmembers class com.archesens.android.Esp32JsBridge {
    public *;
}
```

### 3. 关键代码配置

#### AndroidManifest.xml 权限配置：
```xml
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />

<application
    android:name=".SmartHomeApplication"
    android:allowBackup="true"
    android:icon="@mipmap/ic_launcher"
    android:label="@string/app_name"
    android:theme="@style/AppTheme">
    
    <activity
        android:name=".MainActivity"
        android:exported="true"
        android:launchMode="singleTop">
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
    </activity>
</application>
```

#### SmartHomeApplication.java：
```java
public class SmartHomeApplication extends MultiDexApplication {
    @Override
    public void onCreate() {
        super.onCreate();
        MultiDex.install(this);
    }
}
```

## 🔧 开发工具配置

### 1. VS Code配置（可选）

#### 推荐插件：
```json
{
    "recommendations": [
        "ms-vscode.cpptools",
        "espressif.esp-idf-extension",
        "ms-python.python",
        "redhat.java",
        "vscjava.vscode-java-pack"
    ]
}
```

#### ESP-IDF插件配置：
```json
{
    "idf.espIdfPath": "D:\\Espressif5.5.2\\Espressif\\frameworks\\esp-idf-v5.5.2",
    "idf.toolsPath": "D:\\Espressif5.5.2\\Espressif\\tools",
    "idf.pythonBinPath": "D:\\Espressif5.5.2\\Espressif\\python_env\\idf5.5_py3.12_env\\Scripts\\python.exe",
    "idf.port": "COM3",
    "idf.baudRate": "460800"
}
```

### 2. 串口调试工具

#### 推荐工具：
1. **PuTTY**：简单易用的串口终端
2. **Tera Term**：功能丰富的终端模拟器
3. **Arduino IDE串口监视器**：如果安装了Arduino IDE
4. **ESP-IDF Monitor**：官方推荐工具

#### 串口参数配置：
```
波特率：115200
数据位：8
停止位：1
校验位：None
流控制：None
```

### 3. 网络调试工具

#### HTTP调试：
```bash
# 使用curl测试ESP32 HTTP接口
curl -X GET http://192.168.1.100/api/status
curl -X POST http://192.168.1.100/api/ac/control \
  -H "Content-Type: application/json" \
  -d '{"keyType":"POWER"}'
```

#### Python测试脚本：
```python
# test_esp32_api.py
import requests
import json

ESP32_IP = "192.168.1.100"
BASE_URL = f"http://{ESP32_IP}"

def test_status():
    response = requests.get(f"{BASE_URL}/api/status")
    print(f"Status: {response.status_code}")
    print(f"Response: {response.text}")

def test_ac_control(key_type):
    data = {"keyType": key_type}
    response = requests.post(
        f"{BASE_URL}/api/ac/control",
        headers={"Content-Type": "application/json"},
        data=json.dumps(data)
    )
    print(f"AC Control ({key_type}): {response.status_code}")
    print(f"Response: {response.text}")

if __name__ == "__main__":
    test_status()
    test_ac_control("POWER")
    test_ac_control("TEMP_UP")
```

## 🐛 调试配置

### 1. ESP32调试

#### 日志级别配置：
```cpp
// 在app_main.cpp中设置日志级别
esp_log_level_set("*", ESP_LOG_INFO);
esp_log_level_set("WIFI", ESP_LOG_DEBUG);
esp_log_level_set("HTTP", ESP_LOG_DEBUG);
esp_log_level_set("ALARM", ESP_LOG_VERBOSE);
```

#### 调试宏定义：
```cpp
// 在main/include/debug.h中定义
#define DEBUG_ENABLED 1

#if DEBUG_ENABLED
#define DEBUG_PRINT(fmt, ...) ESP_LOGI("DEBUG", fmt, ##__VA_ARGS__)
#define DEBUG_ERROR(fmt, ...) ESP_LOGE("DEBUG", fmt, ##__VA_ARGS__)
#else
#define DEBUG_PRINT(fmt, ...)
#define DEBUG_ERROR(fmt, ...)
#endif
```

### 2. Android调试

#### Logcat过滤配置：
```bash
# 过滤应用日志
adb logcat | grep "com.archesens.android"

# 过滤特定标签
adb logcat | grep "Esp32JsBridge"

# 保存日志到文件
adb logcat > debug.log
```

#### 调试工具配置：
```java
// 在Esp32JsBridge.java中添加调试开关
private static final boolean DEBUG = BuildConfig.DEBUG;

private void debugLog(String message) {
    if (DEBUG) {
        Log.d(TAG, message);
    }
}
```

## 📊 性能监控配置

### 1. ESP32性能监控

#### 内存监控：
```cpp
// 在app_main.cpp中添加内存监控任务
void memory_monitor_task(void *pvParameters) {
    while (1) {
        size_t free_heap = esp_get_free_heap_size();
        size_t min_free_heap = esp_get_minimum_free_heap_size();
        
        ESP_LOGI("MEMORY", "Free heap: %d bytes, Min free: %d bytes", 
                 free_heap, min_free_heap);
        
        vTaskDelay(pdMS_TO_TICKS(10000)); // 每10秒检查一次
    }
}
```

#### CPU使用率监控：
```cpp
// 启用任务监控
#define configUSE_TRACE_FACILITY 1
#define configUSE_STATS_FORMATTING_FUNCTIONS 1

void cpu_monitor_task(void *pvParameters) {
    char *task_list_buffer = malloc(2048);
    while (1) {
        vTaskList(task_list_buffer);
        ESP_LOGI("CPU", "Task List:\n%s", task_list_buffer);
        vTaskDelay(pdMS_TO_TICKS(30000)); // 每30秒检查一次
    }
    free(task_list_buffer);
}
```

### 2. 网络性能监控

#### WiFi信号强度监控：
```cpp
void wifi_monitor_task(void *pvParameters) {
    wifi_ap_record_t ap_info;
    while (1) {
        if (esp_wifi_sta_get_ap_info(&ap_info) == ESP_OK) {
            ESP_LOGI("WIFI", "RSSI: %d dBm, Channel: %d", 
                     ap_info.rssi, ap_info.primary);
        }
        vTaskDelay(pdMS_TO_TICKS(15000)); // 每15秒检查一次
    }
}
```

## 🔐 安全配置

### 1. WiFi安全配置

#### WPA2企业级配置（可选）：
```cpp
wifi_config_t wifi_config = {
    .sta = {
        .ssid = "YourSSID",
        .password = "YourPassword",
        .threshold.authmode = WIFI_AUTH_WPA2_PSK,
        .pmf_cfg = {
            .capable = true,
            .required = false
        },
    },
};
```

### 2. HTTP安全配置

#### HTTPS配置（生产环境推荐）：
```cpp
// 在HTTP服务器配置中启用HTTPS
httpd_ssl_config_t conf = HTTPD_SSL_CONFIG_DEFAULT();
conf.httpd.server_port = 443;
conf.cacert_pem = server_cert_pem_start;
conf.cacert_len = server_cert_pem_end - server_cert_pem_start;
conf.prvtkey_pem = server_key_pem_start;
conf.prvtkey_len = server_key_pem_end - server_key_pem_start;
```

## 📝 配置文件模板

### 1. 环境配置脚本

#### setup_environment.bat：
```batch
@echo off
echo 正在设置ESP32开发环境...

set IDF_PATH=D:\Espressif5.5.2\Espressif\frameworks\esp-idf-v5.5.2
set PATH=%PATH%;D:\Espressif5.5.2\Espressif\tools\

call %IDF_PATH%\export.bat

echo 环境设置完成！
echo IDF_PATH: %IDF_PATH%

pause
```

### 2. 编译脚本

#### build_and_flash.bat：
```batch
@echo off
echo 开始编译ESP32项目...

cd /d "d:\XinJiaPo\Firefly_code\smart-home\firefly_esp32"

echo 清理构建...
idf.py fullclean

echo 编译项目...
idf.py build

if %ERRORLEVEL% EQU 0 (
    echo 编译成功！开始烧录...
    idf.py -p COM3 flash
    
    if %ERRORLEVEL% EQU 0 (
        echo 烧录成功！启动监控...
        idf.py -p COM3 monitor
    ) else (
        echo 烧录失败！
    )
) else (
    echo 编译失败！
)

pause
```

---

**重要提醒**：
1. 首次配置时请严格按照步骤执行
2. 遇到问题时查看详细错误信息
3. 保持开发环境版本一致性
4. 定期备份配置文件和项目代码

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