功能定义

功能定义是通过建立一套配置信息，来描述不同设备的基础能力，包括设备的属性、事件和命令，从而为设备接入和应用开发建立一套成熟的规范。

功能定义对设备类型关联的所有设备都有效。

如何添加功能定义

在设备类型中，支持多种方式来添加功能定义。

手动添加功能

对于设备的属性、事件和命令，都支持手动添加。在个性化的物联网项目或产品开发中，这是经常会用到的功能。

点击“添加属性”，在添加属性对话框中，填写属性定义的配置信息，如下图：

手动添加事件和命令的方式也类似，您可以在相应的位置点击添加按钮。

添加标准定义

直接导入 ThingsCloud 内置的标准设备类型中的功能定义，包括属性、事件、命令。

通过添加标准功能，您可以快速复用常用的功能，例如：温度、湿度、PM2.5、二氧化碳、信号强度、电量、继电器、开关等。从而减少重复开发时间。

导入功能

导入功能支持从项目中的其它设备类型导入功能定义，也支持从产品库导入功能定义。

从其它设备类型导入

您可以选择已有的其它设备类型，导入其功能定义。如下图：

从产品库导入

您可以选择公共产品库中的产品，导入其功能定义。如下图：

属性定义

属性通常是指设备自身具备的某种状态，比如温度值、开关状态、配置参数。属性可以由设备上报到平台，也可以从平台下发到设备，或者在平台上作为云端私有属性。平台会自动保存属性的当前值和历史值。

一个设备可以拥有多个属性，每个属性都有唯一的属性标识符。例如：以下是设备端向平台发送的属性上报消息，其中包含 9 个属性，分别有不同的属性标识符。

{
    "temperature": 18.99,
    "humidity": 34.97,
    "pressure": 100390,
    "luminosity": 120,
    "pm10": 13,
    "pm2_5": 13,
    "relay1": false,
    "relay2": false,
    "version": "1.2.1"
}

属性名称

给属性起一个简洁、明确且具有描述性的名称，支持中文。属性名称不出现在属性消息中。

当存在属性定义时，在设备相关界面的属性当前值和历史数据图表中，属性名称会自动代替属性标识符，便于浏览。

属性标识符

属性标识符是指属性上报、属性下发或属性更新等消息 JSON 中的字段键名。

属性标识符中只能包含：英文大小写字母、数字、下划线、横线。请注意，属性标识符不支持中文。

属性类型

属性类型用来定义属性在物理设备和云平台之间的流动方向，使得设备和云平台的通信更加规范化。

通过对属性定义属性类型，云平台会自动检查属性消息是否符合定义，并过滤掉不符合定义的属性消息。

数据类型

通过对属性定义数据类型，云平台会自动验证属性的数据类型是否合法，对于不符合数据类型或不在设定范围内的情况，会自动忽略处理。

事件定义

事件一般是设备向云平台的通知或请求，可携带自定义的参数，云平台或应用端需要及时处理。比如故障通知、任务进度通知。

事件名称

用于给事件起一个便于区分的名称，支持中文，不出现在事件消息中。

事件标识符

事件标识符用在事件消息中，是 method 字段的值。

事件标识符中只能包含：英文大小写字母、数字、下划线、横线。

事件参数

事件消息中的 params 字段可携带事件参数，事件参数是一个 键值对集合，例如下边这个事件消息的参数：

{
    "method": "alarm",
    "params": {
        "code": "1001",
        "module": "pressure-sensor",
    }
}

在设备类型中创建事件时，如果定义了参数，云平台会严格验证事件消息中该参数的数据类型。

命令定义

命令是从平台向设备下发的通知或请求，可携带参数。比如下发 OTA升级、重启等命令。

设备端在收到云平台下发的命令消息后，根据命令标识符和命令参数，进行相应的处理。

设备端处理结束后，可以向云平台上报命令回应消息，用于发送处理结果。但命令回应消息不是必须的，设备端也可以用属性上报或事件上报，让云平台或应用端获得需要的信息即可。当然，对于有些下发的命令，设备端处理完成后，也可以不上报任何消息，这取决于您下发命令的需求和目的。

命令名称

用于给命令起一个便于区分的名称，支持中文，不出现在命令消息中。

命令标识符

事件标识符用在事件消息中，是 method 字段的值。

事件标识符中只能包含：英文大小写字母、数字、下划线、横线。

命令参数

命令消息中的 params 字段可携带命令参数，命令参数是一个 键值对集合，例如下边这个命令消息的参数：

{
    "method": "restart",
    "params": {
        "delay": 30
    }
}

在设备类型中创建命令时，如果定义了命令参数，云平台会严格验证命令消息中该参数的数据类型。

回应参数

命令回应消息不是必须的，如果发送它，也可以携带回应参数。

命令回应消息和命令消息的格式一模一样，区别在于只能从设备向云平台发送。例如：

{
    "method": "restart",
    "params": {
        "result": true
    }
}

在设备类型中创建命令时，如果定义了回应参数，云平台会严格验证命令回应消息中该参数的数据类型。