控制消息接口枚举

本篇介绍了控制设备的结构请求结构,控制设备的意图在header中,参数在payload中

3.1 电源控制

控制设备的电源开关

接口名称: DNA.PowerControl

ChangePowerState请求

请求例子

    {
      "directive": {
        "header": {
           "namespace": "DNA.PowerControl",
           "name": "ChangePowerState",
           "interfaceVersion": "2",
           "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
        },
        "endpoint": {
          "endpointId": "appliance-001",
	      "devicePairedInfo":devicePairedInfo,
          "cookie": {}
        },
        "payload": {
          "powerState": "ON"
        }
      }
    }

响应例子

    {
      "context": {
        "properties": [ {
           "namespace": "DNA.PowerControl",
           "name": "powerState",
           "value": "ON",
           "timeOfSample": "2017-02-03T16:20:50.52Z"
        } ]
      },
      "event": {
        "header": {
           "namespace": "DNA.PowerControl",
           "name": "Response",
           "interfaceVersion": "2",
           "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4"
        },
        "endpoint": {
          "endpointId": "appliance-001"
        },
        "payload": {
        }
      }
    }
3.2 频道控制

控制电视/机顶盒频道

接口名称: DNA.ChannelControl

请求例子

    {
      "directive": {
        "header": {
           "namespace": "DNA.ChannelControl",
           "name": "ChangeChannel",
           "interfaceVersion": "2",
           "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
        },
        "endpoint": {

          "endpointId": "appliance-001",
          "devicePairedInfo":devicePairedInfo,
          "cookie": {}
        },
        "payload": {
              "channelNumber":"1234"
        }
      }
    }

响应例子

    {
      "context": {
        "properties": [ {
           "namespace": "DNA.ChannelControl",
           "name": "channelNumber",
           "value":"123",
           "timeOfSample": "2017-02-03T16:20:50.52Z"
        } ]
      },
      "event": {
        "header": {
           "namespace": "DNA.ChannelControl",
           "name": "Response",
           "interfaceVersion": "2",
           "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4"
        },
        "endpoint": {
          "endpointId": "appliance-001"
        },
        "payload": {
        }
      }
    }

按步长调整频道

请求:

    {
      "directive": {
        "header": {
          "namespace": "DNA.ChannelControl",
          "name": "AdjustChannel",
          "messageId": "c8d53423-b49b-48ee-9181-f50acedf2870",
          "payloadVersion": "2"
        },
       "endpoint": {
          "endpointId": "appliance-001",
          "devicePairedInfo":devicePairedInfo,
          "cookie": {}
        },
        "payload": {
          "channelSteps" : 1
        }
      }
    }

响应:

    {
      "context": {
        "properties": [
            {
               "namespace": "DNA.ChannelControl",
               "name": "channelSteps",
               "value": 1
               "timeOfSample": "2017-02-03T16:20:50.52Z"
            }
        ]
      },
      "event": {
          "header": {
          "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
          "name": "Response",
          "payloadVersion": "2"
        },
        "endpoint": {
          "endpointId": "appliance-001"
        },
        "payload": {
        }
      }
    }
3.3 音量控制

控制设备的音量

接口名称: DNA.VolumeControl

响应

    {
      "context": {
        "properties": [
            {
               "namespace": "DNA.VolumeControl",
               "name": "volumeSteps",
               "value": 20
               "timeOfSample": "2017-02-03T16:20:50.52Z"
            }
        ]
      },
      "event": {
          "header": {
          "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
          "name": "Response",
          "payloadVersion": "2"
        },
        "endpoint": {
          "endpointId": "appliance-001"
        },
        "payload": {
        }
      }
    }

响应

    {
      "context": {
        "properties": [
            {
               "namespace": "DNA.VolumeControl",
               "name": "volume",
               "value": 50
               "timeOfSample": "2017-02-03T16:20:50.52Z"
            }
        ]
      },
      "event": {
          "header": {
          "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
          "name": "Response",
          "payloadVersion": "2"
        },
        "endpoint": {
          "endpointId": "appliance-001"
        },
        "payload": {
        }
      }
    }

