참고: https://www.zigbee2mqtt.io/advanced/support-new-devices/01_support_new_devices.html#instructions
만일 Zigbee 장치가 Z2M에서 정상적으로 인식되지 않을 경우 장치에 대한 외부 정의를 파일로 만들어 Z2M에게 인식시켜주면 된다.
이를 위해 아래 과정을 따른다.
1. 제조사 코드로 비슷한 제품으로 인식 시키기
⑴ Zigbee 제조사 코드 알아내기
Zigbee2MQTT > 0xa4c138758807b972(인식불가 기기) > Zigbee 제조사: _TZE204_w1wwxoja
⑵ 자신의 기기와 비슷한 기기의 제조사 코드 알아내기
https://github.com/Koenkk/zigbee-herdsman-converters/blob/master/src/devices/tuya.ts
에서 자신의 기기와 비슷한 모델을 찾는다.
예를 들어 6구 스마트 스위치라면 "6 gang switch"를 검색하여 fingerprint: tuya.fingerprint 목록에서 자신과 비슷한 장치의 제조사 코드를 알아낸다.
코드를 찾았다면(_TZE204_g4au0afs) 구글링을 통해 해당 코드의 제품을 검색해 보고 자신의 기기에 적용해도 될 정도로 비슷한지 판단한다.
⑶ Zigbee2MQTT 중지
설정 > 애드온 > Zigbee2MQTT > 중지
⑷ 인식불가 기기의 제조사 코드 변경
/var/hass/homeassistant/zigbee2mqtt/database.db 편집
인식불가 기기의 ieeeAddr(a4c138758807b972)을 검색하여 해당 줄을 찾아낸다.
인식불가 제조사 코드(_TZE204_w1wwxoja)를 인식 가능한 코드(_TZE204_g4au0afs)로 manufName, manufacturerName 항목을 변경한다.
⑸ Zigbee2MQTT 시작
설정 > 애드온 > Zigbee2MQTT > 시작하기
⑹ Zigbee2MQTT 목록에서 기기 정상등록 확인
※이 방법은 기기의 제조사 코드가 database.db에서 계속 원상복구 되므로 추천하지는 않는다.
2. 외부 정의 생성
⑴ Zigbee2MQTT > 해당 장치 클릭
⑵ Exposes 탭에서 노출(Expose)된 변수값이 있는지 확인하고 없다면 인식이 안된 것이므로
⑶ 개발자 콘솔 탭에서 [generate_external_definition]을 클릭하여 이 장치에 맞는 외부 정의를 생성한다.
※이 방법은 장치가 Zigbee ZCL(Cluster Library Specification) 사양을 구현할 때만 작동이 가능하고 실패할 수도 있다.
만들어진 외부 확장을 /var/hass/homeassistant/zig2mqtt에 임의의 파일명(ts0222.js)으로 저장한다.
그리고 /var/hass/homeassistant/zig2mqtt/configuration.yaml에 아래를 추가 후 Z2M을 재시작한다.
----------
advanced:
log_level: debug
external_converters:
- ts0222.js
----------
3. 외부 정의 확장
만일 위의 방법이 실패할 경우 아래의 과정을 진행한다. (tuya 장치일 경우)
https://github.com/Koenkk/zigbee-herdsman-converters/blob/master/src/devices/tuya.ts
를 참고하여 컨버터의 내용 일부를 외부 확장 js 파일 작성에 사용한다.
*** SAMPLE: 조도센서(_TZ3000_9kbbfeho) ***
----------
const {battery, illuminance } = require('zigbee-herdsman-converters/lib/modernExtend');
const definition = {
zigbeeModel: ['TS0222'],
model: 'TS0222',
vendor: '_TZ3000_9kbbfeho',
description: 'Light Sensor',
extend: [battery(), illuminance()],
meta: {},
};
module.exports = definition;
----------
*** SAMPLE: 6구 스위치(_TZE204_w1wwxoja) ***
----------
const {} = require('zigbee-herdsman-converters/lib/modernExtend');
const fz = require('zigbee-herdsman-converters/converters/fromZigbee');
const tz = require('zigbee-herdsman-converters/converters/toZigbee');
const exposes = require('zigbee-herdsman-converters/lib/exposes');
const reporting = require('zigbee-herdsman-converters/lib/reporting');
const ota = require('zigbee-herdsman-converters/lib/ota');
const utils = require('zigbee-herdsman-converters/lib/utils');
const globalStore = require('zigbee-herdsman-converters/lib/store');
const tuya = require('zigbee-herdsman-converters/lib/tuya');
const e = exposes.presets;
const ea = exposes.access;
const definition = {
fingerprint: tuya.fingerprint('TS0601', ['_TZE204_w1wwxoja']),
model: 'TS0601_switch_6_gang',
vendor: 'Tuya',
description: '6 gang switch',
fromZigbee: [tuya.fz.datapoints],
toZigbee: [tuya.tz.datapoints],
configure: async (device, coordinatorEndpoint, logger) => {
const endpoint = device.getEndpoint(1);
await reporting.bind(endpoint, coordinatorEndpoint, ['genOnOff']);
await reporting.onOff(endpoint);
device.powerSource = 'Mains (single phase)';
device.save();
},
exposes: [
tuya.exposes.switch().withEndpoint('l1'),
tuya.exposes.switch().withEndpoint('l2'),
tuya.exposes.switch().withEndpoint('l3'),
tuya.exposes.switch().withEndpoint('l4'),
tuya.exposes.switch().withEndpoint('l5'),
tuya.exposes.switch().withEndpoint('l6'),
],
endpoint: (device) => {
return {l1: 1, l2: 1, l3: 1, l4: 1, l5: 1, l6: 1};
},
whiteLabel: [tuya.whitelabel('Tuya', 'TS0601_switch_6_gang', 'Living room main 6 gang switch', ['_TZE204_w1wwxoja'])],
meta: {
multiEndpoint: true,
tuyaDatapoints: [
[1, 'state_l1', tuya.valueConverter.onOff],
[2, 'state_l2', tuya.valueConverter.onOff],
[3, 'state_l3', tuya.valueConverter.onOff],
[4, 'state_l4', tuya.valueConverter.onOff],
[5, 'state_l5', tuya.valueConverter.onOff],
[6, 'state_l6', tuya.valueConverter.onOff],
],
},
};
module.exports = definition;
----------
정상적으로 동작할 경우 Z2M에서 아래와 같은 로그를 출력한다.
Zigbee2MQTT:debug 2019-11-09T12:24:22: No converter available for 'WSDCGQ01LM' with cluster 'msTemperatureMeasurement' and type 'attributeReport' and data '{"measuredValue":2512}'
만일 로그가 아무것도 없을 경우 추가 구성이 필요하며 이는 configure: 섹션을 추가하여 구성할 수 있다.
예를 들어 tuya 호환 장치일 경우 아래 주소를 참고한다.
https://www.zigbee2mqtt.io/advanced/support-new-devices/02_support_new_tuya_devices.html
몇 가지 기본적인 외부 변환기 예:
전구(조명): https://github.com/Koenkk/zigbee2mqtt.io/blob/master/docs/externalConvertersExample/light.js
플러그(스위치): https://github.com/Koenkk/zigbee2mqtt.io/blob/master/docs/externalConvertersExample/switch.js
고급 예제: https://github.com/Koenkk/zigbee2mqtt.io/blob/master/docs/externalConvertersExample/freepad_ext.js
이미 지원되는 기기의 정의는
https://github.com/Koenkk/zigbee-herdsman-converters/tree/master/src/devices
웹페이지를 참고한다.