IoT Web Configurator

파트너 전달 안내 (한글) — 먼저 이 순서로 보세요: RELEASE-NOTES.md (이번 버전·변경·주의·배포) → BSP-INTEGRATION.md (설치 경로·샘플 recipe·의존성) → DELIVERABLE-MANIFEST.txt (패키지 구성).

IoT 디바이스 설정을 위한 웹 인터페이스를 제공하는 경량 Python stdlib HTTP 서버입니다. 원래 Java Spring Boot 애플리케이션이었으나, 순수 Python(stdlib만 사용)으로 재작성되어 메모리 사용량이 ~436 MB에서 10–30 MB로 줄었습니다. 모든 설정은 디바이스 내 SQLite 데이터베이스(board_config 테이블)에 저장됩니다.

---

저장소 구조

경로	설명
src/	애플리케이션 소스 — 서버, DB 매니저, 유효성 검사기, 로그 매니저, 네트워크 적용 엔진(src/network/), 펌웨어 OTA(src/firmware/), Wi-Fi AP(src/network/ap_*), 프론트엔드 SPA(src/static/js/pages/ 하위 ~18개 페이지 모듈)
docs/	설계 문서, 사양서, 운영 가이드 (docs/DEPLOY.md 참조)
scripts/	라이브 배포 도구 (deploy.ps1)
CHANGELOG.md	버전 변경 이력

---

로컬 실행

# From the repo root
python src/server.py

서버는 기본적으로 0.0.0.0:9090에 바인딩됩니다. 환경 변수로 재정의할 수 있습니다:

변수	기본값	설명
HOST	0.0.0.0	바인딩 주소
PORT	9090	수신 포트
DB_PATH	/home/root/db/dynamic_data.db	SQLite 데이터베이스 경로
LOG_DIR	/opt/log/dpworldapp	로그 파일 디렉터리

포트 안내: 설정기는 PC·디바이스 어디서든 9090 입니다 (디바이스는 systemd 유닛 deploy/web-configurator.service 이 PORT=9090 을 지정 — 코드 기본값과 동일). 디바이스의 :8080 은 별개의 레거시 Java app-runner(이 앱 아님)이며 무관합니다 — docs/DEPLOY.md §7 참조.

예시:

PORT=8888 DB_PATH=./dev_data.db python src/server.py

---

배포

디바이스 배포는 scripts/deploy.ps1 (PowerShell, Windows 개발 호스트)을 사용합니다. 전체 절차는 docs/DEPLOY.md 를 참조하세요. 다음 내용을 다룹니다:

• 버전 정책(vMAJOR.MINOR.PATCH) 및 릴리즈 절차
• 사전 요건 및 사용 방법
• 스크립트 동작 순서 (아카이브 → 전송 → 백업 → 교체 → 버전 스탬프 → 재시작 → 검증)
• 배포 검증 및 디바이스에서 DEPLOYED_VERSION 확인
• 롤백 (-Rollback 플래그)
• 디바이스 아키텍처 (포트, 경로, 서비스 이름)
• 문제 해결

빠른 참조:

.\scripts\deploy.ps1 192.168.55.56          # deploy a tagged release
.\scripts\deploy.ps1 192.168.55.56 -Rollback  # restore last backup

deploy.ps1은 nginx를 설치하거나 수정하지 않습니다. deploy/nginx.conf는 :80 리버스 프록시를 통해 앱을 노출하는 제품을 위한 선택적 BSP 샘플일 뿐이며, 디바이스는 :9090으로 앱에 직접 접근할 수도 있습니다.

---

API 엔드포인트

디바이스 설정

메서드	경로	설명
GET	/setting/get-device	디바이스 설정 읽기 (비어있으면 204 반환)
POST	/setting/device	디바이스 설정 저장
GET	/setting/get-protocol	프로토콜 설정 읽기 (비어있으면 204 반환)
POST	/setting/protocol	프로토콜 설정 저장
GET	/api/mac	WiFi MAC 주소 읽기

로그 관리

