1. 从零开始：搭建你的第一个ESP32 BLE项目

如果你手头有一块ESP32开发板，想用它做点蓝牙相关的智能硬件，比如做个无线传感器、遥控个小车，或者做个自定义的键盘鼠标，那么BLE（蓝牙低功耗）绝对是你的首选。它功耗低、连接快，非常适合物联网设备。但说实话，我刚接触ESP32 BLE开发时，看着官方例程里一堆结构体和事件回调，头都大了。网上的资料要么太零碎，要么直接甩一堆API文档，对新手实在不友好。今天，我就把自己踩过的坑和总结出来的实战经验，用最直白的方式分享给你。咱们不扯那些复杂的协议栈原理，就手把手，从给设备改个名字开始，一步步实现数据的收发，让你能快速做出一个能用的东西，建立信心。

首先，你得把开发环境搭起来。这里我强烈推荐使用乐鑫官方的ESP-IDF开发框架。虽然Arduino核心库用起来更简单，但真要深入搞BLE，尤其是想灵活配置GATT服务，ESP-IDF提供的控制力和完整性是无可替代的。你去乐鑫的官网下载ESP-IDF的离线安装包或者用Git克隆，按照指南安装好就行。这个过程可能会遇到一些环境变量的问题，特别是Windows用户，耐心跟着官方文档一步步走，肯定能搞定。安装完成后，我建议你先别急着动自己的代码，而是找到那个宝藏般的官方例程。它通常就在你的ESP-IDF安装目录下，路径类似 esp-idf-v5.x/examples/bluetooth/bluedroid/ble/gatt_server_service_table。这个例程就是一个已经能工作的BLE服务器，我们所有的修改都将基于它，这是最稳妥的起点。

把你的工程目录建好，然后把这个例程里的 gatt_server_service_table.c 和 gatt_server_service_table.h 文件复制过去。接着，用VS Code打开工程（记得先运行 export.bat 或 export.sh 来激活IDF环境），尝试编译一下。这时候，新手常遇到的第一个坑可能就来了：编译报错，提示找不到 esp_bt.h 之类的头文件。别慌，这十有八九是因为蓝牙组件没被激活。你需要打开终端，输入 idf.py menuconfig，这会弹出一个图形化的配置菜单。在这个菜单里，你需要依次进入 Component config -> Bluetooth，确保 Bluetooth 选项是开启的（被选中）。然后，在 Bluetooth 的子菜单里，选择 Bluedroid Options，再确保 BLE 是开启状态。保存配置，退出，再重新编译，这个问题基本就解决了。这一步虽然简单，但却是后面所有工作的基础，确保你的工具链是畅通的。

2. 给你的BLE设备起个响亮的名字

设备名字就像是你的硬件产品的“脸面”，当你在手机蓝牙搜索列表里看到它时，一个清晰、独特的名字能让你快速识别。在BLE开发里，修改设备名称有两种方式，一种是“表面”修改，简单快捷；另一种是“实质”修改，更底层、更灵活。我们先从最简单的开始。

在官方例程的 gatt_server_service_table.c 文件里，大概第39行左右，你会看到一行宏定义：#define SAMPLE_DEVICE_NAME "ESP_GATTS_DEMO"。没错，直接把双引号里的内容改成你想要的名字，比如 "My_Awesome_ESP32"。这就是表面修改，改完编译烧录，你的设备在广播时就会使用这个名字。这种方法适用于绝大多数情况，非常直观。但是，如果你好奇这个名字到底是怎么被广播出去的，或者你想更精细地控制广播数据包，那就需要了解第二种方法。

BLE设备通过广播数据包来宣告自己的存在。这个数据包是一串字节数组，里面按照特定格式包含了各种信息，比如“我是一个低功耗蓝牙设备”、“我的发射功率是多少”、“我提供什么服务”以及“我的设备名”。在例程里，查找一个名为 raw_adv_data 的静态数组。这个数组就是广播数据的原始字节。我们聚焦在设置设备名的部分。它通常长这样：

static uint8_t raw_adv_data[] = {
    /* Flags */
    0x02, 0x01, 0x06,
    /* Tx Power */
    0x02, 0x0a, 0xeb,
    /* Service UUID */
    0x03, 0x03, 0xFF, 0x00,
    /* Device name */
    0x07, 0x09, 'E', 'S', 'P', '_', 'G', 'A', 'T', 'T', 'S', '_', 'D', 'E', 'M', 'O'
};

我们来拆解“Device name”这一行。第一个字节 0x07 表示接下来这个“设备名”字段的总长度是7个字节。第二个字节 0x09 是AD Type，固定值，表示“完整的设备名称”。从第三个字节开始，就是设备名字符的ASCII码。注意，这里数组里显示的长度是包括了 0x07 和 0x09 这两个字节的。所以，如果你想把名字改成 "LALALA"（6个字符），那么字段总长度就应该是 2（类型和长度字节）+ 6（名字字符）= 8，也就是 0x08。修改后的数组应该是：

/* Device name */
0x08, 0x09, 'L', 'A', 'L', 'A', 'L', 'A'

一定要算对长度，否则广播包格式错误，手机可能就解析不出名字，或者直接搜不到设备。我当初就在这里栽过跟头，名字死活显示不对，最后才发现是长度字节算错了。这种实质修改给了你更大的控制权，你可以决定是否包含设备名，或者把设备名放在广播包的什么位置。对于新手，我建议先用第一种宏定义的方式，快速验证；等熟悉了整个流程后，再来研究这个原始广播数据，你会对BLE有更深的理解。

3. 深入GATT核心：创建自定义Characteristic

设备能找到了，接下来就要考虑它能提供什么数据或服务。这就是GATT（通用属性协议）干的事。你可以把GATT服务理解为一个“服务菜单”，而Characteristic（特征值）就是菜单里的“一道道菜”，每一道菜都是一种具体的数据或功能。比如，一个“心率服务”里可能包含“心率测量值”、“身体传感器位置”等Characteristic。官方例程已经预置了一个服务和几个Characteristic，我们现在要学着自己加一道“新菜”。

首先，你得给你这道“菜”一个独一无二的“编号”，也就是UUID。UUID有16位、32位、128位之分。为了简单，我们通常使用16位UUID在开发测试阶段。在例程文件开头，找定义服务UUID和特征UUID的地方，照猫画虎地加上我们自己的。比如：

/* Service UUID */
static const uint16_t GATTS_SERVICE_UUID_TEST = 0x00FF;
/* Existing Characteristic UUIDs */
static const uint16_t GATTS_CHAR_UUID_TEST_A = 0xFF01;
static const uint16_t GATTS_CHAR_UUID_TEST_B = 0xFF02;
/* Our New Characteristic UUID */
static const uint16_t GATTS_CHAR_UUID_TEST_D = 0xFF04;

这里我们打算在现有的服务（UUID为0x00FF）下，添加一个UUID为0xFF04的新Characteristic。接下来，我们需要在属性表中为这个新Characteristic“占个座”。在 gatt_server_service_table.h 文件中，找到一个枚举类型，比如叫 heart_rate_svc_db。这个枚举定义了所有属性在数据库中的索引顺序，非常重要。我们需要在末尾添加我们新Characteristic的索引：

enum {
    IDX_SVC,                    // 服务声明，句柄值起点
    IDX_CHAR_A,                 // 特征A声明
    IDX_CHAR_VAL_A,             // 特征A的值
    IDX_CHAR_CFG_A,             // 特征A的配置描述符（用于Notify/Indicate）
    // ... 其他已有特征
    IDX_CHAR_D,                 // 【新增】特征D声明
    IDX_CHAR_VAL_D,             // 【新增】特征D的值
    HRS_IDX_NB                  // 总属性数量
};

注意 HRS_IDX_NB 必须是最后一个，它代表了属性的总数。然后，回到 .c 文件，我们需要定义这个新Characteristic的属性。在定义特征属性（Property）的地方，添加一个属性变量。比如我们要创建一个可读（READ）可写（WRITE）的特征：

static const uint8_t char_prop_read_write = ESP_GATT_CHAR_PROP_BIT_READ | ESP_GATT_CHAR_PROP_BIT_WRITE;

