البرنامج التعليمي: تكوين أجهزتك من خدمة خلفية

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

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

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

يوضح لك هذا البرنامج التعليمي كيفية استخدام الخصائص المطلوبة والمبلغ عنها لمزامنة معلومات الحالة.

في هذا البرنامج التعليمي، يمكنك تنفيذ المهام التالية:

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

في حال لم يكن لديك اشتراك Azure، فأنشئ حساباً مجانيّاً قبل البدء.

المتطلبات

• يستخدم هذا البرنامج التعليمي Azure CLI لإنشاء موارد سحابية. إذا كان لديك بالفعل مركز IoT مع جهاز مسجل فيه، فيمكنك تخطي هذه الخطوات. هناك طريقتان لتشغيل أوامر CLI:

  • استخدم بيئة Bash في Azure Cloud Shell. لمزيد من المعلومات، راجع تشغيل سريع لـ Azure Cloud Shell - Bash.

  • إذا كنت تفضل تشغيل أوامر مرجع CLI محلياً قم بتثبيت CLI Azure. إذا كنت تعمل على نظام تشغيل Windows أو macOS، ففكر في تشغيل Azure CLI في حاوية Docker. لمزيد من المعلومات، راجع كيفية تشغيل Azure CLI في حاوية Docker.

    • قم بتسجيل الدخول إلى CLI Azure باستخدام az login.
    • عندما يطلب منك ذلك، قم بتثبيت ملحقات Azure CLI عند الاستخدام الأول. لمزيد من المعلومات بشأن الامتدادات، راجع استخدام امتدادات مع Azure CLI.
    • يُرجى تشغيل إصدار az للوصول إلى الإصدار والمكتبات التابعة التي تم تثبيتها. للتحديث لآخر إصدار، يُرجى تشغيل تحديث az.

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

  • يمكنك تنزيل Node.js لمنصات متعددة من nodejs.org.

  • يمكنك التحقق من الإصدار الحالي من Node.js على جهاز التطوير الخاص بك باستخدام الأمر التالي:

    node --version
    

• استنساخ أو تنزيل نموذج Node.js المشروع من نماذج Azure IoT Node.js.

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

إعداد موارد Azure

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

إذا لم يكن لديك بالفعل مركز IoT تم إعداده في اشتراكك، فيمكنك إعداد واحد باستخدام البرنامج النصي CLI التالي. يستخدم هذا البرنامج النصي الاسم tutorial-iot-hub مع رقم عشوائي مرفق باسم مركز IoT. يمكنك استبدال هذا الاسم باسمك الفريد عالميا عند تشغيله. يقوم البرنامج النصي بإنشاء مجموعة الموارد والمركز في منطقة وسط الولايات المتحدة ، والتي يمكنك تغييرها إلى منطقة أقرب إليك. يسترد البرنامج النصي سلسلة اتصال خدمة مركز IoT، والتي تستخدمها في نموذج الواجهة الخلفية للاتصال بمركز IoT الخاص بك:

let "randomIdentifier=$RANDOM*$RANDOM"  
hubname="tutorial-iot-hub-$randomIdentifier"
location=centralus

# Install the IoT extension if it's not already installed:
az extension add --name azure-iot

# Create a resource group:
az group create --name tutorial-iot-hub-rg --location $location

# Create your free-tier IoT hub. You can only have one free IoT hub per subscription.
# Change the sku to S1 to create a standard-tier hub if necessary.
az iot hub create --name $hubname --location $location --resource-group tutorial-iot-hub-rg --partition-count 2 --sku F1

# Make a note of the service connection string, you need it later:
az iot hub connection-string show --hub-name $hubname --policy-name service -o table

يستخدم هذا البرنامج التعليمي جهازا محاكاة يسمى MyTwinDevice. يضيف البرنامج النصي التالي هذا الجهاز إلى سجل الهوية الخاص بك ويسترد سلسلة الاتصال الخاصة به:

# Create the device in the identity registry:
az iot hub device-identity create --device-id MyTwinDevice --hub-name $hubname --resource-group tutorial-iot-hub-rg

# Retrieve the device connection string, you need this later:
az iot hub device-identity connection-string show --device-id MyTwinDevice --hub-name $hubname --resource-group tutorial-iot-hub-rg -o table

إرسال معلومات الحالة إلى جهاز

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

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

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

يمكنك هيكلة الخصائص التي تريدها بأي طريقة مناسبة لتطبيقك. يستخدم هذا المثال خاصية واحدة من المستوى الأعلى تسمى fanOn وتجمع الخصائص المتبقية في مكونات منفصلة. يوضح قصاصة JSON التالية بنية الخصائص المطلوبة التي يستخدمها هذا البرنامج التعليمي. JSON موجود في ملف desired.json.

