تنفيذ CameraStream باستخدام WebRTC

‫1. قبل البدء

تنتمي السمة CameraStream إلى الأجهزة التي يمكنها بث خلاصات الفيديو إلى الشاشات الذكية وأجهزة Chromecast والهواتف الذكية. أصبح بروتوكول WebRTC متوافقًا الآن مع السمة CameraStream، ما يعني أنّه يمكنك تقليل وقت بدء التشغيل ووقت استجابة البث بشكل كبير من جهاز كاميرا إلى شاشة Google Nest.

المتطلبات الأساسية

• راجِع مقدمة حول النقل من السحابة الإلكترونية إلى السحابة الإلكترونية.

أهداف الدورة التعليمية

• كيفية نشر خدمة سحابية للمنزل الذكي
• كيفية ربط خدمتك بخدمة "مساعد Google"
• كيفية البث إلى شاشة Google Nest باستخدام بروتوكول WebRTC

المتطلبات

• متصفّح ويب، مثل Google Chrome
• جهاز iOS أو Android مثبّت عليه تطبيق Google Home
• الإصدار 10.16 من Node.js أو إصدار أحدث
• خطة Blaze (الدفع حسب الاستخدام) في Firebase
• جهاز كاميرا ويب مدمَج أو خارجي يمكنه عرض المحتوى بدقة فائقة
• شاشة Google Nest

‫2. البدء

تثبيت Firebase CLI

تتيح لك أداة Firebase CLI عرض تطبيقات الويب محليًا ونشرها على "استضافة Firebase".

لتثبيت واجهة سطر الأوامر (CLI) في Firebase، اتّبِع الخطوات التالية:

1. في الوحدة الطرفية، نزِّل Firebase CLI وثبِّته:

$ npm install -g firebase-tools

2. تحقَّق من تثبيت واجهة سطر الأوامر بشكل صحيح:

$ firebase --version

3. امنح Firebase CLI إذن الوصول إلى حساب Google الخاص بك:

$ firebase login

إنشاء مشروع

1. انتقِل إلى Google Home Developer Console.
2. انقر على إنشاء مشروع، وأدخِل اسمًا للمشروع، ثم انقر على إنشاء مشروع.

تشغيل تطبيق عميل CameraStream

يتضمّن الرمز المصدر لهذا الدرس التطبيقي حول الترميز عميل WebRTC ينشئ جلسة WebRTC ويتفاوض بشأنها ويديرها بين كاميرا الويب وجهاز العرض الخاص بالمنزل المزوّد بأجهزة ذكية من Google.

لتشغيل تطبيق عميل CameraStream WebRTC، اتّبِع أحد الإجراءَين التاليَين:

• انقر على الزر التالي لتنزيل رمز المصدر على جهاز التطوير:

file_downloadتنزيل رمز المصدر

• استنسِخ مستودع GitHub هذا:

  $ git clone https://github.com/google-home/smarthome-camerastream-webrtc.git
  

يتضمّن الرمز الأدلة التالية:

• الدليل camerastream-start الذي يحتوي على الرمز الأولي الذي تستند إليه في إنشاء تطبيقك
• الدليل camerastream-done الذي يحتوي على رمز الحلّ لبرنامج التدريب العملي المكتمل

يحتوي الدليل camerastream-start على الدلائل الفرعية التالية:

• الدليل الفرعي public الذي يحتوي على واجهة مستخدم أمامية للتحكّم بسهولة في حالة جهاز الكاميرا ومراقبتها
• الدليل الفرعي functions الذي يحتوي على خدمة سحابية تم تنفيذها بالكامل وتدير الكاميرا باستخدام وظائف Firebase السحابية وقاعدة بيانات الوقت الفعلي

يحتوي الرمز البرمجي الأوّلي على تعليقات TODO تشير إلى الأماكن التي تحتاج فيها إلى إضافة رمز أو تغييره، مثل المثال التالي:

// TODO: Implement full SYNC response.

إضافة Firebase إلى مشروعك في Google Home Developer Console

الطريقة 1: من خلال وحدة تحكّم Firebase

1. انتقِل إلى Firebase.
2. انقر على إنشاء مشروع على Firebase.
   
3. في شاشة إنشاء مشروع، انقر على إضافة Firebase إلى مشروع Google Cloud.
   
4. في شاشة البدء، اختَر مشروع Google Cloud الذي أنشأته للتو في Google Home Developer Console، ثم انقر على متابعة.
   

الطريقة 2: من خلال Firebase CLI

firebase projects:addfirebase

اختَر مشروع Google Home Developer Console الذي أنشأته للتو لإضافة Firebase.

عند إضافة Firebase إلى مشروعك على Google Home Play Console، سيظهر في وحدة تحكُّم Firebase. سيتوافق رقم تعريف مشروع Firebase مع رقم تعريف مشروعك على Google Home Play Console.

