功能定义


功能定义

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

提示

功能定义并不是必须的。没有功能定义,并不影响设备通过 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 内置的标准设备类型,包含了各类功能定义,通过添加标准功能,您可以快速复用已有的功能,从而减少重复开发时间。