ble-低功耗蓝牙相关功能

2024-05-14

ble模块用于提供BLE GATT Server （从机）与 Client （主机）功能，基于BLE 4.2协议。

示例：

见github：https://github.com/QuecPython/example_BLE

当前仅EC200U/EC600U/EG915U/EG912U型号支持ble功能。

初始化相关功能

`ble.gattStart`

ble.gattStart()

开启 BLE GATT 功能。

返回值描述：

执行成功返回整型0，失败返回整型-1。

`ble.gattStop`

ble.gattStop()

关闭 BLE GATT 功能。

返回值描述：

执行成功返回整型0，失败返回整型-1。

`ble.getStatus`

ble.getStatus()

获取 BLE 的状态。

返回值描述：

0 - BLE处于停止状态。1 - BLE处于开启状态。-1 - 获取状态失败。

`ble.getPublicAddr`

ble.getPublicAddr()

获取 BLE 协议栈正在使用的公共地址。该接口需要在BLE已经初始化完成并启动成功后才能调用，比如在回调中收到 event_id 为0的事件之后，即 start 成功后，去调用。

返回值描述：

执行成功返回bytearray类型的BLE地址，大小6个byte，失败返回整型-1。

示例：

>>> addr = ble.getPublicAddr()
>>> print(addr)
b'\xdb3\xf5\x1ek\xac'
>>> mac = '{:02x}:{:02x}:{:02x}:{:02x}:{:02x}:{:02x}'.format(addr[5], addr[4], addr[3], addr[2], addr[1], addr[0])
>>> print('mac = [{}]'.format(mac))
mac = [ac:6b:1e:f5:33:db]

如果有出厂设置默认蓝牙MAC地址，那么该接口获取的MAC地址和默认的蓝牙MAC地址是一致的；如果没有设置，那么该接口获取的地址，将是蓝牙启动后随机生成的静态地址，因此在每次重新上电运行蓝牙功能时都不相同。

BLE Server相关功能

`ble.serverInit`

ble.serverInit(user_cb)

初始化 BLE Server 并注册回调函数。

参数描述：

user_cb-回调函数，类型为function。回调函数参数含义：args[0] 固定表示event_id，args[1]固定表示状态，0表示成功，非0表示失败。回调函数的参数个数并不是固定2个，而是根据第一个参数args[0]来决定的，下表中列出了不同事件ID对应的参数个数及说明。

event_id	参数个数	参数说明
0	2	args[0] ：event_id，表示 BT/BLE start args[1] ：status，表示操作的状态，0-成功，非0-失败
1	2	args[0] ：event_id，表示 BT/BLE stop args[1] ：status，表示操作的状态，0-成功，非0-失败
16	4	args[0] ：event_id，表示 BLE connect args[1] ：status，表示操作的状态，0-成功，非0-失败 args[2] ：connect_id args[3] ：addr，BT/BLE address，bytearray类型数据
17	4	args[0] ：event_id，表示 BLE disconnect args[1] ：status，表示操作的状态，0-成功，非0-失败 args[2] ：connect_id， args[3] ：addr，BT/BLE address，bytearray类型数据
18	7	args[0] ：event_id，表示 BLE update connection parameter args[1] ：status，表示操作的状态，0-成功，非0-失败 args[2] ：connect_id args[3] ：max_interval，最大的间隔，间隔：1.25ms，取值范围：6-3200，时间范围：7.5ms\ ~ 4s args[4] ：min_interval，最小的间隔，间隔：1.25ms，取值范围：6-3200，时间范围：7.5ms\ ~ 4s args[5] ：latency，从机忽略连接状态事件的时间。需满足：（1+latecy)max_interval21.25<timeout10 args[6] ：timeout，没有交互，超时断开时间，间隔：10ms，取值范围：10-3200ms，时间范围：100ms ~ 32s
20	4	args[0] ：event_id，表示 BLE connection mtu args[1] ：status，表示操作的状态，0-成功，非0-失败 args[2] ：handle args[3] ：mtu值
21	7	args[0] ：event_id，表示 client写入特征值或描述符通知 args[1] ：status，表示操作的状态，0-成功，非0-失败 args[2] ：data_len，获取数据的长度 args[3] ：data，一个数组，存放获取的数据 args[4] ：attr_handle，属性句柄，整型值 args[5] ：short_uuid，整型值 args[6] ：long_uuid，一个16字节数组，存放长UUID
22	7	args[0] ：event_id，表示client读取特征值或描述符通知 args[1] ：status，表示操作的状态，0-成功，非0-失败 args[2] ：data_len，获取数据的长度 args[3] ：data，一个数组，存放获取的数据 args[4] ：attr_handle，属性句柄，整型值 args[5] ：short_uuid，整型值 args[6] ：long_uuid，一个16字节数组，存放长UUID
25	2	args[0] ：event_id，表示 server发送通知并接收到了发送结束通知 args[1] ：status，表示操作的状态，0-成功，非0-失败
63	2	args[0] ：event_id，表示SMP配对流程完成通知 args[1] ：status，表示操作的状态，0-成功，非0-失败
64	5	args[0] ：event_id，表示SMP配对用户确认通知 args[1] ：status，表示操作的状态，0-成功，非0-失败 args[2] ：connect_id args[3] ：pair_mode，配对模式，整型值。 0 - 配对失败 1 - Legacy Pairing：使用Just Works，不需要输入PIN码 2 - Legacy Pairing：使用Passkey Entry，显示PIN码，不需要输入PIN码 3 - Legacy Pairing：使用Passkey Entry，需要输入PIN码 4 - Legacy Pairing：使用OOB，目前不支持这种方式 5 - Secure Connections Pairing：使用Just Works，不需要输入PIN码 6 - Secure Connections Pairing：使用Numeric Comparison，显示PIN码，不需要输入PIN码 7 - Secure Connections Pairing：使用Passkey Entry，显示PIN码，不需要输入PIN码 8 - Secure Connections Pairing：使用Passkey Entry，需要输入PIN码 9 - Secure Connections Pairing：使用OOB，目前不支持这种方式 args[4] ：pin_code，PIN码，整型值

