事物描述

事物描述

概述

事物描述 (Thing Description) 提供了一种用 JSON 编码的机器可读的格式来描述连接到万维网的物理设备。

它用来描述指定的事物及其交互接口，主要包括了属性 (Properties)，操作 (Actions) 和事件 (Events) 等.

事物描述模型

一般来说事物能力描述模型主要由以下三个模块组成:

  • 关于 Properties, Actions 和 Events 的核心事物描述;
  • 数据类型描述 (JSON 数据类型子集);
  • 以及安全配置方案 (用来定义需要的安全机制及其配置信息)

Thing - 事物

下面是一个简单的事物描述示例:

{
  "name":"On/Off Switch",
  "description": "A web connected switch",
  "properties": {
    "on": {
      "title": "On/Off",
      "type": "boolean",
      "description": "Whether the lamp is turned on",
      "links": [{"href": "/things/lamp/properties/on"}]
    }
  }
}

基本成员

下面是事物的基本属性:

NAME TYPE DESCRIPTION
@context string | array 模式存储库 URI 地址
@type string | array 模式类型
id string 这个事物的唯一标识
title string 方便人读的事物的名称
description string 方便人读的事物描述信息
properties Propertymap 属性类交互接口
actions Actionmap 操作类交互接口
events Eventmap 事件类交互接口
support string 事物的维护者的联系信息, 可以是网址, 电话等
version object 版本信息
created string 这个事物描述的创建时间
modified string 这个事物描述的最后修改时间
base URI string 这个描述相关的 URL 的基本路径
services Thing array 这个事物的内置服务列表

@context 成员

@context 成员是一个可选的注释，可用于提供模式存储库 (schema repository ) 的 URI，该存储库为常见的类型的设备及能力定义了标准的模式。然后可以在描述的其他地方使用 @type 注释引用这些类型。

例如:

"@context": "https://iot.domain-name.org/schemas"

@type 成员

@type 成员是一个可选注释，可用于提供模式 (schema) 的名称, 表示设备支持 @context 成员中引用的模式存储库中相应类型的模式定义的功能。@type 成员的值是一个字符串或字符串数组，这些字符串对应于模式存储库中的模式名称。

@type 注释可以告诉应用程序，它可以期望设备符合该类型的模式的约束。这可能包括设备可能支持的某些类型的属性、操作和事件。应用程序可以利用这些信息来帮助自动化或为已知的标准设备提供相应的用户界面。

例如:

"@type": ["Light", "OnOffSwitch"]

title 成员

title 成员是用于描述设备的对人类友好的字符串。这可以由设备创建者设置为任何值，并可能包括品牌名称或型号。

description 成员

description 成员是一个人类友好的字符串，它用于描述设备及其功能。这可以由设备创建者设置为任何值。

version 成员

version 成员用来描述这个事物相关的版本

  • instance 实例
  • firmware 固件
  • hardware 硬件
  • software 软件

properties 成员

properties 成员是设备属性描述对象的集合。

actions 成员

actions 成员是操作对象的集合，它用于描述可以在设备上执行的功能。当仅设置属性不足以影响所需的状态更改时，将使用操作。这可以用来描述一个函数，它需要一段时间来完成，操作多个属性，或者根据提供的参数或当前状态得到不同的结果。例如，“fade” 操作具有指定的“duration” 参数，而 “sequence” 操作将触发一系列灯光的闪烁，或者对开关进行 “toggle” 操作等。

events 成员

events 成员是事件对象的集合，它定义了设备可能发出的事件类型。当订阅属性状态的更改还不够时，可以使用事件。这可以用于监视属性更改之外的其他事件内容或多个属性的更改。例如，当设备即将重新启动时发出的事件。

InteractionPattern - 交互接口

InteractionPattern 包含了 Properties, Actions 和 Events 等所有交互接口的基本属性的定义:

NAME TYPE DESCRIPTION
@type string 基本属性类型名称
title string 方便人读的名称
description string 方便人读的描述信息
forms array of Form 底层协议绑定定义

Property - 属性

InteractionPattern 的子类:

{
    "on": {
        "title": "On/Off",
        "type": "boolean",
        "forms": [...]
    }
}

属性对象描述事物的属性，并由属性 id 索引。

属性同样也是 DataSchema 的实例，可能包含 DataSchema 的属性

另外属性描述还可以包括 (其他属性请参考 DataSchema):

NAME TYPE DEFAULT DESCRIPTION
@type string - 基本属性类型名称
title string - 方便人读的名称
description string - 方便人读的描述信息
observable boolean false 指出这个属性是否是可观察的
more... DataSchema - 其他属性请参考 DataSchema

Action - 方法

InteractionPattern 的子类:

{
    "title": "Fade in/out",
    "description": "Smooth fade in and out animation.",
    "input": {
        "type": "object",
        "properties": {
            "from": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
            },
            "to": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
            },
            "duration": {"type": "number"}
        },
        "required": ["to","duration"]
    },
    "output": {"type": "string"}
}

Action 对象用于描述可以在设备上执行的函数。定义可包括:

NAME TYPE DESCRIPTION
@type string 基本操作类型名称
title string 方便人读的名称
description string 方便人读的描述信息
input DataSchema 输入参数
output DataSchema 输出参数
safe boolean 指出是否安全，即不会改变内部的状态
idempotent boolean 指出是否幂等，即相同的操作总是返回相同的结果

