ESP-IDF BluFi 完整指南：3 步用蓝牙给 ESP32 配好 Wi-Fi

ESP-IDF BluFi 完整指南3 步用蓝牙给 ESP32 配好 Wi-Fi【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf手里有一块没屏幕、没网口的 ESP32 开发板Wi-Fi 密码只能写死在代码里换个办公室就得重新烧录其实不必这么麻烦。ESP-IDF 内置了一套叫BluFi的配网协议ESP32 变身蓝牙 GATT Server手机装个 App 连上来几秒内就能把 SSID 和密码安全地送进设备。下面带你从零跑通再拆开它的内部机制。一句话讲透 BluFi 是什么BluFi 是基于蓝牙通道的 Wi-Fi 网络配置功能设备负责收手机负责发中间用密钥协商 对称加密保证凭证不以明文落地。它的几个核心亮点安全传输默认 DH 协商共享密钥再用 128 位 AES 加密数据密码全程不明文分片机制单帧装不下的长数据如企业级 CA 证书可拆分发送总长最大支持 64 KB双向通信设备既能收配置也能回报 Wi-Fi 状态、扫描周边热点列表三种网络模式Station连网、SoftAP开热点、二者同时开启协议全开源加密、校验、协商算法都是可注册的回调可按需替换快速上手ESP32 蓝牙配 Wi-Fi 三步法 准备工作类别清单硬件ESP32 / ESP32-C2 / C3 / C5 / C6 / C61 / S3 / S31 开发板一块 USB 数据线设备端烧录 BluFi 示例工程clone 仓库命令git clone https://gitcode.com/GitHub_Trending/es/esp-idf手机端安装官方 EspBlufi 应用Android / iOS 均有第一步烧录并观察串口idf.py set-target esp32 idf.py -p PORT flash monitor看到BLUFI init finish字样说明设备已就绪、开始广播。第二步手机连接设备打开手机 Wi-Fi、蓝牙和位置权限BLE 扫描依赖它打开 EspBlufi 下拉刷新点目标设备连接。第三步下发 Wi-Fi 配置并验证点配网按钮选Station模式 → 刷新列表选目标 AP → 输入密码 → 确定若选SoftAP模式则填写热点 SSID、密码、加密方式、信道和最大连接数验证方式有两处串口日志出现BLUFI ble connect及got ip信息EspBlufi 界面回显 AP 的 BSSID、SSID 与连接状态。SoftAP 模式下还能直接用手机搜索到刚创建的热点原理拆解密码如何从手机安全走到 ESP32BluFi 并不是独立协议栈它架在标准 BLE 之上。先看下 ESP-IDF 的蓝牙分层结构BluFi 工作在最上层它复用 GATT 通道自己定义了一套帧格式 应用层安全与底层用 Bluedroid 还是 NimBLE 无关。第一层通道怎么搭设备开机后以 GATT Server 身份发出自定义广播数据手机作为 GATT Client 连上来。通信走两个固定特性UUID方向权限0xFF01手机 → ESP32可写0xFF02ESP32 → 手机可读可通知第二层一次完整配网的 6 个动作设备广播手机扫码式发现并建立 GATT 连接手机发数据帧开始密钥协商默认 DH也可换 RSA/ECC协商完成后手机发控制帧设置安全模式控制帧和数据帧各自独立开关加密/校验手机分帧发送 SSID、密码、认证证书等数据帧手机发连接 AP控制帧设备开始连网设备回发状态报告帧配网闭环第三层安全靠什么兜底防重放每发一帧序列号自增 1 并参与校验重连后清零完整性校验默认 CRC16覆盖序列号、长度和明文加密对称加/解密前后长度必须一致支持原地操作分片帧控制位标记后数据区前 2 字节先报总长接收端据此预分配内存进阶细节帧格式与安全回调 基础帧结构字段长度说明类型1 B低 2 位分控制帧/数据帧高 6 位为子类型SSID、密码、状态报告等帧控制1 B见下方位定义序列号1 B防重放数据长度1 B不含校验数据N B分片帧的前 2 字节为内容总长度校验2 B校验序列号 长度 明文帧控制位位含义0x01数据字段是否加密控制帧恒为 00x02帧尾是否携带校验0x04传输方向1 为设备 → 手机0x08是否要求对端回 ACK0x10是否还有后续分片设备端要实现的回调协议把算法选择权交给开发者注册时提供四个函数即可typedef void (*esp_blufi_negotiate_data_handler_t)(uint8_t *data, int len, uint8_t **output_data, int *output_len, bool *need_free); 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); typedef uint16_t (*esp_blufi_checksum_func_t)(uint8_t iv8, uint8_t *data, int len);口语化解释第一个回调处理协商数据算完把要回发什么通过output_data带出来后三个分别实现加密、解密、校验iv8用帧的 8 位序列号充当 IV。通过esp_blufi_register_callbacks()一次性挂入完整定义可查 esp_blufi API 参考示例中的默认实现DH AES CRC在 blufi_security.c 里建议精读一遍。适用场景与优势谁最适合用它无屏幕、无键盘的 IoT 终端智能插座、传感器网关——配网全靠手机产线批量烧录后现场配网免进网、免扫码需要设备反向回报连接状态或扫描列表的中高端产品相比传统方式比硬编码密码省掉了换网就重烧的代价比纯 SoftAP 热点配网多了端到端加密凭证不会在局域网里裸奔协议本身极简移植到自研 App 成本不高。排坑指南现象 → 原因 → 解法 现象手机蓝牙列表里根本看不到设备→ 原因iOS/Android 的 BLE 扫描依赖定位权限没开就扫不到或设备广播名太通用被淹没 → 解法授予位置权限把广播设备名改成有辨识度的字符串再扫现象EspBlufi 连上了但配网按钮置灰→ 原因蓝牙权限未完全授予或 GATT 连接实际未建立 → 解法重启 ESP32 重新广播确认系统设置里蓝牙权限为允许现象列表里选不到 5 GHz 网络或选中后连不上→ 原因ESP32 系 Wi-Fi 射频只支持 2.4 GHz → 解法把路由器拆成 2.4 G/5 G 双频或单独走 2.4 GHz 网络现象串口收到异常报告帧序列/校验/解密错误→ 原因安全模式控制帧未先于数据帧下发或双端校验/加密算法不一致 → 解法检查手机端流程先 0x01 控制帧设置安全模式再发数据帧对照 BluFi 协议文档 核对算法疑问新项目要不要选 BluFi→ 原因官方已宣布 BluFi 进入维护模式不再新增功能 → 解法存量设备继续用没问题新项目建议评估 ESP-IDF 生态中的network_provisioning组件SoftAP / QR / BLE 多模式仍在积极维护写在最后BluFi 用一套轻量帧协议 可插拔安全回调把无屏设备怎么配网这个老问题解得干净利落。下一步不妨把示例里的默认 DH AES 换成你自己的算法或者把esp_blufi_register_callbacks()集成进现有产品动手跑通一次 Station 配网协议的所有细节都会瞬间清晰。【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考