返回值描述：

执行成功返回整型0，失败返回整型-1。

示例：

def ble_callback(args):
    event_id = args[0]
    status = args[1]
    print('[ble_callback]: event_id={}, status={}'.format(event_id, status))

    if event_id == 0:  # ble start
        if status == 0:
            print('[callback] BLE start success.')
        else:
            print('[callback] BLE start failed.')
    elif event_id == 1:  # ble stop
        if status == 0:
            print('[callback] ble stop successful.')
        else:
            print('[callback] ble stop failed.')
    elif event_id == 16:  # ble connect
        if status == 0:
            print('[callback] ble connect successful.')
            connect_id = args[2]
            addr = args[3] # 这是一个bytearray类型
            addr_str = '{:02x}:{:02x}:{:02x}:{:02x}:{:02x}:{:02x}'.format(addr[0], addr[1], addr[2], addr[3], addr[4], addr[5])
            print('[callback] connect_id = {}, addr = {}'.format(connect_id, addr_str))
        else:
            print('[callback] ble connect failed.')
    elif event_id == 17:  # ble disconnect
        if status == 0:
            print('[callback] ble disconnect successful.')
            connect_id = args[2]
            addr = args[3] # 这是一个bytearray类型
            addr_str = '{:02x}:{:02x}:{:02x}:{:02x}:{:02x}:{:02x}'.format(addr[0], addr[1], addr[2], addr[3], addr[4], addr[5])
            print('[callback] connect_id = {}, addr = {}'.format(connect_id, addr_str))
        else:
            print('[callback] ble disconnect failed.')
            ble.gattStop()
            return
    elif event_id == 18:  # ble update connection parameter
        if status == 0:
            print('[callback] ble update parameter successful.')
            connect_id = args[2]
            max_interval = args[3]
            min_interval = args[4]
            latency = args[5]
            timeout = args[6]
            print('[callback] connect_id={},max_interval={},min_interval={},latency={},timeout={}'.format(connect_id, max_interval, min_interval, latency, timeout))
        else:
            print('[callback] ble update parameter failed.')
            ble.gattStop()
            return
    elif event_id == 20:  # ble connection mtu
        if status == 0:
            print('[callback] ble connect mtu successful.')
            handle = args[2]
            ble_mtu = args[3]
            print('[callback] handle = {:#06x}, ble_mtu = {}'.format(handle, ble_mtu))
        else:
            print('[callback] ble connect mtu failed.')
            ble.gattStop()
            return
    elif event_id == 21:  # server:when ble client write characteristic value or descriptor,server get the notice
        if status == 0:
            print('[callback] ble recv successful.')
            data_len = args[2]
            data = args[3]  # 这是一个bytearray类型
            attr_handle = args[4]
            short_uuid = args[5]
            long_uuid = args[6]  # 这是一个bytearray类型
            print('len={}, data:{}'.format(data_len, data))
            print('attr_handle = {:#06x}'.format(attr_handle))
            print('short uuid = {:#06x}'.format(short_uuid))
            print('long uuid = {}'.format(long_uuid))
        else:
            print('[callback] ble recv failed.')
            ble.gattStop()
            return
    elif event_id == 22:  # server:when ble client read characteristic value or descriptor,server get the notice
        if status == 0:
            print('[callback] ble recv read successful.')
            data_len = args[2]
            data = args[3]  # 这是一个bytearray类型
            attr_handle = args[4]
            short_uuid = args[5]
            long_uuid = args[6]  # 这是一个bytearray类型
            print('len={}, data:{}'.format(data_len, data))
            print('attr_handle = {:#06x}'.format(attr_handle))
            print('short uuid = {:#06x}'.format(short_uuid))
            print('long uuid = {}'.format(long_uuid))
        else:
            print('[callback] ble recv read failed.')
            ble.gattStop()
            return
    elif event_id == 25:  # server send notification,and recieve send end notice
        if status == 0:
            print('[callback] ble send data successful.')
        else:
            print('[callback] ble send data failed.')
    else:
        print('unknown event id.')

ble.serverInit(ble_callback)

`ble.serverRelease`

ble.serverRelease()

BLE Server 资源释放。

返回值描述：

执行成功返回整型0，失败返回整型-1。

`ble.setLocalName`

ble.setLocalName(code, name)

设置 BLE 名称。

参数描述：

code-编码模式，类型为整型。0 - UTF8，1 - GBK。
name-编码模式，类型为string。BLE 名称，名称最长不能超过29个字节。

返回值描述：

执行成功返回整型0，失败返回整型-1。

示例：

>>> ble.setLocalName(0, 'QuecPython-BLE')
0

对于BLE，设备在广播时，如果希望手机扫描app扫描时，能看到广播设备的名称，是需要在广播数据中包含蓝牙名称的，或者在扫描回复数据中包含设备名称。

`ble.setAdvParam`

ble.setAdvParam(min_adv,max_adv,adv_type,addr_type,channel,filter_policy,discov_mode,no_br_edr,enable_adv)

设置广播参数。

参数描述：

