starcloud-sdk-uniapp/uni.md

说明

星云SDK-Uni版是一款专为Uniapp开发者打造的智能锁SDK，旨在简化与智能锁与星云平台的交互。通过封装底层操作，使接入者无需关注锁的操作逻辑，能够将更多精力集中在业务开发中。

引用

npm install star-cloud-uni

公共参数

Result 方法的统一返回结构

// Result类是所有有返回结果的方法，统一的返回结构，以下接口文档的返回只列出data中的数据结构
import {Result} from 'star-cloud-uni'
// Result.Success中code=0，message='成功'，data根据不同方法返回不同数据，默认为{}
const {code, data, message} = Result.Success
// 常用判断方式
if (code === Result.Success.code) {
    // 逻辑代码   
} else {
    // 错误处理
}

code	变量名	描述（message）
0	Success	成功
-1	Fail	失败
-10	NotMoreData	没有更多数据
-20	NotAvailableBluetooth	蓝牙尚未打开，请先打开蓝牙
-21	NotAvailableBluetoothPermission	小程序蓝牙功能被禁用，请打开小程序蓝牙权限
-22	NotAvailableWeChatNearbyDevicesPermission	蓝牙功能需要附近设备权限，请前往设置开启微信的附近设备权限后再试
-23	NotAvailableWeChatLocationPermission	蓝牙功能需要定位权限，请前往设置开启微信的定位权限后再试
-24	NotAvailableWeChatNearbyDevicesEmpty	蓝牙功能需要定位服务，请前往设置开启定位服务后再试
-25	NotAvailableWeChatBluetoothPermission	微信的蓝牙权限被禁用，请前往设置开启微信的蓝牙权限后再试
-30	DeviceHasBeenReset	设备已被重置
251	ReadyHasPassword	该密码已存在

AccountInfo 账号信息

参数名称	数据类型	描述
uid	Number	用户uid
username	String	用户名
password	String	密码

LockInfo 锁信息

参数名称	数据类型	描述
deviceId	String	设备 ID
serviceId	String	服务 ID
notifyCharacteristicId	String	通知特征值 ID
writeCharacteristicId	String	写入特征值 ID
pwdTimestamp	Number	密码时间戳（毫秒）
featureValue	String	功能值
featureSettingValue	String	功能设置值
featureSettingParams	Array.<Number>	功能设置参数
lockUserNo	Number	锁用户编号
lockId	Number	锁 ID
keyId	Number	钥匙 ID
adminPwd	String	管理密码
bluetooth	Bluetooth	蓝牙信息
lockConfig	LockConfig	锁配置信息

Bluetooth 蓝牙信息

参数名称	数据类型	描述
bluetoothDeviceId	String	蓝牙设备 ID
bluetoothDeviceName	String	蓝牙设备名称
publicKey	Array.<Number>	公钥
privateKey	Array.<Number>	私钥
signKey	Array.<Number>	签名密钥

LockConfig 锁配置信息

参数名称	数据类型	描述
vendor	String	厂商
product	Number	产品号
model	String	型号
fwVersion	String	固件版本
hwVersion	String	硬件版本
serialNum0	String	序列号 0
serialNum1	String	序列号 1
btDeviceName	String	蓝牙设备名称
electricQuantity	Number	电量
electricQuantityStandby	Number	备用电量
restoreCount	Number	重置次数
restoreDate	Number	重置日期（时间戳秒）
icPartNo	String	芯片型号
indate	Number	入网日期（时间戳秒）
mac	String	MAC 地址
timezoneOffset	Number	时区偏移（秒）

初始化

初始化星云

调用方法

import {init} from 'star-cloud-uni'

init(params)

入参

参数名称	数据类型	必须	描述
clientId	String	Y	客户端Id
clientSecret	String	Y	客户端密码
env	String	Y	环境('SKY'：斯凯环境 'XHJ'：鑫泓佳环境)
accounts	Array<AccountInfo>	Y	账号列表，后续方法中需传入uid，若未传入则默认使用第一个账号
isReportLog	Boolean	N	是否上报日志，默认不上报

返回
无

用户

注册

调用方法

