ble_host

功能支持

ble_host组件主要支持如下功能：

• Generic Access Profile(GAP)角色支持

• Peripheral&Central

• Observer&Broadcaster

• Generic Attribute Profile(GATT)连接支持

• GATT client

• GATT server

• Security Manager(SM)支持

• Legacy Pairing

• 多安全等级设定Security Level 1, 2, 3, 4

• 安全连接Security Connection

• LE Privacy（RPA地址生成）

• HCI接口支持

• 标准HCI接口，支持host-only，host通过HCI硬件接口（以UART为主）和controller对接

• 虚拟HCI接口，支持host+controller，适合SoC的硬件平台

版权说明

目录结构

|-- ble_profiles             #BLE服务
|-- bt_crypto                #BLE安全
|-- bt_defconfig             #BLE配置项
|-- bt_host                  #BLE Host核心代码
|-- bt_preconfig             #BLE预配置项
|-- bt_shell                 #BLE控制台命令
|-- include                  #头文件
|-- package.yaml             #makefile
|-- README.md                #README文档
|-- SConscript
|-- script

依赖组件

• osal_aos

API列表

API详情

ble_stack_init

BLE模块初始化。函数原型

int ble_stack_init(init_param_t *param)

输入参数

返回参数0：成功， 其他值：失败。

ble_stack_event_register

注册BLE协议栈事件回调函数。注意：入参不能是一个局部变量。函数原型

int ble_stack_event_register(ble_event_cb_t *callback)

输入参数

返回参数0：成功， 其他值：失败。

ble_stack_adv_start

打开BLE广播功能。函数原型

int ble_stack_adv_start(adv_param_t *param)

输入参数

返回参数0：成功， 其他值：失败。

ble_stack_adv_stop

关闭BLE广播功能。函数原型

int ble_stack_adv_stop()

输入参数

返回参数0：成功， 其他值：失败。

ble_stack_scan_start

打开BLE扫描功能。函数原型

int ble_stack_scan_start(const scan_param_t *param)

输入参数

返回参数0：成功， 其他值：失败。

ble_stack_scan_stop

关闭BLE扫描功能。异步事件，扫描结果在注册的事件回调函数中返回，返回事件EVENT_GAP_DEV_FIND函数原型

int ble_stack_scan_stop()

输入参数

返回值0：成功， 其他值：失败。

ble_stack_gatt_mtu_get

获取一个连接的当前MTU大小函数原型

int ble_stack_gatt_mtu_get(int16_t conn_handle)

输入参数

返回值23-65535: MTU大小

ble_stack_gatt_registe_service

注册一个GATT服务函数原型

int ble_stack_gatt_registe_service(gatt_service *s, gatt_attr_t attrs[], uint16_t attr_num)

输入参数

返回值0：成功， 其他值：失败。

ble_stack_gatt_notificate

GATT服务某个属性值上报，此上报方式无需GATT Client回复函数原型

int ble_stack_gatt_notificate(int16_t conn_handle, uint16_t char_handle, const uint8_t *data, uint16_t len)

输入参数

返回值0：成功， 其他值：失败。

ble_stack_gatt_indicate

GATT服务某个属性值上报，此上报方式GATT Client回复confirm。函数原型

int ble_stack_gatt_indicate(int16_t conn_handle, int16_t char_handle, const uint8_t *data, uint16_t len)

输入参数

返回值0：成功， 其他值：失败。

ble_stack_gatt_mtu_exchange

GATT Client功能，确保配置项CONFIG_BT_GATT_CLIENT配置。GATT协商MTU大小，协商大小由配置项CONFIG_BT_L2CAP_RX_MTU与CONFIG_BT_L2CAP_TX_MTU的最小值以及对端设备的回复决定。异步事件，执行结果在注册的事件回调函数中返回，返回事件EVENT_GATT_MTU_EXCHANGE函数原型

int ble_stack_gatt_mtu_exchange(int16_t conn_handle)

输入参数

返回值0：成功， 其他值：失败。

ble_stack_gatt_discovery

GATT Client功能，确保配置项CONFIG_BT_GATT_CLIENT配置。GATT服务或者属性项发现。异步事件，执行结果在注册的事件回调函数中返回，返回事件根据入参不同而不同

函数原型

int ble_stack_gatt_discovery(int16_t conn_handle,
                             gatt_discovery_type_en type,
                             uuid_t *uuid,
                             uint16_t start_handle,
                             uint16_t end_handle)

