ESP32蓝牙开发实战：从零搭建GATT服务器（基于ESP-IDF 4.4 + VSCode环境）

ESP32蓝牙GATT服务器深度实战：构建稳定可靠的低功耗物联网数据通道

最近在做一个智能家居中控项目，需要让ESP32作为数据枢纽，通过蓝牙与多个传感器节点通信。翻遍了官方文档和社区案例，发现很多教程要么过于简略只讲个“Hello World”，要么代码堆砌让人摸不着头脑。折腾了两周，踩了无数坑之后，我决定把整个ESP32蓝牙GATT服务器的构建过程重新梳理一遍，特别是那些官方例程没明说、但实际开发中至关重要的细节。

如果你正在开发需要蓝牙通信的物联网设备——无论是环境监测传感器、可穿戴设备，还是智能家居控制器——这篇文章应该能帮你少走不少弯路。我会从最基础的环境搭建讲起，逐步深入到服务架构设计、事件处理优化、功耗控制等实战层面，不仅仅是代码复制粘贴，更重要的是理解每个步骤背后的设计逻辑和最佳实践。

1. 开发环境配置与项目初始化策略

很多开发者第一步就卡在环境配置上。虽然ESP-IDF官方提供了多种安装方式，但根据我的经验，在VSCode中使用ESP-IDF插件是最稳定高效的选择，特别是对于需要频繁调试的蓝牙项目。

首先确保你的系统已经安装了Python 3.8或更高版本。打开VSCode，在扩展商店搜索“ESP-IDF”并安装官方插件。安装过程中，插件会引导你完成ESP-IDF框架的下载和配置。这里有个关键点：一定要选择ESP-IDF 4.4或更高版本，因为早期版本在蓝牙协议栈的稳定性和功能完整性上存在不少问题。

安装完成后，创建一个新的项目：

idf.py create-project bluetooth_gatt_server
cd bluetooth_gatt_server

项目结构初始化后，需要修改CMakeLists.txt文件，添加蓝牙组件依赖：

set(COMPONENTS
main
bt
nvs_flash
esp_bt
)

注意：很多教程会忽略nvs_flash组件，但蓝牙配置信息需要持久化存储，否则每次重启设备都需要重新配对，用户体验会很差。

接下来配置项目参数。运行idf.py menuconfig，进入配置界面后，重点关注以下几个部分：

• Component config → Bluetooth → Bluetooth controller mode：选择BR/EDR/BLE/DUALMODE（根据你的需求，如果只需要BLE，选择BLE only可以节省内存）
• Component config → Bluetooth → Bluetooth Host：确保Bluedroid Enabled被选中
• Component config → Bluetooth → Bluedroid Options：根据设备内存大小调整BT/BLE DU memory size，对于复杂服务建议设置为35000以上

环境配置完成后，先编译一个空项目测试环境是否正常：

idf.py build

如果编译成功，说明基础环境已经就绪。这里我建议在继续之前，先了解一下ESP32蓝牙协议栈的整体架构，这对后续的调试和问题排查会有很大帮助。

ESP32的蓝牙协议栈采用分层设计，从下到上主要包括：

这种分层架构意味着，当出现通信问题时，我们需要先定位问题发生在哪一层。比如，如果设备无法被扫描到，可能是GAP层配置问题；如果能连接但无法读写数据，则可能是GATT服务定义有问题。

2. 蓝牙协议栈初始化与资源管理

蓝牙协议栈的初始化看似简单，但配置不当会导致各种奇怪的问题，比如内存泄漏、连接不稳定、功耗异常等。下面是我在实际项目中总结出的最佳实践。

首先在main.c中包含必要的头文件：

#include "esp_bt.h"
#include "esp_bt_main.h"
#include "esp_gap_ble_api.h"
#include "esp_gatts_api.h"
#include "esp_bt_device.h"
#include "esp_log.h"

定义日志标签，方便调试：

static const char *TAG = "BLE_SERVER";

初始化函数应该按特定顺序调用，这个顺序很重要：

esp_err_t 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. 初始化蓝牙控制器配置
esp_bt_controller_config_t bt_cfg = BT_CONTROLLER_INIT_CONFIG_DEFAULT();

