功能定义
功能定义
功能定义是通过建立一套模型，来描述不同设备的能力，包括设备的属性、事件和命令，从而为设备接入和应用开发建立一套成熟的规范。功能定义对设备类型中的所有设备都有效。
提示
功能定义并不是必须的。没有功能定义，并不影响设备通过 MQTT 协议上报属性、事件，以及接收命令消息。
对于熟悉面向对象编程的开发者而言，功能定义更像是给设备定义了一个类，其中约定了有哪些成员变量，以及变量的数据类型，另外还约定了一些特殊的方法。
属性
属性一般是设备自身具备的某种状态，比如温度值、开关状态、配置参数。
属性可以由设备上报到云平台，或从云平台下发到设备。云平台会自动保存属性的当前值和历史值。
设备可拥有多个属性，例如：
{
"temperature": 18.99,
"humidity": 34.97,
"pressure": 100390,
"luminosity": 120,
"pm10": 13,
"pm2_5": 13,
"relay1": false,
"relay2": false,
"version": "1.2.1"
}
属性名称
用于给属性起一个便于区分的名称，支持中文，不出现在属性消息中。
在一些设备面板界面的属性当前值和时序图表中，属性名称会自动代替属性标识符，便于浏览。
属性标识符
属性标识符中只能包含：英文大小写字母、数字、下划线、横线。
属性类型
设备上报
这类属性只能由设备上报到云平台。支持的方式包括：
- 属性上报
- 规则引擎中的属性上报预处理
- 规则引擎中的自定义数据上报
设备上报属性的常见例子：
- 温度属性上报
{
"temperature": 28.4
}
- 固件当前版本上报
{
"version": "1.3.2"
}
- GPS 坐标上报
{
"location": {
"lat": 38.8721,
"lng": 139.1647
}
}
云端下发
这类只能由云平台下发到设备的属性。
云端下发属性的常见例子：
- 电源开关控制
{
"power": false
}
- 模式切换
{
"mode": "semi-auto"
}
设备云端共享
这类属性既可以由设备上报，也可以由云平台下发到设备，也就是可以同时被设备和云平台改写。
设备云端共享属性的常见例子：
- 灯泡开关状态
{
"light": false
}
云端私有
这类属性只能通过云平台更新，不会下发到设备，也无法由设备上报到云平台。
云端私有属性的常见例子：
- 供云端应用使用的温度阈值
{
"threshold": [0, 50]
}
数据类型
通过对属性设置数据类型，云平台会自动验证属性的数据类型是否合法，对于不符合数据类型或不在设定范围内的情况，会自动忽略处理。
ThingsCloud 支持以下数据类型：
Number（数值）
任意数值，不区分整数和浮点数，例如：
-12345
0
0.123
12.345
12345
附加选项：
- 单位
- 精度
- 最小值
- 最大值
提示
当设置数值属性的最大值或最小值后，如果上报或下发的数值属性不符合该条件，ThingsCloud 会拒绝处理，您可以在设备调试中查看详细错误提示，便于修改合理的限制条件。
例如，设备上报数值型的属性格式：
{
"temperature": 23.2,
"humidity": 56.1
}
Text（文本）
Plaintext 字符串，例如：
auto
例如，设备上报文本型的属性格式：
{
"mode": "auto"
}
Switch（开关量）
Switch 开关量用于表示两种状态，例如 LED 的开/关，继电器的闭合/断开。
开关量使用布尔类型，如下：
true/false
为了支持各种硬件设备的开关量表达方式，开关量允许在设备和云平台之间的消息 JSON 中使用多种开关值，如下：
- 布尔类型
true/false
- 整数类型
1/0
- 文本类型
ON/OFF
附加选项：
- ON 文字
- OFF 文字
例如，设备上报开关量型的属性格式：
{
"switch1": false,
"switch2": true
}
Enum（枚举型）
Enum 类型的属性，本身也是一种文本类型，区别在于必须在限定的枚举值中取值。
例如，设备上报枚举型的属性格式：
{
"mode": "1"
}
Object（键值对集合）
{
"key1": value1,
"key2": value2,
"key3": value3,
...
}
value 表示已支持的任意基本数据类型。
例如，设备上报键值对型的属性格式：
{
"data": {
"temperature": 31.2,
"switch": true,
"mode": "1"
}
}
List（列表）
[
value1,
value2,
value3,
...
]
value 表示已支持的任意基本数据类型。
例如，设备上报列表型的属性格式：
{
"data": [
1,
3,
5
]
}
MapPoint（地理坐标）
该数据类型用于表示地理坐标，可在内置的坐标转换和电子围栏等规则中使用。
该数据类型的结构如下：
{
"lat": number,
"lng": number
}
例如，设备上报地理坐标型的属性格式：
{
"location": {
"lat": 41.0203,
"lng": 38.3183
}
}
MapCircle（地理圆形围栏）
该数据类型用于表示地理圆形围栏，可在内置的电子围栏规则中使用。
该数据类型的结构如下：
{
"centerPoint": {
"lat": number,
"lng": number
},
"radius": number
}
centerPoint：圆形区域的中心点位置。radius：圆形的半径，单位是米。
例如，设备上报地理圆形围栏型的属性格式：
{
"map_circle": {
"centerPoint": {
"lat": 41.0203,
"lng": 38.3189
},
"radius": 500
}
}
MapPolygon（地理多边形围栏）
该数据类型用于表示地理多边形围栏，可在内置的电子围栏规则中使用。
该数据类型的结构如下：
[
{
"lat": number,
"lng": number
},
{
"lat": number,
"lng": number
},
{
"lat": number,
"lng": number
},
...
]
事件
事件一般是设备向云平台的通知或请求，可携带自定义的参数，云平台或应用端需要及时处理。比如故障通知、任务进度通知。
事件名称
用于给事件起一个便于区分的名称，支持中文，不出现在事件消息中。
事件标识符
事件标识符用在事件消息中，是 method 字段的值。
事件标识符中只能包含：英文大小写字母、数字、下划线、横线。
事件参数
事件消息中的 params 字段可携带事件参数，事件参数是一个 键值对集合，例如下边这个事件消息的参数：
{
"method": "alarm",
"params": {
"code": "1001",
"module": "pressure-sensor",
}
}
在设备类型中创建事件时，如果定义了参数，云平台会严格验证事件消息中该参数的数据类型。
命令
命令是从平台向设备下发的通知或请求，可携带参数。比如下发 OTA升级、重启等命令。
设备端在收到云平台下发的命令消息后，根据命令标识符和命令参数，进行相应的处理。
设备端处理结束后，可以向云平台上报命令回应消息，用于发送处理结果。但命令回应消息不是必须的，设备端也可以用属性上报或事件上报，让云平台或应用端获得需要的信息即可。当然，对于有些下发的命令，设备端处理完成后，也可以不上报任何消息，这取决于您下发命令的需求和目的。
命令名称
用于给命令起一个便于区分的名称，支持中文，不出现在命令消息中。
命令标识符
事件标识符用在事件消息中，是 method 字段的值。
事件标识符中只能包含：英文大小写字母、数字、下划线、横线。
命令参数
命令消息中的 params 字段可携带命令参数，命令参数是一个 键值对集合，例如下边这个命令消息的参数：
{
"method": "restart",
"params": {
"delay": 30
}
}
在设备类型中创建命令时，如果定义了命令参数，云平台会严格验证命令消息中该参数的数据类型。
回应参数
命令回应消息不是必须的，如果发送它，也可以携带回应参数。
命令回应消息和命令消息的格式一模一样，区别在于只能从设备向云平台发送。例如：
{
"method": "restart",
"params": {
"result": true
}
}
在设备类型中创建命令时，如果定义了回应参数，云平台会严格验证命令回应消息中该参数的数据类型。
添加标准功能
ThingsCloud 内置的标准设备类型，包含了各类功能定义，通过添加标准功能，您可以快速复用已有的功能，从而减少重复开发时间。