starcloud-sdk-uniapp/uni.md

# 说明

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

# 引用

```git
npm install star-cloud-uni
```

# 公共参数

## Result 方法的统一返回结构

```javascript
// 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 | 时区偏移（秒）    |

# 初始化

## 初始化星云

**调用方法**

```javascript
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  | 是否上报日志，默认不上报                    |

**返回**  
无

# 用户

## 注册

**调用方法**

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

register()
```

**入参**  
无

**返回**

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

## 退出登录

**调用方法**

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

logout(params)
```

**入参**

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

**返回**  
无

# 设备

## 搜索设备

**调用方法**

```javascript
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           | 蓝牙设备名称，某些设备可能没有                      |

## 停止搜索设备

**调用方法**

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

const result = await stopSearchDevice()
```

**入参**  
无

**返回**  
无

## 绑定设备

**调用方法**

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

bindDevice(params)
```

**入参**

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

**返回**

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

# 锁基本功能

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

**调用方法**

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

selectLock(params)
```

**入参**

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

**返回**  
无

## 开关门

**调用方法**

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

openDoor(params)
```

**入参**

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

**返回**  
无

## 删除锁

**调用方法**

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

deleteLock(params)
```

**入参**

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

**返回**  
无

## 获取锁支持功能

**调用方法**

```javascript
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 | 是否支持离线密码最大个数   |

# 密码

## 获取离线密码

**调用方法**

```javascript
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：待生效 |

## 检查密码是否重复

**调用方法**

```javascript
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  | 密码    |

**返回**

无

## 修改超级管理员密码

**调用方法**

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

updateAdminPassword(params)
```

**入参**

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

**返回**  
无

## 操作自定义密码

**调用方法**

```javascript
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 | 密码编号                  |

# 记录

## 同步开门记录

**调用方法**

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

syncOpenDoorRecord(params)
```

**入参**

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

**返回**  
无

# 其他

## 获取服务器时间

**调用方法**

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

getServerTime()
```

**入参**  
无

**返回**

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

## 移除坏锁

**调用方法**

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

removeBadLock(params)
```

**入参**

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

**返回**    
无


# 电表

## 更新电表信息

**调用方法**

```javascript
import { refreshElecInfo } from 'star-cloud-web'

refreshElecInfo(params)
```

**入参**

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

**返回**    
无


# 冷水表

## 更新冷水表信息

**调用方法**

```javascript
import { refreshColdWaterInfo } from 'star-cloud-web'

refreshColdWaterInfo(params)
```

**入参**

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

**返回**    
无



# 热水表

## 更新热水表信息

**调用方法**

```javascript
import { refreshHotWaterInfo } from 'star-cloud-web'

refreshHotWaterInfo(params)
```

**入参**

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

**返回**    
无