Skip to content

Latest commit

 

History

History
366 lines (295 loc) · 14.3 KB

接口文档(v1.4.x).md

File metadata and controls

366 lines (295 loc) · 14.3 KB

通通锁蓝牙模块通信插件接口说明文档 (version: 1.4.1)

说明

通通锁蓝牙模块通信插件是基于微信小程序接口开发的蓝牙模块插件，使用时需配合通通锁开放平台接口使用。
该文档适用于1.3.2及1.4.0版本, 2.x版本请参考READEME.md 通通锁开放平台

  1. 添加智能锁：调用开放平台/oauth2/token接口登录 -> 小程序initLock接口 -> 开放平台锁初始化接口/v3/lock/initialize
    注意：若未上传服务器可能导致智能锁数据丢失，只能物理重置智能锁
  1. 开锁：调用获取锁的普通钥匙列表 -> 小程序UnlockBleLock接口开锁
    注意：小程序接口不主动上传操作记录，如需上传请自行调用开放平台接口上传记录
  1. 校准锁时间：调用获取锁的普通钥匙列表 -> 小程序CorrectBleLockTime接口校准锁时间

重要参数

1. LOCK_BLE_UUID

变量, 为锁蓝牙模块的uuid

2. LOCK_TYPE_V3

变量, 三代锁

主要接口

1. 方法 获取当前锁类型

function getLockType(lockVersion)

参数

lockVersion：为锁版本信息json, 添加锁时会返回该字段

返回值

0 -不开放或已不支持的锁类型 3 -二代门锁 4 -二代锁(带永久密码功能) 5 -三代锁

版本更新内容

1.4.1
版本无更新

1.4.0
版本无更新

1.3.2

  1. 返回值为3和4的值不支持蓝牙添加锁等功能

1.3.1
版本无更新

1.3.0

  1. 增加返回值0，小程序接口不支持返回值为0的锁类型
2. 方法 判断设备是否允许远程开锁

function isRemoteUnlockEnabled(specialValue)

参数

specialValue:锁的特征值

返回值

Boolean

版本更新内容

1.4.1
版本无更新

1.4.0
版本无更新

1.3.2

  1. 修改输入参数specialValue不正确时，返回值为false
3. 方法 蓝牙开锁接口 -1.4.1版本增加uniqueid返回值

function UnlockBleLock(deviceId: String, uid: Number, lockVersion: Object, startDate: Number, endDate: Number, lockKey: String, lockFlagPos: Number, aesKeyStr: String, timezoneRawOffset: Number, callBack: Function, serverTime：Number)

参数
  deviceId:蓝牙设备返回的deviceId，(!!iOS和Android设备均可填写MAC地址，格式:"AA:AA:AA:BB:BB:BB", 兼容原接口中填写微信返回的deviceId的写法)
  uid:通通锁登录后返回的uid, (!!调试环境下可填写0)
  lockVersion:为锁版本信息json,添加锁时会返回该字段
  startDate：蓝牙钥匙的生效时间, (!!调试环境下可填写0)
  endDate：蓝牙钥匙的过期时间, (!!调试环境下可填写0)
  lockKey：蓝牙钥匙的开锁钥匙信息，由通通锁开发平台获取钥匙时返回
  lockFlagPos：钥匙重置标志位，由通通锁开放平台返回
  aesKeyStr：蓝牙钥匙的aes
  timezoneRawOffset：时区偏移量,由通通锁开放平台返回
  callBack：钥匙开门后的回调(由调用者传入，传入方法需有一个返回数据对象)，以下为回调中返回的数据对象内容 返回参数形式：callBack(unlockResult: Option)
    unlockResult = 
    {
      lockDate:锁中当前时间的时间戳, (!!仅在开锁成功后返回)
      errorCode: 错误码 （1.3.2版本新增）
      errorMsg:错误提示
      electricQuantity:锁电量 范围 0-100, (!!仅在开锁成功后返回)
      uniqueid: 唯一标识 （1.4.1版本新增）
    }
  serverTime: 从服务器获取的时间戳，用于校准锁时间，传入null值或不传则开锁时不校准锁时间, 默认为空值（1.4.0版本新增）
返回值

在callBack回调中返回

版本更新内容

1.4.1

  1. 增加uniqueid返回值

1.4.0

  1. 增加服务器时间参数
  2. 删除蓝牙开锁时必定校准锁时间的功能，改为由传入的serverTime控制
  3. 删除success和errCode返回值

1.3.2

  1. 修改deviceId输入的兼容性
  2. 修改开锁接口的稳定性，集成开启蓝牙适配、搜索设备和关闭连接等功能，新版本使用方法请参考DEMO，兼容旧版本
  3. 新增规范化返回参数errorCode
  4. success和errCode返回值将在下一版本废止，请及时更新
4. 方法 扫描蓝牙设备接口 -1.4.0版本无修改

function startScanBleDevice(callBack: Function, failCallback: Function)