响应

    {
      "context": {
        "properties": [
            {
               "namespace": "DNA.VolumeControl",
               "name": "mute",
               "value": true
               "timeOfSample": "2017-02-03T16:20:50.52Z"
            }
        ]
      },
      "event": {
          "header": {
          "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
          "name": "Response",
          "payloadVersion": "2"
        },
        "endpoint": {
          "endpointId": "appliance-001"
        },
        "payload": {
        }
      }
    }
3.4播放控制

控制设备的播放/暂停等,由于播放控制不涉及状态,所有返回是统一的。

接口名称:DNA.PlaybackControl

    {
      "directive": {
        "header": {
          "namespace": "DNA.PlaybackController",
          "name": "Pause",
          "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
          "payloadVersion": "2"
        },
        "endpoint": {
          "endpointId": "<设备ID,发现时返回>",
	  "devicePairedInfo":devicePairedInfo,
          "cookie": {}
        },
        "payload": {
        }
      }
    }
3.5风速控制
控制风扇的速度

接口名称:DNA.WindSpeedControl

响应:

    {
      "context": {
        "properties": [
            {
               "namespace": "DNA.PercentageControl",
               "name": "windSpeed",
               "value":"HIGH",
               "timeOfSample": "2017-02-03T16:20:50.52Z"
            }
        ]
      },
      "event": {
          "header": {
          "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
          "name": "Response",
          "payloadVersion": "2"
        },
        "endpoint": {
          "endpointId": "appliance-001"
        },
        "payload": {
        }
      }
    }

具体支持的列表,请参考智能家居接口属性参考表

响应:

    {
      "context": {
        "properties": [
            {
               "namespace": "DNA.PercentageControl",
               "name": "windSpeedSteps",
               "value":1,
               "timeOfSample": "2017-02-03T16:20:50.52Z"
            }
        ]
      },
      "event": {
          "header": {
          "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
          "name": "Response",
          "payloadVersion": "2"
        },
        "endpoint": {
          "endpointId": "appliance-001"
        },
        "payload": {
        }
      }
    }
3.6风向控制

控制设备的风向,控制不涉及状态,所有返回是统一的。

接口名称:DNA.AirFlowControl

响应:

    {
      "context": {
        "properties": [
        ]
      },
      "event": {
          "header": {
          "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
          "name": "Response",
          "payloadVersion": "2"
        },
        "endpoint": {
          "endpointId": "appliance-001"
        },
        "payload": {
        }
      }
    }

3.7颜色控制

控制设备的颜色

接口名称:DNA.ColorControl

3.8颜色名称控制

控制设备的颜色

接口名称:DNA.ColorNameControl

请求

    {
        "directive": {
            "header": {
                "namespace": "DNA.ColorNameControl",
                "name": "SetColorName",
                "interfaceVersion": "2",
                "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
            },
            "endpoint": {
                "endpointId": "appliance-001",
		"devicePairedInfo":devicePairedInfo,
                "cookie": {}
            },
            "payload": {
                "colorName": "RED"
            }
        }
    }

响应

    {
      "context": {
        "properties": [
            {
               "namespace": "DNA.ColorNameControl",
               "name": "colorName",
               "value":"RED",
               "timeOfSample": "2017-02-03T16:20:50.52Z"
            }
        ]
      },
      "event": {
          "header": {
          "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
          "name": "Response",
          "payloadVersion": "2"
        },
        "endpoint": {
          "endpointId": "appliance-001"
        },
        "payload": {
        }
      }
    }
3.9色温控制
控制设备的色温

接口名称:DNA.ColorTempControl
3.10亮度控制
控制设备的亮度

接口名称:DNA.BrightnessControl
3.11百分比控制
控制设备属性的百分比

接口名称:DNA.PercentageControl

请求:
    {
      "directive": {
        "header": {
          "namespace": "DNA.PercentageControl",
          "name": "SetPercentage",
          "interfaceVersion": "2",
          "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
        },
        "endpoint": {
          "endpointId": "appliance-001",
	  "devicePairedInfo":devicePairedInfo,
          "cookie": {}
        },
        "payload": {
          "percentage": 74
        }
      }
    }
响应:
    {
      "context": {
        "properties": [
            {
               "namespace": "DNA.PercentageControl",
               "name": "percentage",
               "value":42,
               "timeOfSample": "2017-02-03T16:20:50.52Z"
            }
        ]
      },
      "event": {
          "header": {
          "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
          "name": "Response",
          "payloadVersion": "2"
        },
        "endpoint": {
          "endpointId": "appliance-001"
        },
        "payload": {
        }
      }
    }
3.12温控器控制
控制可以调节温度的设备

接口名称:DNA.ThermostatControl

* 目标温度控制

请求:
    {
      "directive": {
        "header": {
          "namespace": "DNA.ThermostatControl",
          "name": "SetTargetTemperature",
          "interfaceVersion": "2",
          "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
        },
        "endpoint": {
          "endpointId": "appliance-001",
	  "devicePairedInfo":devicePairedInfo,
          "cookie": {}
        },
        "payload": {
          "targetPoint": {
                "value":23.0,
                "scale":"CELSIUS"
            }
        }
      }
    }
响应:
    {
      "context": {
        "properties": [
            {
               "namespace": "DNA.ThermostatControl",
               "name": "targetPoint",
               "value":{
                    "value":23.0,
                    "scale":"CELSIUS"
               },
               "timeOfSample": "2017-02-03T16:20:50.52Z"
            }
        ]
      },
      "event": {
          "header": {
          "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
          "name": "Response",
          "payloadVersion": "2"
        },
        "endpoint": {
          "endpointId": "appliance-001"
        },
        "payload": {
        }
      }
    }

具体支持的模式列表,请参考智能家居接口属性参考表

3.13温度感知
查询温度
接口名称:DNA.TemperatureSensor

请求
    {
      "directive": {
        "header": {
          "namespace": "DNA.TemperatureSensor",
          "name": "ReportState",
          "interfaceVersion": "2",
          "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
        },
        "endpoint": {
          "endpointId": "appliance-001",
	  "devicePairedInfo":devicePairedInfo,
          "cookie": {}
        },
        "payload": {}
      }
    }
响应
        {
          "context": {
            "properties": [
                {
                   "namespace": "DNA.TemperatureSensor",
                   "name": "temperature",
                   "value":{
                        "value":12,
                        "scale":"CELSIUS",
                        "attributeName":""
                        "scaleName":"",
                        "valueName":""
                   },
                   "timeOfSample": "2017-02-03T16:20:50.52Z"
                }
            ]
          },
          "event": {
              "header": {
              "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
              "name": "StateReport",
              "payloadVersion": "2"
            },
            "endpoint": {
              "endpointId": "appliance-001"
            },
            "payload": {
            }
          }
        }
3.14湿度感知
查询湿度
接口名称:DNA.HumiditySensor

请求
    {
      "directive": {
        "header": {
          "namespace": "DNA.HumiditySensor",
          "name": "ReportState",
          "interfaceVersion": "2",
          "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
        },
        "endpoint": {
          "endpointId": "appliance-001",
	  "devicePairedInfo":devicePairedInfo,
          "cookie": {}
        },
        "payload": {}
      }
    }
响应
        {
          "context": {
            "properties": [
                {
                   "namespace": "DNA.HumiditySensor",
                   "name": "humidity",
                   "value":{
                        "value":12,
                        "scale":"",
                        "attributeName":""
                        "scaleName":"",
                        "valueName":""
                   },
                   "timeOfSample": "2017-02-03T16:20:50.52Z"
                }
            ]
          },
          "event": {
              "header": {
              "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
              "name": "StateReport",
              "payloadVersion": "2"
            },
            "endpoint": {
              "endpointId": "appliance-001"
            },
            "payload": {
            }
          }
        }
3.15PM2.5感知
查询PM2.5
接口名称:DNA.PM2_5Sensor

请求
    {
      "directive": {
        "header": {
          "namespace": "DNA.PM2_5Sensor",
          "name": "ReportState",
          "interfaceVersion": "2",
          "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
        },
        "endpoint": {
          "endpointId": "appliance-001",
	  "devicePairedInfo":devicePairedInfo,
          "cookie": {}
        },
        "payload": {}
      }
    }
响应
        {
          "context": {
            "properties": [
                {
                   "namespace": "DNA.PM2_5Sensor",
                   "name": "pm2_5",
                   "value":{
                        "value":20,
                        "scale":"",
                        "attributeName":""
                        "scaleName":"",
                        "valueName":""
                   },
                   "timeOfSample": "2017-02-03T16:20:50.52Z"
                }
            ]
          },
          "event": {
              "header": {
              "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
              "name": "StateReport",
              "payloadVersion": "2"
            },
            "endpoint": {
              "endpointId": "appliance-001"
            },
            "payload": {
            }
          }
        }
3.16状态查询
请求
        {
          "directive": {
            "header": {
              "messageId": "abc-123-def-456",
              "namespace": "DNA.TemperatureSensor"|“DNA”,
              "name": "ReportState",
              "interfaceVersion": "2"
            },
            "endpoint": {
              "endpointId": "appliance-001",
	      "devicePairedInfo":devicePairedInfo,
              "cookie": {},
            },
            "payload": {
            }
          }
        }
响应:
        {
          "context": {
            "properties": [
                {
                   "namespace": "DNA.TemperatureSensor",
                   "name": "temperature",
                   "value":{
                        "value":12,
                        "scale":"",
                        "attributeName":""
                        "scaleName":"",
                        "valueName":""
                   },
                   "timeOfSample": "2017-02-03T16:20:50.52Z"
                }
            ]
          },
          "event": {
              "header": {
              "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
              "name": "StateReport",
              "payloadVersion": "2"
            },
            "endpoint": {
              "endpointId": "appliance-001"
            },
            "payload": {
            }
          }
        }

状态查询响应时,每个属性都会携带如下字段:

===================== ================== scale 单位 attributeName 属性名称 scaleName 单位名称 valueName 值名称 ===================== ==================

如果是查询一个endpoint的全部状态, namespace需要填DNA.

如果是查询单个属性,则填入对应属性的接口名称。

3.17变化通知

变化通知有三种通知:

  1. 设备属性变化,比如温度,开关状态,设备在线情况变化

  2. 设备附件状态变化,比如用户的设备名称变化,用户新增加/删除设备(本套服务不涉及这种变化)

这里描述第一种变化

当一个设备多个属性变化时,放到payload中,一起上报。

上报格式:
        {
          "context": {
            "properties": []
          },
          "event": {
              "header": {
              "namespace": "DNA",
              "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
              "name": "ChangeReport",
              "payloadVersion": "2"
            },
            "endpoint": {
              "endpointId": "appliance-001",
	      "devicePairedInfo":devicePairedInfo,
              "cookie": {}
            },
            "payload": {
              "reportType":"STATE_CHANGE",
              "change": {
                "cause": {
                  "type": "PHYSICAL_INTERACTION"
                },
                "properties": [
                  {
                    "namespace": "DNA.PowerControl",
                    "name": "powerState",
                    "value": "ON",
                    "timeOfSample": "2017-02-03T16:20:50.52Z",
                    "uncertaintyInMilliseconds": 0
                  },
		  {
                    "namespace": "DNA.EndpointHealth",
                    "name": "connectivity",
                    "value": "OK",
                    "timeOfSample": "2017-02-03T16:20:50.52Z",
                    "uncertaintyInMilliseconds": 0
                  },
                  {
                    "namespace": "DNA.PercentageControl",
                    "name": "percentage",
                    "value": 40,
                    "timeOfSample": "2017-02-03T16:20:50.52Z"
                  }
                ]
              }
            }
          }
        }
reportType 说明 备注
STATE_CHANGE 设备状态变化

cause字段用来描述设备状态变化的原因。

3.18错误响应
查询湿度
接口名称:DNA.ErrorResponse