min_adv-最小广播间隔，范围0x0020-0x4000。计算方式：时间间隔 = min_adv * 0.625，单位ms。类型为整型。
max_adv-最大广播间隔，范围0x0020-0x4000。计算方式：时间间隔 = max_adv * 0.625，单位ms。类型为整型。
adv_type-广播类型，0 - 可连接的非定向广播，默认选择，1 - 可连接高占空比的定向广播，2 - 可扫描的非定向广播，3 - 不可连接的非定向广播，4 - 可连接低占空比的定向广播。类型为整型。
addr_type-本地地址类型，0 - 公共地址，1 - 随机地址。类型为整型。
channel-广播通道，1 - 37信道，2 - 38信道，4 - 39信道，7 - 上述3个通道都选择，默认该选项。类型为整型。
filter_policy-广播过滤策略，0 - 处理所有设备的扫描和连接请求，1 - 处理所有设备的连接请求和只处理白名单设备的扫描请求（暂不支持），2 - 处理所有设备的扫描请求和只处理白名单设备的连接请求（暂不支持），3 - 只处理白名单设备的连接和扫描请求（暂不支持）。类型为整型。
discov_mode-发现模式，GAP协议使用，1 - 有限可发现模式，2 - 一般可发现模式。类型为整型。
no_br_edr-不用BR/EDR，1-不用BR/EDR，默认为该值，0-使用BR/EDR。类型为整型。
enable_adv-使能广播，1-使能，默认为该值，0-不使能。类型为整型。

返回值描述：

执行成功返回整型0，失败返回整型-1。

示例：

def ble_gatt_set_param():
    min_adv = 0x300
    max_adv = 0x320
    adv_type = 0  # 可连接的非定向广播,默认选择
    addr_type = 0  # 公共地址
    channel = 0x07
    filter_strategy = 0  # 处理所有设备的扫描和连接请求
    discov_mode = 2
    no_br_edr = 1
    enable_adv = 1
    ret = ble.setAdvParam(min_adv, max_adv, adv_type, addr_type, channel, filter_strategy, discov_mode, no_br_edr, enable_adv)
    if ret != 0:
        print('ble_gatt_set_param failed.')
        return -1
    print('ble_gatt_set_param success.')
    return 0

`ble.setAdvData`

ble.setAdvData(data)

设置广播数据内容。

参数描述：

data-广播数据，最长不超过31个字节，类型为bytearray。广播数据的内容，采用 length+type+data 的格式。一条广播数据中可以包含多个这种格式数据的组合，如下示例中包含了两个数据组合，第一个是 "0x02, 0x01, 0x05"，0x02表示后面有两个数据，分别是0x01和0x05，0x01即type，0x05表示具体数据；第二个是ble名称数据组合， length为ble名称长度加1、type为0x09，具体数据为name对应的具体编码值。关于type具体值代表的含义，请参考蓝牙协议官方标准文档。

返回值描述：

执行成功返回整型0，失败返回整型-1。

示例：

def ble_gatt_set_data():
    adv_data = [0x02, 0x01, 0x05]
    ble_name = "Quectel_ble"
    length = len(ble_name) + 1
    adv_data.append(length)
    adv_data.append(0x09)
    name_encode = ble_name.encode('UTF-8')
    for i in range(0, len(name_encode)):
        adv_data.append(name_encode[i])
    print('set adv_data:{}'.format(adv_data))
    data = bytearray(adv_data)
    ret = ble.setAdvData(data)
    if ret != 0:
        print('ble_gatt_set_data failed.')
        return -1
    print('ble_gatt_set_data success.')
    return 0

`ble.setAdvRspData`

ble.setAdvRspData(data)

设置扫描回复数据。

参数描述：

data-扫描回复数据，最长不超过31个字节，类型为bytearray。格式和上面设置广播数据内容接口一致。

返回值描述：

执行成功返回整型0，失败返回整型-1。

示例：

def ble_gatt_set_rsp_data():
    adv_data = []
    ble_name = "Quectel_ble"
    length = len(ble_name) + 1
    adv_data.append(length)
    adv_data.append(0x09)
    name_encode = ble_name.encode('UTF-8')
    for i in range(0, len(name_encode)):
        adv_data.append(name_encode[i])
    print('set adv_rsp_data:{}'.format(adv_data))
    data = bytearray(adv_data)
    ret = ble.setAdvRspData(data)
    if ret != 0:
        print('ble_gatt_set_rsp_data failed.')
        return -1
    print('ble_gatt_set_rsp_data success.')
    return 0

当client设备扫描方式为积极扫描时，设置扫描回复数据才有意义。

`ble.addService`

ble.addService(primary, server_id, uuid_type, uuid_s, uuid_l)

增加一个服务。

参数描述：

primary-服务类型，1表示主要服务，其他值表示次要服务，类型为整型。
server_id-服务ID，用来确定某一个服务，类型为整型。
uuid_type-uuid类型，0 - 长UUID，128bit；1 - 短UUID，16bit。类型为整型。
uuid_s-短UUID，2个字节（16bit），类型为整型，当uuid_type为0时，该值给0。
uuid_l-长UUID，16个字节（128bit），类型为bytearray，当uuid_type为1时，该值填 bytearray([0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00])。

返回值描述：

执行成功返回整型0，失败返回整型-1。

示例：

def ble_gatt_add_service():
    primary = 1
    server_id = 0x01
    uuid_type = 1  # 短UUID
    uuid_s = 0x180F
    uuid_l = bytearray([0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00])
    ret = ble.addService(primary, server_id, uuid_type, uuid_s, uuid_l)
    if ret != 0:
        print('ble_gatt_add_service failed.')
        return -1
    print('ble_gatt_add_service success.')
    return 0

