فهم التوائم الرقمية أجهزة التوصيل و التشغيل IoT

مقالة
02/06/2024

يقوم جهاز IoT أجهزة التوصيل و التشغيل بتنفيذ نموذج موصوف بواسطة مخطط لغة تعريف التوائم الرقمية (DTDL). يصف النموذج مجموعة المكونات والخصائص والأوامر ورسائل بيانات تتبع الاستخدام التي يمكن أن يحتوي عليها جهاز معين.

إشعار

DTDL ليست حصرية أجهزة التوصيل و التشغيل IoT. تستخدمها خدمات إنترنت الأشياء الأخرى، مثل Azure Digital Twins، لتمثيل بيئات بأكملها مثل المباني وشبكات الطاقة.

تتضمن حزم SDK لخدمة Azure IoT واجهات برمجة التطبيقات التي تسمح للخدمة بالتفاعل مع التوأم الرقمي للجهاز. على سبيل المثال، يمكن للخدمة قراءة خصائص الجهاز من التوأم الرقمي أو استخدام التوأم الرقمي لاستدعاء أمر على جهاز. لمعرفة المزيد، راجع أمثلة التوأم الرقمي لمركز IoT.

يقوم مثال جهاز IoT أجهزة التوصيل و التشغيل في هذه المقالة بتنفيذ نموذج وحدة تحكم درجة الحرارة الذي يحتوي على مكونات Thermostat.

توائم الجهاز والتوائم الرقمية

بالإضافة إلى التوأم الرقمي، يحافظ Azure IoT Hub أيضا على توأم جهاز لكل جهاز متصل. يشبه توأم الجهاز التوأم الرقمي من حيث أنه تمثيل لخصائص الجهاز. يقوم مركز IoT بتهيئة توأم رقمي وتوائم جهاز في المرة الأولى التي يتم فيها توفير جهاز IoT أجهزة التوصيل و التشغيل. تتضمن حزم SDK لخدمة Azure IoT واجهات برمجة التطبيقات للتفاعل مع توائم الجهاز.

توائم الجهاز عبارة عن مستندات JSON تُخزِّن معلومات حالة الجهاز، بما في ذلك بيانات التعريف والتكوينات والحالات. لمعرفة المزيد، راجع أمثلة عميل خدمة IoT Hub. يمكن لمنشئي الأجهزة والحلول استخدام نفس مجموعة واجهات برمجة التطبيقات المزدوجة للجهاز وSDKs لتنفيذ الأجهزة والحلول باستخدام اصطلاحات IoT أجهزة التوصيل و التشغيل. في توأم الجهاز، يتم تقسيم حالة الخاصية القابلة للكتابة عبر الخصائص المطلوبة وأقسام الخصائص المبلغ عنها. تتوفر كافة خصائص القراءة فقط ضمن قسم الخصائص التي تم الإبلاغ عنها.

تعمل واجهات برمجة التطبيقات الرقمية المزدوجة على بنيات DTDL عالية المستوى مثل المكونات والخصائص والأوامر وتجعل من السهل على منشئي الحلول إنشاء حلول IoT أجهزة التوصيل و التشغيل. في التوأم الرقمي، هناك طريقة عرض موحدة للحالة الحالية والمطلوبة للخاصية. يتم تخزين حالة المزامنة لخاصية معينة في قسم المكون $metadata الافتراضي المقابل.

مثال على JSON المزدوج للجهاز

تعرض القصاصة البرمجية التالية جهاز IoT أجهزة التوصيل و التشغيل المزدوج المنسق ككائن 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 التوأم الرقمي:

اسم الحقل	‏‏الوصف
`$dtId`	سلسلة يوفرها المستخدم تمثل معرف التوأم الرقمي للجهاز.
`{propertyName}`	قيمة خاصية في JSON.
`$metadata.$model`	[اختياري] معرف واجهة النموذج التي تميز هذا التوأم الرقمي.
`$metadata.{propertyName}.desiredValue`	[فقط للخصائص القابلة للكتابة] القيمة المطلوبة للخاصية المحددة.
`$metadata.{propertyName}.desiredVersion`	[فقط للخصائص القابلة للكتابة] إصدار القيمة المطلوبة التي يحتفظ بها IoT Hub.
`$metadata.{propertyName}.ackVersion`	[مطلوب، فقط للخصائص القابلة للكتابة] الإصدار الذي أقر به الجهاز الذي ينفذ التوأم الرقمي، يجب أن يكون أكبر أو مساويا للإصدار المطلوب.
`$metadata.{propertyName}.ackCode`	[مطلوب، فقط للخصائص القابلة للكتابة] التعليمات `ack` البرمجية التي تم إرجاعها بواسطة تطبيق الجهاز الذي ينفذ التوأم الرقمي.
`$metadata.{propertyName}.ackDescription`	[اختياري، فقط للخصائص القابلة للكتابة] `ack` الوصف الذي تم إرجاعه بواسطة تطبيق الجهاز الذي ينفذ التوأم الرقمي.
`$metadata.{propertyName}.lastUpdateTime`	يحافظ IoT Hub على الطابع الزمني لآخر تحديث للخاصية بواسطة الجهاز. تكون الطوابع الزمنية بتنسيق 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 كمكونات thermostat1 وفي thermostat2نموذج نموذج وحدة تحكم درجة الحرارة.

في توأم الجهاز، يتم تحديد مكون بواسطة العلامة { "__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"
}
}
}

واجهات برمجة تطبيقات التوأم الرقمي

تتضمن واجهات برمجة التطبيقات التوأم الرقمي الحصول على Digital Twin وتحديث Digital Twin و Invoke Component Command و Invoke Command operations more managing a digital twin. يمكنك إما استخدام واجهات برمجة تطبيقات REST مباشرة أو من خلال إحدى حزم SDK للخدمة.

أحداث التغيير المزدوج الرقمية

عند تمكين أحداث تغيير التوأم الرقمي، يتم تشغيل حدث كلما تغيرت القيمة الحالية أو المطلوبة للمكون أو الخاصية. يتم إنشاء أحداث تغيير التوأم الرقمي بتنسيق JSON Patch . يتم إنشاء الأحداث المقابلة بتنسيق الجهاز المزدوج إذا تم تمكين أحداث التغيير المزدوج.

لمعرفة كيفية تمكين التوجيه لأحداث الجهاز والتوائم الرقمية، راجع استخدام توجيه رسائل IoT Hub لإرسال رسائل من جهاز إلى سحابة إلى نقاط نهاية مختلفة. لفهم تنسيق الرسالة، راجع إنشاء رسائل IoT Hub وقراءتها.

على سبيل المثال، يتم تشغيل حدث تغيير التوأم الرقمي التالي عند 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

توائم الجهاز والتوائم الرقمية

مثال على JSON المزدوج للجهاز

مثال التوأم الرقمي

خصائص

خاصية للقراءة فقط

خاصية قابلة للكتابة

المكونات

واجهات برمجة تطبيقات التوأم الرقمي

أحداث التغيير المزدوج الرقمية

الخطوات التالية

الموارد الإضافية