BLE APIs

BLE 简介

BK7238 是BLE 5.2 协议栈，同时支持master和slave 模式。

BLE API 类别

BLE API 可分为：

BLE common interface

BLE scan interface

BLE ADV interface

BLE connect interface

编程建议

重要

使用BLE API 的一些特别注意项:
1. 不要在 BLE 事件回调中做太多工作，需将事件通过信号量等方式抛到您自己的应用程序任务处理.
2. BK7238 BLE API都是异步执行的,应用程序调用 BLE API ，需要获得对应的BLE 事件通知。

API Reference

Functions

uint8_t app_ble_get_idle_actv_idx_handle(void)

Get an idle activity.

返回: the idle activity’s index

ble_err_t bk_ble_create_db(struct bk_ble_db_cfg *ble_db_cfg)

Register a gatt service.

example: First we must build test_att_db test_att_db is a database for att, which used in ble discovery. reading writing and other operation is used on a att database.

#define BK_ATT_DECL_PRIMARY_SERVICE_128     {0x00,0x28,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0}
#define BK_ATT_DECL_CHARACTERISTIC_128      {0x03,0x28,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0}
#define BK_ATT_DESC_CLIENT_CHAR_CFG_128     {0x02,0x29,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0}

#define WRITE_REQ_CHARACTERISTIC_128        {0x01,0xFF,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0}
#define INDICATE_CHARACTERISTIC_128         {0x02,0xFF,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0}
#define NOTIFY_CHARACTERISTIC_128           {0x03,0xFF,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0,0x0}

static const uint8_t test_svc_uuid[16] = {0xFF,0xFF,0,0,0x34,0x56,0,0,0,0,0x28,0x37,0,0,0,0};

enum
{
   TEST_IDX_SVC,
   TEST_IDX_FF01_VAL_CHAR,
   TEST_IDX_FF01_VAL_VALUE,
   TEST_IDX_FF02_VAL_CHAR,
   TEST_IDX_FF02_VAL_VALUE,
   TEST_IDX_FF02_VAL_IND_CFG,
   TEST_IDX_FF03_VAL_CHAR,
   TEST_IDX_FF03_VAL_VALUE,
   TEST_IDX_FF03_VAL_NTF_CFG,
   TEST_IDX_NB,
};

//att records database.
bk_attm_desc_t test_att_db[TEST_IDX_NB] =
{
   //  Service Declaration
   [TEST_IDX_SVC]              = {BK_ATT_DECL_PRIMARY_SERVICE_128, PROP(RD), 0},

   //  Level Characteristic Declaration
   [TEST_IDX_FF01_VAL_CHAR]    = {BK_ATT_DECL_CHARACTERISTIC_128,  PROP(RD), 0},
   //  Level Characteristic Value
   [TEST_IDX_FF01_VAL_VALUE]   = {WRITE_REQ_CHARACTERISTIC_128,    PROP(WR)|ATT_UUID(128), 128|OPT(NO_OFFSET)},

   [TEST_IDX_FF02_VAL_CHAR]    = {BK_ATT_DECL_CHARACTERISTIC_128,  PROP(RD), 0},
   //  Level Characteristic Value
   [TEST_IDX_FF02_VAL_VALUE]   = {INDICATE_CHARACTERISTIC_128,     PROP(I), 128|OPT(NO_OFFSET)},

   //  Level Characteristic - Client Characteristic Configuration Descriptor

   [TEST_IDX_FF02_VAL_IND_CFG] = {BK_ATT_DESC_CLIENT_CHAR_CFG_128, PROP(RD)|PROP(WR),OPT(NO_OFFSET)},

   [TEST_IDX_FF03_VAL_CHAR]    = {BK_ATT_DECL_CHARACTERISTIC_128,  PROP(RD), 0},
   //  Level Characteristic Value
   [TEST_IDX_FF03_VAL_VALUE]   = {NOTIFY_CHARACTERISTIC_128,       PROP(N), 128|OPT(NO_OFFSET)},

   //  Level Characteristic - Client Characteristic Configuration Descriptor

   [TEST_IDX_FF03_VAL_NTF_CFG] = {BK_ATT_DESC_CLIENT_CHAR_CFG_128, PROP(RD)|PROP(WR), OPT(NO_OFFSET)},
};

TEST_IDX_SVC is nessecery, is declare a primary att service. The macro define is: which is an UUID say it is a “primary service”

TEST_IDX_FF01_VAL_CHAR declare a characteristic as a element in service, it must be PROP(RD)

TEST_IDX_FF01_VAL_VALUE is the real value of TEST_IDX_FF01_VAL_CHAR,

PROP(N) Notification Access

PROP(I) Indication Access

PROP(RD) Read Access

PROP(WR) Write Request Enabled

PROP(WC) Write Command Enabled

ATT_UUID(128) set att uuid len

Secondlly, we build ble_db_cfg

struct bk_ble_db_cfg ble_db_cfg;

ble_db_cfg.att_db = (ble_attm_desc_t *)test_att_db;
ble_db_cfg.att_db_nb = TEST_IDX_NB;
ble_db_cfg.prf_task_id = g_test_prf_task_id;
ble_db_cfg.start_hdl = 0;
ble_db_cfg.svc_perm = BK_BLE_PERM_SET(SVC_UUID_LEN, UUID_16);

