اصطلاحات IoT Plug and Play

يجب أن تتبع أجهزة IoT أجهزة التوصيل و التشغيل مجموعة من الاصطلاحات عند تبادل الرسائل مع مركز IoT. تستخدم أجهزة IoT أجهزة التوصيل و التشغيل بروتوكول MQTT للتواصل مع IoT Hub، ويتم دعم AMQP من قبل IoT Hub ومتاح في بعض SDKs للجهاز.

يمكن أن يتضمن الجهاز وحدات نمطية، أو يتم تنفيذه في وحدة IoT Edge التي يستضيفها وقت تشغيل IoT Edge.

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

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

لمزيد من المعلومات، راجع دليل نمذجة أجهزة التوصيل و التشغيل IoT.

تحديد النموذج

للإعلان عن النموذج الذي ينفذه، يتضمن جهاز أو وحدة IoT أجهزة التوصيل و التشغيل معرف النموذج في حزمة اتصال MQTT عن طريق إضافة model-id إلى USERNAME الحقل.

لتحديد النموذج الذي ينفذه الجهاز أو الوحدة النمطية، يمكن للخدمة الحصول على معرف النموذج من:

  • الحقل المزدوج modelId للجهاز.
  • حقل التوأم $metadata.$model الرقمي.
  • إعلام بتغيير التوأم الرقمي.

بيانات تتبع الاستخدام

  • لا يتطلب القياس عن بعد المرسل من أي جهاز مكون أي بيانات تعريف إضافية. يضيف النظام الخاصية dt-dataschema .
  • يجب أن يضيف بيانات تتبع الاستخدام المرسلة من جهاز باستخدام المكونات اسم المكون إلى رسالة بيانات تتبع الاستخدام.
  • عند استخدام MQTT، أضف الخاصية $.sub باسم المكون إلى موضوع بيانات تتبع الاستخدام، يضيف النظام الخاصية dt-subject .
  • عند استخدام AMQP، أضف الخاصية dt-subject باسم المكون كتعليق توضيحي للرسالة.

ملاحظة

يتطلب القياس عن بعد من المكونات رسالة واحدة لكل مكون.

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

يتم تعيين خاصية للقراءة فقط بواسطة الجهاز ويتم الإبلاغ عنها إلى التطبيق الخلفي.

عينة لا توجد خاصية للقراءة فقط للمكون

يمكن للجهاز أو الوحدة النمطية إرسال أي JSON صالح يتبع قواعد DTDL V2.

DTDL الذي يحدد خاصية على واجهة:

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

عينة حمولة الخصائص المبلغ عنها:

"reported" :
{
  "temperature" : 21.3
}

عينة من خاصية للقراءة فقط لمكونات متعددة

يجب أن يضيف الجهاز أو الوحدة النمطية العلامة {"__t": "c"} للإشارة إلى أن العنصر يشير إلى مكون.

DTDL الذي يشير إلى مكون:

