蓝牙接口(Bluetooth)

  • CMBLS蓝牙接口(7.3.0及以上版本支持)


接口描述

小程序可以通过调用该接口使用设备的蓝牙功能。


调用命令

接口调用

·http://cmbls/Bluetooth?action=action&param=xxx


参数名必选说明
action操作类型

接口返回:

  • CMBLS.Bluetooth.successCallback(id,message)

  • CMBLS.Bluetooth.failCallback(id,message)

成功返回:

<Data>
<stateCode>0</stateCode>
<description>Success</description>
</Data>

失败返回:

<Data>
<stateCode>非0的错误码</stateCode>
<description>错误信息</description>
</Data>



action参数列表

注:以下接口如无特殊说明,返回结果均在CMBLS.Bluetooth.successCallback(id,message)和CMBLS.Bluetooth.failCallback(id,message)中接收

  • openBluetoothAdapter

    初始化蓝牙适配器,使用蓝牙功能前必须要调用该接口对蓝牙接口进行初始化。调用该接口同时会启动4个(onDeviceFound, onConnectionStateChange, onCharacteristicValueChange, onAdapterStateChange)监听回调接口。

    调用示例: http://cmbls/Bluetooth?id=xxx&action=openBluetoothAdapter
  • queryState

    查询蓝牙适配器状态

    调用示例: http://cmbls/Bluetooth?id=xxx&action=queryState"

    返回结果

    <Data><available>yes/no</available>   //蓝牙是否可用    <discovering>yes/no</discovering> //是否正在搜索设备(iOS9以上返回该字段)</Data>
  • closeBluetoothAdapter

    关闭蓝牙适配器, 蓝牙适配器使用完毕后需调用该接口以释放相关资源

    使用该接口参数如下


参数名必选说明
ble经典蓝牙接口传false,使用BLE接口传true,默认为true
调用示例: http://cmbls/Bluetooth?id=xxx&action=closeBluetoothAdapter
  • startDeviceDiscovery

开始搜寻附近的蓝牙外围设备。此操作比较耗费系统资源,请在搜索并连接到设备后调用 stopDevicesDiscovery 方法停止搜索。调用该接口后,数据在onDeviceFound中返回。

使用该接口参数如下

参数名必选说明
servicesserviceUUID,若传入该参数则只返回有对应service的设备,services可以传多个UUID,用英文逗号分隔,如services=UUID1,UUID2.
interval上报设备时间间隔,默认为0即找到设备立即上报,单位是秒
allowDuplicatesKey是否允许重复上报同一设备,传入yes或no,默认是no(仅iOS支持该参数)。
ble经典蓝牙接口传false,使用BLE接口传true,默认为true
    调用示例: http://cmbls/BlueTooth?id=xxx&action=startDeviceDiscovery&services=uuid1,uuid2&allowDuplicatesKey=no&interval=2
  • stopDeviceDiscovery 停止搜索附近的蓝牙设备。

使用该接口参数如下

参数名必选说明
ble经典蓝牙接口传false,使用BLE接口传true,默认为true
    调用示例: http://cmbls/BlueTooth?id=xxx&action=stopDeviceDiscovery
  • connectDevice

    连接低功耗蓝牙设备

    使用该接口参数如下

参数名必选说明
deviceId蓝牙设备的uuid,该参数可在startDeviceDiscovery调用后获得
ble经典蓝牙接口传false,使用BLE接口传true,默认为true
    调用示例: http://cmbls/BlueTooth?id=xxx&action=connectDevice&deviceId=xxxx

注:iOS在连接设备前需要调用startDeviceDiscovery在onDeviceFound中接收到相应设备信息后再进行连接才可以连接成功

  • disconnectDevice

    断开低功耗蓝牙设备连接

    使用该接口参数如下

参数名必选说明
deviceId蓝牙设备的uuid
ble经典蓝牙接口传false,使用BLE接口传true,默认为true
    调用示例: http://cmbls/BlueTooth?id=xxx&action=disconnectDevice&deviceId=xxxx
  • queryServices

获取蓝牙设备所有服务(service)。

使用该接口参数如下

参数名必选说明
deviceId蓝牙设备的uuid
调用示例: http://cmbls/Bluetooth?id=xxx&action=queryServices&deviceId=xxxx

返回结果(service可能会返回多条数据):

<Data><service><uuid>serviceUUID</uuid><isPrimary>yes/no</isPrimary></service></Data>
  • queryCharacteristics

    获取蓝牙设备对应服务的的 characteristic

    使用该接口参数如下

参数名必选说明
deviceId蓝牙设备的uuid
serviceId要查询服务对应的serviceId
调用示例:http://cmbls/BlueTooth?id=xxx&action=queryCharacteristics&deviceId=xxxx&serviceId=xxx

返回结果(characteristic可能会有多条数据):

