starcloud-sdk-miniprogram/miniprogram/doc/README.md

说明

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

版本

当前最新版本 1.1.0

引用

APPID: wxf2c491f734bbf82f

1. 登录小程序后台-选择设置->第三方设置->插件管理->点击“添加插件”->搜索对应APPID->添加插件->等待审核通过
2. 项目中引用需在app.json文件中添加

{
  "plugins": {
    "starCloud": {
      "version": "1.1.0",
      "provider": "wxf2c491f734bbf82f"
    }
  }
}

3. 页面中引用

// 引用插件
const plugin = requirePlugin('starCloud')

公共参数

Result 方法的统一返回结构

// Result 类是所有有返回结果的方法，统一的返回结构
const {Result} = requirePlugin('starCloud')
// code对应报错码有三部分组合构成，锁端报错码+星云服务端报错码+自定义报错码
const {code, data, message} = Result.Success
// 常用判断方式
if (code === Result.Success.code) {
    // 逻辑代码   
} else {
    // 错误处理
}

code	变量名	描述
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	时区偏移（秒）

初始化

初始化星云

1. 调用方法

/**
 * 初始化星云
 */
plugin.init(params)

2. 入参

名称	类型	描述
clientId	String	客户端Id
clientSecret	String	客户端密码
env	String	环境(SKY,XHJ)
isReportLog	Boolean	是否上报日志

3. 返回 无

用户

注册

1. 调用方法

/**
 * 注册
 * @returns Result
 */
const result = await plugin.register()

2. 入参 无

3. 返回

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

退出登录

1. 调用方法

/**
 * 退出登录
 * @param params
 * @param {int} params.uid 用户uid
 * @returns Result
 */
const result = await plugin.logout(params)

2. 入参

名称	类型	描述
uid	Number	用户uid

3. 返回 无

设备

搜索设备

1. 调用方法

/**
 * 搜索蓝牙设备
 * @returns Result
 */
plugin.searchDevice(callback)
const callback = async result => {
    if (result.code === Result.Success.code) {
        this.setData({
            list: result.data.list
        })
    }
}

2. 入参 callback 回调方法

3. 返回

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

停止搜索设备

1. 调用方法

/**
 * 停止搜索
 * @returns Result
 */
const result = await stopSearchDevice()

2. 入参 无

3. 返回 无

绑定设备

1. 调用方法

/**
 * 绑定设备
 * @param params
 * @param {AccountInfo} params.accountInfo 账号信息
 * @param {String} params.name 设备名称
 * @returns Result
 */
const result = await plugin.bindDevice(params)
if (result.code === Result.Success.code) {
    this.setData({
        lock: result.data.lock
    })
}

2. 入参

名称	类型	描述
accountInfo	AccountInfo	账号信息
name	String	设备名称

3. 返回

名称	类型	描述
lock	LockInfo	锁信息

锁基本功能

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

1. 调用方法

/**
 * 选择锁
 * @param params
 * @param {AccountInfo} params.accountInfo 账号信息
 * @param {Number} params.lockId 锁ID
 * @returns Result
 */
const result = await plugin.selectLock(params)

2. 入参

名称	类型	描述
accountInfo	AccountInfo	账号信息
lockId	Number	锁ID

3. 返回 无

开关门

1. 调用方法

/**
 * 开门
 * @param params
 * @param {AccountInfo} params.accountInfo 账号信息
 * @param {String} params.type 开门方式 close: 关门 open: 开门
 * @param {Boolean} params.disconnect 操作后是否断开连接
 * @returns Result
 */
const result = await plugin.openDoor(params)

2. 入参

名称	类型	描述
accountInfo	AccountInfo	账号信息
type	String	开门方式
disconnect	Boolean	操作后是否断开连接

3. 返回 无

删除锁

1. 调用方法

/**
 * 删除锁
 * @param params
 * @param {AccountInfo} params.accountInfo 账号信息
 * @returns Result
 */
const result = await plugin.deleteLock(params)

2. 入参

名称	类型	描述
accountInfo	AccountInfo	账号信息

3. 返回 无

获取锁支持功能

1. 调用方法

/**
 * 获取锁支持项
 * @param params
 * @param {AccountInfo} params.accountInfo 账号信息
 * @param {Number} params.lockId  锁 Id
 * @returns Result
 */
const result = await plugin.getLockSupportFeatures(params)

2. 入参

名称	类型	描述
accountInfo	AccountInfo	账号信息
lockId	Number	锁 Id

3. 返回

以下所有功能字段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	是否支持离线密码最大个数

密码

获取离线密码

1. 调用方法

/**
 * 获取离线密码
 * @param {AccountInfo} params.accountInfo 账号信息
 * @param {OfflinePassword} params.password 密码信息
 * @returns Result
 */
const result = await plugin.getOfflinePassword(params)

2. 入参

OfflinePassword 密码信息

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

keyboardPwdType 密码类型

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

3. 返回

属性	类型	描述
keyboardPwd	Number	密码
keyboardPwdId	Number	密码

修改超级管理员密码

1. 调用方法

/**
 * 修改管理员密码
 * @param params
 * @param {AccountInfo} params.accountInfo 账号信息
 * @param {String} params.adminPwd 管理员密码
 * @param {Boolean} params.disconnect 操作后是否断开连接
 * @returns {Promise<Result>}
 */
const result = await plugin.updateAdminPassword(params)

2. 入参

属性	类型	描述
accountInfo	AccountInfo	账号信息
adminPwd	String	管理员密码
disconnect	Boolean	操作后是否断开连接

3. 返回 无

记录

同步开门记录

1. 调用方法

/**
 * 同步全部开门记录
 * @param params
 * @param {AccountInfo} params.accountInfo 账号信息
 * @param {Boolean} params.disconnect 操作后是否断开连接
 * @returns Result
 */
const result = await plugin.syncOpenDoorRecord()

2. 入参

名称	类型	描述
accountInfo	AccountInfo	账号信息
disconnect	Boolean	操作后是否断开连接

3. 返回 无

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

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

调用方法

const result = await plugin.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 统一返回结果格式

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

监听相关事件

事件名	描述	返回值示例
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}

监听事件示例

// 监听卡片注册成功事件
starEventOn('registerCardConfirm', async (data) => {
    // TODO
});
// 监听指纹注册进度事件
starEventOn('registerFingerprintProcess', async (data) => {
    // TODO
});
// 监听指纹注册成功事件
starEventOn('registerFingerprintConfirm', async (data) => {
    // TODO
});
// 其他事件同理...

取消操作

调用方法

 await plugin.registerExtendedProductsCancel(params)

入参

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

返回
无

获取ic卡列表

调用方法

const result = await plugin.getIcCardList(params)

入参

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

返回

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

获取指纹列表

调用方法

const result = await plugin.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-web'

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-web'

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-web'

getRemoteList(params)

入参

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

返回

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

其他

获取服务器时间

1. 调用方法

/**
 * 获取服务器时间
 * @returns Result
 */
const result = await plugin.getServerTime()

2. 入参 无

3. 返回

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

移除坏锁

1. 调用方法

/**
 * 移除坏锁
 * @param params
 * @param {AccountInfo} params.accountInfo 账号信息
 * @param {List[int]} params.lockIds 锁Id列表
 * @returns Result
 */
const result = await plugin.removeBadLock(params)

2. 入参

名称	类型	描述
accountInfo	AccountInfo	账号信息
lockIds	Array.<Nmuber>	锁Id列表

3. 返回 无