Сведения о цифровых двойниках IoT Plug and Play

Статья
02/06/2024

Устройство IoT Plug and Play реализует модель, описываемую схемой языка определения цифровых двойников (Digital Twins Definition Language, DTDL). Эта модель описывает набор компонентов, свойств, команд и сообщений телеметрии, которые может иметь определенное устройство.

Примечание.

DTDL используется не только в IoT Plug and Play. Другие службы IoT, такие как Azure Digital Twins, используют этот язык для представления целых сред, таких как здания и электрические сети.

Пакеты SDK для служб Azure IoT включают интерфейсы API, которые позволяют службе взаимодействовать с цифровым двойником устройства. Например, служба может считывать свойства устройства из цифрового двойника или использовать двойника для вызова команды на устройстве. Дополнительные сведения см. в статье Примеры цифровых двойников в центре Интернета вещей.

В примере устройства IoT Plug and Play в этой статье реализована модель контроллера температуры с компонентами термостата.

Двойники устройств и цифровые двойники

Наряду с цифровым двойником Центр Интернета вещей Azure также поддерживает двойник устройства для каждого подключенного устройства. Двойник устройства аналогичен цифровому двойнику в том, что это представление свойств устройства. Центр Интернета вещей инициализирует цифровой двойник и двойник устройства при первой подготовке устройства самонастраивающийся Интернета вещей. Пакеты SDK для служб Azure IoT включают API для взаимодействия с двойниками устройств.

Двойники устройств — это документы JSON, хранящие сведения о состоянии устройства, в том числе метаданные, конфигурации и условия. Дополнительные сведения см. в статье Примеры клиентов службы Центра Интернета вещей. Построители устройств и решений могут использовать один и тот же набор API двойников устройств и пакетов SDK для реализации устройств и решений с помощью соглашений самонастраивающийся Интернета вещей. В двойнике устройства состояние доступного для записи свойства разбивается на разделы требуемых свойств и сообщаемых свойств. Все свойства, доступные только для чтения, находятся в разделе сообщаемых.

API цифровых двойников работают на высокоуровневых конструкциях DTDL, таких как компоненты, свойства и команды, и упрощают создание решений для разработчиков решений самонастраивающийся решений. В цифровом двойника есть унифицированное представление текущего и требуемого состояния свойства. Состояние синхронизации для определенного свойства хранится в разделе $metadata соответствующего компонента по умолчанию.

Пример кода JSON двойника устройства

В следующем фрагменте кода показан двойник устройства IoT Plug and Play в формате объекта JSON:

{
  "deviceId": "sample-device",
  "modelId": "dtmi:com:example:TemperatureController;1",
  "version": 15,
  "properties": {
    "desired": {
      "thermostat1": {
        "__t": "c",
        "targetTemperature": 21.8
      },
      "$metadata": {...},
      "$version": 4
    },
    "reported": {
      "serialNumber": "alwinexlepaho8329",
      "thermostat1": {
        "maxTempSinceLastReboot": 25.3,
        "__t": "c",
        "targetTemperature": {
          "value": 21.8,
          "ac": 200,
          "ad": "Successfully executed patch",
        }
      },
      "$metadata": {...},
      "$version": 11
    }
  }
}

Пример цифрового двойника

В следующем фрагменте кода показан цифровой двойник в формате объекта JSON:

{
  "$dtId": "sample-device",
  "serialNumber": "alwinexlepaho8329",
  "thermostat1": {
    "maxTempSinceLastReboot": 25.3,
    "targetTemperature": 21.8,
    "$metadata": {
      "targetTemperature": {
        "desiredValue": 21.8,
        "desiredVersion": 4,
        "ackVersion": 4,
        "ackCode": 200,
        "ackDescription": "Successfully executed patch",
        "lastUpdateTime": "2020-07-17T06:11:04.9309159Z"
      },
      "maxTempSinceLastReboot": {
         "lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
      }
    }
  },
  "$metadata": {
    "$model": "dtmi:com:example:TemperatureController;1",
    "serialNumber": {
      "lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
    }
  }
}

