BlueNRG-LP v3.x 协议栈 API 使用教程（基础实战版）

---

📦 一、初始化 BLE 协议栈

// 必须先调用 BLE_STACK_Init_nocallbacks()
// 提供 RAM buffer 和连接配置参数
BLE_STACK_InitTypeDef ble_init_params = {
    .BLEStartRamAddress = ble_ram_buffer,
    .BLEStackSize = BLE_STACK_RAM_SIZE,
    .NumAttrRecords = 100,
    .NumOfLinks = 2,
    ...
};
BLE_STACK_Init_nocallbacks(&ble_init_params);

// 初始化 GAP
aci_gap_init(GAP_PERIPHERAL_ROLE, privacy, dev_name_len, &service_handle, &name_handle, &appearance_handle);

---

📡 二、开启广播（Peripheral 模式）

// 1. 设置广播参数（adv_set）
aci_gap_set_advertising_configuration(
    0, GAP_MODE_GENERAL_DISCOVERABLE, ADV_IND,
    ADV_FILTER_POLICY_ALLOW_SCAN_ANY_CON_ANY,
    160, 160,
    PUBLIC_ADDR, NULL, 0,
    TX_POWER_NO_PREFERENCE,
    LE_1M_PHY, LE_1M_PHY,
    0, 0);

// 2. 设置广播数据
uint8_t adv_data[] = {
    0x02, 0x01, 0x06,
    0x0A, 0x09, 'B','L','E','_','D','E','M','O'
};
aci_gap_set_advertising_data(0, GAP_ADV_DATA_TYPE_COMPLETE_LOCAL_NAME, sizeof(adv_data), adv_data);

// 3. 启动广播
aci_gap_set_advertise_enable(ENABLE, 0, 0);

---

🔍 三、启动扫描（Central 模式）

// 1. 设置扫描参数
aci_gap_set_scan_configuration(
    GAP_OBSERVER_ROLE,            // 角色
    LE_1M_PHY,                    // PHY
    ACTIVE_SCAN,                  // 扫描类型
    100, 100,                     // window, interval
    PUBLIC_ADDR,                  // own address
    0                             // filter duplicates
);

// 2. 启动扫描
aci_gap_start_procedure(GAP_OBSERVER_ROLE, SCAN_INTERVAL_MS, SCAN_WINDOW_MS, SCAN_TIMEOUT_MS);

• 扫描结果会通过 HCI_LE_ADVERTISING_REPORT_EVENT 事件上报。

---

🔗 四、发起连接（Central 连接 Peripheral）

// 1. 设置连接参数（可选）
aci_gap_set_connection_configuration(LE_1M_PHY, ...);  // 可调超时时间等

// 2. 创建连接
aci_gap_create_connection(
    160, 160,                     // min/max interval
    PUBLIC_ADDR,                 // peer type
    peer_addr,                   // peer address
    PUBLIC_ADDR,                 // own address
    60, 60,                      // supervision timeout
    0, 600, 0, 0                 // latency, CE length
);

• 连接成功后会收到 HCI_LE_CONNECTION_COMPLETE_EVENT。

---

📨 五、发送通知数据（GATT Server）

// 初始化时添加服务、特征值
aci_gatt_srv_add_service(UUID_TYPE_16, uuid, PRIMARY_SERVICE, num_handles, &service_handle);
aci_gatt_srv_add_char(service_handle, UUID_TYPE_16, char_uuid,
                      max_len, CHAR_PROP_NOTIFY, ATTR_PERMISSION_NONE, ...);

// 连接后发送 notify
aci_gatt_srv_notify(conn_handle, char_handle, len, data);

---

📥 六、接收 notify / indication（GATT Client）

• 中央设备连接后，通过事件获取 notify 数据：

case ACI_GATT_CLT_NOTIFICATION_EVENT:
    // data->Attr_Handle, data->Attr_Value

• 启用 notify 需写入 CCCD descriptor（UUID 0x2902）：

aci_gatt_clt_write(conn_handle, cccd_handle, 2, (uint8_t[]){0x01, 0x00});

---

🛑 七、断开连接

aci_gap_terminate(conn_handle, 0x13);  // reason = user terminated

---

📎 八、其他常用操作

功能	API
设置广播 PHY	aci_gap_set_advertising_phy_configuration() //这个st还没有实现
修改广播内容	aci_gap_set_advertising_data()
修改 GATT 值	aci_gatt_srv_write_handle_value()
发起 MTU 交换	aci_att_exchange_mtu()
设置白名单	aci_gap_configure_white_and_resolving_list()

---

✅ 最小流程建议（用于调试验证）

// 初始化 BLE 协议栈
BLE_STACK_Init_nocallbacks(...);
aci_gap_init(...);

// 启动广播（Peripheral）
aci_gap_set_advertising_configuration(...);
aci_gap_set_advertising_data(...);
aci_gap_set_advertise_enable(ENABLE, ...);

// 主循环中处理事件
if (ble_evt_pending) {
    hci_user_evt_proc();
    ble_evt_pending = false;
}

---

📚 参考接口头文件

所有函数声明在：

Middlewares/ST/BLE_Stack/inc/bluenrg_lp_api.h