# BluFi配网使用指南

## 概述

本项目已成功集成BluFi配网功能，实现了蓝牙优先配网，2分钟超时后自动回退到WiFi AP配网模式。

## 配网流程

### 1. 自动配网流程

1. **设备启动** - 设备启动后自动检查是否有已保存的WiFi凭据
2. **BluFi优先** - 如果没有WiFi凭据或WiFi连接失败，自动启动BluFi配网
3. **设备广播** - 设备开始蓝牙广播，设备名格式：`Airhub-XXXXXX`（后6位为MAC地址）
4. **客户端连接** - 用户使用手机APP连接设备
5. **WiFi配置** - 通过APP发送WiFi SSID和密码
6. **自动连接** - 设备接收到WiFi凭据后自动尝试连接
7. **超时回退** - 如果2分钟内配网未成功，自动切换到WiFi AP模式

### 2. 状态指示

- **BluFi配网模式** - 显示"BluFi配网模式"和设备名
- **客户端连接** - 显示"客户端已连接"
- **凭据接收** - 显示"WiFi凭据已接收"
- **连接成功** - 显示"WiFi连接成功"并播放提示音
- **连接失败** - 显示"WiFi连接失败"
- **配网超时** - 自动切换到WiFi AP模式

## 客户端APP开发

### Android开发示例

```java
// 1. 添加蓝牙权限
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

// 2. 扫描BluFi设备
BluetoothAdapter bluetoothAdapter = BluetoothAdapter.getDefaultAdapter();
BluetoothLeScanner scanner = bluetoothAdapter.getBluetoothLeScanner();

// 3. 连接设备并发送WiFi凭据
// 使用ESP-IDF提供的BluFi库或自定义实现
```

### iOS开发示例

```swift
// 1. 添加蓝牙权限到Info.plist
<key>NSBluetoothAlwaysUsageDescription</key>
<string>需要蓝牙权限进行设备配网</string>

// 2. 使用Core Bluetooth框架
import CoreBluetooth

// 3. 实现CBCentralManagerDelegate和CBPeripheralDelegate
// 4. 扫描并连接BluFi设备
// 5. 发送WiFi凭据
```

### 微信小程序开发示例

```javascript
// 1. 开启蓝牙适配器
wx.openBluetoothAdapter({
  success: function(res) {
    console.log('蓝牙适配器开启成功');
  }
});

// 2. 搜索蓝牙设备
wx.startBluetoothDevicesDiscovery({
  services: [], // BluFi服务UUID
  success: function(res) {
    console.log('开始搜索设备');
  }
});

// 3. 连接设备并发送WiFi信息
// 使用wx.createBLEConnection()和wx.writeBLECharacteristicValue()
```

## 技术规格

### BluFi协议参数

- **服务UUID**: ESP32 BluFi标准服务
- **设备名前缀**: `Airhub-`
- **配网超时**: 120秒（2分钟）
- **最大连接数**: 1个客户端
- **安全模式**: 支持加密传输（可配置）

### 支持的WiFi参数

- **SSID**: 最长32字节
- **密码**: 最长64字节
- **安全类型**: WPA/WPA2/WPA3
- **频段**: 2.4GHz

## 配置选项

可通过`idf.py menuconfig`配置以下选项：

```
Component config → Bluetooth Provisioning Configuration
├── Enable Bluetooth Provisioning          [*]
├── Device Name Prefix                      (Airhub)
├── Security Mode                           (0)
├── Auto Stop After Success                [*]
├── Stop Delay (seconds)                    (5)
├── WiFi Connection Timeout (seconds)       (30)
├── WiFi Retry Count                        (3)
└── Enable Verbose Logging                  [ ]
```

## 故障排除

### 常见问题

1. **BluFi启动失败**
   - 检查sdkconfig中蓝牙配置是否正确
   - 确认CONFIG_BT_ENABLED=y
   - 确认CONFIG_BT_BLUFI_ENABLED=y

2. **客户端无法发现设备**
   - 确认设备蓝牙广播正常
   - 检查客户端蓝牙权限
   - 确认设备名称格式正确

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

4. **配网超时**
   - 检查客户端APP实现
   - 确认蓝牙连接稳定性
   - 调整超时时间配置

### 调试方法

1. **启用详细日志**
   ```
   CONFIG_LOG_DEFAULT_LEVEL_DEBUG=y
   CONFIG_BT_STACK_NO_LOG=n
   ```

2. **监控串口输出**
   ```bash
   idf.py monitor
   ```

3. **使用蓝牙抓包工具**
   - Android: HCI Snoop Log
   - iOS: PacketLogger
   - PC: Wireshark + Bluetooth adapter

## 性能优化

### 内存优化

- 蓝牙协议栈预留内存：64KB
- BluFi最大连接数：1
- 动态内存分配：关闭

### 功耗优化

- 配网成功后自动停止蓝牙
- 支持蓝牙低功耗模式
- WiFi和蓝牙共存优化

## 安全考虑

### 数据加密

- 支持AES加密传输
- 可配置PSK预共享密钥
- 防重放攻击保护

### 访问控制

- 设备名称随机化
- 连接超时保护
- 最大重试次数限制

## 扩展功能

### 自定义数据传输

- 支持自定义数据通道
- 设备信息查询
- 固件版本检查
- OTA升级支持

### 多语言支持

- 中文界面提示
- 英文调试信息
- 可扩展其他语言

## 版本历史

- **v1.0.0** - 初始版本，基础BluFi配网功能
- **v1.1.0** - 添加超时回退机制
- **v1.2.0** - 优化用户界面和提示
- **v1.3.0** - 添加安全加密支持

## 技术支持

如有问题，请检查：
1. ESP-IDF版本兼容性
2. 硬件蓝牙模块状态
3. 客户端APP实现
4. 网络环境配置

更多技术细节请参考ESP-IDF官方BluFi文档。