非常久以前我曾經寫過一篇教學，從安裝 Hassbian 到串接語音助理的教學，由於那篇串接語音助理的部分很粗略，所以寫了這篇新版 "詳細的" 教學https://www.dcard.tw/f/3c/p/228685493
不管是 Google 的語音助理或是 Siri，在以上那篇文章中提供的方法已經都不適用了，在現在的版本中，兩個語音助理的串接都變得更簡單了
在本篇教學中前 3/5 都會是 Google Assistant 的內容，因為 Siri 的部分太過於簡單，所以佔的比重非常少，比較多的是官方的問題排除方法，我一併翻譯了

開始進入主題吧

在 HA 中，如果想串接 GA，你有兩個選擇，付費與免費
HA 現在背後的贊助商為 Nabu Casa，藉由每個月 5 美金訂閱 Nabu Casa 所提供的伺服器 Home Assistant Cloud，可以免費試用一個月，你可以省去下面一堆設定
想要免費的? 就付出點勞力吧XD
免費版本的跟付費版本的功能完全一樣，但是你必須有以下的條件
1. 有自己的網域，或者是申請 DuckDNS 子網域且要 SSL 加密
2. 外網能直接與你的 HA 溝通，也就是外網通訊埠 8123 與內網通訊埠 8123 要能直接綁定

第 1 點本篇教學有，但第 2 點需要自己衡量自家的網路環境，像是有人住宿舍，房東自己弄了一個路由器然後分派 IP 下來給各住戶，你又弄了一個路由器給 HA 連，這時從外網連進來第一關會是房東的路由器，然後就死在這裡了，他沒辦法跟第二層的路由器溝通更不可能連到你的 HA
社區大樓也有可能會有這種問題，但若是你住大樓又是獨立牽自家網路線的話就不會有這問題
群組裡也有人提出，如果網路因某些原因無法對外的話，可以用 VPS + ssh tunnel 解決

接下來 DuckDNS 的教學會拆成兩種，一種是 Hassbian 的安裝法，另一種是 Hass.io 的安裝法
不管是哪種都必須先到 https://www.duckdns.org/ 註冊帳戶 ，註冊完成後新增你的 DuckDNS 子網域
在上方紅框位置有你個人的 token，等等會用到所以網頁先不用關
我們假設子網域為123456.duckdns.org，在本篇的教學中只要看到123456，就把他代換成自己的子網域
我們先來講 Hassbian
選擇使用 Hassbian 的人應該都知道 SSH 了，安裝 DuckDNS 必須 SSH 進入 Hassbian 中下指令安裝，只有以下一行指令
sudo hassbian-config install duckdns
接下來會開始引導你安裝 DuckDNS，途中會要求你輸入你剛剛設定的 DuckDNS 子網域以及 token，安裝完後必須在 configuration.yaml 中 http: 底下新增三行
ssl_certificate: /home/homeassistant/dehydrated/certs/123456.duckdns.org/fullchain.pem
ssl_key: /home/homeassistant/dehydrated/certs/123456.duckdns.org/privkey.pem
base_url: 123456.duckdns.org:8123
新增那三行後重啟 HA，之後你會發現你用原本的 http://192.168.x.x:8123 或是 http://123456.duckdns.org:8123 都無法進入系統了
這是因為 HA 已改為 SSL 加密，所以網址必須用 https://...... 為開頭
Hassbian 就到這裡，接下來是 Hass.io

Hass.io 的定位在讓新手也能快速上手 HA，所以很多東西都可以在介面上完成不會讓你打指令，而且也沒有指令讓你打

在側邊攔點選 Hass.io
點選 ADD-ON STORE
往下找到 Duck DNS 並點選他
點選 INSTALL
1. 將 accept_term 的 false 改為 true
2. 填入 token (要雙引號)
3. 填入子網域 (要雙引號)
4. SAVE
儲存後就可以點選 START 了
這時你的 HA 就可以透過 https://123456.duckdns.org 進入系統Hass.io 的部分結束，接下來才要開始設定 GA