{
  "@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 الذي يحدد المكون:

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

عينة حمولة الخصائص المبلغ عنها:

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

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

يمكن تعيين خاصية قابلة للكتابة بواسطة التطبيق الخلفي وإرسالها إلى الجهاز.

يجب أن يؤكد الجهاز أو الوحدة النمطية أنه تلقى الخاصية عن طريق إرسال خاصية تم الإبلاغ عنها. يجب أن تتضمن الخاصية المبلغ عنها ما يلي:

  • value - القيمة الفعلية للخاصية (عادة ما تكون القيمة المستلمة، ولكن قد يقرر الجهاز الإبلاغ عن قيمة مختلفة).
  • ac - رمز إقرار يستخدم رمز حالة HTTP.
  • av - إصدار إقرار يشير إلى $version الخاصية المطلوبة. يمكنك العثور على هذه القيمة في حمولة JSON للخاصية المطلوبة.
  • ad - وصف إقرار اختياري.

استجابات الإقرار

عند الإبلاغ عن خصائص قابلة للكتابة، يجب أن يقوم الجهاز بإنشاء رسالة الإقرار، باستخدام الحقول الأربعة الموضحة أعلاه، للإشارة إلى حالة الجهاز الفعلية، كما هو موضح في الجدول التالي:

الحالة (ac) الإصدار (av) القيمة (القيمة) الوصف (av)
200 الإصدار المطلوب القيمة المطلوبة تم قبول قيمة الخاصية المطلوبة
202 الإصدار المطلوب القيمة المقبولة من قبل الجهاز تم قبول قيمة الخاصية المطلوبة، التحديث قيد التقدم (يجب أن ينتهي ب 200)
203 0 القيمة التي تم تعيينها بواسطة الجهاز مجموعة الخصائص من الجهاز، لا تعكس أي رغبة
400 الإصدار المطلوب القيمة الفعلية المستخدمة من قبل الجهاز قيمة الخاصية المطلوبة غير مقبولة
500 الإصدار المطلوب القيمة الفعلية المستخدمة من قبل الجهاز استثناء عند تطبيق الخاصية

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

عند بدء تشغيل جهاز للمرة الأولى، يمكنه إرسال قيمة أولية لخاصية تم الإبلاغ عنها إذا لم يتلق خاصية مطلوبة أولية من مركز IoT. في هذه الحالة، يمكن للجهاز إرسال القيمة الافتراضية مع av إلى 0 وإلى ac203. على سبيل المثال:

"reported": {
  "targetTemperature": {
    "value": 20.0,
    "ac": 203,
    "av": 0,
    "ad": "initialize"
  }
}

يمكن للجهاز استخدام الخاصية التي تم الإبلاغ عنها لتوفير معلومات أخرى إلى المركز. على سبيل المثال، يمكن للجهاز الاستجابة بسلسلة من الرسائل قيد التقدم مثل:

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

عندما يصل الجهاز إلى درجة الحرارة المستهدفة، يرسل الرسالة التالية:

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

يمكن للجهاز الإبلاغ عن خطأ مثل:

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

نوع الكائن

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

  • الكائن بأكمله.
  • الحقول التي حدثها الجهاز فقط.
  • مجموعة فرعية من الحقول.

بالنسبة للكائنات الكبيرة، ضع في اعتبارك تقليل حجم الكائن الذي تقوم بتضمينه في الإقرار.

يوضح المثال التالي خاصية قابلة للكتابة Object معرفة على أنها مع أربعة حقول:

DTDL:

{
  "@type": "Property",
  "name": "samplingRange",
  "schema": {
    "@type": "Object",
    "fields": [
      {
        "name": "startTime",
        "schema": "dateTime"
      },
      {
        "name": "lastTime",
        "schema": "dateTime"
      },
      {
        "name": "count",
        "schema": "integer"
      },
      {
        "name": "errorCount",
        "schema": "integer"
      }
    ]
  },
  "displayName": "Sampling range"
  "writable": true
}

لتحديث هذه الخاصية القابلة للكتابة، أرسل كائنا كاملا من الخدمة يبدو مثل المثال التالي:

{
  "samplingRange": {
    "startTime": "2021-08-17T12:53:00.000Z",
    "lastTime": "2021-08-17T14:54:00.000Z",
    "count": 100,
    "errorCount": 5
  }
}

يستجيب الجهاز بإقرار يشبه المثال التالي:

{
  "samplingRange": {
    "ac": 200,
    "av": 5,
    "ad": "Weighing status updated",
    "value": {
      "startTime": "2021-08-17T12:53:00.000Z",
      "lastTime": "2021-08-17T14:54:00.000Z",
      "count": 100,
      "errorCount": 5
    }
  }
}

عينة لا توجد خاصية قابلة للكتابة للمكون

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

يمكن للجهاز أو الوحدة النمطية إرسال أي JSON صالح يتبع قواعد DTDL V2.

DTDL:

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

عينة حمولة الخاصية المطلوبة:

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

عينة الحمولة الأولى للخاصية المبلغ عنها:

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

عينة الحمولة الثانية للخاصية المبلغ عنها:

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

ملاحظة

يمكنك اختيار دمج هاتين الحمولتين الخاصيتين المبلغ عنهما في حمولة واحدة.

عينة خاصية قابلة للكتابة لمكونات متعددة

يجب أن يضيف الجهاز أو الوحدة النمطية العلامة {"__t": "c"} للإشارة إلى أن العنصر يشير إلى مكون.

يتم إرسال العلامة فقط لتحديثات الخصائص المحددة في مكون. التحديثات إلى الخصائص المحددة في المكون الافتراضي لا تتضمن العلامة، راجع عينة لا توجد خاصية قابلة للكتابة للمكون.

عندما يتلقى الجهاز خصائص متعددة تم الإبلاغ عنها في حمولة واحدة، يمكنه إرسال استجابات الخصائص المبلغ عنها عبر حمولات متعددة أو دمج الاستجابات في حمولة واحدة.

يجب أن يؤكد الجهاز أو الوحدة النمطية أنه تلقى الخصائص عن طريق إرسال الخصائص المبلغ عنها:

DTDL الذي يشير إلى مكون:

{
  "@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 الذي يحدد المكون:

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

عينة حمولة الخاصية المطلوبة:

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

عينة الحمولة الأولى للخاصية المبلغ عنها:

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

عينة الحمولة الثانية للخاصية المبلغ عنها:

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

ملاحظة

يمكنك اختيار دمج هاتين الحمولتين الخاصيتين المبلغ عنهما في حمولة واحدة.

الأوامر

لا تستخدم أي واجهات مكون اسم الأمر بدون بادئة.

على جهاز أو وحدة نمطية، تستخدم واجهات مكونات متعددة أسماء الأوامر بالتنسيق التالي: componentName*commandName.

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

الآن بعد أن تعرفت على اصطلاحات IoT أجهزة التوصيل و التشغيل، إليك بعض الموارد الأخرى: