Home Assistant와 Xiaomi Gateway 3 통합: 펌웨어 패치 및 자동화

Xiaomi Gateway를 Home Assistant에 XiaomiGateway3 활용하여 통합하기

— 펌웨어(패치)·설치·전환(ZHA/z2m)·보안·운영까지 “처음부터 끝까지” 가이드

Xiaomi Multimode Gateway(일명 Gateway 3), Multimode Gateway 2, Aqara Hub E1를 Home Assistant(HA) 에 XiaomiGateway3로 통합하는 전체 과정을 순서대로 정리합니다. 모델·펌웨어별 패치(소프트/하드), 통합 설치, Zigbee 운용모드(ZHA/zigbee2mqtt) 전환, 예제 자동화, 보안 기준과 점검표, 장애 대응·복구까지 다룹니다.

0) 전체 흐름 한눈에 보기

1. 가장 안전한 기본 경로(권장)
   • HACS 설치 → XiaomiGateway3 설치 → Cloud 연결(계정 로그인) → Gateway 추가
   • 필요 시 소프트 패치(텔넷 열기) → openmiio_agent 자동 실행 → 바로 사용
2. 운용모드 선택
   • Mi Home 모드 유지: 미홈 앱 + HA 병행 제어(안정·간편)
   • ZHA 모드: socket://게이트웨이IP:8888 로 HA ZHA 연결(단일화·간단, 재페어 필요)
   • zigbee2mqtt 모드: tcp://게이트웨이IP:8888 + adapter: ezsp(대규모·확장성, 재페어 필요)
3. 보안 기본선
   • IoT VLAN/별도 SSID, 고정 IP, 2.4GHz-20MHz-WPA2, 최소 포트만 허용
   • 텔넷은 임시 사용 후 비밀번호 설정/차단, 토큰·키는 비밀 저장
4. 문제 시 복구
   • 공장 초기화, 슬롯 스왑(가능한 모델), UART 복구(고급) 사전 계획 필수

1) 준비물 & 사전 점검

• 장치: Gateway 3(주요 모델), Gateway 2, Aqara Hub E1 중 1대
• Mi Home 계정: 지역은 게이트웨이 판매지역과 일치 권장
• 네트워크
  • 게이트웨이·HA 동일 서브넷, 게이트웨이 고정 IP 예약
  • 2.4GHz 전용, 채널폭 20MHz, WPA2-PSK(WPA3 혼용 비권장)
  • 라우터의 Airtime Fairness/밴더 특화 옵션은 일단 비활성 권장
• Home Assistant: 최신(또는 안정) 릴리스. SSH/터미널 접근 가능
• 보안 기본: 관리 PC·HA에 MFA, 비밀 저장소(secrets.yaml) 사용

2) HACS & XiaomiGateway3 설치

1. HACS 설치(없다면)
   • HA → Settings → Add-ons → Add-on Store → Repositories 에 HACS 등록
   • HACS 애드온 설치 → 실행 → HA 재시작
2. XiaomiGateway3 설치
   • HACS → Integrations → 우상단 ‘Explore & Download’ → XiaomiGateway3 → Install
   • (수동) 릴리스의 custom_components/xiaomi_gateway3/ 폴더를 /config/custom_components/에 복사 후 재시작

3) 통합 추가(Cloud → Gateway 순서가 핵심)

1. Cloud 통합 추가
   • HA → Settings → Devices & Services → Add Integration → XiaomiGateway3 (Cloud)
   • Mi Home 계정 로그인 → 내 계정에 등록된 게이트웨이/토큰/키 정보를 HA가 가져오도록 함
   • 장점: 별도 추출 없이 토큰/키 관리 자동화, 다수 게이트웨이도 한 번에 조회
2. Gateway 통합 추가
   • 다시 Add Integration → XiaomiGateway3 (Gateway)
   • 게이트웨이 IP(고정), 토큰(필수), 키(펌웨어에 따라 필요) 입력
   • 완료 후 Gateway + 연결된 하위 장치(Zigbee/BLE/Mesh) 가 엔티티로 생성

일부 최신 펌웨어는 토큰만으로 충분하거나, 토큰+키 모두 필요할 수 있습니다.
위 Cloud 단계에서 둘 다 자동 취득되는 경우가 많습니다.

4) 소프트 패치: 텔넷 열기 & openmiio_agent

목적: 장치 내부에서 openmiio_agent를 실행해 로컬 MQTT 브릿지, ZHA/z2m 브릿지, BLE 로컬 처리 등 고급 기능을 사용합니다. 대부분은 통합이 자동으로 처리하지만, 연결 문제·펌웨어 차이로 텔넷 활성이 필요한 경우가 있습니다.

4-1) 가장 쉬운 방법: HA 통합의 “명령 입력” 기능 사용

• XiaomiGateway3 통합 설정에 “Open Telnet command(또는 유사)” 입력 필드가 있습니다.
• 제공된 예시 명령(JSON)을 그대로 넣어 텔넷 데몬(telnetd) 실행 → 곧바로 접속 가능.

4-2) 터미널에서 직접(예: python-miio)

# 1) 설치
pip install python-miio

# 2) 텔넷 오픈(예시: set_ip_info에 명령 주입)
miiocli device --ip <GW_IP> --token <GW_TOKEN> raw_command set_ip_info \
'{"ssid":"\"\"","pswd":"123123 ; passwd -d admin ; echo enable > /sys/class/tty/tty/enable; telnetd"}'

# 3) 텔넷 접속(성공 시)
telnet <GW_IP> 23
# 로그인: admin / (빈 비밀번호) → 즉시 비밀번호 설정 권장
passwd

4-3) openmiio_agent 상태 점검

# MQTT 브릿지 토픽이 뜨는지 점검(HA 호스트에서)
apk add mosquitto-clients  # (또는) apt/yum으로 mosquitto-clients 설치
mosquitto_sub -h <GW_IP or HA_Broker_IP> -t 'miio/#' -v
mosquitto_pub -h <GW_IP or HA_Broker_IP> -t 'miio/command' -m '{"method":"miIO.info","params":[]}'

텔넷은 임시 목적으로만 열고, 사용 후 비밀번호 설정 혹은 방화벽 차단으로 노출 최소화하세요.

300x250

Xiaomi Gateway 3 커스텀 펌웨어 패치와 설치에는 텔넷 접속, 스크립트 실행, FTP 업로드, 수동 업데이트 과정이 필요합니다. 아래는 쉬운 방법(Easy Way) 과 고급 방법(Hard Way) 입니다.

• 게이트웨이 모델: mgl03 (Xiaomi Gateway 3)
• 홈 네트워크에 연결된 게이트웨이 IP 확인 (라우터/미홈 앱에서 가능)
• PC에서 사용할 텔넷 클라이언트(PuTTY 등)
• (권장) Home Assistant + XiaomiGateway3 통합 설치 후 사용

텔넷(Telnet) 열기

• 게이트웨이에서 텔넷 접속 허용이 선행되어야 합니다.
• 접속 계정은 기본적으로
  • ID: admin
  • PW: 없음 (빈 값)
• 접속 성공 시 루트 쉘로 명령 실행 가능.

쉬운 방법(Easy Way)

가장 간단히 스크립트를 실행해 펌웨어를 교체하는 방식입니다.

1. 텔넷으로 게이트웨이에 접속
2. 아래 명령어 실행

   wget -O /tmp/curl "http://master.dl.sourceforge.net/project/mgl03/bin/curl?viasf=1" && chmod +x /tmp/curl
   export PATH="$PATH:/tmp"
   curl -s -k -L -o /tmp/update.sh https://raw.githubusercontent.com/zvldz/mgl03_fw/main/firmware/mgl03_update.sh && sh /tmp/update.sh

   
3. 스크립트가 실행되면 업데이트할 펌웨어 버전을 선택
4. 완료 후 게이트웨이 자동 재부팅
5. PuTTY/텔넷 창이 닫히면 정상. 오류 없는지 확인

주요 펌웨어 버전 차이가 크다면 게이트웨이 공장 초기화(버튼 10번 연속 클릭) 필요할 수 있음.

어려운 방법(Hard Way, Warrior Mode)

FTP를 직접 켜고, 펌웨어 파일을 업로드한 뒤 수동으로 업데이트하는 방식입니다.
고급 사용자를 위한 방법으로, 세부 제어가 필요할 때 활용합니다.

 

4-1) FTP 서버 열기

• 방법 A: Home Assistant 서비스 호출
  • Developer Tools → Services
  • 서비스 실행

    Service: remote.send_command
    Entity: remote.0x<게이트웨이ID>_pair
    Data:
      command: ftp

    
• 방법 B: 텔넷 직접 실행

  wget -O /data/busybox "http://master.dl.sourceforge.net/project/mgl03/bin/busybox?viasf=1" && chmod +x /data/busybox
  /data/busybox tcpsvd -vE 0.0.0.0 21 /data/busybox ftpd -w &

  

4-2) 펌웨어 파일 다운로드 & 준비

• 커스텀 펌웨어 다운로드 경로 예시
  • mgl03_1.4.6_0012_mod20210308.zip
• 압축 해제 → 내부 파일
  • linux_1.4.6_0012.bin
  • root_1.4.6_0012_mod20210308.bin
  • full_ble_1.4.6_0012.gbl

 