prf_task_id is app handle. If you have multi att service, used prf_task_id to distinguish it. svc_perm show TEST_IDX_SVC UUID type’s len.

参数

ble_db_cfg, : – service param

返回

ERR_SUCCESS: succeed
others: other errors.

void ble_set_notice_cb(ble_notice_cb_t func)

Register ble event notification callback.

User example:

   void ble_notice_cb(ble_notice_t notice, void *param)
   {
      switch (notice) {
      case BLE_5_STACK_OK:
      case BLE_5_WRITE_EVENT: 
      case BLE_5_READ_EVENT:
      case  BLE_5_TX_DONE
        break;
      case BLE_5_CREATE_DB:
      //bk_ble_create_db success here
        break;
      }
   }

ble_set_notice_cb(ble_notice_cb);

Attention

you must regist it, otherwise you cant get any event !
you must regist it before bk_ble_create_db, otherwise you cant get BLE_5_CREATE_DB event

参数: func, : – event callback
返回: void

uint8_t ble_appm_get_dev_name(uint8_t *name, uint32_t buf_len)

Get device name.

参数

name, : – store the device name
buf_len, : – the length of buf to store the device name

返回

length: the length of device name

uint8_t ble_appm_set_dev_name(uint8_t len, uint8_t *name)

Set device name.

参数

len, : – the length of device name
name, : – the device name to be set

返回

length: the length of device name

ble_err_t bk_ble_adv_start(uint8_t actv_idx, struct adv_param *adv, ble_cmd_cb_t callback)

Create and start a ble advertising activity.

User example:

struct adv_param adv_info;
adv_info.channel_map = 7;
adv_info.duration = 0;
adv_info.prop = (1 << ADV_PROP_CONNECTABLE_POS) | (1 << ADV_PROP_SCANNABLE_POS);
adv_info.interval_min = 160;
adv_info.interval_max = 160;
adv_info.advData[0] = 0x09;
adv_info.advData[1] = 0x09;
memcpy(&adv_info.advData[2], "7238_BLE", 8);
adv_info.advDataLen = 10;
adv_info.respData[0] = 0x05;
adv_info.respData[1] = 0x08;
memcpy(&adv_info.respData[2], "7238", 4);
adv_info.respDataLen = 6;
actv_idx = app_ble_get_idle_actv_idx_handle();
bk_ble_adv_start(actv_idx, &adv_info, ble_cmd_cb);

Attention

you must wait callback status, 0 mean success.

参数

actv_idx, : – the index of activity
adv, : – the advertising parameter
callback, : – register a callback for this action, ble_cmd_t: BLE_INIT_ADV

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_adv_stop(uint8_t actv_idx, ble_cmd_cb_t callback)

Stop and delete the advertising that has been created.

Attention

you must wait callback status, 0 mean success.
must used after bk_ble_adv_start

参数

actv_idx, : – the index of activity
callback, : – register a callback for this action, ble_cmd_t: BLE_DEINIT_ADV

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_scan_start(uint8_t actv_idx, struct scan_param *scan, ble_cmd_cb_t callback)

Create and start a ble scan activity.

User example:

struct scan_param scan_info;
scan_info.channel_map = 7;
scan_info.interval = 100;
scan_info.window = 30;
actv_idx = app_ble_get_idle_actv_idx_handle();
bk_ble_scan_start(actv_idx, &scan_info, ble_cmd_cb);

Attention

you must wait callback status, 0 mean success.

参数

actv_idx, : – the index of activity
scan, : – the scan parameter
callback, : – register a callback for this action, ble_cmd_t: BLE_INIT_SCAN

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_scan_stop(uint8_t actv_idx, ble_cmd_cb_t callback)

Stop and delete the scan that has been created.

Attention

you must wait callback status, 0 mean success.
must used after bk_ble_scan_start

参数

actv_idx, : – the index of activity
callback, : – register a callback for this action, ble_cmd_t: BLE_DEINIT_SCAN

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_create_advertising(uint8_t actv_idx, unsigned char chnl_map, uint32_t intv_min, uint32_t intv_max, ble_cmd_cb_t callback)

Create a ble advertising activity.

User example:

actv_idx = app_ble_get_idle_actv_idx_handle();
if (actv_idx != UNKNOW_ACT_IDX) {
    bk_ble_create_advertising(actv_idx,7,160,160, ble_cmd_cb);
}

Attention

you must wait callback status, 0 mean success.

参数

actv_idx, : – the index of activity
chnl_map, : – the advertising channel map
intv_min, : – the advertising min interval
intv_max, : – the advertising max interval
callback, : – register a callback for this action, ble_cmd_t: BLE_CREATE_ADV

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_create_extended_advertising(uint8_t actv_idx, unsigned char chnl_map, uint32_t intv_min, uint32_t intv_max, uint8_t scannable, uint8_t connectable, ble_cmd_cb_t callback)

Create a ble advertising activity.

User example:

actv_idx = app_ble_get_idle_actv_idx_handle();
if (actv_idx != UNKNOW_ACT_IDX) {
    bk_ble_create_extended_advertising(actv_idx,7,160,160,1,0,ble_cmd_cb);
}