메서드	경로	설명
GET	/setting/log-files	로그 파일 목록 조회 (크기, 수정 일시, 유형)
GET	/setting/log-stats	로그 디렉터리 통계
POST	/setting/log-download	선택한 파일을 tar.gz로 다운로드
POST	/setting/log-compress	비활성 로그 파일 수동 압축
POST	/setting/log-delete	선택한 로그 파일 삭제
GET	/setting/kernel-bundle	커널 로그 번들 .tar.gz 다운로드 (journalctl 텍스트 내보내기 + /opt/log 커널 로그 + 부팅 이력 + pstore) — v1.1.0에서 추가

대시보드 / 모니터링

메서드	경로	설명
GET	/api/health	서버 상태 (가동 시간, DB 백엔드)
GET	/api/system-status	홈 대시보드 페이로드 — 최상위 키: core_app, communication, network, system (v1.0.x~); hardware_modules GNSS + WiFi 펌웨어 (v1.2.0에서 추가); dpworldapp_status 7단계 시작 추적기 + 5-상태 결과 + 런타임 설정 필드 6개 (v1.3.0에서 추가)
GET	/api/support-bundle	진단 zip (상태 + 마스킹된 설정 + 최근 로그 + OS 진단)
POST	/api/action/test-connections	설정된 서버 엔드포인트 TCP 프로브
POST	/api/action/restart-dpworldapp	systemctl을 통해 dpworldapp 재시작

네트워크 적용 엔진 (v1.6.0+)

30초 watchdog를 사용하여 OS 상의 네트워크 설정을 적용/검증/롤백합니다. 전체 내용: docs/network-apply-engine-guide.md.

메서드	경로	설명
GET	/api/network/state	라이브 인터페이스 + drift + watchdog + 최종 적용 + country_pending
GET	/api/network/drift	전역 미적용 변경 수 (경량)
GET	/api/network/apply/status?id=<apply_id>	진행 중인 적용 폴링 (confirm TTL도 이 요청으로 갱신)
GET	/api/network/journal?limit=<n>	적용 저널 tail
GET	/api/network/config	유효한 net_config 읽기 (watchdog 킬스위치)
POST	/api/network/apply	네트워크 필드 적용 (또는 dry_run) — 비동기, apply_id 반환
POST	/api/network/apply/confirm	TTL 내에 eth1 단절성 적용 확인
POST	/api/network/rollback	이전 적용 스냅샷으로 롤백
POST	/api/network/config	net_config watchdog 키 쓰기

Wi-Fi AP

현장 프로비저닝을 위한 Soft-AP(ap0) 관리. 전체 내용: docs/wifi-ap-guide.md.

메서드	경로	설명
GET	/api/network/ap/status	AP 런타임 상태
POST	/api/network/ap/config	ap_config 쓰기
POST	/api/network/ap/apply	AP 설정 적용 (ap0 시작/중지)

펌웨어 OTA

dpworldapp 펌웨어 채널을 통한 업로드 → 사전 검증 → 플래시 → 복원 확인 흐름. 전체 내용: docs/firmware-ota-guide.md.

메서드	경로	설명
GET	/api/firmware/status	현재 OTA 상태 스냅샷
POST	/api/firmware/preflight	업로드 전 사전 검증
POST	/api/firmware/upload	펌웨어 ZIP 업로드
POST	/api/firmware/flash	플래시 실행
POST	/api/firmware/restore-check	플래시 후 복원 검증

서브시스템 내부 구조 (상태 머신, byte-exact 렌더링, 부팅 강화)는 docs/architecture.md 및 위에 링크된 서브시스템별 가이드에 문서화되어 있습니다.

---

기술 스택

• Python 3.10 (stdlib만 사용 — 외부 의존성 없음)
• SQLite3 (기본 설정 저장소)
• 멀티스레드 HTTP 서버 (ThreadingMixIn)
• Vanilla ES-module SPA 프론트엔드 (빌드 단계 없음) — Two Faces 사용자/고급 보기 전환 기능을 포함한 ~18개 페이지 모듈 (src/static/js/view-mode.js)
• 주요 서브시스템: 네트워크 적용 엔진, Wi-Fi AP, 펌웨어 OTA (API 섹션 및 서브시스템별 가이드 참조)