4-3) FTP 업로드

• FTP 클라이언트(FileZilla/WinSCP 등) 사용
• 게이트웨이에 접속 → /tmp 폴더에 위 3개 파일 업로드

 

4-4) 펌웨어 수동 업데이트

텔넷 접속 상태에서 실행

fw_update /tmp/linux_1.4.6_0012.bin
fw_update /tmp/root_1.4.6_0012_mod20210308.bin
run_ble_dfu.sh /dev/ttyS1 /tmp/firmware/full_ble_1.4.6_0012.gbl 123 1
reboot

• 재부팅 후 자동으로 /tmp의 임시 파일 삭제됨
• 주요 변경이 큰 경우 → 게이트웨이 리셋 버튼 10회 클릭으로 공장 초기화 필요

5) Zigbee 운용 모드 3가지

5-1) 모드 A: Mi Home 유지(기본)

• 게이트웨이의 Zigbee는 Mi Home 네트워크를 그대로 사용
• 미홈 앱 + HA 모두에서 장치를 제어(일부 타사 Zigbee는 HA 전용일 수 있음)
• 재페어(다시 연결) 불필요, 안정·간편

5-2) 모드 B: ZHA 전환(HA 내장 Zigbee)

• HA → Settings → Devices & Services → Add Integration → Zigbee Home Automation
• Serial device에 다음 경로 입력

  socket://<GW_IP>:8888

• Mi Home Zigbee 네트워크는 중지되고, 모든 Zigbee 장치를 ZHA에 재페어해야 합니다.
• 장점: HA 일원화(간단), 단점: 무선 브리지(EZSP over TCP) 특성상 환경에 따라 안정성 편차

5-3) 모드 C: zigbee2mqtt 전환(확장성·대규모)

• Mosquitto + Zigbee2MQTT 애드온 설치
• configuration.yaml 또는 z2m UI에서 어댑터 설정

  serial:
    port: tcp://<GW_IP>:8888
    adapter: ezsp

• 모든 Zigbee 장치 재페어 필요
• 장점: 장치 호환성·커스터마이징 강함, 단점: 구성 난이도/학습곡선

ZHA/z2m로 전환하면 Mi Home Zigbee 네트워크와 호환되지 않으므로 재페어는 필수입니다.
되돌릴 땐 초기화가 필요할 수 있습니다.

6) 예제: 자동화·제어(HA YAML)

6-1) 버튼 액션으로 “집 전체 소등”

automation:
  - alias: '[버튼] 한번 클릭 시 집 전체 소등'
    trigger:
      - platform: state
        entity_id: sensor.0x158d0002fa99fd_action
        to: button_1_single
    action:
      - service: light.turn_off
        entity_id: all
    mode: single

6-2) 현관문 센서로 사이렌(게이트웨이 버저) 울리기

automation:
  - alias: '[도어센서] 열림 시 게이트웨이 버저 10초 울림'
    trigger:
      - platform: state
        entity_id: binary_sensor.front_door_contact
        to: 'on'  # 열림
    action:
      - service: alarm_control_panel.alarm_trigger
        target:
          entity_id: alarm_control_panel.gateway_alarm
        data:
          code: "10,3"  # 10초, 볼륨 3

6-3) 조도+모션으로 자동 점등(시간대 조건)

automation:
  - alias: '[모션/조도] 해질녘~밤 자동 점등'
    trigger:
      - platform: state
        entity_id: binary_sensor.living_motion
        to: 'on'
    condition:
      - condition: numeric_state
        entity_id: sensor.living_illuminance
        below: 50
      - condition: time
        after: '18:00:00'
        before: '23:59:59'
    action:
      - service: light.turn_on
        target:
          entity_id: light.living_main
        data:
          brightness_pct: 60

7) 보안 가이드 점검

1. 네트워크 분리
   • 게이트웨이·IoT 기기는 전용 VLAN/SSID(인터넷만)
   • HA가 있는 관리망과 필요 포트만 상호 허용
   • 권장 허용: HA↔GW TCP 8888(Zigbee EZSP), 1883(MQTT, 필요 시), 23(telnet: 임시만)
   • UPnP, 외부 포트 포워딩 금지
2. 자격·비밀 관리
   • Mi Home 계정 MFA 적용
   • 토큰/키는 secrets.yaml 또는 전용 비밀관리(예: Vault) 보관
   • 통합이 생성하는 키 파일(있을 경우) 백업 및 권한 제한
3. 텔넷 최소화
   • 사용 목적 달성 즉시 passwd로 강한 비밀번호 설정 또는 방화벽/ACL로 차단
   • 소프트 패치 명령은 운영 종료 시 원복(지속 데몬 비활성)
