uniapp BLE低功耗蓝牙插件 支持安卓 iOS 鸿蒙NEXT 微信小程序

xl-ble插件

概述

本SDK提供了一套完整的蓝牙低功耗(BLE)设备交互接口，采用模块化设计，将功能接口与回调监听分离，便于开发者灵活使用。

• 支持蓝牙扫描、连接、断开;

• 支持字节数据、字符串数据写入;

• 蓝牙状态监听、连接状态监听、数据回传监听、数据写入是否完成监听;

• 支持GBK编码;

导入

import * as ble from '@/uni_modules/xl-ble';

功能接口说明

扫描设备

// callback: 发现设备回调
ble.startScan((device) => {console.log(`发现设备: ${JSON.stringify(device)}`);
});

停止扫描

ble.stopScan();

连接设备

// 参数1: 设备id
// 参数2(可选):指定服务与特征，未指定内部会自动匹配
ble.connect(deviceId,// {// 	seviceUuid: '0000ff00-0000-1000-8000-00805f9b34fb',// 	writeUuid: '0000ff02-0000-1000-8000-00805f9b34fb',// 	notifyUuid: '0000ff01-0000-1000-8000-00805f9b34fb'// },
)

断开设备

ble.disconnect()

写入数据

• 写入字节数组

  // 参数为字节数组，需设备支持的指令，这点很重要
  ble.writeBytes([0x10, 0xff, 0x30])
  

• 写入字符串

  // 参数1: 字符串内容，传的字符串需设备支持的指令，这点很重要
  // 参数2(可选): 字符串编码, 默认 "UTF_8" 编码, 传 "GBK" 使用GBK编码
  ble.writeString('ABC')
  ble.writeString('ABC', 'GBK')
  

设置MTU分包大小

ble.setMtu(100)

蓝牙事件监听

蓝牙状态监听

ble.onBluetoothStatusChanged((isOn) => {uni.showToast({title: isOn ? "蓝牙已开启" : "蓝牙已关闭",icon: 'none'});
});

蓝牙连接状态监听

ble.onConnectionStateChange((connectionState) => {uni.showToast({title: connectionState.msg,icon: 'none'})switch (connectionState.state) {case 'connectFail':// 连接失败break;case 'disconnected':// 断开连接break;case 'connected':// 断开成功break;}
});

蓝牙数据回传监听

ble.onDataReceived((data) => {let result = String.fromCharCode(...data);console.log(`收到蓝牙数据: ${data}`)console.log(`收到蓝牙数据转字符串: ${result}`);
});

数据写入是否完成监听

ble.onWriteComplete((isComplete) => {console.log(isComplete ? "写入完成" : "写入失败");
})

蓝牙权限

• 安卓

  <uses-permission android:name="android.permission.BLUETOOTH"/>
  <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
  <uses-permission android:name="android.permission.BLUETOOTH_CONNECT"/>
  <uses-permission android:name="android.permission.BLUETOOTH_SCAN"/>
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
  <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
  

• iOS

  <key>NSBluetoothAlwaysUsageDescription</key>
  <string>开启蓝牙</string>
  <key>NSBluetoothPeripheralUsageDescription</key>
  <string>蓝牙</string>
  <key>UIBackgroundModes</key>
  <array><string>bluetooth-central</string>
  </array>
  

类型定义

设备信息

interface BLEDevice {name: string       // 设备名称deviceId: string   // 设备唯一标识rssi: number       // 信号强度
}

连接配置

interface ConnectOptions {serviceUuid: string   // 主服务UUIDwriteUuid: string     // 写入特征UUIDnotifyUuid: string    // 通知特征UUIDautoConnect?: boolean // 是否自动重连
}

服务信息

interface ServiceAndCharacteristics {service: string         // 服务UUIDcharacteristics: string[] // 特征值列表
}

连接状态

type ConnectionState = {status: 'connected' | 'disconnected' | 'failed'message?: string
}