更新记录

0.2.0（2026-08-03）

增加了ios，测试了2款产品

0.1.0（2026-08-01）

新版本，后续会加上ios

平台兼容性

uni-app(5.07)

color-meter-ble

深圳市澳美科技有限公司笔式便携检测仪的 BLE 通讯插件，适用于 uni-app App-Android 和 App-iOS。iOS 端已新增基于系统 CoreBluetooth 的实现，与 Android 共用同一套 UTS API、事件名称和设备通信协议。

该硬件为便携式色差仪，用于采集物体颜色、对比色差，支持获取 Lab、RGB 等颜色数据。

产品用途

• 涂料、皮革、印刷、车漆调色等颜色采集与色差对比场景
• 读取仪器采集的 Lab、RGB、光谱测量数据和电量等状态
• 执行黑校准、白校准、测量、显示参数和颜色容差配置

使用说明

1. 开启仪器和手机蓝牙，在 App 中授予蓝牙权限。
2. 调用 startScan('CM') 扫描仪器，默认仅显示名称以 CM 开头的设备。
3. 连接设备，收到 connected 事件后再发送测量或读取指令。
4. 将仪器底部感光口紧贴被测物体的平整表面，避免环境光从缝隙进入。
5. 调用 measure(0) 采集颜色，再调用 readLabData(0) 或 readRgbData(0) 读取色值。

仪器默认会休眠。插件每次发送业务命令前均先发送 0xF0 唤醒帧，并等待 100ms 后再发送正式命令，满足仪器至少等待 50ms 的通信要求。

Android 的 deviceId 是设备 MAC 地址；iOS 的 deviceId 是 CoreBluetooth 返回的 Peripheral UUID。两端都应直接使用 scanResult 事件返回的值。

蓝牙配置

• 扫描名称前缀可选；本插件示例默认使用 CM，传空字符串时不过滤设备名称
• 服务 UUID：0000FFE0-0000-1000-8000-00805F9B34FB
• 写入和通知特征 UUID：0000FFE1-0000-1000-8000-00805F9B34FB
• 协议帧：BB + 命令 + 数据 + FF + 累加和

插件内部负责运行时权限、扫描、连接、通知、20 字节写入分片、响应组帧、校验和、超时及重试。

基本使用

import {
  onBleEvent,
  requestBlePermissions,
  startScan,
  connect,
  measure,
  readMeasureData
} from '@/uni_modules/color-meter-ble'

onBleEvent((eventJson) => {
  const event = JSON.parse(eventJson)
  console.log(event.type, event)
})

if (requestBlePermissions()) {
  startScan('CM')
}
connect(deviceIdFromScanResult)
measure(0)
readMeasureData(0)

requestBlePermissions() 返回 true 表示当前已经具备权限；返回 false 表示已发起系统权限请求或请求失败。用户完成授权后再次调用 startScan('CM')。

Android 与 iOS 一致用法

页面层调用方式完全一致，不需要通过 uni.getSystemInfo() 判断 Android 或 iOS。设备标识只应取自当前平台 scanResult 事件的 deviceId，再原样传给 connect()。

import {
  close,
  connect,
  onBleEvent,
  readLabData,
  requestBlePermissions,
  startScan
} from '@/uni_modules/color-meter-ble'

export default {
  onLoad() {
    onBleEvent((eventJson) => {
      const event = JSON.parse(eventJson)

      if (event.type === 'scanResult') {
        // Android 返回 MAC 地址，iOS 返回 Peripheral UUID，均可直接传给 connect。
        connect(event.deviceId)
      }

      if (event.type === 'connected') {
        readLabData(0)
      }

      if (event.type === 'labData') {
        console.log('Lab:', event.lab)
      }

      if (event.type === 'commandError') {
        console.error(event.errCode, event.errMsg)
      }
    })

    if (!requestBlePermissions()) {
      return
    }
    startScan('CM')
  },
  onUnload() {
    close()
  }
}

首次调用 requestBlePermissions() 时，Android 可能弹出附近设备或定位权限窗口，iOS 会在创建蓝牙管理器时弹出系统蓝牙授权窗口。授权完成后重新调用 startScan('CM') 即可。

API

setDisplayParams 使用协议值：光源 0-25，角度 0=2°/1=10°，测量模式 0-2，颜色空间 0-20，色差公式 0-6。

事件

通用字段为 type 和 timestamp。主要事件：

• 连接：scanStarted、scanResult、scanStopped、connecting、connected、servicesDiscovered、notifyEnabled、disconnected
• 测量：measure、measureData、labData、rgbData
• 设备：deviceInfo、power、adjustState
• 设置：blackAdjust、whiteAdjust、displayParamsSet、toleranceSet、timeSynced
• 异常：commandRetry、commandError

commandError 包含 errCode、errMsg，与 utssdk/unierror.uts 中的定义一致。

限制

• 当前支持传统 uni-app 的 App-Android 和 App-iOS，暂不支持 uni-app x、Web 或小程序。
• 本插件仅适配深圳市澳美科技有限公司该笔式便携检测仪的 BLE 服务与通信协议。
• 设备信息的 200 字节结构按厂家 Demo 解析。
• 厂家协议中的标样和试样管理命令尚未纳入第一版。

iOS 配置

• 最低系统版本：iOS 12.0。
• 插件内置 NSBluetoothAlwaysUsageDescription 和 NSBluetoothPeripheralUsageDescription 蓝牙用途说明。
• iOS 不需要 Android 的定位或附近设备权限；首次初始化 CBCentralManager 时由系统弹出蓝牙授权窗口。
• 当前没有声明 UIBackgroundModes，应用进入后台后不保证继续扫描或通信。

iOS 实现说明

• 已实现扫描、连接、服务与特征发现、通知订阅、指令发送、20 字节分片写入、响应组帧、校验和、超时重试和资源释放。
• iOS 使用系统 CoreBluetooth，不依赖厂商 iOS 二进制 SDK、CocoaPods 或额外 Framework。
• iOS 的 deviceId 是系统分配的 Peripheral UUID，不是 Android MAC 地址；必须直接使用本次 scanResult 事件返回的 deviceId 连接设备。
• iOS 扫描、连接和读写需在真机验证，模拟器不具备可用的 BLE 外设通信能力。
• 在 Windows 环境下可通过 HBuilderX 云端打包 iOS 自定义基座或正式包验证插件；本地编译、Swift 断点调试仍需要 macOS 与 Xcode。