ESP32 蓝牙配网三步搞定BluFi 安全下发 Wi-Fi 凭证的完整流程【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf一批无屏 IoT 设备出货前怎么让每一台都连上客户家的 Wi-Fi逐台插串口手敲密码显然不现实。ESP-IDF 里的 BluFi 给了另一条路把 Wi-Fi 的 SSID、密码通过蓝牙 GATT 通道安全地送到 ESP32 手上设备既能以 Station 模式连入已有网络也能用 SoftAP 模式自建热点。下面先带你把配网示例跑通再拆开看它背后的安全通道与帧协议。手把手跑通BluFi 配网三步走 这一节的目标很简单让一台设备通过手机蓝牙连上 Wi-Fi并且每一步都能从串口日志里看到对应信号。准备清单类别内容硬件一块 ESP32 系开发板ESP32 / C2 / C3 / C5 / C6 / S3 等均可、一台电脑用于供电和看串口固件烧录 ESP-IDF 的蓝牙配网示例 examples/bluetooth/blufi手机装一个 EspBlufi 应用Android / iOS 都有并开启蓝牙与位置权限Station 模式让设备连入已有网络上电等待初始化。动作给板上电打开串口工具。验证信号出现BLUFI VERSION 0102接着是BLUFI init finish此时设备已开始广播。用 EspBlufi 建立蓝牙连接。动作手机开启 Wi-Fi、蓝牙和位置权限打开 EspBlufi下拉刷新扫描点目标设备连接。验证信号串口打印BLUFI ble connect。选 Station填 SSID 和密码。动作点配网设备模式选 Station刷新列表挑一个2.4GHz网络输入密码点确定。验证信号依次出现BLUFI set WIFI opmode 1、Recv STA SSID xxx、Recv STA PASSWORD xxx最后是wifi: connected with xxx, channel x和ip_event: ip: 192.168.x.x——拿到 IP配网完成。SoftAP 模式让设备自己当热点蓝牙连接方式同上。配置热点参数配网界面选 SoftAP填入 SSID、密码、加密方式、信道、最大连接数点确定。验证信号串口连续打印Recv SOFTAP SSID xxx、Recv SOFTAP PASSWD xxx、Recv SOFTAP CHANNEL 10、Recv SOFTAP MAX CONN NUM 2。验证热点动作打开手机 Wi-Fi 列表应能看到刚配置的 SSID连上它。验证信号串口出现wifi: mode : softAP有设备接入时还会打印station xx:xx:xx:xx:xx:xx join。幕后机制安全通道是怎么搭起来的 上面每一步的背后其实是一条先协商、再加密、后连网的流水线。第一步建安全通道。蓝牙 GATT 连接建立后手机先发来一帧协商数据双方用 DH 算法交换参数、推导出共享密钥示例工程里就是blufi_dh_negotiate_data_handler在做这件事。协商完成后手机再发一帧控制帧来设置安全模式高 4 位决定控制帧、低 4 位决定数据帧各自是否带校验、是否加密。在此之前所有帧都是明文设置之后数据帧才真正进入加密状态。第二步分帧加密传输。之后 SSID、密码等每一项 Wi-Fi 参数都是独立的一帧数据格式如下字段长度字节作用类型1低 2 位区分控制帧/数据帧高 6 位是子类型SSID、密码、状态报告……帧控制1位标志加密、校验、传输方向、要求 ACK、是否有分片序列号1每发一帧自动 1重新连接后清零用来拒绝重放数据长度1数据字段的字节数数据N正文分片帧的前 2 字节是内容总长度校验2对序列号、长度和明文做 CRC16 校验数据超长怎么办帧控制的0x10位置 1 表示还有后续分片数据区开头的 2 字节会提前报出剩余内容的总长度最大支持 64K接收端据此一次性分配好内存再拼装——这就是大密码、企业级证书这类长数据能可靠送达的原因。第三步连网与状态回传。参数齐了之后手机发一帧连接到 AP控制帧设备端随即调用esp_wifi_connect()拿到 IP 后设备回发一帧连接状态报告把当前模式、连接状态、BSSID 等信息带回手机。至此整条链路闭环配网结束。接口速览设备端要注册的 4 个回调BluFi 框架负责帧的解析与拼装你只需提供安全函数。示例工程在 blufi_example_main.c 里注册的就是这 4 个// 协商数据处理解析 DH 协商数据产出待回发的响应 typedef void (*esp_blufi_negotiate_data_handler_t)(uint8_t *data, int len, uint8_t **output_data, int *output_len, bool *need_free); // 加密AES-128iv8 取帧的 8 位序列号原地加解密 typedef int (*esp_blufi_encrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len); // 解密与加密同长支持原地处理 typedef int (*esp_blufi_decrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len); // 校验CRC16返回值与帧尾校验字段比对 typedef uint16_t (*esp_blufi_checksum_func_t)(uint8_t iv8, uint8_t *data, int len);注册方式一句话把四个函数填进esp_blufi_callbacks_t结构体调用esp_blufi_register_callbacks()即可算法可整体替换成你自己实现的版本。选型与边界BluFi 适合谁适合无屏设备出厂前逐台配网产线/现场都适用要求 Wi-Fi 凭证不经过明文广播通道的场景批量设备各自独立配网、不想共用一个广播口令的产线。硬边界ESP32 系 Wi-Fi 只工作在 2.4GHzBluFi 下发的网络也只能是 2.4GHz 频段。与 SmartConfig 的取舍SmartConfig 只需手机 Wi-Fi、操作更轻但凭证走明文广播安全性弱BluFi 走蓝牙 DH AES-128 CRC16安全性高一档代价是手机必须有蓝牙并装 EspBlufi 类应用。官方现状⚠️ BluFi 目前处于维护模式不再新增功能。全新项目建议同时评估 ESP-IDF 配套的 network_provisioning 组件见 idf-extra-components它更安全且仍在积极维护。ESP32 蓝牙配网常见坑排错速查现象App 里看不到配网按钮或点了没反应。原因设备还没初始化完没到广播状态或手机蓝牙/位置权限没给足。处理重启设备等串口出现BLUFI init finish再扫描同时确认手机蓝牙与位置权限均已开启。现象配网成功流程走完但设备就是连不上目标 Wi-Fi。原因选中的是 5GHz 网络ESP32 不支持。处理换 2.4GHz 的 SSID 重新配网路由器双频合一时先拆成独立 SSID。现象提交后设备回报错误串口BLUFI report error。原因SSID/密码超长超过 32 字节会被判为数据格式错误、密码输错或 App 与设备协议版本不匹配。处理核对凭证长度与内容使用官方 EspBlufi 应用必要时重新拔插重启两端。现象重连后又出现 sequence/checksum/decrypt 类报错。原因蓝牙断开后旧的安全上下文没清干净序列号或密钥状态错乱。处理在ESP_BLUFI_EVENT_BLE_DISCONNECT事件里重置安全状态示例工程已做重连后重新走密钥协商。写在最后BluFi 用蓝牙当信使、DHAES 当保险箱的方式把最敏感的 Wi-Fi 凭证从明文的广播配网里挪了出来是无屏设备安全配网的成熟选项。完整示例代码在 examples/bluetooth/blufi协议细节与帧定义见官方文档 docs/zh_CN/api-guides/ble/blufi.rst动手前各读一遍基本可以少踩一半坑。【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考