IoT 微信小程序 | H5 SDK 使用指南

更新时间：2025-05-30 01:56:03下载pdf

使用步骤

引入模块

import { OpenSaasSDK } from ‘xxx/openSaasSdk’

初始化开发者信息，对应涂鸦云 clientId、secret、访问令牌、刷新令牌。

OpenSaasSDK.set({clientId, secret, access_token, refresh_token})

调用示例

OpenSaasSDK.request({ 
  data: {  
    action: "***.***",  
    version: "1.0",
    params: {"***":{}}
  }
});

方法列表

动作	版本号	描述
mqtt.getMqttConfig	1.0	获取MQTT连接配置
device.listDevices	1.0	获取设备列表
device.getDeviceStatus	1.0	获取设备最新状态
device.batchQuerySwitchStatus	1.0	批量查询开关状态
device.getDeviceFunctions	1.0	获取设备功能集列表
device.getDeviceSpecifications	1.0	获取设备规格属性列表
device.controlDevice	1.0	下发设备指令
device.controlDeviceSwitch	1.0	控制设备开关
device.controlInfraredDevice	1.0	控制红外设备
device.getInfraredStatus	1.0	获取红外设备最新状态
scene.listScenes	1.0	获取场景列表
scene.triggerScenes	1.0	触发场景
doorLock.remoteUnlock	1.0	zigbee远程开锁
elevator.qrcode	1.0	获取梯控二维码
见底部	1.0	小程序蓝牙SDK使用步骤

获取MQTT连接配置

方法说明

获取MQTT连接配置

方法参数

action	version
mqtt.getMqttConfig	1.0

请求参数

参数名	类型	说明
connect_id	String	终端设备唯一标识(非必传，建议传)

响应参数

参数名	类型	说明
code	Integer	响应码（详情见错误码章节），成功时为空
success	Boolean	是否成功：（true：成功，false：失败）
msg	String	请求失败的信息，成功时为空
result	Object	MQTT连接配置

result参数说明

参数名	类型	说明
client_id	String	mqtt连接client_id（用户账号及unique_id 生成的一个唯一不变的映射）一个clientId 即可以用于发布也可以订阅
expire_time	Integer	当前配置失效期，当前配置失效，所有的链接都将断开
username	String	mqtt连接用户名（用户账号生成的一个唯一不变的映射）
password	String	mqtt连接密码，失效期内该字段不变
sink_topic	Map	mqtt topic：用户下发设备控制的mqtt，格式cloud/token/out/{dev_id}，传具体控制的iot设备id
source_topic	Map	mqtt topic：设备上报消息推送给该账号(支持多个clientId取链接)
url	String	Mmqtt链接地址（包括协议、ip、port）

请求示例

OpenSaasSDK.request({ 
  data: {  
    action: "mqtt.getMqttConfig",
    version: "1.0",
    params: {
      "connect_id": "******"
    },
  }
});

成功响应示例

{
  "result": {
    "client_id": "******",
    "expire_time": 7200,
    "username": "******",
    "password": "******",
    "sink_topic":{
      "device":"cloud/token/out/{device_id}"
    },
    "source_topic":{
      "device":"cloud/token/in/22e37df6e53bc8******"
    },
    "url": "wss://m1.tuyacn.com:443/mqtt"
    }, 
    "success": true
}

失败响应示例

{
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false
}

获取设备列表

方法描述

获取设备列表

方法参数

action	version
device.listDevices	1.0

响应参数

参数名	类型	说明
code	Integer	响应码（详情见错误码章节），成功时为空
success	Boolean	是否成功：（true：成功，false：失败）
msg	String	请求失败的信息，成功时为空
result	Array	设备列表

result参数说明

参数名	类型	说明
device_id	String	设备唯一标识
product_id	String	产品唯一标识
device_name	String	设备名称
category_name	String	品类名称
category_code	String	品类编码
sub	Boolean	子设备标识
online	Boolean	是否在线
position	String	位置
dp_count	Integer	Data point数量

请求示例

OpenSaasSDK.request({ 
  data: {  
    action: "device.listDevices",
    version: "1.0" 
  }
});

成功响应示例

{
  "result": [
    {
      "category_code": "ckqdkg",
      "category_name": "",
      "device_id": "6c423606c35******",
      "device_name": "Zigbee low-frequency card power switch",
      "dp_count": 0,
      "online": true,
      "position": "Living room",
      "product_id": "iqsefpek",
      "sub": false
    }
  ], 
  "success": true
}