// 调整关键参数（根据实际需求）
bt_cfg.mode = ESP_BT_MODE_BLE; // 仅BLE模式
bt_cfg.ble_max_conn = 3; // 最大连接数
bt_cfg.ble_max_conn_params = 3; // 连接参数更新次数
bt_cfg.bt_max_acl_conn = 3; // ACL连接数
bt_cfg.bt_max_sync_conn = 3; // 同步连接数

// 3. 初始化蓝牙控制器
ret = esp_bt_controller_init(&bt_cfg);
if (ret != ESP_OK) {
ESP_LOGE(TAG, "控制器初始化失败: %s", esp_err_to_name(ret));
return ret;
}

// 4. 使能蓝牙控制器
ret = esp_bt_controller_enable(ESP_BT_MODE_BLE);
if (ret != ESP_OK) {
ESP_LOGE(TAG, "控制器使能失败: %s", esp_err_to_name(ret));
return ret;
}

// 5. 初始化Bluedroid协议栈
ret = esp_bluedroid_init();
if (ret != ESP_OK) {
ESP_LOGE(TAG, "Bluedroid初始化失败: %s", esp_err_to_name(ret));
return ret;
}

// 6. 使能Bluedroid协议栈
ret = esp_bluedroid_enable();
if (ret != ESP_OK) {
ESP_LOGE(TAG, "Bluedroid使能失败: %s", esp_err_to_name(ret));
return ret;
}

ESP_LOGI(TAG, "蓝牙协议栈初始化完成");
return ESP_OK;
}

提示：在生产环境中，建议为每个错误检查添加更详细的日志，并考虑错误恢复机制。比如控制器初始化失败后，可以尝试延迟重试。

内存管理是蓝牙开发中的另一个关键点。ESP32的内存在运行蓝牙协议栈时相对紧张，特别是当同时运行Wi-Fi和其他功能时。以下是一些内存优化技巧：

• 静态分配优先：尽可能使用静态数组而非动态分配
• 合理设置MTU大小：默认MTU为23字节，但可以通过协商增加到247字节，减少分包次数
• 控制连接数：每个连接都会占用内存，根据实际需求设置ble_max_conn

初始化完成后，需要注册GAP和GATT回调函数。这里有个常见误区：很多人把这两个回调注册放在同一个函数里，但实际上它们应该分开管理，因为GAP事件通常与设备发现和连接管理相关，而GATT事件则专注于数据交换。

// 注册GAP事件回调
esp_ble_gap_register_callback(gap_event_handler);

// 注册GATT事件回调
esp_ble_gatts_register_callback(gatts_event_handler);

回调函数的实现我们会在下一节详细讨论。现在，先确保初始化流程能够正确执行。你可以在app_main函数中调用ble_init()，然后添加一个简单的日志输出，验证初始化是否成功。

3. GAP层配置与广播策略优化

GAP（Generic Access Profile）层负责设备发现、连接建立和安全控制。很多开发者只关注GATT服务，却忽略了GAP配置的重要性，结果导致设备难以被发现、连接不稳定或功耗过高。

3.1 广播数据配置

广播数据决定了外围设备如何被中心设备（如手机）发现和识别。ESP-IDF提供了两种配置方式：标准数据结构和原始数据。对于大多数应用，我推荐使用原始数据方式，因为它更灵活。

首先定义广播数据：

// 广播数据（31字节限制）
static uint8_t raw_adv_data[] = {
// 标志位
0x02, 0x01, 0x06,
// 完整设备名
0x0d, 0x09, 'E', 'S', 'P', '3', '2', '_', 'G', 'A', 'T', 'T', '_', 'S', 'V', 'R',
// 128位服务UUID
0x11, 0x07,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00
};

// 扫描响应数据
static uint8_t raw_scan_rsp_data[] = {
// 制造商特定数据
0x05, 0xff, 0x4c, 0x00, 0x02, 0x15,
// 发射功率
0x02, 0x0a, 0xeb
};

广播数据格式解析：

• 第1-3字节：0x02, 0x01, 0x06 表示"标志"数据类型，长度2，内容0x06（LE通用发现模式+不支持传统蓝牙）
• 第4-19字节：设备名称，0x0d表示后面有13个字节数据，0x09表示"完整设备名"类型
• 第20-36字节：服务UUID，0x11表示后面有17个字节，0x07表示"128位服务UUID"类型

注意：广播数据总长度不能超过31字节，这是BLE协议的限制。如果数据过多，需要合理取舍或使用扫描响应数据补充。

配置广播参数时，有几个关键设置会影响设备行为：

static esp_ble_adv_params_t adv_params = {
.adv_int_min = 0x20, // 最小广播间隔：32*0.625ms = 20ms
.adv_int_max = 0x40, // 最大广播间隔：64*0.625ms = 40ms
.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,
};

广播间隔的选择需要在功耗和响应速度之间权衡：

• 快速广播（20-40ms）：设备容易被发现，但功耗较高
• 慢速广播（1-2s）：功耗低，但设备发现延迟大

在实际项目中，我通常采用双阶段广播策略：设备刚启动时使用快速广播（20-40ms），持续30秒；如果没有连接，切换到慢速广播（1-2s）。这样可以兼顾快速连接和低功耗的需求。

3.2 GAP事件处理

GAP事件处理函数需要处理多种事件，以下是一个相对完整的实现：

static void gap_event_handler(esp_gap_ble_cb_event_t event, esp_ble_gap_cb_param_t *param)
{
switch (event) {
case ESP_GAP_BLE_ADV_DATA_RAW_SET_COMPLETE_EVT:
ESP_LOGI(TAG, "广播数据设置完成");
adv_config_done &= ~ADV_CONFIG_FLAG;
if (adv_config_done == 0) {
esp_ble_gap_start_advertising(&adv_params);
}
break;

case ESP_GAP_BLE_SCAN_RSP_DATA_RAW_SET_COMPLETE_EVT:
ESP_LOGI(TAG, "扫描响应数据设置完成");
adv_config_done &= ~SCAN_RSP_CONFIG_FLAG;
if (adv_config_done == 0) {
esp_ble_gap_start_advertising(&adv_params);
}
break;

case ESP_GAP_BLE_ADV_START_COMPLETE_EVT:
if (param->adv_start_cmpl.status != ESP_BT_STATUS_SUCCESS) {
ESP_LOGE(TAG, "广播启动失败");
// 这里可以添加重试逻辑
vTaskDelay(pdMS_TO_TICKS(1000));
esp_ble_gap_start_advertising(&adv_params);
} else {
ESP_LOGI(TAG, "广播已启动");
}
break;

case ESP_GAP_BLE_ADV_STOP_COMPLETE_EVT:
ESP_LOGI(TAG, "广播已停止");
break;

case ESP_GAP_BLE_UPDATE_CONN_PARAMS_EVT:
ESP_LOGI(TAG, "连接参数更新: interval=%d, latency=%d, timeout=%d",
param->update_conn_params.conn_int,
param->update_conn_params.latency,
param->update_conn_params.timeout);
break;

case ESP_GAP_BLE_SEC_REQ_EVT:
// 安全请求处理
esp_ble_gap_security_rsp(param->ble_security.ble_req.bd_addr, true);
break;

default:
ESP_LOGD(TAG, "未处理的GAP事件: %d", event);
break;
}
}

连接参数管理是保证通信稳定性的关键。当设备连接后，应该根据应用需求更新连接参数：

static void update_connection_params(esp_bd_addr_t bd_addr)
{
esp_ble_conn_update_params_t conn_params = {
.bda = bd_addr,
.min_int = 0x10, // 20ms
.max_int = 0x20, // 40ms
.latency = 0,
.timeout = 400, // 4000ms
};

esp_ble_gap_update_conn_params(&conn_params);
}

对于不同的应用场景，连接参数应该有所调整：

• 实时数据传输（如传感器流）：使用较短的连接间隔（20-40ms），低延迟
• 间歇性数据传输（如温度上报）：使用较长的连接间隔（100-200ms），降低功耗
• 电池供电设备：尽可能使用长连接间隔，并允许一定的延迟

4. GATT服务架构设计与实现

