plugin-websocket-mqtt

基于 MQTT WebSocket协议的微信小程序Js Sdk，支持设备指令下发、监听设备实时数据上报及连接关闭。

安装

npm install @quec-wx-mp/plugin-websocket-mqtt

import mqtt from '@quec-wx-mp/plugin-websocket-mqtt'
const plugin = requirePlugin('quecPlugin')

plugin.use(mqtt)

API 列表

| 方法 | 说明 | | ------- | ------------------------------------------ | | connect | 建立 MQTT 连接，并按消息类型分发至对应回调 | | send | 向设备下发指令 | | close | 关闭连接（等待当前消息处理完毕） |

API 详细

1) 建立连接

接口名称

connect

功能描述

建立 MQTT WebSocket 连接，连接成功后自动订阅设备 Topic，并按消息类型分发至对应回调函数。

参数

| 属性 | 类型 | 默认值 | 必填 | 说明 | | -------- | -------- | ------ | ---- | ------------------------------------------------ | | userid | string | - | 是 | 当前登录用户 ID，用于构造 MQTT clientId | | pk | string | - | 是 | ProductKey | | dk | string | - | 是 | DeviceKey | | topics | string[] | - | 否 | 自定义订阅 Topic 列表，不传时使用默认 7 个 Topic | | online | function | - | 否 | 设备上下线状态回调，消息 type == 'ONLINE' | | status | function | - | 否 | 设备与模组状态回调，消息 type == 'STATUS' | | mattr | function | - | 否 | 物模型属性上报回调，消息 type == 'MATTR' | | raw | function | - | 否 | 透传数据上行回调，消息 type == 'RAW' | | location | function | - | 否 | 设备定位信息回调，消息 type == 'LOCATION' | | ota | function | - | 否 | OTA 升级状态回调，消息 type == 'OTA' | | ask | function | - | 否 | 指令下发 ACK 回调，消息 type == 'SENDACK' | | enduser | function | - | 否 | 设备权限变更回调，消息 type == 'ENDUSER' | | error | function | - | 否 | 业务错误回调，消息 type == 'BUSI-ERROR' |

返回数据

• success 各消息回调 res 结构：

| 字段 | 类型 | 说明 | | ---------- | ------ | -------------------------- | | type | string | 消息类型，见消息类型说明 | | productKey | string | 产品 ProductKey | | deviceKey | string | 设备 DeviceKey | | data | object | 消息体，不同 type 内容不同 |

示例代码

plugin.socket.connect({
  userid: 'user_id_123',
  pk: 'your_product_key',
  dk: 'your_device_key',
  online(res) {
    // res.data.status: 1=在线, 0=离线
    console.log('设备上下线:', res)
  },
  status(res) {
    console.log('设备状态:', res)
  },
  mattr(res) {
    // res.data 为物模型属性键值对，如 { switch: 1, temperature: 25 }
    console.log('属性上报:', res)
  },
  raw(res) {
    console.log('透传数据:', res)
  },
  location(res) {
    console.log('定位信息:', res)
  },
  ota(res) {
    console.log('OTA 状态:', res)
  },
  ask(res) {
    console.log('指令响应:', res)
  },
  enduser(res) {
    console.log('权限变更:', res)
  },
  error(res) {
    console.log('业务错误:', res)
  }
})

2) 指令下发

接口名称

send

功能描述

指令下发。

参数

| 属性 | 类型 | 默认值 | 必填 | 说明 | | -------- | -------- | ------ | ---- | ------------------------------------------------------------------------------------------------------------ | | pk | string | - | 是 | ProductKey | | dk | string | - | 是 | deviceKey | | type | string | - | 是 | 类型（READ-ATTR 物模型属性-读；WRITE-ATTR 物模型属性-写；EXE-SERV 调用物模型服务；EXE-SERV2 调用物模型服务） | | sendData | array | - | 是 | 发送数据 | | success | function | - | 否 | 成功回调 | | fail | function | - | 否 | 失败回调 |

返回数据

• success(res)：发送成功响应

示例代码

// 备注：
// 发送数据, 各个类型参考格式如下：
// 布尔: [{"物模型CODE": true}]
// 枚举: [{"物模型CODE": 1}]
// 数值: [{"物模型CODE": 10}]
// 文本：[{"物模型CODE": "china"}]
// 数组: [{"物模型CODE": [{"0": 1 }, {"0": 2 }] }] (数组角标，默认都是"0")
// 结构体: [{"物模型CODE": [{"struct_attr" : 1}, {"struct_bool" : true}] }]

// 写属性（物模型）
plugin.socket.send({
  pk: 'your_product_key',
  dk: 'your_device_key',
  type: 'WRITE-ATTR',
  sendData: [{ 'switch': true }, { 'temperature': 26 }],
  success(res) {
    console.log(res)
  },
  fail(err) {
    console.log(JSON.stringify(err))
  }
})

// 物模型读取
plugin.socket.send({
  pk: 'your_product_key',
  dk: 'your_device_key',
  type: ''READ-ATTR',
  sendData: ['物模型CODE1','物模型CODE2']
})

// 调用服务（物模型）
plugin.socket.send({
  pk: 'your_product_key',
  dk: 'your_device_key',
  type: 'EXE-SERV',
  sendData: [{ 'reboot': 1 }]
})

3) 关闭连接

接口名称

close

功能描述

关闭 MQTT 连接，等待当前消息处理完毕后断开，不会立即释放资源。适合页面正常退出时使用。

参数

无

示例代码

// 在页面卸载时调用
onUnload() {
  plugin.socket.close()
}