失败响应示例

{
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false
}

获取设备最新状态

方法描述

获取设备最新状态

方法参数

action	version
device.getDeviceStatus	1.0

请求参数

参数名	类型	说明
device_id	String	设备唯一标识

响应参数

参数名	类型	说明
code	Integer	响应码（详情见错误码章节），成功时为空
success	Boolean	是否成功：（true：成功，false：失败）
msg	String	请求失败的信息，成功时为空
result	Array	设备状态列表

result参数说明

参数名	类型	说明
code	String	状态码
value	String	状态值

请求示例

OpenSaasSDK.request({ 
  data: {  
    action: "device.getDeviceStatus",
    version: "1.0",
    params: {
      "device_id": "6c760b4d9668******_switch_2"
    }
  }
});

成功响应示例

{
  "result": [
    {
      "code": "switch",
      "value": "true"
    }
  ], 
  "success": true
}

失败响应示例

{
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false
}

批量查询设备开关状态

方法描述

批量查询设备开关状态

方法参数

action	version
device.batchQuerySwitchStatus	1.0

请求参数

参数名	类型	说明
device_ids	List	设备唯一标识列表

响应参数

参数名	类型	说明
code	Integer	响应码（详情见错误码章节），成功时为空
success	Boolean	是否成功：（true：成功，false：失败）
msg	String	请求失败的信息，成功时为空
result	Array	设备开关状态列表

result参数说明

参数名	类型	说明
device_id	String	设备唯一标识
status	Boolean	开关状态

请求示例

OpenSaasSDK.request({ 
  data: {  
    action: "device.batchQuerySwitchStatus",
    version: "1.0",
    params: {
      "device_id": "6c760b4d9668******"
    }
  }
});

成功响应示例

{
  "result": [
    {
      "device_id": "6c760b4d9668******",
      "status": true
    }
  ], 
  "success": true
}

失败响应示例

{
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false
}

获取设备功能集

方法描述

获取设备功能集

方法参数

action	version
device.getDeviceFunctions	1.0

请求参数

参数名	类型	说明
device_id	String	设备唯一标识

响应参数

参数名	类型	说明
code	Integer	响应码（详情见错误码章节），成功时为空
success	Boolean	是否成功：（true：成功，false：失败）
msg	String	请求失败的信息，成功时为空
result	Object	返回结果

result参数说明

参数名	类型	说明
category_code	String	品类编码
functions	Array	功能集列表

result.functions参数说明

参数名	类型	说明
code	String	功能码
type	String	功能类型
values	String	参数取值范围
name	String	功能名称
desc	String	功能详情

请求示例

OpenSaasSDK.request({ 
  data: {  
    action: "device.getDeviceFunctions",
    version: "1.0",
    params: {
      "device_id": "6c760b4d96688******"
    }
  }
});

成功响应示例

{
  "result": {
    "category": "kg",
    "functions": [
      {
        "name": "Switch",
        "desc": "Main switch. true: all on. false: all off.",
        "code": "switch",
        "type": "Boolean",
        "values": "{}"
      }
    ] 
  },
  "success": true
}

失败响应示例

{
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false
}

获取设备规格属性

方法描述

获取设备规格属性

方法参数

action	version
device.getDeviceSpecifications	1.0

请求参数

参数名	类型	说明
device_id	String	设备唯一标识

响应参数

参数名	类型	说明
code	Integer	响应码（详情见错误码章节），成功时为空
success	Boolean	是否成功：（true：成功，false：失败）
msg	String	请求失败的信息，成功时为空
result	Object	返回结果

result参数说明

参数名	类型	说明
category_code	String	品类编码
functions	Array	功能集列表
status	Array	状态集列表

result.functions参数说明

参数名	类型	说明
code	String	功能码
type	String	功能类型
values	String	参数取值范围
name	String	功能名称
desc	String	功能详情

result.status参数说明

参数名	类型	说明
code	String	状态码
type	String	状态类型
values	String	参数取值范围.

请求示例

OpenSaasSDK.request({ 
  data: {  
    action: "device.getDeviceSpecifications",
    version: "1.0",
    params: {
      "device_id": "6c760b4d96688******"
    }
  }
});

成功响应示例

