uni.openBluetoothAdapter(OBJECT)

uni.openBluetoothAdapter({ 
           success(res) { 
             console.log(res)     // 接口调用成功的回调函数   },   fail:(res)=>{ 
               // 接口调用失败的回调函数   },   complete:()=>{ 
          // 接口调用后的回调函数(调用成功或失败)   } }) 

错误 ：res.errCode

注意

uni.onBluetoothAdapterStateChange(CALLBACK)

CALLBACK 返回参数

示例代码

uni.onBluetoothAdapterStateChange((res) => { 
             console.log('onBluetoothAdapterStateChange', res)     // avaiable：蓝牙适配器是否可用
    if (res.available) { 
        
        // 取消监听，否则stopBluetoothDevicesDiscovery后仍会继续触发onBluetoothAdapterStateChange，
        // 导致再次调用startBluetoothDevicesDiscovery
        uni.onBluetoothAdapterStateChange(() => { 
        });
        // 开始搜寻附近的蓝牙外围设备
        uni.startBluetoothDevicesDiscovery(OBJECT)
    }
})

uni.startBluetoothDevicesDiscovery(OBJECT)

此操作比较耗费系统资源，请在搜索并连接到设备后调用 uni.stopBluetoothDevicesDiscovery 方法停止搜索。

OBJECT 参数说明

错误

注意：

• App 端目前仅支持发现ble蓝牙设备，更多蓝牙设备发现，可以使用 Native.js，参考：https://ask.dcloud.net.cn/article/114。也可以在插件市场获取原生插件

示例代码

// 以微信硬件平台的蓝牙智能灯为例，主服务的 UUID 是 FEE7。传入这个参数，只搜索主服务 UUID 为 FEE7 的设备
uni.startBluetoothDevicesDiscovery({ 
        
  services: ['FEE7'],
  success(res) { 
        
    console.log(res)
    // 监听寻找到新设备的事件
    uni.onBluetoothDeviceFound(OBJECT)
  }
})

uni.onBluetoothDeviceFound(CALLBACK)

CALLBACK 返回参数

devices 的结构

注意

• 若在 uni.onBluetoothDeviceFound 回调了某个设备，则此设备会添加到 uni.getBluetoothDevices 接口获取到的数组中。

示例代码

// ArrayBuffer转16进度字符串示例
function ab2hex(buffer) { 
        
  const hexArr = Array.prototype.map.call(
    new Uint8Array(buffer),
    function (bit) { 
        
      return ('00' + bit.toString(16)).slice(-2)
    }
  )
  return hexArr.join('')
}
uni.onBluetoothDeviceFound(function (devices) { 
        
  console.log('new device list has founded')
  console.dir(devices)
  console.log(ab2hex(devices[0].advertisData))
})

uni.stopBluetoothDevicesDiscovery(OBJECT)

若已经找到需要的蓝牙设备并不需要继续搜索时，建议调用该接口停止蓝牙搜索。

OBJECT 参数说明

错误

示例代码

uni.stopBluetoothDevicesDiscovery({ 
        
  success(res) { 
        
    console.log(res)
  }
})

uni.getConnectedBluetoothDevices(OBJECT)

OBJECT 参数说明

success 返回参数说明：

res.devices 的结构

错误

示例代码

uni.getConnectedBluetoothDevices({ 
        
  success(res) { 
        
    console.log(res)
  }
})

uni.getBluetoothDevices(OBJECT)

包括已经和本机处于连接状态的设备。

OBJECT 参数说明

success 返回参数说明：

res.devices 的结构

错误

示例代码

// ArrayBuffer转16进度字符串示例
function ab2hex(buffer) { 
        
  const hexArr = Array.prototype.map.call(
    new Uint8Array(buffer),
    function (bit) { 
        
      return ('00' + bit.toString(16)).slice(-2)
    }
  )
  return hexArr.join('')
}
uni.getBluetoothDevices({ 
        
  success(res) { 
        
    console.log(res)
    if (res.devices[0]) { 
        
      console.log(ab2hex(res.devices[0].advertisData))
    }
  }
})

注意

• 该接口获取到的设备列表为蓝牙模块生效期间所有搜索到的蓝牙设备，若在蓝牙模块使用流程结束后未及时调用 uni.closeBluetoothAdapter 释放资源，会存在调用该接口会返回之前的蓝牙使用流程中搜索到的蓝牙设备，可能设备已经不在用户身边，无法连接。
• 蓝牙设备在被搜索到时，系统返回的 name 字段一般为广播包中的 LocalName 字段中的设备名称，而如果与蓝牙设备建立连接，系统返回的 name 字段会改为从蓝牙设备上获取到的 GattName。若需要动态改变设备名称并展示，建议使用 localName 字段。

uni.getBluetoothAdapterState(OBJECT)

OBJECT 参数说明

success 返回参数说明：

错误

示例代码

uni.getBluetoothAdapterState({ 
        
  success(res) { 
        
    console.log(res)
  }
})

uni.closeBluetoothAdapter(OBJECT)

调用该方法将断开所有已建立的连接并释放系统资源。建议在使用蓝牙流程后，与 uni.openBluetoothAdapter 成对调用。

OBJECT 参数说明

错误

示例代码

uni.closeBluetoothAdapter({ 
        
  success(res) { 
        
    console.log(res)
  }
})

[uni.setBLEMTU(OBJECT)

需在 uni.createBLEConnection调用成功后调用，mtu 设置范围 (22,512)。安卓5.1以上有效。

OBJECT 参数说明

uni.writeBLECharacteristicValue(OBJECT)

注意：必须设备的特征值支持 write 才可以成功调用。

OBJECT 参数说明

错误

注意

• 并行调用多次会存在写失败的可能性。
• APP不会对写入数据包大小做限制，但系统与蓝牙设备会限制蓝牙4.0单次传输的数据大小，超过最大字节数后会发生写入错误，建议每次写入不超过20字节。
• 若单次写入数据过长，iOS 上存在系统不会有任何回调的情况（包括错误回调）。
• 安卓平台上，在调用 notifyBLECharacteristicValueChange 成功后立即调用 writeBLECharacteristicValue 接口，在部分机型上会发生 10008 系统错误

示例代码

// 向蓝牙设备发送一个0x00的16进制数据
const buffer = new ArrayBuffer(1)
const dataView = new DataView(buffer)
dataView.setUint8(0, 0)
uni.writeBLECharacteristicValue({ 
        
  // 这里的 deviceId 需要在 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取
  deviceId,
  // 这里的 serviceId 需要在 getBLEDeviceServices 接口中获取
  serviceId,
  // 这里的 characteristicId 需要在 getBLEDeviceCharacteristics 接口中获取
  characteristicId,
  // 这里的value是ArrayBuffer类型
  value: buffer,
  success(res) { 
        
    console.log('writeBLECharacteristicValue success', res.errMsg)
  }
})

uni.readBLECharacteristicValue(OBJECT)

注意：必须设备的特征值支持 read 才可以成功调用。

OBJECT 参数说明

错误

注意

• 并行调用多次会存在读失败的可能性。
• 接口读取到的信息需要在 onBLECharacteristicValueChange 方法注册的回调中获取。

示例代码

// 必须在这里的回调才能获取
uni.onBLECharacteristicValueChange(function (characteristic) { 
        
  console.log('characteristic value comed:', characteristic)
})
uni.readBLECharacteristicValue({ 
        
  // 这里的 deviceId 需要已经通过 createBLEConnection 与对应设备建立链接
  deviceId,
  // 这里的 serviceId 需要在 getBLEDeviceServices 接口中获取
  serviceId,
  // 这里的 characteristicId 需要在 getBLEDeviceCharacteristics 接口中获取
  characteristicId,
  success(res) { 
        
    console.log('readBLECharacteristicValue:', res.errCode)
  }
})

uni.onBLEConnectionStateChange(CALLBACK)

包括开发者主动连接或断开连接，设备丢失，连接异常断开等等

CALLBACK 返回参数

示例代码

uni.onBLEConnectionStateChange(function (res) { 
        
  // 该方法回调中可以用于处理连接意外断开等异常情况
  console.log(`device ${ 
          res.deviceId} state has changed, connected: ${ 
          res.connected}`)
})

uni.onBLECharacteristicValueChange(CALLBACK)

必须先启用 notifyBLECharacteristicValueChange 接口才能接收到设备推送的 notification。

CALLBACK 返回参数

示例代码

// ArrayBuffer转16进度字符串示例
function ab2hex(buffer) { 
        
  const hexArr = Array.prototype.map.call(
    new Uint8Array(buffer),
    function (bit) { 
        
      return ('00' + bit.toString(16)).slice(-2)
    }
  )
  return hexArr.join('')
}
uni.onBLECharacteristicValueChange(function (res) { 
        
  console.log(`characteristic ${ 
          res.characteristicId} has changed, now is ${ 
          res.value}`)
  console.log(ab2hex(res.value))
})

uni.notifyBLECharacteristicValueChange(OBJECT)

启用低功耗蓝牙设备特征值变化时的 notify 功能，订阅特征值。注意：必须设备的特征值支持 notify 或者 indicate 才可以成功调用。 另外，必须先启用 notifyBLECharacteristicValueChange<