2. BLE 自定义服务示例

📁 源码位置: samples/bluetooth/ble/peripheral/custom_service 查看源码

2.1. 功能说明

本示例演示如何使用 LISA Bluetooth 组件实现自定义 GATT 服务。 主要功能包括：

  1. 自定义广播数据（Flags, Local Name）。

  2. 自定义扫描响应数据（Manufacturer Specific Data）。

  3. 自定义 GAP 配置（MAC 地址，设备名称）。

  4. 启动 BLE 协议栈（外设模式）。

  5. 自定义 GATT 服务 (UUID: 0x1234)，包含以下特征值：

    • 只读特征值 (UUID: 0x1235): 仅支持读取。

    • 只写特征值 (UUID: 0x1236): 支持 Write Request 和 Write Command。

    • 通知特征值 (UUID: 0x1237): 支持 Notify，带有 CCCD。

    • 读写特征值 (UUID: 0x1238): 支持读取和写入。

    • 安全读特征值 (UUID: 0x1239): 需要配对/认证后才能读取。

2.2. 硬件连接

无需外部连接，使用板载 BLE 功能。

2.3. 示例内容

  1. 初始化 NVS 和 射频校准。

  2. 初始化 LISA Bluetooth 组件。

  3. 注册自定义 GATT 服务。

  4. 系统自动开始广播（作为外设）。

2.4. 编译

重要提示：在编译前，请先确认您使用的开发板型号。SDK 目前支持以下开发板：

  • arcs_evb - ARCS EVB 评估板

  • arcs_mini - ARCS Mini 开发板

根据您的开发板型号，选择对应的编译命令：

在示例目录下执行编译:

# 使用 arcs_evb 开发板
./build.sh -C -DBOARD=arcs_evb

# 或使用 arcs_mini 开发板
./build.sh -C -DBOARD=arcs_mini

Note

如果在 SDK 根目录执行，需要指定示例路径:

# 使用 arcs_evb 开发板
./build.sh -C -S samples/<示例路径> -DBOARD=arcs_evb

# 或使用 arcs_mini 开发板
./build.sh -C -S samples/<示例路径> -DBOARD=arcs_mini

Note

确保已安装对应的工具链。

2.5. 预期输出

[I][sample] === BLE Custom Service Example ===
[I][lisa_bt] BLE Stack Initialized
[I][custom_svc] Initializing Custom Service
[I][custom_svc] Custom Service added, start_hdl=...
...

2.6. 核心 API

API

说明

lisa_bluetooth_init()

初始化蓝牙协议栈

lisa_bt_get_adv_data()

获取自定义广播数据（弱符号覆盖）

lisa_bt_get_scan_rsp_data()

获取自定义扫描响应数据（弱符号覆盖）

lisa_bt_gap_config()

自定义 GAP 配置（弱符号覆盖）

ble_gatt_user_register()

注册 GATT 回调

ble_gatt_db_svc16_add()

添加 16-bit UUID 服务到数据库

2.7. 关键代码

自定义广播数据

/* 自定义广播数据 */
const uint8_t* lisa_bt_get_adv_data(uint8_t *len)
{
    *len = sizeof(user_adv_data);
    return user_adv_data;
}

自定义服务属性表

static const ble_gatt_att16_desc_t custom_att_db[IDX_NB] = {
    // Service Declaration
    [IDX_SVC] = {BLE_GATT_DECL_PRIMARY_SERVICE, BLE_PROP(RD), 0},

    // Char 1: Read (只读)
    [IDX_CHAR_READ_DECL] = {BLE_GATT_DECL_CHARACTERISTIC, BLE_PROP(RD), 0},
    [IDX_CHAR_READ_VAL] = {CUSTOM_CHAR_READ_UUID, BLE_PROP(RD), 20},

    // ... (其他特征值)

    // Char 5: Secure Read (安全读取，需要认证)
    [IDX_CHAR_SEC_READ_DECL] = {BLE_GATT_DECL_CHARACTERISTIC, BLE_PROP(RD), 0},
    [IDX_CHAR_SEC_READ_VAL] = {CUSTOM_CHAR_SEC_READ_UUID, BLE_PROP(RD) | BLE_SEC_LVL(RP, AUTH), 20},
};

2.8. 注意事项

  1. MAC 地址: 示例中使用了固定的 MAC 地址，实际产品中应从 NVS 或其他存储中读取。

  2. 广播数据: 广播数据长度有限制（通常 31 字节），请注意不要溢出。

  3. 安全特征值: 访问安全特征值（如 UUID 0x1239）时，手机端通常会弹出配对请求，需确认配对后方可读取。