{
  "fanOn": "true",
  "components": {
    "system": {
      "id": "17",
      "units": "farenheit",
      "firmwareVersion": "9.75"
    },
    "wifi" : { 
      "channel" : "6",
      "ssid": "my_network"
    },
    "climate" : {
      "minTemperature": "68",
      "maxTemperature": "76"
    }
  }
}

تلقي الخصائص المطلوبة في تطبيق جهاز

لعرض نموذج التعليمات البرمجية للجهاز المحاكاة الذي يتلقى الخصائص المطلوبة، انتقل إلى مجلد iot-hub/Tutorials/DeviceTwins في نموذج Node.js المشروع الذي قمت بتنزيله. ثم افتح ملف SimulatedDevice.js في محرر نصوص.

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

استرداد الكائن المزدوج للجهاز

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

// Get the device connection string from a command line argument
var connectionString = process.argv[2];

تحصل التعليمات البرمجية التالية على توأم من كائن العميل:

// Get the device twin
client.getTwin(function(err, twin) {
  if (err) {
    console.error(chalk.red('Could not get device twin'));
  } else {
    console.log(chalk.green('Device twin created'));

إنشاء معالجات

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

// Handle all desired property updates
twin.on('properties.desired', function(delta) {
    console.log(chalk.yellow('\nNew desired properties received in patch:'));

يتفاعل المعالج التالي فقط مع التغييرات التي تم إجراؤها على الخاصية المطلوبة fanOn :

// Handle changes to the fanOn desired property
twin.on('properties.desired.fanOn', function(fanOn) {
    console.log(chalk.green('\nSetting fan state to ' + fanOn));

    // Update the reported property after processing the desired property
    reportedPropertiesPatch.fanOn = fanOn ? fanOn : '{unknown}';
});

معالجات لخصائص متعددة

في عينة الخصائص المطلوبة JSON لهذا البرنامج التعليمي ، تحتوي عقدة المناخ الموجودة أسفل المكونات على خاصيتين ، minTemperature و maxTemperature.

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

// Handle desired properties updates to the climate component
twin.on('properties.desired.components.climate', function(delta) {
    if (delta.minTemperature || delta.maxTemperature) {
      console.log(chalk.green('\nUpdating desired tempertures in climate component:'));
      console.log('Configuring minimum temperature: ' + twin.properties.desired.components.climate.minTemperature);
      console.log('Configuring maximum temperture: ' + twin.properties.desired.components.climate.maxTemperature);

      // Update the reported properties and send them to the hub
      reportedPropertiesPatch.minTemperature = twin.properties.desired.components.climate.minTemperature;
      reportedPropertiesPatch.maxTemperature = twin.properties.desired.components.climate.maxTemperature;
      sendReportedProperties();
    }
});

معالجة عمليات الإدراج والتحديث والحذف

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

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

// Keep track of all the components the device knows about
var componentList = {};

// Use this componentList list and compare it to the delta to infer
// if anything was added, deleted, or updated.
twin.on('properties.desired.components', function(delta) {
  if (delta === null) {
    componentList = {};
  }
  else {
    Object.keys(delta).forEach(function(key) {

      if (delta[key] === null && componentList[key]) {
        // The delta contains a null value, and the
        // device has a record of this component.
        // Must be a delete operation.
        console.log(chalk.green('\nDeleting component ' + key));
        delete componentList[key];

      } else if (delta[key]) {
        if (componentList[key]) {
          // The delta contains a component, and the
          // device has a record of it.
          // Must be an update operation.
          console.log(chalk.green('\nUpdating component ' + key + ':'));
          console.log(JSON.stringify(delta[key]));
          // Store the complete object instead of just the delta
          componentList[key] = twin.properties.desired.components[key];

        } else {
          // The delta contains a component, and the
          // device has no record of it.
          // Must be an add operation.
          console.log(chalk.green('\nAdding component ' + key + ':'));
          console.log(JSON.stringify(delta[key]));
          // Store the complete object instead of just the delta
          componentList[key] = twin.properties.desired.components[key];
        }
      }
    });
  }
});

إرسال الخصائص المطلوبة من تطبيق خلفي

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

لعرض نموذج التعليمات البرمجية للجهاز المحاكاة الذي يتلقى الخصائص المطلوبة، انتقل إلى مجلد iot-hub/Tutorials/DeviceTwins في نموذج Node.js المشروع الذي قمت بتنزيله. ثم افتح ملف ServiceClient.js في محرر نصوص.

يوضح قصاصة التعليمات البرمجية التالية كيفية الاتصال بسجل هوية الجهاز والوصول إلى التوأم لجهاز معين:

// Create a device identity registry object
var registry = Registry.fromConnectionString(connectionString);

// Get the device twin and send desired property update patches at intervals.
// Print the reported properties after some of the desired property updates.
registry.getTwin(deviceId, async (err, twin) => {
  if (err) {
    console.error(err.message);
  } else {
    console.log('Got device twin');

يعرض القصاصة البرمجية التالية تصحيحات الخصائص المختلفة المطلوبة التي يرسلها تطبيق الواجهة الخلفية إلى الجهاز:

// Turn the fan on
var twinPatchFanOn = {
  properties: {
    desired: {
      patchId: "Switch fan on",
      fanOn: "false",
    }
  }
};

// Set the maximum temperature for the climate component
var twinPatchSetMaxTemperature = {
  properties: {
    desired: {
      patchId: "Set maximum temperature",
      components: {
        climate: {
          maxTemperature: "92"
        }
      }
    }
  }
};

// Add a new component
var twinPatchAddWifiComponent = {
  properties: {
    desired: {
      patchId: "Add WiFi component",
      components: {
        wifi: { 
          channel: "6",
          ssid: "my_network"
        }
      }
    }
  }
};

// Update the WiFi component
var twinPatchUpdateWifiComponent = {
  properties: {
    desired: {
      patchId: "Update WiFi component",
      components: {
        wifi: { 
          channel: "13",
          ssid: "my_other_network"
        }
      }
    }
  }
};

// Delete the WiFi component
var twinPatchDeleteWifiComponent = {
  properties: {
    desired: {
      patchId: "Delete WiFi component",
      components: {
        wifi: null
      }
    }
  }
};

يوضح المقتطف التالي كيف يرسل التطبيق الخلفي تحديث الخاصية المطلوب إلى جهاز:

// Send a desired property update patch
async function sendDesiredProperties(twin, patch) {
  twin.update(patch, (err, twin) => {
    if (err) {
      console.error(err.message);
    } else {
      console.log(chalk.green(`\nSent ${twin.properties.desired.patchId} patch:`));
      console.log(JSON.stringify(patch, null, 2));
    }
  });
}

تلقي معلومات الحالة من جهاز

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

إرسال المواقع التي تم الإبلاغ عنها من جهاز

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

// Create a patch to send to the hub
var reportedPropertiesPatch = {
  firmwareVersion:'1.2.1',
  lastPatchReceivedId: '',
  fanOn:'',
  minTemperature:'',
  maxTemperature:''
};

يستخدم الجهاز المحاكي الوظيفة التالية لإرسال التصحيح الذي يحتوي على الخصائص التي تم الإبلاغ عنها إلى لوحة التحكم:

// Send the reported properties patch to the hub
function sendReportedProperties() {
  twin.properties.reported.update(reportedPropertiesPatch, function(err) {
    if (err) throw err;
    console.log(chalk.blue('\nTwin state reported'));
    console.log(JSON.stringify(reportedPropertiesPatch, null, 2));
  });
}

معالجة الخصائص المبلغ عنها

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

// Display the reported properties from the device
function printReportedProperties(twin) {
  console.log("Last received patch: " + twin.properties.reported.lastPatchReceivedId);
  console.log("Firmware version: " + twin.properties.reported.firmwareVersion);
  console.log("Fan status: " + twin.properties.reported.fanOn);
  console.log("Min temperature set: " + twin.properties.reported.minTemperature);
  console.log("Max temperature set: " + twin.properties.reported.maxTemperature);
}

تشغيل التطبيقات

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

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

لتشغيل تطبيق الجهاز المحاكاة، افتح نافذة shell أو موجه الأوامر وانتقل إلى مجلد iot-hub/Tutorials/DeviceTwins في مشروع Node.js قمت بتنزيله. ثم قم بتشغيل الأوامر التالية:

npm install
node SimulatedDevice.js "{your device connection string}"

لتشغيل التطبيق الخلفي، افتح نافذة أخرى أو موجه الأوامر. ثم انتقل إلى مجلد iot-hub/Tutorials/DeviceTwins في مشروع Node.js قمت بتنزيله. ثم قم بتشغيل الأوامر التالية:

npm install
node ServiceClient.js "{your service connection string}"

مراقبة تحديثات الممتلكات المطلوبة

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

تعرض لقطة الشاشة التالية الإخراج من التطبيق الخلفي وتسلط الضوء على كيفية إرسال تحديث إلى الخاصية maxTemperature المطلوبة:

مراقبة تحديثات الممتلكات التي تم الإبلاغ عنها

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

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

تنظيف الموارد

إذا كنت تخطط لإكمال البرنامج التعليمي التالي، فاترك مجموعة الموارد ومركز IoT لإعادة استخدامها لاحقا.

إذا لم تعد بحاجة إلى مركز IoT، فاحذفه ومجموعة الموارد في المدخل. للقيام بذلك، حدد مجموعة موارد البرنامج التعليمي iot-hub-rg التي تحتوي على مركز IoT الخاص بك وحدد حذف.

بدلا من ذلك، استخدم واجهة سطر الأوامر (CLI):

# Delete your resource group and its contents
az group delete --name tutorial-iot-hub-rg

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

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

تنفيذ تحديث الجهاز للبرنامج التعليمي Azure IoT Hub باستخدام الصورة المرجعية Raspberry Pi 3 B+.