GATT（Generic Attribute Profile）是BLE数据交换的核心。设计良好的GATT服务架构不仅能提高开发效率，还能确保系统的可维护性和扩展性。

4.1 服务表定义

GATT服务通过属性表（Attribute Table）定义。每个服务包含多个特征（Characteristic），每个特征又包含值、描述符等属性。以下是一个完整的环境监测服务示例：

#define GATT_DB_NUM 7 // 属性总数

// 自定义UUID（128位）
static const uint8_t SERVICE_UUID_ENV[16] = {
0x00, 0x00, 0x00, 0x00, 0x12, 0x34, 0x56, 0x78,
0x9a, 0xbc, 0xde, 0xf0, 0x00, 0x00, 0x00, 0x01
};

static const uint8_t CHAR_UUID_TEMP[16] = {
0x00, 0x00, 0x00, 0x00, 0x12, 0x34, 0x56, 0x78,
0x9a, 0xbc, 0xde, 0xf0, 0x00, 0x00, 0x00, 0x02
};

static const uint8_t CHAR_UUID_HUMID[16] = {
0x00, 0x00, 0x00, 0x00, 0x12, 0x34, 0x56, 0x78,
0x9a, 0xbc, 0xde, 0xf0, 0x00, 0x00, 0x00, 0x03
};

// 属性表定义
static const esp_gatts_attr_db_t gatt_db[GATT_DB_NUM] = {
// [0] 服务声明
{
{ESP_GATT_AUTO_RSP},
{ESP_UUID_LEN_16, (uint8_t *)&primary_service_uuid,
ESP_GATT_PERM_READ,
sizeof(SERVICE_UUID_ENV), sizeof(SERVICE_UUID_ENV),
(uint8_t *)SERVICE_UUID_ENV}
},

// [1] 温度特征声明
{
{ESP_GATT_AUTO_RSP},
{ESP_UUID_LEN_16, (uint8_t *)&character_declaration_uuid,
ESP_GATT_PERM_READ,
CHAR_PROP_BIT_READ | CHAR_PROP_BIT_NOTIFY,
0, NULL}
},

// [2] 温度特征值
{
{ESP_GATT_AUTO_RSP},
{ESP_UUID_LEN_128, (uint8_t *)CHAR_UUID_TEMP,
ESP_GATT_PERM_READ,
sizeof(float), 0, NULL}
},

// [3] 温度CCCD（客户端特征配置描述符）
{
{ESP_GATT_AUTO_RSP},
{ESP_UUID_LEN_16, (uint8_t *)&character_client_config_uuid,
ESP_GATT_PERM_READ | ESP_GATT_PERM_WRITE,
sizeof(uint16_t), 0, NULL}
},

// [4] 湿度特征声明
{
{ESP_GATT_AUTO_RSP},
{ESP_UUID_LEN_16, (uint8_t *)&character_declaration_uuid,
ESP_GATT_PERM_READ,
CHAR_PROP_BIT_READ | CHAR_PROP_BIT_WRITE,
0, NULL}
},

// [5] 湿度特征值
{
{ESP_GATT_AUTO_RSP},
{ESP_UUID_LEN_128, (uint8_t *)CHAR_UUID_HUMID,
ESP_GATT_PERM_READ | ESP_GATT_PERM_WRITE,
sizeof(float), 0, NULL}
},

// [6] 湿度CCCD
{
{ESP_GATT_AUTO_RSP},
{ESP_UUID_LEN_16, (uint8_t *)&character_client_config_uuid,
ESP_GATT_PERM_READ | ESP_GATT_PERM_WRITE,
sizeof(uint16_t), 0, NULL}
}
};

属性表的关键字段说明：

• UUID长度和值：16位标准UUID或128位自定义UUID
• 权限：ESP_GATT_PERM_READ、ESP_GATT_PERM_WRITE等
• 最大长度：特征值允许的最大字节数
• 初始值：特征的初始数据，如果为0或NULL，则需要在创建时动态设置

4.2 GATT事件处理

GATT事件处理函数是服务逻辑的核心。以下是一个支持多服务、多连接的处理框架：

// 连接信息结构
typedef struct {
uint16_t conn_id;
esp_gatt_if_t gatts_if;
uint16_t temp_ccc_value;
uint16_t humid_ccc_value;
bool connected;
} conn_info_t;

