Rdzleo/toy-hardware

Fork 0

Rdzleo d5460d2bb9 Create v1.7.5(第1次提交)

2026-01-20 16:32:43 +08:00

8.5 KiB

Raw Blame History

蓝牙配网集成指南

本文档详细说明如何将蓝牙配网功能集成到小智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中确保启用以下配置：

# 蓝牙基础配置
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中添加蓝牙配网任务：

#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中添加：

#include "bluetooth_provisioning.h"

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

在application.cc中实现：

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中的配置参数：

// 修改设备名称
#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 基本使用流程

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

4.2 状态监控

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

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

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

4.3 事件处理

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

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

5.2 自定义APP开发

参考ESP-IDF的BLUFI协议文档：

6. 故障排除

6.1 常见问题

问题1：蓝牙初始化失败

检查sdkconfig中蓝牙相关配置是否正确
确保有足够的内存空间
检查是否与其他蓝牙功能冲突

问题2：WiFi连接失败

检查WiFi凭据是否正确
确认WiFi信号强度
检查路由器兼容性

问题3：客户端无法发现设备

确认蓝牙广播是否正常启动
检查设备名称是否正确
确认客户端APP版本兼容性

6.2 调试方法

启用详细日志：
```
#define BT_PROVISIONING_VERBOSE_LOG 1
```
使用ESP-IDF监控工具：
```
idf.py monitor
```

检查内存使用：

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 自定义数据传输

// 发送自定义数据
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：云端集成功能

联系支持

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

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

祝您集成顺利！ 🎉

8.5 KiB Raw Blame History Unescape Escape