跳至主要內容

数据类型

约 1727 字大约 6 分钟

数据类型

在 ThingsCloud 设备类型的功能定义中,可以为设备属性设置以下数据类型:

基本类型:

  • Number(数值)
  • Text(文本)
  • Switch(开关量)
  • Enum(枚举型)
  • Object(键值对集合)
  • List(列表)

高级类型:

  • MapPoint(地理坐标)
  • MapCircle(地理圆形围栏)
  • MapPolygon(地理多边形围栏)
  • DailyTimer(每日定时器)

下面是各种数据类型的详细介绍。

Number(数值)

任意数值,不区分整数和浮点数,例如:

-12345
0
0.123
12.345
12345

附加选项:

  • 单位
  • 精度
  • 最小值
  • 最大值

提示

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

例如,设备上报数值型的属性:

{
    "temperature": 23.2,
    "humidity": 56.1
}

Number(数值)类型的属性,可以用来定义绝大多数用数字表示的设备参数,例如:

属性名称标识符单位示例值
温度temperature摄氏度/华氏度25.6°C, 78.1°F
湿度humidity%45.0%
压力pressure百帕斯卡/英寸汞柱1013 hPa, 29.92 inHg
电压voltage伏特220V, 5V
电流current安培/毫安10A, 0.5mA
功率power瓦/毫瓦100W, 1500mW
亮度brightness流明/坎德拉800 lm, 1000 cd
速度speed公里/小时/英里/小时60 km/h, 35 mph
距离distance米/千米10m, 5km
高度height米/英尺1.75m, 5000ft
重量weight公斤/磅70kg, 150lb
流量flow_rate升/分钟/立方米/小时100 L/min, 50 m³/h
频率frequency赫兹/吉赫兹50Hz, 2.4GHz
时间长度duration秒/小时3600秒, 1.5小时
时间timeUnix 时间戳(秒)1621027222
浓度concentration微克/立方米/毫克/立方米500 μg/m³, 0.08 mg/m³

Text(文本)

Plaintext 字符串,例如:

auto

例如,设备上报文本型的属性:

{
    "mode": "auto"
}

Switch(开关量)

Switch 开关量用于表示两种状态,例如 LED 的开/关,继电器的闭合/断开。

开关量使用布尔类型,如下:

true/false

例如,设备上报开关量型的属性:

{
    "switch1": false,
    "switch2": true
}

为了支持各种硬件设备上不同的开关量表达方式,开关量类型允许在设备和云平台之间的消息 JSON 中使用多种值类型,如下:

  • 布尔类型
true/false
  • 整数类型
1/0
  • 文本类型
ON/OFF

需要注意的是,选择不同的值类型,只影响设备端上报属性和接收下发属性中的开关量的值,并不影响这个属性值在平台上的存储和展示方式。在控制台或 API 中下发开关量属性时,应始终使用 true/false 布尔类型值。

附加选项:

  • ON 文字
  • OFF 文字

Enum(枚举型)

Enum 类型的属性,本身也是一种文本类型,区别在于必须在限定的枚举值中取值。

例如,设备上报枚举型的属性 mode

{
    "mode": "1"
}

Object(键值对集合)

{
    "key1": value1,
    "key2": value2,
    "key3": value3,
    ...
}

value 表示已支持的任意基本数据类型。

例如,设备上报键值对型的属性 data

{
    "data": {
        "temperature": 31.2,
        "switch": true,
        "mode": "1"
    }
}

List(列表)

[
    value1,
    value2,
    value3,
    ...
]

value 表示已支持的任意基本数据类型。

例如,设备上报列表型的属性 data

{
    "data": [
        1,
        3,
        5
    ]
}

MapPoint(地理坐标)

该数据类型用于表示地理坐标,可在内置的坐标转换和电子围栏等规则中使用。

该数据类型的结构如下:

{
    "lat": number,
    "lng": number
}

请注意:以上属性值都是数值格式,而不是字符串格式,不要加双引号。

例如,设备上报地理坐标型的属性 location

{
    "location": {
        "lat": 41.0203,
        "lng": 38.3183
    }
}

MapCircle(地理圆形围栏)

该数据类型用于表示地理圆形围栏,可在内置的电子围栏规则中使用。

该数据类型的结构如下:

{
    "centerPoint": {
        "lat": number,
        "lng": number
    },
    "radius": number
}
  • centerPoint:圆形区域的中心点位置。
  • radius:圆形的半径,单位是米。

例如,设备上报地理圆形围栏型属性 map_circle,如下:

{
    "map_circle": {
        "centerPoint": {
            "lat": 41.0203,
            "lng": 38.3189
        },
        "radius": 500
    }
}

MapPolygon(地理多边形围栏)

该数据类型用于表示地理多边形围栏,可在内置的电子围栏规则中使用。

该数据类型的结构如下:

[
    {
        "lat": number,
        "lng": number
    },
    {
        "lat": number,
        "lng": number
    },
    {
        "lat": number,
        "lng": number
    },
    ...
]

例如:在应用端通过 API 更新设备的地理多边形围栏属性 map_polygon,如下:

{
    "map_polygon": [
        {
            "lat": 38.462,
            "lng": 140.391
        },
        {
            "lat": 39.462,
            "lng": 140.391
        },
        {
            "lat": 39.462,
            "lng": 141.391
        },
        {
            "lat": 38.462,
            "lng": 141.391
        }
    ]
}

DailyTimer(每日定时器)

该数据类型用于表示每日定时设置,数据类型的结构如下:

{
    "enable": boolean,
    "time": string,
    "repeat": string
}
  • enable:表示定时器是否启用,true 表示启用,false 表示禁用。
  • time:表示定时器的触发时间,格式为 HH:mm:ss
  • repeat:表示定时器的重复设置,格式为 0123456,每个数字代表一周中的一天,0 表示周日,1 表示周一,以此类推。

例如,平台下发到设备的定时器属性 switch_open_timer,表示定时器启用,时间为周一到周五每天的 12:00:00 ,如下:

{
    "switch_open_timer": {
        "enable": true,
        "time": "12:00:00",
        "repeat": "12345"
    }
}

每日定时器类型的属性,还可以用在任务的定时设置中,使得任务可以对不同设备执行不同的定时设置。您还可以在 ThingsX App 设备面板中添加定时器属性组件,让用户快捷的管理多个定时器,对不同设备设置定时器的状态、时间和重复参数。详细请浏览用户如何在 ThingsX 设置定时任务?open in new window

DailyTimerRange(每日定时区间)

该数据类型用于表示每日定时区间设置,数据类型的结构如下:

{
    "enable": boolean,
    "start_time": string,
    "end_time": string,
    "repeat": string
}
  • enable:表示定时区间是否启用,true 表示启用,false 表示禁用。
  • start_time:表示定时区间的开始时间,格式为 HH:mm:ss
  • end_time:表示定时区间的结束时间,格式为 HH:mm:ss
  • repeat:表示定时区间的重复设置,格式为 0123456,每个数字代表一周中的一天,0 表示周日,1 表示周一,以此类推。

例如,平台更新某设备开关的定时区间属性 switch_timer_range,用来表示定时区间启用,周一到周五每天的 12:00:00 开启开关,18:00:00 关闭开关,如下:

{
    "switch_open_timer": {
        "enable": true,
        "start_time": "12:00:00",
        "end_time": "18:00:00",
        "repeat": "12345"
    }
}

每日定时区间类型的属性,同样可以和[任务]结合使用,一个定时区间属性可以通过 start_timeend_time 分别关联到两个任务,比如一个任务用来开启开关,一个任务用来关闭开关。