[UTS蓝牙插件文档] batchWriteBLECharacteristicValue 接口描述

用法：batchWriteBLECharacteristicValue(OBJECT)

用途：此接口会自动在底层分包然后向低功耗蓝牙设备特征值中写入二进制数据。注意：必须设备的特征值支持 write 才可以成功调用。

传输时间的测试条件和结果比较：

• 蓝牙模块：XY-MBA32A
• 蓝牙模块的波特率：115200
• 蓝牙模块的MTU：23
• 蓝牙模块的传输间隙：固件默认（对照测试时，没有通过任何蓝牙API进行更改）
• 周边的蓝牙设备数量：20+
• 测试手机：红米note9，OPPO reno5, 红米k60pro, 三星S23Ultra...
• batchWriteBLECharacteristicValue 接口：0.4到0.8s
• writeBLECharacteristicValue 接口：2s+

OBJECT 参数说明

属性	类型	默认值	必填	说明
deviceId	string		是	蓝牙设备 id
serviceId	string		是	蓝牙特征值对应服务的 uuid
characteristicId	string		是	蓝牙特征值的 uuid
characteristicHandle	number		是	蓝牙特征值的 实例id，仅uuid重复出现时可用于区分特征实例，仅Android可用
value	ArrayBuffer或number[]		是	蓝牙设备特征值对应的二进制值
size	number		是	每次发送的分包大小，建议传入20
writeType	string		是	蓝牙特征值的写模式设置，有两种模式，iOS 优先 write，安卓优先 writeNoResponse 。
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

writeType

属性	说明
write	强制回复写，不支持时报错
writeNoResponse	强制无回复写，不支持时报错

错误

错误码	错误信息	说明
0	ok	正常
-1	already connect	已经连接（WX特性）
10000	not init	未初始化蓝牙适配器
10001	not available	当前蓝牙适配器不可用
10002	no device	没有找到指定设备
10003	connection fail	连接失败
10004	no service	没有找到指定服务
10005	no characteristic	没有找到指定特征值
10006	no connection	当前连接已断开
10007	property not support	当前特征值不支持此操作
10008	system error	其余所有系统上报的异常
10009	system not support	Android 系统特有，系统版本低于 4.3 不支持 BLE
10010	already connect	已连接（UNI特性）
10011	need pin	配对设备需要配对码
10012	operate time out	连接超时
10013	invalid_data	连接 deviceId 为空或者是格式不正确

注意

1. MTU虽然大，并且 size 参数也给了接近MTU的值，速度并不比只发送20个字节快多少？

   • 即使MTU增大，如果通信周期（connection interval）较长或者连接间隔没有相应优化，两次传输之间的时间增加可能会抵消掉因MTU增大而获得的潜在速度提升。
   • 建议 size 参数赋值为20，稳定性极佳，速率又比 writeBLECharacteristicValue 接口高

2. 暂时不建议使用此接口传输超过 10KB 的包（发送一次可能要花费1s+以上，包越大越久）

   • 因为现在还未实现取消发送和发送进度通知的能力，如果发送太大的数据包，会导致此接口无法在短时间内success或者fail，用户无法得知进度而体验较差
   • 建议先分包为4KB，然后再调用本接口发送，后期开发者会尽快优化此问题

3. 在鸿蒙NEXT上，由于鸿蒙的原生API的缘故，会导致此接口出现一定概率的丢包，为了减少丢包，你可能需要以下操作：

   • 降低 batchWriteBLECharacteristicValue 接口的调用频率，也就是在每次调用此接口之间添加一定的延时（慢慢尝试，从10ms开始测试，找到一个符合你的设备的连接间隙和MTU大小的间隔时间值）

     鸿蒙底层的 writeCharacteristicValue 原生接口，发送实际上只是把数据放到缓冲区，回调成功不代表已经发送出去，如果太快调用会导致缓冲区溢出从而丢包

     建议调试一下BLE设备，如果是BLE转UART可以看UART多久收到你发送的整个大数据包，然后对比发送成功的回调的执行时间，将接口调用的延迟设置为UART收到完整包的时间 + 100ms，差不多就能稳定发送。

   • 如果可以设置设备的MTU的话，调用一下 setBLEMTU 接口提高一下MTU，然后把此接口的 size 设置为100以上是最佳速率的体现

如果可以，尽量不要在鸿蒙NEXT设备上使用此接口，因为鸿蒙NEXT还在迭代，有些接口还是存在不稳定因素的。
如果项目或者领导期望非常高，建议直接放弃期望。DCLOUD官方本身也不建议抱太高期望去移植UNIAPP的工程到鸿蒙NEXT上

示例代码

UniAppX:

// 20250618 tips更新：DCLOUD官方添加了对 ArrayBuffer 和 DataView 的 UniappX 支持，但是此插件很多工程在使用，因此无法轻易修改接口定义，请开发者自行处理类型转换的问题（可用Array.from() 之类的函数进行转换）。
let dataBytes: number[] = [0x00, 0x01, 0x02];
UTSBLE.batchWriteBLECharacteristicValue({
  // 这里的 deviceId 需要在 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取
  deviceId,
  // 这里的 serviceId 需要在 getBLEDeviceServices 接口中获取
  serviceId,
  // 这里的 characteristicId 需要在 getBLEDeviceCharacteristics 接口中获取
  characteristicId,
  // 仅支持 number[] 类型
  value: dataBytes,
  success(res) {
    console.log('batchWriteBLECharacteristicValue success', res.errMsg)
  }
} as BatchWriteBLECharacteristicValueOptions)

UniAppJS:

// 向蓝牙设备发送一个0x00的16进制数据
const buffer = new ArrayBuffer(1)
const dataView = new DataView(buffer)
dataView.setUint8(0, 0)
UTSBLE.batchWriteBLECharacteristicValue({
  // 这里的 deviceId 需要在 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取
  deviceId,
  // 这里的 serviceId 需要在 getBLEDeviceServices 接口中获取
  serviceId,
  // 这里的 characteristicId 需要在 getBLEDeviceCharacteristics 接口中获取
  characteristicId,
  // UTS插件目前只支持number[]类型，但是很多官方的实例代码都是 ArrayBuffer 类型，因此插件开发者在 BLE.js 做了自动转换的过程
  // 但是开发者如果可以办到，请在传入的时候改为使用 number[] 类型
  // 如果不使用 BLE.js 或者上述的开源例程中的 ble.uts 进行接口调用，那就必须要传入 number[] 类型！！！否则可能导致闪退或其他的异常
  value: buffer,
  success(res) {
    console.log('batchWriteBLECharacteristicValue success', res.errMsg)
  }
})