配置能力模型

配置能力模型介绍

#定义

设备能力配置包括数据定义及约束，对数据定义、约束的配置又称为对设备属性、事件和操作的配置。

• 属性：是由多个电控参数组成，是用户可见的而且会被同步到影子服务的参数集合。
• 事件：可以约定设备在特定时机（如：状态变更、工作环境切换、异常等）触发的事件上报格式及内容。同属性一样，设备描述文件可继承其它格式，因此也可以选择排除或重写继承模型的事件定义。
• 操作：是指使用者对设备控制时执行的操作。可以简单理解为用户对设备的控制，对应设备、遥控器、App插件等中的按键执行的操作，从范围上来说，动作可以是针对单个属性，也可以是针对一组属性，或者是针对整个设备的某几个大类的复杂交互控制。

事件与操作的主要区别**在于：事件的发起者为设备，操作的发起者为用户。

---

#基本信息

能力模型的基本信息包括影子等级、物模型1.0版本、电控固件版本和模组固件版本。

参数	说明
影子等级	总共有五个等级，等级三以下(包括三)不支持影子，支持影子的设备状态变动都会实时同步到云端。
物模型1.0版本	此能力模型版本。格式要求三段数字，由1.0.0版本开始，逐级递增。
电控固件版本	当前能力模型能支持的电控固件版本，格式要求三段数字，由1.0.0版本开始，逐级递增。
模组固件本	当前能力模型能支持的模组固件版本，格式要求三段数字，由1.0.0版本开始，逐级递增。

要确定设备影子等级前必须先对设备进行测试，给出测试报告。

---

#快速开始

在智能产品中选择“创建智能产品”，点击硬件产品。

选择品类并填写相关信息后点击“能力定义”。在导入模板后点击“选择模板导入”，选中相对应的模板并“确定”。

如果没有想要的模板，则可以新建模板。具体新建模板步骤的配置参考从零开始配置能力模型。

也可以直接通过导入已有产品直接复制同品类下的产品配置信息。 。

---

#流程

可以从已有的能力模型基础上快速开始。

也可以从零开始，能力模型的配置顺序：

1. 配置属性和配置数据集
2. 配置操作或配置事件

能力模型配置后可以调试与发布，调试环境相对于配置环境低级，测试的dcp、美居和设备环境可以使用sit或者uat。

能力模型的使用：调用接口。

3.1美的智能设备词汇库和语义模型

词汇库

基于事业部编写各个品类物模型1.0文档，整理而得常用词汇库和品类词汇库，还在持续完善中，具体地址如下：

Midea-IoT-Vocabulary(opens new window)

---

语义模型

基于W3C TD Ontology、iotschema 并结合美的IoT实际业务整理而得，还在持续完善中，具体地址如下：

Midea-IoT-Semantic(opens new window)

---

申请词汇库 如果平台现有词汇库无法满足需求，可以在系统右上角点击“工单支持”，在我的工单中点击“新建工单”来申请添加词汇，

选择“软件开发类相关”，根据按需填写，在反馈内容中标注需要添加的能力模型词汇的标识和类型，例如标识为workhour,类型为object。

3.2配置属性

选择“属性”，点击“添加标准属性”。会显示如下页面，左右拖动查看参数，也可以通过右上角搜索框进行搜索，如果属性中没有你需要的参数则可以通过提交工单来申请。

#属性的使用

属性将会用于操作与事件的配置和调用中,属性可以作为操作的输入输出参数，也可以作为事件的参数。具体请参考配置操作、配置事件和接口调用 。

操作举例：进行更改电饭煲工作模式的操作时，属性或数据集定义将作为http请求体发送给物模型1.0接口，操作成功则会返回属性集或数据集定义。

事件举例：电饭煲会定时上报自己的状态，这其实就是设备会定时将自己的属性或数据集定义上报给云端。

3.3配置数据集

新增数据集

进入能力配置页面，在操作->添加自定义/编辑->编辑进入页面，进行如下图的操作，填写数据集标识及描述后。

