Matter 연결 가이드
이 가이드는 Homenet2Matter (h2m-matter) 연동 방식을 사용하여, 월패드 기기들을 다양한 스마트홈 플랫폼(애플 홈, 구글 홈, 삼성 스마트싱스 등)에 직접 연결하는 방법을 다룹니다.
1. 개요
**Homenet2Matter (h2m-matter)**는 스마트홈 국제 표준 프로토콜인 Matter를 통해 별도의 복잡한 연동 장치나 추가적인 MQTT 브로커 없이 스마트홈 플랫폼과 직접 통신합니다.
MQTT 연동과의 차이점
| 구분 | MQTT 연동 (h2m-mqtt) | Matter 연동 (h2m-matter) |
|---|---|---|
| 통신 방식 | MQTT 프로토콜 (MQTT Broker 필요) | Matter 프로토콜 (IPv6 / mDNS 기반 로컬 통신) |
| 대상 플랫폼 | Home Assistant | Apple Home, Samsung SmartThings, Google Home 등 |
| 등록 방식 | HA 구성요소 자동 발견 또는 YAML 작성 | 앱에서 QR 코드 스캔 또는 수동 코드 입력 |
| 기기 노출 시점 | 최초 상태 패킷 수신 시 자동 발견 발행 (지연 발행) | 서비스 구동 즉시 설정된 모든 지원 기기 일괄 노출 |
| 필요 장치 | MQTT Broker 서버 | 플랫폼별 Matter 호환 허브 (HomePod, SmartThings Hub 등) |
NOTE
기기 노출 방식의 차이점
- MQTT 연동: 실제 가동 중인 기기 위주로 자동 발견하도록 최초 상태 패킷 수신 시에 Discovery 메시지를 발행합니다. (
discovery_always설정을 사용해 강제 발행도 가능) - Matter 연동: 기동 즉시 설정에 등록되어 있는 모든 지원 기기들을 가상 디바이스 노드로 선언하여 스마트홈 컨트롤러에 전달합니다. 따라서 MQTT Discovery 전용 제어 옵션인
discovery_always,discovery_linked_id,discovery_skip등은 Matter 모드에서 모두 무시됩니다.
2. 사전 네트워크 요건 (중요)
Matter는 **mDNS (Multicast DNS, UDP 포트 5353)**와 IPv6를 사용하여 기기를 탐색하고 연결합니다.
- 동일한 서브넷: 스마트홈 플랫폼의 **허브(Hub)**와 h2m 서비스가 설치된 호스트, 그리고 등록을 진행할 스마트폰은 반드시 동일한 공유기(서브넷) 아래에 있어야 합니다.
- Docker 사용 시: mDNS 패킷이 정상적으로 중계될 수 있도록 반드시
network_mode: host설정으로 구동해야 합니다. (자세한 내용은 Docker 설치 가이드를 참고하세요.) - 스마트홈 허브(컨트롤러) 준비: Matter 브릿지를 등록하려면 해당 플랫폼의 Matter 컨트롤러 역할을 하는 허브 장치(예: Apple HomePod, Apple TV, SmartThings Hub, Google Home Nest Hub 등)가 필요합니다.
3. 최초 페어링 절차 (공통)
h2m-matter 브릿지가 구동되면 다음과 같은 공통 순서로 플랫폼에 기기를 추가할 수 있습니다.
1단계: Web UI에서 페어링 정보 확인
- 브라우저에서 h2m 웹 UI(
http://<서버IP>:3000)에 접속합니다. - 좌측 메뉴 또는 상단 탭에서 Matter 아이콘/메뉴를 클릭합니다.
- 페어링 정보(Pairing Credentials) 영역에서 QR 코드와 수동 페어링 코드(Manual Pairing Code), Passcode를 확인합니다.
2단계: 스마트홈 플랫폼 앱에서 추가
- 사용하려는 스마트홈 앱(예: Apple 홈, Samsung SmartThings, Google Home 등)을 켭니다.
- 기기 추가 또는 액세서리 추가 버튼을 누릅니다.
- 카메라가 켜지면 h2m 웹 UI에 표시된 QR 코드를 스캔합니다.
- QR 코드 스캔이 불가능하거나 실패하는 경우, **'코드 없음 또는 스캔할 수 없음'**을 누르고 **수동 페어링 코드(11자리 숫자)**를 직접 입력합니다.
- 화면의 안내에 따라 연결을 완료하면, 브릿지 기기가 등록되고 브릿지에 연결된 월패드 하위 기기(조명, 난방, 환기팬 등)가 일괄적으로 등록됩니다.
4. 멀티 패브릭 (다른 플랫폼에 추가 연결)
Matter 프로토콜은 **멀티 패브릭(Multi-Fabric)**을 지원하므로, 하나의 h2m-matter 브릿지를 애플 홈과 스마트싱스에 동시에 연결해 두고 양쪽에서 실시간으로 제어할 수 있습니다.
추가 플랫폼 연결 방법
- 첫 번째 플랫폼에 성공적으로 페어링을 완료합니다.
- 등록된 플랫폼 앱의 기기 설정 화면에서 '다른 서비스와 공유' 또는 **'페어링 모드 켜기'**를 선택합니다.
- 앱에서 새롭게 생성된 일회용 QR 코드 또는 페어링 코드가 제공됩니다.
- 두 번째 플랫폼 앱을 켜고, 해당 QR 코드 또는 페어링 코드를 입력하여 등록합니다.
5. 트러블슈팅
Q. 기기 검색 실패 또는 "페어링할 수 없음" 오류가 발생합니다.
- 네트워크 모드 확인: Docker로 실행 중인 경우
docker-compose.yml파일에서network_mode: host가 적용되었는지 반드시 확인하세요.ports:포트 포워딩 방식으로는 mDNS 멀티캐스트 패킷이 중계되지 않습니다. - Wi-Fi 주파수 밴드: 스마트폰과 스마트홈 허브가 동일한 공유기의 2.4GHz 또는 5GHz 밴드에 함께 연결되어 있는지 확인하세요. 일부 공유기에서 밴드 간 분리(AP Isolation) 기능이 켜져 있으면 mDNS 통신이 차단될 수 있습니다.
- 네트워크 장비 차단: IGMP Snooping 기능이 있는 스위칭 허브나 공유기에서 멀티캐스트 전송을 제한하는 경우가 있습니다. 공유기 설정에서 멀티캐스트 관련 옵션을 검토하세요.
Q. 기기가 부분적으로만 제어되거나 반응이 느립니다.
- Matter 브릿지 연결 상태를 웹 UI의 Matter 탭에서 새로고침하여 활성 Fabric 정보가 올바르게 업데이트되었는지 확인하세요.
- RS485 패킷 전송 주기에 부하가 없는지 웹 UI의 최근 활동 또는 raw패킷로그에서 확인해보세요.