首先點擊下面網址 https://console.cloud.google.com/apis/api/homegraph.googleapis.com/overview如果你是第一次進入 Google Cloud Platform，你必須勾選同意服務條款、選定國家才能繼續使用
"選取專案"
"新增專案"
1. 填入專案名稱，這裡隨你高興填英數字
2. "建立"
成功建立專案後點擊 "API 和服務"
"＋啟用 API 和服務"
在搜尋框中打入 Homegraph
點選唯一一個搜尋結果
"啟用"
成功啟用 HomeGraph API 後點擊 "建立憑證"
點擊 "憑證"
"建立憑證"
下拉選單選取 "API金鑰"
按下複製圖示將 API 金鑰複製起來貼到任何地方，最後會用到，然後就可關閉對話框了，網頁也可關掉
再來點擊下面網址進入 Actions on Google consolehttps://console.actions.google.com/接下來的網頁就沒有中文了

"New Project"
1. Yes
2. Taiwan
3. No
4. No
5. Agree and continue
點選輸入框即會顯示你剛剛在 Google Cloud Console 上新建的專案，點擊那個專案
"Import project"
選取 "Smart Home"
選取 "Smart home"
點選 Name your Smart Home action
將你的服務命名，這步驟可做也可以不做，如果不過的話頂多就是在最後串接服務時名稱會顯示 [test] my test app，不會造成功能上的影響
命名之後點 SAVE，再點選側邊欄的 Actions
1. 在 Fulfillment 中填入https://123456.duckdns.org:8123/api/google_assistant2. SAVE
點選側邊攔 Account linking 後點選 Next
點選 Linking type 下拉選單
分別選擇 OAuth 與 Authorization Code，再點選 Next
由上至下
1. 填入 https://oauth-redirect.googleusercontent.com/，最後的 / 很重要不要忽略他
2. 填入任何字串
3. 填入 https://123456.duckdns.org:8123/auth/authorize4. 填入 https://123456.duckdns.org:8123/auth/token5. Next
1. Scopes 中輸入你的 email
2. Add scope
3. 再輸入你的名字
4. 再按一次 Add scope
5. Next
Testing instructions 隨便輸入然後按 Save
完成儲存後按下 Test 生成測試草稿
在生成測試草稿時，網頁會要求你的位置權限
如果你的帳號沒有開啟 "網路和應用程式活動" 的權限的話，必須點擊 Visit Activity controls 將此權限打開
進入測試程序後點擊右上方三點點選單
點選 Project settings
複製 Project ID 貼到記事本中後面會用到，這時你的記事本已經記錄兩組值了，另一組是 API 金鑰
做完以上步驟後可以說已經快完成了，接下來要驗證你建立的服務是否可以跟 HA 相通

在手機上的 Google app→Settings→Google Assistant→Home control
點選＋，然後尋找 [test] 開頭的項目，如果你剛剛沒有改服務名的話預設就是 my test app，點選他就會進到 Home Assistant 的登入畫面了，如果沒有順利進入登入畫面，你可能需要往回檢查你剛剛的那一堆網址有沒有填錯
然而你這時輸入帳號密碼後可以登入成功，但是會沒有任何事發生，因為你還沒有在 HA 中新增 Google Assistant 的整合元件

在 configuration.yaml 底下新增以下幾行
project_id 填入記事本中的 Project ID
api_key 填入記事本中的 API 金鑰
基本上只要新增了這三行並重啟 HA 後，對 GA 說 "Sync my device"，HA 上所有在支援裝置內的項目都會在 Google app→Settings→Google Assistant→Home control 中出現，如果沒有的話可以再點選＋，然後點選 [test] 開頭的服務再登入一次

好了，裝置是都整合到 GA 裡了沒錯，剛剛加入 configuration.yaml 中的那三行只是能讓 GA 運作的最基礎設定，我接下來要做細部調整，不然會碰到以下各種問題...
1. Google 會開始要求你將每一個裝置都分派到所屬區域中，要一個一個慢慢點很麻煩
2. 怎麼 GA 上好像沒有看到某某裝置
2. 裝置名稱會預設帶入 HA 上的名稱，雖然可以直接改，但要一個一個慢慢改很麻煩
3. 有些裝置我不要讓他出現在 GA 中，怎麼辦

