TL;DR

  • Roborock Local Server는 로컬 네트워크에서 Roborock 클라우드 백엔드를 구동해, 하드웨어 개조나 펌웨어 루팅 없이 대부분의 지원 진공청소기에서 인터넷 연결 없이 실시간 지도와 로컬 제어를 제공함.
  • DNS 재지정, 초기 온보딩 핸드셰이크, 로컬 HTTPS·MQTT 스택을 통해 진공청소기가 공식 클라우드 대신 자체 서버에 연결됨.
  • Home Assistant와 로컬 앱, 패치된 공식 앱 등 여러 프런트엔드를 지원하며, 새 기기의 사전 클라우드 등록 없는 온보딩과 되돌릴 수 있는 설정을 제공함.
  • 최신 v2 프로토콜 모델을 포함한 대부분의 Roborock 진공청소기가 대상이지만, 인증서 검증 방식 차이로 Q7 등 보급형 Q 시리즈는 현재 지원되지 않음.
  • 자체 도메인과 로컬 DNS 재작성, LAN 내 서버, 유효한 SSL 인증서, 초기 온보딩용 보조 컴퓨터가 필요함.

Roborock Local Server

  • Roborock의 클라우드 백엔드를 자체 로컬 네트워크에서 실행하는 소프트웨어임.
  • 인터넷 연결이 없는 격리된 LAN에서도 진공청소기의 실시간 지도와 로컬 제어를 유지하며, 하드웨어 개조나 펌웨어 루팅이 필요하지 않음.

개발 배경

  • Home Assistant는 로컬 프로토콜로 Roborock 진공청소기와 통신하지만, 완전한 오프라인 운용에는 두 가지 제약이 있었음.
  • 클라우드에 종속된 지도: 진공청소기 자체에 지도가 저장돼 있음에도 Roborock이 지도 데이터를 공식 클라우드 서버를 통해서만 전달함.
  • 클라우드 상태 확인: 진공청소기가 Roborock 서버에 접속하지 못하면 네트워크 인터페이스를 반복적으로 재시작해 로컬 통신이 끊김.
  • 상위 클라우드의 인증 방식 변경도 서드파티 통합에서 가장 자주 발생하는 장애 원인임.
  • Roborock Local Server는 온프레미스 HTTPS 및 MQTT 스택을 제공함. DNS를 재지정하고 최초 온보딩 핸드셰이크를 완료하면 진공청소기가 공식 클라우드 대신 로컬 서버에 연결됨.

기능

  • 로컬 지도 스트리밍: 클라우드 접속 없이 실시간 지도와 방별 청소를 지원함.
  • 하드웨어 개조 불필요: 분해, 납땜, 부트로더 잠금 해제가 필요하지 않음.
  • 신규 기기 온보딩: 이전에 클라우드에 등록하지 않은 새 진공청소기도 처음부터 지원함.
  • 되돌릴 수 있는 설정: 진공청소기의 Wi-Fi를 초기화하면 공장 페어링 모드로 돌아감.
  • 프런트엔드 선택지: Home Assistant(애드온 제공), LocalRock(오픈소스 모바일 앱), Android APK 패치 또는 iOS MITM 프로필을 적용한 공식 앱과 함께 작동함.

호환성

  • 지원 대상: Dennis Giese의 펌웨어 연구를 바탕으로, 최신 v2 프로토콜 모델을 포함한 대부분의 Roborock 진공청소기임.
  • 현재 미지원 대상: 인증서 검증 방식 차이로 Q7 등 보급형 Q 시리즈임. QRevo와 혼동하면 안 됨.
  • 구체적인 모델별 보고는 Tested Vacuums List에서 확인 가능함.

요구 사항

  • 로컬 DNS 재작성을 설정할 수 있는 자체 도메인: Pi-hole, AdGuard Home 또는 라우터 DNS가 해당함.
  • LAN에서 스택을 실행할 환경: Docker Compose 또는 애드온을 지원하는 Home Assistant 설치 환경이 해당함.
  • 도메인에 유효한 SSL 인증서: Cloudflare DNS-01 자동 발급 방식 또는 수동 발급 방식이 해당함.
  • 최초 온보딩에 사용할 Wi-Fi 지원 보조 컴퓨터 한 대임.

시작하기

  • 스택을 처음 설정하는 경우 다음 안내를 따름.
  • Installation: 공통 요구 사항, 네트워크 설정, Docker Compose 설치 경로 안내임.
  • Home Assistant: Docker Compose 대신 Home Assistant 애드온으로 설치하는 안내임.
  • Cloudflare setup: 인증서 자동 갱신을 위한 Cloudflare DNS-01 설정 안내임.
  • Onboarding: 서버 실행 후 보조 컴퓨터에서 진공청소기를 페어링하는 안내임.
  • Updating: 기존 설치 환경을 최신 안정 버전으로 업데이트하는 안내임.
  • 인증서 방식을 선택하기 전에 Tested vacuums를 확인해야 함. 모델마다 허용하는 인증서 체인이 서로 다름.
  • 대부분의 사용자는 ZeroSSL부터 시작하는 것이 권장됨. Actalis는 주로 구형 진공청소기나 해당 인증서 체인을 더 안정적으로 신뢰하는 것으로 알려진 모델에 적합함.
  • 추가 문서 목록임.
  • Docs index
  • Technical Writeup: How Reverse Engineering Works
  • Known limitations
  • Tested vacuums
  • 애드온 설치 경로와 통합 설정을 다루는 Home Assistant 안내
  • Mobile App Options
  • Custom MQTT
  • Custom certificate management

컨테이너 이미지

  • 게시된 이미지는 ghcr.io/python-roborock/local_roborock_server:latest이며, docker pull 명령으로 가져오는 이미지임.

기여

  • 완전히 테스트한 코드 기여를 환영함.
  • 동영상 안내와 설정 튜토리얼 기여를 환영함.
  • 문서 개선과 네트워크 설정 가이드 기여를 환영함.

감사의 말

  • Dennis Giese(@dgiese): Roborock 진공청소기 리버스 엔지니어링 연구와 논문이 작업의 상당 부분에 영감을 줌.
  • Sören Beye(@Hypfer): 클라우드 없는 진공청소기 제어 분야의 기반을 마련한 Valetudo 제작자임.
  • @rovo89: 진행 과정에서 많은 팁과 조언을 제공함.
  • python-miio: 저장소가 python-roborock 로직의 상당 부분을 위한 기반임.
  • @humbertogontijo: python-roborock 저장소를 처음 만든 인물임.
  • @allenporter: python-roborock 라이브러리와 Roborock 통합 유지 관리에서 중요한 역할을 맡고 있음. 저장소에 기여한 개선 사항의 중요성이 큼.
  • @rccoleman: 첫 베타 테스터로서 여러 문제를 해결하는 데 도움을 줌.

면책 조항

  • 이 소프트웨어는 어떠한 종류의 보증도 없이 ‘있는 그대로’ 제공됨.
  • 이 스택을 실행하면 Roborock 진공청소기의 네트워크 통신 방식이 변경됨. 하드웨어 손상, 데이터 손실, 네트워크 노출 및 기타 결과에 대한 책임은 전적으로 사용자에게 있음.
  • 사용에 따른 위험은 사용자 부담임. 이 프로젝트는 Roborock과 제휴하거나 Roborock의 승인 또는 후원을 받은 프로젝트가 아님.

라이선스

  • 이 프로젝트는 MIT License로 배포되며, 자세한 내용은 LICENSE에서 확인 가능함.