الربط مع Firebase

1. انتقِل إلى الدليل camerastream-start، ثمّ أعدّ Firebase CLI باستخدام مشروع Actions:

$ cd camerastream-start
$ firebase use <project-id>

2. في الدليل camerastream-start، انتقِل إلى المجلد functions ثم ثبِّت جميع العناصر التابعة اللازمة:

$ cd functions
$ npm install

3. إذا ظهرت لك الرسالة التالية، تجاهلها. يرجع سبب هذا التحذير إلى التبعيات القديمة. لمزيد من المعلومات، يُرجى الاطّلاع على مشكلة GitHub هذه.

found 5 high severity vulnerabilities
  run `npm audit fix` to fix them, or `npm audit` for details

4. إعداد مشروع Firebase:

$ firebase init

5. اختَر الدوالّ والاستضافة. يؤدي ذلك إلى تهيئة واجهات برمجة التطبيقات والميزات اللازمة لمشروعك.

? Which Firebase features do you want to set up for this directory? Press Space to select features, then Enter
 to confirm your choices. (Press <space> to select, <a> to toggle all, <i> to invert selection, and <enter> to
 proceed)
>( ) Data Connect: Set up a Firebase Data Connect service
 ( ) Firestore: Configure security rules and indexes files for Firestore
 ( ) Genkit: Setup a new Genkit project with Firebase
 (*) Functions: Configure a Cloud Functions directory and its files
 ( ) App Hosting: Configure an apphosting.yaml file for App Hosting
 (*) Hosting: Configure files for Firebase Hosting and (optionally) set up GitHub Action deploys
 ( ) Storage: Configure a security rules file for Cloud Storage
 ( ) Emulators: Set up local emulators for Firebase products
 ( ) Remote Config: Configure a template file for Remote Config
 ( ) Extensions: Set up an empty Extensions manifest
 (*) Realtime Database: Configure a security rules file for Realtime Database and (optionally) provision
default instance
 ( ) Data Connect: Set up a Firebase Data Connect service
 ( ) Firestore: Configure security rules and indexes files for Firestore

6. اضبط Cloud Functions باستخدام الملفات التلقائية، وتأكَّد من عدم استبدال الملفَين index.js وpackage.json الحاليَين في نموذج المشروع:

? Would you like to initialize a new codebase, or overwrite an existing one?
Overwrite

? What language would you like to use to write Cloud Functions?
JavaScript

? File functions/package.json already exists. Overwrite?
No

? File functions/index.js already exists. Overwrite?
No

? Do you want to install dependencies with npm now?
Yes

7. اضبط إعدادات الاستضافة باستخدام الدليل public في رمز المشروع واستخدِم الملف index.html الحالي:

? What do you want to use as your public directory?
public

? Configure as a single-page app (rewrite all urls to /index.html)?
Yes

? Set up automatic builds and deploys with GitHub?
No

? File public/index.html already exists. Overwrite?
 No

3- تبادل رسائل بروتوكول وصف الجلسة (SDP)

يُعد تبادل رسائل SDP خطوة مهمة في إنشاء بث WebRTC. بروتوكول وصف الجلسة (SDP) هو بروتوكول مستند إلى نص يصف خصائص جلسة وسائط متعددة. يُستخدم في WebRTC للتفاوض على مَعلمات اتصال من نظير إلى نظير، مثل برامج الترميز المستخدَمة وعناوين IP للمشاركين والمنافذ المستخدَمة لنقل الوسائط.

لاستخدام قاعدة بيانات الوقت الفعلي كمضيف لتبادل رسائل بروتوكول وصف الجلسة (SDP) بين كاميرا الويب وتطبيق عميل CameraStream في المنزل المزوّد بأجهزة ذكية، اتّبِع الخطوات التالية:

1. في وحدة تحكّم Firebase، انقر على إنشاء > قاعدة بيانات الوقت الفعلي > إنشاء قاعدة بيانات.

2. في القائمة المنسدلة موقع قاعدة بيانات الوقت الفعلي، اختَر الموقع المناسب الذي تريد استضافة قاعدة البيانات منه.

3. انقر على البدء في الوضع التجريبي، ثمّ انقر على تفعيل. بعد تفعيل قاعدة بيانات الوقت الفعلي، يجب أن تتمكّن من الرجوع إليها من تطبيق عميل CameraStream.

4. في "وحدة تحكّم Firebase"، انقر على إعدادات المشروع > إعدادات المشروع > إضافة Firebase إلى تطبيق الويب لبدء سير عمل الإعداد.
5. إذا سبق لك إضافة تطبيق إلى مشروع Firebase، انقر على إضافة تطبيق لعرض خيارات المنصّة.
6. أدخِل لقبًا للتطبيق، مثل My web app، ثم انقر على تسجيل التطبيق.
7. في قسم إضافة حزمة تطوير البرامج (SDK) لمنصة Firebase، اختَر استخدام علامة <script>.
8. انسخ القيم من عنصر firebasebaseConfig ثم الصِقها في ملف camaerastream-start/public/webrtc_generator.js.

const firebaseConfig = {
  apiKey: "XXXXX",
  authDomain: "XXXXX",
  projectId: "XXXXX",
  storageBucket: "XXXXX",
  messagingSenderId: "XXXXX",
  appId: "XXXXX",
  measurementId: "XXXXX"
};

9. انقر على متابعة إلى وحدة التحكّم لإكمال العملية. يظهر تطبيق الويب الذي تم إنشاؤه حديثًا في صفحة إعدادات المشروع.

4. إنشاء كاميرا WebRTC

بعد إعداد الإجراء، يجب أن تتعامل خدمة السحابة الإلكترونية مع الأهداف التالية:

• SYNC هي نية تحدث عندما يريد "مساعد Google" معرفة الأجهزة التي ربطها المستخدم. يتم إرسال هذا الرمز إلى خدمتك عندما يربط المستخدم حسابًا. يجب الردّ بحِزمة JSON تتضمّن أجهزة المستخدم وإمكاناتها.
• EXECUTE/QUERY هي نية تحدث عندما يريد "مساعد Google" التحكّم في جهاز نيابةً عن المستخدم. يجب الردّ بحِمل JSON يتضمّن حالة التنفيذ لكل جهاز مطلوب.

في هذا القسم، ستعدّل الدوال التي سبق لك نشرها للتعامل مع هذه النوايا.

تعديل الردّ في SYNC

1. انتقِل إلى الملف functions/index.js. يحتوي على الرمز البرمجي اللازم للاستجابة لطلبات "مساعد Google".
2. عدِّل SYNC intent لعرض البيانات الوصفية للجهاز وإمكاناته:

index.js

app.onSync((body) => {
return {
  requestId: body.requestId,
  payload: {
    agentUserId: USER_ID,
    devices: [{
      id: 'camera',
      type: 'action.devices.types.CAMERA',
      traits: [
        'action.devices.traits.OnOff',
        'action.devices.traits.CameraStream',
      ],
      name: {
        defaultNames: ['My WebRTC Camera'],
        name: 'Camera',
        nicknames: ['Camera'],
      },
      deviceInfo: {
        manufacturer: 'Acme Co',
        model: 'acme-camera',
        hwVersion: '1.0',
        swVersion: '1.0.1',
      },
      willReportState: false,
      attributes: {
        cameraStreamSupportedProtocols:['webrtc'],
        cameraStreamNeedAuthToken: true, 
        cameraStreamSupportsPreview: true
      },
    }],
  },
};
});

3. لم يتم تحديد USER_ID في الرمز. أضِف ما يلي ضمن const _ = require('underscore');:

// Hardcoded user ID
const USER_ID = '123';

التعامل مع نية EXECUTE

يتعامل EXECUTE الغرض مع الأوامر لتعديل حالة الجهاز. يعرض الردّ حالة كل أمر، مثل SUCCESS أو ERROR أو PENDING، وحالة الجهاز الجديدة.

للتعامل مع طلب EXECUTE، عدِّل طلب EXECUTE لعرض نقطة النهاية signaling لمشروع Firebase في ملف functions/index.js:

index.js

app.onExecute(async (body,headers) => {
  var array = headers.authorization.split(' ');
  var snapshot = await firebaseRef.ref('/userId/'+array[1]).once('value');
  var offerGenLocation = snapshot.val().type;
  const {requestId} = body;

  var result = {
    status: 'SUCCESS',
    states: {
      cameraStreamProtocol: 'webrtc',
      cameraStreamSignalingUrl:'https://us-central1-<project-id>.cloudfunctions.net/signaling?token='+array[1], // TODO: Add Firebase hosting URL
      cameraStreamIceServers: '',
      cameraStreamOffer:'',
      cameraStreamAuthToken:'',
    },
    ids: [ 
      'camera'
    ],
  };
  
  return {
    requestId: requestId,
    payload: {
      commands: [result],
    },
  };
});

التعامل مع مشاركة المراجع مع نطاقات خارجية (CORS)

للتعامل مع CORS بسبب استخدام طريقة POST لإرسال وصف الجلسة (SDP)، أضِف عنوان URL الخاص بخدمة "استضافة Firebase" إلى مصفوفة allowlist في ملف functions/index.js:

index.js

'use strict';
.....

var allowList = ['https://www.gstatic.com','https://<project-id>.web.app']; //TODO Add Firebase hosting URL.

لمزيد من المعلومات حول CORS، يُرجى الاطّلاع على مشاركة المراجع مع نطاقات خارجية (CORS).