这里用按位或操作符组合了读和写两种权限。最后，也是最关键的一步，修改GATT属性数据库 gatt_db。这是一个 esp_gatts_attr_db_t 类型的数组，它按照前面枚举定义的顺序，详细描述了每一个属性的具体信息。我们需要在数组的对应位置（也就是 IDX_CHAR_D 和 IDX_CHAR_VAL_D 的位置）插入两个新的属性描述。

static const esp_gatts_attr_db_t gatt_db[HRS_IDX_NB] = {
    // 服务声明 (IDX_SVC)
    [IDX_SVC] = {...},
    // 特征A声明 (IDX_CHAR_A) 和 值 (IDX_CHAR_VAL_A)
    [IDX_CHAR_A] = {...},
    [IDX_CHAR_VAL_A] = {...},
    // ... 其他已有属性
    // 【新增】特征D声明
    [IDX_CHAR_D] = {
        .attr_control = ESP_GATT_AUTO_RSP,
        .att_desc = {
            .uuid_length = ESP_UUID_LEN_16,
            .uuid_p = (uint8_t *)&primary_service_uuid,
            .perm = ESP_GATT_PERM_READ,
            .max_length = sizeof(uint16_t),
            .length = sizeof(uint16_t),
            .value = (uint8_t *)&char_prop_read_write, // 这里指向我们定义的读写属性
        }
    },
    // 【新增】特征D的值
    [IDX_CHAR_VAL_D] = {
        .attr_control = ESP_GATT_AUTO_RSP,
        .att_desc = {
            .uuid_length = ESP_UUID_LEN_16,
            .uuid_p = (uint8_t *)&GATTS_CHAR_UUID_TEST_D, // 指向我们定义的UUID
            .perm = ESP_GATT_PERM_READ | ESP_GATT_PERM_WRITE, // 权限：可读可写
            .max_length = 100, // 这个值允许的最大长度，根据你的数据定
            .length = 0, // 初始长度，可以为0
            .value = NULL, // 初始值，可以为NULL
        }
    },
};

这个过程就像是在一个固定的表格里新增两行，每一行都要填好UUID、权限、长度等所有信息。尤其是权限（perm）一定要和前面定义的属性（char_prop_read_write）匹配，否则客户端操作时会返回权限错误。做完这些，编译并烧录程序，用手机上的BLE调试工具（比如nRF Connect）连接你的ESP32，你应该就能在GATT服务列表里看到你新添加的那个Characteristic了，并且可以尝试对它进行读和写操作。虽然现在读写还不会有实际反应，但架子已经搭好了。

4. 让数据流动起来：发送与接收实战

Characteristic建好了，它就像一个信箱。现在我们要学会往信箱里放数据（发送），以及从信箱里取数据（接收）。这是实现具体功能的关键。

4.1 主动发送数据：Notify与Write Response

发送数据分两种情况。第一种是服务器主动“推送”数据给客户端，这对应着Characteristic的Notify或Indicate属性。你需要先为你之前创建的特征添加一个CCCD（客户端特征配置描述符），也就是前面枚举里的 IDX_CHAR_CFG_D，并在属性表中配置好它。当客户端通过写入这个描述符来启用通知后，服务器就可以在数据更新时，调用 esp_ble_gatts_send_indicate 或 esp_ble_gatts_send_response 函数来主动发送数据。这种方式非常适合传感器周期性上报数据。

第二种更直接的方式，是响应客户端的“读”请求。当客户端读取Characteristic的值时，服务器需要返回当前值。但有时我们想主动更新这个值，让下次客户端读取时拿到新数据。这时可以用 esp_ble_gatts_set_attr_value 函数。这个函数直接设置底层属性值。你需要知道要设置哪个特征的“值句柄”。句柄是GATT服务器为每个属性分配的唯一数字标识。通常，特征值的句柄就是其索引值加一个基础偏移。根据之前的枚举，IDX_CHAR_VAL_D 的索引是49（假设），那么这个特征值的句柄很可能就是49。发送数据的代码通常这样写：

