个人开发技术分享 ESP Dev Center

开始前适用开发板：ESP32-S3 Korvo · 开发框架：ESP-IDF

适用开发板：Korvo S3 · 工程 02.beginner.blufi · target esp32s3
通用概念：配网教程
学习时长：约 25 分钟 · 难度：★★★☆☆

学习目标

完成本节后，你将能够：

理解 BluFi 配网的完整流程与安全机制
区分 BluFi 与普通 BLE 透传的本质差异
掌握 BluFi 回调事件的处理方法
了解产品级无屏配网方案的设计思路

1. 这个例子在干嘛

让用户不需要改代码就能配置 Wi-Fi——通过手机蓝牙将 Wi-Fi 信息安全地发送给设备。

这是产品常见的「开箱体验」：新设备没有屏幕和键盘，用户如何告诉它 Wi-Fi 密码？答案是 BluFi——蓝牙配网。

完整配网流程

用户操作                              设备内部
─────────                           ──────────
1. 设备上电                         → 进入 BluFi 广播模式
                                      （蓝牙在"喊"：我在这里！）

2. 手机打开 EspBlufi App            → 扫描到设备
   ↓
3. 点击连接                         → BLE 连接建立

4. App 与设备自动安全协商            → DH 密钥交换（blufi_security.c）
   ↓                                  双方生成共享密钥
5. 输入 Wi-Fi SSID / 密码           → 加密传输到设备
   ↓
6. 设备收到 Wi-Fi 信息              → esp_wifi_connect()
   ↓
7. 连接成功                         → 屏幕/串口显示 GOT_IP
                                      蓝牙可选择断开

BluFi vs 普通 BLE 透传

对比项	BluFi	BLE SPP 透传
协议	乐鑫定义的配网专用协议	通用 BLE 串口透传
安全性	DH 密钥交换 + AES 加密	无内建加密
用途	Wi-Fi 配网	通用数据传输
App	EspBlufi（专用）	任意 BLE 调试工具
易用性	流程固定，开箱即用	需自定义协议

2. 编译烧录

cd Korvo_Firmware\02.beginner.blufi
idf.py set-target esp32s3
idf.py build flash monitor

提示：BluFi 同时使用 Wi-Fi 和蓝牙，Flash 空间需求较大。若编译报空间不足，检查分区表。

3. 手机端操作步骤

3.1 安装 App

下载 Espressif 官方 EspBlufi App：

Android：各应用商店搜索 "EspBlufi"
iOS：App Store 搜索 "EspBlufi"

3.2 配网步骤

开启手机蓝牙
打开 EspBlufi App → 搜索设备
找到设备名（源码中定义的广播名，通常含 "BLUFI" 字样）→ 点击连接
连接成功后，App 显示配网界面
选择或输入 Wi-Fi SSID 和密码
点击「配网」发送
等待设备连接 Wi-Fi
成功：设备串口/屏幕显示 GOT IP

4. 运行现象

阶段	屏幕表现	串口输出
启动	等待配网提示	`BluFi init OK` / 广播开始
App 连接	连接状态更新	`BLUFI_EVENT_INIT_FINISH`
安全协商	—	DH 协商日志
收到 Wi-Fi	开始连接	`SSID: xxx, Password: ***`
联网成功	显示 IP	`GOT_IP: 192.168.x.x`
联网失败	错误提示	`WIFI_EVENT_STA_DISCONNECTED`

5. 关键文件与代码解析

文件	作用	重点关注
`main/app_main.c`	主流程、NVS/Wi-Fi/BLE 初始化	初始化顺序
`main/blufi_init.c`	BluFi 初始化、回调注册	`esp_blufi_register_callbacks`
`main/blufi_security.c`	DH 密钥交换、AES 加密	安全相关

核心回调事件

esp_blufi_cb_t callbacks = {
    .event_cb = blufi_event_callback,
    .negotiate_data_handler = blufi_dh_negotiate_data_handler,
    .encrypt_func  = blufi_aes_encrypt,
    .decrypt_func  = blufi_aes_decrypt,
    .checksum_func = blufi_crc_checksum,
};

事件回调中的关键处理

