Roborock Vacuum：把掃地機器人放進 Apple「家庭」App

Roborock 掃地機器人平常都在 Roborock App 裡操作。如果家裡其他設備已經放進 Apple「家庭」App，你大概也會希望掃地機器人加入它們：用 Siri 叫它開始打掃、出門時讓自動化啟動它、順手看一眼電量。Roborock Vacuum 是我維護的 Homebridge 外掛，透過 HomeKit 或 Matter 把 Roborock 掃地機器人放進「家庭」App；控制指令走家裡的網路，就算 Roborock 雲端斷線，也能繼續控制。

雲端斷線，照樣能用

Homebridge 負責把裝置橋接進「家庭」App，這個外掛負責和 Roborock 掃地機器人溝通。外掛只在兩件事上需要 Roborock 雲端：登入你的 Roborock 帳號，以及讀取帳號裡的裝置清單。取得裝置清單和每台掃地機器人的本機金鑰之後，開始、停止、回充這些控制指令，都會經由家裡的網路直接送到掃地機器人。

控制指令走家裡的網路；Roborock 雲端只在登入和讀取裝置清單時需要。

每次成功從雲端更新後，外掛會把裝置清單、本機金鑰和每台掃地機器人最後已知的區網位址存在 Homebridge 主機上（只有擁有者能讀取）。如果 Homebridge 啟動時連不上 Roborock 雲端，外掛就用這份儲存的資料以僅限本機（local-only）的模式啟動：掃地機器人照樣出現在「家庭」App，開始、停止、回充都照常運作。外掛會先用 UDP 探索尋找掃地機器人；如果找不到，例如掃地機器人在另一個 VLAN，就直接連線到儲存的位址。

場景、即時狀態推送這類只有雲端才能提供的功能，在斷線期間會暫時無法使用。外掛會在背景持續重試，雲端恢復後這些功能會自己回來，不需要重新啟動 Homebridge。

有兩點要注意：外掛需要先成功連線啟動過一次，才會儲存裝置清單，所以全新安裝無法在離線狀態下啟動；另外，從其他 Roborock 帳號分享給你的掃地機器人，只能透過雲端控制。

在「家庭」App 裡能做什麼

每台掃地機器人都會帶著它實際具備的控制項和資訊出現；基座洗拖布、耗材這些額外功能會不會出現，取決於機型回報了什麼。

開始、停止、送回充電座：透過 HomeKit 時，掃地機器人以風扇樣式的方塊出現，打開就開始打掃，關閉就停止並返回充電座。Siri、場景和自動化都能用。
電量、充電與錯誤：電量、充電狀態和低電量警告；掃地機器人回報錯誤或離線時，會被標示出來。
你的 Roborock 場景：在 Roborock App 建立、有用到這台掃地機器人的已啟用場景，都會變成開關，點一下或用自動化就能跑完整套流程。
基座洗拖布：基座能清洗拖布的機型會多一個開關，可以開始或停止清洗。不論清洗是從 Roborock App 啟動、還是打掃途中自動進行，只要基座正在洗，開關就會顯示為開啟。
濾網與刷子：透過 HomeKit 時，顯示濾網、主刷和邊刷的剩餘壽命，剩下 5% 以下會提醒你更換。
目前房間送到 MQTT（選用）：把正在打掃的房間發佈到你的 MQTT broker，例如讓燈光跟著掃地機器人一間一間走。這只是遙測資料，不會出現在「家庭」App，預設關閉。

清除排除後仍不消失的錯誤

有些錯誤在原因排除之後，仍會留在掃地機器人上，直到你在 Roborock App 把它標記為已解決。典型的例子是清水箱補滿水後，基座還在回報缺水；這段期間「家庭」App 也會一直顯示故障。外掛設定頁會在裝置清單裡列出錯誤代碼和簡短說明，按下 Clear error 就能清除，效果和在 Roborock App 標記已解決一樣。清除前請先排除原因，否則錯誤還會回來；這個操作也需要 Homebridge 正在執行。

HomeKit 還是 Matter，每台分別選

在外掛設定頁按下 Load devices，帳號裡的每台掃地機器人都可以三選一：HomeKit (HAP)、Matter (Beta) 或略過。

示意圖：同一台掃地機器人，透過 HomeKit 是風扇樣式的方塊，透過 Matter 則是原生的掃地機器人配件。

HomeKit 是預設選項，穩定、熟悉，掃地機器人以風扇樣式的方塊出現，濾網與刷子的壽命也只在 HomeKit 下提供。選擇 Matter，Apple「家庭」就會把它顯示成掃地機器人而不是風扇：有原生的圖示和控制項，可以挑選要打掃的房間（不選或全選就是打掃全屋），在吸塵、拖地、兩者並行之間切換，也能送它回充電座；分房打掃時，App 會顯示目前正在打掃哪一間。Google Home、Alexa 和 SmartThings 也能使用 Matter 版本。略過則是讓這台不出現在「家庭」App，例如別人家分享給你的掃地機器人。