Attention

you must wait callback status, 0 mean success.

参数

actv_idx, : – the index of activity
chnl_map, : – the advertising channel map
intv_min, : – the advertising min interval
intv_max, : – the advertising max interval
scannable, : – the advertising whether be scanned
connectable, : – the advertising whether be connected
callback, : – register a callback for this action, ble_cmd_t: BLE_CREATE_ADV

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_start_advertising(uint8_t actv_idx, uint16 duration, ble_cmd_cb_t callback)

Start a ble advertising.

Attention

you must wait callback status, 0 mean success.
must used after bk_ble_create_advertising

参数

actv_idx, : – the index of activity
duration, : – Advertising duration (in unit of 10ms). 0 means that advertising continues
callback, : – register a callback for this action, ble_cmd_t: BLE_START_ADV

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_stop_advertising(uint8_t actv_idx, ble_cmd_cb_t callback)

Stop the advertising that has been started.

Attention

you must wait callback status, 0 mean success.
must used after bk_ble_start_advertising

参数

actv_idx, : – the index of activity
callback, : – register a callback for this action, ble_cmd_t: BLE_STOP_ADV

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_delete_advertising(uint8_t actv_idx, ble_cmd_cb_t callback)

Delete the advertising that has been created.

Attention

you must wait callback status, 0 mean success.
must used after bk_ble_create_advertising

参数

actv_idx, : – the index of activity
callback, : – register a callback for this action, ble_cmd_t: BLE_DELETE_ADV

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_set_adv_data(uint8_t actv_idx, unsigned char *adv_buff, unsigned char adv_len, ble_cmd_cb_t callback)

Set the advertising data.

User example:

const uint8_t adv_data[] = {0x0A, 0x09, 0x37 0x32, 0x33, 0x31, 0x4e, 0x5f, 0x42, 0x4c, 0x45};
bk_ble_set_adv_data(actv_idx, adv_data, sizeof(adv_data), ble_cmd_cb);

Attention

you must wait callback status, 0 mean success.
must used after bk_ble_create_advertising

参数

actv_idx, : – the index of activity
adv_buff, : – advertising data
adv_len, : – the length of advertising data
callback, : – register a callback for this action, ble_cmd_t: BLE_SET_ADV_DATA

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_set_ext_adv_data(uint8_t actv_idx, unsigned char *adv_buff, uint16_t adv_len, ble_cmd_cb_t callback)

Set the ext advertising data.

User example:

const uint8_t adv_data[] = {0x0A, 0x09, 0x37 0x32, 0x33, 0x31, 0x4e, 0x5f, 0x42, 0x4c, 0x45};
bk_ble_set_ext_adv_data(actv_idx, adv_data, sizeof(adv_data), ble_cmd_cb);

Attention

you must wait callback status, 0 mean success.
must used after bk_ble_create_extended_advertising

参数

actv_idx, : – the index of activity
adv_buff, : – advertising data
adv_len, : – the length of advertising data
callback, : – register a callback for this action, ble_cmd_t: BLE_SET_ADV_DATA

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_set_scan_rsp_data(uint8_t actv_idx, unsigned char *scan_buff, unsigned char scan_len, ble_cmd_cb_t callback)

Set the scan response data.

User example:

const uint8_t scan_data[] = {0x0A, 0x09, 0x37 0x32, 0x33, 0x31, 0x4e, 0x5f, 0x42, 0x4c, 0x45};
bk_ble_set_scan_rsp_data(actv_idx, scan_data, sizeof(scan_data), ble_cmd_cb);

Attention

you must wait callback status, 0 mean success.
scan rsp data similaly to adv data
must used after bk_ble_create_advertising

参数

actv_idx, : – the index of activity
scan_buff, : – scan response data
scan_len, : – the length of scan response data
callback, : – register a callback for this action, ble_cmd_t: BLE_SET_RSP_DATA

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_set_ext_scan_rsp_data(uint8_t actv_idx, unsigned char *scan_buff, uint16_t scan_len, ble_cmd_cb_t callback)

Set the ext adv scan response data.

User example:

const uint8_t scan_data[] = {0x0A, 0x09, 0x37 0x32, 0x33, 0x31, 0x4e, 0x5f, 0x42, 0x4c, 0x45};
bk_ble_set_ext_scan_rsp_data(actv_idx, scan_data, sizeof(scan_data), ble_cmd_cb);

Attention

you must wait callback status, 0 mean success.
scan rsp data similaly to adv data
must used after bk_ble_create_extended_advertising

参数

actv_idx, : – the index of activity
scan_buff, : – scan response data
scan_len, : – the length of scan response data
callback, : – register a callback for this action, ble_cmd_t: BLE_SET_RSP_DATA

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_create_periodic_advertising(uint8_t actv_idx, struct per_adv_param *per_adv, ble_cmd_cb_t callback)

Create a ble periodic advertising activity.

User example:

struct per_adv_param per_adv_param;
per_adv_param.adv_intv_min = 120;
per_adv_param.adv_intv_max = 160;
per_adv_param.chnl_map = 7;
per_adv_param.adv_prop = (0 << ADV_PROP_CONNECTABLE_POS) | (0 << ADV_PROP_SCANNABLE_POS);;
per_adv_param.prim_phy = 1;
per_adv_param.second_phy = 1;
per_adv_param.own_addr_type = GAPM_STATIC_ADDR;