<Data>< characteristic ><uuid>xxxx<uuid><properties>0000</properties> // 返回值为4个标识位, 分别表示read、write、notify、indicate, 1表示支持,0表示不支持(如1000,表示只有read权限)    </characteristic><Data>
  • notifyCharacteristicValueChange

启用低功耗蓝牙设备特征值变化时的 notify 功能。注意:设备的特征值必须支持 notify/indicate 才可以成功调用,具体参照 characteristic 的 properties 属性 另外,必须先启用 notify 才能监听到设备 onCharacteristicValueChange 事件。

使用该接口参数如下

参数名必选说明
deviceId蓝牙设备的UUID
serviceId服务的UUID
characteristicId特征值UUID
state是否启用notify或indicate 传入yes/no, 默认为yes

接口调用结果在successCallback和failCallback中返回, 数据回调在 onCharacteristicValueChange(message)中返回。

调用示例: http://cmbls/Bluetooth?id=xxx&action=notifyCharacteristicValueChange&deviceId=ddd&serviceId=sss&characteristicId=ccc&state=yes

*注: 订阅操作成功后需要设备主动更新特征值的 value,才会触发onCharacteristicValueChange 。订阅方式效率比较高,推荐使用订阅代替 read 方式。

  • readCharacteristic

读取低功耗蓝牙设备特征值中的数据。调用后在 onCharacteristicValueChange事件中接收数据返回。

使用该接口参数如下

参数名必选说明
deviceId蓝牙设备的UUID
serviceId服务的UUID
characteristicId特征值UUID
调用示例: http://cmbls/Bluetooth?id=xxx&action=readCharacteristic&deviceId=ddd&serviceId=sss&characteristicId=ccc

注:设备的特征值必须支持read才可以成功调用,具体参照 characteristic 的 properties 属性

  • writeCharacteristic

向低功耗蓝牙设备特征值中写入数据。

使用该接口参数如下

参数名必选说明
deviceId蓝牙设备的UUID
serviceId服务的UUID
characteristicId特征值UUID
value蓝牙设备特征值对应的值,16进制字符串,限制在20字节内
 调用示例: http://cmbls/Bluetooth?id=xxx&action=writeCharacteristic&deviceId=ddd&serviceId=sss&characteristicId=ccc&value=value

注:设备的特征值必须支持 write 才可以成功调用,具体参照 characteristic 的 properties 属性。如果需要写入数据较大需要分包处理,写入数据时最好依赖于上一次写入成功回调后再写入下一次数据,否则可能造成数据写入无法成功或响应,Android设备遇到该问题概率较大。

  • writeData 向蓝牙设备写入输入(仅支持经典蓝牙接口)

使用该接口参数如下

参数名必选说明
deviceId蓝牙设备的UUID
value16进制字符串
isResponse是否需要读取设备返回值,需要传入true

(注意:该接口需要传ble=false,明确指定) isResponse为true时,调用该接口会触发 CMBLS.Bluetooth.onWriteResponse(message) 接口回调。


监听回调接口

  • CMBLS.Bluetooth.onAdapterStateChange(message) (仅iOS支持该回调)

蓝牙适配器状态变更会触发改接口 message数据格式:

<Data>    <available>yes/no</available>   //蓝牙适配器是否可用      <discovering>yes/no</discovering> //是否正在搜索设备</Data>

  • CMBLS.Bluetooth.onDeviceFound(message)

搜索到新的蓝牙设备时触发此接口 message数据格式:

<Data>    <device><name>蓝牙设备1</name>   //有的设备可能没有name            <deviceId>UUID</deviceId>    <RSSI>xxx</RSSI>    <advertiseData>HexString</advertiseData> //iOS设备该内容为广播字段中的manufactureData       </device><Data>

  • CMBLS.Bluetooth.onConnectionStateChange(message)

蓝牙设备连接状态的监听回调 message数据格式:

<Data>

   <deviceId>xxxx</deviceId>

   <connected>yes/no</connected>

</Data>

  • CMBLS.Bluetooth.onCharacteristicValueChange(message)

监听特征值数据变化 message数据格式:

<Data>    <deviceId>xxxx</deviceId>    <serviceId>xxxx</serviceId>    <characteristicId>xxx</characteristicId>    <value>HexString</value></Data>

  • CMBLS.Bluetooth.onWriteResponse(message)

经典蓝牙接口写入的回调函数 message数据格式:

<Data>    <deviceId>xxxx</deviceId>    <value>HexString</value></Data>


错误码

<stateCode>xxx</stateCode>
201 蓝牙适配器不可用
202 未找到指定设备
203 未找到指定服务
204 连接失败
205 未找到指定特征值
206 当前特征值不支持此操作
207 缺少参数,检查调用的参数
208 写入特征值失败
209 读取特征值失败
210 订阅特征值失败
211 未找到该接口
212 接口使用错误,请选择正确的蓝牙策略