您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

IoT 即插即用约定IoT Plug and Play conventions

IoT 即插即用设备在与 IoT 中心交换消息时应遵循一组约定。IoT Plug and Play devices should follow a set of conventions when they exchange messages with an IoT hub. IoT 即插即用设备使用 MQTT 协议与 IoT 中心通信。IoT Plug and Play devices use the MQTT protocol to communicate with IoT Hub.

设备可以包含 模块,也可以在 IoT Edge 运行时承载的 IoT Edge 模块 中实现。Devices can include modules, or be implemented in an IoT Edge module hosted by the IoT Edge runtime.

使用 数字孪生定义语言 v2 (DTDL) 模型 来描述 IoT 即插即用设备实现的遥测、属性和命令。You describe the telemetry, properties, and commands that an IoT Plug and Play device implements with a Digital Twins Definition Language v2 (DTDL) model. 本文中引用的模型分为两种类型:There are two types of model referred to in this article:

  • 无组件 -没有组件的模型。No component - A model with no components. 该模型在主接口的内容部分中将遥测、属性和命令声明为顶级属性。The model declares telemetry, properties, and commands as top-level properties in the contents section of the main interface. 在 Azure IoT 资源管理器工具中,此模型显示为单个 默认组件In the Azure IoT explorer tool, this model appears as a single default component.
  • 多个组件 -由两个或多个接口组成的模型。Multiple components - A model composed of two or more interfaces. 主接口,它显示为 默认组件,具有遥测、属性和命令。A main interface, which appears as the default component, with telemetry, properties, and commands. 将一个或多个接口声明为包含附加遥测、属性和命令的组件。One or more interfaces declared as components with additional telemetry, properties, and commands.

有关详细信息,请参阅 IoT 即插即用模型中的组件For more information, see IoT Plug and Play components in models.

标识模型Identify the model

若要公布它实现的模型,IoT 即插即用设备或模块通过添加到字段,在 MQTT 连接数据包中包含模型 ID model-id USERNAMETo announce the model it implements, an IoT Plug and Play device or module includes the model ID in the MQTT connection packet by adding model-id to the USERNAME field.

若要标识设备或模块实现的模型,服务可以从以下各内容获取模型 ID:To identify the model that a device or module implements, a service can get the model ID from:

  • 设备克隆 modelId 字段。The device twin modelId field.
  • 数字双子 $metadata.$model 字段。The digital twin $metadata.$model field.
  • 数字克隆更改通知。A digital twin change notification.

遥测Telemetry

从无组件设备发送的遥测无需任何额外的元数据。Telemetry sent from a no component device doesn't require any extra metadata. 系统添加 dt-dataschema 属性。The system adds the dt-dataschema property.

从多个组件设备发送的遥测必须 $.sub 作为消息属性添加。Telemetry sent from a multiple component device must add $.sub as a message property. 系统添加 dt-subjectdt-dataschema 属性。The system adds the dt-subject and dt-dataschema properties.

只读属性Read-only properties

示例无组件只读属性Sample no component read-only property

设备或模块可以发送遵循 DTDL v2 规则的任何有效 JSON。A device or module can send any valid JSON that follows the DTDL v2 rules.

DTDL:DTDL:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:example: Thermostat;1",
  "@type": "Interface",
  "contents": [
    {
      "@type": "Property",
      "name": "temperature",
      "schema": "double"
    }
  ]
}

报告的示例属性负载:Sample reported property payload:

"reported" :
{
  "temperature" : 21.3
}

示例多个组件只读属性Sample multiple components read-only property

设备或模块必须添加 {"__t": "c"} 标记,以指示元素引用组件。The device or module must add the {"__t": "c"} marker to indicate that the element refers to a component.

引用组件的 DTDL:DTDL that references a component:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:TemperatureController;1",
  "@type": "Interface",
  "displayName": "Temperature Controller",
  "contents": [
    {
      "@type" : "Component",
      "schema": "dtmi:com:example:Thermostat;1",
      "name": "thermostat1"
    }
  ]
}

定义组件的 DTDL:DTDL that defines the component:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:Thermostat;1",
  "@type": "Interface",
  "contents": [
    {
      "@type": "Property",
      "name": "temperature",
      "schema": "double"
    }
  ]
}

报告的示例属性负载:Sample reported property payload:

"reported": {
  "thermostat1": {
    "__t": "c",
    "temperature": 21.3
  }
}

可写属性Writable properties

设备或模块应通过发送报告的属性来确认它已接收到属性。The device or module should confirm that it received the property by sending a reported property. 报告的属性应包括:The reported property should include:

  • value -属性的实际值 (通常是接收到的值,但设备可能决定报告不同的值) 。value - the actual value of the property (typically the received value, but the device may decide to report a different value).
  • ac -使用 HTTP 状态代码的确认代码。ac - an acknowledgment code that uses an HTTP status code.
  • av -引用所 $version 需属性的的确认版本。av - an acknowledgment version that refers to the $version of the desired property. 可以在所需的属性 JSON 有效负载中找到此值。You can find this value in the desired property JSON payload.
  • ad -可选确认说明。ad - an optional acknowledgment description.