В следующей таблице описаны поля в объекте JSON цифрового двойника:

Имя поля	Description
`$dtId`	Указанная пользователем строка, представляющая идентификатор цифрового двойника устройства.
`{propertyName}`	Значение свойства в ФОРМАТЕ JSON.
`$metadata.$model`	[Необязательно] Идентификатор интерфейса модели, характеризующего этот цифровой двойник.
`$metadata.{propertyName}.desiredValue`	[Только для доступных для записи свойств] Требуемое значение указанного свойства.
`$metadata.{propertyName}.desiredVersion`	[Только для доступных для записи свойств] Версия требуемого значения, поддерживаемая Центр Интернета вещей.
`$metadata.{propertyName}.ackVersion`	[Обязательный, только для записываемых свойств] Версия, подтвержденная устройством, реализующим цифровой двойник, должна быть больше или равна требуемой версии.
`$metadata.{propertyName}.ackCode`	[Обязательный, только для записываемых свойств] Код, `ack` возвращаемый приложением устройства, реализующим цифровой двойник.
`$metadata.{propertyName}.ackDescription`	[Необязательно, только для записываемых свойств] Описание `ack` , возвращаемое приложением устройства, реализующим цифровой двойник.
`$metadata.{propertyName}.lastUpdateTime`	В Центре Интернета вещей сохраняется метка времени последнего обновления свойства устройством. Метки времени находятся в формате UTC и кодируются ISO8601 в формате YYYY-MM-DDTHH:MM:SS.mmmZ.
`{componentName}`	Объект JSON, содержащий значения и метаданные свойств компонента.
`{componentName}.{propertyName}`	Значение свойства компонента в ФОРМАТЕ JSON.
`{componentName}.$metadata`	Метаданные для компонента.

Свойства

Свойства — это поля данных, представляющие состояние сущности так же, как свойства во многих объектно-ориентированных языках программирования.

Свойство только для чтения

Схема DTDL:

{
    "@type": "Property",
    "name": "serialNumber",
    "displayName": "Serial Number",
    "description": "Serial number of the device.",
    "schema": "string"
}

В этом примере alwinexlepaho8329 — текущее значение свойства serialNumber, доступного только для чтения, сообщаемое устройством.

В следующих фрагментах кода показано параллельное представление JSON для свойства serialNumber:

Двойник устройства

"properties": {
"reported": {
"serialNumber": "alwinexlepaho8329"
}
}

Цифровой двойник

"serialNumber": "alwinexlepaho8329"

Свойство, доступное для записи.

В следующих примерах показано свойство, доступное для записи, в компоненте по умолчанию.

DTDL:

{
  "@type": "Property",
  "name": "fanSpeed",
  "displayName": "Fan Speed",
  "writable": true,
  "schema": "double"
}

Двойник устройства

{
"properties": {
"desired": {
"fanSpeed": 2.0,
},
"reported": {
"fanSpeed": {
"value": 3.0,
"ac": 200,
"av": 1,
"ad": "Successfully executed patch version 1"
}
}
},
}

Цифровой двойник

{
"fanSpeed": 3.0,
"$metadata": {
"fanSpeed": {
"desiredValue": 2.0,
"desiredVersion": 2,
"ackVersion": 1,
"ackCode": 200,
"ackDescription": "Successfully executed patch version 1",
"lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
}
}
}

В этом примере 3.0 — текущее значение свойства fanSpeed, сообщаемое устройством. 2.0 — требуемое значение, которое задается решением. Требуемое значение и состояние синхронизации свойства корневого уровня устанавливаются на корневом уровне $metadata цифрового двойника. Когда устройство переходит в подключенный режим, оно может применить это обновление и вернуть обновленное значение.

Компоненты

Компоненты позволяют создать интерфейс модели в виде сборки других интерфейсов. Например, интерфейс Thermostat можно включить в качестве компонентов и thermostat2 в модель модели контроллера температурыthermostat1.

В двойнике устройства компонент идентифицируется маркером { "__t": "c"}. В цифровом двойнике на присутствие компонента указывает объект $metadata.