输入参数

返回值0：成功， 其他值：失败。

ble_stack_gatt_read

GATT Client功能，确保配置项CONFIG_BT_GATT_CLIENT配置。GATT读取某个属性项的属性值异步事件，执行结果在注册的事件回调函数中返回，返回事件EVENT_GATT_CHAR_READ_CB函数原型

int ble_stack_gatt_read(int16_t conn_handle, uint16_t attr_handle, uint16_t offset)

输入参数

返回值0：成功， 其他值：失败。

ble_stack_gatt_read_multiple

GATT Client功能，确保配置项CONFIG_BT_GATT_CLIENT配置。GATT读取多个属性项的属性值异步事件，执行结果在注册的事件回调函数中返回，返回事件EVENT_GATT_CHAR_READ_CB函数原型

int ble_stack_gatt_read_multiple(int16_t conn_handle, uint16_t attr_count, uint16_t attr_handle[])

输入参数

返回值0：成功， 其他值：失败。

ble_stack_gatt_write

GATT Client功能，确保配置项CONFIG_BT_GATT_CLIENT配置。GATT写入某个属性项的属性值异步事件，执行结果在注册的事件回调函数中返回，返回事件EVENT_GATT_CHAR_WRITE_CB函数原型

int ble_stack_gatt_write(int16_t conn_handle, uint16_t attr_handle, uint8_t *data, uint16_t len, uint16_t offset, gatt_write_en type)

输入参数

返回值0：成功， 其他值：失败。

ble_stack_gatt_read_multiple

GATT Client功能，确保配置项CONFIG_BT_GATT_CLIENT配置。此函数用于GATT读取多个属性项的属性值。异步事件，执行结果在注册的事件回调函数中返回，返回事件EVENT_GATT_CHAR_READ_CB函数原型

int ble_stack_gatt_read_multiple(int16_t conn_handle, uint16_t attr_count, uint16_t attr_handle[])

输入参数

返回值0：成功， 其他值：失败。

ble_stack_connect

BLE连接功能，确保配置项CONFIG_BT_CONN配置。此函数用于BLE连接某个设备。异步事件，执行结果在注册的事件回调函数中返回，返回事件EVENT_GATT_CONN_CHANGE函数原型

int ble_stack_connect(dev_addr_t *peer_addr, conn_param_t *param, uint8_t auto_connect)

输入参数

返回值0：成功， 其他值：失败。

ble_stack_disconnect

BLE连接功能，确保配置项CONFIG_BT_CONN配置。此函数用于BLE断开某个设备的连接。异步事件，执行结果在注册的事件回调函数中返回，返回事件EVENT_GATT_CONN_CHANGE函数原型

int ble_stack_disconnect(int16_t conn_handle)

输入参数

返回值0：成功， 其他值：失败。

ble_stack_connect_param_update

BLE连接功能，确保配置项CONFIG_BT_CONN配置。此函数用于BLE修改某个连接的连接参数。异步事件，执行结果在注册的事件回调函数中返回，返回事件EVENT_GAP_CONN_PARAM_UPDATE函数原型

int ble_stack_connect_param_update(int16_t conn_handle, conn_param_t *param)

输入参数

返回值0：成功， 其他值：失败。

ble_stack_security

BLE连接功能，确保配置项CONFIG_BT_CONN配置。此函数用于BLE修改某个连接的安全参数。异步事件，执行结果在注册的事件回调函数中返回，返回事件EVENT_GAP_CONN_SECURITY_CHANGE函数原型

int ble_stack_security(int16_t conn_handle, security_en level)

输入参数

返回值0：成功， 其他值：失败。

ble_stack_iocapability_set

BLE SMP配对功能，确保配置项CONFIG_BT_SMP配置。此函数用于设置BLE设备的IO能力，这个设置会在BLE SMP配对被使用。函数原型

int ble_stack_iocapability_set(uint8_t io_cap)

输入参数

返回值0：成功， 其他值：失败。

ble_stack_smp_cancel

BLE SMP配对功能，确保配置项CONFIG_BT_SMP配置。此函数用于取消当前BLE的SMP配对请求。函数原型

int ble_stack_smp_cancel(int16_t conn_handle)

输入参数

返回值0：成功， 其他值：失败。

ble_stack_smp_passkey_entry

