ESP32 BLE广播实战：5分钟搞定自定义数据包（附nRF Connect调试技巧）-育师

ESP32 BLE广播实战：5分钟搞定自定义数据包（附nRF Connect调试技巧）

如果你手头正好有一块ESP32开发板，想快速实现一个物联网设备信息广播的功能，比如让手机能直接扫描到设备状态、传感器读数或者自定义的标识信息，那么这篇文章就是为你准备的。很多开发者初次接触BLE广播时，容易被复杂的协议栈和API淹没，但其实核心的广播功能，尤其是发送自定义数据，用ESP-IDF框架可以非常简洁地实现。今天我们不深入代码细节，而是从“硬件交互”和“移动端可视化调试”的视角，带你走一遍完整的流程。你将看到如何用几行代码配置一个包含自定义十六进制数据的广播包，并立刻用手机上的nRF Connect应用验证广播内容是否按预期发送。整个过程力求直观、可操作，即使你之前没有深入接触过BLE，也能跟着步骤快速上手。

1. 理解BLE广播：从“喊话”到“握手”

在低功耗蓝牙的世界里，设备间的初次接触大多始于广播。你可以把广播想象成一个设备在人群中不断喊出自己的名字和一些基本信息。这个“喊话”的设备被称为外围设备或从机，而聆听并可能做出回应的设备（通常是手机、平板或中央网关）则被称为中心设备或主机。

广播的核心目的是被发现和建立连接，但也有很多场景下，设备只需要单向地、周期性地向外发送信息，而不需要建立稳定的双向连接。例如：

信标：如iBeacon、Eddystone，用于室内定位或信息推送。
传感器节点：定期广播温度、湿度等读数，由附近的网关收集。
设备状态指示器：广播电池电量、运行模式等。

广播数据包本身有严格的格式和长度限制（通常为31字节），这31个字节需要承载多种类型的信息。ESP-IDF的esp_ble_adv_data_t结构体为我们封装了这些细节，我们只需关心填充哪些字段。一个典型的广播包可能包含以下部分：

数据段类型	说明	示例/常用值
Flags	广播模式标识，如“可被发现”、“可连接”等。	`ESP_BLE_ADV_FLAG_GEN_DISC`
设备名称	人类可读的设备标识。	`"ESP32_Sensor_01"`
服务UUID	告知扫描者本设备支持的服务类型。	心率服务`0x180D`
制造商特定数据	自定义数据的核心区域，可自由定义格式。	`{0xAA, 0xBB, 0x01, 0x02}`
发射功率	设备的信号强度参考值，用于距离估算。	包含`include_txpower`
外观	设备类型的图标标识，如手表、温度计。	`ESP_BLE_APPEARANCE_GENERIC_THERMOMETER`

广播事件并非持续不断，而是以特定的时间间隔（Advertising Interval）周期性发生。每次广播事件会在三个不同的射频通道（37, 38, 39）上发送相同的数据包，以提高被发现的概率。广播间隔直接影响功耗和被发现的速度，需要在两者间权衡。

提示：广播间隔的单位是0.625毫秒。例如，将adv_int_min和adv_int_max设置为0x20和0x40，意味着广播间隔在320.625ms=20ms到640.625ms=40ms之间随机选择，这属于较快的广播频率，适用于需要快速被发现的场景。

2. 五分钟实战：配置并发送自定义广播包

让我们直接进入实战环节。假设我们要让ESP32广播一个包含设备序列号（例如0xDEADBEEF）和当前固件版本号（例如0x0102）的数据包。我们将使用制造商特定数据字段来承载这些信息。

2.1 工程准备与基础配置

首先，确保你的开发环境已搭建好ESP-IDF。创建一个新的项目或打开一个已有的BLE示例工程（如ble_adv）。在main函数或你的广播初始化函数中，我们需要完成蓝牙控制器的初始化和使能。