uint8_t send_data[] = "Hello from ESP32!";
esp_err_t ret = esp_ble_gatts_set_attr_value(49, sizeof(send_data) - 1, send_data);
if (ret != ESP_OK) {
    ESP_LOGE(GATTS_TAG, "Set attribute value failed, error code = %x", ret);
}

这里要注意，sizeof(send_data) 会包含字符串结尾的 \0，而BLE传输纯数据时通常不需要这个结束符，所以用 sizeof(send_data) - 1 只发送有效字符。调用这个函数后，特征值就被更新了。之后当客户端发起读操作时，读到的就是 "Hello from ESP32!"。你也可以在需要的时候主动调用它来更新数据，模拟一种“服务器可更新、客户端可读取”的模型。

4.2 接收并处理客户端数据

接收数据主要处理客户端的“写”请求。当客户端向我们具有写权限的Characteristic写入数据时，ESP32的BLE协议栈会触发一个 ESP_GATTS_WRITE_EVT 事件。我们的事件处理回调函数 gatts_event_handler 会捕获到这个事件。在这个事件的 case 分支里，我们能拿到客户端发来的所有信息。

找到 gatts_event_handler 函数中 case ESP_GATTS_WRITE_EVT: 的部分。关键信息都在 param->write 这个结构体里：

• param->write.handle：客户端写入的属性句柄。通过对比这个句柄，我们可以知道是哪个Characteristic被写了。通常我们会用之前枚举的索引值（如 IDX_CHAR_VAL_D）来比较，但要注意，实际句柄可能是一个更大的数字，我们需要用 param->write.handle 与我们存储的 gl_profile_tab[PROFILE_APP_ID].char_handle 数组中的对应值进行比较。
• param->write.value：指向写入数据缓冲区的指针。
• param->write.len：写入数据的长度。

一个典型的处理代码如下：

case ESP_GATTS_WRITE_EVT: {
    ESP_LOGI(GATTS_TAG, "GATT_WRITE_EVT, handle = %d, value len = %d", param->write.handle, param->write.len);
    // 判断是否是写入我们自定义的特征D的值句柄
    if (param->write.handle == gl_profile_tab[PROFILE_APP_ID].char_handle[IDX_CHAR_VAL_D]) {
        // 打印接收到的数据
        ESP_LOGI(GATTS_TAG, "Received data for CHAR_D:");
        esp_log_buffer_hex(GATTS_TAG, param->write.value, param->write.len);
        // 你可以在这里处理数据，比如：
        // 1. 控制一个GPIO引脚
        // 2. 解析指令，改变系统状态
        // 3. 将数据存储起来
        // 例如，如果收到"ON"，点亮LED
        if (param->write.len == 2 && memcmp(param->write.value, "ON", 2) == 0) {
            gpio_set_level(LED_GPIO, 1);
            ESP_LOGI(GATTS_TAG, "LED turned ON");
        }
        // 如果需要，可以在这里更新特征值，作为对客户端的回应
        // esp_ble_gatts_set_attr_value(param->write.handle, response_len, response_data);
    }
    // 处理CCCD写入（启用/禁用通知）
    else if (param->write.handle == gl_profile_tab[PROFILE_APP_ID].char_handle[IDX_CHAR_CFG_D]) {
        // 解析客户端是否启用了通知/指示
        uint16_t desc_value = param->write.value[1] << 8 | param->write.value[0];
        if (desc_value == 0x0001) {
            ESP_LOGI(GATTS_TAG, "Notify enable");
            // 可以在这里启动一个定时器，周期性发送通知
        } else if (desc_value == 0x0002) {
            ESP_LOGI(GATTS_TAG, "Indicate enable");
        } else {
            ESP_LOGI(GATTS_TAG, "Notify/Indicate disable");
        }
    }
    // 发送写响应（如果属性配置为ESP_GATT_RSP_BY_APP，则需要手动发送响应）
    // esp_ble_gatts_send_response(gatts_if, param->write.conn_id, param->write.trans_id, ESP_GATT_OK, NULL);
    break;
}