`ble.addChara`

ble.addChara(server_id, chara_id, chara_prop, uuid_type, uuid_s, uuid_l)

在服务里增加一个特征。

参数描述：

server_id-服务ID，用来确定某一个服务，类型为整型。
chara_id-特征ID，类型为整型。
chara_prop-特征的属性，十六进制数，可通过“或运算”同时指定多个属性，值具体含义如下表，类型为整型。

值	含义
0x01	广播
0x02	可读
0x04	0x04 - 可写且不需要链路层应答
0x08	可写
0x10	通知
0x20	指示
0x40	认证签名写
0x80	扩展属性

uuid_type-uuid类型，0 - 长UUID，128bit；1 - 短UUID，16bit。类型为整型。
uuid_s-短UUID，2个字节（16bit），类型为整型，当uuid_type为0时，该值给0。
uuid_l-长UUID，16个字节（128bit），类型为bytearray，当uuid_type为1时，该值填 bytearray([0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00])。

返回值描述：

执行成功返回整型0，失败返回整型-1。

示例：

def ble_gatt_add_characteristic():
    server_id = 0x01
    chara_id = 0x01
    chara_prop = 0x02 | 0x10 | 0x20  # 0x02-可读 0x10-通知 0x20-指示
    uuid_type = 1  # 短UUID
    uuid_s = 0x2A19
    uuid_l = bytearray([0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00])
    ret = ble.addChara(server_id, chara_id, chara_prop, uuid_type, uuid_s, uuid_l)
    if ret != 0:
        print('ble_gatt_add_characteristic failed.')
        return -1
    print('ble_gatt_add_characteristic success.')
    return 0

`ble.addCharaValue`

ble.addCharaValue(server_id, chara_id, permission, uuid_type, uuid_s, uuid_l, value)

在特征里增加一个特征值。

参数描述：

server_id-服务ID，用来确定某一个服务，类型为整型。
chara_id-特征ID，类型为整型。
permission-特征值的权限，2个字节，十六进制数，可通过“或运算”同时指定多个属性，值具体含义如下表，类型为整型。

值	含义
0x0001	可读权限
0x0002	可写权限
0x0004	读需要认证
0x0008	读需要授权
0x0010	读需要加密
0x0020	读需要授权认证
0x0040	写需要认证
0x0080	写需要授权
0x0100	写需要加密
0x0200	写需要授权认证

uuid_type-uuid类型，0 - 长UUID，128bit；1 - 短UUID，16bit。类型为整型。
uuid_s-短UUID，2个字节（16bit），类型为整型，当uuid_type为0时，该值给0。
uuid_l-长UUID，16个字节（128bit），类型为bytearray，当uuid_type为1时，该值填 bytearray([0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00])。
value-特征值数据。类型为bytearray。

返回值描述：

执行成功返回整型0，失败返回整型-1。

示例：

def ble_gatt_add_characteristic_value():
    data = []
    server_id = 0x01
    chara_id = 0x01
    permission = 0x0001 | 0x0002
    uuid_type = 1  # 短UUID
    uuid_s = 0x2A19
    uuid_l = bytearray([0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00])
    for i in range(0, 244):
        data.append(0x00)
    value = bytearray(data)
    ret = ble.addCharaValue(server_id, chara_id, permission, uuid_type, uuid_s, uuid_l, value)
    if ret != 0:
        print('ble_gatt_add_characteristic_value failed.')
        return -1
    print('ble_gatt_add_characteristic_value success.')
    return 0

`ble.changeCharaValue`

ble.changeCharaValue(server_id, chara_id, value)

修改特征值。

参数描述：

server_id-服务ID，用来确定某一个服务，类型为整型。
chara_id-特征ID，类型为整型。
value-特征值数据。类型为bytearray。

返回值描述：

执行成功返回整型0，失败返回整型-1。

`ble.addCharaDesc`

ble.addCharaDesc(server_id, chara_id, permission, uuid_type, uuid_s, uuid_l, value)

在特征里增加一个特征描述，注意特征描述和特征值同属与一个特征。

参数描述：

server_id-服务ID，用来确定某一个服务，类型为整型。
chara_id-特征ID，类型为整型。
permission-特征值的权限，2个字节，十六进制数，可通过“或运算”同时指定多个属性，值具体含义如下表，类型为整型。

值	含义
0x0001	可读权限
0x0002	可写权限
0x0004	读需要认证
0x0008	读需要授权
0x0010	读需要加密
0x0020	读需要授权认证
0x0040	写需要认证
0x0080	写需要授权
0x0100	写需要加密
0x0200	写需要授权认证

uuid_type-uuid类型，0 - 长UUID，128bit；1 - 短UUID，16bit。类型为整型。
uuid_s-短UUID，2个字节（16bit），类型为整型，当uuid_type为0时，该值给0。
uuid_l-长UUID，16个字节（128bit），类型为bytearray，当uuid_type为1时，该值填 bytearray([0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00])。
value-特征描述数据。类型为bytearray。

返回值描述：

执行成功返回整型0，失败返回整型-1。

示例：

def ble_gatt_add_characteristic_desc():
    data = [0x00, 0x00]
    server_id = 0x01
    chara_id = 0x01
    permission = 0x0001 | 0x0002
    uuid_type = 1  # 短UUID
    uuid_s = 0x2902
    uuid_l = bytearray([0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00])
    value = bytearray(data)
    ret = ble.addCharaDesc(server_id, chara_id, permission, uuid_type, uuid_s, uuid_l, value)
    if ret != 0:
        print('ble_gatt_add_characteristic_desc failed.')
        return -1
    print('ble_gatt_add_characteristic_desc success.')
    return 0

