更新记录

1.0.1（2026-07-03）

文档优化

1.0.0（2026-07-03）

首次提交

平台兼容性

uni-app(4.81)

uni-app x(4.82)

hl-hband-sdk

HBand / Veepoo 蓝牙手环 SDK 的 UniApp UTS 原生插件。业务侧只需 import * as HBand from '@/uni_modules/hl-hband-sdk'，无需直接接触 Android AAR / iOS Framework。

支持平台：App Android、App iOS（需自定义基座或云打包）。H5 / 小程序 / HarmonyOS 不支持。

目录

• 使用前准备
• 5 分钟上手
• 标准调用流程
• 通用约定
• 完整 API 列表
• 分模块示例
• invokeSpecialModule 专项能力
• 错误码
• Demo 与延伸阅读

使用前准备

1. 安装插件

将 uni_modules/hl-hband-sdk 放入项目，HBuilderX 识别为 UTS 插件。

2. 制作自定义调试基座

插件含原生 AAR / Framework，标准基座无法使用。菜单：运行 → 运行到手机或模拟器 → 制作自定义调试基座，编译成功后用自定义基座运行。

3. 系统权限

4. 导入方式（固定写法）

import * as HBand from '@/uni_modules/hl-hband-sdk'

不要导入 utssdk/app-android/index.uts 等平台文件。

5. iOS 特别注意

• 必须先 startScan() 扫到设备，再 connectDevice(mac, name)（SDK 依赖扫描得到的 peripheral）。
• 三方 Framework 已随插件携带；若遇旧版 pod install / UIKit 报错，清理 UTS/iOS 编译缓存后重编基座。

5 分钟上手

import * as HBand from '@/uni_modules/hl-hband-sdk'
import { onUnmounted } from 'vue'

// 1. 初始化
HBand.initSDK()

// 2. 可选：看插件日志
HBand.enableDebugLog((level, tag, msg) => {
  console.log(`[${level}] ${tag}: ${msg}`)
})

// 3. 扫描
HBand.startScan(
  (device) => console.log('发现设备', device.name, device.mac, device.rssi),
  () => console.log('扫描结束'),
  (code, msg) => console.error('扫描失败', code, msg)
)

// 4. 连接 + 校验密码（默认密码多为 0000）
HBand.connectDevice(mac, name, (event) => {
  console.log(event.status, event.message)
  if (event.status == 'connected' || event.status == 'notifyReady') {
    HBand.verifyPassword({ password: '0000', is24Hour: true }, (result) => {
      if (result.code == 0) {
        // 5. 校验成功后再读数据
        HBand.readBattery(console.log)
        HBand.readStep(console.log)
      }
    })
  }
})

// 6. 页面退出时释放
onUnmounted(() => {
  HBand.stopScan()
  HBand.destroySDK()
})

新手易错点：

1. 未做自定义基座 → 原生方法找不到。
2. 未 verifyPassword 就调业务指令 → 返回未连接或设备未就绪。
3. 测量、OTA、表盘传输、历史同步等长流程并发调用 → 请串行排队。
4. 每个回调先判断 result.code == 0 再读 result.data。
5. iOS 未先扫描就连接 → 连接失败。

标准调用流程

initSDK()
  → startScan() 发现设备
  → connectDevice(mac, name)
  → 收到 connected / notifyReady
  → verifyPassword({ password, is24Hour })
  → 收到 verified（或 verifyPassword 回调 code==0）
  → readBattery / startMeasure / syncData / 高级 API ...
  → 页面卸载：stopScan() + destroySDK()

通用约定

HBandResult（多数指令的回调结构）

HBandConnectionEvent（连接回调）

HBandDevice（扫描结果）

HBandMeasureEvent（实时测量 / 微体检等）

完整 API 列表

以下与 utssdk/interface.uts 一一对应。带 callback 的均为异步；无 callback 的为同步或 fire-and-forget。

一、初始化 / 扫描 / 连接（13 个）

二、基础数据读写（4 个）

HBandPersonalInfo：

三、语言 / 基础开关 / 通知（8 个）

readBaseFunction / setBaseFunction 常用 type：

