Xiaomi Home 계정으로 설정

이 방법은 로봇 청소기가 현재 Xiaomi Home 애플리케이션을 통해 관리되는 경우 사용해야 합니다. 호환성을 보장하기 위해 iOS 및 Android용 공식 Xiaomi Home 앱과 비교하여 확인할 수 있습니다.

요구 사항

• 자격 증명: 모바일 애플리케이션에 로그인할 때 사용한 정확한 사용자 이름과 비밀번호여야 합니다(공식 웹사이트 아님).
• 서버 지역: 선택한 국가는 앱에서 장치가 등록된 지역과 일치해야 합니다. 지역이 일치하지 않으면 "로그인 실패" 또는 "장치를 찾을 수 없음" 오류가 발생합니다.

제3자 로그인

계정이 서드파티 서비스(예: Google 또는 Apple)를 이용해 생성된 경우, 먼저 애플리케이션의 사용자 설정에서 전용 비밀번호를 생성해야 합니다. 서드파티 계정 비밀번호는 인증에 사용할 수 없습니다.

앱 선택 권장

일부 장치는 Dreamehome 또는 Xiaomi Home 애플리케이션을 사용하여 구성할 수 있습니다. 로컬 연결이 엄격하게 필요하지 않은 한, 지원되는 장치의 경우 Xiaomi Home 대신 Dreamehome 앱을 사용하는 것이 강력히 권장됩니다:

• 카메라 스트림: Xiaomi Home을 통해 구성된 장치에서는 카메라 스트림 기능을 사용할 수 없습니다.
• 푸시 업데이트: Dreamehome 연결은 클라우드 푸시를 사용하여 실시간 업데이트를 제공하므로 주기적인 폴링 요청이 필요 없습니다.

클라우드 옵션 선호

구성 단계에서는 추가로 클라우드 선호 옵션이 제공되며 기본적으로 선택되어 있습니다.

• 선택됨(기본값)일 때: 모든 통신을 클라우드를 통해 강제합니다(장치에서 지원하는 경우). 이는 최신 장치에서 Xiaomi가 로컬 접근 기능을 비활성화했기 때문에 기본 동작입니다. 또한, 장치와 Home Assistant가 서로 다른 서브넷에 있으면 로컬 통신이 실패합니다.
• 선택되지 않음(지원되는 설정에 권장): 통합은 필요한 토큰을 클라우드에서 가져오지만 장치와 직접 로컬 연결을 설정합니다(로컬 연결 방식과 유사). 이는 자동 토큰 및 IP 갱신의 이점을 제공하면서 모든 통신(지도 데이터를 제외한)을 로컬에서 유지합니다. 만약 이 방식이 마지막 설정 단계에서 "장치에 접근할 수 없음" 오류를 발생시키면, 클라우드 우선 옵션을 선택한 후 다시 설정해야 합니다.

  서브넷 요구 사항

  보안상의 이유로, 장치는 자신의 서브넷에서 발생한 요청에만 응답합니다. 따라서 로봇 청소기와 Home Assistant가 로컬 통신을 위해 정확히 동일한 서브넷에 있어야 합니다. 이 python-miio 문서를 참조하여 서브넷 간 문제를 해결하세요.

캡차 인증

Xiaomi Home 서버가 로그인 시도 또는 IP 주소를 신뢰할 수 없는 것으로 표시하면 캡차 인증 단계가 필요합니다. 이 경우 다음 단계로 진행하려면 캡차 이미지를 해결해야 합니다.

이중 인증(2FA)

캡차 외에도, 신뢰할 수 없는 로그인 시도는 이중 인증(2FA)을 유발할 수 있습니다. 통합은 Xiaomi Home 서버에서 2FA 코드를 자동으로 요청하며, 이 코드는 등록된 전화번호(우선적으로) 또는 이메일 주소로 전송됩니다.

이 코드를 받아서 구성 단계에 입력해야 로그인 완료가 가능합니다.

2FA 제한 사항

• 코드 유효성: 구성 창이 닫히고 새로운 로그인 시도가 발생하면 새로운 2FA 코드가 생성됩니다. 항상 가장 최근에 수신한 코드를 사용해야 합니다.
• 요청 제한: Xiaomi는 하루에 요청할 수 있는 2FA 코드 수를 엄격하게 제한합니다. 반복적인 로그인 시도는 일시적인 차단을 초래할 수 있습니다.

주기적인 상태 업데이트

푸시 알림을 지원하는 다른 클라우드 연결 방법과 달리, Xiaomi Home 연결은 최신 상태를 가져오기 위해 전적으로 백그라운드 폴링에 의존합니다. 네트워크 사용을 최적화하기 위해, 폴링 간격은 마지막 상태 변경 이후 경과 시간을 기반으로 동적으로 계산됩니다; 장치가 활성 상태일 때는 요청이 자주 전송되지만, 장치가 유휴 상태로 남아 있는 시간이 길어질수록 간격이 점차 늘어납니다.

재인증

통합 기능은 로그인 성공 후 인증 토큰을 안전하게 저장하여 클라우드 서버와 통신합니다. 이 토큰이 만료되거나 클라우드 서비스에 의해 무효화되면, Home Assistant는 자동으로 재인증 흐름을 트리거하여 계정 자격 증명을 다시 입력하도록 요청합니다.