הטמעה של האפליקציה המקומית למילוי הזמנות

כדי לתמוך במימוש הזמנות בחנויות מקומיות, צריך ליצור אפליקציה שתטפל בכוונות האלה של בית חכם:

• IDENTIFY: תומך באיתור של מכשירים חכמים שאפשר לשלוט בהם באופן מקומי. ה-intent handler מחלץ נתונים שהמכשיר החכם מחזיר במהלך הגילוי ושולח אותם בתגובה ל-Google.
• ‫EXECUTE: תומך בהרצת פקודות.
• ‫QUERY: תומך בשאילתות לגבי מצב המכשיר.
• ‫REACHABLE_DEVICES: (אופציונלי) תומך באיתור של מכשירי קצה שאפשר לשלוט בהם באופן מקומי, שנמצאים מאחורי רכזת (או גשר).

האפליקציה הזו פועלת במכשירי Google Home או Google Nest של המשתמש ומחברת את המכשיר החכם אל Assistant. אפשר ליצור את האפליקציה באמצעות TypeScript (מומלץ) או JavaScript.

מומלץ להשתמש ב-TypeScript כי אפשר להשתמש בקשירות כדי לוודא באופן סטטי שהנתונים שהאפליקציה מחזירה תואמים לסוגים שהפלטפורמה מצפה להם.

מידע נוסף על ה-API זמין במאמר Local Home SDK הפניית API.

בקטעי הקוד הבאים אפשר לראות איך מאתחלים את אפליקציית ההזמנות עם משלוח מהיר ומצרפים את ה-handlers.

import App = smarthome.App;
const localHomeApp: App = new App("1.0.0");
localHomeApp
  .onIdentify(identifyHandler)
  .onExecute(executeHandler)
  .listen()
  .then(() => {
    console.log("Ready");
  });

import App = smarthome.App;
const localHomeApp: App = new App("1.0.0");
localHomeApp
  .onIdentify(identifyHandler)
  .onReachableDevices(reachableDevicesHandler)
  .onExecute(executeHandler)
  .listen()
  .then(() => {
    console.log("Ready");
  });

יצירת הפרויקט

כדי לפרוס את האפליקציה לניהול הזמנות מקומיות, צריך ליצור חבילת JavaScript עבור הקוד וכל התלויות שלו.

משתמשים בכלי לאתחול פרויקטים באפליקציה לניהול הזמנות מקומיות כדי ליצור את מבנה הפרויקט המתאים עם הגדרות חבילת המשאבים המועדפת.

תבניות פרויקט

כדי לבחור את הגדרות ה-bundler, מריצים את הפקודה npm init כמו בדוגמאות הבאות:

npm init @google/local-home-app project-directory/ --bundler none

project-directory/
├── node_modules/
├── package.json
├── .gitignore
├── index.ts
├── test.ts
├── tsconfig.json
├── tslint.json
└── serve.js

npm init @google/local-home-app project-directory/ --bundler webpack

project-directory/
├── node_modules/
├── package.json
├── .gitignore
├── index.ts
├── test.ts
├── tsconfig.json
├── tslint.json
├── webpack.config.web.js
├── webpack.config.node.js
└── serve.js

npm init @google/local-home-app project-directory/ --bundler rollup

project-directory/
├── node_modules/
├── package.json
├── .gitignore
├── index.ts
├── test.ts
├── tsconfig.json
├── tslint.json
├── rollup.config.js
└── serve.js

npm init @google/local-home-app project-directory/ --bundler parcel

project-directory/
├── node_modules/
├── package.json
├── .gitignore
├── index.ts
├── test.ts
├── tsconfig.json
├── tslint.json
└── serve.js

ביצוע משימות נפוצות ברמת הפרויקט

הפרויקט שנוצר תומך בסקריפטים של npm הבאים:

cd project-directory/
npm run build

cd project-directory/
npm run lint
npm run compile
npm test

cd project-directory/
npm run start

הטמעה של רכיב ה-handler של IDENTIFY

ה-handler‏ IDENTIFY יופעל כשמכשיר Google Home או מכשיר Google Nest יופעל מחדש ויימצא מכשירים מקומיים לא מאומתים (כולל מכשירי קצה שמחוברים לרכזת). פלטפורמת Local Home תסרוק את המכשירים המקומיים באמצעות פרטי ההגדרה של הסריקה שציינתם קודם, ותפעיל את ה-handler של IDENTIFY עם תוצאות הסריקה.

‫IdentifyRequest מפלטפורמת Local Home מכיל את נתוני הסריקה של מופע LocalIdentifiedDevice. רק מופע אחד של device מאוכלס, על סמך הגדרת הסריקה שגילתה את המכשיר.

אם תוצאות הסריקה תואמות למכשיר, רכיב ה-handler של IDENTIFY צריך להחזיר אובייקט IdentifyResponsePayload, שכולל אובייקט device עם מטא-נתונים של בית חכם (כמו סוגים, מאפיינים וסטטוס הדוח).

