更新记录

1.0.5（2026-07-10）

sdk 104 版本更新

1.0.0（2025-12-20）

一、首次提交

平台兼容性

uni-app(4.62)

uni-app x(4.76)

hl-iuhfq-uts — 设备型号=T91 Pro, iData Q3000 UHF RFID 读写器插件

基于 iUHFQ SDK V1.0.4，封装为 uni-app UTS 插件，支持 Android 平台。

这个插件能做什么？

• 读写 RFID 标签：盘点、读取、写入、锁定、销毁
• 蓝牙连接：扫描并连接 Q3000 蓝牙读写器
• 设备配置：功率、Session、盘点模式、区域、蜂鸣器等
• 固件升级：模块固件 + Q3000 固件

快速开始

第 1 步：导入插件

在页面中引入插件并获取客户端实例：

import { getUhfClient } from '@/uni_modules/hl-iuhfq-uts'
const uhf = getUhfClient()

第 2 步：注册标签回调（页面加载时）

必须做：在 onLoad 里注册回调，否则盘点时收不到标签数据。

import { onLoad, onUnload } from '@dcloudio/uni-app'

onLoad(() => {
  uhf.onTagCallback((res) => {
    if (res.code !== 0) return

    if (res.type === 'tagReport') {
      // 盘点到标签：res.epc / res.tid / res.count
      console.log('标签:', res.epc, 'TID:', res.tid)
    } else if (res.type === 'inventoryRate') {
      // 盘点速率：res.rate（标签/秒）
      console.log('速率:', res.rate)
    } else if (res.type === 'log') {
      // 诊断日志（排查问题时会用到）
      console.log('日志:', res.message)
    }
  })
})

第 3 步：初始化设备

有两种初始化方式，根据设备类型选择：

// 方式一：内置串口设备（直接初始化）
uhf.initDevice({ mode: 1 }, (res) => {
  if (res.code === 0) {
    console.log('初始化成功:', res.deviceModel)
    // 可以开始盘点或配置参数了
  } else {
    console.log('初始化失败:', res.message)
    // 如果失败，可能是蓝牙外接设备，请走方式二
  }
})

// 方式二：蓝牙外接 Q3000（先扫描再连接）
// 1. 扫描蓝牙设备
uhf.scanBluetooth((res) => {
  if (res.type === 'log') {
    console.log(res.message)  // 诊断日志
  }
  if (res.code === 0 && res.type === 'btDevice') {
    // res.devices 是扫描到的设备列表 [{name, mac, rssi}]
    // 选择 Q3000 设备进行连接
    const target = res.devices.find(d => d.name.includes('Q3000'))
    if (target) {
      // 2. 连接设备（连接成功后自动初始化）
      uhf.connectBluetooth({ mac: target.mac, mode: 1 }, (res) => {
        if (res.type === 'log') console.log(res.message)
        if (res.type === 'btConnected') {
          console.log('蓝牙连接并初始化成功')
          // 可以开始盘点了
        }
      })
    }
  }
})

第 4 步：开始盘点

// 最简单的方式：只盘 EPC（与官方 demo 一致，兼容性最好）
uhf.startInventory((res) => {
  if (res.code === 0) {
    console.log('盘点已开始，标签数据通过 onTagCallback 回调')
  }
})

// 需要高级配置时：
uhf.startInventoryEx(
  {
    readMode: 0,        // 0:仅EPC(推荐) / 1:EPC+TID / 2:EPC+TID+USER
    invMode: 0,         // 0:远距离 / 1:多标签
    enableFastId: true,
    isFilter: false     // true 时需设置 filterBank/filterAddress/filterLength/filterData
  },
  (res) => {
    if (res.code === 0) console.log('盘点已开始')
  }
)

// 停止盘点
uhf.stopInventory((res) => {
  // res.totalTags / res.uniqueTags / res.lastRate
})

接口列表

设备管理

盘点

参数配置

标签读写

存储区（bank）说明：0-保留区 / 1-EPC / 2-TID / 3-USER

// 读标签示例
uhf.readTag({ bank: 1, address: 2, length: 4, password: '00000000' }, (res) => {
  if (res.code === 0) console.log('读取数据:', res.readData)
})

// 写标签示例
uhf.writeTag({ bank: 1, address: 2, data: '30001234', password: '00000000' }, (res) => {
  if (res.code === 0) console.log('写入成功')
})

蓝牙

固件升级

uhf.updateModuleFirmware({ path: '/sdcard/module.bin' }, (res) => {
  if (res.type === 'firmwareProgress') console.log('进度:', res.progress + '%')
  if (res.type === 'firmwareSuccess') console.log('升级完成')
})

回调数据结构

所有接口的回调都返回 HlIuhfqUtsResult：

type 字段含义：

诊断日志

插件内置全链路诊断日志，通过 type='log' 回传前端，方便排查问题：

uhf.onTagCallback((res) => {
  if (res.type === 'log') {
    console.log(`[${res.level}] ${res.message}`)
    // 在日志面板显示：addLog(res.message, res.level)
  }
})

日志覆盖范围：设备初始化每一步、蓝牙状态/权限/扫描流程、SDK 回调、异常堆栈、系统信息（型号/品牌/系统版本）。

Demo 页面说明

每个页面的操作日志区域都有「复制」按钮，可以一键复制日志发给开发者排查问题。

注意事项

1. 先初始化再操作：所有读写/盘点操作前必须先 initDevice 或 connectBluetooth 成功
2. 内置设备 vs 蓝牙设备：
   • 内置串口设备 → 用 initDevice
   • 蓝牙外接 Q3000 → 用 scanBluetooth + connectBluetooth（连接成功自动初始化）
   • 如果 initDevice 失败，大概率是蓝牙外接设备，请改走蓝牙连接
3. 盘点模式：readMode=0（仅 EPC）兼容性最好，与官方一致；readMode=1/2（读 TID/USER）部分设备可能不兼容
4. 回调注册：页面 onLoad 必须调用 onTagCallback，否则收不到标签数据
5. 及时断开：页面 onUnload 中调用 disconnect，释放设备连接