sdk-web

氦氪前端开发工具库

使用示例

index.html

属性

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

| 名称 | 类型 | 说明 | | --- | --- | --- | | URL | object | api请求相关的地址 | | device | object | 设备相关的数据 | | options | object | 从地址栏获取到的参数和初始化传递进入类的参数 | | fetch | object | api相关请求挂载的对象 | | template | object | 设备协议 |

方法

| 名称 | 参数 | 返回值 | 说明 | | --- | --- | --- | --- | | decode | 待解码数据 | object/string | 解码数据 | | emit | (enent: string) | - | 触发事件 | | encode | 待编码数据 | object/string | 编码数据 | | off | (enent: string, fn: function) | - | 移除事件监听 | | on | (enent: string, fn: function) | - | 添加事件监听 | | once | (enent: string, fn: function) | - | 只监听一次事件 | | send | (data: object) | - | 发送数据到云端 | | ready | (callback?: function) | Promise<void>| sdk准备完毕之后运行回调，如果失败会让Promise reject | | destroy | - | - | 销毁当前对象，释放占用资源 |

事件

| 名称 | 回调参数 | 说明 | | --- | --- | --- | | loading | 返回boolean值，用来控制是否显示加载中浮层 | 控制命令下发超时的时候浮层显示控制 | | online | - | 设备上线 | | offline | - | 设备离线 | | error | 错误帧内容 | 收到errorResp帧时触发 | | devSend | 设备上报帧信息 | 接收到上报帧时触发 |

使用

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

# 更改 npm 源
$ npm config set registry http://npm.hekr.me

# 稳定版
$ 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.hekr.me:186', // websocket地址
    uaa: 'https://uaa-openapi.hekr.me', // uaa地址
    user: 'https://user-openapi.hekr.me', // user地址
    console: 'https://console-openapi.hekr.me' // 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.hekr.me:186',
  uaa: 'https://uaa-openapi.hekr.me',
  user: 'https://user-openapi.hekr.me',
  console: 'https://console-openapi.hekr.me'
}

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 根据这个协议模板来进行协议的编码和解码。

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

参数

| 名称 | 类型 | 单位 | 取值范围 | 参数描述 | |:-----|:-------|:-----|:--------------|:---------| | sw | NUMBER | | · 0 关 · 1 开 | 开关 |

命令

| 名称 | 命令ID | 帧类型 | 示例帧 | 命令描述 | |:----------|:-------|:-------|:-------|:-------------| | queryDev | 0 | 下发帧 | 查看 | 设备状态查询 | | reportDev | 1 | 上报帧 | 查看 | 上报设备状态 | | setSw | 2 | 下发帧 | 查看 | 设置开关 |

通常，当设备接收到 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 => {
    // ...
  })