買到 Z2M 不支援的 Zigbee 裝置？自己寫外部轉換器

charles

Zigbee2MQTT 現在支援 5,473 種裝置（2.12.0 版），
但你還是可能買到不在清單上的。

不用退貨，也不用等官方支援 —— 自己寫一個。



先確認「真的不支援」

配對之後，Z2M 的日誌會出現：

1. Device '0x00158d00xxxxxxxx' with Zigbee model 'TS0601'
2. and manufacturer name '_TZE200_abcdefgh' is NOT supported

複製代碼

記下這兩個東西：

• zigbeeModel —— 例如 TS0601
  
• manufacturerName —— 例如 _TZE200_abcdefgh
  

這兩個是身分證，轉換器就是靠它們對應的。

先搜尋一下有沒有人寫過

在自己動手之前，先花五分鐘搜尋：

• Google 搜 「_TZE200_abcdefgh zigbee2mqtt」
  
• 去 Z2M 的 GitHub Issues 搜那個 manufacturerName
  
• 很多人已經寫好了，直接拿來用
  

找不到才自己寫。

轉換器是什麼

Zigbee 裝置送出來的是一堆數字，轉換器負責把它翻譯成「溫度 26.5 度」。

• fromZigbee —— 裝置 → Z2M（讀取）
  
• toZigbee —— Z2M → 裝置（控制）
  
• exposes —— 告訴 HA「這個裝置有哪些功能」
  

第一步：建立檔案

在 Z2M 的資料目錄裡建一個 my_device.js：

1. /config/zigbee2mqtt/my_device.js

複製代碼

（如果你用 HA 的附加元件，路徑通常是這個）

第二步：最簡單的版本

很多情況下，你的裝置其實跟某個「已支援的裝置」一模一樣，只是廠牌名不同。

這種最好處理：

1. const {temperature, humidity, battery} =
2.   require('zigbee-herdsman-converters/lib/modernExtend');
4. module.exports = [
5.   {
6.     zigbeeModel: ['TS0201'],
7.     model: 'MY-TH-01',
8.     vendor: '雜牌',
9.     description: '溫濕度感測器',
10.     extend: [temperature(), humidity(), battery()],
11.   },
12. ];

複製代碼

這樣就好了。

modernExtend 是 Z2M 提供的「現成零件」，
常用的功能都有現成的：

• onOff() —— 開關
  
• light() —— 燈（可以指定支援調光、色溫、顏色）
  
• temperature() / humidity() / pressure()
  
• battery()
  
• occupancy() —— 人體偵測
  
• iasZoneAlarm() —— 門磁、水浸、煙霧這類警報
  
• electricityMeter() —— 電力監測
  

第三步：告訴 Z2M 載入它

在 configuration.yaml 加：

1. external_converters:
2.   - my_device.js

複製代碼

注意：Z2M 2.x 之後，只要把 .js 檔放在資料目錄就會自動載入，
這個設定可以不用寫。但寫了也不會壞。

重啟 Z2M，然後把裝置重新配對一次。



TS0601：最常見也最麻煩的一種

如果你的 zigbeeModel 是 TS0601，那是塗鴉（Tuya）的裝置。

TS0601 不走標準的 Zigbee 叢集，它用自己的「資料點（DP）」機制 ——
所有東西都塞在同一個叢集裡，用一個編號區分。

所以你要先知道「哪個編號代表什麼」。

怎麼找出 DP 編號：

• 在 Z2M 開 debug 日誌
  
• 操作裝置（按按鈕、改設定、讓它回報）
  
• 看日誌裡出現的 dp: 數字 和 data
  
• 記錄「我做了什麼」對應「哪個 dp 變了」
  

範例的轉換器：

1. const tuya = require('zigbee-herdsman-converters/lib/tuya');
3. module.exports = [
4.   {
5.     fingerprint: tuya.fingerprint('TS0601', ['_TZE200_abcdefgh']),
6.     model: 'MY-TRV-01',
7.     vendor: '雜牌',
8.     description: '溫控閥',
9.     extend: [tuya.modernExtend.tuyaBase({dp: true})],
10.     exposes: [
11.       tuya.exposes.temperature(),
12.       tuya.exposes.temperatureSetpoint(),
13.     ],
14.     meta: {
15.       tuyaDatapoints: [
16.         [2, 'current_heating_setpoint', tuya.valueConverter.divideBy10],
17.         [3, 'local_temperature', tuya.valueConverter.divideBy10],
18.         [4, 'battery', tuya.valueConverter.raw],
19.       ],
20.     },
21.   },
22. ];

複製代碼

重點是 tuyaDatapoints 那個陣列：

1. [DP 編號, 屬性名稱, 怎麼換算]

複製代碼

常用的 valueConverter：

• raw —— 直接用
  
• divideBy10 / divideBy100 —— 除以 10 / 100
  
• trueFalse1 —— 1 是 true
  
• onOff —— 轉成 ON / OFF
  

用 fingerprint 而不是 zigbeeModel

因為 TS0601 這個型號被幾百種裝置共用，
只寫 zigbeeModel 會對應錯。

fingerprint 同時比對型號和廠商名，才不會撞號。



除錯

看日誌

Z2M 前端 → Logs 分頁，或者設定裡把 log_level 調成 debug。

常見的錯誤：

一、「外部轉換器載入失敗」

• JavaScript 語法錯了 —— 少一個逗號、括號沒配對
  
• 日誌會顯示第幾行
  

二、「載入了但還是不支援」

• zigbeeModel 或 manufacturerName 拼錯（注意底線和大小寫）
  
• 沒有重新配對 —— 改完轉換器要把裝置移除再配對一次
  

三、「支援了但數值不對」

• valueConverter 選錯 —— 溫度顯示 265 度就是少了 divideBy10
  
• DP 編號對應錯
  

四、「讀得到但控制不了」

• 只寫了 fromZigbee 沒寫 toZigbee
  
• 用 modernExtend 的話通常兩邊都有
  

升級 Z2M 之後轉換器壞掉

這會發生。

• Z2M 的 API 會改（特別是 2.0 那次）
  
• 舊的寫法（純 fromZigbee/toZigbee 陣列）還能用但不推薦
  
• modernExtend 是現在的標準寫法
  

建議：

• 把你的轉換器備份（跟設定檔一起）
  
• 升級之後第一件事就是看日誌有沒有載入失敗
  
• 寫得成功的話，考慮提交給官方 —— 以後就不用自己維護了
  

提交給官方

這是最好的結局。

• 去 zigbee-herdsman-converters 的 GitHub
  
• 開一個 Pull Request
  
• 附上你的測試結果（哪些功能測過了）
  
• 通過之後，下一版就內建了
  

維護者通常很願意收，而且會幫你看程式碼。

---

下一篇：Zigbee 的 OTA 韌體更新，
還有怎麼備份協調器，換硬體不用重配對。