custom-findmydevice/README.md

Find My Device

Home Assistant에 기록된 Galaxy Z Fold7의 위치, 배터리, 활동 상태, 이동 경로와 모바일 앱 센서 값을 지도 및 설정형 화면에 표시하는 개인용 나의 찾기 페이지입니다.

<meta charset="UTF-8">
<link href="/custom/common/css/findmydevice.css" rel="stylesheet" />
<script src="/custom/findmydevice/js/main.js"></script>

기능

• 현재 위치 지도 표시
• GPS 정확도 원 표시
• 사용자 지정 기간 이동 경로 표시
• 지도 타입 전환, 교통/거리뷰 레이어 토글
• 이동 기록 요약, 경로 전체 보기, 경로 재생
• 배터리, 충전 상태, 배터리 건강, 온도, 전력, 활동 상태, 걸음 수, 이동 거리 표시
• 네트워크, 기기, 화면/오디오, 건강/활동, 저장공간/데이터, 알림/통화, 센서 정보를 섹션별로 표시
• 자동 위치 갱신 웹훅 제어
• 강제 업데이트 요청
• 한국어/영어 전환
• Wake Lock 지원

구조

• php/api.php: Home Assistant 상태/히스토리 조회 API
• js/main.js: 지도 렌더링, 상태 갱신, 히스토리 표시
• css/style.css: 기존 삽입 코드 호환용 공용 CSS import
• img/: 지도 마커 및 언어 아이콘

공통 모듈 연동

인증과 Home Assistant 호출은 /custom/common을 사용합니다. 브라우저 JS에는 더 이상 API Bearer 토큰이나 Home Assistant 웹훅 식별자를 직접 넣지 않습니다.

접근 확인은 JS에서 읽을 수 있는 레거시 쿠키가 아니라 /custom/launcher/api.php?session=1 서버 응답으로 처리합니다. 공통 인증 쿠키는 HttpOnly이므로 브라우저 스크립트가 직접 읽지 않습니다.

표시할 모바일 앱 센서 목록은 /custom/common/config.php의 findmydevice_sensor_sections에서 섹션 단위로 관리합니다. 화면 CSS 원본은 /custom/common/css/findmydevice.css를 사용합니다. 기존 운영 HTML이 /custom/findmydevice/css/style.css를 참조해도 호환 파일이 공용 CSS를 import합니다.

히스토리와 지도

실시간 화면은 현재 위치와 상태만 조회하고, 이동 기록은 기간 입력을 변경했을 때만 history=1 옵션으로 요청합니다. 서버는 Home Assistant 위치 기록을 15m 미만 미세 이동 기준으로 정리한 뒤 최대 300개 지점으로 샘플링합니다.

Naver Map에는 전체 경로선을 먼저 그리고 시작/종료 마커와 최대 60개의 중간 포인트만 표시합니다. 기록 조회 시 지도는 경로 전체가 보이도록 자동으로 범위를 맞추며, 종료 지점 정보창을 먼저 열어 최근 위치를 바로 확인할 수 있게 합니다.

지도 기능은 NAVER 지도 API v3의 기본 컨트롤, 지도 유형, TrafficLayer, StreetLayer, Polyline, PointingIcon, fitBounds를 활용합니다. 화면 상단 지도 도구에서 일반/위성 지도 전환, 교통 레이어, 거리뷰 가능 구역 레이어, 경로 전체 보기, 경로 재생을 제어합니다.

히스토리 요약 패널은 이동 거리, 기록 시간, 평균 속도, 최대 기록 공백, 지점 수를 표시합니다. 경로선 클릭으로 요약 패널을 숨기거나 다시 볼 수 있고, 각 히스토리 마커 정보창에는 기록 시각과 시작점 기준 누적 거리를 함께 표시합니다.

센서 표시 정책

실제 Fold7에서 확인된 값 기준으로 의미 있는 섹션만 유지합니다. 현재 표시 대상은 배터리, 네트워크, 기기, 화면/오디오, 건강/활동, 저장공간/데이터, 알림/통화, 센서입니다.

unknown, unavailable, <not connected>, <not available>, none처럼 표시 가치가 낮은 상태와 Wi-Fi 미연결 시의 0Mbps, 0MHz, -1dBm 값은 화면에서 제외합니다. Home Assistant 로그에서 속성 크기 경고가 발생하는 활성 알림 목록은 상세 속성을 노출하지 않고 개수만 표시합니다.

Android Companion App의 실제 상태값은 API에서 한국어/영어 표시값으로 변환합니다. 예를 들어 still, cellular, foreground_service, Transmitting, Stopped, portrait, silent 같은 값은 화면 언어에 맞춰 표시됩니다.

운영 메모

이 프로젝트는 위치, 주소, 배터리, 활동 기록을 포함하므로 private 저장소와 개인 접근 환경에서만 운영합니다.