首先，只有以下種類的裝置和支援模式可以拋過去給 GA 使用
．燈　　　 light (開、關、亮度、色彩、色溫)
．鎖　　　 lock (上鎖、解鎖)
．群組　　 group (開、關)
．場景　　 scene (僅支援開)
．腳本　　 script (僅支援開)
．風扇　　 fan (開、關、調速)
．窗簾　　 cover (開、關、設定位置)
．空調　　 climate (溫度控制、空調模式)
．攝影機　 camera (僅支援串流功能)
．布林值　 input_boolean (開、關)
．播放器　 media_player (開、關、音量、輸入源)
．掃地機　 vacuum (回充、開始、停止、暫停)
．感應器　 sensor (僅支援溫度感應器)
．開關插座 switch (開、關)

接下來我們要來設定什麼裝置要拋到 GA 或什麼裝置不要拋到 GA
HA 這邊的參數分成兩種
1. 預設全都拋，expose_by_default 為 true當 expose_by_default 為 true 時，你可以透過 exposed_domains 來設定只要拋哪一種類的裝置，你可以全都列上去因為是全都拋過去了，但總是有一兩個裝置或自動化你不想讓它出現在 GA 中，這時必須透過 entity_config 的 expose 一個一個設定這項目要拋 (true) 或不拋 (false)
2. 預設都不拋，我一個一個放行 expose_by_default 為 false因為是要一個一個放行，所以不用再設定要拋什麼種類的裝置，直接告訴 HA 要拋什麼裝置，這邊 entity_config 的 expose 只會出現 true，因為根本不用考慮 false 的情況
兩種拋的方法比較一下，我個人喜歡一一放行的方案，因為全都拋過去後需要告訴 HA 我有很多自動化以及腳本不想出現在 GA 中

最後，我們要來幫拋到 GA 上的裝置命名與指定區域，不然一個一個在 Google app 裡面設定也太心累
name: 為該裝置在 GA 顯示的名稱
aliases: 為該裝置的別名
room: 為該裝置所在的區域
可以使用中文命名，但是對於現在 Google Home 還未開放中文前，不建議 name 跟 aliases 都設中文，至少有一個要是英文，這樣就算以後開放中文了，中英都可控制裝置
針對鎖的裝置還有一個特別的參數，GA 預設情況下不能幫你解鎖門，你需要提供解鎖碼 secure_devices_pin: 給 HA 讓 GA 用

名稱跟區域都搞定了，重啟 HA 後對 GA 說 "Sync my devices"，在 Home control 中的所有裝置都會重新整理
如果在最一開始沒有取得 api_key 的話是不能直接叫 GA 重整裝置的
好了 GA 的整合已經全都完成了

接下來是 Siri 的部分，這部分會很簡單

GA 本身既是語音助理也是智慧家庭的平台，而 Siri 只是語音助理，其取用的是 HomeKit 這個智慧家庭的平台，所以我們要整合的其實並不是 Siri 而是 HomeKit
在我先前的教學文中我用的是 Hassbian 的 HomeBridge 套件，但這個已經被終止開發跟維護了
從 0.64 後 HA 就直接整合了 HomeKit，可以讓 HA 的裝置直接拋過去給 iOS 的家庭 app 使用
我們開始教學吧~

在 configuration.yaml 底下新增一行 homekit:，好了，大功告成，沒有其他的了XD
接下來儲存後重開 HA，你會在通知欄中看到 HomeKit 的配對碼卡片
打開 iOS 的家庭 app → 加入配件
尋找 Home Assistant Bridge 並強制加入→手動輸入代碼
輸入 HA 上的配對碼
配對成功後會開始設定裝置的名稱與位置
跟 GA 一樣，只新增一行 homekit 只是完成最基礎的設定，接下來要設定 filter 來決定什麼東西要不要拋到 HomeKit，你有以下 4 種參數可用
．包含種類 include_domains
．包含物件 include_entities
．排除種類 exclude_domains
．排除物件 exclude_entities
規則如下：(種類=domain，物件=entity)
1. 沒有設定 filter 就是物件全拋到 HomeKit
2. 有設定 include 沒有設定 exclude：只會拋有 include 的物件
3. 有設定 exclude 沒有設定 include：除了 exclude 的物件之外都拋
4. include 跟 exclude 皆有設定：
．設定了包含種類 include_domains
　。當種類被 include，物件沒有被 exclude，則拋該物件
　。當種類沒有被 include，物件也沒有被 include，則不拋該物件
．設定了排除種類 exclude_domains
　。當種類被 exclude，物件沒有被 exclude，則不拋該物件
　。當種類沒有被 exclude，物件也沒有被 include，則拋該物件
　。當種類被同時 include 和 exclude，種類 exclude 會被系統忽略
．皆沒有設定包含種類和排除種類
　。當物件被 include，則拋該物件，等同於第 2 點
　。當物件被同時 include 和 exclude，物件的 exclude 會被系統忽略