‫Google יוצרת שיוך למכשיר אם הערך verificationId מהתגובה IDENTIFY תואם לאחד מהערכים otherDeviceIds שמוחזרים בתגובה SYNC.

דוגמה

בקטעי הקוד הבאים אפשר לראות איך יוצרים רכיבי handler של IDENTIFY לשילובים של מכשירים עצמאיים ושל רכזות, בהתאמה.

const identifyHandler = (request: IntentFlow.IdentifyRequest):
  IntentFlow.IdentifyResponse => {

    // Obtain scan data from protocol defined in your scan config
    const device = request.inputs[0].payload.device;
    if (device.udpScanData === undefined) {
      throw Error("Missing discovery response");
    }
    const scanData = device.udpScanData.data;

    // Decode scan data to obtain metadata about local device
    const verificationId = "local-device-id";

    // Return a response
    const response: IntentFlow.IdentifyResponse = {
      intent: Intents.IDENTIFY,
      requestId: request.requestId,
      payload: {
        device: {
          id: device.id || "",
          verificationId, // Must match otherDeviceIds in SYNC response
        },
      },
    };
    return response;
  };

const identifyHandler = (request: IntentFlow.IdentifyRequest):
  IntentFlow.IdentifyResponse => {

    // Obtain scan data from protocol defined in your scan config
    const device = request.inputs[0].payload.device;
    if (device.udpScanData === undefined) {
      throw Error("Missing discovery response");
    }
    const scanData = device.udpScanData.data;

    // Decode scan data to obtain metadata about local device
    const proxyDeviceId = "local-hub-id";

    // Return a response
    const response: IntentFlow.IdentifyResponse = {
      intent: Intents.IDENTIFY,
      requestId: request.requestId,
      payload: {
        device: {
          id: proxyDeviceId,
          isProxy: true,     // Device can control other local devices
          isLocalOnly: true, // Device not present in `SYNC` response
        },
      },
    };
    return response;
  };

זיהוי מכשירים שמחוברים למרכז

אם Google מזהה מכשיר מרכזי, היא מתייחסת אליו כאל צינור להעברת נתונים למכשירי הקצה שמחוברים למרכז, ומנסה לאמת את מכשירי הקצה האלה.

כדי לאפשר ל-Google לוודא שקיים מכשיר רכזת, פועלים לפי ההוראות האלה לIDENTIFY handler:

• אם בתגובה של SYNC מופיעים מזהים של מכשירי קצה מקומיים שמחוברים ל-hub, מגדירים את isProxy כ-trueב-IdentifyResponsePayload.
• אם בתגובה של SYNC לא מופיע המכשיר שלכם, צריך להגדיר את isLocalOnly כ-true ב-IdentifyResponsePayload.
• בשדה device.id מופיע מזהה המכשיר המקומי של מכשיר ה-Hub עצמו.

הטמעה של רכיב ה-handler‏ REACHABLE_DEVICES (רק בשילובים עם רכזות)

‫Google שולחת את כוונת REACHABLE_DEVICES כדי לאשר אילו מכשירי קצה אפשר לשלוט בהם באופן מקומי. הכוונה הזו מופעלת בכל פעם ש-Google מריצה סריקה לגילוי (פעם בדקה בערך), כל עוד המרכז מזוהה כמחובר לאינטרנט.

מטמיעים את ה-handler‏ REACHABLE_DEVICES באופן דומה ל-handler‏ IDENTIFY, אבל ה-handler צריך לאסוף מזהי מכשירים נוספים שאפשר להגיע אליהם באמצעות ה-proxy המקומי (כלומר, המרכז). השדה device.verificationId מכיל את מזהה המכשיר המקומי של מכשיר קצה שמחובר לרכזת.

‫ReachableDevicesRequest מפלטפורמת Local Home מכיל מופע של LocalIdentifiedDevice. באמצעות המופע הזה, אפשר לקבל את מזהה מכשיר ה-proxy וגם נתונים מתוצאות הסריקה.

הפונקציה לטיפול ב-REACHABLE_DEVICES צריכה להחזיר אובייקט ReachableDevicesPayload שכולל אובייקט devices שמכיל מערך של ערכי verificationId שמייצגים את מכשירי הקצה שהרכזת שולטת בהם. הערכים של verificationId צריכים להיות זהים לאחד מהערכים של otherDeviceIds בתגובה SYNC.

בקטע הקוד הבא אפשר לראות איך יוצרים את ה-handler של REACHABLE_DEVICES.

const reachableDevicesHandler = (request: IntentFlow.ReachableDevicesRequest):
  IntentFlow.ReachableDevicesResponse => {

    // Reference to the local proxy device
    const proxyDeviceId = request.inputs[0].payload.device.id;

    // Gather additional device ids reachable by local proxy device
    // ...

    const reachableDevices = [
      // Each verificationId must match one of the otherDeviceIds
      // in the SYNC response
      { verificationId: "local-device-id-1" },
      { verificationId: "local-device-id-2" },
    ];

    // Return a response
    const response: IntentFlow.ReachableDevicesResponse = {
      intent: Intents.REACHABLE_DEVICES,
      requestId: request.requestId,
      payload: {
        devices: reachableDevices,
      },
    };
    return response;
  };

