WiFi 라우터 기능 복원

README.md

@@ -1,10 +1,10 @@
 # Control
 
-팬 제어, 시스템 모니터링, WakeLock을 제공하는 PHP 기반 단일 관리 패널입니다.
+팬 제어, 시스템 모니터링, WiFi 제어, WakeLock을 제공하는 PHP 기반 단일 관리 패널입니다.
 
 ## 프로젝트 성격
 
-Control은 라즈베리파이/리눅스 호스트의 팬과 시스템 상태를 웹에서 관리하기 위한 내부 운영 도구입니다. 로그인 후 대시보드에서 온도, 팬 RPM, PWM, 저전압/스로틀링, notice를 확인하고 필요한 제어 명령을 실행합니다. 첫 화면은 운영 판단에 필요한 핵심 정보 위주로 구성하고, 상세 차트와 진단성 데이터는 접힘 영역에 둡니다.
+Control은 라즈베리파이/리눅스 호스트의 팬과 시스템 상태를 웹에서 관리하기 위한 내부 운영 도구입니다. 로그인 후 대시보드에서 온도, 팬 RPM, PWM, WiFi client, 저전압/스로틀링, notice를 확인하고 필요한 제어 명령을 실행합니다. 첫 화면은 운영 판단에 필요한 핵심 정보 위주로 구성하고, 상세 차트와 진단성 데이터는 접힘 영역에 둡니다.
 
 상태 갱신은 WebSocket을 우선 사용하고, 연결 실패 시 HTTP fallback으로 전환합니다. 팬 정책 적용과 센서 수집은 백그라운드 작업과 API 호출을 통해 DB에 기록됩니다.
 
@@ -17,6 +17,11 @@ Control은 라즈베리파이/리눅스 호스트의 팬과 시스템 상태를
 - RP1 온도, 팬 효율, CPU 전력 상세 차트는 접힘 영역에서 확인
 - UPS/배터리 잔여 시간 기능은 장치 제거 후 비활성 상태로 두고, 배터리 센서 조회와 장기 학습 계산은 돌리지 않음
 - 라즈베리파이 저전압/스로틀링 현재 상태, 복구 중/반복 발생 판정, 부팅 후 이력, 최근 감지 시각, 지속시간, 최근 10분 통계 표시
+- WiFi client 목록과 2.4G/5G client 수 표시
+- 5G 외부 WiFi 모듈이 연결 시간을 제공하지 않는 경우 서버 관측 기반 연결 시간 보정
+- WiFi 호스트명이 비어 있으면 MAC 기반 임시명을 표시하고, MAC별 수동 호스트명을 DB에 저장해 이후에도 유지
+- WiFi 신호/송신 속도/수신 속도가 비어 있으면 대역, dBm, 송수신 속도, 5G RTL8822BU 특성을 기준으로 결측값 보정
+- WiFi client 신호는 7단계 한글 등급으로 표시하고, hover/focus/touch 시 커스텀 툴팁에서 실제 dBm을 표시
 - System Notice 최근 이력 표시
 - process CPU/MEM 후보는 프로세스 상세 접힘 영역에서 표시
 - `/etc/systemd/system/*.service` 기준 사용자 생성 서비스의 서비스명, 현재 상태, enable 상태, PID, restart 횟수, 최근 journal 로그를 진단 접힘 영역에서 표시
@@ -30,9 +35,11 @@ Control은 라즈베리파이/리눅스 호스트의 팬과 시스템 상태를
 
 ## 주요 API
 
-- `public/api.php?action=status`: 팬, 센서, 시스템, history, notice 상태 조회
+- `public/api.php?action=status`: 팬, 센서, 시스템, WiFi, history, notice 상태 조회
 - `public/api.php?action=collect`: 센서 snapshot 수집 후 팬 정책 적용
 - `public/api.php?action=fan`: 팬 모드와 PWM 저장/적용