{
  "result": {
    "category": "kg",
    "functions": [
      {
        "name": "Switch",
        "desc": "Main switch. true: all on. false: all off.",
        "code": "switch",
        "type": "Boolean",
        "values": "{}"
      }
    ],
    "status":[
      {
        "code":"switch_1",
        "type":"Boolean",
        "values":"{}"
      }
    ]
  },
  "success": true
}

失败响应示例

{
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false
}

控制设备

方法描述

根据设备唯一标识下发指令

方法参数

action	version
device.controlDevice	1.0

请求参数

参数名	类型	说明
device_id	String	设备唯一标识
commands	Array	指令集

commands参数说明

参数名	类型	说明
code	String	指令码
value	Object	指令值

响应参数

参数名	类型	说明
code	Integer	响应码（详情见错误码章节），成功时为空
success	Boolean	是否成功：（true：成功，false：失败）
msg	String	请求失败的信息，成功时为空
result	Boolean	操作结果

请求示例

OpenSaasSDK.request({ 
  data: {  
    action: "device.getDeviceSpecifications",
    version: "1.0",
    params: {
      "device_id": "6c760b4d96688******",
      "commands": [
        {
          "code": "switch_1",
          "value": false
        }
      ]
    }
  }
});

成功响应示例

{
  "result": true,
  "success": true
}

失败响应示例

{
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false
}

控制设备开关

方法描述

根据设备唯一标识控制开关

方法参数

action	version
device.controlDeviceSwitch	1.0

请求参数

参数名	类型	说明
device_id	String	设备唯一标识
value	Boolean	Device switch. true:开；false:关

响应参数

参数名	类型	说明
code	Integer	响应码（详情见错误码章节），成功时为空
success	Boolean	是否成功：（true：成功，false：失败）
msg	String	请求失败的信息，成功时为空
result	Boolean	操作结果

请求示例

OpenSaasSDK.request({ 
  data: {  
    action: "device.controlDeviceSwitch",
    version: "1.0",
    params: {
      "device_id": "6c760b4d96688******",
      "value": true
    }
  }
});

成功响应示例

{
  "result": true,
  "success": true
}

失败响应示例

{
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false
}

控制红外设备

方法描述

根据设备唯一标识控制红外设备

方法参数

action	version
device.controlInfraredDevice	1.0

请求参数

参数名	类型	说明
infrared_id	String	红外设备唯一标识
standard_key	String	红外设备标准key

响应参数

参数名	类型	说明
code	Integer	响应码（详情见错误码章节），成功时为空
success	Boolean	是否成功：（true：成功，false：失败）
msg	String	请求失败的信息，成功时为空
result	Boolean	操作结果

请求示例

OpenSaasSDK.request({ 
  data: {  
    action: "device.controlInfraredDevice",
    version: "1.0",
    params: {
      "infrared_id": "6c760b4d966882******",
      "standard_key": "PowerOn"
    }
  }
});

成功响应示例

{
  "result": true,
  "success": true
}

失败响应示例

{
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false
}

获取红外设备最新状态

方法描述

根据设备唯一标识获取红外设备最新状态

方法参数

action	version
device.getInfraredStatus	1.0

请求参数

参数名	类型	说明
infrared_id	String	红外设备唯一标识

响应参数

参数名	类型	说明
code	Integer	响应码（详情见错误码章节），成功时为空
success	Boolean	是否成功：（true：成功，false：失败）
msg	String	请求失败的信息，成功时为空
result	Object	返回结果

请求示例

OpenSaasSDK.request({ 
  data: {  
    action: "device.getInfraredStatus",
    version: "1.0",
    params: {
      "infrared_id": "6c760b4d966882******"
    }
  }
});

成功响应示例

{
  "result": {
    "mode": "4",
    "temp": "22",
    "power": "1",
    "wind": "2"
  },
  "success": true
}

失败响应示例

{
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false
}

获取场景列表

方法描述

获取场景列表

方法参数

action	version
scene.listScenes	1.0

响应参数

参数名	类型	说明
code	Integer	响应码（详情见错误码章节），成功时为空
success	Boolean	是否成功：（true：成功，false：失败）
msg	String	请求失败的信息，成功时为空
result	Array	场景列表

result参数说明

参数名	类型	说明
scene_id	String	场景唯一标识
name	String	场景名称

请求示例

OpenSaasSDK.request({ 
  data: {  
    action: "scene.listScenes",
    version: "1.0" 
  }
});

成功响应示例

{
  "result": [
    {
      "scene_id": "*******",
      "name": "Turn on all lights"
    }
  ], 
  "success": true
}

