toy-Kapi_Rtc/蓝牙配网集成指南.md

# 蓝牙配网集成指南

本文档详细说明如何将蓝牙配网功能集成到小智AI项目中。

## 1. 文件说明

### 新增文件

- `main/bluetooth_provisioning.h` - 蓝牙配网类头文件
- `main/bluetooth_provisioning.cc` - 蓝牙配网类实现文件
- `main/bluetooth_provisioning_config.h` - 蓝牙配网配置文件
- `main/bluetooth_provisioning_example.cc` - 使用示例文件

### 修改文件

- `main/CMakeLists.txt` - 添加了蓝牙配网源文件和组件依赖

## 2. 功能特性

### 核心功能

- ✅ 蓝牙BLE广播和连接管理
- ✅ WiFi凭据接收和配置
- ✅ WiFi连接状态监控和报告
- ✅ 事件回调机制
- ✅ 状态管理和错误处理
- ✅ 自动重连和故障恢复

### 安全特性

- 🔒 支持加密通信（可选）
- 🔒 预共享密钥（PSK）认证
- 🔒 WiFi密码安全传输
- 🔒 连接超时保护

### 兼容性

- 📱 兼容ESP-IDF官方配网APP
- 📱 支持自定义配网APP开发
- 🔧 支持ESP32/ESP32-S3/ESP32-C3等芯片

## 3. 集成步骤

### 3.1 配置ESP-IDF

在项目的`sdkconfig`中确保启用以下配置：

```bash
# 蓝牙基础配置
CONFIG_BT_ENABLED=y
CONFIG_BLUEDROID_ENABLED=y
CONFIG_BT_BLUFI_ENABLE=y

# 蓝牙控制器配置
CONFIG_BTDM_CTRL_MODE_BLE_ONLY=y
CONFIG_BTDM_CTRL_MODE_BR_EDR_ONLY=n
CONFIG_BTDM_CTRL_MODE_BTDM=n

# WiFi配置
CONFIG_ESP32_WIFI_ENABLED=y
CONFIG_ESP32_WIFI_STATIC_RX_BUFFER_NUM=10
CONFIG_ESP32_WIFI_DYNAMIC_RX_BUFFER_NUM=32

# 事件循环配置
CONFIG_ESP_EVENT_LOOP_PROFILING=y

# NVS配置
CONFIG_NVS_ENCRYPTION=n
```

### 3.2 在现有代码中集成

#### 方法1：独立任务集成（推荐）

在`application.cc`中添加蓝牙配网任务：

```cpp
#include "bluetooth_provisioning.h"

// 全局蓝牙配网对象
static BluetoothProvisioning* g_bt_provisioning = nullptr;

// 蓝牙配网事件回调
void bluetooth_provisioning_callback(BluetoothProvisioningEvent event, void* data) {
    switch (event) {
    case BluetoothProvisioningEvent::WIFI_CONNECTED:
        ESP_LOGI("APP", "WiFi配网成功");
        // 在这里添加配网成功后的处理逻辑
        break;
    case BluetoothProvisioningEvent::WIFI_FAILED:
        ESP_LOGE("APP", "WiFi配网失败");
        // 在这里添加配网失败后的处理逻辑
        break;
    // 处理其他事件...
    }
}

// 蓝牙配网任务
void bluetooth_provisioning_task(void* pvParameters) {
    g_bt_provisioning = new BluetoothProvisioning();
    g_bt_provisioning->SetCallback(bluetooth_provisioning_callback);
    
    if (g_bt_provisioning->Initialize()) {
        g_bt_provisioning->StartProvisioning("Airhub_Ble");
        
        while (true) {
            // 监控配网状态
            vTaskDelay(pdMS_TO_TICKS(5000));
        }
    }
    
    vTaskDelete(nullptr);
}

// 在Application::Initialize()中启动配网任务
void Application::Initialize() {
    // 现有初始化代码...
    
    // 创建蓝牙配网任务
    xTaskCreate(bluetooth_provisioning_task, "bt_prov", 8192, nullptr, 5, nullptr);
}
```

#### 方法2：直接集成到Application类

在`application.h`中添加：

```cpp
#include "bluetooth_provisioning.h"

class Application {
private:
    BluetoothProvisioning* bluetooth_provisioning_;
    
public:
    void StartBluetoothProvisioning();
    void StopBluetoothProvisioning();
    bool IsWiFiConnected();
};
```

在`application.cc`中实现：

```cpp
void Application::StartBluetoothProvisioning() {
    if (!bluetooth_provisioning_) {
        bluetooth_provisioning_ = new BluetoothProvisioning();
        bluetooth_provisioning_->SetCallback([this](BluetoothProvisioningEvent event, void* data) {
            // 处理配网事件
        });
    }
    
    if (bluetooth_provisioning_->Initialize()) {
        bluetooth_provisioning_->StartProvisioning("小智AI");
    }
}
```

### 3.3 配置参数调整

根据项目需求，修改`bluetooth_provisioning_config.h`中的配置参数：

```cpp
// 修改设备名称
#define BT_PROVISIONING_DEFAULT_DEVICE_NAME "你的设备名称"

// 调整超时时间
#define BT_PROVISIONING_WIFI_TIMEOUT_MS (60 * 1000)  // 60秒

// 启用/禁用安全模式
#define BT_PROVISIONING_SECURITY_ENABLED 1

// 配网成功后自动停止
#define BT_PROVISIONING_AUTO_STOP_ON_SUCCESS 1
```