以上規則清楚後，再來看有什麼種類 (domain) 的裝置 (entity) 可以拋到 HomeKit
燈　　　 light (開、關、亮度、色彩)
鎖　　　 lock (上鎖、解鎖)
場景　　 scene (以開關呈現)
腳本　　 script (以開關呈現)
空調　　 climate (所有 HA 上的空調)
窗簾　　 cover (開、關、停止、設定位置)
人物　　 person (存在)
風扇　　 fan (開、關、風速、方向擺動)
自動化　 automation (以開關呈現)
布林值　 input_boolean (以開關呈現)
遙控器　 remote (以開關呈現)
車庫門　 cover (開、關)
追蹤器　 device_tracker (存在)
播放器　 media_player (開、關、音量、播放、中止、暫停、模式)
感應器　 sensor (亮度、溫溼度、空氣品質、一氧化碳、二氧化碳)
二元開關 binary_sensor (氣體、煙霧、門窗開關、動作、存在)
保全控制 alarm_control_panel (所有 HA 上的保全系統)
開關插座 switch (開、關)
電熱水器 water_heater (所有 HA 上的電熱水器)

知道了 include、exclude 以及所有的 domain 後就來設定 filter 吧
以我下圖的範例就是只拋保全控制以及燈這兩種類的裝置，但是燈這個種類中我要排除 kitchen_light
設定了如何包含、排除種類與裝置，接下來幫裝置命名，省去在家庭 app 打字的麻煩
跟 GA 一樣都是透過 entity_config
HomeKit 不像 GA 可以在 HA 中就設定裝置的位置，但除了 name 的參數之外，HomeKit 還提供了許多 GA 沒有的參數
．linked_battery_sensor 電量參考裝置，可以將電量感應器連結到該裝置作為他的電量參考
．low_battery_threshold 低電量臨界值，可以設定最低臨界值，在裝置提醒你低電量前就通知你，預設為20%
．code 給保全裝置、鎖使用的，用來警戒/解除警戒或者解鎖門用
．feature_list 給播放器的裝置使用，可以設定該播放器有什麼功能，只有四種
．type 給開關種類的裝置使用，有以下六種 type
1. 閥　　　 valve
2. 插座　　 outlet
3. 開關　　 switch
4. 灑水器　 sprinkler
5. 水龍頭　 faucet
6. 淋浴開關 shower
全部設定好後儲存重開 HA，重啟 HA 後將 iOS 的家庭 app 關閉並從後台移除，再開起家庭 app，全部裝置將會重新整理

OK，全都弄好了，現在來講一下注意事項，非常重要!!!
1. 對於 HomeKit 來說，這個 Home Assistant Bridge 是一個 Hub，所有呈現在家庭 app 裡的裝置都是 Home Assistant Bridge 的子裝置
由於 HomeKit 先天上的限制，一個 Hub 上最多只能有 100 個子裝置，所以如果你 HA 上的裝置超過 100 個，然後接入 HomeKit 又沒有設定 include 或 exclude 來篩選要拋的裝置，會造成無法設定 Home Assistant Bridge 到家庭 app 中

2. 當你要將 HA 移到新的環境時，除了複製設定檔外，.homekit.state 這個隱藏檔也要跟著複製到新環境
3. 建議不要使用 HomeKit 的 auto_start，改用自動化的方式來啟動 HomeKit
auto_start 參數須為 false
HomeKit 整合部分可能會遇上不少問題，也可能很順利，官方有提出一些問題以及解決辦法
1. 當遇上輸入了配對碼卻無法配對 HA Bridge 時，請先停止 HA 後刪除 .homekit.state 檔