import {register} from 'star-cloud-uni'

register()

入参
无

返回

参数名称	数据类型	描述
username	String	用户名
password	String	密码
uid	Number	用户uid

退出登录

调用方法

import {logout} from 'star-cloud-uni'

logout(params)

入参

参数名称	数据类型	必须	描述
uid	Number	Y	用户uid

返回
无

设备

搜索设备

调用方法

import {searchDevice} from 'star-cloud-uni'

searchDevice(callback)
const callback = async result => {
}

入参

参数名称	数据类型	必须	描述
callback	Function	Y	回调方法，名称自定义

返回

参数名称	数据类型	描述
list	Array.<DeviceInfo>	设备列表

DeviceInfo 设备信息

参数名称	数据类型	描述
deviceId	String	蓝牙设备 id
RSSI	Number	当前蓝牙设备的信号强度，单位 dBm
connectable	Boolean	当前蓝牙设备是否可连接（ Android 8.0 以下不支持返回该值 ）
advertisData	ArrayBuffer	当前蓝牙设备的广播数据段中的 ManufacturerData 数据段
advertisServiceUUIDs	Array.<string>	当前蓝牙设备的广播数据段中的 ServiceUUIDs 数据段
localName	String	当前蓝牙设备的广播数据段中的 LocalName 数据段
name	String	蓝牙设备名称，某些设备可能没有

停止搜索设备

调用方法

import {stopSearchDevice} from 'star-cloud-uni'

const result = await stopSearchDevice()

入参
无

返回
无

绑定设备

调用方法

import {bindDevice} from 'star-cloud-uni'

bindDevice(params)

入参

参数名称	数据类型	必须	描述
uid	Number	N	用户uid
name	String	Y	设备名称

返回

参数名称	数据类型	描述
lock	LockInfo	锁信息

锁基本功能

选择锁(对锁进行蓝牙操作前调用)

调用方法

import {selectLock} from 'star-cloud-uni'

selectLock(params)

入参

参数名称	数据类型	必须	描述
uid	Number	N	用户uid
lockId	Number	Y	锁ID

返回
无

开关门

调用方法

import {openDoor} from 'star-cloud-uni'

openDoor(params)

入参

参数名称	数据类型	必须	描述
uid	Number	N	用户uid
type	String	Y	开门方式
disconnect	Boolean	N	操作后是否断开连接，默认断开

返回
无

删除锁

调用方法

import {deleteLock} from 'star-cloud-uni'

deleteLock(params)

入参

参数名称	数据类型	必须	描述
uid	Number	N	用户uid

返回
无

获取锁支持功能

调用方法

import {getLockSupportFeatures} from 'star-cloud-uni'

getLockSupportFeatures(params)

入参

参数名称	数据类型	必须	描述
uid	Number	N	用户uid
lockId	Number	Y	锁 Id

返回

以下所有功能字段0代表不支持，1代表支持