التعامل مع إنهاء البث

للتعامل مع إنهاء بث WebRTC، أضِف عنوان URL لوظيفة "الإشارة" في Firebase إلى الملف public/webrtc_generator.js:

webrtc_generator.js

terminateButton.onclick = function(){
  console.log('Terminating Stream!!')
  var signalingURL = 'https://us-central1-<project-id>.cloudfunctions.net/signaling'; //TODO Add Firebase hosting URL
   var http = new XMLHttpRequest();

النشر على Firebase

للنشر على Firebase، عليك نشر خدمة تنفيذ الطلبات المستندة إلى السحابة الإلكترونية المعدَّلة باستخدام Firebase CLI:

$ firebase deploy

ينشر هذا الأمر تطبيقًا على الويب وعدّة وظائف Firebase السحابية:

...

✔ Deploy complete!

Project Console: https://console.firebase.google.com/project/<project-id>/overview
Hosting URL: https://<project-id>.web.app

ضبط مشروعك على Play Console

1. انتقِل إلى Play Console.
2. انقر على إنشاء مشروع، وأدخِل اسمًا للمشروع، ثم انقر على إنشاء مشروع.

اختيار عملية الدمج من السحابة الإلكترونية إلى السحابة الإلكترونية

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

1. أدخِل اسم عملية الدمج، واختَر الكاميرا ضِمن نوع الجهاز. يظهر هذا الاسم في تطبيق Google Home لاحقًا عند توفّر جهاز لإعداده. في هذا الدرس العملي، أدخلنا WebRTC Codelab كاسم معروض، ولكن يمكنك استخدام اسم مختلف.

2. ضمن العلامة التجارية للتطبيق، حمِّل ملف png لرمز التطبيق بحجم 144 × 144 بكسل، وأطلِق عليه الاسم .png.

تفعيل ربط الحساب

لتفعيل ربط الحسابات بعد نشر مشروعك، اتّبِع الخطوات التالية:

1. انتقِل إلى Play Console وافتح المشروع.
2. ضمن قسم الدمج بين الخدمات السحابية، انقر على تطوير > تعديل بجانب عملية الدمج.
3. في صفحة الإعداد والضبط، ابحث عن قسم ربط الحساب وأدخِل المعلومات التالية في مربّعات النص المناسبة:

4. انقر على حفظ > اختبار.

5. اختبار كاميرا WebRTC الافتراضية

1. انتقِل إلى عنوان URL الخاص بخدمة الاستضافة الذي ظهر لك عند نشر مشروع Firebase. تظهر لك الواجهة التالية، وهي تطبيق عميل CameraStream:

2. في لوحة درجة دقة الفيديو المحلي، اختَر الفيديو المطلوب.
3. امنح تطبيق عميل CameraStream الإذن بالوصول إلى كاميرا الويب والميكروفون. تظهر خلاصة فيديو من كاميرا الويب على الجهاز العميل.

رابط إلى CameraStream إجراء المنزل الذكي

1. في تطبيق Google Home، انقر على إضافة > يعمل مع Google.

2. ابحث عن الإجراء الذي أنشأته ثم اختَره.

3. دوِّن الرمز الأبجدي الرقمي الفريد المكوّن من خمسة أحرف لأنّك ستحتاج إليه لاحقًا.

4. انقر على إعادتي إلى الصفحة السابقة. تتم إضافة كاميرا WebRTC إلى منزلك في تطبيق Google Home.

بدء بث WebRTC

1. في صفحة الويب الخاصة بتطبيق عميل CameraStream، أدخِل الرمز الأبجدي الرقمي من القسم الأخير في مربّع النص قيمة الرمز المميز لربط الحساب، ثم انقر على إرسال.

2. لبدء جلسة WebRTC من جهاز العرض الذكي من Google، اتّبِع أحد الإجراءات التالية:

• قُل "Ok Google، أريد بثّ محتوى كاميرا WebRTC".
• على جهاز العرض الذكي من Google، انقر على التحكّم في المنزل > الكاميرا > كاميرا WebRTC.

من تطبيق عميل CameraStream في Google Home، يمكنك ملاحظة أنّه تم إنشاء Offer SPD وAnswer SDP وتبادلهما بنجاح. يتم بث الصورة من كاميرا الويب إلى جهاز العرض الذكي من Google باستخدام WebRTC.

6. تهانينا

تهانينا! تعرّفت على كيفية بث المحتوى من كاميرا الويب إلى شاشة Google Nest باستخدام بروتوكول WebRTC.

مزيد من المعلومات

• سمات الأجهزة المنزلية الذكية
• Actions on Google: نموذج المنزل الذكي باستخدام Node.js
• اختبار ومشاركة "مهام المنزل المزوّد بأجهزة ذكية"