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

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

# 版本
当前最新版本 1.1.0

# 引用
APPID: **wxf2c491f734bbf82f**
1. 登录小程序后台-选择设置->第三方设置->插件管理->点击“添加插件”->搜索对应APPID->添加插件->等待审核通过
2. 项目中引用需在app.json文件中添加
```json
{
  "plugins": {
    "starCloud": {
      "version": "1.1.0",
      "provider": "wxf2c491f734bbf82f"
    }
  }
}
```
3. 页面中引用
```javascript
// 引用插件
const plugin = requirePlugin('starCloud')
```

# 公共参数

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

```javascript
// 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. 调用方法
```javascript
/**
 * 初始化星云
 */
plugin.init(params)
```

2. 入参

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

3. 返回
   无

# 用户

## 注册

1. 调用方法
```javascript
/**
 * 注册
 * @returns Result
 */
const result = await plugin.register()
```

2. 入参
   无

3. 返回

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


## 退出登录

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

2. 入参

|名称|类型|描述|
| -- | -- | -- |
|uid|Number|用户uid|

3. 返回
   无

# 设备

## 搜索设备

1. 调用方法
```javascript
/**
 * 搜索蓝牙设备
 * @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. 调用方法
```javascript
/**
 * 停止搜索
 * @returns Result
 */
const result = await stopSearchDevice()
```

2. 入参
   无

3. 返回
   无

## 绑定设备

1. 调用方法
```javascript
/**
 * 绑定设备
 * @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. 调用方法
```javascript
/**
 * 选择锁
 * @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. 调用方法
```javascript
/**
 * 开门
 * @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. 调用方法
```javascript
/**
 * 删除锁
 * @param params
 * @param {AccountInfo} params.accountInfo 账号信息
 * @returns Result
 */
const result = await plugin.deleteLock(params)
```

2. 入参

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

3. 返回
   无

## 获取锁支持功能

1. 调用方法
```javascript
/**
 * 获取锁支持项
 * @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. 调用方法
```javascript
/**
 * 获取离线密码
 * @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. 调用方法
```javascript
/**
 * 修改管理员密码
 * @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. 调用方法
```javascript
/**
 * 同步全部开门记录
 * @param params
 * @param {AccountInfo} params.accountInfo 账号信息
 * @param {Boolean} params.disconnect 操作后是否断开连接
 * @returns Result
 */
const result = await plugin.syncOpenDoorRecord()
```

2. 入参

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

3. 返回
   无

# 其他
## 获取服务器时间

1. 调用方法
```javascript
/**
 * 获取服务器时间
 * @returns Result
 */
const result = await plugin.getServerTime()
```

2. 入参
   无

3. 返回

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

## 移除坏锁

1. 调用方法
```javascript
/**
 * 移除坏锁
 * @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. 返回
   无