失败响应示例

{
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false
}

触发场景

方法描述

根据场景唯一标识触发场景

方法参数

action	version
scene.triggerScenes	1.0

请求参数

参数名	类型	说明
scene_id	String	场景唯一标识

响应参数

参数名	类型	说明
code	Integer	响应码（详情见错误码章节），成功时为空
success	Boolean	是否成功：（true：成功，false：失败）
msg	String	请求失败的信息，成功时为空
result	Boolean	操作结果

请求示例

OpenSaasSDK.request({ 
  data: {  
    action: "scene.triggerScenes",
    version: "1.0",
    params: {
      "scene_id": "6c760******f"
    }
  }
});

成功响应示例

{
  "result": true, 
  "success": true
}

失败响应示例

{
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false
}

zigbee远程开锁

方法描述

zigbee门锁免密开锁

方法参数

action	version
doorLock.remoteUnlock	1.0

请求参数

参数名	类型	说明
device_id	String	设备唯一标识

响应参数

参数名	类型	说明
code	Integer	响应码（详情见错误码章节），成功时为空
success	Boolean	是否成功：（true：成功，false：失败）
msg	String	请求失败的信息，成功时为空
result	Boolean	操作结果

请求示例

OpenSaasSDK.request({ 
  data: {  
     action: "doorLock.remoteUnlock",
     version: "1.0",
     params: {
     device_id: "04020475840d8e*****"
    }

  }
});

成功响应示例

{
  "result": true, 
  "success": true
}

失败响应示例

{
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false
}

MQTT连接、监听消息

引入模块

import { SaasMqtt } from 'xxx/openSaasSdk'

连接MQTT

方法描述: 连接mqtt(含消息订阅)
方法: SaasMqtt.connectMqtt(config)

参数说明

参数名	类型	说明
config	Object	mqtt连接配置

config参数说明

参数名	类型	说明
client_id	String	mqtt连接client_id（用户账号及unique_id 生成的一个唯一不变的映射）一个clientId 即可以用于发布也可以订阅
expire_time	Integer	当前配置失效期，当前配置失效，所有的链接都将断开
username	String	mqtt连接用户名（用户账号生成的一个唯一不变的映射）
password	String	mqtt连接密码，失效期内该字段不变
sink_topic	Map	mqtt topic：用户下发设备控制的mqtt，格式cloud/token/out/{dev_id}，传具体控制的iot设备id
source_topic	Map	mqtt topic：设备上报消息推送给该账号(支持多个clientId取链接)
url	String	Mmqtt链接地址（包括协议、ip、port）

示例

async function () {
  const  { result } = await OpenSaasSDK.getgetMqttConfig()
  SaasMqtt.connectMqtt(result)
}

监听消息

方法描述: 监听MQTT实例
方法: SaasMqtt.on(event, fn)

参数说明

参数名	类型	说明
event	Object	监听事件名称
fn	Function	监听事件的处理函数

event参数说明

参数名	类型	说明
close	String	关闭连接事件
disconnect	String	连接断开事件
offline	String	脱机事件
error	String	发生错误事件
message	String	接收消息事件

特殊情况
对应监听事件为message时，fn回调函数有三个回调参数可使用

event参数说明

参数名	类型	说明
topic	String	消息队列topic
message	String	消息体
packet	String	数据包

示例

SaasMqtt.on('message',  (topic, message) => {
  console.log(message)
});

建议将mqtt对象放入全局变量中使用,方法处理对应面板的消息推送

注意事项

由于微信的websocket机制问题，mqtt会经常断开连接所以需要在app.js文件中的onShow生命周期监听函数中添加如下代码:

// ...获取mqtt配置 -config    
SassMqtt.connectMqtt(config)

SassMqtt.on(‘close’, (errMsg) => {
  // ...获取mqtt配置 -config 
  SassMqtt.connectMqtt(config)
  console.log(‘errorMsg: mqttClose’, errMsg)
})

SassMqtt.on(‘error, (errMsg) => {
   //... 获取mqtt配置
  SassMqtt.connectMqtt(config)
  console.log(‘errorMsg: mqttError, errMsg)
})

获取梯控二维码

方法描述

获取梯控二维码

方法参数

action	version
elevator.qrcodes	1.0

响应参数

参数名	类型	说明
code	Integer	响应码（详情见错误码章节），成功时为空
success	Boolean	是否成功：（true：成功，false：失败）
msg	String	请求失败的信息，成功时为空
result	String	梯控二维码

