如何在Home Assistant的localTuya設定裝置的實體？ / How to Set Up Device Entities in LocalTuya on Home Assistant?
要在Home Assistant裡面使用localTuya，我們除了要取得裝置的local key之外，還需要自行設定裝置的實體在Home Assistant的控制方式。以下我們就用威技除溼機WDH-11FS為例子，來看看怎麽將UVC模式設定到Home Assistant上。
To use localTuya in Home Assistant, besides obtaining the device's local key, we also need to configure how the physical device is controlled within Home Assistant. Below, we'll use the NWT WDH-11FS dehumidifier as an example to demonstrate how to set up the UVC mode in Home Assistant.
前置作業 / Preliminary Work
這篇的操作我主要想講Entity的設定，不過我們還是有必要提一下在這之前的操作。
首先，我們必須確保你的Home Assistant有正確安裝localTyua，也就是LocalTuya integration。localTuya的保存庫有寫到如何安裝，最簡單的做法是用HACS。手動安裝的教學可以參考「LocalTuya Home Assistant 使用教程」這篇的做法。安裝完成後，啟動Home Assistant，在整合裡面就可以找到LocalTuya integration。
https://www.youtube.com/watch?v=Q1ZShFJDvE0
下一步是要取得裝置的local key。這個步驟需要先讓裝置連上手機的Tuya APP，讓Tuya IoT伺服器取得裝置的資訊。接著需要你註冊並登入Tuya的IoT開發者平臺：
然後經歷一連串的設定，你要找到裝置的device_id，最後就能在API Explorer > IoT Core > Device Management > Query Device Details in Bulk裡面，用device_id找到它的local_key。整個操作非常的複雜，而且Tuya不時會更動系統的操作邏輯。我看的每個教學細節都不太一樣，最後還是要靠自己摸索才能找到。
附帶一提，如果你的裝置有經過重置WIFI的話，local_key也會跟著改變。到時候記得要再回去Tuya IoT找尋改變後的local_key喔。
如果你要控制的WIFI裝置跟Home Assistant在同一個區域網路底下，localTuya應該能夠抓到你的WIFI裝置，然後你就可以進入設定。設定裡面的Device ID、Local key都是前面步驟中找到的關鍵資訊。
但如果你繼續設定，就會發現localTuya開始問你關於實體的設定方式。通常這時候我們就會不知道該怎麼進行設定了。
實體裝置跟虛擬的「實體」 / Physical Devices and Virtual "Entities"
這裡我們要先來說明Home Assistant裡面「實體」(entity)的概念。一臺真實的除溼機上面有很多按鈕，這包括了電源開關、除溼模式、風速、定時等等。這些每一個可控制的開關、每一個負責感應與記錄數值的感應器，它們在Home Assistant裡面都會對應成虛擬的「實體」(entity)。
一般來說，經過配置好的智慧家電，通常會自己能夠告知Home Assistant自己有哪些實體可以使用。而Home Assistant會自動把它加入到系統中，你就能夠直接控制。但在localTuya裡面，這些實體得要你自己手動設定才行。
手動設定，意味著你要瞭解這臺裝置它的以下資訊：
- ID，在Tuya裡面稱為「dp_id」，在localTuya裡面稱為「ID」。這是用來表示裝置上某個實體的代號。
- 用途，在Tuya裡面稱為「code」，localTuya裡面則是代表你設定的名稱「name」：這表示該代號的功能，例如「switch」表示電源開關。每個裝置自己的code都不一樣，需要各別去解讀。
- 類型，在Tuya裡面稱為「type」，在localTuye裡面就是Entity Type。這是用來呈現實體的表現形式。常用的type設定大概有這幾種：
- 它是開關的的話，Tuya會記錄成「bool」(boolean的簡稱)，在localTuya裡，可控制的實體要設定成「switch」，不可控制的感應器則設為「binary_sensor」。
- 記錄數值的感應器，Tuya會記錄成「value」，在localTuya則要設定成「sensor」。
- 多種選項中其中一種的選項，在Tyua會記錄成「enum」，在localTuya則要設定成「select」。
- 數值，在Tuya跟localTuya裡面都稱為「value」。這是用來表示現在該ID的狀態。
- 如果是開關類型的「switch」，大多value都是true或false。
- 感應器類型則會以數字表示。
- 多種選項的話通常會以字串記錄。
除了數值之外，ID、用途(名稱)、類型，這些都是我們要在localTuya裡面配置的參數。但我們不能光靠localTuya就知道裝置的細節，還是要上Tuya IoT網站查詢。
查詢裝置的屬性 / Query Properites of the Device
上述屬性我們要在API Explorer裡面查詢，也就是跟查詢local_key類似的位置。請按照以下步驟進入查詢：
- 進入Device Control。
- 進入Query Properties。
- 輸入device_id。
- 在Response取得結果。
我們來看一下部分Response的結果：
{
"result": {
"properties": [
{
"code": "switch",
"custom_name": "",
"dp_id": 1,
"time": 1737549561825,
"type": "bool",
"value": false
},
{
"code": "dehumidify_set_value",
"custom_name": "",
"dp_id": 2,
"time": 1733855769285,
"type": "value",
"value": 60
}
// 中間省略
}我們可以從這裡查到「dp_id」，也就是裝置各項控制或感應器的實體，例如1；然後再看到「code」，這表示實體的名稱，例如「switch」；然後我們要看看它的「type」，例如「bool」，這是boolean二元值的簡稱；最後關注到「value」，就是它實際的值。
其實我們光看code還是很難猜得到這個實體到底是什麼意思。這時候我們可以嘗試手動開關除溼機設備的各項控制器，再去觀察各個實體的變化。例如我把除溼機的開關給打開，然後再到Tuya IoT網站上去查詢。
此時dp_id為1，意思為switch的實體，數值變成了true。因此可以推測這可能是電源開關。
用類似的邏輯來看，我們也可以發現dp_id為6的實體，它其實是室內溼度的感應器。
如何查詢enum可能的value？ / How to Query Possible Values of an Enum?
比較麻煩的是UVC它的類型是「enum」，而數值是字串「low」，這又是什麼意思呢？
這時候我們就需要一邊調整可以一邊搭配控制裝置，一邊查詢API，以此瞭解實體可能的值。舉例來說，剛剛UVC模式是「弱速」，所以Tuya API的數值是「low」。現在我們把UVC模式調整為「強速」來看看。
再查詢API，你就會發現value變成了「high」。
UVC模式設為「自動」的話，value就變成了「auto」。
在localTuya裡面設定UVC模式 / Setting UVC Mode in LocalTuya
瞭解了enum的可能數值後，我們就可以回到localTuya裡面設定裝置的Entity。enum的Entity type請選擇select。
在Configure entity裡面進行以下設定：
- ID設定為UVC模式的dp_id，也就是106。
- Friendly name則參考code的寫法，寫上便於理解的名稱，例如「uvc」。
- Valid enties裡面就得要設定「off;low;high;auto」，各別代表UVC模式的「關閉」、「低速」、「高速」、「自動」。
這樣就能將uvc新增為Home Assistant的實體，在Home Assistant裡面控制除溼機的UVC模式。我為了避免uvc名稱太容易跟其他實體混淆，我就把除溼機的全名寫了上去，看起來有點長。
威技WDH-11FS的設定 / Configuration of NWT WDH-11FS
在瞭解如何查詢裝置的API，獲得實體的設定值之後，我們就能逐步查詢裝置的細節。最後我把威技WDH-11FS裡我會用到的設定整理如下。
開關類別 / Switch
| 實體 | localTuya: Friendly Name | Tuya: dp_id localTuya: ID |
Tuya: type | localTuya: platform | localTuya: Current |
| 除溼機電源開關 | Dehumidifier NWT WDH-11FS Power | 1 | switch | switch | 1 |
選單類別 / Select
| 實體 | localTuya: Friendly Name | Tuya: dp_id localTuya: ID |
Tuya: type | localTuya: platform | localTuya: Valid entries |
| 除溼模式 | Dehumidifier NWT WDH-11FS Dehumidify Mode | 5 | enum | select | auto;dehumidify;continuous;off |
| 風扇方向 | Dehumidifier NWT WDH-11FS swing_set | 105 | enum | select | off;ud;lr;all |
| UVC模式 | Dehumidifier NWT WDH-11FS UVC | 106 | enum | select | off;low;high |
二元感應器類別 / Binary Sensor
| 實體 | localTuya: Friendly Name | Tuya: dp_id localTuya: ID |
Tuya: type | localTuya: platform |
localTyua: On Value (for binary_sensor) |
localTyua: Device Class (for sensor and binary_sensor) |
|
| 水箱是否已滿 | Dehumidifier NWT WDH-11FS tank_full | 101 | bool | binary_sensor | TRUE | FALSE | safety |
| HEPA濾網是否需要更換 | Dehumidifier NWT WDH-11FS hepa_change | 103 | bool | binary_sensor | TRUE | FALSE | safety |
感應器類別 / Sensor
| 實體 | localTuya: Friendly Name | Tuya: dp_id localTuya: ID |
Tuya: type | localTuya: platform | localTyua: Unit of Measurement (for sensor) |
localTyua: Device Class (for sensor and binary_sensor) |
| 室內溼度 | Dehumidifier NWT WDH-11FS humidity_indoor | 6 | value | sensor | % | humidity |
| PM2.5感測器 | Dehumidifier NWT WDH-11FS UVC PM25 | 15 | value | sensor | ppm | aqi |
結語 / Conclusion
除溼機能夠跟Home Assistant整合嗎？大部分的商家都會跟你說，不行，只能跟我自家的APP整合，頂多是跟Google助理或Homekit整合。至於為什麼客服會這樣說，你看了我這篇的說明大概也能猜到一二，那就是Home Assistant的設定的確是複雜很多。
這篇是因為使用了localTuya的方案，不僅local_key得要自己查詢，所有的entity都得要一一查詢、設定，通常還需要多次的嘗試錯誤，最後才能找到正確的設定。
如果直接使用Home Assistant裡面的Tuya整合，那應該可以更簡單一點。但是Tuya整合要求每半年都要上平臺申請驗證，久了也覺得麻煩，所以才有了這次嘗試localTuya的打算。
雖然設定好localTuya除溼機跟自動化規則之後，我就不太需要再回去設定localTuya。但未來如果還要繼續使用localTuya方案，我肯定會忘記上面那串查詢跟設定的操作方式。還是趁自己還有記憶的時候，趕快把它記錄下來吧。
這篇關於在Home Assistant使用localTuya的教學就到此為止了。文章最後的問題是，你對於localTuya的設定過程有什麼看法呢？
- 1. 雖然很複雜，但設定完之後就可以不用再調整，還是蠻值得一試的。
- 2. 用Tuya整合就好了吧？頂多每半年去申請一次延長，還有裝置一定要連上網際網路而已。
- 3. 太麻煩了，有沒有更容易整合的除溼機？
- 4. 為什麼除溼機要整合到智慧家居？自己按個按鈕不行嗎？
- 5. 為什麼要用除溼機？
- 6. 其他：歡迎在下面留言，分享你的看法吧！