metric、timeFormat、automaticHeartRate、automaticBloodPressure、findPhoneUi、stopwatch、oxygenLowRemind、wearDetection、automaticHrv、disconnectRemind、sos、ppg、musicControl、longpressUnlock、messageScreenLight、automaticTemperature、automaticBloodGlucose、stress、met（Android 梅脱）、ecgAlwaysOpen（iOS）

setPhoneControlListener（Android）：一次注册同时监听来电控制与音乐键事件。

配合 sendNotification({ type: 'call', ... }) 推送来电；收到音乐 event 后由 App 联动系统媒体播放 API。

通知 type：all、call、sms、wechat、qq、sina、facebook、twitter、***、line、instagram、telegram、messenger、other 等（Android 另支持 zalo、viber）。

sendNotification 参数：{ type, title, content, contactName, phoneNumber }

syncData options：

{
  dataType: 'all',      // 见平台差异表
  dayNumber: 0,         // 0=今天，1=昨天…
  : (progress, state) => {},
  onData: (dataType, data) => {},
  onFinish: (result) => {}
}

四、实时测量 / 拍照 / 查找（8 个）

startMeasure / stopMeasure 支持 type：

heartRate、bloodOxygen、bloodPressure、breath、fatigue、temperature、bloodGlucose、stress、hrv、gsr

五、闹钟 / 联系人 / SOS（6 个）

manageAlarm options：

HBandAlarmItem：id, hour, minute, enabled, repeatDays, singleDate, scene, content

manageContacts：

六、天气 / 世界时钟（4 个）

七、运动模式（4 个）

八、表盘 / OTA / 杰理认证（6 个）

transferDial options：{ dialType, platform, filePath, screenIndex?, photoLayout?, ?, onFinish? }

dialType 扩展：agps / g15_profile / g15_theme1 / g15_theme2 / g15_qrcode / market / server / photo / custom

startOtaUpgrade options：{ platform, firmwarePath, ?, onFinish? }

platform：Android jl / nordic / nrf / zk；iOS remote / local

九、蓝牙通话 BT（5 个）

十、ECG 心电（6 个）

十一、设备设置 / 校准 / 历史 / 微体检（20 个）

readDeviceSetting / setDeviceSetting 的 type：

raiseHand、brightness、screenTimeout、heartAlarm、screenStyle、healthReminder、longSit、femaleHealth、lowPower、countDown、antiLoss、bpFunction、bloodOxygenNight、wearCheck

screenStyle 也可通过 readDialInfo / setActiveDial 操作。

readManualMeasureHistory options：{ timestamp, dataType }

• timestamp：秒级，只返回该时间之后的数据
• dataType：all / heartRate / bloodPressure / bloodOxygen / bloodGlucose / bloodComponents / temperature / healthGlance

readPrivateMeasureMode type：bloodPressure / bloodGlucose / bloodGlucoseMulti / bloodComponent / bloodAnalysis

readHealthHistory type：origin / oxygen / hrv / sleep / drink（Android）/ chanting

• date：yyyy-MM-dd，或 dayNumber 字符串 "0"（今天）/ "1"（昨天）；chanting 可传秒级 timestamp 字符串

readApneaRemind / setApneaRemind（双端支持）：

setApneaRemind 入参（未传字段使用默认值）：

readApneaRemind / setApneaRemind 成功时 data 常见字段：

失败时返回 -7081。

resetDevice mode：

readConnectedRssi 成功时 data.rssi 为当前连接信号强度。

controlMusic action：play / pause / next / previous / volumeUp / volumeDown / readVolume / setVolume

十二、身体成分 / 血液成分 / 健康监测 / 密码 / 来电（12 个）

readHealthMonitor / setHealthMonitor 的 type：

heartRate / bloodOxygen / bloodPressure / temperature / bloodGlucose / stress / hrv

（也支持别名如 heart、oxygen、glucose）

分模块示例

基础读写

HBand.readBattery((r) => {
  if (r.code == 0) console.log('电量', r.data['batteryPercent'])
})

HBand.syncPersonalInfo({
  sex: 'male', height: 170, weight: 65,
  age: 30, birthYear: 1996, stepGoal: 8000, sleepGoal: 480
}, console.log)

HBand.setBaseFunction('automaticHeartRate', true, console.log)

实时测量（含私人模式）

HBand.startMeasure('bloodPressure', (e) => {
  console.log(e.stage, e.value, e.progress)
}, { mode: 'private' })

