功能定义¶

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

对于熟悉面向对象编程的开发者而言，功能定义更像是给设备定义了一个类，其中约定了有哪些成员变量，以及变量的数据类型，另外还约定了一些特殊的方法。

属性¶

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

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

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

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

1) 属性名称¶

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

在一些设备面板界面的属性当前值和时序图表中，属性名称会自动代替属性标识符，便于浏览。

2) 属性标识符¶

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

3) 属性类型¶

设备上报¶

这类属性只能由设备上报到云平台。支持的方式包括：

属性上报
规则引擎中的属性上报预处理
规则引擎中的自定义数据上报

设备上报属性的例子：

// 温度属性上报
{ "temperature": 28.4 }

云端下发¶

这类只能由云平台下发到设备的属性。

云端下发属性的例子：

// 电源开关控制
{ "power": false }

双向互发¶

这类属性既可以由设备上报，也可以由平台下发到设备，也就是可以同时被设备和平台改写。

双向互发属性的例子：

// 灯泡开关状态
{ "light": false }

云端私有¶

这类属性只能通过平台更新，不会下发到设备，也无法由设备上报到平台。

云端私有属性的例子：

// 供云端应用使用的温度阈值
{ "threshold": [0, 50] }

4) 数据类型¶

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

平台支持以下数据类型：

Number(数值)¶

任意数值，不区分整数和浮点数，例如：-12345、0、12.345、12345

附加选项：

单位
精度
最小值
最大值

当设置数值属性的最大值或最小值后，如果上报或下发的数值属性不符合该条件，平台会拒绝处理，您可以在设备调试中查看详细错误提示，便于修改合理的限制条件。

Text(文本)¶

Plaintext 字符串，例如：auto

例如，设备上报文本型的属性格式：

{ "mode": "auto" }

Swich(开关量)¶

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] }

事件¶

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

1)事件名称¶

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

2)事件标识符¶

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

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

3)事件参数¶

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

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

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

命令¶

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

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

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

1)命令名称¶

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

2)命令标识符¶

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

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

3)命令参数¶

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

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

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

4)回应参数¶

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

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

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

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

5)命令实例¶

本系统支持对设备类型或设备创建命令实例。

命令实例中不仅明确了命令标识符、命令参数，还明确了各命令参数的值。

创建命令实例可以帮助用户一键快速下发具有复杂参数组合的命令。

对某个设备类型创建命令实例后，该设备类型下的所有设备都可方便的使用该命令实例。