+- `public/api.php?action=wifi`: 허용된 WiFi/DHCP service 제어
+- `public/api.php?action=wifi_alias`: MAC별 WiFi 호스트명 저장
 - `public/api.php?action=settings`: 설정 가능한 Control 동작값 조회
 - `public/api.php?action=settings_save`: 설정 모달 값 저장
 - `public/api.php?action=settings_reset`: 설정 모달 값을 기본값으로 초기화
@@ -50,6 +57,8 @@ Control은 라즈베리파이/리눅스 호스트의 팬과 시스템 상태를
 - `config/config.php`: DB, 인증, CSRF, shell 실행 공통 함수
 - `apply_policy.php`: CLI/cron 팬 정책 적용
 - `bin/control_ws.php`: WebSocket 서버. 핵심 PHP 파일 변경 감지 시 종료되고 systemd가 재시작해 새 코드를 로드
+- `bin/wifi_observe.php`: 5G WiFi 연결 시간 보정을 위한 시스템단 관측 CLI
+- `systemd/control-wifi-observe.*`: WiFi 관측 CLI를 주기적으로 실행하는 systemd unit 예시
 
 `asset-version.php`는 `public`의 PHP/JS/CSS/manifest/icon 파일과 `config`의 PHP 파일을 읽어 크기, 수정 시각, sha256 hash를 묶은 버전을 만듭니다. `asset-reload.js`는 화면 복귀, 포커스 복귀, 30초 간격으로 이 값을 다시 확인하고, 값이 달라지면 브라우저 Cache Storage를 비운 뒤 현재 화면을 다시 엽니다.
 
@@ -61,6 +70,8 @@ Control은 라즈베리파이/리눅스 호스트의 팬과 시스템 상태를
 - `/tmp/control-throttling-state.json`: `vcgencmd get_throttled` 기반 스로틀링 감지 상태, 최근 지속시간, 최근 episode 이력
 - `system_notice_state`: notice 활성 상태와 기준값
 - `system_notice_logs`: notice 발생 이력
+- `wifi_observed_sessions`: 5G WiFi client의 최초/마지막 감지 시간
+- `wifi_client_aliases`: MAC별 수동 WiFi 호스트명
 - `app_settings`: 설정 모달에서 저장한 Control 동작값 오버라이드
 - `/home/seo/secret/control.php`: 앱 비밀번호, DB 설정, 선택적 배터리 설정
 - UPS/배터리 기능은 `/home/seo/secret/control.php`의 `battery.enabled`가 명시적으로 true일 때만 동작합니다. 현재 운영 기준은 UPS 제거 상태이므로 기본값은 false입니다.
@@ -80,7 +91,7 @@ API 응답의 `battery.enabled`는 false, `battery.removed`는 true로 내려가
 설정 가능한 항목은 다음 범위입니다.
 
 - 팬 자동 제어: 팬 시작 온도, 최대 온도, 즉시 최대 PWM 온도, RP1 온도 반영 비율, 팬 판단 온도 여유, 자동 상승/하강 PWM step
-- 보안 정책: 자동 로그인 유지 기간, remember 쿠키 Secure/SameSite, CSRF 길이, remember 토큰 길이, User-Agent/IP 접두사 검증, 로그인 실패 잠금, 재부팅 허용 여부, 재부팅 확인 문구, 명령 timeout
+- 보안 정책: 자동 로그인 유지 기간, remember 쿠키 Secure/SameSite, CSRF 길이, remember 토큰 길이, User-Agent/IP 접두사 검증, 로그인 실패 잠금, 재부팅 허용 여부, 재부팅 확인 문구, 명령 timeout, WiFi 조작 허용 여부
 - 화면/진단 표시: 프로세스 후보 수, 사용자 서비스 로그 줄 수, 사용자 서비스 캐시 시간, 팬 이상 이력 수
 - 저전압/스로틀링: 최근 판정창, 복구 중 유지 시간, 반복 발생 기준 횟수
 - 팬 이상감지: 기준 표본 수, 최신 표본 제외 수, RPM/온도 이상 감지 차이, RPM/온도 복구 차이, RPM 감시 시작 PWM, alert 유지 중 반복 기록, 반복 기록 간격, 하강 변화 원인 후보 표시 여부