`ble.addOrClearService`

ble.addOrClearService(option, mode)

增加已添加的所有服务信息到模块，或者删除模块中已增加的所有服务信息。

参数描述：

option-操作类型，类型为整型。0 - 删除服务，1 - 增加服务。
mode-是否保留系统默认服务，类型为整型。 0 - 删除系统默认的GAP和GATT服务，1 - 保留系统默认的GAP和GATT服务。

返回值描述：

执行成功返回整型0，失败返回整型-1。

`ble.sendNotification`

ble.sendNotification(connect_id, attr_handle, value)

发送通知。

参数描述：

connect_id-连接ID，类型为整型。
attr_handle-属性句柄，类型为整型。
value-要发送的数据，发送数据长度不要超过MTU，类型为bytearray。

返回值描述：

执行成功返回整型0，失败返回整型-1。

`ble.sendIndication`

ble.sendIndication(connect_id, attr_handle, value)

发送指示。

参数描述：

connect_id-连接ID，类型为整型。
attr_handle-属性句柄，类型为整型。
value-要发送的数据，发送数据长度不要超过MTU，类型为bytearray。

返回值描述：

执行成功返回整型0，失败返回整型-1。

`ble.advStart`

ble.advStart()

开启广播。

返回值描述：

执行成功返回整型0，失败返回整型-1。

`ble.advStop`

ble.advStop()

停止广播。

返回值描述：

执行成功返回整型0，失败返回整型-1。

BLE Client相关功能

`ble.clientInit`

ble.clientInit(user_cb)

初始化 BLE Client 并注册回调函数。

参数描述：

user_cb-回调函数，类型为function。回调函数参数含义：args[0] 固定表示event_id，args[1] 固定表示状态，0表示成功，非0表示失败。回调函数的参数个数并不是固定2个，而是根据第一个参数args[0]来决定的，下表中列出了不同事件ID对应的参数个数及说明。

event_id	参数个数	参数说明
0	2	args[0] ：event_id，表示 BT/BLE start args[1] ：status，表示操作的状态，0-成功，非0-失败
1	2	args[0] ：event_id，表示 BT/BLE stop args[1] ：status，表示操作的状态，0-成功，非0-失败
16	4	args[0] ：event_id，表示 BLE connect args[1] ：status，表示操作的状态，0-成功，非0-失败 args[2] ：connect_id args[3] ：addr，BT/BLE address，bytearray类型数据
17	4	args[0] ：event_id，表示 BLE disconnect args[1] ：status，表示操作的状态，0-成功，非0-失败 args[2] ：connect_id， args[3] ：addr，BT/BLE address，bytearray类型数据
18	7	args[0] ：event_id，表示 BLE update connection parameter args[1] ：status，表示操作的状态，0-成功，非0-失败 args[2] ：connect_id args[3] ：max_interval，最大的间隔，间隔：1.25ms，取值范围：6-3200，时间范围：7.5ms ~ 4s args[4] ：min_interval，最小的间隔，间隔：1.25ms，取值范围：6-3200，时间范围：7.5ms ~ 4s args[5] ：latency，从机忽略连接状态事件的时间。需满足：（1+latecy)max_interval21.25<timeout10 args[6] ：timeout，没有交互，超时断开时间，间隔：10ms，取值范围：10-3200，时间范围：100ms ~ 32s
19	9	args[0] ：event_id，表示 BLE scan report args[1] ：status，表示操作的状态，0-成功，非0-失败 args[2] ：event_type args[3] ：扫描到的设备名称 args[4] ：设备地址类型 args[5] ：设备地址，bytearray类型数据 args[6] ：rssi，信号强度 args[7] ：data_len，扫描的原始数据长度 args[8] ：data，扫描的原始数据
20	4	args[0] ：event_id，表示 BLE connection mtu args[1] ：status，表示操作的状态，0-成功，非0-失败 args[2] ：handle args[3] ：mtu值
23	4	args[0] ：event_id，表示 client接收到通知 args[1] ：status，表示操作的状态，0-成功，非0-失败 args[2] ：data_len，数据长度 args[3] ：data，包含句柄等数据的原始数据，数据格式及解析见最后的综合示例程序
24	4	args[0] ：event_id，表示 client recieve indication，即接收指示 args[1] ：status，表示操作的状态，0-成功，非0-失败 args[2] ：data_len，数据长度 args[3] ：data，包含indication的原始数据，数据格式及解析见最后的综合示例程序
26	2	args[0] ：event_id，表示开始查找服务 args[1] ：status，表示操作的状态，0-成功，非0-失败
27	5	args[0] ：event_id，表示查找到服务 args[1] ：status，表示操作的状态，0-成功，非0-失败 args[2] ：start_handle，表示service的开始句柄 args[3] ：end_handle，表示service的结束句柄 args[4] ：UUID，表示service的UUID（短UUID）
28	4	args[0] ：event_id，表示查找到服务特征 args[1] ：status，表示操作的状态，0-成功，非0-失败 args[2] ：data_len，数据长度 args[3] ：data，包含句柄、属性、UUID等数据的原始数据，数据格式及解析见最后的综合示例程序
29	4	args[0] ：event_id，表示查找到特征描述 args[1] ：status，表示操作的状态，0-成功，非0-失败 args[2] ：data_len，数据长度 args[3] ：data，包含句柄、UUID等数据的原始数据，数据格式及解析见最后的综合示例程序
30	2	args[0] ：event_id，表示写入特征值并需要server端确认 args[1] ：status，表示操作的状态，0-成功，非0-失败
31	2	args[0] ：event_id，表示写入特征值，无需server端确认 args[1] ：status，表示操作的状态，0-成功，非0-失败
32	4	args[0] ：event_id，表示通过句柄来读取特征值 args[1] ：status，表示操作的状态，0-成功，非0-失败 args[2] ：data_len，数据长度 args[3] ：data，原始数据
33	4	args[0] ：event_id，表示通过UUID来读取特征值 args[1] ：status，表示操作的状态，0-成功，非0-失败 args[2] ：data_len，数据长度 args[3] ：data，原始数据
34	4	args[0] ：event_id，表示读取多个特征值 args[1] ：status，表示操作的状态，0-成功，非0-失败 args[2] ：data_len，数据长度 args[3] ：data，原始数据
35	2	args[0] ：event_id，表示写入特征描述，需server端确认 args[1] ：status，表示操作的状态，0-成功，非0-失败
36	4	args[0] ：event_id，表示读特征描述 args[1] ：status，表示操作的状态，0-成功，非0-失败 args[2] ：data_len，数据长度 args[3] ：data，原始数据
37	3	args[0] ：event_id，表示属性错误 args[1] ：status，表示操作的状态，0-成功，非0-失败 args[2] ：errcode，错误码
63	2	args[0] ：event_id，表示SMP配对流程完成通知 args[1] ：status，表示操作的状态，0-成功，非0-失败
64	5	args[0] ：event_id，表示SMP配对用户确认通知 args[1] ：status，表示操作的状态，0-成功，非0-失败 args[2] ：connect_id args[3] ：pair_mode，配对模式，整型值。 0 - 配对失败 1 - Legacy Pairing：使用Just Works，不需要输入PIN码 2 - Legacy Pairing：使用Passkey Entry，显示PIN码，不需要输入PIN码 3 - Legacy Pairing：使用Passkey Entry，需要输入PIN码 4 - Legacy Pairing：使用OOB，目前不支持这种方式 5 - Secure Connections Pairing：使用Just Works，不需要输入PIN码 6 - Secure Connections Pairing：使用Numeric Comparison，显示PIN码，不需要输入PIN码 7 - Secure Connections Pairing：使用Passkey Entry，显示PIN码，不需要输入PIN码 8 - Secure Connections Pairing：使用Passkey Entry，需要输入PIN码 9 - Secure Connections Pairing：使用OOB，目前不支持这种方式 args[4] ：pin_code，PIN码，整型值

