Skip to content

Developer Guide

Jump to bottom
David2766 edited this page Aug 21, 2026 · 1 revision

Developer Guide

This guide is for developers who want to build NAMO from source, modify the embedded dashboard or firmware, run the host-side test suites, or study the distributed spatial platform.

한국어로 보기

Project Status and Scope

NAMO v0.5.5 is a public beta. The reference product currently targets a Seeed Studio XIAO ESP32S3 with 8 MB Flash and 8 MB PSRAM, an LD2450-series radar, and the ESP-IDF framework through ESPHome.

The implemented platform supports standalone sensing and a bounded Fusion Group of up to seven NAMO inputs. Five-device pairing and physical role-handover scenarios have been exercised. Wider physical installation matrices, rolling upgrades, third-party Satellite admission, and Home Assistant release verification remain ongoing.

Do not treat a passing simulator or native test as proof that a change has passed on real ESP32 hardware.

Prerequisites

Install these tools before starting:

  • Git
  • Node.js 24, matching the repository's .nvmrc
  • Python with ESPHome available as python -m esphome
  • The Python packages in tools/platform-sim/requirements.txt
  • A host C++ compiler for native tests: MSVC cl, g++, or clang++
  • PowerShell when using the Windows firmware build wrapper

Clone the repository and install the development dependencies:

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 ..

Confirm the main tools before debugging a build failure:

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

Repository Map

Path Purpose
namo.yaml Public ESPHome firmware entry point and build substitutions
packages/namo/ Shared ESPHome packages, pins, entities, and feature configuration
components/radar_api_server/ Firmware HTTP API, spatial platform runtime, embedded dashboard assets, and signed OTA implementation
dashboard/src/web/ Embedded dashboard application
dashboard/src/core/ Shared frontend state, geometry, floorplan, and protocol logic
tools/presence-replay/ Replay tools and native C++ tests
tools/platform-sim/ Protocol fixtures, simulations, and Python contract tests
tools/namo-cluster/ Two-to-seven-process host integration and fault testing
custom_components/namo/ Home Assistant custom integration
hardware/ Reference PCB, enclosure, assembly files, and hardware documentation
docs/ Versioned API, architecture, signing, tracking, and roadmap contracts

Dashboard Development

Run the browser dashboard with mock data:

cd dashboard
npm run dev:web

Open:

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

The initial setup page is available at:

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

Use the mock mode for layout, interaction, floorplan, and normal UI-state work. It does not prove ESP32 HTTP behavior, persistence, timing, pairing, or hardware recovery.

Before embedding dashboard changes into firmware, run:

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

build:dashboard generates components/radar_api_server/dashboard_assets.h and updates the dashboard version. Review both generated changes before committing them.

Firmware Development

Validate the public configuration from the repository root:

python -m esphome config namo.yaml

On Windows, the normal unsigned development build is:

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

The wrapper builds the dashboard and performs a clean build by default. Use -NoDashboard or -NoClean only when the corresponding generated files and build state are already known to be current.

A successful normal build advances the development suffix in version.json and synchronizes the firmware version. A failed build restores the previous version files. Review these changes instead of assuming the build is read-only.

The cross-platform Node entry point for the same build pipeline is:

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

An unsigned development build is suitable for local source work and USB installation. Do not publish firmware containing private Wi-Fi settings, API keys, signing material, or machine-specific configuration.

Tests

The standard test command is run from dashboard/:

npm test

It runs setup-page localization checks, build and signing script tests, native C++ tests, presence replay tests, platform protocol tests, and dashboard tests.

Useful focused commands are:

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

The normal npm test reports native tests as skipped when no supported host compiler is available. npm run test:native fails instead, which is the correct command when native coverage is required.

Use tools/namo-cluster for bounded coordinator, restart, partition, and rejoin testing. It does not execute the firmware HTTP pairing or calibration handlers and does not replace physical-device testing.

API and Protocol Changes

Before changing or adding an HTTP endpoint, read the API contract. It is the source of truth for response schemas, status codes, error codes, compatibility behavior, and frontend/firmware coordination.

For an API change:

  1. Update the English and Korean API contracts with the code change.
  2. Keep machine-readable error codes separate from translated UI text.
  3. Preserve existing fields unless a versioned migration is defined.
  4. Update mock responses and frontend consumers together.
  5. Add contract tests for success, failure, timeout, and readback behavior.

For Site, Group, Configuration Owner, pairing, calibration, or fusion changes, also read the platform architecture and implementation roadmap before editing code.

Firmware Signing

Official NAMO Release keys are not part of the repository. Generating your own Root, Release, and Developer keys creates an independent trust chain for your own devices; it does not create an official NAMO release or an OTA package trusted by official NAMO firmware.

Unsigned builds require no signing keys. Developers maintaining their own signed device line should follow the complete firmware signing guide, including offline Root-key custody, separate role keys, rollback protection, recovery, and physical release gates.

Never commit private keys, passphrases, DPAPI secret caches, generated personal firmware, or a key directory.

Verification Levels

Report verification precisely:

  • Static: typecheck, lint, configuration validation, or source inspection only
  • Host tested: JavaScript, Python, native C++, replay, simulator, or cluster tests passed
  • Compiled: an ESP32 firmware image was built successfully
  • Device tested: the stated workflow was exercised on named physical hardware
  • Release verified: all release gates for that feature and hardware matrix passed

Do not replace one level with another in an issue, pull request, or release note.

Contribution Checklist

Before submitting a change:

  • Keep the change scoped to one behavior or closely related set of behaviors.
  • Run the focused tests while developing, then the standard test suite before submission.
  • Rebuild and review embedded dashboard assets when frontend production code changes.
  • Update English and Korean contracts or guides together when behavior changes.
  • State which verification levels were completed and which were not.
  • Remove credentials, local IP addresses, captures, generated object files, and private build paths.
  • Check the software license and the separate hardware license before redistributing modified work.

Software and firmware use AGPL-3.0-or-later. Files under hardware/ use CC BY-NC-SA 4.0. Third-party components retain their own licenses.

Further Reading

NAMO Wiki

English

한국어

Clone this wiki locally