响应
        {
          "context": {},
          "event": {
              "header": {
              "namespace": "DNA",
              "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
              "name": "ErrorResponse",
              "payloadVersion": "2"
            },
            "endpoint": {
              "endpointId": "appliance-001"
            },
            "payload": {
                "type": "ENDPOIONT_UNREACHABLE",
                "message":"设备离线"
            }
          }
        }
        {
          "context": {},
          "event": {
              "header": {
              "namespace": "DNA",
              "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
              "name": "ErrorResponse",
              "payloadVersion": "2"
            },
            "endpoint": {
              "endpointId": "appliance-001"
            },
            "payload": {
                "type": "VALUE_OUT_OF_RANGE",
                "message":"值越界",
                "validRange": {
                    "minimumValue":10,
                    "maximumValue":200
                }
            }
          }
3.20运动控制

控制设备的动作,所有返回是统一的。

接口名称:DNA.MotionControl

响应

    {
      "context": {
        "properties": [
        ]
      },
      "event": {
          "header": {
          "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
          "name": "Response",
          "payloadVersion": "2"
        },
        "endpoint": {
          "endpointId": "appliance-001"
        },
        "payload": {
        }
      }
    }
3.21文本控制

通过文本字符串控制设备或者场景

接口名称: DNA.TextControl

请求例子

    {
      "directive": {
        "header": {
           "namespace": "DNA.TextControl",
           "name": "Request",
           "interfaceVersion": "2",
           "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
        },
        "endpoint": {
          "endpointId": "appliance-001",
	  "devicePairedInfo":devicePairedInfo,
          "cookie": {}
        },
        "payload": {
          "text":"",
          "additionals":{}
        }
      }
    }

响应例子

    {
      "context": {
      },
      "event": {
        "header": {
           "namespace": "DNA.TextControl",
           "name": "Response",
           "interfaceVersion": "2",
           "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4"
        },
        "endpoint": {
          "endpointId": "appliance-001"
        },
        "payload": {
            "answerText":"",
            "endpoints":[
                {
                    "endpointId":"",
                    "actions": [{
                        "namespace":"",
                        "name":"",
                        "value":{}
                    }
                    ]
                }
            ]
        }
      }
    }
3.22自定义面板控制

控制RM自定义面板,需要运维设置是否返回自定义面板

接口名称: DNA.CustomizedRemoteControl

请求例子

    {
      "directive": {
        "header": {
           "namespace": "DNA.CustomizedRemoteControl",
           "name": "打开",
           "interfaceVersion": "2",
           "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
        },
        "endpoint": {
          "endpointId": "appliance-001",
	  "devicePairedInfo":devicePairedInfo,
          "cookie": {}
        },
        "payload": {
          "text":"",
          "additionals":{}
        }
      }
    }

响应例子

    {
      "context": {
        "properties": []
      },
      "event": {
          "header": {
          "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
          "name": "Response",
          "payloadVersion": "2"
        },
        "endpoint": {
          "endpointId": "appliance-001"
        },
        "payload": {
        }
      }
    }

说明:

1.发现设备时能力中会返回自定义面板所支持的动作。

2.可以通过displayCategories中CUSTOMIZED来区分是否为自定义面板。

3.actions中的能力对应面板中保存的按键。

举例如下:

      {
                "endpointId":"3008880577263935437",
                "friendlyName":"自定义空调",
                "description":"BroadLink 智能遥控",
                "manufacturerName":"BroadLink",
                "icon":"https://ihcv0.ibroadlink.com/ec4appsysinfo/category2/CUSTOMIZED.png",
                "brand":"BroadLink",
                "roomName":"客厅",
                "displayCategories":[
                    "CUSTOMIZED"
                ],
                "cookie":{
                    "did":"xx",
                    "pid":"10039",
                    "sdid":"",
                    "spid":"",
                    "userid":"xx",
                    "devtype":0,
                    "devname":"自定义空调",
                    "moduleid":"3008880577263935437",
                    "moduletype":"20",
                    "familyid":"004734ce018aba779d8961378fa720bb",
                    "familyname":"我的家庭"
                },
                "isReachable":true,
                "capabilities":[
                    {
                        "type":"DNAInterface",
                        "interface":"DNA.CustomizedRemoteControl",
                        "version":"2",
                        "properties":{
                            "supported":null,
                            "proactivelyReported":false,
                            "retrievable":false
                        },
                        "actions":{
                            "supported":[
                                {
                                    "name":"打开"
                                },
                                {
                                    "name":"关闭"
                                }
                            ]
                        }
                    }
                ],
                "additional":null
      }

3.23 空调快照控制
{
  "directive": {
    "header": {
       "namespace": "DNA.ACControl",
       "name": "set",
       "interfaceVersion": "2",
       "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
    },
    "endpoint": {
      "devicePairedInfo":devicePairedInfo,
      "endpointId": "",
      "cookie": {}
    },
    "payload": {
       "state":{ 
        	"powerState":"ON",
        	"mode":"COLD",
       		"windSpeed":"AUTO",
        	"fixedTargetTemperature":26
       } 
    }
  }
}