HBand.stopMeasure('bloodPressure', console.log, { mode: 'private' })

闹钟与联系人

HBand.manageAlarm({
  alarmType: 'scene',
  operation: 'add',
  alarm: {
    id: 1, hour: 7, minute: 30, enabled: true,
    repeatDays: '0111110', singleDate: null, scene: 1, content: null
  }
}, console.log)

HBand.manageContacts('add', [{
  id: 1, name: '张三', phoneNumber: '***', isSos: false
}], null, null, console.log)

表盘与 OTA

HBand.readDialInfo(console.log)

HBand.setActiveDial(0, 'default', console.log)

HBand.transferDial({
  dialType: 'photo', // 或 g15_profile / g15_theme1 / g15_theme2 / g15_qrcode / agps
  platform: 'jl',
  filePath: '/storage/emulated/0/Download/dial.bin',
  screenIndex: 0,
  photoLayout: null,
  : (p, stage) => console.log(stage, p),
  onFinish: console.log
})

HBand.startOtaUpgrade({
  platform: 'jl', // nordic / nrf / zk
  firmwarePath: '/storage/emulated/0/Download/firmware.bin',
  : (p, stage) => console.log(stage, p),
  onFinish: console.log
})

HBand.startJlDeviceAuth((r) => {
  if (r.code == 0) HBand.checkFirmwareUpdate(console.log)
})

来电与音乐键监听（Android）

// 一次注册，同时覆盖来电控制 + 手环音乐键
HBand.setPhoneControlListener((event) => {
  if (event.event == 'rejectPhone' || event.event == 'cliencePhone') {
    console.log('来电控制', event.event)
  } else if (event.event == 'nextMusic' || event.event == 'playMusic') {
    // 联动系统媒体 API：下一曲 / 播放等
    console.log('音乐键', event.event)
  }
})

// 推送来电到手环
HBand.sendNotification({
  type: 'call',
  title: '来电',
  content: '***',
  contactName: '张三',
  phoneNumber: '***'
}, console.log)

ECG

HBand.startEcgMeasure({ needCurve: true, multiLead: false }, (e) => {
  console.log(e.stage, e.progress, e.data)
})
HBand.stopEcgMeasure(console.log)

历史同步

HBand.syncData({
  dataType: 'all',
  dayNumber: 0,
  : (p, s) => console.log(p, s),
  onData: (type, data) => console.log(type, data),
  onFinish: console.log
})

恢复出厂 / 呼吸暂停 / 免打扰

// 读取呼吸暂停（血氧）提醒配置
HBand.readApneaRemind((r) => {
  if (r.code == 0) {
    console.log('已开启', r.data['enabled'])
    console.log('低血氧阈值', r.data['lowOxygenValue'])
  }
})

// 设置呼吸暂停提醒（未传字段使用默认值，见上文表格）
HBand.setApneaRemind({
  enabled: true,
  startHour: 22,
  startMinute: 0,
  endHour: 8,
  endMinute: 0,
  durationTime: 10,
  remindTime: 5,
  lowOxygenValue: 90
}, console.log)

// 免打扰：标准 SDK 无专用协议，双端返回 -7072，请在 App 端按时段拦截 sendNotification
HBand.readDoNotDisturb(console.log)

// 清除设备数据（慎用，设备可能关机并断开）
HBand.resetDevice('clear', console.log)

invokeSpecialModule 专项能力

统一入口，适合定制项目设备：

HBand.invokeSpecialModule('jh58', 'readHistory', {
  date: '2026-06-12 10:00:00',
  testMode: 'MODE1'
}, console.log)

具体 params 以设备 SDK 文档为准；失败常见 code: -7101。

错误码

Demo 与延伸阅读

开发与扩展约定

1. 业务只依赖 @/uni_modules/hl-hband-sdk，不引用 utssdk/app-android/* 等平台文件。
2. 新增 API 顺序：interface.uts → app-android/index.uts + Hybrid.kt / HybridModules.kt → iOS 对应文件。
3. 原生层统一返回 HBandResult，不把 SDK 原始 listener 泄漏到 JS。
4. 长流程（测量、同步、OTA、表盘）串行调用；页面 onUnload 调用 destroySDK()。
5. 不同设备固件能力差异大，务必先读 verifyPassword 返回的 data.capability 再调高级功能。

平台与环境（技术附录）