static conn_info_t connections[MAX_CONNECTIONS];

static void gatts_event_handler(esp_gatts_cb_event_t event,
esp_gatt_if_t gatts_if,
esp_ble_gatts_cb_param_t *param)
{
// 查找或创建连接信息
conn_info_t *conn = find_connection(gatts_if, param->connect.conn_id);

switch (event) {
case ESP_GATTS_REG_EVT:
ESP_LOGI(TAG, "GATT应用注册成功，接口ID: %d", gatts_if);

// 设置设备名称
esp_ble_gap_set_device_name("ESP32_ENV_SENSOR");

// 配置广播数据
esp_ble_gap_config_adv_data_raw(raw_adv_data,
sizeof(raw_adv_data));

// 创建属性表
esp_ble_gatts_create_attr_tab(gatt_db, gatts_if,
GATT_DB_NUM, 0);
break;

case ESP_GATTS_CONNECT_EVT: {
ESP_LOGI(TAG, "设备连接，连接ID: %d", param->connect.conn_id);

if (conn == NULL) {
conn = add_connection(gatts_if, param->connect.conn_id);
}

conn->connected = true;
conn->conn_id = param->connect.conn_id;
conn->gatts_if = gatts_if;

// 更新连接参数
update_connection_params(param->connect.remote_bda);

// 停止广播以节省功耗
esp_ble_gap_stop_advertising();
break;
}

case ESP_GATTS_DISCONNECT_EVT:
ESP_LOGI(TAG, "设备断开连接，原因: 0x%x",
param->disconnect.reason);

if (conn != NULL) {
conn->connected = false;
remove_connection(conn);
}

// 重新开始广播
esp_ble_gap_start_advertising(&adv_params);
break;

case ESP_GATTS_CREAT_ATTR_TAB_EVT:
if (param->add_attr_tab.status == ESP_GATT_OK) {
ESP_LOGI(TAG, "属性表创建成功，句柄数: %d",
param->add_attr_tab.num_handle);

// 保存句柄
save_attribute_handles(param->add_attr_tab.handles,
param->add_attr_tab.num_handle);

// 启动服务
esp_ble_gatts_start_service(
param->add_attr_tab.handles[0]);
}
break;

case ESP_GATTS_READ_EVT:
handle_read_event(gatts_if, conn, param);
break;

case ESP_GATTS_WRITE_EVT:
handle_write_event(gatts_if, conn, param);
break;

case ESP_GATTS_MTU_EVT:
ESP_LOGI(TAG, "MTU更新: %d", param->mtu.mtu);
break;

default:
ESP_LOGD(TAG, "未处理的GATT事件: %d", event);
break;
}
}

读写事件的具体处理需要根据业务逻辑实现。以下是一个温度读取的示例：

static void handle_read_event(esp_gatt_if_t gatts_if,
conn_info_t *conn,
esp_ble_gatts_cb_param_t *param)
{
uint16_t handle = param->read.handle;
esp_gatt_rsp_t rsp;

memset(&rsp, 0, sizeof(esp_gatt_rsp_t));

// 根据句柄判断读取哪个特征
if (handle == temp_value_handle) {
// 读取温度值
float current_temp = read_temperature_sensor();
memcpy(rsp.attr_value.value, &current_temp, sizeof(float));
rsp.attr_value.len = sizeof(float);

ESP_LOGI(TAG, "温度读取: %.2f°C", current_temp);
}
else if (handle == humid_value_handle) {
// 读取湿度值
float current_humid = read_humidity_sensor();
memcpy(rsp.attr_value.value, &current_humid, sizeof(float));
rsp.attr_value.len = sizeof(float);

ESP_LOGI(TAG, "湿度读取: %.2f%%", current_humid);
}
else {
// 其他特征或描述符
rsp.attr_value.len = 0;
}

// 发送响应
esp_ble_gatts_send_response(gatts_if,
param->read.conn_id,
param->read.trans_id,
ESP_GATT_OK, &rsp);
}

写事件处理，特别是CCCD的写入，需要特别注意：