返回值描述：

执行成功返回整型0，失败返回整型-1。

`ble.clientRelease`

ble.clientRelease()

BLE Client 资源释放。

返回值描述：

执行成功返回整型0，失败返回整型-1。

`ble.setScanParam`

ble.setScanParam(scan_mode, interval, scan_window, filter_policy, addr_type)

设置扫描参数。

参数描述：

scan_mode-扫描模式，类型为整型。扫描模式，默认为积极扫描。0 - 消极扫描，1 - 积极扫描。
interval-扫描间隔，类型为整型。范围0x0004-0x4000，时间间隔 = interval * 0.625，单位ms。
scan_window-一次扫描的时间，类型为整型。范围0x0004-0x4000，扫描时间 = scan_window* 0.625，单位ms。
filter_policy-扫描过滤策略，类型为整型。默认为0。0 - 过滤目标地址不是本设备的定向广播包，1 - 过滤目标地址不是本设备的定向广播包及白名单之外的广播包，2 -过滤目标地址不是本设备且没使用Resolvable private address的定向广播包，3 - 过滤目标地址不是本设备且没使用Resolvable private address的定向广播包及白名单之外的广播包。
addr_type-本地地址类型，类型为整型。0 - 公共地址，1 - 随机地址。

返回值描述：

执行成功返回整型0，失败返回整型-1。

扫描时间 scan_window 不能大于扫描间隔 interval 。如果两者相等，则表示连续不停的扫描。此时 BLE 的 Controller 会连续运行扫描，占满系统资源而导致无法执行其他任务。所以不允许设置连续扫描。并且不建议将时间设置的太短，扫描越频繁则功耗越高。

`ble.scanStart`

ble.scanStart()

开始扫描。

返回值描述：

执行成功返回整型0，失败返回整型-1。

`ble.scanStop`

ble.scanStop()

停止扫描。

返回值描述：

执行成功返回整型0，失败返回整型-1。

`ble.setScanFilter`

ble.setScanFilter(act)

打开或者关闭扫描过滤。如果打开，那么扫描设备的广播数据时，同一个设备的广播数据只会上报一次；如果关闭，则同一个设备的所有的广播数据都会上报。

参数描述：

act-扫描过滤开关，类型为整型。0 - 关闭扫描过滤功能，1 - 打开扫描过滤功能。默认打开过滤功能。

返回值描述：

执行成功返回整型0，失败返回整型-1。

`ble.connect`

ble.connect(addr_type, addr)

根据指定的设备地址去连接设备。

参数描述：

addr_type-地址类型，类型为整型。0 - 公共地址，1 - 随机地址。
addr-BLE地址，类型为bytearray，大小为6字节。

返回值描述：

执行成功返回整型0，失败返回整型-1。

`ble.cancelConnect`

ble.cancelConnect(addr)

取消正在建立的连接。

参数描述：

addr-BLE地址，类型为bytearray，大小为6字节。

返回值描述：

执行成功返回整型0，失败返回整型-1。

`ble.disconnect`

ble.disconnect(connect_id)

断开已建立的连接。

参数描述：

connect_id-连接ID，建立连接时得到的连接ID，类型为整型。

返回值描述：