4. 로그·감사
   • MQTT 명령/이벤트 토픽(miio/#, openmiio/# 등)을 중앙 로그(ELK/Loki 등) 로 수집
   • 허가되지 않은 명령/비정상 이벤트 탐지 룰 구성
   • 변경관리: 모드 전환(ZHA↔z2m), 펌웨어 플래시/롤백 등 모두 Change Ticket 기록
5. 펌웨어 변경 통제
   • 커스텀 Zigbee FW/멀티프로토콜 RCP는 ZHA/z2m 안정성 목적으로만 제한 사용
   • 롤백 절차(기본 FW 복원, 공장 초기화, UART 복구) 문서화 및 리허설

8) 트러블슈팅(증상 → 조치)

1. 장치가 자주 끊김/응답 느림
   • 2.4GHz 전용, 채널폭 20MHz, 고정 채널(1/6/11)
   • 게이트웨이·HA 동일 서브넷, 게이트웨이 고정 IP
   • 라우터의 Airtime Fairness, Band Steering, 802.11k/v/r 등은 일단 비활성
2. 토큰/키가 안 보임
   • Cloud 통합을 먼저 추가하여 계정 연동 → 이후 Gateway 추가
   • 계정 지역·게이트웨이 지역 불일치 시 앱에서 동일 지역으로 재등록
3. ZHA/z2m 전환 후 장치가 안 보임
   • 재페어 필수(Mi Home 네트워크와 호환되지 않음)
   • 전환 전 “중요 장치 리스트업 → 전환 후 순차 페어링” 계획
4. 8888/TCP가 열리지 않음
   • 소프트 패치(openmiio_agent) 재적용, 방화벽 확인
   • nmap -p 8888 <GW_IP> 로 포트 개방 점검
5. BLE/Mesh 장치가 안 보임
   • Mi Home 모드에서도 BLE/Mesh는 대부분 동시 동작
   • 장치 배터리·거리·간섭(전자레인지, 금속) 체크

9) 롤백·복구 시나리오

• 기본 복구: 게이트웨이 공장 초기화 → Mi Home 재등록 → HA 재통합
• 슬롯 스왑(일부 모델): 과거 펌웨어로 부팅(모델/상태에 따라 불가할 수 있음)
• UART(고급): 3.3V TTL(UART)로 부트로더 진입 → factory/boot 파티션 확인 → 텔넷 비번 확인·패치 → 부팅/복구
  • 고급/위험 작업: 로그 백업·정확한 명령·정전 대비 필수

주의: 하드 패치(UART, 부트로더 조작)는 오타/정전 시 벽돌 위험이 큽니다.
실험 전 전체 백업·비상전원·정전기 대책을 준비하세요.

10) 점검표(체크리스트)

• 모델/펌웨어 파악(토큰만? 토큰+키?)
• HACS 설치 → XiaomiGateway3 설치
• Cloud 통합(계정 로그인) → Gateway 통합(IP/토큰/키)
• (필요 시) 소프트 패치로 텔넷 열기 → openmiio_agent 동작 확인
• 운용모드 선택: Mi Home 유지 / ZHA / zigbee2mqtt
• 네트워크 튜닝: 2.4GHz/20MHz/고정채널, 동일 서브넷, 고정 IP
• 보안: IoT VLAN, 텔넷 최소화, secrets.yaml, 로그 중앙수집
• 전환 계획: 재페어 순서표, 다운타임 공지
• 복구 계획: 초기화·슬롯·UART 비상경로 문서화

11) 자주 쓰는 명령·설정 모음(치트시트)

텔넷 열기(예시)

pip install python-miio
miiocli device --ip <GW_IP> --token <GW_TOKEN> raw_command set_ip_info \
'{"ssid":"\"\"","pswd":"123123 ; passwd -d admin ; echo enable > /sys/class/tty/tty/enable; telnetd"}'
telnet <GW_IP> 23

ZHA 연결 경로

socket://<GW_IP>:8888

zigbee2mqtt 설정

serial:
  port: tcp://<GW_IP>:8888
  adapter: ezsp

MQTT 점검

mosquitto_sub -h <BROKER_IP> -t 'miio/#' -v
mosquitto_pub -h <BROKER_IP> -t 'miio/command' -m '{"method":"miIO.info","params":[]}'

포트 점검

nmap -p 23,1883,8888 <GW_IP>

마무리 정리

• 가장 안전한 시작은 Cloud → Gateway 순으로 통합하고, 필요할 때만 소프트 패치(텔넷)를 사용하는 것입니다.
• 이후 Mi Home 유지(간편), ZHA(간단·일원화), zigbee2mqtt(대규모·확장) 중 상황에 맞게 선택하세요.
• 보안·복구 플랜을 미리 세우면 운영이 훨씬 편해집니다.