#include "esp_bt.h" #include "esp_bt_main.h" #include "esp_gap_ble_api.h" #include "esp_log.h" static const char *TAG = "BLE_ADV_DEMO"; void ble_init(void) { // 1. 初始化NVS（非易失性存储），蓝牙配置会用到 esp_err_t ret = nvs_flash_init(); if (ret == ESP_ERR_NVS_NO_FREE_PAGES || ret == ESP_ERR_NVS_NEW_VERSION_FOUND) { ESP_ERROR_CHECK(nvs_flash_erase()); ret = nvs_flash_init(); } ESP_ERROR_CHECK(ret); // 2. 释放经典蓝牙占用的内存（因为我们只用BLE） ESP_ERROR_CHECK(esp_bt_controller_mem_release(ESP_BT_MODE_CLASSIC_BT)); // 3. 初始化并启用BLE控制器 esp_bt_controller_config_t bt_cfg = BT_CONTROLLER_INIT_CONFIG_DEFAULT(); ret = esp_bt_controller_init(&bt_cfg); if (ret != ESP_OK) { ESP_LOGE(TAG, "控制器初始化失败: %s", esp_err_to_name(ret)); return; } ret = esp_bt_controller_enable(ESP_BT_MODE_BLE); if (ret != ESP_OK) { ESP_LOGE(TAG, "控制器使能失败: %s", esp_err_to_name(ret)); return; } // 4. 初始化并启用Bluedroid协议栈 ret = esp_bluedroid_init(); if (ret != ESP_OK) { ESP_LOGE(TAG, "Bluedroid初始化失败: %s", esp_err_to_name(ret)); return; } ret = esp_bluedroid_enable(); if (ret != ESP_OK) { ESP_LOGE(TAG, "Bluedroid使能失败: %s", esp_err_to_name(ret)); return; } // 5. 注册GAP事件回调函数（下一步实现） ret = esp_ble_gap_register_callback(gap_event_handler); if (ret != ESP_OK) { ESP_LOGE(TAG, "GAP回调注册失败: %s", esp_err_to_name(ret)); } }

2.2 定义并填充自定义数据

接下来，我们定义要广播的自定义数据。制造商特定数据字段通常以两个字节的制造商ID开头（由蓝牙技术联盟分配），后面跟着自定义的有效载荷。对于测试或个人项目，你可以使用一个测试ID（如0xFFFF）或直接开始放置你的数据。这里我们定义一个简单的6字节数组：前两个字节作为我们虚拟的“公司ID”，后四个字节是我们的自定义信息。

// 自定义广播数据 // 假设公司ID为 0xFEED (仅用于示例，实际项目应使用正式分配的ID) // 数据载荷：0xDE 0xAD 0xBE 0xEF 作为序列号，0x01 0x02 作为版本号 static uint8_t custom_manufacturer_data[] = { 0xED, 0xFE, // 公司ID (Little-Endian: 0xFEED) 0xDE, 0xAD, 0xBE, 0xEF, // 自定义数据：序列号 0x01, 0x02 // 自定义数据：固件主版本.次版本 };

现在，我们配置广播数据结构和广播参数结构体。

// 广播数据结构体 static esp_ble_adv_data_t adv_data = { .set_scan_rsp = false, // 这是广播数据包，不是扫描响应包 .include_name = true, // 包含设备名称 .include_txpower = false, // 不包含发射功率（可节省字节） .min_interval = 0x20, // 最小连接间隔建议值（可选） .max_interval = 0x40, // 最大连接间隔建议值（可选） .appearance = ESP_BLE_APPEARANCE_GENERIC_TAG, // 设备显示为“通用标签” .manufacturer_len = sizeof(custom_manufacturer_data), // 自定义数据长度 .p_manufacturer_data = custom_manufacturer_data, // 指向自定义数据的指针 .service_data_len = 0, // 无服务数据 .p_service_data = NULL, .service_uuid_len = 0, // 无服务UUID .p_service_uuid = NULL, .flag = (ESP_BLE_ADV_FLAG_GEN_DISC | ESP_BLE_ADV_FLAG_BREDR_NOT_SPT), // 通用可发现，不支持经典蓝牙 }; // 广播参数结构体 static esp_ble_adv_params_t adv_params = { .adv_int_min = 0x320, // 最小广播间隔：0x320 * 0.625ms = 500ms .adv_int_max = 0x640, // 最大广播间隔：0x640 * 0.625ms = 1000ms .adv_type = ADV_TYPE_IND, // 可连接、可扫描的非定向广播 .own_addr_type = BLE_ADDR_TYPE_PUBLIC, // 使用公共地址 .channel_map = ADV_CHNL_ALL, // 在所有三个广播通道上发送 .adv_filter_policy = ADV_FILTER_ALLOW_SCAN_ANY_CON_ANY, // 允许任何设备扫描和连接 .peer_addr_type = BLE_ADDR_TYPE_PUBLIC, .peer_addr = {0}, // 非定向广播，对端地址无关 };

2.3 实现GAP事件回调并启动广播

我们需要一个GAP事件回调函数来处理广播配置完成和启动完成的事件。