הטמעה של ה-handler של EXECUTE

ה-handler של EXECUTE באפליקציה מעבד פקודות של משתמשים ומשתמש ב-Local Home SDK כדי לגשת למכשירים החכמים שלכם באמצעות פרוטוקול קיים.

פלטפורמת Local Home מעבירה את אותה מטען ייעודי (payload) של קלט לפונקציית ה-handler של EXECUTE כמו לפונקציית ה-intent של EXECUTE למילוי ההזמנה בענן. באופן דומה, הפונקציה לטיפול בבקשות EXECUTE מחזירה נתוני פלט באותו פורמט כמו נתוני הפלט שמתקבלים מעיבוד כוונת המשתמש EXECUTE. כדי לפשט את יצירת התגובה, אפשר להשתמש במחלקה Execute.Response.Builder ש-Local Home SDK מספק.

לאפליקציה שלכם אין גישה ישירה לכתובת ה-IP של המכשיר. במקום זאת, משתמשים בממשק CommandRequest כדי ליצור פקודות שמבוססות על אחד מהפרוטוקולים הבאים: UDP,‏ TCP או HTTP. לאחר מכן, קוראים לפונקציה deviceManager.send() כדי לשלוח את הפקודות.

כשמפנים פקודות למכשירים, משתמשים במזהה המכשיר (ובפרמטרים מהשדה customData, אם הם כלולים) מהתשובה SYNC כדי לתקשר עם המכשיר.

דוגמה

בקטע הקוד הבא אפשר לראות איך יוצרים את רכיב ה-handler של EXECUTE.

const executeHandler = (request: IntentFlow.ExecuteRequest):
  Promise<IntentFlow.ExecuteResponse> => {

    // Extract command(s) and device target(s) from request
    const command = request.inputs[0].payload.commands[0];
    const execution = command.execution[0];

    const response = new Execute.Response.Builder()
      .setRequestId(request.requestId);

    const result = command.devices.map((device) => {
      // Target id of the device provided in the SYNC response
      const deviceId = device.id;
      // Metadata for the device provided in the SYNC response
      // Use customData to provide additional required execution parameters
      const customData: any = device.customData;

      // Convert execution command into payload for local device
      let devicePayload: string;
      // ...

      // Construct a local device command over TCP
      const deviceCommand = new DataFlow.TcpRequestData();
      deviceCommand.requestId = request.requestId;
      deviceCommand.deviceId = deviceId;
      deviceCommand.data = devicePayload;
      deviceCommand.port = customData.port;
      deviceCommand.operation = Constants.TcpOperation.WRITE;

      // Send command to the local device
      return localHomeApp.getDeviceManager()
        .send(deviceCommand)
        .then((result) => {
          response.setSuccessState(result.deviceId, state);
        })
        .catch((err: IntentFlow.HandlerError) => {
          err.errorCode = err.errorCode || IntentFlow.ErrorCode.INVALID_REQUEST;
          response.setErrorState(device.id, err.errorCode);
        });
    });

    // Respond once all commands complete
    return Promise.all(result)
      .then(() => response.build());
  };

הטמעה של רכיב handler מסוג QUERY

ה-handler ‏QUERY באפליקציה מעבד את בקשות המשתמשים ומשתמש ב-Local Home SDK כדי לדווח על מצב המכשירים החכמים.

פלטפורמת Local Home מעבירה את אותה מטען ייעודי (payload) של בקשה לפונקציית הטיפול QUERY כמו ל-intent‏ QUERY למילוי ההזמנות בענן. באופן דומה, הפונקציה QUERY handler מחזירה נתונים באותו פורמט כמו העיבוד של כוונת המשתמש QUERY.

שליחת פקודות למכשירים שמוגדרים מאחורי רכזת

כדי לשלוט במכשירי קצה שמוגדרים מאחורי רכזת, יכול להיות שתצטרכו לספק מידע נוסף במטען הייעודי (payload) של הפקודה הספציפית לפרוטוקול שנשלחת לרכזת, כדי שהרכזת תוכל לזהות לאיזה מכשיר מיועדת הפקודה. במקרים מסוימים, אפשר להסיק את הערך הזה ישירות מהערך device.id, אבל אם זה לא המצב, צריך לכלול את הנתונים הנוספים האלה כחלק מהשדה customData.

אם יצרתם את האפליקציה באמצעות TypeScript, חשוב לזכור לקמפל את האפליקציה ל-JavaScript. אתם יכולים להשתמש במערכת המודולים שתבחרו כדי לכתוב את הקוד. מוודאים שהיעד נתמך בדפדפן Chrome.