参数名称	数据类型	描述
password	Number	是否支持密码
icCard	Number	是否支持 IC 卡
fingerprint	Number	是否支持指纹
fingerVein	Number	是否支持指静脉
palmVein	Number	是否支持掌静脉
d3Face	Number	是否支持 3D 人脸
qrCode	Number	是否支持二维码
bluetoothRemoteControl	Number	是否支持蓝牙遥控器
wirelessKey	Number	是否支持无线钥匙
gatewayUnlock	Number	是否支持网关开锁
lockCommand	Number	是否支持闭锁指令
firmwareUpgrade	Number	是否支持固件升级设置指令
passwordIssue	Number	是否支持密码下发
cardIssue	Number	是否支持卡片下发
fingerprintIssue	Number	是否支持指纹下发
fingerVeinIssue	Number	是否支持指静脉下发
palmVeinIssue	Number	是否支持掌静脉下发
d3FaceIssue	Number	是否支持 3D 人脸下发
lockFreeze	Number	是否支持冻结/解冻锁
readAdminPassword	Number	是否支持读取管理员密码
passwordManagement	Number	是否支持密码管理功能
passwordWithDelete	Number	是否支持密码带删除功能
remoteUnlock	Number	是否支持配置远程开锁
autoLock	Number	是否支持自动闭锁设置
antiPrySwitch	Number	是否支持防撬开关配置
resetSwitch	Number	是否支持重置键配置
lockSwitch	Number	是否支持反锁功能配置
lockSound	Number	是否支持语音提示管理
languageSetting	Number	是否支持语言设置
realTimeClock	Number	是否支持实时时钟
wifi	Number	是否支持 WIFI
videoIntercom	Number	是否支持可视对讲
cyclePassword	Number	是否支持循环密码
cycleFingerprintCard	Number	是否支持循环指纹/卡
doubleAuthentication	Number	是否支持双重认证
openDirection	Number	是否支持开门方向设置
proximitySensing	Number	是否支持接近感应
doorStatus	Number	是否支持门磁状态
wiredDoorMagnet	Number	是否支持有线门磁
wirelessDoorMagnet	Number	是否支持无线门磁
doorNotClosedAlarm	Number	是否支持门未关报警
unlockReminder	Number	是否支持开锁提醒
wirelessKeyboard	Number	是否支持无线键盘
lightingTime	Number	是否支持照明灯时间配置
passageMode	Number	是否支持常开模式
hotelLockCardSystem	Number	是否支持酒店锁卡系统
appUnlockOnline	Number	是否支持 APP 开锁需联网
bluetoothBroadcast	Number	是否支持蓝牙广播
attendance	Number	是否支持考勤
motorTorsion	Number	是否支持电机扭力
stayWarn	Number	是否支持逗留警告
abnormalWarn	Number	是否支持异常警告
isSupportIris	Number	是否支持虹膜识别
isSupportCatEye	Number	是否支持猫眼
deviceEnMultiLanguage	Number	是否支持设备支持的多国语言
isNoSupportedBlueBroadcast	Number	是否不支持蓝牙广播
isSupportAutoLight	Number	是否支持自动亮屏
isSupportBackupBattery	Number	是否支持备用电池
isSupportForcedOpen	Number	是否支持胁迫开门
isSupportOpen	Number	是否支持开门器开锁
isSupportPush	Number	是否支持推送
offlinePasswordEncryption	Number	是否支持密码算法
offlinePasswordNumMax	Number	是否支持离线密码最大个数

密码

获取离线密码

调用方法

import {getOfflinePassword} from 'star-cloud-uni'

getOfflinePassword(params)

入参

参数名称	数据类型	必须	描述
uid	Number	N	用户uid
password	OfflinePassword	Y	密码信息

OfflinePassword 密码信息

属性	数据类型	必须	描述
lockId	Number	Y	锁 Id
keyboardPwdName	String	Y	密码名称
keyboardPwdType	Number	Y	密码类型
isCoerced	Number	Y	是否胁迫模式 1:胁迫 2:非胁迫
startDate	Number	Y	开始日期时间戳(毫秒，永久默认为0)
endDate	Number	Y	结束日期时间戳(毫秒，永久默认为0)
hoursStart	Number	Y	开始时间（小时, 不需要时传0）
hoursEnd	Number	Y	结束时间（小时, 不需要时传0）

keyboardPwdType 密码类型

状态	状态说明
1	单次
2	永久
3	限时
4	删除
5	周末循环
6	每日循环
7	工作日循环
8	周一循环
9	周二循环
10	周三循环
11	周四循环
12	周五循环
13	周六循环
14	周天循环

返回

属性	数据类型	描述
keyboardPwd	Number	密码
keyboardPwdId	Number	密码ID
keyboardPwdStatus	Number	密码状态 1：正常 2：已过期 3：待生效

检查密码是否重复

调用方法

import {checkPassword} from 'star-cloud-uni'

checkPassword(params)

入参

参数名称	数据类型	必须	描述
uid	Number	N	用户uid
info	CheckInfo	Y	信息

CheckInfo 检查密码信息

属性	数据类型	必须	描述
lockId	Number	Y	锁 Id
keyboardPwdName	String	N	密码名称
keyboardPwdId	String	N	密码 Id
keyboardPwd	String	N	密码

返回

无

修改超级管理员密码

调用方法

