Skip to main content

理解Azure IoT Hub的孪生设备(Device Twin)和孪生模块(Module Twin)

分类:  Azure物联网 ◆ 标签:  #Azure #IoT Hub # ◆ 发布于: 2023-06-12 21:31:15

孪生设备(Device Twin)是用于存储链接到Azure IoT Hub的设备状态信息，包括元数据，配置, 状态等信息的Json文档，Azure IoT Hub为每个链接上来的设备都存储一份这样的文档。

孪生设备主要用于：

  • 保存设备特定的元数据，例如设备部署的位置等等。
  • 上报设备当前的状态以及配置，例如使用什么网络链接，设备的资源状态等等。
  • 同步长时间运行的工作流的状态，例如更新或者升级的状态。
  • 查询设备元数据，配置或者状态。

总之它是用于存储设备相关的信息：

  • 设备应用和后端应用可以使用它来同步设备的状态和配置。
  • 后端应用可以查询长时间运行操作的状态。

孪生设备的生命周期默认是和设备标识是一致的，设备标识创建孪生设备被创建，设备标识被删除，孪生设备被删除。

孪生设备(Device Twin)的文档结构

孪生设备(Device Twin)的文档主要包括如下的基本信息：

  • Tags: 可用于后端应用读写的区域，但是对于设备时不可见的。
  • 预期属性(Desired Properties): 一般和上报属性(reported Properties)一起使用，用于同步设备的配置和状态，后端应用可以设置预期属性，设备app可以读取他们，并通过上报属性上报。
  • 上报属性(reported properties): 和预期属性(Desired Properties)联合使用。用于同步设备的配置和状态，设备上报该种类属性。后端应用可以查询它。
  • 设备标识属性(Device Identity Properties): 孪生设备文档包含的只读属性(这些值从设备标识库中读出)

详细如下图：


我们来快速的看一个孪生设备文档的例子：

{
    "deviceId": "devA",
    "etag": "AAAAAAAAAAc=", 
    "status": "enabled",
    "statusReason": "provisioned",
    "statusUpdateTime": "0001-01-01T00:00:00",
    "connectionState": "connected",
    "lastActivityTime": "2015-02-30T16:24:48.789Z",
    "cloudToDeviceMessageCount": 0, 
    "authenticationType": "sas",
    "x509Thumbprint": {     
        "primaryThumbprint": null, 
        "secondaryThumbprint": null 
    }, 
    "version": 2, 
    "tags": {
        "$etag": "123",
        "deploymentLocation": {
            "building": "43",
            "floor": "1"
        }
    },
    "properties": {
        "desired": {
            "telemetryConfig": {
                "sendFrequency": "5m"
            },
            "$metadata" : {...},
            "$version": 1
        },
        "reported": {
            "telemetryConfig": {
                "sendFrequency": "5m",
                "status": "success"
            },
            "batteryLevel": 55,
            "$metadata" : {...},
            "$version": 4
        }
    }
}

这个孪生设备文档里的根对象是设备标识属性，并包括上报，预期等属性区域。

后端应用支持的操作

后端应用支持如下的原子操作， 这些操作通过HTTPS来暴漏给用户：

  • 根据设备ID取得孪生设备的文档: 该操作返回孪生设备的整个文档。
  • 部分更新孪生设备文档：注意：
    • 预期属性设为null即删除。
    • 更新已存在的，即为更新。
    • 添加新的，即为增加。

例如：

{
     "properties": {
         "desired": {
             "newProperty": {
                 "nestedProperty": "newValue"
             },
             "existingProperty": "otherNewValue",
             "otherOldProperty": null
         }
     }
}

所有这些操作都支持乐观并发，除了这些操作之外，后端应用可以：

  • 使用IoT Hub 查询语言查询孪生设备信息。
  • 使用Jobs在大量设备上运行操作。

设备允许的操作

设备端仅仅支持对孪生设备做如下的原子操作：

  • 取回孪生设备文档。
  • 部分更新上报属性
  • 监控预期属性的变动。

使用Azure IoT Hub SDK可以很容易的处理我们上面提出的各种动作。之后我们会推出实例教程。

Tags和Properties格式

Tags, 预期属性, 上报属性都是Json对象，需要遵行下述规则：

  • Keys: 所有在Json文档中的key都是utf-8编码，区分大小写，最长1kb. 除了不允许包括unicode 控制字符串以及., $,以及SP,其他字符串都可以。
  • 值： 值可以是：boolean, number, string， 也支持Array。
    • 整型最大：4503599627370495， 最小：-4503599627370496
    • 字符串必须是UTF-8编码，最大4kb.
  • 嵌套深度最大嵌套10层。

立即孪生模块(Module Twin)

在Azure IoT Hub中，每个设备标识下可以创建50个模块标识(module identity), 每个模块标识默认创建一个孪生模块，和孪生设备一样，孪生模块也是一个Json文档，格式以及支持的操作和孪生设备几乎是一致的，同时也可以使用查询语言查询。其数据结构也和孪生设备时一致的, 可以参考下图：


如下是一个实例：

{
    "deviceId": "devA",
    "moduleId": "moduleA",
    "etag": "AAAAAAAAAAc=", 
    "status": "enabled",
    "statusReason": "provisioned",
    "statusUpdateTime": "0001-01-01T00:00:00",
    "connectionState": "connected",
    "lastActivityTime": "2015-02-30T16:24:48.789Z",
    "cloudToDeviceMessageCount": 0, 
    "authenticationType": "sas",
    "x509Thumbprint": {     
        "primaryThumbprint": null, 
        "secondaryThumbprint": null 
    }, 
    "version": 2, 
    "tags": {
        "$etag": "123",
        "deploymentLocation": {
            "building": "43",
            "floor": "1"
        }
    },
    "properties": {
        "desired": {
            "telemetryConfig": {
                "sendFrequency": "5m"
            },
            "$metadata" : {...},
            "$version": 1
        },
        "reported": {
            "telemetryConfig": {
                "sendFrequency": "5m",
                "status": "success"
            },
            "batteryLevel": 55,
            "$metadata" : {...},
            "$version": 4
        }
    }
}

其他的内容基本和孪生设备一致。