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

## 星云SDK

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

## 公共参数

> 返回结果
{.is-success}
```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
{.is-success}
```javascript
AccountInfo accountInfo
```

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

> 锁信息 LockInfo
{.is-success}
```javascript
LockInfo lock
```

| 名称                      | 类型   | 描述                       |
|---------------------------|--------|----------------------------|
| 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
{.is-success}
```javascript
Bluetooth bluetooth
```

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

> 锁配置信息 LockConfig
{.is-success}
```javascript
LockConfig 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 | 时区偏移（秒）            |

## 初始化

> 初始化星云
{.is-success}
1. 调用方法
```javascript
/**
 * 初始化星云
 */
plugin.initStarCloud(params)
```

2. 入参

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

3. 返回
   无

## 账户相关

> 注册
{.is-success}

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

2. 入参
   无

3. 返回

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


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

2. 入参

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

3. 返回
   无

## 设备相关

> 搜索设备
{.is-success}

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

> 停止搜索设备
{.is-success}

1. 调用方法
```javascript
/**
 * 停止搜索
 * @returns Result
 */
const result = await stopSearchDevice()
```

2. 入参
   无

3. 返回
   无

> 绑定设备
{.is-success}

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|锁信息|

## 锁基础功能

> 选择锁(对锁进行操作前调用)
{.is-success}
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. 返回
   无

> 开关门
{.is-success}
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. 返回
   无

> 删除锁
{.is-success}
1. 调用方法
```javascript
/**
 * 删除锁
 * @param params
 * @param {AccountInfo} params.accountInfo 账号信息
 * @returns Result
 */
const result = await plugin.deleteLock(params)
```

2. 入参

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

3. 返回
   无

## 锁密码相关

> 获取离线密码
{.is-success}

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

2. 入参

OfflinePassword 密码信息

| 属性              | 类型     | 描述              |
|-------------------|----------|-------------------|
| 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   | 密码          |


> 修改超级管理员密码
{.is-success}

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. 返回
   无

## 锁记录相关

> 同步开门记录
{.is-success}

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. 返回
   无


## 其他

> 获取服务器时间
{.is-success}

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

2. 入参
   无

3. 返回

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

> 移除坏锁
{.is-success}

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. 返回
   无