BLE SMP配对功能，确保配置项CONFIG_BT_SMP配置。此函数用于SMP Passkey模式下输入当前passkey，当接收到EVENT_SMP_PASSKEY_ENTER后调用。函数原型

int ble_stack_smp_passkey_entry(int16_t conn_handle, uint32_t passkey)

输入参数

返回值0：成功， 其他值：失败。

ble_stack_smp_passkey_confirm

BLE SMP配对功能，确保配置项CONFIG_BT_SMP配置。此函数用于SMP Passkey模式下确认当前的passkey是否正确，当接收到EVENT_SMP_PASSKEY_CONFIRM后调用。函数原型

int ble_stack_smp_passkey_confirm(int16_t conn_handle)

输入参数

返回值0：成功， 其他值：失败。

ble_stack_dev_unpair

BLE SMP配对功能，确保配置项CONFIG_BT_SMP配置。此函数用于解除某台已SMP配对的设备的配对，如果连接存在则断开连接。函数原型

int ble_stack_dev_unpair(dev_addr_t *peer_addr)

输入参数

返回值0：成功， 其他值：失败。

步骤1 创建或打开工程

打开已有工程

如果用于测试的案例工程已存在，可参考《AliOS Things集成开发环境使用说明之打开工程》打开已有工程。

创建新的工程

组件的示例代码可以通过编译链接到AliOS Things的任意案例（solution）来运行，这里选择helloworld_demo案例。helloworld_demo案例相关的源代码下载可参考《AliOS Things集成开发环境使用说明之创建工程》。

步骤2 添加组件

案例下载完成后，需要在helloworld_demo组件的package.yaml中添加对组件的依赖：

depends:
  - ble_host: master

步骤3 下载组件

在已安装了的开发环境工具栏中，选择Terminal -> New Terminal启动终端，并且默认工作路径为当前工程的workspace，此时在终端命令行中输入：

aos install ble_host

上述命令执行成功后，组件源码则被下载到了./components/ble_host路径中。

步骤4 添加示例

修改solutions/helloworld_demo/helloworld_demo.c，如下：

头文件修改

#include <aos/ble.h>
#include <atomic.h>
#include <bluetooth/bluetooth.h>
#include <bluetooth/gatt.h>
#include <bluetooth/uuid.h>

代码修改

#define EXAMPLE_BLE_DEV_NAME        "HaaS BLE"
#define DEVICE_ADDR                 {0xE8,0x3B,0xE3,0x88,0xB4,0xC8}

int application_start(int argc, char *argv[])
{
    int count = 0;
    int ret;
    dev_addr_t addr = {DEV_ADDR_LE_RANDOM, DEVICE_ADDR};
    init_param_t init = {
        .dev_name = EXAMPLE_BLE_DEV_NAME,
        .dev_addr = &addr,   //&addr,
        .conn_num_max = 1,
    };

    printf("nano entry here!\r\n");

#if 1
    /* bt stack init */
    ret = ble_stack_init(&init);
    if (ret) {
        printf("error: ble_stack_init!, ret = %x\r\n", ret);
        return -1;
    }
#endif

    while(1) {
        printf("hello world! count %d \r\n", count++);
        aos_msleep(1000);
    };
}

步骤5 编译固件

在示例代码已经添加至组件的配置文件，并且helloworld_demo已添加了对该组件的依赖后，就可以编译helloworld_demo案例来生成固件了，具体编译方法可参考《AliOS Things集成开发环境使用说明之编译固件》。

步骤6 烧录固件

helloworld_demo案例的固件生成后，可参考《AliOS Things集成开发环境使用说明之烧录固件》来烧录固件。

步骤7 打开串口

固件烧录完成后，可以通过串口查看示例的运行结果，打开串口的具体方法可参考《AliOS Things集成开发环境使用说明之查看日志》。

当串口终端打开成功后，可在串口中输入help来查看已添加的测试命令。

步骤8 测试示例

打开串口工具，在串口工具中输入ble，可看到ble的cli命令集。

BLE广播与连接测试

在串口工具中输入ble adv start 020106，可以在串口日志中看到如下打印

adv_type:0;adv_interval_min:160 (*0.625)ms;adv_interval_max:240 (*0.625)ms
Advertising started

此时在手机端打开NRF Connect工具并搜索广播包，可以看到设备。

点击连接，可以看到Generic Access(GAP)和Generic Attribute(GATT)2个服务，点击GAP服务的Device Name的读取按键（下图红色圈中的箭头），可以读取到数值“HaaS BLE”