更新记录

1.0.6（2025-07-01） 下载此版本

文档更新

1.0.5（2025-01-09） 下载此版本

1

1.0.4（2025-01-06） 下载此版本

增加设备过滤方式

平台兼容性

uni-app

蓝牙模块使用说明

概述

这是一个基于 uni-app 的蓝牙低功耗（BLE）控制模块，提供完整的蓝牙设备扫描、连接、数据收发功能。模块包含三个主要文件：

• bluetoothControl.js - 基础蓝牙控制类
• deviceControl.js - 扩展的设备控制类（支持命令响应模式）
• bufferConversion.js - 数据缓冲区转换工具

模块结构

BluetoothControl 类

基础蓝牙控制类，提供核心的蓝牙操作功能。

DeviceControl 类

继承自 BluetoothControl，增加了命令执行和响应处理功能。

工具函数

提供各种数据格式转换功能。

安装和导入

import { BluetoothControl } from '@/uni_modules/x-bluetooth/js_sdk/bluetoothControl.js'
import { DeviceControl } from '@/uni_modules/x-bluetooth/js_sdk/deviceControl.js'
import { ab2hex, ab2hexArr, str2ab, num2ab } from '@/uni_modules/x-bluetooth/js_sdk/bufferConversion.js'

配置参数

BluetoothControlOptions

基本使用

1. 创建蓝牙控制实例

import { BluetoothControl } from '@/uni_modules/x-bluetooth/js_sdk/bluetoothControl.js'

// 基础用法
const bluetooth = new BluetoothControl({
    debug: true,
    serviceId: 'YOUR_SERVICE_UUID',
    writeCharacteristicId: 'YOUR_WRITE_CHARACTERISTIC_UUID',
    notifyCharacteristicId: 'YOUR_NOTIFY_CHARACTERISTIC_UUID'
})

// 带设备过滤
const bluetooth = new BluetoothControl({
    debug: true,
    mode: 'name',
    filter: 'MyDevice', // 或使用正则: /MyDevice/i
    serviceId: 'YOUR_SERVICE_UUID'
})

// 使用自定义过滤函数
const bluetooth = new BluetoothControl({
    debug: true,
    mode: 'fun',
    filter: device => {
        const { name, advertisData } = device

        const arr = bufferUtil.ab2hexArr(advertisData)

        // 设备广播数据第一字节等于 01, 同时设备名包含 xxx 通过过滤
        if (arr[0] === '01' && name.includes('xxx')) {
            device.advertisDataArr = arr
            return true
        }
    },
    serviceId: 'YOUR_SERVICE_UUID'
})

2. 扫描设备

// 开始扫描
await bluetooth.startFind((device, devices) => {
    console.log('发现设备:', device.name, device.deviceId)
    console.log('当前设备列表:', devices)
})

// 停止扫描
await bluetooth.stopFind()

3. 连接设备

try {
    // 连接设备（deviceId 从扫描结果中获取）
    await bluetooth.connect(deviceId, 512, true)
    console.log('设备连接成功')
} catch (error) {
    console.error('连接失败:', error)
}

4. 设置数据监听

// 启用特征值变化监听
await bluetooth.setNotify({})

// 监听数据变化
bluetooth.startListenerCharacteristicValueChange((data) => {
    console.log('接收到数据:', data.hex)
    console.log('十六进制数组:', data.hexArr)
})

5. 发送数据

// 发送字符串数据
const message = 'Hello'
const buffer = str2ab(message)
await bluetooth.write(buffer)

// 发送数字数据
const numberBuffer = num2ab([0x01, 0x02, 0x03])
await bluetooth.write(numberBuffer)

// 发送十六进制数据
const hexData = new Uint8Array([0xFF, 0xFE, 0xFD])
await bluetooth.write(hexData.buffer)

6. 断开连接

await bluetooth.disconnect(deviceId)

高级用法 - DeviceControl

DeviceControl 类提供命令-响应模式的数据交互：

import { DeviceControl } from '@/uni_modules/x-bluetooth/js_sdk/deviceControl.js'

const deviceControl = new DeviceControl({
    debug: true,
    serviceId: 'YOUR_SERVICE_UUID',
    writeCharacteristicId: 'YOUR_WRITE_UUID',
    notifyCharacteristicId: 'YOUR_NOTIFY_UUID'
})

// 连接设备
await deviceControl.connect(deviceId)

// 启用监听
await deviceControl.setNotify({})
deviceControl.startListenerCharacteristicValueChange((data) => {
    console.log('收到响应:', data.hex)
})