actv_idx = app_ble_get_idle_actv_idx_handle();
bk_ble_create_periodic_advertising(actv_idx, &per_adv_param, ble_cmd_cb);

Attention

you must wait callback status, 0 mean success.

参数

actv_idx – : the index of periodic advertising activity
per_adv, : – the periodic advertising parameter
callback, : – register a callback for this action, ble_cmd_t: BLE_CREATE_ADV

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_set_periodic_adv_data(uint8_t actv_idx, unsigned char *adv_buff, uint16_t adv_len, ble_cmd_cb_t callback)

Set the periodic advertising data.

Attention

you must wait callback status, 0 mean success.
must used after bk_ble_create_periodic_advertising.

参数

actv_idx – : the index of periodic advertising activity
adv_buff, : – periodic advertising data
adv_len, : – the length of periodic advertising data
callback, : – register a callback for this action, ble_cmd_t: BLE_SET_ADV_DATA

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_start_periodic_advertising(uint8_t actv_idx, uint16 duration, ble_cmd_cb_t callback)

Start a ble periodic advertising.

Attention

you must wait callback status, 0 mean success.
must used after bk_ble_create_periodic_advertising.

参数

actv_idx – : the index of periodic advertising activity
duration, : – periodic advertising (in unit of 10ms). 0 means that periodic advertising continues
callback, : – register a callback for this action, ble_cmd_t: BLE_START_ADV

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_stop_periodic_advertising(uint8_t actv_idx, ble_cmd_cb_t callback)

Stop the periodic advertising that has been started.

Attention

you must wait callback status, 0 mean success.
must used after bk_ble_start_periodic_advertising.

参数

actv_idx – : the index of periodic advertising activity
callback, : – register a callback for this action, ble_cmd_t: BLE_STOP_ADV

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_delete_periodic_advertising(uint8_t actv_idx, ble_cmd_cb_t callback)

Delete the periodic advertising that has been created.

Attention

you must wait callback status, 0 mean success.
must used after bk_ble_create_periodic_advertising.

参数

actv_idx – : the index of periodic advertising activity
callback, : – register a callback for this action, ble_cmd_t: BLE_DELETE_ADV

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_create_periodic_sync(uint8_t actv_idx, ble_cmd_cb_t callback)

Create a ble periodic synchronize activity.

User example:

actv_idx = app_ble_get_idle_actv_idx_handle();
bk_ble_create_periodic_sync(actv_idx, ble_cmd_cb);

Attention

you must wait callback status, 0 mean success.

参数

actv_idx – : the index of periodic synchronize activity
callback, : – register a callback for this action, ble_cmd_t: BLE_CREATE_PERIODIC_SYNC

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_start_periodic_sync(uint8_t actv_idx, ble_periodic_sync_param_t *param, ble_cmd_cb_t callback)

Start a ble periodic synchronize.

User example:

ble_periodic_sync_param_t periodic_param;
uint8_t mac[6]={0xc8,0x47,0x8c,0x11,0x22,0x33};
memcpy(periodic_param.adv_addr.addr, mac, GAP_BD_ADDR_LEN);
periodic_param.report_en_bf = 1;
periodic_param.adv_sid = 0;
periodic_param.adv_addr_type = 0;
periodic_param.skip = 0;
periodic_param.sync_to = 150;
periodic_param.cte_type = 0;
periodic_param.per_sync_type = GAPM_PER_SYNC_TYPE_GENERAL;
bk_ble_start_periodic_sync(actv_idx, &periodic_param, ble_cmd_cb);

Attention

you must wait callback status, 0 mean success.
must used after bk_ble_create_periodic_sync.

参数

actv_idx – : the index of periodic synchronize activity
param, : – the periodic synchronization parameters
callback, : – register a callback for this action, ble_cmd_t: BLE_START_PERIODIC_SYNC

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_stop_periodic_sync(uint8_t actv_idx, ble_cmd_cb_t callback)

Stop the periodic synchronize that has been started.

Attention

you must wait callback status, 0 mean success.
must used after bk_ble_start_periodic_sync.

参数

actv_idx – : the index of periodic synchronize activity
callback, : – register a callback for this action, ble_cmd_t: BLE_STOP_PERIODIC_SYNC

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_delete_periodic_sync(uint8_t actv_idx, ble_cmd_cb_t callback)

Delete the periodic synchronize that has been created.

Attention

you must wait callback status, 0 mean success.
must used after bk_ble_create_periodic_sync.

参数

actv_idx – : the index of periodic synchronize activity
callback, : – register a callback for this action, ble_cmd_t: BLE_DELETE_PERIODIC_SYNC

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_periodic_adv_sync_transf(uint8_t actv_idx, uint16_t service_data)

Transfer periodic advertising sync information to peer device.

参数

actv_idx – : periodic advertising or periodic sync activity index
service_data, : – a value provided by application

返回

ERR_SUCCESS: succeed
others: fail

ble_err_t bk_ble_update_param(uint8_t conn_idx, uint16_t intv_min, uint16_t intv_max, uint16_t latency, uint16_t sup_to)

Update connection parameters.

Attention

must used after connected

参数

conn_idx, : – the index of connection
intv_min, : – connection min interval
intv_max, : – connection max interval
latency, : – connection latency
sup_to, : – connection timeout

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_disconnect(uint8_t conn_idx)

Disconnect a ble connection.

Attention

must used after connected

参数

conn_idx, : – the index of connection

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_create_scaning(uint8_t actv_idx, ble_cmd_cb_t callback)

Create a ble scan activity.

User example:

actv_idx = app_ble_get_idle_actv_idx_handle();
bk_ble_create_scaning(actv_idx, ble_at_cmd);

Attention

you must wait callback status, 0 mean success.

参数

actv_idx, : – the index of activity
callback, : – register a callback for this action, ble_cmd_t: BLE_CREATE_SCAN

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_start_scaning(uint8_t actv_idx, uint16_t scan_intv, uint16_t scan_wd, ble_cmd_cb_t callback)

Start a ble scan.

Attention

you must wait callback status, 0 mean success.
must used after bk_ble_create_scaning
adv will report in ble_notice_cb_t as BLE_5_REPORT_ADV

参数

actv_idx, : – the index of activity
scan_intv, : – scan interval
scan_wd, : – scan window
callback, : – register a callback for this action, ble_cmd_t: BLE_START_SCAN

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_stop_scaning(uint8_t actv_idx, ble_cmd_cb_t callback)

Stop the scan that has been started.

Attention

you must wait callback status, 0 mean success.
must used after bk_ble_start_scaning

参数

actv_idx, : – the index of activity
callback, : – register a callback for this action, ble_cmd_t: BLE_STOP_SCAN

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_delete_scaning(uint8_t actv_idx, ble_cmd_cb_t callback)

Delete the scan that has been created.

Attention

you must wait callback status, 0 mean success.
must used after bk_ble_create_scaning

参数

actv_idx, : – the index of activity
callback, : – register a callback for this action, ble_cmd_t: BLE_DELETE_SCAN

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_gap_read_phy(uint8_t conn_idx, ble_read_phy_t *phy)

Read the current transmitter PHY and receiver PHY on the connection identified by remote address.

Attention

The command is used after the connection is established.

参数

conn_idx – : the index of connection
phy, : – store the tx_phy and rx_phy

返回

ERR_SUCCESS: succeed
others: fail

ble_err_t bk_ble_gap_set_phy(uint8_t conn_idx, ble_set_phy_t *phy)

Set the PHY preferences for the connection identified by the remote address.

Attention

The Controller might not be able to make the change (e.g. because the peer does not support the requested PHY) or may decide that the current PHY is preferable.
The command is used after the connection is established.

参数

conn_idx – : the index of connection
phy, : – the phy to be set

返回

ERR_SUCCESS: succeed
others: fail

ble_err_t bk_ble_gap_update_per_adv_list(uint8_t add_remove, struct bd_addr *addr, uint8_t addr_type, uint8_t adv_sid)

Add or Remove a single device to the Periodic Advertiser list stored in the Controller.

Attention

The size of the per_adv list is 6.

参数

addr_remove – : 0=remove/1=add
addr, : – device address
addr_type, : – address type of device 0=public/1=random
adv_sid, : – advertising sid subfield in the ADI field used to identify the periodic advertising

返回

ERR_SUCCESS: succeed
others: fail

ble_err_t bk_ble_gap_clear_per_adv_list(void)

Remove all devices from the list of Periodic Advertisers in the Controller.

返回

ERR_SUCCESS: succeed
others: fail

ble_err_t bk_ble_gap_get_whitelist_size(uint8_t *wl_size)

Get the total size of Whitelist.

参数

wl_size – : point to whitelist size

返回

ERR_SUCCESS: succeed
others: fail

ble_err_t bk_ble_gap_update_whitelist(uint8_t add_remove, struct bd_addr *addr, uint8_t addr_type)

Add or Remove a single device to the whitelist.

参数

addr_remove – : 0=remove/1=add
addr, : – point to device address
addr_type, : – address type of device 0=public/1=random

返回

ERR_SUCCESS: succeed
others: fail

ble_err_t bk_ble_gap_clear_whitelist(void)

Remove all devices from the Whitelist.

返回

ERR_SUCCESS: succeed
others: fail

ble_err_t bk_ble_gap_prefer_ext_connect_params_set(uint8_t phy_mask, struct appm_create_conn_param *phy_1m_conn_params, struct appm_create_conn_param *phy_2m_conn_params, struct appm_create_conn_param *phy_coded_conn_params)

Set aux connection parameters.

参数

phy_mask – : bit 0: 1M; bit 1: 2M; bit 2: coded
phy_1m_conn_params, : – point to the params used by 1M phy
phy_2m_conn_params, : – point to the params used by 2M phy
phy_coded_conn_params, : – point to the params used by coded phy

返回

ERR_SUCCESS: succeed
others: fail

ble_err_t bk_ble_gap_config_local_icon(uint16_t appearance)

Set local gap appearance icon.

参数

appearance – : External appearance value, these values are defined by the Bluetooth SIG, please refer to https://specificationrefs.bluetooth.com/assigned-values/Appearance%20Values.pdf

返回

ERR_SUCCESS: succeed
others: fail