在 Matter 下有一點和 HomeKit 不同：把運轉模式切到閒置，掃地機器人會原地停下，不會自己回去；要它回充電座，請用回充（Go Home）的控制項。

Matter 目前是 Beta。Apple「家庭」對 Matter 掃地機器人的支援還很新，想要最穩定的體驗，請繼續使用 HomeKit。選擇 Matter 之前，請先知道這幾件事：

需要開啟 Matter 的 Homebridge 2。在 Homebridge 1.x 或沒開 Matter 時，外掛會退回 HomeKit，並在記錄裡留下警告。
配對時會出現「未經認證的配件」警告，名稱也會是通用的「Matter Accessory」，要自己輸入名稱；設定頁的配對面板會顯示該輸入什麼。
分房清掃需要 iOS 18.4 以上，房間也必須先在 Roborock App 裡命名。
多樓層地圖、區域清掃和耗材資訊，目前還不能透過 Matter 使用。
iOS 更新後，配件偶爾會顯示沒有回應或少了某些功能。
把掃地機器人改成另一種協定時，配件會重新建立，之後要重新設定它的房間和自動化。

改用 Matter 的步驟

開啟 Matter：外掛以子橋接器執行時（透過 Homebridge UI 設定時的預設），在外掛設定頁勾選 Enable Matter on this plugin's child bridge；如果在主橋接器上執行，則在 config.json 的 bridge 區塊加上 "matter": true。接著重新啟動 Homebridge。
選擇協定：按 Load devices，把這台的選單設成 Matter (Beta)，再重新啟動一次。
配對：重新打開設定頁，每台選了 Matter 的掃地機器人下方會出現配對面板，有 QR code 和手動配對碼，每台各有一組。在「家庭」App 加入配件，掃描 QR code 即可。
場景按鈕（選用）：Matter 下的場景按鈕和洗拖布開關，放在外掛自己的 Matter 橋接器上，需要另外配對：捲到設定頁裝置清單最下方，掃描那裡的橋接器 QR code。

安裝與設定

你需要一台已經加入 Roborock App 的掃地機器人和那個 Roborock 帳號的 email，以及 Homebridge 1.6 以上，搭配 Node.js 18.20、20.15、22 或 24。

三個步驟：安裝外掛、登入 Roborock 帳號、為每台選擇協定後重新啟動。

安裝外掛：在 Homebridge UI 打開「外掛」，搜尋 Roborock Vacuum，安裝 homebridge-roborock-vacuum。
登入：在外掛設定頁輸入 Roborock App 的 email。可以輸入密碼後按 Password Login；也可以按 Send 2FA Email，把 email 收到的驗證碼填進去再按 Verify Code，帳號要求兩步驟驗證時也是用這個方式完成登入。Region 維持 Auto detect 即可，除非自動偵測選錯了伺服器。設定頁會儲存加密過的工作階段權杖，Homebridge 重新啟動後不必再登入。
選擇並重新啟動：按 Load devices 列出帳號裡的掃地機器人，為每台選擇 HomeKit (HAP)、Matter (Beta) 或略過，然後重新啟動 Homebridge。

沒有使用 Homebridge UI 的話，在 Homebridge 所在的環境用 npm 安裝：

npm install -g homebridge-roborock-vacuum

設定頁還有一個 Language 選項，決定外掛新增的開關和感應器用哪種語言命名，支援繁體中文在內的 12 種語言。更改語言只會在下次重新啟動時改名，不必重新配對，也不用重新設定房間。

支援的機型

用你在 Roborock App 使用的帳號登入，外掛會自動找到帳號裡的掃地機器人，不用自己查裝置 ID 或 IP 位址。以下機型已確認可用：S4、S4 Max、S5 Max、S6、S6 Pure、S6 MaxV、S7、S7 MaxV (Ultra)、S7 Pro Ultra、S7 Max Ultra、S8、S8 Pro Ultra、Q5+、Q5 Pro、Q7、Q7 Max、Q8 Max、Qrevo、Qrevo Pro、Qrevo S、Qrevo Curv、Saros 10。Roborock App 裡的其他機型大多也能使用。

只在米家 App 裡？外掛看得到的是你 Roborock 帳號裡的掃地機器人。只在米家（Xiaomi Home）App 設定的掃地機器人不在這個帳號裡，所以不會出現。

這個外掛以 copystring 的 ioBroker.roborock 為基礎改寫，採用 MIT 授權釋出。