static void handle_write_event(esp_gatt_if_t gatts_if,
conn_info_t *conn,
esp_ble_gatts_cb_param_t *param)
{
uint16_t handle = param->write.handle;

if (handle == temp_cccd_handle) {
// 温度通知配置更新
uint16_t cccd_value =
*(uint16_t *)param->write.value;

conn->temp_ccc_value = cccd_value;

if (cccd_value == 0x0001) {
ESP_LOGI(TAG, "温度通知已启用");
// 启动温度定时通知任务
start_temperature_notification(conn);
} else {
ESP_LOGI(TAG, "温度通知已禁用");
// 停止温度定时通知任务
stop_temperature_notification(conn);
}
}
else if (handle == humid_value_handle) {
// 湿度值写入（配置阈值等）
float threshold = *(float *)param->write.value;
set_humidity_threshold(threshold);

ESP_LOGI(TAG, "湿度阈值更新: %.2f%%", threshold);
}

// 如果需要响应（非自动响应）
if (!param->write.need_rsp) {
esp_ble_gatts_send_response(gatts_if,
param->write.conn_id,
param->write.trans_id,
ESP_GATT_OK, NULL);
}
}

5. 数据通信优化与功耗管理

在实际部署中，通信效率和功耗往往是决定项目成败的关键因素。经过多个项目的实践，我总结了一些有效的优化策略。

5.1 数据分包与重组

BLE协议每个数据包的有效载荷有限（默认23字节，协商后最多247字节）。传输较大数据时需要分包发送。以下是一个可靠的分包传输实现：

#define MAX_PACKET_SIZE 20 // 预留3字节给ATT头

typedef struct {
uint8_t data[256];
uint16_t total_len;
uint16_t sent_len;
uint16_t handle;
uint8_t packet_seq;
} large_data_t;

static void send_large_data(esp_gatt_if_t gatts_if,
uint16_t conn_id,
uint16_t handle,
uint8_t *data,
uint16_t len)
{
large_data_t *ld = malloc(sizeof(large_data_t));

memcpy(ld->data, data, len);
ld->total_len = len;
ld->sent_len = 0;
ld->handle = handle;
ld->packet_seq = 0;

// 启动分段发送任务
xTaskCreate(send_segmented_task,
"send_seg",
4096,
(void *)ld,
5,
NULL);
}

static void send_segmented_task(void *arg)
{
large_data_t *ld = (large_data_t *)arg;

while (ld->sent_len < ld->total_len) {
uint16_t remaining = ld->total_len – ld->sent_len;
uint16_t chunk_size = (remaining > MAX_PACKET_SIZE) ?
MAX_PACKET_SIZE : remaining;

// 添加序列号（可选）
uint8_t packet[MAX_PACKET_SIZE + 2];
packet[0] = ld->packet_seq++;
packet[1] = (remaining > MAX_PACKET_SIZE) ? 0 : 1; // 最后包标志

memcpy(&packet[2],
&ld->data[ld->sent_len],
chunk_size);

// 发送数据包
esp_ble_gatts_send_indicate(ld->gatts_if,
ld->conn_id,
ld->handle,
chunk_size + 2,
packet,
false); // 不需要确认

ld->sent_len += chunk_size;

// 等待ACK或延迟（避免拥塞）
vTaskDelay(pdMS_TO_TICKS(10));
}

free(ld);
vTaskDelete(NULL);
}

5.2 功耗优化策略

对于电池供电的设备，功耗优化至关重要。以下是一些经过验证的有效方法：

连接参数优化表：

动态功耗管理代码示例：

typedef enum {
POWER_MODE_HIGH = 0, // 高性能模式
POWER_MODE_BALANCED, // 平衡模式
POWER_MODE_LOW, // 低功耗模式
} power_mode_t;

static power_mode_t current_power_mode = POWER_MODE_BALANCED;

