# 功能定义

功能定义是通过建立一套模型，来描述不同设备的能力，包括设备的属性、事件和命令，从而为设备接入和应用开发建立一套成熟的规范。功能定义对设备类型中的所有设备都有效。

# 属性

属性一般是设备自身具备的某种状态，比如温度值、开关状态、配置参数。

属性可以由设备上报到云平台，或从云平台下发到设备。云平台会自动保存属性的当前值和历史值。

设备可拥有多个属性，例如：

{
    "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 支持的数据类型，请阅读 数据类型。

# 事件

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

# 事件名称

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

# 事件标识符

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

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

# 事件参数

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

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

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

# 命令

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

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

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

# 命令名称

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

# 命令标识符

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

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

# 命令参数

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

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

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

# 回应参数

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

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

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

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

# 添加标准功能

ThingsCloud 内置的标准设备类型，包含了各类功能定义，通过添加标准功能，您可以快速复用已有的功能，从而减少重复开发时间。