2. 如果 HA 沒有出現配對碼通知，表示你有可能已經配對過了，如果沒有配對過，請參照第1點刪除 .homekit.state 檔

3. HA Bridge 沒有在家庭 app 中出現，這通常是網路問題，請檢查路由器設定或者是改通訊埠號，要注意 iOS 裝置在與 HA Bridge 配對時需要在同個網段下

4. 在 Docker 環境下 HA Bridge 沒有在家庭 app 中出現，請新增一個參數
network_mode: host
5. 在 VirtualBox 環境下 HA Bridge 沒有在家庭 app 中出現，請新增一個參數
network_mode: networkbridge
6. 配對都會失敗，且出現 NonUniqueNameException 訊息，請新增一個參數並重啟 HA
safe_mode: true重啟 HA 後若是沒有看到配對碼，請參照第1點刪除 .homekit.state 檔
為了避免後續有任何錯誤，如果已經能正常配對、加入裝置，請把 safe_mode: true 參數刪除

7. 配對無限等待中，或者只有在 debug 模式下能配對，如果沒有出現錯誤只是一直卡在配對中，請確保子裝置沒有超過100個
檢查 Log，並搜尋 "Starting accessory Home Assistant Bridge on address"，確保 HA Bridge 掛接在正確的介面上，如果沒有正確掛接，請新增一個參數
ip_address: 192.168.X.X (根據你的 HA 位置)
8. 當有重複的 AID 時會發生錯誤，所以請確保 HA 上的裝置的 entity_id 都不可重複

9. 在正常情況下我的 Z-Wave 裝置或自動偵測的裝置沒有顯示，請停用 auto_start 改用自動化來啟動 HomeKit
10. 有些裝置沒有出現，請確定該裝置的種類 (domain) 是否為 HomeKit 所支援，如果有設定 include_entities 的話，請確認拼字有無錯誤

11. 當你區網上有第二個 HA 要接入 HomeKit，你必須將第二個 HA 給改名，否則會無法加入 HomeKit
12. 某些特定裝置沒有作用，雖然我們已經盡力在整合 HomeKit，但也些裝置尚未整合到 HomeKit 中，這可能會導致配對失敗，或者是配對成功後全部裝置都無法使用。請使用 filter 來排除是哪個裝置出了問題，建議一個一個裝置新增比較容易找出問題，也請回報給官方

13. 裝置皆顯示無回應，請看第12點

14. 裝置在更新 HA 後或者重啟 HA 後無回應，請注意子裝置上限 100 個

15. 裝置偶爾會無回應，很不幸的，這時常會發生，關閉家庭 app 後過幾分鐘應該會解決問題

16. linked_battery_sensor 無作用，請移除該裝置再重新加入，如果你是在既有豬帳上加入 linked_battery_sensor 參數，除非你刪除後重新加入裝置，不然變更不會生效

17. 播放器類別的裝置沒有正確顯示為電視，在 iOS 12.2 以及 macOS 10.14.4 之後只要 device_class 為 tv 的裝置都會自動判別並顯示成電視設備。請移除該裝置並重新加入，尤其是先前播放器類別的裝置加入後被判別成一系列的開關。如果你有新增/移除功能 (feature_list)，你也必須移除並重新加入裝置

18. 無法控制播放器媒體音量，播放開始/暫停與音量皆會顯示在遙控 app 中，或者是控制中心中。如果你的電視支援在 HA 中調整音量，你可以在裝置上顯示該遙控器時使用側邊的音量鍵來控制音量

19. 以往要重製裝置時你必須移除再重新加入，在 0.97 的版本後你可以用
homekit.reset_accessory 這個服務來重製裝置，舉例來說，當你把播放器的 device_class 改為 tv 後、連結電量參考值、或者是 HA 又新增了更多的可支援裝置時，你必須重製裝置，這時你就可以用這服務
不管是刪除後重新加入，或者是用 homekit.reset_accessory 服務，在家庭 app 中都是視為新加入子裝置，所以子裝置的名稱、群組、位置、場景、自動化都要重新設定

這次的教學文就到這裡，下一篇教學文打算寫如何用 LINE 控制智慧家電，與 GA 的最強外掛 Dialogflow，還有後續的 Google Nest Hub Max 開箱文