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

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

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

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

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

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

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

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

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

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

القياس عن بعد

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

إشعار

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

لمزيد من أمثلة بيانات تتبع الاستخدام، راجع بيانات تتبع الاستخدام للحمولات >

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

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

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

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

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
  }
}

لمزيد من أمثلة خصائص القراءة فقط، راجع خصائص Payloads>.

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

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

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

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

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

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

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

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

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

"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.

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.

لمزيد من أمثلة الأوامر، راجع أوامر Payloads>.

تلميح

لدى IoT Central الاصطلاحات الخاصة به لتنفيذ الأوامر طويلة الأمد والأوامر غير المتصلة.

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

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

• لغة تعريف التوائم الرقمية (DTDL)
• C device SDK
• واجهة برمجة تطبيقات IoT REST
• دليل نمذجة أجهزة التوصيل و التشغيل IoT