import {updateAdminPassword} from 'star-cloud-uni'

updateAdminPassword(params)

入参

属性	数据类型	必须	描述
uid	Number	N	用户uid
adminPwd	String	Y	管理员密码
disconnect	Boolean	N	操作后是否断开连接，默认断开

返回
无

操作自定义密码

调用方法

import {customPassword} from 'star-cloud-uni'

customPassword(params)

入参

参数名称	数据类型	必须	描述
uid	Number	N	用户uid
password	CustomPassword	Y	密码信息
disconnect	Boolean	N	操作后是否断开连接，默认断开

CustomPassword password 密码信息

属性	数据类型	必须	描述
keyboardPwdName	String	Y	密码名称
keyboardPwdId	Number	N	密码Id（创建无需传）
keyboardPwdType	Number	Y	密码类型：2：永久 3：限期
keyboardPwd	String	Y	密码
addType	Number	Y	添加方式 1：应用 2：网关
isCoerced	Number	Y	是否是胁迫密码，1：是 2：否
startDate	Number	Y	起始时间（毫秒）
endDate	Number	Y	结束时间（毫秒）
operate	Number	Y	操作 0：注册 1：修改 2：删除自定义密码 3：删除离线密码
pwdRight	Number	Y	是否是管理员密码 0：不是 1：是
pwdNo	Number	N	密码编号（创建无需传）
lockId	Number	Y	锁Id

返回

operate=0时返回

属性	数据类型	描述
keyboardPwdId	Number	密码Id
keyboardPwdStatus	Number	密码状态 1：正常 2：已过期 3：待生效
keyboardPwd	String	密码
pwdNo	Number	密码编号

记录

同步开门记录

调用方法

import {syncOpenDoorRecord} from 'star-cloud-uni'

syncOpenDoorRecord(params)

入参

参数名称	数据类型	必须	描述
uid	Number	N	用户uid
disconnect	Boolean	N	操作后是否断开连接，默认断开

返回
无

其他

获取服务器时间

调用方法

import {getServerTime} from 'star-cloud-uni'

getServerTime()

入参
无

返回

参数名称	数据类型	描述
date	Number	时间戳（毫秒）

移除坏锁

调用方法

import {removeBadLock} from 'star-cloud-uni'

removeBadLock(params)

入参

参数名称	数据类型	必须	描述
uid	Number	N	用户uid
lockIds	Array.	Y	锁Id列表

返回
无

电表

更新电表信息

调用方法

import {refreshElecInfo} from 'star-cloud-uni'

refreshElecInfo(params)

入参

参数名称	数据类型	必须	描述
uid	Number	N	用户uid
elecId	Number	Y	电表ID

返回
无

冷水表

更新冷水表信息

调用方法

import {refreshColdWaterInfo} from 'star-cloud-uni'

refreshColdWaterInfo(params)

入参

参数名称	数据类型	必须	描述
uid	Number	N	用户uid
waterId	Number	Y	冷水表ID

返回
无

热水表

更新热水表信息

调用方法

import {refreshHotWaterInfo} from 'star-cloud-uni'

refreshHotWaterInfo(params)

入参

参数名称	数据类型	必须	描述
uid	Number	N	用户uid
waterId	Number	Y	热水表ID

返回
无

监听事件

监听相关事件

事件名	描述	返回值示例
registerCardConfirm	卡片注册成功	{cardNumber:1,cardId:1}
registerFingerprintProcess	指纹注册进度	{status: 0,process: 0}；process总步数在上方统一Result中返回
registerFingerprintConfirm	指纹注册成功	{fingerprintNumber:1,fingerprintId:1}
registerFaceProcess	人脸注册进度	{faceNumber:1,faceId:1}
registerFaceConfirm	人脸注册成功	{faceNumber:1,faceId:1}
registerPalmVeinConfirm	掌静脉注册成功	{palmVeinNumber:1,palmVeinId:1}
registerRemoteConfirm	遥控注册成功	{remoteNumber:1,remoteId:1}
searchWiFiResult	wifi搜索结果	{status:0, numberOfSsid:7, wifiList:[Object]}

监听事件示例

