更新记录

1.0.3（2026-07-24）

无

1.0.2（2026-07-24）

无

1.0.1（2026-07-24）

无

平台兼容性

uni-app(5.01)

uni-app x(5.01)

etalya-ring 接口文档

概述

etalya-ring 是一个 uni-app UTS 插件，通过 UTS 桥接层直连 CRP BLE SDK（my-ring-ble-1.2.0-20260522.aar），实现 MYRing 智能戒指的蓝牙扫描、连接和数据通信。

导入方式

import * as Ring from '@/uni_modules/etalya-ring'

所有 API 通过 Ring 对象调用。

运行环境

• HBuilderX 4.27+
• uni-app Vue 3 项目
• Android 6+（BLE 支持）
• Android 12+ 需额外声明 BLUETOOTH_SCAN / BLUETOOTH_CONNECT 权限

快速开始

import * as Ring from '@/uni_modules/etalya-ring'

// 1. 初始化 SDK
Ring.init()

// 2. 注册数据事件监听（接收设备推送数据）
Ring.onDataEvent((event) => {
  console.log(event.event, event.data)
})

// 3. 注册扫描事件监听
Ring.onScanEvent((result) => {
  if (result.type === 'scanning') {
    console.log('发现设备:', result.device)
  } else if (result.type === 'complete') {
    console.log('扫描完成, 共', result.count, '个设备')
  }
})

// 4. 检查蓝牙并开始扫描
if (Ring.isBluetoothEnabled()) {
  Ring.startScan()
}

// 5. 停止扫描
// Ring.stopScan()

// 6. 连接设备
// Ring.connect({ macAddress: 'XX:XX:XX:XX:XX:XX', callback: (ret) => { ... } })

// 7. 断开连接
// Ring.disconnect()

API 参考

初始化

Ring.init()

初始化 CRP BLE SDK，必须第一个调用。

• 参数: 无
• 返回: CallbackResult

const ret = Ring.init()
if (ret.code === 0) {
  console.log('初始化成功')
} else {
  console.error('初始化失败:', ret.msg)
}

蓝牙状态

Ring.isBluetoothEnabled(): boolean

检查手机蓝牙是否已开启。

if (Ring.isBluetoothEnabled()) {
  console.log('蓝牙已开启')
} else {
  console.log('请打开蓝牙')
}

数据事件

Ring.onDataEvent(callback)

注册设备数据事件监听（on 前缀自动保持回调存活）。连接设备后，所有健康数据（心率、步数、电量等）通过此回调推送。

• 参数:
  • callback: (event: DataEvent) => void

Ring.onDataEvent((event) => {
  console.log(event.event)     // 事件名，如 'onHeartRateChange'
  console.log(event.data)      // 事件数据对象
})

事件列表:

扫描

Ring.onScanEvent(callback)

注册扫描结果回调（on 前缀自动保持回调存活）。需在 startScan() 之前调用。

• 参数:
  • callback: (result: ScanResult) => void

Ring.onScanEvent((result) => {
  if (result.type === 'scanning') {
    // 每发现一个设备触发
    console.log('设备:', result.device.name, result.device.macAddress)
  } else if (result.type === 'complete') {
    // 扫描结束（有设备）
    console.log('共发现', result.count, '个设备')
  } else if (result.type === 'timeout') {
    // 扫描结束（无设备）
    console.log('未发现设备')
  }
})

ScanResult:

ScanDeviceResult:

Ring.startScan()

开始 BLE 设备扫描。

• 参数: 无
• 返回: CallbackResult

const ret = Ring.startScan()
if (ret.code !== 0) {
  console.error('启动扫描失败:', ret.msg)
}

说明: 扫描为连续模式，不会自动停止。SDK 内部会周期性地触发 onScanComplete 回调，插件会自动重启扫描保持连续。如需停止，手动调用 stopScan()。

Ring.stopScan()

停止扫描。

• 参数: 无
• 返回: CallbackResult

Ring.stopScan()

连接

Ring.connect(options)

连接指定 MAC 地址的戒指设备。

• 参数:

  • options.macAddress: string — 必填，设备 MAC 地址
  • options.callback: (state: ConnectionState) => void — 连接状态回调（可选）

• 返回: CallbackResult

Ring.connect({
  macAddress: 'XX:XX:XX:XX:XX:XX',
  callback: (state) => {
    console.log('连接状态:', state.stateText)
    // state: { state: 2, stateText: 'connected' }
    // state: { state: 0, stateText: 'disconnected' }
  }
})

ConnectionState:

Ring.disconnect()

断开当前连接。

• 参数: 无
• 返回: CallbackResult

Ring.disconnect()

Ring.isDeviceConnected(): boolean

查询当前设备是否已连接。

if (Ring.isDeviceConnected()) {
  console.log('设备已连接')
}

设备信息

Ring.queryFirmwareVersion()

查询固件版本信息。结果通过 onDataEvent('onFirmwareVersion', ...) 推送。

• 参数: 无
• 返回: CallbackResult

Ring.queryFirmwareHash()

查询固件哈希。

• 参数: 无
• 返回: CallbackResult

Ring.checkFirmwareVersion(options)

检查固件更新。

• 参数:
  • options.version: string — 当前固件版本号
• 返回: CallbackResult

Ring.queryBattery()

查询电池电量。结果通过 onDataEvent('onBattery', ...) 推送。

• 参数: 无
• 返回: CallbackResult

时间同步

Ring.syncTime()

同步手机当前时间到戒指。

• 参数: 无
• 返回: CallbackResult

Ring.syncTime()

用户信息

Ring.sendUserInfo(options)

发送用户信息到戒指（用于更精准的健康计算）。

• 参数:
  • options.weight: number — 体重(kg)
  • options.height: number — 身高(cm)
  • options.gender: number — 性别（0=女, 1=男）
  • options.age: number — 年龄
  • options.stepLength: number — 步长(cm)
• 返回: CallbackResult

Ring.sendUserInfo({
  weight: 65,
  height: 170,
  gender: 1,
  age: 30,
  stepLength: 70
})

设备控制

以下方法均通过 onDataEvent 推送回调结果。

类型定义

CallbackResult

type CallbackResult<T = any> = {
  code: number    // 0=成功, 非0=错误
  msg: string     // 描述信息
  data?: T        // 返回数据（可选）
}

ScanDeviceResult

type ScanDeviceResult = {
  name: string                 // 设备名称
  macAddress: string           // MAC 地址
  rssi: number                 // 信号强度 (dBm)
  deviceId?: string            // 固件类型标识
}

ConnectionState

type ConnectionState = {
  state: number                // 0=断开, 1=连接中, 2=已连接
  stateText: 'disconnected' | 'connecting' | 'connected'
}

DataEvent

type DataEvent = {
  event: string                // 事件名称
  data: any                    // 事件数据
}

注意事项

1. on 前缀函数

onScanEvent 和 onDataEvent 以 on 开头且仅有单个 callback 参数，UTS 运行时自动保持回调存活，支持多次触发。

2. 扫描为连续模式

startScan() 会持续扫描直到手动调用 stopScan()。SDK 内部周期结束会自动重启。

3. Android 运行时权限

BLE 扫描需要运行时动态请求权限：

建议在调用 startScan() 前使用 plus.android.requestPermissions() 请求权限。

4. AAR 依赖路径

SDK AAR 文件位于 utssdk/app-android/libs/ 目录，路径在 utssdk/app-android/config.json 中声明。

5. UTS 桥接限制

6. 修改 .uts 无需重打基座

开发模式下，修改 .uts 文件后直接运行到手机即可生效，无需重新打包自定义基座。

如需更换 AAR 依赖（如更新 SDK 版本），需修改 config.json 后重新运行。