参数
  callBack扫描接口成功获取设备回调, 扫描成功该方法可能执行多次，请不要在该循环执行添加锁等操作，返回参数信息callback(BleDevice: Option, BleDeviceList: Array)
    BleDevice为扫描到的单把锁信息, 同一把锁可能返回多次, 说明: {
      lockName: "",   -锁蓝牙名称
      deviceId: "",   -锁ID
      rssi: 0,        -蓝牙当前信号强度, 该参数, 1.3.0版本新增特殊返回值0, 表示该设备已掉线
      lockMac: "",    -当前的锁MAC值
      protocolType: 0,      -锁协议类型
      protocolVersion: 0,   -锁协议版本
      scene: 0,             -场景值
      isSettingMode: false，-是否是可初始化模式，只有处于可初始化模式才能初始化锁, 1.3.0版本以前无蓝牙超时处理, 设备超时无回调
      electricQuantity: 0,  -电池电量
    }
    BleDeviceList说明: 1.3.0版本新增, 为当前扫描状态下周围锁信息列表, 以添加状态、蓝牙信号强度排序, 参数信息参考BleDevice
  failCallback: 1.3.0版本新增,用于开启蓝牙扫描失败回调, 返回参数形式：failCallBack(err: Option)
    err说明：{
      errorCode: 错误码,
      errorMsg: 错误信息,
      description: 蓝牙失败原因描述
    }
返回值

在callBack和failCallback回调中返回

版本更新内容

1.4.1
版本无更新

1.4.0
版本无修改

1.3.2
无特殊修改

1.3.1

  1. 修复iOS设备扫描无返回的问题

1.3.0

  1. 新增参数failCallback, 用于失败回调
  2. 新增callback回调参数BleDeviceList, 返回当前蓝牙设备列表信息
  3. 修改蓝牙超时无响应不回调的问题
  4. 修改设备操作提示信息
5. 方法 停止扫描蓝牙设备接口 -1.4.0版本无修改

function stopScanBleDevice(callBack: Function, failCallback: Function)

参数
  callback为蓝牙停止扫描成功接口回调, 返回参数形式：callback(res: Option)
    res说明：{
      errorCode: 0,           -错误码
      errorMsg: "操作成功"    -错误信息
    }
  failCallback -蓝牙停止扫描失败接口回调, 返回参数形式：failCallback(err: Option)
    err说明：{
      errorCode: 错误码,
      errorMsg: 错误信息,
      description: 蓝牙失败原因描述
    }
返回值

在callBack和failCallback回调中返回

版本更新内容

1.4.1
版本无更新

1.4.0
版本无修改

1.3.2
无特殊修改

1.3.1
无特殊修改

1.3.0

  1. 新增停止扫描蓝牙设备接口
6. 方法 初始化锁 -1.4.0版本删除部分返回值

function initLock(bleDevice: Object, callBack: Function)

参数
  bleDevice为蓝牙扫描接口startScanBleDevice方法返回的单个对象, 仅isSettingMode=true的锁可进行初始化
  callBack为蓝牙停止扫描成功接口回调, 返回参数形式：callback(initLockResult: Option)
    initLockResult = {
      errorCode: 错误码 （1.3.2版本新增） 
      errorMsg:"",
      lockData:"" 为锁初始化数据的jsonStr，对应于开放平台服务器 锁初始化接口 中的lockData字段
    }
返回值

在callBack回调中返回

版本更新内容

1.4.1
版本无更新

1.4.0

  1. 删除返回值resultCode

1.3.2

  1. 修改初始化智能锁接口的稳定性，集成开启蓝牙适配、搜索设备和关闭连接等功能，新版本使用方法请参考DEMO，兼容旧版本
  2. 新增规范化返回参数errorCode
  3. resultCode返回值将在下一版本废止，请及时更新
  4. (!!不支持二代锁和车位锁，请注意)
7. 方法 重置锁 -1.4.0版本删除部分返回值

function resetLock(deviceId: String, uid: Number, lockVersion: Object, adminPwd: String, lockKey: String, lockFlagPos: Number, aesKeyStr: String, callBack: Function)

参数
  deviceId:蓝牙设备返回的deviceId，(!!iOS和Android设备均可填写MAC地址，格式:"AA:AA:AA:BB:BB:BB", 兼容原接口中填写微信返回的deviceId的写法)
  uid:通通锁登录后返回的uid, (!!调试环境下可填写0)
  lockVersion:为锁版本信息json,添加锁时会返回该字段, 开放平台获取的钥匙数据中也包含该参数
  adminPwd: 锁管理员密码用于校验身份，由通通锁开发平台获取钥匙时返回
  lockKey：蓝牙钥匙的开锁钥匙信息，由通通锁开发平台获取钥匙时返回
  lockFlagPos：蓝牙钥匙的开锁钥匙信息，由通通锁开发平台获取钥匙时返回
  aesKeyStr：蓝牙钥匙的aes, 由通通锁开放平台返回
  callBack：锁重置结果回调(由调用者传入，传入方法需有一个返回数据对象)，返回参数形式：callback(resetLockResult: Option)
    resetLockResult = {
      errorCode: 0,   -错误码（1.3.2版本新增） 
      errorMsg: ""    -错误信息（1.3.2版本新增） 
    }
