wx-ble

wx-bluetooth

可能是Github上迄今为止最适合前端、最易用的微信小程序蓝牙实现。 iOS bluetooth_run_screenshot

• Features
• Usage
• Example
• 实现
• API
  • config
  • connectOptions
  • 实例方法
• TODOs
• ChangeLog
• License

Features

• 简单强大的API
• 使用状态机自动管理状态
• 支持自动修复连接，重新连接
• 支持connect timeout 连接超时机制
• 支持初始化多个蓝牙实例
• 支持found,connect,notify,timout,fail回调
• 支持wx.method.paramters.success方法的promisify

Usage

• npm:

  npm install wx-ble

  then

  import Bluetooth from 'wx-ble'

• 直接下载项目后，在页面引入。建议将该工具方法放在 utils or vendors 目录下，并新建名为bluetooth的目录后，将文件下载到该目录中:

  cd ProjectPath/utils
  git clone https://github.com/vuchan/wx-bluetooth.git

  then

  import Bluebooth from 'yourRelativePath/bluetooth/index.js'

Example

注： 如果keepAlive配置项为true的话，需要手动在 sendData 方法成功then后写上 return this.trigger('success', true) 以触发 finish 。

const bluebooth = new Bluetooth({   // configOptions 参考下方的API
  debug: false,
  timeout: 5,
  keepAlive: true,
  // 必须配置 `connectOptions` 中的 `deviceName` 和 `services` 以匹配你想匹配的蓝牙设备
  connectOptions: {
    interval: 0,
    services: [''], // your device services array
    allowDuplicatesKey: false,
    deviceName: '', // device name
    // characteristicId: ''
  },
  onConnect: function () {
    // 如果 keepAlive 为`true`的话，需要自己手动在 sendData 成功后执行 `return this.trigger('success', true)` 以触发 `finish` 状态以进入关闭蓝牙连接和蓝牙适配器操作
    this.sendData('01').then(res => this.sendData('02')).then(res => this.sendData('03')).then(res => this.trigger('success'))
  }
})

实现

通过triggerCommands触发success or failure进入成功或失败状态。

1. 初始化-init
2. 搜索-search
3. 连接-connect
4. 通信-transfer
5. 结束-finish

API

config 配置项：

option name	type	parameter	default value	description
autoConnect	Boolean		false	初始化实例时完成后自动根据 connenctOptions 连接蓝牙，否者手动调用实例的 start 方法
debug	Boolean		true	打开console，debug程序内部状态的变化
timeout	Number		false	以s(秒)为单位。在蓝牙的连接过程中，若在该 timeout 秒时间内无法连接，则进入 timeout 回调。如果为0 or false，则关闭该项。
keepAlive	Boolean		false	保持蓝牙通讯的连接
autoFixConnect	Boolean		true	蓝牙断开后，自动修复蓝牙连接
maxReconnectTimes	Number		5	最大重连次数
onFound	Function	devices	[]	当蓝牙发现新设备时，接收第一个参数 devices 获取所有设备
onConnect	Function			连接成功后的回调，进行传输数据等操作
onNotify	Function	value		收到蓝牙传输过来的值的回调，通过参数value查看该值
onTimeout	Function	error		连接超时的回调函数（连接超时函数若不自定义会自动进入onFail函数）
onFail	Function	error		再重连maxReconnectTimes后，会调用连接失败后的回调
connectOptions	Object		见下面connectOptions API	connectOptions 是一个对象，用来设置连接蓝牙的配置项。蓝牙是否能够连接，跟此配置项有莫大关系。

connectOptions 配置项：

property name	type	default value	descripion	details
interval	Number	0	上报设备的间隔，默认为0，意思是找到新设备立即上报，否则根据传入的间隔上报	更多
services	Array	[]	蓝牙设备主 service 的 uuid 列表	更多
allowDuplicatesKey	Boolean	false	是否允许重复上报同一设备， 如果允许重复上报，则onDeviceFound 方法会多次上报同一设备，但是 RSSI 值会有不同	更多
deviceName	String	''	通过该项匹配当前设备，如果设备名称包含该字段，则认为匹配
characteristicId	String	''	该项目前未使用

实例方法

method name	parameter	default value	return	description
start				手动开启该实例对象的蓝牙连接
sendData	data	''	{Promise}	向已连接的蓝牙设备发送数据(该方法必须在蓝牙连接成功后调用)
resetState				清空和重置内部状态，关闭蓝牙连接，如果不再存在蓝牙实例，则关闭蓝牙适配器

TODOs

1. timeout
2. 欢迎issue
3. 欢迎pull/request
4. 如果API有不甚清晰的地方，请issue
5. If it is useful for u, please give me a star to make me has more passion to update it, Thanks!

ChangeLog

2018-1-30

1. finished timeout logic.
2. fixed resetState function.

2018-2-2

1. Modified the code of example.

2018-2-5

1. Updated the TODOs of this doc.
2. Mofified API doc.

2018-2-26

1. add a new config option autoConnect
2. add new callback function onFound

2018-4-08

1. fixed the timeout method will be auto set off at init state bluetoothStateHandler function.
2. add a fallback feature to the start function.

License

MIT