static void gap_event_handler(esp_gap_ble_cb_event_t event, esp_ble_gap_cb_param_t *param) { esp_err_t err; switch (event) { case ESP_GAP_BLE_ADV_DATA_SET_COMPLETE_EVT: // 广播数据设置完成，可以开始广播了 ESP_LOGI(TAG, "广播数据设置完成"); err = esp_ble_gap_start_advertising(&adv_params); if (err != ESP_OK) { ESP_LOGE(TAG, "开始广播失败: %s", esp_err_to_name(err)); } break; case ESP_GAP_BLE_ADV_START_COMPLETE_EVT: // 广播启动完成事件 if (param->adv_start_cmpl.status == ESP_BT_STATUS_SUCCESS) { ESP_LOGI(TAG, "广播已成功启动"); } else { ESP_LOGE(TAG, "广播启动失败，错误码: %d", param->adv_start_cmpl.status); } break; // 可以根据需要处理其他事件，如连接建立、断开等 default: break; } }

最后，在初始化完成后，我们设置设备名称并配置广播数据。

void start_custom_advertising(void) { // 设置一个容易识别的设备名称 esp_ble_gap_set_device_name("My_Custom_Beacon"); // 配置广播数据，这会触发 ESP_GAP_BLE_ADV_DATA_SET_COMPLETE_EVT 事件 esp_err_t ret = esp_ble_gap_config_adv_data(&adv_data); if (ret != ESP_OK) { ESP_LOGE(TAG, "配置广播数据失败: %s", esp_err_to_name(ret)); } }

将ble_init()和start_custom_advertising()调用放入你的app_main()函数中，编译并烧录到ESP32。如果一切正常，ESP32的日志应该会显示“广播已成功启动”。现在，你的设备已经开始以500ms到1000ms的间隔，向外广播包含你自定义数据的信号了。

3. 使用nRF Connect进行可视化调试与验证

代码写好了，设备也在运行，但我们怎么知道它确实在广播我们期望的数据呢？这时，一个强大的手机调试工具就派上用场了。nRF Connect是Nordic Semiconductor开发的一款免费的蓝牙调试应用，支持Android和iOS，它能以非常直观的方式展示广播包的所有细节。

3.1 安装与基础扫描

在你的手机上（Android或iOS）的应用商店搜索“nRF Connect”并安装。
打开应用，确保手机的蓝牙已开启。
点击顶部的“SCAN”按钮，应用会开始扫描附近的BLE设备。
在设备列表中，你应该能看到名为“My_Custom_Beacon”的设备（或者你设置的设备名）。注意看它的信号强度（RSSI）和地址。

3.2 深度解析广播数据

点击列表中的“My_Custom_Beacon”设备，进入详细视图。这里的信息非常丰富：

设备信息：显示了MAC地址、信号强度、连接状态等。
广播数据：这是关键部分。nRF Connect会将原始的广播字节流解析成人类可读的格式。

你应该能看到类似下面的解析结果：

ADVERTISEMENT DATA Flags: 0x06 (LE General Discoverable Mode, BR/EDR Not Supported) Complete Local Name: 'My_Custom_Beacon' Manufacturer Specific Data: 0xFEED DEADBEEF 0102 Appearance: Generic Tag (0x0200)

让我们仔细看看“制造商特定数据”这一行：

0xFEED：这就是我们定义的公司ID（注意nRF Connect显示的是大端字节序，所以我们定义的0xED, 0xFE被正确解析为0xFEED）。
DEADBEEF 0102：这就是我们紧随其后的6个字节的自定义数据，被清晰地显示为十六进制。

注意：如果你没有看到“制造商特定数据”字段，或者数据看起来不对，请检查以下几点：
manufacturer_len是否正确设置为数据数组的长度。
数据数组的内容是否正确。
广播包总长度是否超过31字节。你可以通过勾选或取消勾选include_txpower、include_name等字段来调整。

3.3 进阶技巧：RAW数据视图与扫描响应

nRF Connect还提供了“RAW”数据视图，可以查看原始的字节序列。这对于调试复杂或非标准的数据格式非常有用。点击“查看RAW数据”，你会看到类似这样的字节流：

02 01 06 0D 09 4D 79 5F 43 75 73 74 6F 6D 5F 42 65 61 63 6F 6E FF 06 ED FE DE AD BE EF 01 02 03 02 00 02

我们可以简单解析一下：

02 01 06：长度2，类型0x01（Flags），值0x06。
0D 09 ...：长度13，类型0x09（完整设备名），后面是“My_Custom_Beacon”的ASCII码。
FF 06 ED FE DE AD BE EF 01 02：长度6，类型0xFF（制造商特定数据），后面是我们的6字节数据。
03 02 00 02：长度3，类型0x02（16位UUID列表），值0x0200（外观：通用标签）。

此外，你还可以配置扫描响应数据。扫描响应是当中心设备主动发送扫描请求时，外围设备回复的一个额外数据包（同样最多31字节）。这可以用来携带更多在初始广播包中放不下的信息。在esp_ble_adv_data_t中，只需将set_scan_rsp设置为true，并填充另一个数据包即可。

static esp_ble_adv_data_t scan_rsp_data = { .set_scan_rsp = true, .include_name = false, // 扫描响应可以放更多自定义数据 .manufacturer_len = sizeof(additional_data), .p_manufacturer_data = additional_data, // ... 其他字段 }; // 先配置广播数据，再配置扫描响应数据 esp_ble_gap_config_adv_data(&adv_data); esp_ble_gap_config_adv_data(&scan_rsp_data);

在nRF Connect中，当设备被扫描时，广播数据和扫描响应数据会被合并显示，让你能完整看到设备提供的所有信息。

4. 广播参数调优与常见问题排查

成功发送和验证了基本广播后，你可能需要根据实际应用调整参数。下面是一个关键参数调优指南和问题排查清单。

4.1 关键参数调优

广播行为主要由esp_ble_adv_params_t中的参数控制。理解它们对功耗和性能的影响至关重要。

参数	含义与影响	推荐值/范围
`adv_int_min`/`adv_int_max`	广播间隔的最小值和最大值。单位是0.625ms。值越大，广播频率越低，功耗越小，但被发现的延迟可能增加。	低功耗应用：0x500 - 0x1000 (500ms - 1280ms) 快速发现：0x100 - 0x320 (100ms - 500ms)
`adv_type`	广播类型，决定设备是否可连接、是否可扫描。	`ADV_TYPE_IND`：可连接、可扫描（最常见） `ADV_TYPE_NONCONN_IND`：不可连接，仅广播（如信标）
`adv_filter_policy`	广播过滤策略，控制设备如何响应扫描和连接请求。	`ADV_FILTER_ALLOW_SCAN_ANY_CON_ANY`：允许任何设备扫描和连接（默认） `ADV_FILTER_ALLOW_SCAN_WLST_CON_WLST`：仅允许白名单设备（提升安全性）
`channel_map`	选择在哪些广播信道上发送。三个广播信道是37, 38, 39。	`ADV_CHNL_ALL`：使用全部三个信道（推荐，兼容性最好） `ADV_CHNL_37`/`38`/`39`：仅使用特定信道（特殊测试用）

一个常见的平衡功耗和响应速度的配置如下：

static esp_ble_adv_params_t balanced_adv_params = { .adv_int_min = 0x200, // 320ms .adv_int_max = 0x400, // 640ms .adv_type = ADV_TYPE_IND, .own_addr_type = BLE_ADDR_TYPE_RANDOM, // 使用随机地址增强隐私 .channel_map = ADV_CHNL_ALL, .adv_filter_policy = ADV_FILTER_ALLOW_SCAN_ANY_CON_ANY, };

4.2 常见问题与解决方案

在实际开发中，你可能会遇到以下问题：

手机扫描不到设备
- 检查供电与天线：确保ESP32供电稳定，且天线（如果外接）连接良好。
- 确认广播已启动：查看串口日志，确认ESP_GAP_BLE_ADV_START_COMPLETE_EVT事件返回成功。
- 检查广播类型：如果你设置为ADV_TYPE_NONCONN_IND，一些扫描工具可能不会将其显示为“可连接”设备，但它仍然应该出现在nRF Connect的扫描列表中。
- 距离与干扰：将手机靠近ESP32，并远离Wi-Fi路由器、微波炉等可能产生2.4GHz干扰的设备。
自定义数据在nRF Connect中显示不正确或缺失
- 数据长度溢出：这是最常见的原因。广播包总长度（包括Flags、名称、服务UUID等所有字段）不能超过31字节。计算一下你的数据总长。可以暂时移除设备名称(include_name = false)或服务UUID来测试。
- 字节序问题：ESP32是小端架构。如果你定义的数据包含多字节整数（如16位的公司ID），要确保在数组中以正确的字节序放置。nRF Connect通常按大端显示。
- 制造商数据格式：确保p_manufacturer_data指向的数组第一个字节是公司ID的低字节。
广播功耗过高
- 增大广播间隔：这是降低功耗最直接有效的方法。将adv_int_min和adv_int_max提高到1秒以上（例如0x500）。
- 减少广播数据量：更短的数据包意味着射频模块开启时间更短。
- 使用不可连接广播：如果不需要连接，使用ADV_TYPE_NONCONN_IND，设备不会监听连接请求，进一步省电。
- 考虑使用广播扩展：对于ESP32-C3/C6等支持蓝牙5.0的芯片，可以启用扩展广播，它允许更长的数据包，但需要中心设备也支持蓝牙5.0。
日志中看到ESP_ERR_INVALID_ARG或ESP_FAIL错误
- 仔细检查所有结构体成员的赋值，特别是指针（如p_manufacturer_data）是否指向有效的内存区域，以及长度字段（如manufacturer_len）是否正确。
- 确保在调用esp_ble_gap_config_adv_data之前，蓝牙协议栈已成功初始化和使能。