选中数据集并点击右上角“编辑数据集”，可以在“引用属性”中，添加参数，如果“引用属性”中没有找到想要的参数可以提交词汇库申请。

编辑数据集定义完成后下拉点击“保存”。下拉可以继续新增数据集定义，添加完数据集定义后点击“保存”

---

数据集定义的使用

数据集定义将会用于操作与事件的配置和调用中,数据集定义可以作为操作的输入输出参数，也可以作为事件的参数。具体请参考配置操作、配置事件和接口调用 。

操作举例：进行更改电饭煲工作模式的操作时，属性集或数据集定义将作为http请求体发送给物模型1.0接口，操作成功则会返回属性集或数据集定义。

事件举例：电饭煲会定时上报自己的状态，这其实就是设备会定时将自己的属性或数据集定义上传给云端。

3.4配置操作

选择“操作”之后，点击“添加自定义操作”

参数	说明
标识	必填项，支持英文字符大小写，操作唯一标识，重复的情况下会导致覆盖。
名称	必填项，支持英文大小写、中文、数字、标点符号。
是否为控制操作	操作类型主要分为控制和查询（非控制）。
是否为幂等操作	非必填，如果是控制操作，默认非幂等。非控制操作默认为幂等。

操作可以设置输入与输出，点击“编辑”。“编辑”输入输出之前请确认数据集定义或属性是否已配置，当数据集定义与属性为空时，输入与输出都没有可选项。

输入与输出的编辑有两种方法，详情参考数据定义与属性的选择。

可以在输入中定义常量，作为默认值，建议填写，因为系统不会自动赋予默认值。编辑好输入输出后点击“保存”。

保存后就能在界面看到我们添加的操作了，左上角可以继续“添加自定义操作”，右边可以对已有的操作进行“编辑”，也可以“删除”已有的操作。配置好操作后，可以点击“保存”。

这样就配置好了一个动作，具体使用详情请参考接口调用

3.5配置事件

点击“事件”，选择“添加自定义事件”

按需求填写方框中的内容，下拉点击“编辑”对数据格式进行编辑，编辑方法请参考数据定义与属性的选择。编辑完成后点击”保存“。

”保存“可以看到自己添加的事件，右上角可以继续”添加自定义事件“，右边可以对已有事件进行”编辑“或”删除“，编辑事件完成后点击“保存”。

这样就配置好了一个事件

3.6接口调用

#如何使用操作

操作的使用其实就是调用物模型1.0接口并获得响应的过程，即发送http请求到相应的地址并收到响应。

• 请求方法的选择

  幂等指方法多次调用都会获得相同的结果，安全指方法多次调用不会修改资源状态，请求方法的使用原则如下。

  方法	幂等性	安全性
  POST	否	否
  PUT	是	否
  GET	否	是

  注：表中缺失了既是幂等又是安全的场景，现实中此类场景几乎不存在，如果存在也可临时使用PUT方法来操作.

• 如何构造参数

  接口参数基于两种方式传送， GET方法，使用QueryString的方式，即：param1=val1&param2=val。 POST、PUT方法，Context-Type：appliaction/json，body为json结构，其Key为能力模型操作中定义的输入参数。 { “param1”: val1 }

• 构造http请求

  知道了输入中需要的参数(操作中的输入)及其类型之后，就能够构造请求体了（以下请求体为示例，具体使用请根据自己的需求更改）。于是我们可以发送一个http请求给物模型1.0接口，将电饭煲转换为保温模式，具体http请求如下。

  参数名	值
  请求方法	PUT
  媒体类型信息(Content-Type)	application/json
  接口地址（url）	http://sit-appliance-control.smartmidea.net/v1/appliance/operation/keepWarm/3298544980775
  请求体(requestBody)

  注：接口地址具体使用时需要修改两个参数，keepWarm改成具体的操作名，3298544980775改为具体设备编号，menuId、controlSrc、workSwitch为操作keepWarm定义的输入参数。

• 请求返回结果

  返回结果为该操作定义的输出，可以是属性，也可以是数据集定义。