jinpai-sdk-web v0.0.1

sdk-web

氦氪前端开发工具库

使用示例

index.html

属性

所有属性都只能在ready之后调用

方法

事件

使用

在使用模块化的开发方式时，推荐使用 NPM 安装 SDK，能够和 Webpack 等模块打包器配合使用。

# 更改 npm 源
$ npm config set registry http://npm.aihomi.com

# 稳定版
$ npm install @hekr/sdk-web

# 开发版
$ npm install @hekr/sdk-web@beta

之后，在项目文件中注入以下代码。

// main.js
import { Hekr, Matrix } from '@hekr/sdk-web'

// 调试时才会运行，生成环境不会有
window.Matrix = new Matrix({
  token: '',
  reconnect: false, // 断开是否自动重连
  URL: { // 重写默认URL地址，没有传的就是用默认值
    ws: 'wss://asia-app.aihomi.com:186', // websocket地址
    uaa: 'https://uaa-openapi.aihomi.com', // uaa地址
    user: 'https://user-openapi.aihomi.com', // user地址
    console: 'https://console-openapi.aihomi.com' // console地址
  }
})

window.Matrix.setToken('') // 设置token并重连ws
window.Matrix.destroy() // 销毁Matrix

const hekr = new Hekr({
  devTid: '', // 设备devTid
  subDevTid: '', // 子设备devTid
  device, // 设备对象，传了之后就不会再去云端拉去设备信息了
  protocol, // 协议对象，传入后就不会发请求获取协议了
  Matrix: // 上面创建的Matrix对象
  query: { // 定义发送自动查询
    frame: { // 查询帧的帧内容
      cmdId: 0
    },
    duration: 30, // 查询自动查询帧时间间隔
    auto: true, // 是否自动循环发送
    timeService: [], // 授时查询，当项目需要在查询帧中带上授时时修改此参数，可选时间参数有 `year`, `month`, `week`, `day`, `hour`, `minute`
    fn: frame => frame // 查询帧函数，当授时查询不能满足项目需求或其他情况时，在此参数中传入一个函数，在查询发送前进行最后的修改操作。
  },
  decode: raw => raw, // 帧的解码函数
  encode: data => data.raw // 帧的编码函数
})

参数信息

当 SDK 启动后，在此对象中可以获取与当前用户和设备有关的参数，用于请求等。

URL

Hekr请求api域

{
  ws: 'wss://asia-app.aihomi.com:186',
  uaa: 'https://uaa-openapi.aihomi.com',
  user: 'https://user-openapi.aihomi.com',
  console: 'https://console-openapi.aihomi.com'
}

options

Hekroptions属性

{
  devTid: '',
  subDevTid: '',
  device, // 设备对象，传了之后就不会再去云端拉去设备信息了
  protocol, // 协议对象，传入后就不会发请求获取协议了
  matrix, // WebSocket包装后的对象
  token: '', // 请求token
  query: { // 定义发送自动查询
    frame: { // 查询帧的帧内容
      cmdId: 0
    },
    duration: 30, // 查询自动查询帧时间间隔
    auto: true, // 是否自动循环发送
    timeService: [], // 授时查询，当项目需要在查询帧中带上授时时修改此参数，可选时间参数有 `year`, `month`, `week`, `day`, `hour`, `minute`
    fn: frame => frame, // 查询帧函数，当授时查询不能满足项目需求或其他情况时，在此参数中传入一个函数，在查询发送前进行最后的修改操作。
    ...query
  },
  decode, // 帧的解码函数
  encode // 帧的编码函数
}

fetch

Hekr发送请求的Api，可直接调用$hekr.fetch({...})发送请求，使用方式和axios一样(就是对axios的封装)，使用示例可参考云端 API部分

{
  device: Function, // 拉取设备
  protocol: Function // 拉取协议
}

device

设备信息参数在 Hekr.device 中查看，格式详见 列举设备列表。

{
  device: {
    deviceName: '...',
    devTid: '...',
    ...
  }
}

template

协议信息参数在 Hekr.template 中查看，格式详见 获取产品协议模板。

{
  template: {
    protocol: {
      ...
    },
    workModeType: '...',
    ...
  }
}

