设备功能

设备功能是对产品功能的抽象表示，是具体智能设备功能的抽象，用于描述产品功能及其参数。

设备功能定义

• 功能 Code：设备功能的编码。设备与云端的功能数据通过功能 Code 进行传输。支持字母、数字和下划线，以字母开头。

• 功能名称：功能的名称。

• 数据类型：

  类型	参数名	说明	示例
  布尔型	bool	非真即假的二值型变量。	开关功能的开或者关。
  数值型	value	可线性调节类型的数据。	温度调节，温度范围 20-40℃。
  枚举型	enum	自定义的有限集合值。	工作档位，低档/中档/高档。
  故障型	fault	用于上报和统计故障的功能，支持多故障，数据只上报。	温度传感器故障、电机故障和高温故障等。
  字符串型	string	以字符串形式传输的功能。	-
  透传型	raw	以二进制形式透传的功能。raw 型数据需要转换成 HEX 格式的数据	-

• 数据传输类型

  • 可下发可上报：指令数据可以发送给设备，设备数据可以传输给云端。
  • 只上报：数据只支持从设备传输给云端。
  • 只下发：数据只支持从云端发送给设备。

设备功能示例

以灯具产品为例，其设备功能如下所示：

code	名称	模式	类型	类型详情
switch_led	开关	rw	bool	{“type”:“bool”}
work_mode	模式	rw	enum	{“range”:[“white”, “colour”, “scene”, “music”, “scene_1”,“scene_2”, “scene_3”, “scene_4”]}
bright_value	亮度	rw	value	{“min”:25,“scale”:0, “unit”:“”, “max”:255, “step”:1}
temp_value	冷暖	rw	value	{“min”:0, “scale”:0, “unit”:“”, “max”:255,“step”:1}

微信小程序查询设备功能

通过调用云函数，即可查询设备功能。如果没有部署云函数，请参考 微信小程序云函数 完成部署。

• 查询设备功能示例代码如下所示：

      import { request } from '../../utils/request';
      const params = {
          data: {
              action: "device.specifications",
              params: {
                  "device_id": "xxx" // 填写自己的设备 id
              }
          }
      };
      request(params).then(res =>{
          console.log('res', res);
      }).catch(err => console.log('err', err))
  

• 接口返回的内容如下所示：

  {
  	"category":"dj", // 品类（设备的类别）
  	"functions":[  // 功能集合，是一个数组，这里只展示了一个
  	{
  		"code":"switch_led",  // 设备功能 code，（数据下发通过这个 code 就可以下发）
  		"type":"Boolean", // 数据类型
  		"values":"{}" // 类型详情
  	},
  	]
  }
  

微信小程序下发设备功能

取决于设备的通信方式，微信小程序里下发设备功能目前有两种方式：

• 通过接口 device.control 下发，适用于具备自联网能力的设备，如 Wi-Fi 门锁、Wi-Fi 音箱、具备 Wi-Fi 模组的多模设备等。
• 通过微信原生提供的蓝牙 API 下发，适用于无联网能力的蓝牙设备。

方式一：通过调用 device.control 接口

对于具备自联网能力的设备来说，通过调用云函数，即可下发设备功能。如果没有部署云函数，请参考 微信小程序云函数 完成部署。

下发设备功能示例代码如下所示：

const params = {
    data: {
        action: "device.control",
	// params 接口参数
        params: {
            "device_id": "xxx", // 填写自己的设备 id
	    "commands": [{ "code": "switch_led", "value": true }] // 下面的命令，
        }
    }
};
request(params).then(res =>{
    console.log('res', res); // 结果里如果返回 true 则说明下发设备成功
}).catch(err => console.log('err', err))

方式二：通过微信原生提供的蓝牙 API

对于无联网能力的蓝牙设备来说，想要下发设备功能，需要先使其与手机系统建立蓝牙连接通道，再通过微信原生提供的蓝牙 API 进行下发。

为方便小程序开发者更加快速地实现小程序蓝牙功能，涂鸦提供了蓝牙 SDK。更多详情，请参考 微信小程序蓝牙 SDK。

微信小程序查询设备状态

微信小程序里查询设备状态目前有三种方式：

• 通过接口 device.status。
• 通过 MQTT 长连接来实现数据推送。
• 通过微信原生提供的蓝牙 API 进行数据监听，适用于无联网能力的蓝牙设备。

方式一：通过 device.status 接口

const params = {
    data: {
        action: "device.status",
	// params 接口参数
        params: {
		"device_id": "xxx", // 填写自己的设备 id
		"commands": [{ "code": "switch_led", "value": true }] // 下面的命令，
        }
    }
};

request(params).then(res =>{
    console.log('res', res); 
}).catch(err => console.log('err', err))

返回的内容：

"result": [{ // 返回的数组里包含所有的状态
		"code": "switch_led",
		"value": true
	}]

方式二：通过 MQTT 长连接实现数据推送

1. 在微信小程序的 app.js 文件下连接 MQTT。

   // 引入 mqtt 文件
   import wxMqtt from './utils/mqtt/wxMqtt'
   // 在 onLaunch 生命周期里开启连接和对 mqtt 的监听
   onLaunch: function () {
   
   	wxMqtt.connectMqtt()
   
   	wxMqtt.on('close', (errorMsg) => {
   	wxMqtt.connectMqtt()
   	console.log('errorMsg: mqttClose', errorMsg);
   	})
   
   	wxMqtt.on('error', (errorMsg) => {
   	wxMqtt.connectMqtt()
   	console.log('errorMsg: mqttError', errorMsg);
   	})
   
   }
   

2. 在需要监听的页面开发监听。

   wxMqtt.on('message', (topic, newVal) => {
   console.log('message') // 监听的数据
   })
   

方式三：通过微信原生提供的蓝牙 API

对于无联网能力的蓝牙设备来说，查询设备状态的操作如下：

1. 使设备与手机系统建立蓝牙连接通道。
2. 通过微信原生提供的蓝牙 API，监听数据上报。
3. 从上报数据中，解析出设备状态数据。

为方便小程序开发者更加快速地实现小程序蓝牙功能，涂鸦提供蓝牙 SDK。更多详情，请参考 微信小程序蓝牙 SDK。

常见问题

什么时候需要使用 device.status 查询设备状态？

在刚刚进入页面或者设备状态明显变化时，通过调用该接口来查询设备状态，也可以在你认为需要使用的地方进行调用。

MQTT 为什么不稳定？

1. 请确认在手机息屏、网络切换、微信小程序切换到后台等情况下，有没有断开手机的连接并重连。
2. 确认是否处于断网状态。
3. 确认设备是否有上报。

查询设备功能的接口为什么返回权限拒绝？

请检查别的接口是否也出现同样的情况，如果只有查询设备功能的接口出现权限拒绝，说明该设备未能标准化。可通过 提交工单 的方式申请透传。