@@ -96,6 +107,7 @@ API 응답의 `battery.enabled`는 false, `battery.removed`는 true로 내려가
 - 탭 복귀: 즉시 1회 상태 갱신
 - UPS/배터리 잔여 시간: 현재 운영 구성에서는 표시하지 않음
 - dmesg: 진단 패널에서 열었을 때만 1초마다 갱신, 닫으면 중지
+- WiFi 관측 보정 timer: 10초마다 `bin/wifi_observe.php` 실행
 - WebSocket 소스 변경 감지: 15초마다 확인 후 재시작
 - 팬 슬라이더 자동 적용 debounce: 약 450ms
 
@@ -113,6 +125,29 @@ System Notice는 다음 조건으로 동작합니다.
 - System Notice 기록: alert 신규 진입 시 `system_notice_logs`에 기록합니다. `Alert 유지 중 반복 기록`을 켜면 유지 중에도 설정한 반복 기록 간격마다 다시 기록할 수 있습니다.
 - 저전압/스로틀링 표시: `vcgencmd get_throttled`의 현재 비트와 부팅 후 이력 비트를 읽어 현재 상태, 최근 감지, 지속시간, 최근 10분 통계를 표시합니다. 이 값은 System Notice와 별개이며, 팬/온도 alert 조건에는 직접 섞지 않습니다.
 
+## WiFi 관측 자동화
+
+5G 외부 WiFi 모듈은 `iw station dump`에 `connected time`을 제공하지 않는 경우가 있어, 서버가 MAC별 최초 감지 시각을 DB에 저장하고 경과 시간을 계산합니다.
+
+기존 대시보드 조회만으로도 보정은 가능하지만, 사용자가 접속하지 않은 시간에는 최초 감지가 늦어질 수 있습니다. 이를 막기 위해 다음 systemd timer가 10초마다 관측 CLI를 실행합니다.
+
+```bash
+control-wifi-observe.timer
+control-wifi-observe.service
+```
+
+실행 명령은 다음과 같습니다.
+
+```bash
+/usr/bin/php /var/www/control/bin/wifi_observe.php
+```
+
+이 작업은 팬 정책, 차트 로그 저장, System Notice 기록과 분리되어 있으며 WiFi client 목록 확인과 `wifi_observed_sessions` 갱신만 수행합니다.
+
+호스트명은 dnsmasq lease 값을 우선 사용합니다. lease hostname이 `N/A`이면 MAC 주소 끝 6자리 기반 임시명 `기기-XXXXXX`을 표시하고, 표의 호스트명을 클릭해 저장한 수동 이름은 `wifi_client_aliases`에 보관해 이후에도 우선 표시합니다.
+
+신호/송신 속도/수신 속도는 실제 `iw station dump` 값이 있으면 그대로 사용합니다. 값이 비어 있으면 2.4G는 일반 802.11n 계열 링크 속도와 dBm 범위를 기준으로, 5G는 Realtek RTL8822BU/802.11ac 계열 동글의 최대 1300Mbps 특성을 참고해 dBm과 링크 속도 사이를 보정합니다. 화면의 신호 칸은 숫자 대신 `최상`, `매우 좋음`, `좋음`, `양호`, `보통`, `약함`, `매우 약함` 7단계 등급으로 표시하고, 마우스 hover/키보드 focus/모바일 touch 시 커스텀 툴팁으로 실제 dBm을 표시합니다. 툴팁 내용과 위치는 1초 상태 렌더마다 다시 갱신됩니다.
+
 ## 처리 흐름
 
 1. 화면 진입 시 로그인 세션과 remember token을 확인합니다.
@@ -120,13 +155,17 @@ System Notice는 다음 조건으로 동작합니다.
 3. 대시보드는 `status` snapshot을 렌더링합니다.
 4. WebSocket 연결이 성공하면 `status` 메시지로 갱신하고, 실패하면 HTTP fallback을 사용합니다.
 5. 팬 조작은 상태 저장, 정책 적용, 로그 저장 순서로 처리합니다.
-6. WakeLock 버튼은 활성 상태를 초록색 버튼으로 표시합니다.
-7. Reboot 버튼은 설정된 확인 문구와 관리자 암호 재입력을 모두 통과한 뒤 서버 API로 재부팅을 요청합니다.
-8. 시스템 상태는 `vcgencmd get_throttled`를 읽어 현재 저전압/스로틀링 여부와 부팅 후 이력, 최근 감지 시각, 현재/최근 지속시간을 표시합니다.
-9. 저전압/스로틀링 상태 파일에는 최근 episode 시작/종료를 보관하고, 최근 10분 발생 횟수, 감지 누적시간, 감지 비율을 계산합니다.
-10. UPS/배터리 장치가 제거되어 배터리 센서 조회와 잔여 시간 학습 계산은 기본적으로 돌리지 않습니다.
-11. System Notice 조건이 맞으면 Control이 `system_notice_logs`에 이력을 저장합니다.
-12. 대시보드 첫 화면에는 팬/전원/스로틀링/핵심 차트를 우선 배치하고, 상세 차트, 프로세스 후보, 사용자 서비스, dmesg는 접힘 영역으로 분리합니다.
+6. WiFi client 목록은 `iw station dump`와 dnsmasq lease를 조합하고, 5G 연결 시간이 `N/A`이면 MAC 기준 최초 감지 시간을 DB에 저장해 경과 시간을 계산합니다.
+7. WiFi hostname이 비어 있으면 MAC 기반 임시명을 표시하고, 수동 저장한 MAC별 이름은 DB에서 우선 적용합니다.
+8. WiFi 신호/송신 속도/수신 속도 값이 비어 있으면 실제로 존재하는 다른 무선 지표와 대역별 기준으로 값을 채웁니다.
+9. `control-wifi-observe.timer`는 사용자 접속과 무관하게 10초마다 5G 관측 세션을 갱신합니다.
+10. WakeLock 버튼은 활성 상태를 초록색 버튼으로 표시합니다.
+11. Reboot 버튼은 설정된 확인 문구와 관리자 암호 재입력을 모두 통과한 뒤 서버 API로 재부팅을 요청합니다.
+12. 시스템 상태는 `vcgencmd get_throttled`를 읽어 현재 저전압/스로틀링 여부와 부팅 후 이력, 최근 감지 시각, 현재/최근 지속시간을 표시합니다.
+13. 저전압/스로틀링 상태 파일에는 최근 episode 시작/종료를 보관하고, 최근 10분 발생 횟수, 감지 누적시간, 감지 비율을 계산합니다.
+14. UPS/배터리 장치가 제거되어 배터리 센서 조회와 잔여 시간 학습 계산은 기본적으로 돌리지 않습니다.
+15. System Notice 조건이 맞으면 Control이 `system_notice_logs`에 이력을 저장합니다.
+16. 대시보드 첫 화면에는 팬/전원/스로틀링/WiFi/핵심 차트를 우선 배치하고, 상세 차트, 프로세스 후보, 사용자 서비스, dmesg는 접힘 영역으로 분리합니다.
 
 ## 팬 판단 온도
 
@@ -147,6 +186,9 @@ System Notice는 다음 조건으로 동작합니다.
 - `apply_fan_policy()`: 팬 목표값 계산과 적용
 - `fan_control_temp()`: CPU/RP1 혼합 팬 판단 온도 계산
 - `json_out()`: API JSON 응답 표준화
+- `apply_observed_wifi_connected_time()`: 5G WiFi 연결 시간이 없는 client에 서버 관측 경과 시간 적용
+- `wifi_client_aliases()`, `save_wifi_client_alias()`: MAC별 WiFi 호스트명 조회와 저장
+- `apply_wifi_estimates()`: WiFi 신호/송신 속도/수신 속도 결측값 보정
 - `battery_status()`: `CONTROL_BATTERY_ENABLED`가 true일 때만 배터리 센서를 읽고, 현재 기본 구성에서는 제거 상태를 반환
 - `battery_trend_history()`: 배터리 기능을 다시 켤 때 최근 24시간 배터리 기록을 1분 단위로 집계
 - `battery_profile_history()`: 배터리 기능을 다시 켤 때 최대 45일 배터리 기록을 약 5분 간격으로 샘플링하고 파일 캐시로 보관
