Developer Guide ko

개발자 가이드

이 문서는 NAMO를 소스에서 빌드하거나, 내장 대시보드와 펌웨어를 수정하거나, 호스트 테스트를 실행하거나, 분산 공간 플랫폼 구조를 살펴보려는 개발자를 위한 안내서입니다.

View in English

프로젝트 상태와 범위

NAMO v0.5.5는 공개 베타 단계입니다. 기준 제품은 현재 8 MB Flash와 8 MB PSRAM을 갖춘 Seeed Studio XIAO ESP32S3, LD2450 계열 레이더, ESPHome을 통한 ESP-IDF 프레임워크를 대상으로 합니다.

구현된 플랫폼은 단독 감지와 최대 7개 NAMO 입력으로 구성된 제한형 Fusion Group을 지원합니다. 5대 기기 연결과 실제 역할 승계 시나리오는 검증했습니다. 더 넓은 실기기 설치 조합, 순차 업데이트, 외부 Satellite 승인, Home Assistant 릴리스 검증은 아직 진행 중입니다.

시뮬레이터나 네이티브 테스트가 통과했다는 사실을 실제 ESP32 하드웨어 검증 완료로 해석하면 안 됩니다.

준비 사항

개발을 시작하기 전에 다음 도구를 설치합니다.

• Git
• 저장소의 .nvmrc와 일치하는 Node.js 24
• python -m esphome으로 실행할 수 있는 Python과 ESPHome
• tools/platform-sim/requirements.txt에 선언된 Python 패키지
• 네이티브 테스트용 C++ 컴파일러인 MSVC cl, g++ 또는 clang++
• Windows 펌웨어 빌드 래퍼를 사용할 경우 PowerShell

저장소를 복제하고 개발 의존성을 설치합니다.

git clone https://github.com/David2766/NAMO-aint-motion-only.git
cd NAMO-aint-motion-only
python -m pip install esphome
python -m pip install -r tools/platform-sim/requirements.txt
cd dashboard
npm ci
cd ..

빌드 오류를 조사하기 전에 주요 도구가 실행되는지 확인합니다.

node --version
npm --version
python -m esphome version

저장소 구성

경로	역할
namo.yaml	공개 ESPHome 펌웨어 진입점과 빌드 substitution
packages/namo/	공통 ESPHome 패키지, 핀, entity와 기능 설정
components/radar_api_server/	펌웨어 HTTP API, 공간 플랫폼 런타임, 내장 대시보드 asset과 서명 OTA 구현
dashboard/src/web/	내장 대시보드 애플리케이션
dashboard/src/core/	공용 프론트엔드 상태, geometry, 평면도와 protocol 로직
tools/presence-replay/	replay 도구와 네이티브 C++ 테스트
tools/platform-sim/	protocol fixture, simulation과 Python contract 테스트
tools/namo-cluster/	2대부터 7대까지의 호스트 통합 및 장애 테스트
custom_components/namo/	Home Assistant custom integration
hardware/	기준 PCB, 케이스, 조립 파일과 하드웨어 문서
docs/	버전 관리되는 API, architecture, signing, tracking과 roadmap 계약

대시보드 개발

가상 데이터가 제공되는 브라우저 대시보드를 실행합니다.

cd dashboard
npm run dev:web

다음 주소를 엽니다.

http://localhost:5173/dashboard/?demo=1

초기 설정 화면은 다음 주소에서 볼 수 있습니다.

http://localhost:5173/dashboard/?setup=1

레이아웃, 상호작용, 평면도와 일반 UI 상태는 mock 모드에서 개발할 수 있습니다. 하지만 ESP32 HTTP 동작, 영구 저장, 타이밍, 기기 연결과 장애 복구까지 검증하지는 않습니다.

대시보드 변경을 펌웨어에 내장하기 전에 다음 검사를 실행합니다.

cd dashboard
npm run typecheck
npm run lint
npm test
npm run build:dashboard

build:dashboard는 components/radar_api_server/dashboard_assets.h를 생성하고 대시보드 버전을 갱신합니다. 커밋하기 전에 두 변경 사항을 모두 검토해야 합니다.

펌웨어 개발

저장소 루트에서 공개 설정을 검증합니다.

python -m esphome config namo.yaml

Windows에서 사용하는 일반적인 무서명 개발 빌드는 다음과 같습니다.

.\scripts\build-firmware.ps1 -Signer none

이 래퍼는 기본적으로 대시보드 빌드와 clean build를 실행합니다. 생성 파일과 빌드 상태가 최신이라고 확인한 경우에만 -NoDashboard 또는 -NoClean을 사용합니다.

일반 빌드가 성공하면 version.json의 개발 suffix가 올라가고 펌웨어 버전이 동기화됩니다. 빌드가 실패하면 이전 버전 파일을 복원합니다. 빌드가 읽기 전용이라고 가정하지 말고 남은 변경 사항을 확인해야 합니다.

같은 빌드 파이프라인의 cross-platform Node 진입점은 다음과 같습니다.