static void adjust_power_mode(power_mode_t new_mode)
{
if (new_mode == current_power_mode) {
return;
}

switch (new_mode) {
case POWER_MODE_HIGH:
// 快速广播，短连接间隔
adv_params.adv_int_min = 0x20; // 20ms
adv_params.adv_int_max = 0x30; // 30ms
set_connection_interval(0x10, 0x20); // 20-40ms
esp_bt_controller_disable();
esp_bt_controller_enable(ESP_BT_MODE_BLE);
break;

case POWER_MODE_BALANCED:
adv_params.adv_int_min = 0x80; // 80ms
adv_params.adv_int_max = 0x100; // 160ms
set_connection_interval(0x40, 0x80); // 64-128ms
break;

case POWER_MODE_LOW:
// 慢速广播，长连接间隔
adv_params.adv_int_min = 0x200; // 320ms
adv_params.adv_int_max = 0x400; // 640ms
set_connection_interval(0x200, 0x400); // 512-1024ms

// 降低发射功率
esp_ble_tx_power_set(ESP_BLE_PWR_TYPE_DEFAULT,
ESP_PWR_LVL_N12);
break;
}

current_power_mode = new_mode;
ESP_LOGI(TAG, "功耗模式切换至: %d", new_mode);

// 重新配置广播
if (is_advertising) {
esp_ble_gap_stop_advertising();
esp_ble_gap_start_advertising(&adv_params);
}
}

// 根据电池电量和连接状态自动调整
static void auto_adjust_power_mode(void)
{
float battery_level = read_battery_level();
uint8_t connected_devices = count_connected_devices();

if (battery_level < 20.0) {
// 低电量，强制低功耗模式
adjust_power_mode(POWER_MODE_LOW);
}
else if (connected_devices == 0) {
// 无连接，使用平衡或低功耗模式
adjust_power_mode(battery_level < 50.0 ?
POWER_MODE_LOW : POWER_MODE_BALANCED);
}
else {
// 有连接，根据数据频率调整
if (data_update_freq > 10) { // 高频更新
adjust_power_mode(POWER_MODE_HIGH);
} else {
adjust_power_mode(POWER_MODE_BALANCED);
}
}
}

5.3 连接管理与状态同步

在多设备连接场景中，连接管理和状态同步是难点。以下是一个简单的连接管理实现：

#define MAX_DEVICES 3

typedef struct {
esp_bd_addr_t addr;
uint16_t conn_id;
esp_gatt_if_t gatts_if;
uint32_t last_activity;
device_state_t state;
} connected_device_t;

static connected_device_t connected_devices[MAX_DEVICES];
static uint8_t device_count = 0;

static connected_device_t *find_device_by_addr(esp_bd_addr_t addr)
{
for (int i = 0; i < device_count; i++) {
if (memcmp(connected_devices[i].addr, addr, 6) == 0) {
return &connected_devices[i];
}
}
return NULL;
}

static connected_device_t *add_device(esp_bd_addr_t addr,
uint16_t conn_id,
esp_gatt_if_t gatts_if)
{
if (device_count >= MAX_DEVICES) {
ESP_LOGW(TAG, "连接数已达上限");
return NULL;
}

connected_device_t *dev = &connected_devices[device_count++];
memcpy(dev->addr, addr, 6);
dev->conn_id = conn_id;
dev->gatts_if = gatts_if;
dev->last_activity = xTaskGetTickCount();
dev->state = DEVICE_CONNECTED;

ESP_LOGI(TAG, "设备已添加: %02X:%02X:%02X:%02X:%02X:%02X",
addr[0], addr[1], addr[2], addr[3], addr[4], addr[5]);

return dev;
}

static void remove_device(esp_bd_addr_t addr)
{
for (int i = 0; i < device_count; i++) {
if (memcmp(connected_devices[i].addr, addr, 6) == 0) {
// 将最后一个设备移到当前位置
if (i < device_count – 1) {
memcpy(&connected_devices[i],
&connected_devices[device_count – 1],
sizeof(connected_device_t));
}
device_count–;
break;
}
}
}

// 定期检查不活跃连接
static void check_inactive_connections(void)
{
uint32_t current_time = xTaskGetTickCount();

for (int i = 0; i < device_count; i++) {
uint32_t inactive_time = current_time –
connected_devices[i].last_activity;

if (inactive_time > pdMS_TO_TICKS(30000)) { // 30秒无活动
ESP_LOGW(TAG, "设备不活跃，准备断开: %02X:%02X:%02X:%02X:%02X:%02X",
connected_devices[i].addr[0],
connected_devices[i].addr[1],
connected_devices[i].addr[2],
connected_devices[i].addr[3],
connected_devices[i].addr[4],
connected_devices[i].addr[5]);

// 发送断开请求
esp_ble_gap_disconnect(connected_devices[i].addr);
}
}
}