执行成功返回整型0，失败返回整型-1。

`ble.discoverAllService`

ble.discoverAllService(connect_id)

扫描所有的服务。

参数描述：

connect_id-连接ID，建立连接时得到的连接ID，类型为整型。

返回值描述：

执行成功返回整型0，失败返回整型-1。

`ble.discoverByUUID`

ble.discoverByUUID(connect_id, uuid_type, uuid_s, uuid_l)

扫描指定UUID的服务。

参数描述：

connect_id-连接ID，建立连接时得到的连接ID，类型为整型。
uuid_type-uuid类型，0 - 长UUID，128bit；1 - 短UUID，16bit。类型为整型。
uuid_s-短UUID，2个字节（16bit），类型为整型，当uuid_type为0时，该值给0。
uuid_l-长UUID，16个字节（128bit），类型为bytearray，当uuid_type为1时，该值填 bytearray([0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00])。

返回值描述：

执行成功返回整型0，失败返回整型-1。

`ble.discoverAllIncludes`

ble.discoverAllIncludes(connect_id, start_handle, end_handle)

扫描所有的引用，start_handle和end_handle要属于同一个服务。

参数描述：

connect_id-连接ID，建立连接时得到的连接ID，类型为整型。
start_handle-开始句柄，从这个句柄开始寻找引用，类型为整型。
end_handle-结束句柄，从这个句柄结束寻找引用，类型为整型。

返回值描述：

执行成功返回整型0，失败返回整型-1。

`ble.discoverAllChara`

ble.discoverAllChara(connect_id, start_handle, end_handle)

扫描所有的特征，start_handle和end_handle要属于同一个服务。

参数描述：

connect_id-连接ID，建立连接时得到的连接ID，类型为整型。
start_handle-开始句柄，从这个句柄开始寻找特征，类型为整型。
end_handle-结束句柄，从这个句柄结束寻找特征，类型为整型。

返回值描述：

执行成功返回整型0，失败返回整型-1。

`ble.discoverAllCharaDesc`

ble.discoverAllCharaDesc(connect_id, start_handle, end_handle)

扫描所有特征的描述，start_handle和end_handle要属于同一个服务。

参数描述：

connect_id-连接ID，建立连接时得到的连接ID，类型为整型。
start_handle-开始句柄，从这个句柄开始寻找特征描述，类型为整型。
end_handle-结束句柄，从这个句柄结束寻找特征描述，类型为整型。

返回值描述：

执行成功返回整型0，失败返回整型-1。

`ble.readCharaByUUID`

ble.readCharaByUUID(connect_id, start_handle, end_handle, uuid_type, uuid_s, uuid_l)

读取指定UUID的特征值，start_handle和end_handle必须要包含一个特征值句柄。

参数描述：

connect_id-连接ID，建立连接时得到的连接ID，类型为整型。
start_handle-开始句柄，一定要属于同一个服务的句柄，类型为整型。
end_handle-结束句柄，一定要属于同一个服务的句柄，类型为整型。
uuid_type-uuid类型，0 - 长UUID，128bit；1 - 短UUID，16bit。类型为整型。
uuid_s-短UUID，2个字节（16bit），类型为整型，当uuid_type为0时，该值给0。
uuid_l-长UUID，16个字节（128bit），类型为bytearray，当uuid_type为1时，该值填 bytearray([0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00])。

返回值描述：

执行成功返回整型0，失败返回整型-1。

`ble.readCharaByHandle`

ble.readCharaByHandle(connect_id, handle, offset, is_long)

读取指定句柄的特征值。

参数描述：

connect_id-连接ID，建立连接时得到的连接ID，类型为整型。
handle-特征值句柄，类型为整型。
offset-偏移位置，类型为整型。
is_long-长特征值标志，0-短特征值，一次可以读取完；1-长特征值，分多次读取。类型为整型。

返回值描述：

执行成功返回整型0，失败返回整型-1。

`ble.readCharaDesc`

ble.readCharaDesc(connect_id, handle, is_long)

读取特征描述。

参数描述：

connect_id-连接ID，建立连接时得到的连接ID，类型为整型。
handle-特征值句柄，类型为整型。
is_long-长特征值标志，0-短特征值，一次可以读取完；1-长特征值，分多次读取。类型为整型。

返回值描述：

执行成功返回整型0，失败返回整型-1。

`ble.writeChara`

ble.writeChara(connect_id, handle, offset, is_long, data)

写入特征值，需要对端应答。

参数描述：

connect_id-连接ID，建立连接时得到的连接ID，类型为整型。
handle-特征值句柄，类型为整型。
offset-偏移位置，类型为整型。
is_long-长特征值标志，0-短特征值，一次可以读取完；1-长特征值，分多次读取。类型为整型。
data-特征值数据，类型为bytearray。

返回值描述：

执行成功返回整型0，失败返回整型-1。

`ble.writeCharaNoRsp`

ble.writeCharaNoRsp(connect_id, handle, data)

写入特征值，不需要对端应答。

参数描述：

connect_id-连接ID，建立连接时得到的连接ID，类型为整型。
handle-特征值句柄，类型为整型。
data-特征值数据，类型为bytearray。

返回值描述：

执行成功返回整型0，失败返回整型-1。

`ble.writeCharaDesc`

ble.writeCharaDesc(connect_id, handle, data)

写入特征描述。

参数描述：

connect_id-连接ID，建立连接时得到的连接ID，类型为整型。
handle-特征描述句柄，类型为整型。
data-特征描述数据，类型为bytearray。

返回值描述：

执行成功返回整型0，失败返回整型-1。

`ble.exchangeMtu`