@@ -163,6 +205,7 @@ System Notice는 다음 조건으로 동작합니다.
 - `sync_current_battery_remaining_history()`: 잔여 시간 차트 마지막 지점을 현재 snapshot 잔여 시간과 동기화
 - `batteryRemainingTitle()`, `showBatteryTooltip()`, `updateBatteryTooltip()`: 잔여 시간 계산 근거 커스텀 팝오버 표시와 실시간 갱신
 - `setting_definitions()`, `settings_payload()`, `save_settings()`, `reset_settings()`: 설정 모달 항목 정의, 조회, 저장, 초기화
+- `bin/wifi_observe.php`: 화면 접속 없이 `wifi_data()`를 호출해 5G 관측 세션을 선제 갱신
 - `assets/wakelock.js`: WakeLock 버튼 상태와 Screen Wake Lock API 제어
 - `customAlert()`, `customConfirm()`, `customPrompt()`: 대시보드 공통 확인/입력 dialog
 - `controlLang`, `controlTheme`: 재접속 후에도 유지되는 언어/테마 localStorage key
@@ -179,13 +222,18 @@ System Notice는 다음 조건으로 동작합니다.
 - 재부팅 API는 CSRF, 로그인 세션, 설정된 확인 문구, 관리자 암호 재검증을 모두 요구합니다.
 - 로그인 화면은 CSRF 검사를 수행하고, 설정한 실패 횟수/집계 시간/잠금 시간에 따라 세션 단위 잠금을 적용합니다.
 - Remember login은 설정에 따라 Secure/SameSite, 토큰 길이, 만료 기간, User-Agent 고정, IPv4 접두사 고정을 조정할 수 있습니다.
+- WiFi restart/reload 허용 여부와 root 명령 timeout은 설정 모달에서 조정합니다.
 - 앱 비밀번호와 DB/선택적 배터리 설정은 저장소 밖 secret 파일로 관리합니다.
 
 ## 운영 체크포인트
 
 - 센서 수집 주기와 DB 증가량을 확인합니다.
 - UPS/배터리를 다시 붙일 때는 `/home/seo/secret/control.php`의 `battery.enabled`와 용량값을 먼저 확인합니다.
+- WiFi client 표는 갱신 중에도 가로 스크롤 위치를 보존합니다.
 - 하드웨어 또는 OS 변경 후 fan sysfs 경로를 확인합니다.
+- 2.4G 내장 WiFi는 `hostapd-24g.service` 개별 restart 직후 일부 IoT 단말이 WPA/EAPOL 재협상 루프에 들어갈 수 있으므로, 안정화된 상태에서는 개별 restart를 피하고 필요 시 전체 reboot 또는 채널 변경으로 재초기화합니다.
+- 5G WiFi 연결 시간은 외부 모듈이 값을 제공하지 않을 때 서버가 처음 감지한 시각 기준으로 계산합니다. 현재 5G 목록에서 MAC이 사라지면 관측 세션을 즉시 종료하므로 재연결 시 0부터 다시 누적됩니다.
+- `control-wifi-observe.timer`는 10초마다 `/var/www/control/bin/wifi_observe.php`를 실행해 사용자가 대시보드에 접속하지 않아도 5G 연결 시간 카운터를 시작하고 유지합니다.
 - WebSocket은 장기 실행 프로세스이므로 `public/api.php`, `config/config.php`, `bin/control_ws.php` 변경을 감지하면 15초 안에 종료되고 `control-websocket.service`가 새 프로세스로 재시작합니다.
 - WebSocket 장기 실행 중 DB 연결이 끊길 수 있으므로 reconnect 로그를 확인합니다.
 - SmartThings 재로드 자동화는 서울 전력분전반과 목포 누전차단기 전력 센서의 값이 10초 이상 변하지 않으면 통합을 재로드합니다.