这段代码做了几件事：首先，它通过句柄判断数据写到了哪里。如果是我们关心的特征值，就把收到的数据打印出来（方便调试），并可以根据数据内容执行具体的动作，比如控制LED。其次，它还检查了是否是CCCD描述符被写入，从而知道客户端是否开启了通知功能。在实际项目中，这里就是你业务逻辑的入口，你可以把接收到的数据转换成命令、配置或者任何你需要的信息。

5. 调试技巧与常见问题排查

理论走通了，但实际做的时候总会遇到各种稀奇古怪的问题。这里分享几个我常用的调试方法和踩过的坑，希望能帮你节省时间。

必备调试工具：手机端，我强烈推荐 nRF Connect 这款App。它免费、功能强大，能扫描、连接BLE设备，直观地展示完整的GATT服务树，并且能对任意Characteristic进行读、写、订阅通知等操作。电脑端，你可以使用 Wireshark 配合专门的蓝牙嗅探器，或者使用 Ellisys 等专业工具来抓取空中包，但这通常需要硬件支持且门槛较高。对于初学者，nRF Connect完全够用。

连接不上怎么办？ 这是最常见的问题。首先，检查手机蓝牙是否开启，是否在扫描。其次，确认你的ESP32程序确实在广播。你可以在代码里增加日志，在广播开始的回调 ESP_GATTS_REG_EVT 或 ESP_GAP_BLE_ADV_DATA_SET_COMPLETE_EVT 事件中打印日志。如果手机根本扫不到设备，问题可能出在广播数据包上。回顾一下修改设备名那一步，检查 raw_adv_data 数组的长度字段是否计算正确。一个快速验证的方法是，先注释掉所有自定义的广播数据，使用 esp_ble_gap_config_adv_data 函数并传入一个简单的标准广播数据结构，看是否能被扫描到。

能连接，但看不到服务/特征：如果手机能连接上ESP32，但在nRF Connect里看不到服务，或者服务是空的。这通常意味着GATT数据库注册或启动失败了。检查 esp_ble_gatts_app_register 的返回值，以及后续 ESP_GATTS_CREATE_EVT 事件是否成功触发。另外，确保你的属性表 gatt_db 数组的大小 HRS_IDX_NB 与实际元素数量严格一致，多一个少一个都会导致数据库注册异常。

读写操作失败，返回错误码：在nRF Connect里进行读写操作时，如果弹出“权限错误”、“不支持该操作”等提示。请仔细核对两点：第一，Characteristic的属性（Property）是否包含了相应的读写位（ESP_GATT_CHAR_PROP_BIT_READ/WRITE）。第二，Characteristic值的权限（perm）是否也设置了相应的 ESP_GATT_PERM_READ/WRITE。属性和权限必须同时匹配，操作才能成功。例如，属性有写，但权限没开写，客户端写操作也会被拒绝。

数据收发异常：发送数据时，如果客户端收不到或收到乱码，检查数据长度。确保你调用 esp_ble_gatts_set_attr_value 或发送通知时指定的长度与实际数据缓冲区的有效长度一致。对于字符串，注意是否误将结束符 \0 也发送了出去。接收数据时，在 ESP_GATTS_WRITE_EVT 事件中，一定要先检查 param->write.len，再访问 param->write.value，避免内存越界。同时，使用 esp_log_buffer_hex 打印原始字节是排查数据问题最有效的手段。

资源与内存：ESP32的BLE协议栈会消耗一部分内存。如果你的工程比较复杂，添加了Wi-Fi等其他功能，可能会遇到内存不足的问题。留意编译时的内存分配警告，可以适当调整 menuconfig 中堆内存的大小。另外，长时间运行后如果出现不稳定，可以考虑是否在事件回调中进行了耗时的操作，阻塞了BLE任务。复杂的处理最好放到其他任务中去做。

最后，保持耐心。BLE开发涉及软硬件协同，问题可能出现在任何环节。养成查看串口日志的习惯，ESP-IDF的日志系统非常强大，把日志级别调到DEBUG，很多时候错误信息会直接告诉你哪里出了问题。多动手修改例程，从最小的改动开始测试，每成功一步，你的信心和经验就增加一分。当你第一次用自己的手机APP成功控制ESP32上的LED灯时，那种成就感会让你觉得这一切都是值得的。