返回值

在callBack回调中返回

版本更新内容

1.4.1
版本无更新

1.4.0

  1. 删除返回值resultCode和resultMsg

1.3.2

  1. 修改deviceId输入的兼容性
  2. 修改重置锁接口的稳定性，集成开启蓝牙适配、搜索设备和关闭连接等功能，新版本使用方法请参考DEMO，兼容旧版本
  3. 新增规范化返回参数errorCode和errorMsg
  4. resultCode和resultMsg返回值将在下一版本废止，请及时更新
8. 方法 校准锁时间 -1.4.0修复钥匙不在有效期内无法校准锁时间的问题，删除部分返回值

function CorrectBleLockTime(deviceId: String, uid: Number, lockVersion: Object, startDate: Number, endDate: Number, lockKey: String, lockFlagPos: Number, aesKeyStr: String, timezoneRawOffset: Number, serverTime: Number, callBack: Function, showLog：Boolean)

参数
  deviceId:蓝牙设备返回的deviceId，(!!iOS和Android设备均可填写MAC地址，格式:"AA:AA:AA:BB:BB:BB", 兼容原接口中填写微信返回的deviceId的写法)
  uid:通通锁登录后返回的uid, (!!调试环境下可填写0)
  lockVersion:为锁版本信息json,添加锁时会返回该字段, 开放平台获取的钥匙数据中也包含该参数
  startDate：蓝牙钥匙的生效时间, (!!调试环境下可填写0)
  endDate：蓝牙钥匙的过期时间, (!!调试环境下可填写0)
  lockKey：蓝牙钥匙的开锁钥匙信息，由通通锁开发平台获取钥匙时返回
  lockFlagPos：蓝牙钥匙的开锁钥匙信息，由通通锁开发平台获取钥匙时返回
  aesKeyStr：蓝牙钥匙的aes, 由通通锁开放平台返回
  timezoneRawOffset：时区偏移量,由通通锁开放平台返回
  serverTime: 校准的服务器时间
  callBack：钥匙开门后的回调(由调用者传入，传入方法需有一个返回数据对象)，以下为回调中返回的数据对象内容，返回参数形式：callback(correctLockTimeResult: Option)
    correctLockTimeResult = 
    {
      errorCode: 0,   -错误码（1.3.2版本新增） 
      errorMsg: ""    -错误信息（1.3.2版本新增）
      electricQuantity:   锁电量 范围 0-100 (!!仅在开锁成功后返回)
    }
返回值

在callBack回调中返回

版本更新内容

1.4.1
版本无更新

1.4.0

  1. 修复钥匙不在有效期内无法校准锁时间的问题
  2. 删除返回值success、errCode和errMsg

1.3.2

  1. 修改deviceId输入的兼容性
  2. 修改校准锁时间接口的稳定性，集成开启蓝牙适配、搜索设备和关闭连接等功能，新版本使用方法请参考DEMO，兼容旧版本
  3. 新增规范化返回参数errorCode和errorMsg
  4. errCode和errMsg返回值将在下一版本废止，请及时更新
9. 方法 获取当前设备mac地址 -1.4.0版本无修改

function getDeviceMacAddress(deviceFromWx: Object)

参数
  deviceFromWx: 对象为微信小程序 蓝牙扫描接口返回的device对象
返回值

lockMac: String || null -返回当前锁的mac地址, 格式"AA:AA:AA:BB:BB:BB", 参数错误时返回null

版本更新内容

1.4.1
版本无更新

1.4.0
版本无修改

1.3.2

  1. 修改：参数错误时返回参数为null
10. 方法 设置是否打开调试日志 -1.4.0版本新增

function setShowLog(showLog: Boolean)

参数
  showLog: 是否打印调试日志，默认为false
返回值

无

版本更新内容

1.4.1
版本无更新

1.4.0

  1. 版本新增

返回errorCode说明

0               -操作成功
10000           -钥匙或者锁时间不正确
10001           -锁可能被重置，请重新添加
10002           -锁连接超时，请确认是否在锁附近或者稍后重试
10003           -锁连接已断开
10004           -蓝牙数据发送失败，请稍后重试
10005           -无效钥匙，请检查钥匙数据是否正确
10006           -钥匙数据解析失败，请重试
10007           -建立蓝牙连接失败或连接已中断
10008           -停止蓝牙扫描失败
10009           -不支持的锁类型
10010           -锁未进入可添加模式
10030           -启动蓝牙适配器失败
10031           -停止蓝牙扫描失败
10032           -启用蓝牙特征值监控失败，请重试
10033           -蓝牙通信失败，请重试
10034           -设备通信错误
10035           -锁初始化失败
10036           -搜索不到设备，已停止搜索，请确认是否在锁附近或稍后重试
10042           -非管理员，没有操作权限
10043           -管理员校验失败
10047           -智能锁处于不可添加状态，请确保锁已被重置并已摸亮
10050           -电池电量低