81 lines
8.2 KiB
Markdown
81 lines
8.2 KiB
Markdown
# Find My Device
|
|
|
|
Home Assistant에 기록된 Galaxy Z Fold7의 위치, 배터리, 활동 상태, 이동 경로와 모바일 앱 센서 값을 지도 및 설정형 화면에 표시하는 개인용 나의 찾기 페이지입니다.
|
|
|
|
```html
|
|
<meta charset="UTF-8">
|
|
<link href="/custom/common/css/findmydevice.css" rel="stylesheet" />
|
|
<script src="/custom/findmydevice/js/main.js"></script>
|
|
```
|
|
|
|
## 기능
|
|
|
|
- 현재 위치 지도 표시
|
|
- GPS 정확도 원 표시
|
|
- 사용자 지정 기간 이동 경로 표시
|
|
- 이동 기록 요약, 경로 전체 보기, 경로 재생, 시간 슬라이더
|
|
- 부드러운 렌더링용 경로선, GPS 튐 보정 토글, 체류 지점 자동 표시
|
|
- 현재 위치 기준 집 50m, 500m/1km 반경 표시와 선택 지점 Naver 지도 열기
|
|
- 집 체류 합산, 외출/복귀 세션, 마지막 복귀 시각과 현재 상태 표시
|
|
- 배터리, 충전 상태, 배터리 건강, 온도, 전력, 활동 상태, 걸음 수, 이동 거리 표시
|
|
- 네트워크, 기기, 화면/오디오, 건강/활동, 저장공간/데이터, 알림/통화, 센서 정보를 섹션별로 표시
|
|
- 자동 위치 갱신 웹훅 제어와 Companion App 위치 갱신 명령 전송
|
|
- 강제 위치/센서 업데이트 요청
|
|
- 한국어/영어 전환
|
|
- 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합니다.
|
|
|
|
위치 갱신 명령은 `/custom/common/config.php`의 `findmydevice_location_refresh` 설정을 사용합니다. `seoul`, `main` Home Assistant 프로필의 `notify.mobile_app_seocaegeonyi_z_fold7` 서비스로 Companion App notification command를 보냅니다. 자동 업데이트가 켜지면 Android high accuracy mode를 5초 간격으로 설정하고 `force_on`을 보낸 뒤 `request_location_update`와 `command_update_sensors`를 함께 호출합니다. 자동 업데이트 중에는 10초마다 위치 요청과 센서 업데이트 요청을 반복하고, 자동 업데이트를 끄거나 페이지를 벗어나면 `force_off`를 보냅니다.
|
|
|
|
## 히스토리와 지도
|
|
|
|
실시간 화면은 현재 위치와 상태를 조회하고, 기본 기간 입력값에 해당하는 최근 하루 이동 기록도 지도에 함께 표시합니다. 기간 입력을 변경하면 해당 범위의 이동 기록을 `history=1` 옵션으로 다시 요청합니다. 서버는 기간이 길어도 Home Assistant 히스토리 API를 실행한 뒤, 브라우저 렌더링용으로 경로를 부드럽게 단순화해 응답합니다.
|
|
|
|
상태 조회는 `seoul`, `main` Home Assistant의 `/states`를 모두 읽어 entity별로 병합합니다. 한쪽에만 의미 있는 값이 있으면 해당 값을 사용하고, 양쪽 모두 값이 있으면 더 최신 `last_updated` 또는 `last_changed` 값을 사용합니다. 선택된 상태의 attributes에 빈 값이 있으면 다른 쪽 attributes로 채워 빈칸을 줄입니다.
|
|
|
|
히스토리 조회도 `seoul`, `main` Home Assistant history를 모두 읽습니다. 서버는 시간과 좌표를 기준으로 중복 지점을 제거하고 시간순으로 병합한 뒤 기존 경로 단순화와 smoothing을 적용합니다. 응답에는 병합 전 출처별 지점 수인 `historySourceCounts`도 포함합니다.
|
|
|
|
Naver Map에는 단일 Polyline 중심의 부드러운 경로선을 먼저 그리고 시작/종료 마커와 체류 지점 마커를 표시합니다. 중간 점 마커는 긴 기간 조회에서 브라우저 부하가 커지므로 표시하지 않습니다. 기록 조회 시 지도는 경로 전체가 보이도록 자동으로 범위를 맞추며, 종료 지점 정보창을 먼저 열어 최근 위치를 바로 확인할 수 있게 합니다.
|
|
|
|
지도 기능은 NAVER 지도 API v3의 기본 컨트롤, `Polyline`, `PointingIcon`, `Circle`, `fitBounds`를 활용합니다. 지도 아래 도구 패널에서 경로 전체 보기, 경로 재생, GPS 튐 보정, Naver 지도 열기를 제어합니다.
|
|
|
|
히스토리 요약 패널은 이동 거리, 기록 시간, 평균 속도, 최대 기록 공백, 지점 수, 체류 지점 수, 집 반경, 집 체류 시간, 외출 시간, 외출 횟수, 마지막 복귀 시각과 현재 상태를 표시합니다. 각 히스토리 마커 정보창에는 기록 시각, 시작점 기준 누적 거리, 좌표를 함께 표시합니다.
|
|
|
|
경로선은 Douglas-Peucker 단순화와 가벼운 좌표 smoothing을 거쳐 긴 기간에서도 완만한 단일 선으로 표시합니다. 2km 이상 순간 이동하면서 180km/h를 넘는 GPS 튐은 기본적으로 제외하며, 지도 아래 `GPS 튐 보정` 버튼으로 원본 렌더링 경로와 보정 경로를 전환할 수 있습니다.
|
|
|
|
집 판정은 현재 위치를 중심점으로 한 50m 반경을 기준으로 합니다. 50~90m 구간은 집 근처/불안정 구간으로 두고, 집 밖 상태가 5분 이상 지속될 때만 외출 세션으로 확정합니다. 여러 번 나갔다 돌아온 경우 집 체류 시간은 합산하고, 외출은 출발/복귀 단위의 세션으로 따로 보여줍니다.
|
|
|
|
기록 시간 슬라이더를 움직이면 선택 마커가 해당 시점으로 이동하고, 선택 시각과 추정 속도를 지도 아래에 표시합니다. 경로 재생도 같은 선택 마커를 사용합니다. 80m 반경 안에서 10분 이상 머문 구간은 체류 지점 마커로 묶어 표시하며, 클릭 시 체류 시간과 시작/종료 시각을 확인할 수 있습니다.
|
|
|
|
라이브 위치에는 집 50m 원, GPS 정확도 원, 500m/1km 현재 위치 반경 원을 함께 표시합니다. `Naver 지도` 버튼은 히스토리 선택 지점 또는 현재 위치를 Naver 지도에서 바로 엽니다.
|
|
|
|
## 센서 표시 정책
|
|
|
|
실제 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` 같은 값은 화면 언어에 맞춰 표시됩니다.
|
|
|
|
## 운영 메모
|
|
|
|
긴 기간 히스토리 조회는 Home Assistant recorder 데이터량과 웹서버/프록시 timeout 영향을 받을 수 있습니다. findmydevice API는 Home Assistant 쿼리를 실행한 뒤 원본 지점 수와 렌더링 지점 수를 함께 내려주며, 브라우저에는 부드러운 지도 표시용 경로를 출력합니다.
|
|
|
|
Companion App의 `request_location_update`는 앱이 실행 중이거나 백그라운드에 있을 때 위치 보고를 시도합니다. Android에서는 위치 권한, 백그라운드 실행 허용, Location Sensors의 Background Location, Single Accurate Location, High Accuracy Mode 설정이 실제 갱신 빈도에 영향을 줍니다.
|
|
|
|
이 프로젝트는 위치, 주소, 배터리, 활동 기록을 포함하므로 private 저장소와 개인 접근 환경에서만 운영합니다.
|