ESP32 蓝牙配网实战：用 ESP-IDF 的 BluFi，3 步把 Wi-Fi 密码安全送进芯片
【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf
你手头有一台没有屏幕的设备，却必须连上 Wi-Fi，怎么办？BluFi 就是为此而生：它借用蓝牙通道，把 Wi-Fi 的 SSID 和密码安全地"隔空"传给 ESP32 芯片，而 ESP-IDF 框架已经把这个蓝牙配网协议做成了现成组件。你不必扫二维码，也不必让设备先连上某个"配网专用网络"——手机通过蓝牙把凭证发过去，设备自己连上路由器。
全景速览：一张图看懂 BluFi 🧭
整条链路很短：你的手机（装 EspBlufi App）→ 蓝牙 → ESP32（跑 BluFi 示例）→ Wi-Fi 路由器。手机先通过 GATT（蓝牙的数据传输协议）连上 ESP32，双方在蓝牙里协商出一把秘密钥匙，然后手机把 Wi-Fi 凭证加密后发过来，ESP32 解密、拿它去连路由器，最后把连接状态回传给你。
设备上电、BluFi 初始化完成后，串口会打出这样的日志，说明蓝牙配网已就绪：
把它和 SmartConfig（手机把 Wi-Fi 信息以广播包形式发出，ESP32 用 2.4G Wi-Fi 听广播）这类传统配网对比，差异有五点：
- 凭证走蓝牙而非 Wi-Fi 广播，不依赖设备处于"听广播"状态，两边也不要求在同一网络里
- 每帧都加密并带 CRC16 校验，Wi-Fi 密码不会以明文出现在空中
- 支持 Station、SoftAP、AP+STA 组合三种模式，SmartConfig 基本只管"连路由器"
- 加密与校验算法可以自定义，安全级别随项目要求上调或下调
- 手机端是标准 GATT Client，App 开源，可自己魔改界面
三步跑通最小配网 🚀
路线一：Station 模式（设备连已有 Wi-Fi）
- 硬件就绪：开发板用 USB 连上电脑，打开串口工具。校验点：串口出现
BLUFI init finish，说明配网通道已就绪。 - 烧录示例：打开 BluFi 示例工程，执行
idf.py set-target esp32，再执行idf.py flash monitor。校验点：烧录成功，串口持续输出 BLUFI 版本与初始化日志。 - 手机配网：安装 EspBlufi App，授予蓝牙、Wi-Fi、定位权限，刷新列表连上 ESP32，点 Networking，选 Station，选中路由器并输入密码。校验点：App 显示连接成功，串口里设备连上 AP 并拿到 IP。
路线二：SoftAP 模式（设备自己当路由器）
- 硬件就绪：同上，确认串口出现
BLUFI init finish。 - 烧录同一个示例：不需要改任何代码，SoftAP 只是 App 里的一个运行时选项。校验点：示例正常跑起来。
- 手机设热点：蓝牙连上后，在 App 里选 SoftAP 模式，填写热点 SSID、密码和加密方式。校验点：用手机搜索到并连上这个新建热点。
顺带一提：示例支持 ESP32、C2、C3、C5、C6、C61、S3、S31 等目标芯片，换芯片只需改一行idf.py set-target <芯片>。
协议与安全机制深挖 🔐
帧结构与分片
BluFi 规定每次蓝牙传输都按固定格式打包，字段速查表如下：
| 字段 | 长度 | 一句话解释 |
|---|---|---|
| 类型 | 1 字节 | 这是什么帧：控制帧还是数据帧 |
| 帧控制 | 1 字节 | 携带"已加密""后面还有分片"等标志位 |
| 序列号 | 1 字节 | 逐帧递增，用来防止重放 |
| 数据长度 | 1 字节 | 后面数据字段的实际长度 |
| 数据 | N 字节 | 真正的内容（SSID、密码等） |
| 校验 | 2 字节 | 对数据做的 CRC16 校验值 |
内容太长装不进一帧时自动分片：帧控制位打上分片标志，数据部分的前 2 字节写明整包总长度。接收端照这个长度预分配内存，再按序列号把碎片依次拼回去。
加密 / 校验 / 防重放
设备端默认配了三件安全武器：
- 密钥协商（DH 算法）：双方各发一个公开参数，各自在本地算出同一把秘密钥匙，钥匙本身从不上链路
- 数据加密（128 位 AES）：每帧的数据字段都用这把钥匙加密
- 完整性校验（CRC16）：数据被篡改哪怕 1 个字节，校验也会失败
再加上序列号必须严格递增，重复的旧帧直接丢弃，重放攻击因此失效。如果你想换更强的算法，ESP-IDF 留了四个回调注册点，签名长这样：
esp_blufi_register_encrypt_func(esp_blufi_encrypt_func_t f); // 加密 esp_blufi_register_decrypt_func(esp_blufi_decrypt_func_t f); // 解密 esp_blufi_register_checksum_func(esp_blufi_checksum_func_t f); // 校验 esp_blufi_register_nego_data_handler(esp_blufi_negotiate_data_handler_t h); // 协商分别对应加解密一对、校验一个、协商数据处理一个，全部可替换成你自己的实现。
落地选型与避坑
BluFi 最适合无屏 IoT 设备和批量配网：设备没有屏幕、没有摄像头，现场一次铺几十台也不怕，只要有手机和蓝牙就能逐台喂凭证。相比其他方案，它的长项是链路加密、安全级别可调；短项是蓝牙有效距离短（米级），且手机端要装专门的 App。
三个高频疑问快答：
- 支持 5GHz Wi-Fi 吗？不支持。ESP32 系列芯片的 Wi-Fi 只有 2.4GHz，BluFi 配的目标网络也限于 2.4GHz 频段。
- 安全级别怎么定？一般消费类产品用默认的 DH + AES128 + CRC16 就够了；保密要求更高的场景，可以注册自定义的加密与校验回调把级别拉满。
- 新项目还该选它吗？说句实话：官方 README 已注明 BluFi 处于维护模式，不再规划新功能，新项目建议优先考虑官方维护的 network_provisioning 组件；BluFi 适合存量设备、学习协议和轻量场景。
更细的协议说明在 BluFi 官方文档，API 细节见 esp_blufi_api.h。
【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
