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

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

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

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

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

פרטים נוספים על ה-API זמינים בהפניית ה-API של Local Home SDK.

בקטעי הקוד הבאים מוצגות דוגמאות לאופן שבו אפשר לאתחל את אפליקציית ההזמנות המקומיות ולצרף את ה-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 תסרוק את המכשירים המקומיים באמצעות פרטי ההגדרה של הסריקה שציינתם קודם, ותפעיל את הפונקציה IDENTIFY handler עם תוצאות הסריקה.

‫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 לא מופיע מכשיר ה-Hub, מגדירים את isLocalOnly כ-true ב-IdentifyResponsePayload.
• בשדה device.id מופיע מזהה המכשיר המקומי של מכשיר ה-Hub עצמו.

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

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

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

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

ה-handler של 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 handler מחזירה נתוני פלט באותו פורמט כמו נתוני הפלט שמתקבלים מעיבוד הכוונה 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 כמו ל-QUERY intent למילוי ההזמנות בענן. באופן דומה, הפונקציה לטיפול בבקשות QUERY מחזירה נתונים באותו פורמט כמו העיבוד של כוונת המשתמש QUERY.

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

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

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