node scripts/compile-firmware.mjs --signer none --dashboard --clean --config namo.yaml

무서명 개발 빌드는 로컬 소스 개발과 USB 설치에 사용할 수 있습니다. 개인 Wi-Fi 설정, API 키, 서명 자료 또는 컴퓨터별 설정이 들어간 펌웨어는 공개하면 안 됩니다.

테스트

표준 테스트는 dashboard/에서 실행합니다.

npm test

이 명령은 초기 설정 화면 번역 검사, 빌드 및 서명 스크립트 테스트, 네이티브 C++ 테스트, presence replay 테스트, 플랫폼 protocol 테스트와 대시보드 테스트를 실행합니다.

필요한 범위만 실행할 때는 다음 명령을 사용합니다.

npm run test:scripts
npm run test:native
npm run test:replay
npm run test:platform
npx vitest run

일반 npm test는 지원되는 호스트 컴파일러가 없으면 네이티브 테스트를 skipped로 표시합니다. 네이티브 테스트가 반드시 실행되어야 한다면 누락 시 실패하는 npm run test:native를 사용해야 합니다.

제한형 coordinator, 재시작, network partition과 재합류는 tools/namo-cluster로 테스트할 수 있습니다. 이 도구는 펌웨어 HTTP pairing 또는 calibration handler를 실행하지 않으며 실기기 테스트를 대신하지 않습니다.

API와 Protocol 변경

HTTP endpoint를 변경하거나 추가하기 전에 API 계약을 읽습니다. 응답 schema, status code, error code, 호환 동작과 frontend 및 firmware 조율의 기준 문서입니다.

API를 변경할 때는 다음 규칙을 지킵니다.

1. 코드와 함께 영문 및 한국어 API 계약을 갱신합니다.
2. 기계가 읽는 error code와 번역되는 UI 문구를 분리합니다.
3. 버전이 있는 migration을 정의하지 않았다면 기존 field를 유지합니다.
4. mock 응답과 frontend consumer를 함께 갱신합니다.
5. 성공, 실패, timeout과 readback 동작을 다루는 contract 테스트를 추가합니다.

Site, Group, Configuration Owner, pairing, calibration 또는 fusion을 변경한다면 코드를 수정하기 전에 플랫폼 아키텍처와 구현 로드맵도 읽어야 합니다.

펌웨어 서명

공식 NAMO Release 키는 저장소에 들어 있지 않습니다. 자신의 Root, Release와 Developer 키를 생성하면 자신이 관리하는 기기를 위한 독립 trust chain이 만들어집니다. 공식 NAMO release가 되거나 공식 NAMO 펌웨어가 신뢰하는 OTA package가 만들어지는 것은 아닙니다.

무서명 빌드에는 서명 키가 필요하지 않습니다. 자체 서명 기기 계열을 관리하려는 개발자는 offline Root 키 보관, 역할별 키 분리, rollback 방지, 복구와 실기기 release gate를 포함한 전체 펌웨어 서명 문서를 따라야 합니다.

개인키, passphrase, DPAPI secret cache, 개인용으로 생성한 firmware 또는 key directory를 커밋하면 안 됩니다.

검증 단계

검증 결과는 다음 단계에 맞춰 정확하게 표시합니다.

• 정적 검사: typecheck, lint, configuration 검증 또는 소스 검사만 완료
• 호스트 테스트: JavaScript, Python, 네이티브 C++, replay, simulator 또는 cluster 테스트 통과
• 컴파일: ESP32 firmware image 빌드 성공
• 실기기 테스트: 명시한 실제 hardware에서 해당 흐름 실행
• 릴리스 검증: 기능과 hardware 조합에 필요한 모든 release gate 통과

issue, pull request 또는 release note에서 한 단계를 다른 단계로 대신 표현하면 안 됩니다.

기여 전 확인 사항

변경 사항을 제출하기 전에 다음을 확인합니다.

• 하나의 동작이나 서로 밀접한 동작 묶음에만 변경 범위를 제한합니다.
• 개발 중에는 관련 테스트를 실행하고 제출 전에는 표준 테스트 전체를 실행합니다.
• frontend production 코드를 바꿨다면 내장 대시보드 asset을 다시 빌드하고 변경 내용을 검토합니다.
• 동작이 바뀌면 영문과 한국어 계약 또는 안내서를 함께 갱신합니다.
• 완료한 검증 단계와 하지 못한 단계를 명시합니다.
• credential, 로컬 IP, capture, 생성된 object 파일과 개인 build path를 제거합니다.
• 수정 결과물을 재배포하기 전에 software license와 별도 hardware license를 확인합니다.

software와 firmware는 AGPL-3.0-or-later를 사용합니다. hardware/ 아래 파일은 CC BY-NC-SA 4.0을 사용하며, third-party component는 각각의 license를 유지합니다.

더 읽을 문서

• 문서 인덱스
• 플랫폼 아키텍처
• 구현 로드맵
• API 계약
• 펌웨어 서명
• Home Assistant integration
• 하드웨어 가이드