6. 调试技巧与常见问题解决

即使按照最佳实践开发，在实际部署中仍然会遇到各种问题。以下是我在多个项目中积累的调试经验和常见问题解决方案。

6.1 系统日志配置优化

合理的日志配置可以帮助快速定位问题，同时避免日志输出影响系统性能：

// 在app_main中配置日志级别
void app_main(void)
{
// 设置不同模块的日志级别
esp_log_level_set("*", ESP_LOG_WARN); // 默认警告级别
esp_log_level_set("BLE_SERVER", ESP_LOG_INFO); // 主模块信息级别
esp_log_level_set("GATT", ESP_LOG_DEBUG); // GATT模块调试级别
esp_log_level_set("GAP", ESP_LOG_DEBUG); // GAP模块调试级别

// 启用核心转储（用于分析崩溃）
esp_core_dump_init();

// 初始化蓝牙
ble_init();

// … 其他初始化代码
}

6.2 常见问题排查表

6.3 性能监控与优化

在生产环境中部署前，建议进行全面的性能测试：

// 性能监控结构
typedef struct {
uint32_t connect_count;
uint32_t disconnect_count;
uint32_t read_ops;
uint32_t write_ops;
uint32_t notify_ops;
uint32_t error_count;
uint32_t total_memory;
uint32_t free_memory;
uint32_t min_free_memory;
} performance_stats_t;

static performance_stats_t stats;

// 定期输出性能报告
static void print_performance_report(void)
{
ESP_LOGI("PERF", "=== 性能报告 ===");
ESP_LOGI("PERF", "连接统计: 成功=%d, 断开=%d",
stats.connect_count, stats.disconnect_count);
ESP_LOGI("PERF", "操作统计: 读=%d, 写=%d, 通知=%d",
stats.read_ops, stats.write_ops, stats.notify_ops);
ESP_LOGI("PERF", "错误统计: 总数=%d", stats.error_count);
ESP_LOGI("PERF", "内存使用: 总量=%d, 剩余=%d, 最低剩余=%d",
stats.total_memory, stats.free_memory, stats.min_free_memory);

// 计算连接稳定性
if (stats.connect_count > 0) {
float stability = 100.0 * (1.0 – (float)stats.disconnect_count /
(float)stats.connect_count);
ESP_LOGI("PERF", "连接稳定性: %.1f%%", stability);
}

// 更新最小空闲内存
if (stats.free_memory < stats.min_free_memory) {
stats.min_free_memory = stats.free_memory;
}
}

// 内存监控任务
static void memory_monitor_task(void *arg)
{
while (1) {
multi_heap_info_t info;
heap_caps_get_info(&info, MALLOC_CAP_DEFAULT);

stats.total_memory = info.total_free_bytes + info.total_allocated_bytes;
stats.free_memory = info.total_free_bytes;

vTaskDelay(pdMS_TO_TICKS(5000)); // 每5秒检查一次
}
}

6.4 实际部署注意事项

在将设备部署到实际环境前，有几个关键点需要验证：

我在一个工业环境监测项目中遇到过这样的情况：设备在实验室测试一切正常，但部署到现场后频繁断开连接。后来发现是现场有大量的2.4GHz干扰源（Wi-Fi路由器、微波炉等）。通过调整广播信道和连接参数，并添加重试机制，最终解决了问题。

另一个常见问题是内存碎片化导致的系统不稳定。对于需要长期运行（数月甚至数年）的设备，建议：

• 尽量避免频繁的动态内存分配
• 定期重启服务以清理内存碎片
• 监控内存使用趋势，设置预警阈值

蓝牙开发最麻烦的往往不是代码本身，而是各种边界情况和异常处理。比如设备突然断电后恢复、手机端应用异常退出、多个设备同时连接竞争资源等。好的错误处理和恢复机制能让产品更加可靠。