## 4. 使用方法

### 4.1 基本使用流程

1. **创建对象**：`BluetoothProvisioning* prov = new BluetoothProvisioning();`
2. **设置回调**：`prov->SetCallback(callback_function);`
3. **初始化**：`prov->Initialize();`
4. **启动配网**：`prov->StartProvisioning("设备名称");`
5. **监控状态**：通过回调函数处理各种事件
6. **停止配网**：`prov->StopProvisioning();`（可选）
7. **清理资源**：`prov->Deinitialize(); delete prov;`

### 4.2 状态监控

```cpp
// 获取当前状态
BluetoothProvisioningState state = prov->GetState();

// 检查客户端连接状态
bool connected = prov->IsClientConnected();

// 获取WiFi凭据
WiFiCredentials credentials = prov->GetWiFiCredentials();
```

### 4.3 事件处理

```cpp
void provisioning_callback(BluetoothProvisioningEvent event, void* data) {
    switch (event) {
    case BluetoothProvisioningEvent::STATE_CHANGED:
        // 状态变化
        break;
    case BluetoothProvisioningEvent::CLIENT_CONNECTED:
        // 客户端连接
        break;
    case BluetoothProvisioningEvent::WIFI_CREDENTIALS:
        // 收到WiFi凭据
        WiFiCredentials* creds = (WiFiCredentials*)data;
        break;
    case BluetoothProvisioningEvent::WIFI_CONNECTED:
        // WiFi连接成功
        esp_ip4_addr_t* ip = (esp_ip4_addr_t*)data;
        break;
    case BluetoothProvisioningEvent::WIFI_FAILED:
        // WiFi连接失败
        uint8_t* reason = (uint8_t*)data;
        break;
    }
}
```

## 5. 客户端APP开发

### 5.1 使用ESP-IDF官方APP

1. 下载ESP-IDF官方配网APP
2. 扫描蓝牙设备，找到你的设备
3. 连接设备并输入WiFi凭据
4. 等待配网完成

### 5.2 自定义APP开发

参考ESP-IDF的BLUFI协议文档：
- [BLUFI协议说明](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/blufi.html)
- [BLUFI示例代码](https://github.com/espressif/esp-idf/tree/master/examples/bluetooth/blufi)

## 6. 故障排除

### 6.1 常见问题

**问题1：蓝牙初始化失败**
- 检查`sdkconfig`中蓝牙相关配置是否正确
- 确保有足够的内存空间
- 检查是否与其他蓝牙功能冲突

**问题2：WiFi连接失败**
- 检查WiFi凭据是否正确
- 确认WiFi信号强度
- 检查路由器兼容性

**问题3：客户端无法发现设备**
- 确认蓝牙广播是否正常启动
- 检查设备名称是否正确
- 确认客户端APP版本兼容性

### 6.2 调试方法

1. **启用详细日志**：
   ```cpp
   #define BT_PROVISIONING_VERBOSE_LOG 1
   ```

2. **使用ESP-IDF监控工具**：
   ```bash
   idf.py monitor
   ```

3. **检查内存使用**：
   ```cpp
   ESP_LOGI(TAG, "Free heap: %d", esp_get_free_heap_size());
   ```

## 7. 性能优化

### 7.1 内存优化

- 配网成功后及时释放蓝牙资源
- 调整任务栈大小
- 使用内存池管理

### 7.2 功耗优化

- 配网完成后关闭蓝牙
- 调整广播间隔
- 使用低功耗模式

### 7.3 连接优化

- 优化广播参数
- 调整连接间隔
- 实现快速重连机制

## 8. 安全考虑

### 8.1 数据安全

- 启用加密通信
- 使用强密码策略
- 定期更换PSK

### 8.2 访问控制

- 实现设备认证
- 限制配网时间窗口
- 添加访问日志

### 8.3 隐私保护

- 不记录敏感信息
- 及时清除临时数据
- 遵循数据保护法规

## 9. 扩展功能

### 9.1 自定义数据传输

```cpp
// 发送自定义数据
void send_custom_data(const uint8_t* data, size_t len) {
    esp_blufi_send_custom_data(data, len);
}

// 接收自定义数据
void handle_custom_data(const uint8_t* data, size_t len) {
    // 处理自定义数据
}
```

### 9.2 多设备管理

- 支持同时配网多个设备
- 实现设备分组管理
- 添加设备状态同步

### 9.3 云端集成

- 配网信息云端备份
- 远程配网管理
- 设备状态监控

## 10. 版本更新

### 当前版本：v1.0.0

**功能特性：**
- 基础蓝牙配网功能
- WiFi连接管理
- 事件回调机制
- 状态管理
- 错误处理

**后续计划：**
- v1.1.0：添加安全认证
- v1.2.0：支持多设备配网
- v1.3.0：云端集成功能

---

## 联系支持

如果在集成过程中遇到问题，请：

1. 查看本文档的故障排除章节
2. 检查ESP-IDF官方文档
3. 提交Issue到项目仓库
4. 联系技术支持团队

**祝您集成顺利！** 🎉