// uniapp 监听注册卡片完成事件
uni.$on('registerCardConfirm', async data => {
    // TODO 
})
// uniapp 监听注册指纹进度
uni.$on('registerFingerprintProcess', async data => {
    // TODO 
})
// uniapp 指纹注册成功
uni.$on('registerFingerprintConfirm', async data => {
    // TODO 
})

扩展功能操作（ic卡、指纹、人脸、遥控、掌静脉）

注册、修改、删除、 删除全部

调用方法

import {registerExtendedProducts} from 'star-cloud-uni'

registerExtendedProducts(params)

入参

参数名称	数据类型	必须	描述	说明
type	String	Y	功能类型	['card','fingerprint','face','remote','palmVein']其中一个
keyId	String	Y	钥匙 ID
uid	String	Y	用户uid
userCountLimit	Number	Y	使用次数限制	0xFFFF 表示不限次数
operate	Number	Y	操作类型	0: 注册, 1: 修改, 2: 删除, 3: 删除全部
isAdmin	Number	Y	是否管理员	1 表示是，0 表示否
isForce	Number	Y	是否胁迫	1 表示是，0 表示否
isRound	Number	Y	是否循环	1 表示是，0 表示否
weekDays	Array	N	循环周期	0 -- 6 置位分别代表周日 -- 周六；例如：循环星期一、星期二、星期四,对应为：[1，2，4]
startDate	Number	Y	生效日期	时间戳，永久则填0
endDate	Number	Y	失效日期	时间戳，永久则填0
startTime	String	N	生效时间	例如：'00:00'
endTime	String	N	失效时间	例如：'00:00'
cardId	Number	N	卡片Id	添加后由监听事件返回，仅当 type 为 'card' 且operate!=1 时需要
cardNumber	Number	N	卡片序号	仅当 type 为 'card' 时需要
cardName	String	N	卡片名称	仅当 type 为 'card' 时需要
cardType	Number	N	卡片类型	仅当 type 为 'card' 时需要，1:永久，2：期限，4:循环，
cardUserNo	Number	N	卡UserNo	仅当 type 为 'card' 时需要 （选填）
fingerprintId	Number	N	指纹Id	添加后由监听事件返回，仅当 type 为 'fingerprint' 且operate!=1 时需要
fingerprintName	String	N	指纹序号	仅当 type 为 'fingerprint' 时需要
fingerprintNumber	Number	N	指纹名称	仅当 type 为 'fingerprint' 时需要
fingerprintType	Number	N	指纹类型	仅当 type 为 'fingerprint' 时需要，1:永久，2：期限，3：单次，4:循环
fingerprintUserNo	Number	N	指纹UserNo	仅当 type 为 'fingerprint' 时需要 （选填）
deleteType	Number	N	删除方式	仅当 type 为 'fingerprint' 时需要 1:通过APP走蓝牙删除，必需先通过APP蓝牙删除后再调用该接口,2:通过网关或WiFi锁删除，如果是WiFi锁或有连接网关，则可以传2，直接调用该接口从锁里删除指纹
faceId	Number	N	人脸Id	添加后由监听事件返回，仅当 type 为 'face' 且operate!=1 时需要
faceName	String	N	人脸序号	仅当 type 为 'face' 时需要
faceNumber	Number	N	人脸名称	仅当 type 为 'face' 时需要
faceType	Number	N	人脸类型	仅当 type 为 'face' 时需要，1:永久，2：期限，4:循环
faceUserNo	Number	N	人脸UserNo	仅当 type 为 'face' 时需要 （选填）
palmVeinId	Number	N	掌静脉Id	添加后由监听事件返回，仅当 type 为 'palmVein' 且operate!=1 时需要
palmVeinName	String	N	掌静脉序号	仅当 type 为 'palmVein' 时需要
palmVeinNumber	Number	N	掌静脉名称	仅当 type 为 'palmVein' 时需要
palmVeinType	Number	N	掌静脉类型	仅当 type 为 'palmVein' 时需要，1:永久，2：期限，4:循环
palmVeinUserNo	Number	N	掌静脉UserNo	仅当 type 为 'palmVein' 时需要 （选填）
remoteId	Number	N	遥控Id	添加后由监听事件返回，仅当 type 为 'remote' 且operate!=1 时需要
remoteName	String	N	遥控序号	仅当 type 为 'remote' 时需要
remoteNumber	Number	N	遥控名称	仅当 type 为 'remote' 时需要
remoteType	Number	N	遥控类型	仅当 type 为 'remote' 时需要，1:永久，2：期限，4:循环
remoteUserNo	Number	N	遥控UserNo	仅当 type 为 'remote' 时需要 （选填）