// 执行命令并等待响应
try {
    const cmdBuffer = num2ab([0x01, 0x02, 0x03, 0x04]) // 命令数据
    const response = await deviceControl.execCmd(cmdBuffer, 3000) // 3秒超时
    console.log('命令执行成功，响应:', response)
} catch (error) {
    console.error('命令执行失败:', error)
}

数据转换工具

ArrayBuffer 与十六进制

// ArrayBuffer 转十六进制字符串
const hexString = ab2hex(buffer) // "01 02 03 04"

// ArrayBuffer 转十六进制数组
const hexArray = ab2hexArr(buffer) // ["01", "02", "03", "04"]

字符串转换

// 字符串转 ArrayBuffer
const buffer = str2ab("Hello")

// ArrayBuffer 转字符串
const string = ab2str(buffer)

数字转换

// 单个数字转 ArrayBuffer（1字节）
const buffer1 = num2ab(255)

// 多个数字转 ArrayBuffer
const buffer2 = num2ab([0x01, 0x02, 0x03])

// 指定字节长度（2字节）
const buffer3 = num2ab(65535, 2)

// 数组转 ArrayBuffer
const buffer4 = arr2ab([1, 2, 3, 4])

ArrayBuffer 操作

// 合并多个 ArrayBuffer
const merged = abConcat(buffer1, buffer2, buffer3)

// 反转 ArrayBuffer
const reversed = abReverse(buffer)

错误处理

try {
    await bluetooth.init()
    await bluetooth.startFind(callback)
    await bluetooth.connect(deviceId)
} catch (error) {
    switch (error.message) {
        case '设备未连接':
            console.log('请先连接设备')
            break
        case '未找到设备, 请稍后再试':
            console.log('设备不在范围内')
            break
        case '响应超时':
            console.log('设备响应超时')
            break
        case '指令执行频繁':
            console.log('请等待上一个指令完成')
            break
        default:
            console.error('蓝牙操作失败:', error)
    }
}

注意事项

1. 平台兼容性：

   • Android：支持 MTU 设置
   • iOS：MTU 设置会被跳过，使用默认值

2. MTU 设置：

   • 建议值：22-512 字节
   • Android 需要等待 3 秒后设置
   • 发送数据不应超过 MTU 大小

3. 连接管理：

   • 同时只能连接一个设备
   • 连接新设备会自动断开旧连接
   • 建议使用单例模式

4. 数据发送：

   • iOS 使用 'write' 模式
   • Android 使用 'writeNoResponse' 模式
   • 可手动指定 writeType

5. 特征值自动发现：

   • 如果未指定 UUID，会自动查找可写入和可监听的特征值
   • UUID 会被转换为大写格式

完整示例

import { DeviceControl } from '@/uni_modules/x-bluetooth/js_sdk/deviceControl.js'
import { str2ab, num2ab } from '@/uni_modules/x-bluetooth/js_sdk/bufferConversion.js'

class MyBluetoothDevice {
    constructor() {
        this.device = new DeviceControl({
            debug: true,
            mode: 'name',
            filter: 'MyDevice',
            serviceId: 'FFF0',
            writeCharacteristicId: 'FFF1',
            notifyCharacteristicId: 'FFF2'
        })
    }

    async init() {
        // 开始扫描
        await this.device.startFind((device, devices) => {
            console.log(`发现设备: ${device.name}`)
        })

        // 等待找到设备后连接第一个
        setTimeout(async () => {
            if (this.device.devices.length > 0) {
                await this.connect(this.device.devices[0].deviceId)
            }
        }, 5000)
    }

    async connect(deviceId) {
        try {
            await this.device.connect(deviceId)
            await this.device.setNotify({})

            // 监听数据
            this.device.startListenerCharacteristicValueChange((data) => {
                console.log('收到数据:', data.hex)
            })

            console.log('设备连接并配置完成')
        } catch (error) {
            console.error('连接失败:', error)
        }
    }

    async sendCommand(cmd) {
        try {
            const cmdBuffer = num2ab(cmd)
            const response = await this.device.execCmd(cmdBuffer, 2000)
            return response
        } catch (error) {
            console.error('命令执行失败:', error)
            throw error
        }
    }
}

// 使用示例
const myDevice = new MyBluetoothDevice()
myDevice.init()

这个蓝牙模块为 uni-app 开发者提供了完整的 BLE 设备控制能力，支持设备扫描、连接管理、数据收发等功能，适用于各种蓝牙设备的集成开发。