ble.exchangeMtu(connect_id, mtu_size)

发送MTU交换请求。MTU交换请求应该由client端发起。

参数描述：

connect_id-连接ID，建立连接时得到的连接ID，类型为整型。
mtu_size-MTU大小。

返回值描述：

执行成功返回整型0，失败返回整型-1。

BLE SMP相关功能

`ble.smpSetConfig`

ble.smpSetConfig(io_cap, auth_req, passkey, timeout)

配对能力配置。

参数描述：

io_cap-设备输入输出能力，类型为整型，默认为3。

值	含义
0	只有显示能力，可以显示PIN码
1	只有显示能力，只能显示Yes/No，不能显示PIN码
2	只有输入能力，可以输入PIN码
3	没有输入输出能力
4	有输入输出能力，既可以显示PIN码，又可以输入PIN码。

auth_req-认证请求参数，类型为整型，默认为9。

	Bit0	Bit1	Bit2	Bit3
0	配对后不绑定	预留，无实际含义	不启用MITM	使用Legacy Pairing
1	配对后绑定	预留，无实际含义	启用MITM	使用Secure Connections Pairing

passkey-配对显示的PIN码，类型为整型，默认为123456。
timeout-配对超时时间，单位为100ms，类型为整型，默认为160。

返回值描述：

执行成功返回整型0，失败返回整型-1。

配对方法选择过程：

BLE smp配对有Legacy Pairing和Secure Connections Pairing两种模式，具体有如下4种配对方法：

OOB
Just Works
Passkey Entry
Numeric Comparison (只有 Secure Connections Pairing 模式才有)

具体选择哪一种方法配对，是由配对的双方在交换各自的IO能力后协商决定的，基本分为下面几个阶段：

阶段1：配对双方会先确认使用Legacy Pairing还是Secure Connections Pairing模式来进行配对，原则是：只有双方都设置了Secure Connections Pairing标志，才会使用这种配对模式，否则使用Legacy Pairing。

阶段2：判断是否支持OOB。对于Legacy Pairing模式，只有双方均支持OOB，才会使用OOB方式。对于Secure Connections Pairing模式，如果Initiator支持OOB，则使用OOB方式。

阶段3：检查MITM（中间人）。如果配对双方都没有配置MITM标志，则直接使用Just Works方法来配对，否则按照双方的IO能力来选择配对方法。

阶段4：根据双方的IO能力来选择配对方法。

关于阶段2 ~ 阶段4的具体说明可以参考蓝牙官方手册文档《BLUETOOTH SPECIFICATION Version 4.2 [Vol 3, Part H]》的 *2.3.5.1 Selecting Key Generation Method* 章节的内容。

`ble.smpGetConfig`

ble.smpGetConfig(io_cap, auth_req, passkey, timeout)

配对能力查询。

返回值描述：

执行成功返回值如下，失败返回整型-1。

io_cap-设备输入输出能力，类型为整型，默认为3。

值	含义
0	只有显示能力，可以显示PIN码
1	只有显示能力，只能显示Yes/No，不能显示PIN码
2	只有输入能力，可以输入PIN码
3	没有输入输出能力
4	有输入输出能力，既可以显示PIN码，又可以输入PIN码

auth_req-认证请求参数，类型为整型，默认为9。

	Bit0	Bit1	Bit2	Bit3
0	配对后不绑定	预留，无实际含义	不启用MITM	使用Legacy Pairing
1	配对后绑定	预留，无实际含义	启用MITM	使用Secure Connections Pairing

passkey-配对显示的PIN码，类型为整型，默认为123456。
timeout-配对超时时间，单位为100ms，类型为整型，默认为160。

`ble.smpStartPair`

ble.smpStartPair(connect_id)

开始BLE SMP配对流程。SMP配对由client发起，server也可以通过该接口来通知client发起SMP配对请求。

参数描述：

connect_id-连接ID，建立连接时得到的连接ID，类型为整型。

返回值描述：

执行成功返回整型0，失败返回整型-1。

`ble.smpUserConfirm`

ble.smpUserConfirm(connect_id, pair_operation, pin)

确认配对。收到配对请求后确认是否接受配对。

参数描述：

connect_id-连接ID，建立连接时得到的连接ID，类型为整型。
pair_operation-配对的操作类型，类型为整型。

值	含义
0	取消配对，只有在配对过程中，才能执行该操作。取消配对会导致蓝牙连接断开。
1	确认配对，不携带PIN码（用于Just Work或者Numeric Comparison模式）
2	确认配对，携带PIN码（用于Passkey模式）

pin-PIN码，类型为整型。

返回值描述：

执行成功返回整型0，失败返回整型-1。

`ble.smpGetPairedDevInfo`

ble.smpGetPairedDevInfo()

获取已配对设备信息。

返回值描述：

执行成功返回值如下，失败返回整型-1。

addr_list-已配对设备的BLE地址列表，类型为list，list成员为bytearray类型的BLE地址。

`ble.smpRemovePairedDev`

ble.smpRemovePairedDev(addr)

删除指定的已配对设备信息。

参数描述：

addr-待删除的设备BLE地址，类型为bytearray，大小为6字节。

返回值描述：

执行成功返回整型0，失败返回整型-1。

`ble.smpCleanPairedDev`

ble.smpCleanPairedDev()

删除所有已配对设备信息。

返回值描述：

执行成功返回整型0，失败返回整型-1。

注意：以上BLE SMP相关接口均需要在BLE已经初始化的情况下执行，否则会返回失败。当前仅EC200UEUAA型号特定固件支持BLE SMP功能。

蓝牙通信

bt - 经典蓝牙相关功能