1. 事前準備
身為物聯網 (IoT) 的開發人員,您可以建立智慧型住宅動作,讓使用者透過 Google Home 應用程式中的觸控設定控制裝置,以及透過 Google 助理語音指令。
智慧住宅動作會運用 Home Graph 提供住家及其裝置的情境資料,藉此建立住家的邏輯地圖。這類背景資訊能讓 Google 助理更自然地瞭解使用者與自己在家中的位置相關的要求。舉例來說,Home Graph 可儲存客廳的概念,因為這類客廳包含由不同製造商提供的多種裝置,例如溫度控制器、燈具、風扇和吸塵器。
先備知識
- 開發人員指南:建立智慧型住宅動作
建構項目
在本程式碼研究室中,您將發布管理虛擬智慧洗衣機的雲端服務,然後建構智慧型住宅動作,並將其連結至 Google 助理。
課程內容
- 如何部署智慧型住宅雲端服務
- 如何將服務連結至 Google 助理
- 如何將裝置狀態變更發布至 Google
軟硬體需求
- 使用 Google Chrome 等網路瀏覽器
- 已安裝 Google Home 應用程式的 iOS 或 Android 裝置
- Node.js 10.16 以上版本
- Google Cloud 帳單帳戶
2. 開始使用
啟用活動控制項
如要使用 Google 助理,你必須將特定活動資料提供給 Google。Google 助理需要這類資料才能正常運作;不過,共用資料的規定並不是 SDK 專用。您需要建立 Google 帳戶 (如果尚未建立的話),才能分享這些資料。您可以使用任何 Google 帳戶,不一定要使用開發人員帳戶。
找到要搭配 Google 助理使用的 Google 帳戶,然後開啟「活動控制項」頁面。
請務必啟用下列切換鈕:
- 網頁與應用程式活動:此外,請務必勾選「包括 Chrome 歷史記錄以及採用 Google 服務的網站、應用程式和裝置中的活動記錄」核取方塊。
- 裝置資訊
- 語音和音訊活動
建立 Actions 專案
- 前往 Actions on Google Developer Console。
- 按一下「新增專案」並輸入專案名稱,然後點選「建立專案」。
選取智慧型住宅應用程式
在 Actions 主控台的總覽畫面中,選取「智慧型住宅」。
選擇「智慧型住宅」體驗資訊卡並點選「開始建構」,系統會將您導向專案控制台。
安裝 Firebase CLI
Firebase 指令列介面 (CLI) 可讓您在本機提供網頁應用程式,並將網頁應用程式部署至 Firebase 託管。
如要安裝 CLI,請從終端機執行下列 npm 指令:
npm install -g firebase-tools
如要確認已正確安裝 CLI,請執行下列指令:
firebase --version
執行下列指令,透過 Google 帳戶授權 Firebase CLI:
firebase login
3. 執行範例應用程式
現在您已設定開發環境,可以部署範例專案,確認所有設定皆正確無誤。
取得原始碼
點選下方連結,即可在開發機器上下載這個程式碼研究室的範例:
...或者從指令列複製 GitHub 存放區:
git clone https://github.com/google-home/smarthome-washer.git
關於專案
範例專案包含下列子目錄:
public:
用於輕鬆控制及監控智慧型洗衣機狀態的前端 UI。functions:
這是完全導入的雲端服務,透過 Cloud Functions for Firebase 和 Firebase 即時資料庫管理智慧型洗衣機。
連結至 Firebase
前往 washer-start
目錄,然後使用 Actions 專案設定 Firebase CLI:
cd washer-start firebase use <project-id>
設定 Firebase 專案
初始化 Firebase 專案。
firebase init
選取 CLI 功能、「即時資料庫」、「函式」,以及包含 Firebase 託管的「託管」功能。
? Which Firebase CLI features do you want to set up for this directory? Press Space to select features, then Enter to confirm your choices. ❯◉ Realtime Database: Configure a security rules file for Realtime Database and (optionally) provision default instance ◯ Firestore: Configure security rules and indexes files for Firestore ◉ Functions: Configure a Cloud Functions directory and its files ◉ Hosting: Configure files for Firebase Hosting and (optionally) set up GitHub Action deploys ◯ Hosting: 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
這麼做會為專案初始化必要的 API 和功能。
系統提示時,初始化即時資料庫。您可以使用資料庫執行個體的預設位置。
? It seems like you haven't initialized Realtime Database in your project yet. Do you want to set it up? Yes ? Please choose the location for your default Realtime Database instance: us-central1
您使用的是範例程式碼,因此請選擇安全性規則的預設檔案,而且確保不會覆寫現有的資料庫規則檔案。
? File database.rules.json already exists. Do you want to overwrite it with the Realtime Database Security Rules for <project-ID>-default-rtdb from the Firebase Console? No
如果您要重新初始化專案,請在系統詢問是否要初始化或覆寫程式碼集時,選取「覆寫」。
? Would you like to initialize a new codebase, or overwrite an existing one? Overwrite
設定函式時,請使用預設檔案,並確保您不會覆寫專案範例中現有的 index.js 和 package.json 檔案。
? What language would you like to use to write Cloud Functions? JavaScript ? Do you want to use ESLint to catch probable bugs and enforce style? No ? File functions/package.json already exists. Overwrite? No ? File functions/index.js already exists. Overwrite? No
如果您要重新初始化專案,當系統詢問您要初始化或覆寫函式/.gitignore 時,請選取「No」。
? File functions/.gitignore already exists. Overwrite? No
? Do you want to install dependencies with npm now? Yes
最後,請將「託管」設定設為在專案程式碼中使用 public
目錄,並使用現有的 index.html 檔案。當系統要求使用 ESLint 時,選取「No」。
? 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
如果不小心啟用 ESLint,可以透過下列兩種方法停用:
- 使用 GUI,前往專案底下的
../functions
資料夾,選取隱藏的檔案.eslintrc.js
,然後刪除該檔案。請勿將其誤認為名稱相似的.eslintrc.json
。 - 使用指令列:
cd functions rm .eslintrc.js
為確保 Firebase 設定正確且完整,請將 firebase.json
檔案從 washer-done
目錄複製到 washer-start
目錄,並覆寫 washer-start
中的檔案。
在 washer-start
目錄中:
cp -vp ../washer-done/firebase.json .
部署至 Firebase
您已安裝依附元件並設定專案,現在可以開始執行應用程式了。
firebase deploy
以下是控制台輸出內容:
... ✔ Deploy complete! Project Console: https://console.firebase.google.com/project/<project-id>/overview Hosting URL: https://<project-id>.web.app
這個指令會部署網頁應用程式和多個 Cloud Functions for Firebase。
在瀏覽器中開啟「Hosting URL」(代管網址) (https://<project-id>.web.app
),即可查看網頁應用程式。您將看到以下介面:
這個網頁版 UI 代表可供查看或修改裝置狀態的第三方平台。如要開始在資料庫中填入裝置資訊,請按一下「更新」。您不會看到任何變更,但會將洗衣機的目前狀態儲存在資料庫中。
現在可以透過動作控制台,將您部署的雲端服務連結至 Google 助理。
設定 Actions 主控台專案
在「總覽」>「簡介」下方建立動作,選取「新增動作」。輸入為智慧型住宅意圖執行要求的 Cloud 函式網址,然後按一下「儲存」。
https://us-central1-<project-id>.cloudfunctions.net/smarthome
在「開發」部分「叫用」分頁,為動作新增「顯示名稱」,然後按一下「儲存」。這個名稱會顯示在 Google Home 應用程式中。
如要啟用帳戶連結功能,請選取「開發」>「在左側導覽面板中選取「帳戶連結」選項。使用下列帳戶連結設定:
用戶端 ID |
|
用戶端密碼 |
|
驗證網址 |
|
權杖網址 |
|
按一下「儲存」儲存帳戶連結設定,然後按一下「測試」,即可在專案上啟用測試。
系統會將您重新導向至模擬器。如果系統未顯示「立即測試功能」,請點選「重設測試」,確認測試功能已啟用。
現在您可以開始導入必要的 Webhook,將裝置狀態連結至 Google 助理。
4. 建立洗衣機
動作設定完成後,你可以新增裝置和傳送資料了。您的雲端服務必須處理下列意圖:
- 當 Google 助理想知道使用者連結哪些裝置時,就會發生
SYNC
意圖。當使用者連結帳戶後,系統會將這項資訊傳送至您的服務。您應該使用 JSON 酬載回應,其中包含所有使用者的裝置及其功能。 - 當 Google 助理想要瞭解裝置目前狀態或狀態時,就會發生
QUERY
意圖。您應該在回應中提供 JSON 酬載,其中包含每個要求裝置的狀態。 - 當 Google 助理要代表使用者控制裝置時,就會發生
EXECUTE
意圖。請在回應中提供 JSON 酬載,其中包含每個要求裝置的執行狀態。 - 使用者將帳戶與 Google 助理取消連結時,就會發生
DISCONNECT
意圖。請停止將這位使用者裝置的事件傳送給 Google 助理。
您將在以下各節中更新先前部署的函式,以處理這些意圖。
更新 SYNC 回應
開啟 functions/index.js
,其中包含用來回應 Google 助理要求的程式碼。
您必須傳回裝置中繼資料和功能,來處理 SYNC
意圖。更新 onSync
陣列中的 JSON,加入裝置資訊,以及衣服墊的建議特徵。
index.js
app.onSync((body) => {
return {
requestId: body.requestId,
payload: {
agentUserId: USER_ID,
devices: [{
id: 'washer',
type: 'action.devices.types.WASHER',
traits: [
'action.devices.traits.OnOff',
'action.devices.traits.StartStop',
'action.devices.traits.RunCycle',
],
name: {
defaultNames: ['My Washer'],
name: 'Washer',
nicknames: ['Washer'],
},
deviceInfo: {
manufacturer: 'Acme Co',
model: 'acme-washer',
hwVersion: '1.0',
swVersion: '1.0.1',
},
willReportState: true,
attributes: {
pausable: true,
},
}],
},
};
});
部署至 Firebase
使用 Firebase CLI 部署更新後的 Cloud 執行要求:
firebase deploy --only functions
連結 Google 助理
如要測試智慧型住宅動作,你必須將專案連結至 Google 帳戶。如此一來,就能透過已登入相同帳戶的 Google 助理介面和 Google Home 應用程式進行測試。
- 在手機上開啟 Google 助理設定。請注意,你登入的帳戶必須與控制台中使用的帳戶相同。
- 瀏覽至 Google 助理 >「設定」應用程式 >居家控制系統 (位於 Google 助理下方)。
- 按一下右上方的搜尋圖示。
- 使用 [test] 前置字串搜尋您的測試應用程式,
- 選取該項目。接著,Google 助理會使用您的服務進行驗證並傳送
SYNC
要求,要求您的服務為使用者提供裝置清單。
開啟 Google Home 應用程式,並確認可以看見洗衣機。
5. 處理指令和查詢
雲端服務現在已可正確回報洗衣機裝置給 Google,您需要新增要求裝置狀態及傳送指令的功能。
處理 QUERY 意圖
QUERY
意圖包含一組裝置。您應該針對每部裝置回應目前的狀態。
在 functions/index.js
中編輯 QUERY
處理常式,以處理意圖要求中包含的目標裝置清單。
index.js
app.onQuery(async (body) => {
const {requestId} = body;
const payload = {
devices: {},
};
const queryPromises = [];
const intent = body.inputs[0];
for (const device of intent.payload.devices) {
const deviceId = device.id;
queryPromises.push(queryDevice(deviceId)
.then((data) => {
// Add response to device payload
payload.devices[deviceId] = data;
}
));
}
// Wait for all promises to resolve
await Promise.all(queryPromises);
return {
requestId: requestId,
payload: payload,
};
});
針對要求中的每部裝置,傳回儲存在即時資料庫中的目前狀態。更新 queryFirebase
和 queryDevice
函式,傳回洗衣機的狀態資料。
index.js
const queryFirebase = async (deviceId) => {
const snapshot = await firebaseRef.child(deviceId).once('value');
const snapshotVal = snapshot.val();
return {
on: snapshotVal.OnOff.on,
isPaused: snapshotVal.StartStop.isPaused,
isRunning: snapshotVal.StartStop.isRunning,
};
};
const queryDevice = async (deviceId) => {
const data = await queryFirebase(deviceId);
return {
on: data.on,
isPaused: data.isPaused,
isRunning: data.isRunning,
currentRunCycle: [{
currentCycle: 'rinse',
nextCycle: 'spin',
lang: 'en',
}],
currentTotalRemainingTime: 1212,
currentCycleRemainingTime: 301,
};
};
處理執行意圖
EXECUTE
意圖會處理更新裝置狀態的指令。回應會傳回每個指令的狀態 (例如 SUCCESS
、ERROR
或 PENDING
),以及新的裝置狀態。
在 functions/index.js
中編輯 EXECUTE
處理常式,處理需要更新的特徵清單,以及每個指令的目標裝置組合:
index.js
app.onExecute(async (body) => {
const {requestId} = body;
// Execution results are grouped by status
const result = {
ids: [],
status: 'SUCCESS',
states: {
online: true,
},
};
const executePromises = [];
const intent = body.inputs[0];
for (const command of intent.payload.commands) {
for (const device of command.devices) {
for (const execution of command.execution) {
executePromises.push(
updateDevice(execution, device.id)
.then((data) => {
result.ids.push(device.id);
Object.assign(result.states, data);
})
.catch(() => functions.logger.error('EXECUTE', device.id)));
}
}
}
await Promise.all(executePromises);
return {
requestId: requestId,
payload: {
commands: [result],
},
};
});
在每個指令和目標裝置中,更新與要求特徵對應的即時資料庫值。修改 updateDevice
函式以更新適當的 Firebase 參照,並傳回更新後的裝置狀態。
index.js
const updateDevice = async (execution, deviceId) => {
const {params, command} = execution;
let state; let ref;
switch (command) {
case 'action.devices.commands.OnOff':
state = {on: params.on};
ref = firebaseRef.child(deviceId).child('OnOff');
break;
case 'action.devices.commands.StartStop':
state = {isRunning: params.start};
ref = firebaseRef.child(deviceId).child('StartStop');
break;
case 'action.devices.commands.PauseUnpause':
state = {isPaused: params.pause};
ref = firebaseRef.child(deviceId).child('StartStop');
break;
}
return ref.update(state)
.then(() => state);
};
6. 測試動作
實作所有三個意圖後,您可以測試動作是否控制洗衣機。
部署至 Firebase
使用 Firebase CLI 部署更新後的 Cloud 執行要求:
firebase deploy --only functions
測試洗衣機
現在你可以透過手機使用下列任何語音指令,看看數值的變化:
「Ok Google,打開洗衣機。」
「Ok Google,暫停洗衣機。」
「Ok Google,停止洗衣機。」
你也可以提問,查看洗衣機目前的狀態。
「Ok Google,我的洗衣機已經打開了嗎?」
「Ok Google,我的洗衣機正在跑嗎?」
「Ok Google,洗衣機目前在哪個週期?」
您可以前往 Firebase 控制台的「函式」部分,在函式下方的記錄中查看這些查詢和指令。如要進一步瞭解 Firebase 記錄檔,請參閱「寫入及查看記錄」。
您也可以在 Google Cloud 控制台中依序前往「記錄」 > 查看這些查詢和指令記錄檔探索工具:如要進一步瞭解 Google Cloud Logging,請參閱「透過 Cloud Logging 存取事件記錄檔」一文。
7. 向 Google 回報更新內容
您已全面整合雲端服務與智慧型住宅意圖,讓使用者控制及查詢裝置目前的狀態。然而,實作程序還是無法讓服務主動將活動資訊 (例如裝置在家狀態或狀態變更) 主動傳送給 Google 助理。
使用要求同步處理功能時,當使用者新增或移除裝置,或是裝置功能有所變更時,您可以觸發新的同步處理要求。有了「回報狀態」功能,當使用者實際變更裝置狀態 (例如開燈或使用其他服務變更狀態) 時,雲端服務就能主動將裝置的狀態傳送到 Home Graph。
在本節中,您將新增程式碼,從前端網頁應用程式呼叫這些方法。
啟用 HomeGraph API
HomeGraph API 可以在使用者 Home Graph 中儲存和查詢裝置及其狀態。如要使用這個 API,請先開啟 Google Cloud 控制台,並啟用 HomeGraph API。
在 Google Cloud 控制台中,請務必選取與您的動作相符的專案 <project-id>.
,然後在 HomeGraph API 的 API 程式庫畫面中按一下「啟用」。
啟用報告狀態
寫入即時資料庫,用於觸發範例專案中的 reportstate
函式。更新 functions/index.js
中的 reportstate
函式,擷取寫入資料庫的資料,並透過「報告狀態」發布至 Home 圖表。
index.js
exports.reportstate = functions.database.ref('{deviceId}').onWrite(
async (change, context) => {
functions.logger.info('Firebase write event triggered Report State');
const snapshot = change.after.val();
const requestBody = {
requestId: 'ff36a3cc', /* Any unique ID */
agentUserId: USER_ID,
payload: {
devices: {
states: {
/* Report the current state of our washer */
[context.params.deviceId]: {
on: snapshot.OnOff.on,
isPaused: snapshot.StartStop.isPaused,
isRunning: snapshot.StartStop.isRunning,
},
},
},
},
};
const res = await homegraph.devices.reportStateAndNotification({
requestBody,
});
functions.logger.info('Report state response:', res.status, res.data);
});
啟用「要求同步處理」功能
在前端網頁 UI 中重新整理圖示,即可觸發範例專案中的 requestsync
函式。在 functions/index.js
中實作 requestsync
函式來呼叫 HomeGraph API。
index.js
exports.requestsync = functions.https.onRequest(async (request, response) => {
response.set('Access-Control-Allow-Origin', '*');
functions.logger.info(`Request SYNC for user ${USER_ID}`);
try {
const res = await homegraph.devices.requestSync({
requestBody: {
agentUserId: USER_ID,
},
});
functions.logger.info('Request sync response:', res.status, res.data);
response.json(res.data);
} catch (err) {
functions.logger.error(err);
response.status(500).send(`Error requesting sync: ${err}`);
}
});
部署至 Firebase
使用 Firebase CLI 部署更新後的程式碼:
firebase deploy --only functions
測試實作成果
在網頁版 UI 中按一下「重新整理」 按鈕 ,確認 Firebase 控制台記錄中出現同步處理要求。
接著,在前端網頁 UI 中調整洗衣機裝置的屬性,然後按一下「更新」。確認您可以在 Firebase 控制台記錄中看到向 Google 回報的狀態異動。
8. 恭喜
恭喜!您已成功透過智慧住宅動作,將 Google 助理與裝置雲端服務整合。
瞭解詳情
您可以採行下列建議來深入探討:
您也可以進一步瞭解如何測試並提交動作送審,包括向使用者發布動作應用程式的認證程序。