设备上报注意事项
<h1>设备上报注意事项</h1>
<blockquote>
<p>设备上报、设备类型、设备勿扰、所有灯、名称识别</p>
</blockquote>
<p><strong>说明：</strong>阅读此文当前，建议先掌握
<a href="https://dueros.baidu.com/business/emp/view/doc?md=%2Fmd%2Frcu-new%2Ftool-debug.md" title="行业平台工具-debug工具">行业平台工具-debug工具</a> 的使用，此工具可查看技能实际上报的设备
<a href="https://dueros.baidu.com/business/emp/view/doc?md=%2Fmd%2Frcu-new%2Ftool-find-device.md" title="行业平台工具-批量更新客控设备">行业平台工具-批量更新客控设备</a>，等同于对音箱说“发现设备”</p>
<h3>1、关于设备类型</h3>
<p>建议按照 <a href="https://dueros.baidu.com/didp/doc/dueros-bot-platform/dbp-smart-home/protocol/discovery-message_markdown" title="小度开放平台-智能家居-发现设备协议">小度开放平台-智能家居-发现设备协议</a>里的设备类型标准上报
智能家居协议中没有的设备类型，可以用现有的类型代替，上报正确的控制类型即可
（例如某厂商要接入智能锁，可用【LIGHT】类型代替）</p>
<pre><code class="language-aidl">举 例：智能家居协议里，窗帘：CURTAIN 窗纱：CURT_SIMP
客户把窗帘和窗纱全部上报成：CURTAIN
导致的问题：用户喊小度打开窗帘，窗帘和窗纱会同时打开
原 因：打开窗帘，匹配了所有类型为窗帘（CURTAIN）的设备</code></pre>
<h3>2、关于【灯】类型上报</h3>
<p>如果客户的设备有分组，建议技能上报时，尽量补充 groupName参数</p>
<pre><code class="language-aidl">举 例：客户设备【卫生间灯】
建 议：技能上报时 groupName：卫生间 friendlyName：灯</code></pre>
<h3>3、关于房务面板的上报</h3>
<p>建议上报的设备类型：SWITCH
建议上报的设备名称：请勿打扰、立即清理、请即清理等（不要用两个字的设备名）</p>
<pre><code class="language-aidl">举 例：技能上报了SWITCH 名称是【勿扰】
导致的问题：用户打开勿扰，没有正确执行
原 因：小度音箱本身有【勿扰】模式，打开勿扰会优先匹配音箱本身的模式</code></pre>
<h3>4、关于设备的控制类型</h3>
<p>一定要参考 <a href="https://dueros.baidu.com/didp/doc/dueros-bot-platform/dbp-smart-home/protocol/control-message_markdown" title="小度开放平台-智能家居-控制消息协议">小度开放平台-智能家居-控制消息协议</a>真确上报</p>
<pre><code class="language-aidl">举 例：客户通过技能对接电视
导致的问题：发现电视只能开关不能调台，调台小度提示不支持
原 因：技能给电视设备只上报了控制类型：TurnOn和TurnOff，
解决方案 ：调台的控制指令是：IncrementTVChanne（上一个频道）、 DecrementTVChannelR（下一个频道）、SetTVChannel（调频道）、ReturnTVChannel（返回上一个频道）</code></pre>
<h3>5、关于上报的设备名称</h3>
<p>一定要<strong>通俗易懂、不使用生僻字</strong>、尽量不包含<strong>数字、英文</strong>，如有数字用汉字代替
如一定要使用难以识别的名字，建议给设备上报别名（上报字段 nicknames）</p>
<pre><code class="language-aidl">举 例：用户上报了设备名称【布帘】
导致的问题：打开布帘失败
原 因：因客户口音问题，普通话不标准，查询识别成了【不良】
解决方案 ：给【布帘】上报别名 【不良】字段（nicknames）</code></pre>
<h3>6、关于场景的上报</h3>
<p>场景名称建议四个字，通俗易懂，不使用生僻字，不带数字
<img src="https://dumi-dueros-bj-tob.bj.bcebos.com/amis/2021-12/1638873073503/1638873055581.jpg" alt="" /></p>
<h3>7、关于所有灯</h3>
<p><strong>小度的兜底逻辑</strong>：打开某个不存在的灯名称，或者直接说【开灯】，会匹配所有类型为【LIGHT】的设备</p>
<p>如果需要开所有灯时，小度云只给技能发一条指令，技能需要上报设备名【所有灯】，类型为【LIGHT】
注意：上报的【所有灯】这个设备，不要添加分组，如果加了分组，就只能打开分组内的所有灯</p>
<h3>8、下面是一个完整的上报设备案例</h3>
<pre><code class="language-aidl">{
"header": {
"namespace": "DuerOS.ConnectedHome.Discovery",
"name": "DiscoverAppliancesResponse",
"messageId": "ff746d98-ab02-4c9e-9d0d-b44711658414",
"payloadVersion": "1"
},
"payload": {
"discoveredAppliances": [
{
"actions": [
"turnOn",
"turnOff",
"incrementBrightnessPercentage",
"decrementBrightnessPercentage"
],
"applianceTypes": [
"LIGHT"
],
"additionalApplianceDetails": {
"extraDetail1": "optionalDetailForSkillAdapterToReferenceThisDevice",
"extraDetail2": "There can be multiple entries",
"extraDetail3": "but they should only be used for reference purposes",
"extraDetail4": "This is not a suitable place to maintain current device state"
},
"applianceId": "uniqueLightDeviceId",
"friendlyDescription": "展现给用户的详细介绍",
"friendlyName": "卧室的灯",
"isReachable": true,
"manufacturerName": "设备制造商的名称",
"modelName": "fancyLight",
"version": "your software version number here.",
"attributes": [
{
"name": "name",
"value": "卧室的灯",
"scale": "",
"timestampOfSample": 1496741861,
"uncertaintyInMilliseconds": 10
},
{
"name": "connectivity",
"value": "REACHABLE",
"scale": "",
"timestampOfSample": 1496741861,
"uncertaintyInMilliseconds": 10
},
{
"name": "color",
"value": {
"hue": 350.5,
"saturation": 0.7138,
"brightness": 0.6524
},
"scale": "",
"timestampOfSample": 1496741861,
"uncertaintyInMilliseconds": 10
},
{
"name": "powerState",
"value": "ON",
"scale": "",
"timestampOfSample": 1496741861,
"uncertaintyInMilliseconds": 0
},
{
"name": "brightness",
"value": "50",
"scale": "",
"timestampOfSample": 1496741861,
"uncertaintyInMilliseconds": 100
}
]
},
{
"actions": [
"turnOn",
"turnOff"
],
"applianceTypes": [
"CURTAIN"
],
"additionalApplianceDetails": {
"extraDetail1": "optionalDetailForSkillAdapterToReferenceThisDevice",
"extraDetail2": "There can be multiple entries",
"extraDetail3": "but they should only be used for reference purposes",
"extraDetail4": "This is not a suitable place to maintain current device state"
},
"applianceId": "uniqueSwitchDeviceId",
"friendlyDescription": "展现给用户的详细介绍",
"friendlyName": "卧室的窗帘",
"isReachable": true,
"manufacturerName": "设备制造商的名称",
"modelName": "fancyCurtain",
"version": "your software version number here",
"attributes": [
{
"name": "name",
"value": "卧室的窗帘",
"scale": "",
"timestampOfSample": 1496741861,
"uncertaintyInMilliseconds": 10
},
{
"name": "connectivity",
"value": "REACHABLE",
"scale": "",
"timestampOfSample": 1496741861,
"uncertaintyInMilliseconds": 10
},
{
"name": "turnOnState",
"value": "ON",
"scale": "",
"timestampOfSample": 1496741861,
"uncertaintyInMilliseconds": 10
}
]
},
{
"actions": [
"turnOn",
"turnOff"
],
"applianceTypes": [
"SCENE_TRIGGER"
],
"additionalApplianceDetails": {
"extraDetail1": "detail about the scene",
"extraDetail2": "another detail about scene",
"extraDetail3": "only be used for reference purposes"
},
"applianceId": "uniqueDeviceId",
"friendlyDescription": "来自设备商的场景",
"friendlyName": "回家模式",
"isReachable": true,
"manufacturerName": "yourManufacturerName",
"modelName": "提供场景的设备型号",
"version": "your software version number here",
"attributes": [
{
"name": "name",
"value": "回家模式",
"scale": "",
"timestampOfSample": 1496741861,
"uncertaintyInMilliseconds": 10
},
{
"name": "turnOnState",
"value": "ON",
"scale": "",
"timestampOfSample": 1496741861,
"uncertaintyInMilliseconds": 0
}
]
}
],
"discoveredGroups": [
{
"groupName": "客厅",
"applianceIds": [
"001",
"002",
"003"
],
"groupNotes": "客厅照明分组控制",
"additionalGroupDetails": {
"extraDetail1": "detail about the group",
"extraDetail2": "another detail about group",
"extraDetail3": "only be used for reference group"
}
},
{
"groupName": "卧室",
"applianceIds": [
"004",
"005",
"006"
],
"groupNotes": "卧室空调的分组控制",
"additionalGroupDetails": {
"extraDetail1": "detail about the group",
"extraDetail2": "another detail about group",
"extraDetail3": "only be used for reference group"
}
}
]
}
}
</code></pre>