216 lines
5.2 KiB
Markdown
216 lines
5.2 KiB
Markdown
# 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文档。 |