设备通信

针对不同的项目，在 console 平台对应的产品页面中，会建立不同的协议模板，SDK 根据这个协议模板来进行协议的编码和解码。

例如，某产品有如下协议模板：

参数

命令

通常，当设备接收到 queryDev 的查询帧，或 setSw 的下发帧导致设备状态改变时，设备会主动发送 reportDev 的上报帧。

发送数据

调用 Hekr.send 方法来发送数据，传入一个带有命令名称 cmdTag 和命令所需参数的对象，SDK 会自动根据协议类型进行编码并发送。其中，命令名称 cmdTag: 'setSw' 也可以替换成命令ID cmdId: 2，但建议使用命令名称 cmdTag。

$Hekr.send({
  cmdTag: 'setSw',
  sw: 1
})

接收数据

调用 Hekr.on 方法来监听命令，设备上报是devSend。

$Hekr.on('devSend', data => {
  console.log(data)
})

SDK 也提供与 on 方法对应的，同属事件系统的 off、once 和 emit 方法。

// 监听单次事件
$Hekr.once('devSend', data => {
  console.log(data)
})

// 移除所有事件
$Hekr.off()
// 移除某一事件
$Hekr.off('devSend')
// 移除某一事件下的某一回调函数
$Hekr.off('devSend', fn)

// 主动触发事件
$Hekr.emit('devSend', data)

自定义查询帧

查询帧是一种特殊的下发帧。通常情况下，需要每隔 30 秒查询一次。SDK 预设了一种没有其他参数、且每 30 秒发送一次的查询帧。此外，开发者可对查询帧进行自定义，满足不同项目的需求。

// 默认查询帧格式
{ cmdId: 0 }

// 自定义查询帧
new Hekr({
  devTid: '',
  query: {
    frame: {
      cmdId: 0
    },
    duration: 30,
    auto: true,
    timeService: [],
    fn: frame => frame
  }
})

自定义参数

• frame

查询帧格式，当查询帧不为 { cmdId: 0 } 时修改此参数。

• duration

查询周期，当查询帧不为每30秒发送时修改此参数。

• auto

是否自动查询，当项目不需要自动查询或只需手动发送一帧时修改此参数。

• timeService

授时查询，当项目需要在查询帧中带上授时时修改此参数，可选时间参数有 year, month, week, day, hour, minute。

• fn

查询帧函数，当授时查询不能满足项目需求或其他情况时，在此参数中传入一个函数，在查询发送前进行最后的修改操作。

自定义编解码函数

对于协议类型为 JSON透传协议不校验raw 的项目，需要开发者自行编写自定义的编解码函数，请先阅读理解 串口透传协议。

// 默认函数
new Hekr({
  decode: raw => raw,
  encode: data => data.raw
})

自定义编解码时，只需关注产品业务数据部分，数据头和数据尾会由 SDK 自动补全。例如：

自定义解码

函数中的参数 raw 为帧格式中的产品业务数据部分，并非完整的帧。

// 如果接收的数据为 '48070101010052'
// Hekr 会预先截取产品业务数据部分，即 '0100'
function decode (raw) {
  // raw 为　'0100'
  // ...
  // 最后应该返回 { cmdTag: 'reportDev', cmdId: 1, sw: 0 }
  return decoded
}

自定义编码

函数中的参数 data 为调用 Hekr.send 时所传的数据，且只需要返回帧格式中的产品业务数据部分，并非完整的帧。

// 如果发送的数据为 { cmdId: 2, sw: 1 }　
function encode (data) {
  // ...
  // 最后应该返回 '0201'
  return encoded
}
// Hekr 会补全数据头和数据尾后再发送，即 '48070201020155'

ready函数

SDK 提供一个 ready 方法，用于在完成准备阶段，获取到所有必需参数后，触发回调函数。开发者在页面加载完毕时进行的接口请求等操作，需要在这个回调函数里执行。此外，在没有提供回调函数的情况下返回 Promise。

$Hekr.ready(() => {
  // ...
}).catch(err => {
  // ...
})

// 或

$Hekr.ready()
  .then(() => {
    // ...
  })
  .catch(err => {
    // ...
  })