ble_err_t bk_ble_gap_set_channels(bk_ble_channels_t *channels)

BLE set host channels classification.

参数

channels – : The nth such field (in the range 0 to 36) contains the value for the link layer channel index n. 0 means channel n is bad. 1 means channel n is unknown. The most significant bits are reserved and shall be set to 0. At least one channel shall be marked as unknown.

返回

ERR_SUCCESS: succeed
others: fail

ble_err_t bk_ble_get_bond_device_num(uint8_t *dev_num)

Get the device number of bonded peer devices.

参数

dev_num – : point to bonede device number

返回

ERR_SUCCESS: succeed
others: fail

ble_err_t bk_ble_get_bonded_device_list(uint8_t *dev_num, bk_ble_bond_dev_t *dev_list)

Get the device list of bonded peer devices.

参数

dev_num – : point to the size of device list. If the number of bonded devices is larger than dev_num, this function will return fail.
dev_list, : – point to the list of bonded device.

返回

ERR_SUCCESS: succeed
others: fail

sec_err_t bk_ble_gap_set_security_param(struct app_pairing_cfg *param, sec_notice_cb_t func)

Set the params of pairing, include IO capability, key distribution, auth and secure level.

User example: Suppose peer device is a phone, so that it’s IO capability is KeyboardDisplay and it supports Secure conncetion pairing.

1. Legacy Pairing Use Pass Key Entry.
 param.sec_req = GAP_SEC1_AUTH_PAIR_ENC;
 param.auth = GAP_AUTH_REQ_MITM_BOND;
 param.ikey_dist = GAP_KDIST_ENCKEY | GAP_KDIST_LINKKEY | GAP_KDIST_IDKEY;
 param.rkey_dist = GAP_KDIST_ENCKEY | GAP_KDIST_LINKKEY;
 param.iocap = GAP_IO_CAP_DISPLAY_ONLY;

2. Secure Connection Pairing Use Pass Key Entry.
 param.sec_req = GAP_SEC1_SEC_CON_PAIR_ENC;
 param.auth = GAP_AUTH_REQ_SEC_CON_BOND;
 param.ikey_dist = GAP_KDIST_IDKEY;
 param.rkey_dist = GAP_KDIST_NONE;
 param.iocap = GAP_IO_CAP_DISPLAY_ONLY;

3. Secure Connection Pairing Use Just Work.
 param.sec_req = GAP_SEC1_NOAUTH_PAIR_ENC;
 param.auth = GAP_AUTH_REQ_SEC_CON_BOND;
 param.ikey_dist = GAP_KDIST_IDKEY;
 param.rkey_dist = GAP_KDIST_NONE;
 param.iocap = GAP_IO_CAP_NO_INPUT_NO_OUTPUT;

参数

param – : point to the configuration of pairing params.
func, : – the notice callback function of secure module.

返回

APP_SEC_ERROR_NO_ERROR: succeed
others: fail

sec_err_t bk_ble_gap_security_rsp(uint8_t conn_idx, bool accept)

Grant security request access.

参数

conn_idx – : connection idx of app
accept, : – accept the security request or not

返回

APP_SEC_ERROR_NO_ERROR: succeed
others: fail

sec_err_t bk_ble_gap_pairing_rsp(uint8_t conn_idx, bool accept)

Grant pairing request access.

参数

conn_idx – : connection idx of app
accept, : – accept the pairing request or not

返回

APP_SEC_ERROR_NO_ERROR: succeed
others: fail

sec_err_t bk_ble_passkey_reply(uint8_t conn_idx, bool accept, uint32_t passkey)

Reply the temporary key value to the peer device.

参数

conn_idx – : connection idx of app
accept, : – accept to process tk exchange
passkey, : – passkey value, must be less than 999999

返回

APP_SEC_ERROR_NO_ERROR: succeed
others: fail

sec_err_t bk_ble_confirm_reply(uint8_t conn_idx, bool accept)

Reply the confirm value to the peer device in the secure connection using numeric comparison.

参数

conn_idx – : connection idx of app
accept, : – numbers to compare are the same or different.

返回

APP_SEC_ERROR_NO_ERROR: succeed
others: fail

ble_err_t bk_ble_get_sendable_packets_num(uint16_t *pkt_total)

Get the total packet number that can be sent to controller.

参数

dev_num – : point to the total packet number

返回

ERR_SUCCESS: succeed
others: fail

ble_err_t bk_ble_get_cur_sendable_packets_num(uint16_t *pkt_curr)

Get the available packet number that can be sent to controller.

参数

dev_num – : point to the available packet number

返回

ERR_SUCCESS: succeed
others: fail

void sdp_set_notice_cb(sdp_notice_cb_t func)

Register ble master event notification callback.

you must regist it before bk_ble_create_init

Attention

you must regist it, otherwise you cant get any master event !

User example:

void sdp_event_cb(sdp_notice_t notice, void *param)
{
    switch (notice) {
        case SDP_CHARAC_NOTIFY_EVENT:
            {
                sdp_event_t *g_sdp = (sdp_event_t *)param;
                bk_printf("[SDP_CHARAC_NOTIFY_EVENT]con_idx:%d,hdl:0x%x,value_length:%d\r\n",g_sdp->con_idx,g_sdp->hdl,g_sdp->value_length);
            }
            break;
        case SDP_CHARAC_INDICATE_EVENT:
            {
                sdp_event_t *g_sdp = (sdp_event_t *)param;
                bk_printf("[SDP_CHARAC_INDICATE_EVENT]con_idx:%d,hdl:0x%x,value_length:%d\r\n",g_sdp->con_idx,g_sdp->hdl,g_sdp->value_length);
            }
            break;
        case SDP_CHARAC_READ:
            {
                sdp_event_t *g_sdp = (sdp_event_t *)param;
                bk_printf("[SDP_CHARAC_READ]con_idx:%d,hdl:0x%x,value_length:%d\r\n",g_sdp->con_idx,g_sdp->hdl,g_sdp->value_length);
            }
            break;
        case SDP_DISCOVER_SVR_DONE:
            {
                bk_printf("[SDP_DISCOVER_SVR_DONE]\r\n");
            }
            break;
        case SDP_CHARAC_WRITE_DONE:
            {
                bk_printf("[SDP_CHARAC_WRITE_DONE]\r\n");
            }
            break;
        default:
            bk_printf("[%s]Event:%d\r\n",__func__,notice);
            break;
    }
}
 sdp_set_notice_cb(sdp_event_cb);

参数

func, : – event callback

返回

void

ble_err_t bk_ble_create_init(uint8_t con_idx, unsigned short con_interval, unsigned short con_latency, unsigned short sup_to, ble_cmd_cb_t callback)

Create a activity for initiating a connection.

User example:

con_interval = 0x40; //interval
con_latency = 0;
sup_to = 0x200;//supervision timeout
bk_ble_create_init(con_idx, con_interval, con_latency,sup_to,ble_at_cmd);

Attention

you must wait callback status, 0 mean success.

参数

con_idx, : – the index of connection
con_interval, : – the connection parameter
con_latency, : – the connection parameter
sup_to, : – the connection parameter
callback, : – register a callback for this action, ble_cmd_t: BLE_INIT_CREATE

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_init_set_connect_dev_addr(unsigned char connidx, struct bd_addr *bdaddr, unsigned char addr_type)

Set the address of the device to be connected.

User example:

struct bd_addr bdaddr;
    uint8_t mac[6]={0xc8,0x47,0x8c,0x11,0x22,0x33};
memcpy(bdaddr.addr,mac,6);
addr_type = ADDR_PUBLIC;
bk_ble_init_set_connect_dev_addr(actv_idx,&bdaddr,addr_type);

Attention

must used before bk_ble_init_start_conn and used after bk_ble_create_init
addr_type must right, if wrong, cant connect

参数

connidx, : – the index of connection
bdaddr, : – the address of the device to be connected
addr_type, : – the address type of the device to be connected, 1: public 0: random

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_init_start_conn(uint8_t con_idx, uint16_t con_dev_time, ble_cmd_cb_t callback)

start a connection

Attention

you must wait callback status,0 mean success
must used after bk_ble_create_init and bk_ble_init_set_connect_dev_addr
when connect result, will recv BLE_5_INIT_CONNECT_EVENT in ble_notice_cb_t
when connect timeout,will recv BLE_5_INIT_CONNECT_FAILED_EVENT

参数

con_idx, : – the index of connection
con_dev_time(in – ms): supervision timeout for create connect.0 means keep scan target device
callback, : – register a callback for this action, ble_cmd_t: BLE_INIT_START_CONN

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_init_stop_conn(uint8_t con_idx, ble_cmd_cb_t callback)

Stop a connection.

Attention

you must wait callback status,0 mean success
must used after bk_ble_init_start_conn

参数

con_idx, : – the index of connection
callback, : – register a callback for this action, ble_cmd_t: BLE_INIT_STOP_CONN

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_conidx_send_ntf(uint8_t conidx, uint32_t len, uint8_t *buf, uint16_t prf_id, uint16_t att_idx)

As slaver, send a notification of an attribute’s value.

参数

conidx, : – the index of connection
len, : – the length of attribute’s value
buf, : – attribute’s value
prf_id, : – The id of the profile
att_idx, : – The index of the attribute

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_conidx_send_ind(uint8_t conidx, uint32_t len, uint8_t *buf, uint16_t prf_id, uint16_t att_idx)

As slaver, send an indication of an attribute’s value.

参数

conidx, : – the index of connection
len, : – the length of attribute’s value
buf, : – attribute’s value
prf_id, : – The id of the profile
att_idx, : – The index of the attribute

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_read_service_data_by_handle_req(uint8_t conidx, uint16_t handle)

As master, read attribute value, the result is reported in the callback registered through bk_ble_register_app_sdp_charac_callback.

参数

conidx, : – the index of connection
handle, : – the handle of attribute value

返回

ERR_SUCCESS: succeed
others: fail

ble_err_t bk_ble_write_service_data_req(uint8_t conidx, uint16_t handle, uint16_t data_len, uint8_t *data)

As master, write attribute value.

参数

conidx, : – the index of connection
handle, : – the handle of attribute value
data, : – value data
data_len, : – the length of attribute value

返回

ERR_SUCCESS: succeed
others: fail

ble_err_t bk_ble_gatt_mtu_change(uint8_t conn_idx)