В этом примере thermostat1 является компонентом с двумя свойствами:

maxTempSinceLastReboot — свойство только для чтения.
targetTemperature — свойство, доступное для записи, которое было успешно синхронизировано устройством. Требуемое значение и состояние синхронизации этих свойств содержатся в объекте $metadata компоненте.

В следующих фрагментах кода показано параллельное представление JSON для компонента thermostat1:

Двойник устройства

"properties": {
"desired": {
"thermostat1": {
"__t": "c",
"targetTemperature": 21.8
},
"$metadata": {
},
"$version": 4
},
"reported": {
"thermostat1": {
"maxTempSinceLastReboot": 25.3,
"__t": "c",
"targetTemperature": {
"value": 21.8,
"ac": 200,
"ad": "Successfully executed patch",
"av": 4
}
},
"$metadata": {
},
"$version": 11
}
}

Цифровой двойник

"thermostat1": {
"maxTempSinceLastReboot": 25.3,
"targetTemperature": 21.8,
"$metadata": {
"targetTemperature": {
"desiredValue": 21.8,
"desiredVersion": 4,
"ackVersion": 4,
"ackCode": 200,
"ackDescription": "Successfully executed patch",
"lastUpdateTime": "2020-07-17T06:11:04.9309159Z"
},
"maxTempSinceLastReboot": {
"lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
}
}
}

API цифрового двойника

API-интерфейсы цифрового двойника содержат операции для получения цифровых двойников, обновления цифровых двойников, вызова команд компонента и вызова команд для управления цифровыми двойниками. Интерфейсы REST API можно использовать напрямую или через один из пакетов SDK службы.

События изменения цифровых двойников

Если включить события изменения цифрового двойника, событие будет активироваться при каждом изменении текущего или требуемого значения компонента или свойства. События изменения цифрового двойника создаются в формате исправления JSON. Соответствующие события создаются в формате двойника устройства, если включены события изменения двойника.

Сведения о том, как включить маршрутизацию для событий устройств и цифровых двойников, см. в статье Маршрутизация сообщений с устройств Центра Интернета вещей на различные конечные точки в облаке. Сведения о формате сообщений см. в статье Создание и чтение сообщений Центра Интернета вещей.

Например, следующее событие изменения цифрового двойника активируется при targetTemperature установке решения:

iothub-connection-device-id:sample-device
iothub-enqueuedtime:7/17/2020 6:11:04 AM
iothub-message-source:digitalTwinChangeEvents
correlation-id:275d463fa034
content-type:application/json-patch+json
content-encoding:utf-8
[
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature",
    "value": {
      "desiredValue": 21.8,
      "desiredVersion": 4
    }
  }
]

Следующее событие изменения цифрового двойника срабатывает, когда устройство сообщает о применении указанного выше требуемого изменения:

iothub-connection-device-id:sample-device
iothub-enqueuedtime:7/17/2020 6:11:05 AM
iothub-message-source:digitalTwinChangeEvents
correlation-id:275d464a2c80
content-type:application/json-patch+json
content-encoding:utf-8
[
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature/ackCode",
    "value": 200
  },
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature/ackDescription",
    "value": "Successfully executed patch"
  },
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature/ackVersion",
    "value": 4
  },
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature/lastUpdateTime",
    "value": "2020-07-17T06:11:04.9309159Z"
  },
  {
    "op": "add",
    "path": "/thermostat1/targetTemperature",
    "value": 21.8
  }
]

Примечание.

Когда включены уведомления об изменениях как устройства, так и цифрового двойника, сообщения об изменении двойника дублируются.

Следующие шаги

Теперь, когда вы узнали о цифровых двойниках, вот несколько дополнительных ресурсов:

Сведения о цифровых двойниках IoT Plug and Play

Двойники устройств и цифровые двойники

Пример кода JSON двойника устройства

Пример цифрового двойника

Свойства

Свойство только для чтения

Свойство, доступное для записи.

Компоненты

API цифрового двойника

События изменения цифровых двойников

Следующие шаги

Дополнительные ресурсы