blufi_event_callback(event) {
    switch (event->id) {
        case ESP_BLUFI_EVENT_INIT_FINISH:
            → 开始 BLE 广播
            
        case ESP_BLUFI_EVENT_DEINIT_FINISH:
            → 清理资源
            
        case ESP_BLUFI_EVENT_SET_WIFI_OPMODE:
            → 设置 Wi-Fi 模式（STA）
            
        case ESP_BLUFI_EVENT_BLE_CONNECT:
            → App 已连接，停止广播（可选）
            
        case ESP_BLUFI_EVENT_RECV_STA_SSID:
            → 存储收到的 SSID
            
        case ESP_BLUFI_EVENT_RECV_STA_PASSWD:
            → 存储收到的密码
            
        case ESP_BLUFI_EVENT_RECV_SLAVE_DISCONNECT_BLE:
            → App 请求断开 BLE
            
        case ESP_BLUFI_EVENT_GET_WIFI_STATUS:
            → App 查询当前 Wi-Fi 状态 → 返回
    }
}

安全协商流程（blufi_security.c）

1. App 发起协商 → negotiate_data_handler
2. 双方 DH（Diffie-Hellman）密钥交换
3. 生成共享密钥 → 后续数据 AES 加密
4. CRC 校验保证数据完整性

安全建议：blufi_security.c 中的密钥协商不要随意关闭——虽然关闭后也能配网，但密码会明文传输，存在被嗅探风险。

6. 常见问题与排查

现象	可能原因	解决方案
App 搜不到设备	蓝牙天线/PCB 天线问题	确认板子蓝牙正常；靠近手机
App 搜不到设备	广播名被改或未启动	检查 `blufi_init.c` 广播参数
App 搜不到设备	已被其他手机连接	BluFi 默认只支持单连接
配网后连接失败	Wi-Fi 密码错误	2.4GHz？密码大小写？
配网后连接失败	路由器隐藏 SSID	关闭隐藏或使用 BSSID 连接
连上又断开	回调中重复调用 `esp_wifi_connect`	检查事件处理逻辑，避免重复
安全协商失败	mbedTLS 配置不当	检查 `menuconfig` → mbedTLS 选项

7. 动手改造建议

自定义广播名：修改 blufi_init.c 中的设备名为你的产品名
配网成功大字提示：连接成功后在 LVGL 屏幕大字显示 IP 地址
配网 + MQTT：配网成功后自动连接 MQTT Broker
记忆 Wi-Fi：将 SSID/密码存入 NVS，下次上电自动连接，连接失败再进入 BluFi 模式
超时机制：BluFi 广播 3 分钟无人连接 → 自动关闭蓝牙省电

8. 知识延伸

配网方案对比：

方案优点缺点
BluFi 安全、成熟、有 App 需要蓝牙
SmartConfig 无需蓝牙安全性低、兼容性差
SoftAP 设备开热点配网手机需切换 Wi-Fi
硬编码最简单不灵活
BLE GATT 基础：BluFi 底层使用 BLE GATT（Generic Attribute Profile）服务，定义了特定的 Service UUID 和 Characteristic UUID
ESP32-S3 蓝牙：支持 BLE 5.0（低功耗蓝牙），不支持经典蓝牙（BR/EDR）

方案	优点	缺点
BluFi	安全、成熟、有 App	需要蓝牙
SmartConfig	无需蓝牙	安全性低、兼容性差
SoftAP	设备开热点配网	手机需切换 Wi-Fi
硬编码	最简单	不灵活

9. 下一步

方向	推荐例程	说明
Wi-Fi 基础	wifi_station	硬编码 SSID 直连
BLE 串口透传	`02.beginner.ble_spp_server`	通用 BLE 数据通道
MQTT 通信	MQTT	配网后的典型应用
通用配网教程	配网教程	多种方案对比

酷世DIY · Kevincoooool

在 Web Flasher 中打开选择对应固件并烧录 打开 Web Serial查看运行日志 查看示例工程来源打开 GitHub 文档版本

开始前适用开发板：ESP32-S3 Korvo · 开发框架：ESP-IDF

适用开发板：Korvo S3 · 工程 02.beginner.blufi · target esp32s3
通用概念：配网教程
学习时长：约 25 分钟 · 难度：★★★☆☆

学习目标

完成本节后，你将能够：

理解 BluFi 配网的完整流程与安全机制
区分 BluFi 与普通 BLE 透传的本质差异
掌握 BluFi 回调事件的处理方法
了解产品级无屏配网方案的设计思路

1. 这个例子在干嘛

让用户不需要改代码就能配置 Wi-Fi——通过手机蓝牙将 Wi-Fi 信息安全地发送给设备。

这是产品常见的「开箱体验」：新设备没有屏幕和键盘，用户如何告诉它 Wi-Fi 密码？答案是 BluFi——蓝牙配网。

完整配网流程

用户操作                              设备内部
─────────                           ──────────
1. 设备上电                         → 进入 BluFi 广播模式
                                      （蓝牙在"喊"：我在这里！）

2. 手机打开 EspBlufi App            → 扫描到设备
   ↓
3. 点击连接                         → BLE 连接建立

4. App 与设备自动安全协商            → DH 密钥交换（blufi_security.c）
   ↓                                  双方生成共享密钥
5. 输入 Wi-Fi SSID / 密码           → 加密传输到设备
   ↓
6. 设备收到 Wi-Fi 信息              → esp_wifi_connect()
   ↓
7. 连接成功                         → 屏幕/串口显示 GOT_IP
                                      蓝牙可选择断开

BluFi vs 普通 BLE 透传

对比项	BluFi	BLE SPP 透传
协议	乐鑫定义的配网专用协议	通用 BLE 串口透传
安全性	DH 密钥交换 + AES 加密	无内建加密
用途	Wi-Fi 配网	通用数据传输
App	EspBlufi（专用）	任意 BLE 调试工具
易用性	流程固定，开箱即用	需自定义协议

2. 编译烧录

cd Korvo_Firmware\02.beginner.blufi
idf.py set-target esp32s3
idf.py build flash monitor

提示：BluFi 同时使用 Wi-Fi 和蓝牙，Flash 空间需求较大。若编译报空间不足，检查分区表。

3. 手机端操作步骤

3.1 安装 App

下载 Espressif 官方 EspBlufi App：

Android：各应用商店搜索 "EspBlufi"
iOS：App Store 搜索 "EspBlufi"

3.2 配网步骤

开启手机蓝牙
打开 EspBlufi App → 搜索设备
找到设备名（源码中定义的广播名，通常含 "BLUFI" 字样）→ 点击连接
连接成功后，App 显示配网界面
选择或输入 Wi-Fi SSID 和密码
点击「配网」发送
等待设备连接 Wi-Fi
成功：设备串口/屏幕显示 GOT IP

4. 运行现象

阶段	屏幕表现	串口输出
启动	等待配网提示	`BluFi init OK` / 广播开始
App 连接	连接状态更新	`BLUFI_EVENT_INIT_FINISH`
安全协商	—	DH 协商日志
收到 Wi-Fi	开始连接	`SSID: xxx, Password: ***`
联网成功	显示 IP	`GOT_IP: 192.168.x.x`
联网失败	错误提示	`WIFI_EVENT_STA_DISCONNECTED`

5. 关键文件与代码解析

文件	作用	重点关注
`main/app_main.c`	主流程、NVS/Wi-Fi/BLE 初始化	初始化顺序
`main/blufi_init.c`	BluFi 初始化、回调注册	`esp_blufi_register_callbacks`
`main/blufi_security.c`	DH 密钥交换、AES 加密	安全相关

核心回调事件

esp_blufi_cb_t callbacks = {
    .event_cb = blufi_event_callback,
    .negotiate_data_handler = blufi_dh_negotiate_data_handler,
    .encrypt_func  = blufi_aes_encrypt,
    .decrypt_func  = blufi_aes_decrypt,
    .checksum_func = blufi_crc_checksum,
};

事件回调中的关键处理

blufi_event_callback(event) {
    switch (event->id) {
        case ESP_BLUFI_EVENT_INIT_FINISH:
            → 开始 BLE 广播
            
        case ESP_BLUFI_EVENT_DEINIT_FINISH:
            → 清理资源
            
        case ESP_BLUFI_EVENT_SET_WIFI_OPMODE:
            → 设置 Wi-Fi 模式（STA）
            
        case ESP_BLUFI_EVENT_BLE_CONNECT:
            → App 已连接，停止广播（可选）
            
        case ESP_BLUFI_EVENT_RECV_STA_SSID:
            → 存储收到的 SSID
            
        case ESP_BLUFI_EVENT_RECV_STA_PASSWD:
            → 存储收到的密码
            
        case ESP_BLUFI_EVENT_RECV_SLAVE_DISCONNECT_BLE:
            → App 请求断开 BLE
            
        case ESP_BLUFI_EVENT_GET_WIFI_STATUS:
            → App 查询当前 Wi-Fi 状态 → 返回
    }
}

安全协商流程（blufi_security.c）

1. App 发起协商 → negotiate_data_handler
2. 双方 DH（Diffie-Hellman）密钥交换
3. 生成共享密钥 → 后续数据 AES 加密
4. CRC 校验保证数据完整性

安全建议：blufi_security.c 中的密钥协商不要随意关闭——虽然关闭后也能配网，但密码会明文传输，存在被嗅探风险。

6. 常见问题与排查

现象	可能原因	解决方案
App 搜不到设备	蓝牙天线/PCB 天线问题	确认板子蓝牙正常；靠近手机
App 搜不到设备	广播名被改或未启动	检查 `blufi_init.c` 广播参数
App 搜不到设备	已被其他手机连接	BluFi 默认只支持单连接
配网后连接失败	Wi-Fi 密码错误	2.4GHz？密码大小写？
配网后连接失败	路由器隐藏 SSID	关闭隐藏或使用 BSSID 连接
连上又断开	回调中重复调用 `esp_wifi_connect`	检查事件处理逻辑，避免重复
安全协商失败	mbedTLS 配置不当	检查 `menuconfig` → mbedTLS 选项

7. 动手改造建议

自定义广播名：修改 blufi_init.c 中的设备名为你的产品名
配网成功大字提示：连接成功后在 LVGL 屏幕大字显示 IP 地址
配网 + MQTT：配网成功后自动连接 MQTT Broker
记忆 Wi-Fi：将 SSID/密码存入 NVS，下次上电自动连接，连接失败再进入 BluFi 模式
超时机制：BluFi 广播 3 分钟无人连接 → 自动关闭蓝牙省电

8. 知识延伸

配网方案对比：

方案优点缺点
BluFi 安全、成熟、有 App 需要蓝牙
SmartConfig 无需蓝牙安全性低、兼容性差
SoftAP 设备开热点配网手机需切换 Wi-Fi
硬编码最简单不灵活
BLE GATT 基础：BluFi 底层使用 BLE GATT（Generic Attribute Profile）服务，定义了特定的 Service UUID 和 Characteristic UUID
ESP32-S3 蓝牙：支持 BLE 5.0（低功耗蓝牙），不支持经典蓝牙（BR/EDR）

方案	优点	缺点
BluFi	安全、成熟、有 App	需要蓝牙
SmartConfig	无需蓝牙	安全性低、兼容性差
SoftAP	设备开热点配网	手机需切换 Wi-Fi
硬编码	最简单	不灵活

9. 下一步

方向	推荐例程	说明
Wi-Fi 基础	wifi_station	硬编码 SSID 直连
BLE 串口透传	`02.beginner.ble_spp_server`	通用 BLE 数据通道
MQTT 通信	MQTT	配网后的典型应用
通用配网教程	配网教程	多种方案对比

酷世DIY · Kevincoooool

在 Web Flasher 中打开选择对应固件并烧录 打开 Web Serial查看运行日志 查看示例工程来源打开 GitHub 文档版本

Korvo · BluFi 蓝牙配网

学习目标

1. 这个例子在干嘛

完整配网流程

BluFi vs 普通 BLE 透传

2. 编译烧录

3. 手机端操作步骤

3.1 安装 App

3.2 配网步骤

4. 运行现象

5. 关键文件与代码解析

核心回调事件

事件回调中的关键处理

安全协商流程（blufi_security.c）

6. 常见问题与排查

7. 动手改造建议

8. 知识延伸

9. 下一步

Korvo · BluFi 蓝牙配网

学习目标

1. 这个例子在干嘛

完整配网流程

BluFi vs 普通 BLE 透传

2. 编译烧录

3. 手机端操作步骤

3.1 安装 App

3.2 配网步骤

4. 运行现象

5. 关键文件与代码解析

核心回调事件

事件回调中的关键处理

安全协商流程（blufi_security.c）

6. 常见问题与排查

7. 动手改造建议

8. 知识延伸

9. 下一步