Exchange MTU.

Attention

must used after connected

参数

conn_idx, : – the index of connection

返回

ERR_SUCCESS: succeed
others: other errors.

ble_err_t bk_ble_gatts_read_response(app_gatts_rsp_t *rsp)

Send a response to a read request.

User example:

uint16_t length = 3;
uint8_t value[3] = {0};
value[0] = 0x12;
value[1] = 0x34;
value[2] = 0x56;

app_gatts_rsp_t rsp;
rsp.token = token; // Token provided by GATT module into the GATT_READ_REQ_IND message.
rsp.con_idx = conn_idx; // Connection index.
rsp.attr_handle = hdl; // Attribute handle.
rsp.status = GAP_ERR_NO_ERROR; // Status of the request by GATT user.
rsp.att_length = length;
rsp.value_length = length;
memcpy(rsp.value, value, length);

bk_ble_gatts_read_response(&rsp);

Attention

The role of GATT is server.

参数

rsp – : response data.

返回

ERR_SUCCESS: succeed
others: fail

ble_err_t bk_ble_gatts_app_unregister(uint16_t service_handle)

Unregister with GATT Server.

Attention

The service_handle is any handle between start_handle and end_handle of this unregister with GATT Server.
The role of GATT is server.

参数

service_handle – : the service_handle of GATT Server access handle

返回

ERR_SUCCESS: succeed
others: fail

ble_err_t bk_ble_gatts_remove_service(uint16_t start_handle)

Remove a service.

Attention

The role of GATT is server.

参数

start_handle – : attribute start_handle of the service to remove

返回

ERR_SUCCESS: succeed
others: fail

ble_err_t bk_ble_gatts_set_attr_value(uint16_t attr_handle, uint16_t length, uint8_t *value)

Set the attribute value by the application.

Attention

The attr_handle corresponding attribute UUID cannot be an attribute declaration.
The role of GATT is server.

参数

attr_handle – : the attr_handle which to be set
length, : – the value length
value, : – the pointer to the attribute value

返回

ERR_SUCCESS: succeed
others: fail

ble_err_t bk_ble_gatts_get_attr_value(uint16_t attr_handle, uint16_t *length, uint8_t **value)

Retrieve attribute value.

Attention

The role of GATT is server.

参数

attr_handle – : attribute handle
length, : – the pointer to the attribute value length
value, : – the pointer to attribute value payload, the value cannot be modified by user

返回

ERR_SUCCESS: succeed
others: fail

ble_err_t bk_ble_gatts_send_service_change_indication(uint16_t start_handle, uint16_t end_handle)

Send service change indication.

Attention

The role of GATT is server.

参数

start_handle – : Service changed start handle
end_handle, : – Service changed end handle

返回

ERR_SUCCESS: succeed
others: fail

ble_err_t bk_ble_gattc_read_by_type(uint8_t conn_idx, uint16_t start_handle, uint16_t end_handle, uint8_t uuid_type, uint8_t *uuid)

Read a service’s characteristics of the given characteristic UUID.

Attention

The input of uuid is little endian.
The attribute characteristics property to uuid supports the read property.
The role of GATT is client.

参数

conn_idx – : the index of connection
start_handle, : – Service changed start handle
end_handle, : – Service changed end handle
uuid_type, : – the uuid type
uuid, : – the uuid of attribute which will be read

返回

ERR_SUCCESS: succeed
others: fail

ble_err_t bk_ble_gattc_read_multiple(uint8_t conn_idx, app_gattc_multi_t *read_multi)

Read multiple characteristic or characteristic descriptors.

User example:

app_gattc_multi_t read_multi;
gatt_att_t atts[2];
read_multi.nb_att = 2;
atts[0].length = 3;
atts[0].hdl = 0x1b;
atts[1].length = 3;
atts[1].hdl = 0x1e;
read_multi.p_atts = atts;
bk_ble_gattc_read_multiple(conn_idx, &read_multi);

Attention

The role of GATT is client.

参数

conn_idx – : the index of connection
read_multi – : pointer to the read multiple parameter

返回

ERR_SUCCESS: succeed
others: fail

ble_err_t bk_ble_gattc_register_for_notify(uint8_t conidx, uint16_t handle)

Register for notification of a service.

Attention

The input of handle supports the notify property.
The role of GATT is client.

参数

conn_idx – : the index of connection
handle, : – GATT client characteristic configuration descriptor handle

返回

ERR_SUCCESS: succeed
others: fail

ble_err_t bk_ble_gattc_register_for_indicate(uint8_t conidx, uint16_t handle)

Register for indication of a service.

Attention

The input of handle supports the indicate property.
The role of GATT is client.

参数

conn_idx – : the index of connection
handle, : – GATT client characteristic configuration descriptor handle

返回

ERR_SUCCESS: succeed
others: fail

ble_err_t bk_ble_gattc_unregister_for_notify_or_indicate(uint8_t conidx, uint16_t handle)

Unregister for notification or indication of a service.

Attention

The input of handle supports the notify or indicate property.
The role of GATT is client.

参数

conn_idx – : the index of connection
handle, : – GATT client characteristic configuration descriptor handle

返回

ERR_SUCCESS: succeed
others: fail