请求示例

OpenSaasSDK.request({ 
  data: {  
    action: "elevator.qrcodes",
    version: "1.0" 
  }
});

成功响应示例

{
  "result":  "1d3edf0002ad00736ff1e775da***************8cd5a9f51e2b957749e738c2*********730a8ad372f1",
  "success": true
}

失败响应示例

{
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false
}

小程序蓝牙SDK使用步骤

（一） index.js 为小程序SDK的js文件，bleSDK是蓝牙相关，导出OpenSaasSDK,BleSDK

import { OpenSaasSDK,BleSDK } from ‘xxx/index’

（二）pre 为预发测试环境，prod为线上环境，线上环境暂未部署，先预发测试环境调试

// pre 为预发测试环境，prod为线上环境 ，线上环境暂未部署，先预发测试环境调试
OpenSaasSDK.setEnv('pre')

（三）初始化开发者信息，对应涂鸦云clientId、secret、访问令牌、刷新令牌。

OpenSaasSDK.set({clientId, secret, access_token, refresh_token})

（四）调用device.listDevices，获取设备列表，会获取到device_id，并保存后续使用，

OpenSaasSDK.request({
      data: {
        version: "1.0",
        action: "device.listDevices",
        params: {}
      }
 })

（五）蓝牙初始化，需要传入设备ID：device_id，获取到的instance是蓝牙的实例，只要实例存在，就可以直接调用开锁，获取实例下面获取已创建的实例

const instance = await BleSDK.initBle(device_id)

（六）注册监听蓝牙通信，instance.onReceivePackage((parseReceiveData) => {}),会有相对应的连接失败，未发现蓝牙设备，蓝牙连接成功等回调，可以针对相对应的状态展示不同情况以及开锁等操作

 instance.onReceivePackage(async(parseReceiveData) => {
          const {
            type,
            status,
            dpState,
            deviceId,
          } = parseReceiveData
          if (type === 'connect' && status === 'fail') {
            if (deviceId) {
              console.log('连接失败 或 连接后又断开');
            } else {
              console.log('未发现当前蓝牙设备');
            }
          } else if (type === 'connect' && status === 'connected') {
            console.log('蓝牙连接成功');
           //  蓝牙连接成功后，有两个流程：（可单独写，也可以直接调用方法）
              //   1.调用sendOpenRandomSync方法，下发随机数等相关配置
                 await BleSDK.sendOpenRandomSync()
             //    2.调用sendDpOpenDoor进行开锁相关流程
                BleSDK.sendDpOpenDoor()
          } else if (!(deviceId in parseReceiveData) && dpState) {
           // 一般为dp上报事件，可在此处处理数据or走业务逻辑
          // 上报的数据会被处理成 dpState 对象，dpState 对象下面有举例
         // todo...
                this.handleData(dpState)
          }
        })

回调参数说明

参数名	类型	说明
type	string	状态类型：connect-连接状态; otaStatus-OTA 升级状态;send-发送状态
status	string	状态值
deviceId	string	蓝牙设备 ID，安卓下为mac地址
dpState	Object	当前蓝牙设备的功能状态集

回调参数status数值说明

type	status数值	说明
connect	ready	SDK 准备进行蓝牙连接，进入此状态后，请勿再重复调用connectBlue进行连接，否则可能会导致连接失败
–	connecting	连接中
–	connected	蓝牙连接成功
–	fail	蓝牙连接失败
otaStatus	updating	OTA中
–	updated	OTA成功
–	fail	OTA失败
send	sending	数据发送中
–	sended	数据发送完毕

（七）开始连接蓝牙

    instance.connectBlue()

（八）开锁需要调用的方法，内部已经封装好，可直接调用

    BleSDK.sendOpenRandomSync()
    BleSDK.sendDpOpenDoor()

（九）获取已创建的实例，传入设备ID

    const instance = BleSDK.config.bleService.instance[device_id]
    //也可通过该方式获取已生成的设备实例。BleService.instance 为 BleService 维护的设备实例列表。

参数说明

字段	数据类型	说明
device_id	String	蓝牙设备配网后生成的虚拟 ID

（十）可在页面生命周期销毁时销毁设备的实例

   BleSDK.config.bleService.destroyInstance(device_id)

上一篇IoT 微信小程序或 H5 SDK 授权

下一篇PMS接入