返回

Result 统一返回结果格式

收到锁版提示后，将卡片放置读卡器

取消操作

调用方法

import {registerExtendedProductsCancel} from 'star-cloud-uni'

registerExtendedProductsCancel(params)

入参

参数名称	数据类型	必须	描述	说明
type	String	Y	功能类型	['card','fingerprint','face','remote','palmVein']
keyId	String	Y	钥匙 ID
uid	String	Y	用户uid

返回
无

获取ic卡列表

调用方法

import {getIcCardList} from 'star-cloud-uni'

getIcCardList(params)

入参

参数名称	数据类型	必须	描述
lockId	String	Y	锁id
pageNo	String	N	页码
pageSize	String	N	每页显示数

返回

{
  "list": [],
  "pageNo": 1,
  "pageSize": 0,
  "pages": 0,
  "total": 0
}

获取指纹列表

调用方法

import {getFingerprintList} from 'star-cloud-uni'

getFingerprintList(params)

入参

参数名称	数据类型	必须	描述
lockId	String	Y	锁id
pageNo	String	N	页码
pageSize	String	N	每页显示数

返回

{
  "list": [],
  "pageNo": 1,
  "pageSize": 0,
  "pages": 0,
  "total": 0
}

获取人脸列表

调用方法

import {getFaceList} from 'star-cloud-uni'

getFaceList(params)

入参

参数名称	数据类型	必须	描述
lockId	String	Y	锁id
pageNo	String	N	页码
pageSize	String	N	每页显示数

返回

{
  "list": [],
  "pageNo": 1,
  "pageSize": 0,
  "pages": 0,
  "total": 0
}

获取掌静脉列表

调用方法

import {getPalmVeinList} from 'star-cloud-uni'

getPalmVeinList(params)

入参

参数名称	数据类型	必须	描述
lockId	String	Y	锁id
pageNo	String	N	页码
pageSize	String	N	每页显示数

返回

{
  "list": [],
  "pageNo": 1,
  "pageSize": 0,
  "pages": 0,
  "total": 0
}

获取遥控列表

调用方法

import {getRemoteList} from 'star-cloud-uni'

getRemoteList(params)

入参

参数名称	数据类型	必须	描述
lockId	String	Y	锁id
pageNo	String	N	页码
pageSize	String	N	每页显示数

返回

{
  "list": [],
  "pageNo": 1,
  "pageSize": 0,
  "pages": 0,
  "total": 0
}

wifi配网

• 配网时确保锁板亮屏
• 确保连接的wifi是2.4GHz的wifi

搜索wifi

搜索大约4秒返回结果

调用方法

import {startSearchWiFi} from 'star-cloud-uni'
// 1.选择锁
await selectLock(params)
// 2.启动搜索wifi（）
await startSearchWiFi(params)

入参

参数名称	数据类型	必须	描述	默认
connected	boolean	N	是否已经连接	false
disconnect	boolean	N	应答成功后是否自动断开连接	false

返回

通过事件监听搜索结果的返回值

// wifi搜索结果事件回调
uni.$on('searchWiFiResult', async data => {
    // TODO
})

连接wifi

调用方法

import {connectWiFi} from 'star-cloud-uni'
// 1.选择锁
await selectLock(params)
// 2.连接wifi
const params = {
    ssid: 'wifi昵称',
    password: 'wifi密码',
}
await connectWiFi(params)

入参

参数名称	数据类型	必须	描述	默认
ssid	String	Y	wifi昵称
password	String	Y	wifi密码

返回

{
  "code": 0,
  "data": null,
  "message": "配网成功"
}