Event - 事件

InteractionPattern 的子类

{
    "data": { 
        "type": "string"
    }
}

Event 对象用于描述设备可能发出的一种事件。这可能包括:

NAME TYPE DESCRIPTION
@type string 基本事件类型名称
title string 方便人读的名称
description string 方便人读的描述信息
data DataSchema 这个事件对象的数据
subscription DataSchema 定义用于订阅操作的数据
cancellation DataSchema 定义用于取消订阅的数据

Versioning - 版本信息

NAME TYPE DESCRIPTION
instance string 所属实例的版本
firmware string 固件
hardware string 硬件
software string 软件

数据类型定义

事物描述定义了基本的数据类型，用于和不同格式的数据进行转换，如 JSON, CBOR 等。

下面是事物描述用到的基本数据类型, 由下可见基本和 JSON 的数据类型一致.

NAME NOTE
array 数组, 可以包含多个非空的任意值
boolean 布尔型
integer 整数型
null 空值
number 数值, 主要指浮点数
object 对象, 可以包含多个非空的有名称的任意值
string 字符串

DataSchema - 基本类型

下面是 DataSchema 基本数据类型的基本属性

NAME TYPE APPLY NOTE
@type string | array all 语义类型
title string all 显示名称
description string all 简要描述
type string all 数据类型
const any all 提供一个常量值
decimals integer number 小数位
unit string - 单位信息
oneOf array of DataSchema - 可以属于的数据类型
enum array - 枚举值 (如果这个数据是枚举类型)
readOnly boolean all 是否是只读的
writeOnly boolean all 是否是只写的
format string - 数据格式，如 date, email 等
items DataSchema | array array 表示这个数组包含的项目的类型
minItems integer array 数组最少包含的数量
maxItems integer array 数组最多包含的数量
minimum integer | number number,integer 最小值
maximum integer | number number,integer 最大值
properties map of DataSchema object 定义这个对象包含的属性
required array of string object 表示这个对象必须包含的属性的名称列表

DataSchema 的子类型有: ArraySchema, BooleanSchema, NumberSchema, ObjectSchema, StringSchema.

下面是具体的 Data Schema 类型定义.

ArraySchema - 数组

  • type = "array"
  • items {DataSchema} 表示这个数组包含的项目的类型
  • minItems {unsigned integer} 最小包含的数量
  • maxItems {unsigned integer} 最大包含的数量

BooleanSchema - 布尔型

  • type = "boolean"

IntegerSchema - 整数

  • type = "integer"
  • minimum {integer} 最小值
  • maximum {integer} 最大值
  • unit {string} 单位

NumberSchema - 浮点数

  • type = "number"
  • minimum {number} 最小值
  • maximum {number} 最大值
  • decimals {unsigned integer} 小数位
  • unit {string} 单位

ObjectSchema - 对象类型

用来表示更复杂的类型

  • type = "object"
  • properties {map of DataSchema} 定义这个对象包含的属性
  • required {array of string} 表示这个对象必须包含的属性的名称列表

StringSchema - 字符串

默认为 UTF-8 编码格式

  • type = "string"

示例

事物描述 thing

下面是一个基本的事物描述的示例:

{
    "id": "urn:dev:wot:com:example:servient:myThing",
    "name": "MyThing",
    "description": "Additional (human) readable information of the Thing.",
    "support": "https://servient.example.com/contact",
    "base": "https://servient.example.com/",
    "properties": {...},
    "actions": {...},
    "events": {...}
}

下面是一个更复杂一点的示例:

{
    "@context": "http://www.w3.org/ns/td",
    "@type": "Thing",
    "id": "urn:dev:wot:cn:domain-name:servient:gateway",
    "name": "Gateway",
    "description": "WoT Gateway.",
    "support": "https://{domain.name}/support",
    "base": "https://{domain.name}/",
    "properties": {...},
    "actions": {...},
    "events": {...}
}

属性 properties

用键值对来表示属性, 其中键名即属性名.

{
    "properties": {
        "on": {
            "title": "On/Off",
            "type": "boolean",
            "forms": [...]
        },
        "status": {
            "type": "object",
            "properties": {
                "brightness": {
                    "type": "number",
                    "minimum": 0.0,
                    "maximum": 100.0
                 },
                 "rgb": {
                    "type": "array",
                    "items" : {
                        "type" : "number",
                        "minimum": 0,
                        "maximum": 255
                    },
                    "minItems": 3,
                    "maxItems": 3
                }
            },
            "required": ["brightness", "rgb"]
        }
    }
}
  • title {String} 显示名称

操作 actions

用键值对来表示操作, 其中键名即操作名.

{
    "actions": {
        "fade": {
            "title": "Fade in/out",
            "description": "Smooth fade in and out animation.",
            "input": {
                "type": "object",
                "properties": {
                    "from": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                    },
                    "to": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                    },
                    "duration": {"type": "number"}
                },
                "required": ["to","duration"]
            },
            "output": {"type": "string"}
        }
    }
}
  • label {String} 显示名称
  • description {String} 简要描述
  • input {Data} 输入参数
  • output {Data} 输出参数

事件 events

用键值对来表示事件, 其中键名即事件名.

{
    "events": {
        "overheated": {
            "data": { 
                "type": "string"
            }
        }
    }
}

事件名为 overheated, 事件数据类型为 object, 包含数值属性 temperature

image-modal