设备启动时,应该请求设备克隆,并检查是否有可写的属性更新。When a device starts up, it should request the device twin, and check for any writable property updates. 如果在设备处于脱机状态时增加了可写属性的版本,则设备应发送报告的属性响应,以确认收到更新。If the version of a writable property increased while the device was offline, the device should send a reported property response to confirm that it received the update.

当设备首次启动时,如果它没有从中心接收到初始所需属性,则可以为报告的属性发送初始值。When a device starts up for the first time, it can send an initial value for a reported property if it doesn't receive an initial desired property from the hub. 在这种情况下,设备应设置 av1In this case, the device should set av to 1. 例如:For example:

"reported": {
  "targetTemperature": {
    "value": 20.0,
    "ac": 200,
    "av": 1,
    "ad": "initialize"
  }
}

设备可以使用报告的属性向中心提供其他信息。A device can use the reported property to provide other information to the hub. 例如,设备可能会使用一系列正在进行的消息(例如)进行响应:For example, the device could respond with a series of in-progress messages such as:

"reported": {
  "targetTemperature": {
    "value": 35.0,
    "ac": 202,
    "av": 3,
    "ad": "In-progress - reporting current temperature"
  }
}

当设备达到目标温度时,它将发送以下消息:When the device reaches the target temperature it sends the following message:

"reported": {
  "targetTemperature": {
    "value": 20.0,
    "ac": 200,
    "av": 3,
    "ad": "Reached target temperature"
  }
}

设备可能会报告错误,如:A device could report an error such as:

"reported": {
  "targetTemperature": {
    "value": 120.0,
    "ac": 500,
    "av": 3,
    "ad": "Target temperature out of range. Valid range is 10 to 99."
  }
}

无组件可写属性示例Sample no component writable property

当设备在单个有效负载中接收多个报告属性时,它可以跨多个有效负载发送报告的属性响应。When a device receives multiple reported properties in a single payload, it can send the reported property responses across multiple payloads.

设备或模块可以发送遵循 DTDL v2 规则的任何有效 JSON:A device or module can send any valid JSON that follows the DTDL v2 rules:

DTDL:DTDL:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:example: Thermostat;1",
  "@type": "Interface",
  "contents": [
    {
      "@type": "Property",
      "name": "targetTemperature",
      "schema": "double",
      "writable": true
    }
  ]
}

所需的属性负载示例:Sample desired property payload:

"desired" :
{
  "targetTemperature" : 21.3,
  "targetHumidity" : 80
},
"$version" : 3

报告的示例属性优先负载:Sample reported property first payload:

"reported": {
  "targetTemperature": {
    "value": 21.3,
    "ac": 200,
    "av": 3,
    "ad": "complete"
  }
}

报告的示例属性第二个负载:Sample reported property second payload:

"reported": {
  "targetHumidity": {
    "value": 80,
    "ac": 200,
    "av": 3,
    "ad": "complete"
  }
}

示例多组件可写属性Sample multiple components writable property

设备或模块必须添加 {"__t": "c"} 标记,以指示元素引用组件。The device or module must add the {"__t": "c"} marker to indicate that the element refers to a component.

仅为在组件中定义的属性更新发送标记。The marker is sent only for updates to properties defined in a component. 对默认组件中定义的属性的更新不包括标记,请参阅 示例无组件可写属性Updates to properties defined in the default component don't include the marker, see Sample no component writable property

当设备在单个有效负载中接收多个报告属性时,它可以跨多个有效负载发送报告的属性响应。When a device receives multiple reported properties in a single payload, it can send the reported property responses across multiple payloads.

设备或模块应通过发送报告的属性来确认它已接收到属性:The device or module should confirm that it received the properties by sending reported properties:

引用组件的 DTDL:DTDL that references a component:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:TemperatureController;1",
  "@type": "Interface",
  "displayName": "Temperature Controller",
  "contents": [
    {
      "@type" : "Component",
      "schema": "dtmi:com:example:Thermostat;1",
      "name": "thermostat1"
    }
  ]
}

定义组件的 DTDL:DTDL that defines the component:

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:Thermostat;1",
  "@type": "Interface",
  "contents": [
    {
      "@type": "Property",
      "name": "targetTemperature",
      "schema": "double",
      "writable": true
    }
  ]
}

所需的属性负载示例:Sample desired property payload:

"desired": {
  "thermostat1": {
    "__t": "c",
    "targetTemperature": 21.3,
    "targetHumidity": 80
  }
},
"$version" : 3

报告的示例属性优先负载:Sample reported property first payload:

"reported": {
  "thermostat1": {
    "__t": "c",
    "targetTemperature": {
      "value": 23,
      "ac": 200,
      "av": 3,
      "ad": "complete"
    }
  }
}

报告的示例属性第二个负载:Sample reported property second payload:

"reported": {
  "thermostat1": {
    "__t": "c",
    "targetHumidity": {
      "value": 80,
      "ac": 200,
      "av": 3,
      "ad": "complete"
    }
  }
}

命令Commands

没有组件接口使用不带前缀的命令名。No component interfaces use the command name without a prefix.

在设备或模块上,多个组件接口使用命令名称,格式如下: componentName*commandNameOn a device or module, multiple component interfaces use command names with the following format: componentName*commandName.

后续步骤Next steps

现在,你已了解 IoT 即插即用约定,下面是一些其他资源:Now that you've learned about IoT Plug and Play conventions, here are some additional resources: