setDrag('min')} style={`position: absolute; top: 50%; left: calc(${tMin*100}% - 9px); transform: translateY(-50%); width: 18px; height: 18px; border-radius: 50%; background: var(--text-0); border: 3px solid var(--acc-orange); cursor: grab; box-shadow: var(--shadow-1);`}/>
+
setDrag('max')} style={`position: absolute; top: 50%; left: calc(${tMax*100}% - 9px); transform: translateY(-50%); width: 18px; height: 18px; border-radius: 50%; background: var(--text-0); border: 3px solid var(--acc-orange); cursor: grab; box-shadow: var(--shadow-1);`}/>
+
+ );
+}
+
+/* SVG topology diagrams used by Mesh screen. */
+export function TopologyDiagram({ kind, size = 96 }: { kind: 'straight'|'l_shape'|'u_shape'|'custom'; size?: number }) {
+ const stroke = 'var(--text-2)';
+ const acc = 'var(--acc-orange)';
+ if (kind === 'straight') return (
+
+ );
+ if (kind === 'l_shape') return (
+
+ );
+ if (kind === 'u_shape') return (
+
+ );
+ return (
+
+ );
+}
+
+/* Two-line chart for Motion screen β raw vs smoothed distance. */
+export function LineChart({ raw, smooth, width = 600, height = 180 }: {
+ raw: number[]; smooth: number[]; width?: number; height?: number;
+}) {
+ const lo = 0, hi = 300;
+ const range = hi - lo;
+ const toPath = (data: number[]) => data.map((v, i) => {
+ const x = (i / Math.max(1, data.length - 1)) * width;
+ const y = height - ((v - lo) / range) * height;
+ return `${i === 0 ? 'M' : 'L'}${x.toFixed(1)},${y.toFixed(1)}`;
+ }).join(' ');
+ return (
+
+ );
+}
+
+/* HSV β RGB conversion for the color wheel. */
+export function hsv2rgb(h: number, s: number, v: number): [number, number, number] {
+ h = ((h % 360) + 360) % 360;
+ const c = v * s, x = c * (1 - Math.abs(((h / 60) % 2) - 1)), m = v - c;
+ let r = 0, g = 0, b = 0;
+ if (h < 60) [r, g, b] = [c, x, 0];
+ else if (h < 120) [r, g, b] = [x, c, 0];
+ else if (h < 180) [r, g, b] = [0, c, x];
+ else if (h < 240) [r, g, b] = [0, x, c];
+ else if (h < 300) [r, g, b] = [x, 0, c];
+ else [r, g, b] = [c, 0, x];
+ return [Math.round((r + m) * 255), Math.round((g + m) * 255), Math.round((b + m) * 255)];
+}
+export function rgb2hex(r: number, g: number, b: number) {
+ return '#' + [r, g, b].map(n => Math.max(0, Math.min(255, n)).toString(16).padStart(2, '0')).join('').toUpperCase();
+}
+export function hex2rgb(hex: string): [number, number, number] {
+ const h = hex.replace('#', '').padEnd(6, '0').slice(0, 6);
+ return [parseInt(h.slice(0,2), 16), parseInt(h.slice(2,4), 16), parseInt(h.slice(4,6), 16)];
+}
+
+/* Animated logo mark β triangle "A" with concentric pulse rings.
+ * Pulse intensity scales with proximity (closer target = brighter).
+ * Faithful port of frontend/design-source/project/app.jsx LogoMark. */
+export function LogoMark({ size = 36, distance = 0 }: { size?: number; distance?: number }) {
+ const pulseStrength = Math.max(0.2, Math.min(1, (250 - distance) / 200));
+ return (
+
+
+
+
+ );
+}
+
+/* Wordmark with gradient "Sense" β paired with LogoMark in sidebar/header. */
+export function Wordmark({ font = 16, sub = 10, mono = false, version, target }: {
+ font?: number; sub?: number; mono?: boolean; version?: string; target?: string;
+}) {
+ if (mono) return null;
+ return (
+
+
+ AmbiSense
+
+
+ {version || ''} Β· {target || ''}
+
+
+ );
+}
diff --git a/frontend/src/components.tsx b/frontend/src/components.tsx
new file mode 100644
index 0000000..a569c4e
--- /dev/null
+++ b/frontend/src/components.tsx
@@ -0,0 +1,130 @@
+/** Shared UI atoms. */
+import { ComponentChildren, JSX } from 'preact';
+import { useEffect, useState } from 'preact/hooks';
+
+export function Card({ title, right, children }: {
+ title?: string; right?: ComponentChildren; children: ComponentChildren;
+}) {
+ return (
+
+ {title && (
+
+
{title}
+ {right}
+
+ )}
+
{children}
+
+ );
+}
+
+export function Toggle({ value, onChange, large }: {
+ value: boolean; onChange: (v: boolean) => void; large?: boolean;
+}) {
+ return (
+
onChange(!value)}
+ role="switch"
+ aria-checked={value}
+ />
+ );
+}
+
+export function Field({ label, children }: { label: string; children: ComponentChildren }) {
+ return (
+
+
+ {children}
+
+ );
+}
+
+export function Slider({ value, min, max, onChange, suffix }: {
+ value: number; min: number; max: number; onChange: (v: number) => void; suffix?: string;
+}) {
+ return (
+
+ onChange(parseInt((e.target as HTMLInputElement).value))}
+ />
+
+ {value}{suffix || ''}
+
+
+ );
+}
+
+export function Toast({ msg, kind, onDone }: { msg: string; kind: 'ok'|'err'; onDone: () => void }) {
+ useEffect(() => {
+ const t = setTimeout(onDone, kind === 'err' ? 4500 : 2200);
+ return () => clearTimeout(t);
+ }, []);
+ return
{msg}
;
+}
+
+export function Row({ k, v }: { k: string; v: ComponentChildren }) {
+ return (
+
+ {k}
+ {v}
+
+ );
+}
+
+export function Dot({ kind }: { kind: 'ok'|'warn'|'err'|'off' }) {
+ return
;
+}
+
+/* Optimistic save helper: shows a toast based on a promise. */
+export function useToaster() {
+ const [t, setT] = useState<{ msg: string; kind: 'ok'|'err' } | null>(null);
+ return {
+ toast: t,
+ set: (msg: string, kind: 'ok'|'err' = 'ok') => setT({ msg, kind }),
+ clear: () => setT(null),
+ track: async
(p: Promise, okMsg = 'Saved'): Promise => {
+ try { const r = await p; setT({ msg: okMsg, kind: 'ok' }); return r; }
+ catch (e: any) { setT({ msg: e.message || 'Failed', kind: 'err' }); return undefined; }
+ }
+ };
+}
+
+/* HSV color picker β simple wheel + lightness slider. Returns r/g/b. */
+export function ColorPicker({ rgb, onChange }: { rgb: [number,number,number]; onChange: (r:number,g:number,b:number)=>void }) {
+ const presets: [number,number,number][] = [
+ [255,255,255], [255,170,80], [255,80,80], [255,80,180],
+ [180,80,255], [80,180,255], [80,255,180], [255,255,80],
+ ];
+ return (
+
+ {presets.map(p => {
+ const on = p[0]===rgb[0] && p[1]===rgb[1] && p[2]===rgb[2];
+ return (
+
onChange(p[0], p[1], p[2])}
+ />
+ );
+ })}
+ v.toString(16).padStart(2,'0')).join('')}`}
+ onInput={(e) => {
+ const hex = (e.target as HTMLInputElement).value;
+ const r = parseInt(hex.slice(1,3),16);
+ const g = parseInt(hex.slice(3,5),16);
+ const b = parseInt(hex.slice(5,7),16);
+ onChange(r,g,b);
+ }}
+ style="width: 36px; height: 36px; border: 1px solid var(--line); border-radius: 8px; padding: 2px; background: var(--bg-1); cursor: pointer;"
+ />
+
+ );
+}
diff --git a/frontend/src/led_preview.tsx b/frontend/src/led_preview.tsx
new file mode 100644
index 0000000..ccdd872
--- /dev/null
+++ b/frontend/src/led_preview.tsx
@@ -0,0 +1,198 @@
+/** LED strip canvas preview. Mirrors the firmware's mode logic so the
+ on-screen animation matches what a real strip would show. */
+import { useEffect, useRef } from 'preact/hooks';
+
+export const LED_MODE_NAMES = [
+ 'Standard','Rainbow','Color Wave','Breathing','Solid',
+ 'Comet','Pulse','Fire','Theater Chase','Dual Scan','Motion Particles',
+];
+
+interface PreviewProps {
+ mode: number;
+ rgb: [number, number, number];
+ count: number;
+ brightness: number;
+ span: number;
+ distance?: number;
+ minD?: number;
+ maxD?: number;
+ height?: number;
+ speed?: number;
+ intensity?: number;
+}
+
+interface RGB { r: number; g: number; b: number; }
+
+const wheel = (p: number): RGB => {
+ if (p < 85) return { r: p*3, g: 255-p*3, b: 0 };
+ if (p < 170) { p -= 85; return { r: 255-p*3, g: 0, b: p*3 }; }
+ p -= 170; return { r: 0, g: p*3, b: 255-p*3 };
+};
+const dim = (c: RGB, k: number): RGB => ({ r: (c.r*k)|0, g: (c.g*k)|0, b: (c.b*k)|0 });
+
+export function LedPreview(p: PreviewProps) {
+ const ref = useRef
(null);
+ const stateRef = useRef<{ step: number; particles: any[]; heat: number[]; prev: RGB[] }>({
+ step: 0, particles: [], heat: [], prev: [],
+ });
+
+ useEffect(() => {
+ const canvas = ref.current;
+ if (!canvas) return;
+ const ctx = canvas.getContext('2d');
+ if (!ctx) return;
+
+ let raf = 0;
+ let stop = false;
+
+ const draw = () => {
+ if (stop) return;
+ /* Pause when tab is hidden β phones don't need to burn battery on
+ * an off-screen canvas. The next visibilitychange resumes us. */
+ if (document.hidden) {
+ raf = requestAnimationFrame(draw);
+ return;
+ }
+ const w = canvas.width = canvas.clientWidth * window.devicePixelRatio;
+ const h = canvas.height = (p.height || 80) * window.devicePixelRatio;
+ const n = Math.max(1, Math.min(p.count, 300)); /* preview cap */
+ const pxW = w / n;
+ ctx.clearRect(0, 0, w, h);
+
+ const s = stateRef.current;
+ if (s.heat.length !== n) s.heat = new Array(n).fill(0);
+ if (s.prev.length !== n) s.prev = new Array(n).fill({r:0,g:0,b:0});
+
+ const base: RGB = { r: p.rgb[0], g: p.rgb[1], b: p.rgb[2] };
+ const br = (p.brightness ?? 255) / 255;
+ const minD = p.minD ?? 30, maxD = p.maxD ?? 300;
+ const span = Math.max(1, p.span);
+ const avail = Math.max(0, n - span);
+ const dist = p.distance ?? minD + Math.abs(Math.sin(s.step * 0.01)) * (maxD - minD);
+ const start = ((dist - minD) / (maxD - minD) * avail) | 0;
+ const espd = (p.speed ?? 50) / 50;
+ const eint = (p.intensity ?? 50) / 100;
+
+ const paint = (i: number, c: RGB) => {
+ if (i < 0 || i >= n) return;
+ ctx.fillStyle = `rgb(${(c.r*br)|0},${(c.g*br)|0},${(c.b*br)|0})`;
+ ctx.fillRect(i * pxW, 0, pxW + 1, h);
+ };
+
+ switch (p.mode) {
+ case 0: { /* standard */
+ for (let i = 0; i < n; i++) paint(i, dim(base, 0.05));
+ for (let i = start; i < Math.min(start + span, n); i++) paint(i, base);
+ break;
+ }
+ case 1: { /* rainbow */
+ const off = (s.step * espd) & 0xFF;
+ for (let i = 0; i < n; i++) paint(i, wheel(((i*256/n + off) | 0) & 0xFF));
+ break;
+ }
+ case 2: { /* color_wave */
+ for (let i = 0; i < n; i++) {
+ const phase = i / n * 6.28 + s.step * 0.05 * espd;
+ let k = (Math.sin(phase) + 1) * 0.5;
+ k = k * eint + (1 - eint) * 0.4;
+ paint(i, dim(wheel(((i*256/n + s.step) | 0) & 0xFF), k));
+ }
+ break;
+ }
+ case 3: { /* breathing */
+ let k = (Math.sin(s.step * 0.05 * espd) + 1) * 0.5;
+ k = 0.1 + 0.9 * k * eint;
+ for (let i = 0; i < n; i++) paint(i, dim(base, k));
+ break;
+ }
+ case 4: { /* solid */
+ for (let i = 0; i < n; i++) paint(i, base);
+ break;
+ }
+ case 5: { /* comet */
+ const fade = 0.85;
+ for (let i = 0; i < n; i++) {
+ s.prev[i] = dim(s.prev[i], fade);
+ paint(i, s.prev[i]);
+ }
+ for (let i = 0; i < 3; i++) {
+ const px = start + i;
+ if (px < n) { s.prev[px] = base; paint(px, base); }
+ }
+ break;
+ }
+ case 6: { /* pulse */
+ for (let i = 0; i < n; i++) paint(i, {r:0,g:0,b:0});
+ const max_r = n / 4;
+ for (let p2 = 0; p2 < 3; p2++) {
+ const phase = p2 * 2;
+ const r = ((s.step * 0.2 + phase) % max_r);
+ for (let off = -((r)|0); off <= ((r)|0); off++) {
+ const k = (1 - Math.abs(off / Math.max(0.1, r)) ** 2) * eint;
+ const idx = start + off;
+ if (idx >= 0 && idx < n && k > 0) paint(idx, dim(base, k));
+ }
+ }
+ break;
+ }
+ case 7: { /* fire */
+ for (let i = 0; i < n; i++) s.heat[i] = Math.max(0, s.heat[i] - (Math.random()*55 + 2)|0);
+ for (let i = n-1; i >= 2; i--) s.heat[i] = ((s.heat[i-1] + s.heat[i-2]*2) / 3)|0;
+ if (Math.random() < 0.5) { const y = (Math.random()*7)|0; s.heat[y] = Math.min(255, s.heat[y] + 160 + ((Math.random()*96)|0)); }
+ for (let i = 0; i < n; i++) {
+ const t = ((s.heat[i] * 191) / 255)|0;
+ let c: RGB;
+ if (t < 64) c = {r: t*4, g: 0, b: 0};
+ else if (t < 128) c = {r: 255, g: (t-64)*4, b: 0};
+ else c = {r: 255, g: 255, b: (t-128)*4};
+ paint(i, c);
+ }
+ break;
+ }
+ case 8: { /* theater_chase */
+ const gap = 3, ph = s.step % gap;
+ for (let i = 0; i < n; i++) paint(i, ((i+ph) % gap === 0) ? base : {r:0,g:0,b:0});
+ break;
+ }
+ case 9: { /* dual_scan */
+ for (let i = 0; i < n; i++) paint(i, {r:0,g:0,b:0});
+ const sw = 4, p1 = (s.step|0) % n, p2 = n - 1 - ((s.step|0) % n);
+ const inv: RGB = { r: 255-base.r, g: 255-base.g, b: 255-base.b };
+ for (let off = -sw; off <= sw; off++) {
+ const k = 1 - Math.abs(off/sw);
+ if (p1+off >= 0 && p1+off < n) paint(p1+off, dim(base, k));
+ if (p2+off >= 0 && p2+off < n) paint(p2+off, dim(inv, k));
+ }
+ if (start >= 0 && start < n) paint(start, {r:255,g:255,b:255});
+ break;
+ }
+ case 10: { /* motion_particles */
+ for (const part of s.particles) {
+ if (!part.active) continue;
+ part.pos += part.vel; part.bright -= 0.02;
+ if (part.bright <= 0 || part.pos < 0 || part.pos >= n) part.active = false;
+ }
+ const spawn = 1 + (eint * 4)|0;
+ for (let i = 0; i < spawn; i++) {
+ if (s.particles.length < 50) s.particles.push({ active: true, pos: start + (Math.random()*7-3), vel: (Math.random()*2-1)*espd*0.6, bright: 1 });
+ else for (const part of s.particles) if (!part.active) { part.active = true; part.pos = start + (Math.random()*7-3); part.vel = (Math.random()*2-1)*espd*0.6; part.bright = 1; break; }
+ }
+ for (let i = 0; i < n; i++) paint(i, {r:0,g:0,b:0});
+ for (const part of s.particles) {
+ if (!part.active) continue;
+ const px = part.pos|0;
+ if (px >= 0 && px < n) paint(px, dim(base, part.bright));
+ }
+ break;
+ }
+ }
+
+ s.step++;
+ raf = requestAnimationFrame(draw);
+ };
+ raf = requestAnimationFrame(draw);
+ return () => { stop = true; cancelAnimationFrame(raf); };
+ }, [p.mode, p.rgb[0], p.rgb[1], p.rgb[2], p.count, p.brightness, p.span, p.distance, p.speed, p.intensity]);
+
+ return ;
+}
diff --git a/frontend/src/main.tsx b/frontend/src/main.tsx
new file mode 100644
index 0000000..c40b855
--- /dev/null
+++ b/frontend/src/main.tsx
@@ -0,0 +1,134 @@
+/** App shell β sidebar (logo + nav + IP/board footer) + sticky header
+ * (page name Β· hostname.local + live distance chip + RSSI + theme).
+ * Faithful port of frontend/design-source/project/app.jsx. */
+import { render } from 'preact';
+import { useEffect, useState } from 'preact/hooks';
+import { getJSON, liveSocket } from './api';
+import { Toast, useToaster } from './components';
+import { Icon, LogoMark, Wordmark } from './atoms';
+import { ScreenLive, ScreenLeds, ScreenMotion, ScreenMesh, ScreenHardware, ScreenNetwork, ScreenSystem } from './screens';
+import './styles.css';
+
+type Tab = 'live'|'leds'|'motion'|'mesh'|'hardware'|'network'|'system';
+
+const TABS: { id: Tab; name: string; icon: string }[] = [
+ { id: 'live', name: 'Live', icon: 'dashboard' },
+ { id: 'leds', name: 'LEDs', icon: 'led' },
+ { id: 'motion', name: 'Motion', icon: 'motion' },
+ { id: 'mesh', name: 'Mesh', icon: 'mesh' },
+ { id: 'hardware', name: 'Hardware', icon: 'chip' },
+ { id: 'network', name: 'Network', icon: 'wifi' },
+ { id: 'system', name: 'System', icon: 'settings' },
+];
+
+function App() {
+ const [tab, setTab] = useState(localStorage.getItem('ambitab') as Tab || 'live');
+ const [version, setVersion] = useState({});
+ const [settings, setSettings] = useState({});
+ const [live, setLive] = useState({ distance: 0, raw: 0, direction: 0, rssi: 0, heap: 0, uptime: 0, peers: 0, healthy: 0 });
+ const [theme, setTheme] = useState<'dark'|'light'>(localStorage.getItem('ambitheme') as any || 'dark');
+ const [wsConnected, setWsConnected] = useState(false);
+ const t = useToaster();
+
+ const reload = () => {
+ getJSON('/api/version').then(setVersion).catch(() => {});
+ getJSON('/api/settings').then(setSettings).catch(() => {});
+ };
+
+ useEffect(() => { reload(); }, []);
+ useEffect(() => {
+ const id = setInterval(() => { if (!document.hidden) getJSON('/api/version').then(setVersion).catch(() => {}); }, 30000);
+ return () => clearInterval(id);
+ }, []);
+ useEffect(() => {
+ const close = liveSocket((data) => { setLive(data); setWsConnected(true); });
+ return () => { close(); setWsConnected(false); };
+ }, []);
+ useEffect(() => { document.documentElement.setAttribute('data-theme', theme); localStorage.setItem('ambitheme', theme); }, [theme]);
+ useEffect(() => { localStorage.setItem('ambitab', tab); }, [tab]);
+
+ const state = { live, settings, version, toast: t.toast, setToast: t.set, reload };
+ const switcher: Record = { live: ScreenLive, leds: ScreenLeds, motion: ScreenMotion, mesh: ScreenMesh, hardware: ScreenHardware, network: ScreenNetwork, system: ScreenSystem };
+ const Screen = switcher[tab];
+ const tabName = TABS.find(x => x.id === tab)?.name || '';
+ const dist = Math.round(live.distance || 0);
+ const ipShort = version.ip || 'β';
+ const radarKind = settings.radar_kind ? settings.radar_kind.toUpperCase() : '';
+ const boardSub = `${(version.target || 'esp32').toUpperCase()}${radarKind ? ` Β· ${radarKind}` : ''}`;
+ const fwVer = version.version || 'v6.x';
+ const fwTarget = (version.target || 'esp32').toUpperCase();
+
+ return (
+
+ {/* Sidebar β desktop only */}
+
+
+ {/* Main column */}
+
+ {/* Sticky header */}
+
+
+ {/* Page content */}
+
+
+
+
+ {/* Mobile bottom-tabs */}
+
+
+ {t.toast &&
}
+
+
+
{title}
+ {sub &&
{sub}
}
+
+ {right}
+
+
+
+
+
+
System {sysEn ? 'active' : 'paused'}
+
{sysEn ? 'Radar, mesh, and LED output running' : 'All output muted, mesh idle'}
+
+
+
+
+
+
+
+
Distance
+
+ {dist}cm
+
+
+
+ {inWindow ? 'in window' : 'outside'}
+
+ min {minD}
+ max {maxD}
+ {live.direction === 0 ? 'still' : live.direction < 0 ? 'closer β' : 'away β'}
+
+
+
+
+
+
+
+
+
Live LED preview Β· {LED_MODE_NAMES[settings.light_mode ?? 0]}
+
distance {dist} cm
+
+
+
+
+
+
+ -65 ? 'dBm Β· excellent' : (live.rssi||0) > -75 ? 'dBm Β· good' : 'dBm Β· weak'}/>
+
+
+
+
+
+
+
+
+
Mesh{live.peers > 0 ? 'peer' : 'standalone'}
+
+
{live.peers || 0} peer{(live.peers||0) === 1 ? '' : 's'} Β· {live.healthy||0} healthy
+ {(live.peers || 0) === 0 && (
+
+ No peers discovered. Open Mesh tab to start a 30 s pairing window.
+
+ )}
+
+
+
+
+
{label}
+
{value}
+ {sub &&
{sub}
}
+
+
+ Live preview Β· {LED_MODE_NAMES[mode]}
+ distance {Math.round(live.distance||0)} cm
+
+
+
+
+
Mode
+
+
+ {LED_MODE_NAMES.map((name, i) => (
+
+ ))}
+
+
+
+
+
+ {showColor && (
+
+
Color
+
+
+
+
{
+ const h = (e.target as HTMLInputElement).value;
+ const [r, g, b] = hex2rgb(h);
+ save({ r, g, b });
+ }}/>
+
+
Presets
+
+ {presets.map(p => {
+ const [r, g, b] = hex2rgb(p);
+ const on = hex.toUpperCase() === p.toUpperCase();
+ return (
+
+
+
+ )}
+
+
+
{LED_MODE_NAMES[mode]} parameters
+
+
save({ brightness: v })} min={0} max={255}/>
+ {showSpeed && save({ effect_speed: v })} min={0} max={100}/>}
+ {showIntensity && save({ effect_intensity: v })} min={0} max={100}/>}
+ {showTrail && save({ trail: v })} min={0} max={20}/>}
+ {showDirection && (
+
+
+
Directional light
+
Brighter side leads movement
+
+
save({ dir_light: v ? 1 : 0 })}/>
+
+
+
Background mode
+
Faint always-on color when idle
+
+
save({ bg_mode: v ? 1 : 0 })}/>
+
+
+
+
+
Layout
+
+
+
+ Distance window
+ {s.min_distance ?? 30}β{s.max_distance ?? 300} cm
+
+
save({ min_distance: minVal, max_distance: maxVal })} min={0} max={500}/>
+
+
save({ span: v })} min={1} max={150}/>
+ save({ center_shift: v })} min={-100} max={100}/>
+ save({ led_count: v })} min={1} max={1500}/>
+
+
+
+
+
+
+
Motion smoothing
+
{enabled ? 'Filters jitter and predicts velocity' : 'Disabled β strip follows raw radar'}
+
+
save({ motion_enabled: v ? 1 : 0 })}/>
+
+
+
+
+ Raw vs smoothed Β· last 16 s
+
+ raw
+
+
+ smoothed
+
+ {Math.round(live.distance||0)} cm
+
+
+
+
+
Algorithm
+
+
+ {[
+ { id: 'kalman', name: 'Kalman', desc: 'Default. Estimates position + velocity together; energy-aware noise model. Best for stairs.' },
+ { id: 'pi', name: 'Legacy PI', desc: 'EMA + PI controller from v5. Five tunables; familiar if you tuned the Arduino build.' },
+ ].map(a => {
+ const active = mode === a.id;
+ return (
+
+ );
+ })}
+
+
+
+
Tuning
+
+
+
+
+ Calm β Snappy Β· {response}
+
+
save({ response: +e.target.value })}/>
+
{responseHint}
+
+
+
+
+ {lookAhead} ms
+
+
save({ look_ahead_ms: +e.target.value })}/>
+
{lookHint}
+
+
+
+
+ {outlierLabel}
+
+
+ {[
+ { v: 0, name: 'Off', note: 'Trust radar 1:1' },
+ { v: 1, name: 'Soft', note: 'Median of last 3' },
+ { v: 2, name: 'Strong', note: 'Median of last 7' },
+ ].map(o => {
+ const active = outlier === o.v;
+ return (
+
+ );
+ })}
+
+
Stronger rejection masks single-sample radar glitches but adds 1-2 frames of lag.
+
+
+
+
+ Advanced β Legacy PI gains
+
+ {mode === 'pi' ? 'Active' : 'Inactive in Kalman mode'}
+
+
+
+
save({ pos_smooth_x1k: v })} min={10} max={800} suffix="Γ 1/1000"/>
+ save({ vel_smooth_x1k: v })} min={10} max={500} suffix="Γ 1/1000"/>
+ save({ predict_x1k: v })} min={0} max={2000} suffix="Γ 1/1000"/>
+ save({ p_gain_x1k: v })} min={0} max={1000} suffix="Γ 1/1000"/>
+ save({ i_gain_x1k: v })} min={0} max={200} suffix="Γ 1/1000"/>
+
+
+ These are the v5 firmware knobs. In Kalman mode the Response slider above replaces them. Higher P responds faster but overshoots; higher I corrects steady-state drift over time.
+
+
+
+
+
+
+
Pairing window open
+
+ On the other device, either hold the BOOT button for 3 seconds or open its web UI and click Pair new device. They auto-connect β no need to click on both.
+
+
+
+
+
Topology
+
+
+ {topologies.map(t => {
+ const active = topology.kind === t.id;
+ return (
+
+ );
+ })}
+
+
+
+
+ Devices
+ Click Identify to make a device blink β useful while wiring topology
+
+
+ {allDevices.map((d: any) => {
+ const isIdentifying = identifying === d.mac;
+ return (
+
+
+
+
+ {d.name}
+ {d.role}
+ {d.self && this device}
+
+
{d.mac}
+
+
+
{d.rssi || 'β'} dBm
+
+ {!d.self && (
+
+ )}
+
+ );
+ })}
+ {allDevices.length <= 1 && (
+
+ No peers paired yet. Click Pair new device above to start a 30-second pairing window.
+
+ )}
+
+
+
Sensor priority
+
+
+ {priorities.map(p => {
+ const active = mesh.fusion === p.id;
+ return (
+
+ );
+ })}
+
+
+
+
+
Board profile
+
+
+ {profiles.profiles.map((p: any) => {
+ const on = activeBoard === p.id;
+ return (
+
+ );
+ })}
+
+
+
+
+
+
Radar
+
+ {kinds.kinds.map((r: any) => {
+ const on = activeRadar === r.id;
+ return (
+
+ );
+ })}
+
+
+
+
Pin map{profile.display}
+
+
+ {PINS.map(([key, label, icon, profKey]) => {
+ const cur = pins[key] ?? (profile as any)[profKey];
+ return (
+
+
+
+ {label}
+
+
+
+ );
+ })}
+
+
+
+ Strapping pins are disabled β they affect boot mode and shouldn't drive an LED strip or radar UART. {unsafe.length} hidden ({unsafe.join(', ')}).
+
+
+
+
+
+
+
+
+
+ {wifi.sta_connected ? wifi.ssid : 'Not connected'}
+ {wifi.sta_connected && connected}
+ {wifi.ap_active && AP up}
+
+
+ {wifi.ip || 'β'} Β· {wifi.hostname}.local Β· {wifi.rssi} dBm
+
+
+ {wifi.sta_configured &&
}
+
+
+
Available networks
+
+
+
+ {scan === null &&
Click Scan to discover networks.
}
+ {scan?.length === 0 &&
No networks found.
}
+ {scan?.map(n => {
+ const isCurrent = wifi.sta_connected && n.ssid === wifi.ssid;
+ const bars = n.rssi > -60 ? 4 : n.rssi > -68 ? 3 : n.rssi > -76 ? 2 : 1;
+ return (
+
+
+ {[1,2,3,4].map(i =>
)}
+
+
+
{n.ssid}
+
{n.rssi} dBm Β· {n.secure ? 'WPA2' : 'open'}
+
+ {isCurrent ?
current :
}
+
+ );
+ })}
+
+
+
Join "{joinSsid}"
+
setPwd((e.target as HTMLInputElement).value)} style="margin-bottom: 8px;"/>
+
+
+
+
+
+
+
Hostname
+
+
mDNS name
+
+ setHost((e.target as HTMLInputElement).value.replace(/[^a-z0-9-]/g, ''))}/>
+ .local
+
+
+
+
+
+
+
AP behaviour
+
+ {[
+ { id: 'auto', name: 'Auto', desc: 'AP off when STA connected' },
+ { id: 'always', name: 'Always on', desc: 'AP up at all times β local fallback' },
+ { id: 'sta_only', name: 'STA only', desc: 'AP off, ESP-NOW uses STA channel' },
+ ].map(m => {
+ const on = apMode === m.id;
+ return (
+
+ );
+ })}
+
+
+
+
+
Firmware{version.version || 'β'}
+
+
+
+
+
{version.version} Β· {version.target}
+
ESP-IDF {version.idf_version} Β· built {version.build_date}
+
+
+
+
+
+
+ {otaProg >= 0 && otaProg < 1 && (
+
+
+
Uploading {(otaProg*100).toFixed(0)}%
+
+ )}
+
+ {otaName && otaProg < 0 && (
+
+ )}
+
+
+
+
+
+
Auth
+
+ {authReq ? 'enabled' : 'disabled'}
+
+
+
+
Password (β₯ 8 chars Β· empty disables auth)
+
+ setPwd((e.target as HTMLInputElement).value)}/>
+
+
+
+
+ Required only on this network. Local mDNS access uses cookie sessions.
+
+
+
+
+
JSON config
+
+
+
+
+
+
+
+
Factory reset
+
+
+ Type {version.hostname} to confirm
+
+
+ setConfirmText((e.target as HTMLInputElement).value)}/>
+
+
+
+
+
+> ### π v6.0.0 shipped β full ESP-IDF + FreeRTOS rewrite
+>
+> v6 is a ground-up rewrite from Arduino onto **ESP-IDF + FreeRTOS**: independent
+> FreeRTOS tasks for radar read, motion smoothing, LED rendering, web serving,
+> and ESP-NOW peer-mesh β no more cooperative `loop()` starving the LED
+> render under HTTP load. v6 ships with **LD2450 multi-target tracking**, a
+> **modular radar driver layer** (LD2410 / LD2412 / LD2420 / LD2450 / sim β
+> swap via web UI without reflashing), a **board picker with editable pin map**
+> (ESP32-C3 / ESP32 / S3 / C6), a **peer mesh** for U/L/asymmetric stairs
+> (every device runs identical code; lowest-MAC wins coordinator),
+> **asymmetric pairing** (click Pair on either device β both join), a
+> **Kalman-based motion filter** (3 user knobs instead of v5's 5 cryptic
+> gains), **OTA with rollback**, **captive portal**, **PBKDF2-SHA256 auth**,
+> and a **fully responsive Preact web UI** (sidebar on desktop, bottom-tab
+> nav on mobile).
+>
+> **Recommended hardware: ESP32-S3 (DevKitC-1 or S3-Zero).** ESP32-C3 SuperMini
+> is supported for single-strip installs. See
+> [docs/HARDWARE.md](docs/HARDWARE.md) for the full board recommendation
+> table and known issues.
+>
+> | Branch / tag | Purpose |
+> |---|---|
+> | `main` | v6.0.0 β current canonical firmware (this branch) |
+> | `v6-idf-rewrite` | active dev branch for v6.x work (encrypted ESP-NOW, S3 dual-core, auto-topology) |
+> | `legacy/v5-arduino` | frozen archive of the v5.x Arduino line β reference only |
+> | tag `v6.0.0` | shipped release with prebuilt C3 binaries on the release page |
+> | tag `v5.1.1` | last Arduino-era release |
+
+If you cloned this repo before v6.0.0 landed and your local `main` still
+reflects the old Arduino tree, run `git fetch && git reset --hard origin/main`
+once after the merge to come up to speed. The Arduino code is preserved on
+`legacy/v5-arduino` and under `legacy/AmbiSense/` if you want to keep
+running v5.
+
+## v6 quickstart (ESP-IDF v5.5.2)
+
+**Easiest path** β flash the pre-built C3 binary from the
+[v6.0.0 release page](https://github.com/Techposts/AmbiSense/releases/tag/v6.0.0):
+
+```sh
+pip install esptool
+python -m esptool --chip esp32c3 -p /dev/ttyUSB0 -b 460800 \
+ --before default_reset --after hard_reset write_flash \
+ --flash_mode dio --flash_size 4MB --flash_freq 80m \
+ 0x0 bootloader-c3-v6.0.0.bin \
+ 0x8000 partition-table-c3-v6.0.0.bin \
+ 0x10000 ambisense-c3-v6.0.0.bin
+```
+
+**Build from source** β you need ESP-IDF v5.5.2 installed (`~/esp/esp-idf-v5.5.2/`):
+
+```sh
+git clone https://github.com/Techposts/AmbiSense.git
+cd AmbiSense/firmware
+. ~/esp/esp-idf-v5.5.2/export.sh
+
+idf.py set-target esp32c3 # or: esp32, esp32s3, esp32c6
+idf.py build flash monitor
+```
+
+After flash the device starts a Wi-Fi AP `AmbiSense-XXXX`. Connect from
+your phone β the captive portal pops at `http://192.168.4.1/`. Enter
+home Wi-Fi creds; the device joins and is reachable as
+`http://ambisense-XXXX.local/`.
+
+**Recommended hardware**: ESP32-S3 DevKitC-1 or S3-Zero (dual-core,
+native USB). **Supported**: ESP32-C3 SuperMini for single-strip installs.
+See [docs/HARDWARE.md](docs/HARDWARE.md) for the full table and known
+issues.
+
+VSCode users: install Espressif's ESP-IDF extension to get IntelliSense
+for IDF headers β without it, clangd will report
+`'esp_err.h' file not found` and similar; the code still builds
+correctly via `idf.py`.
+
+## v6 documentation
+
+| Document | Read when |
+|---|---|
+| [docs/V6-ARCHITECTURE.md](docs/V6-ARCHITECTURE.md) | Picking up the v6 rewrite cold β this captures the locked architectural decisions (peer mesh, modular radar drivers, NVS schema, board profiles). Read first before proposing any structural change. |
+| [docs/V6-ROADMAP.md](docs/V6-ROADMAP.md) | Planning what to build next β the 5-PR plan with status per PR and the tag/release cadence. |
+| [docs/HARDWARE.md](docs/HARDWARE.md) | Building or debugging hardware β reference wiring for C3 SuperMini, board profiles, sensor pinouts, and a flash-fails-to-connect troubleshooting ladder. |
+
+## Repo layout
+
+```
+firmware/ β ESP-IDF v6 source (this is where new work goes)
+frontend/design-source/ β Claude-Design handoff bundle for the v6 UI (read frontend/design-source/README.md)
+legacy/AmbiSense/ β v5.x Arduino source, preserved for reference
+Assets/, STL Files/ β design assets, enclosures (unchanged)
+```
+
+---
+
+## v5 (Arduino) docs β reference only
+
+The text below is the original v5.1.1 Arduino README, kept here for
+people running v5 hardware. v5 is **frozen** β no further bug fixes or
+features will be backported. Running v5? Track the
+[`legacy/v5-arduino`](https://github.com/Techposts/AmbiSense/tree/legacy/v5-arduino)
+branch instead of `main`, and the source is at `legacy/AmbiSense/`
+in this tree.
+
+For new installs we strongly recommend going to v6.0.0 β see the
+quickstart above.
+
+---
+
AmbiSense is an innovative smart lighting solution that uses radar sensing technology to create responsive ambient lighting experiences. The system detects movement and distance using an LD2410 radar sensor and dynamically controls NeoPixel LED strips in real-time, creating an interactive lighting environment.
The core of AmbiSense is built around an ESP32 microcontroller that interfaces with an LD2410 radar module and NeoPixel LED strips. The system creates a moving light pattern that responds to a person's proximity, with the illuminated section of the LED strip changing based on detected distance.
diff --git a/docs/HARDWARE.md b/docs/HARDWARE.md
new file mode 100644
index 0000000..cfc24e7
--- /dev/null
+++ b/docs/HARDWARE.md
@@ -0,0 +1,215 @@
+# AmbiSense v6 β Hardware Setup & Troubleshooting
+
+For locked architectural decisions about which boards/sensors are
+supported, see [`V6-ARCHITECTURE.md`](V6-ARCHITECTURE.md). This file
+covers the practical "I have hardware in front of me" stuff.
+
+## Board recommendation (read this first)
+
+| Tier | Board | Why |
+| ---- | ----- | --- |
+| **Recommended** | **ESP32-S3 DevKitC-1** *or* **ESP32-S3-Zero** | Dual-core LX7 @ 240 MHz, native USB-OTG (no CH340 driver fights), 512 KB SRAM. Wi-Fi/HTTP can be pinned to core 0 and radar+LED+motion to core 1 β slider floods can't starve the render loop. Headroom for v6.1 features (auto-topology, encrypted ESP-NOW, larger strips). Best choice for a stairwell with mesh peers. |
+| **Supported** | **ESP32-C3 SuperMini** | Single-core RISC-V @ 160 MHz. The validated v6.0 reference build. Fine for **single-strip, single-device** installs. The 300 ms client-side debounced-save shipped with v6.0 prevents HTTP saturation under slider drag. Stops being the right choice the moment you want >2 mesh peers or >300 LEDs. |
+| **Deprecated** | ESP32 classic (WROOM-32) | Older silicon, no native USB, no advantage over S3. Profile still builds; not recommended for new installs. |
+| **Avoid** | ESP32-C6 | Single-core, *less* SRAM than C3, and Wi-Fi 6 / Thread don't help AmbiSense. |
+
+If you're starting from scratch and asked us "which board do I buy" β **S3-Zero**. If you already have a C3 SuperMini on the bench β it works.
+
+## Reference wiring (ESP32-C3 SuperMini)
+
+This is the validated reference build for v6.0.
+
+| Function | C3 GPIO | Note |
+| -------------- | ------- | ----------------------------------- |
+| LED data (DIN) | GPIO 10 | WS2812 / NeoPixel |
+| Radar RX (MCU) | GPIO 20 | from radar's TX |
+| Radar TX (MCU) | GPIO 21 | to radar's RX |
+| Reset / mode | GPIO 4 | momentary button to GND |
+| Status LED | GPIO 8 | onboard (active-low, on most clones)|
+| 5 V power | 5V pin | for radar VCC |
+| Ground | GND | radar, LED logic ground |
+
+**Pin defaults match the firmware out of the box** β flash the C3
+SuperMini build, wire to spec, no NVS pin override needed. If you
+remap pins from the web UI later, the unsafe-pin guard refuses
+strapping/USB-JTAG/flash pins (GPIOs 9, 11β19 on C3).
+
+### Power supply
+
+- **Logic**: USB power is fine for radar + MCU + onboard status LED.
+- **LED strip**: drive from a separate 5 V PSU sized to the strip
+ (60 mA per WS2812 LED at full white). **Inject power on both ends**
+ for runs above ~50 LEDs to prevent voltage droop and rainbow
+ desaturation. The C3's 3.3 V LDO cannot power more than ~30 LEDs at
+ full brightness β don't try.
+- **Common ground**: tie the LED PSU's GND to the C3's GND so the
+ data signal references correctly.
+
+## Sensor reference wiring
+
+Both LD2410 and LD2450 use 256000 baud UART, 5 V VCC, identical pinout:
+
+```
+Sensor MCU (C3 SuperMini)
+------ ------------------
+TX β GPIO 20 (radar_rx)
+RX β GPIO 21 (radar_tx)
+VCC β 5V
+GND β GND
+```
+
+LD2450 adds OUT pin (digital presence indicator) β leave unconnected
+for v6, the firmware reads everything via UART.
+
+## Supported boards (v6.0)
+
+| Profile | Status | LED pin | Radar RX | Radar TX | Button | Status LED |
+| --------------------- | ------------- | ------- | -------- | -------- | ------ | ------------- |
+| `esp32s3-zero` | recommended | 21 | 4 | 5 | 9 | 21 |
+| `esp32c3-supermini` | β
validated | 10 | 20 | 21 | 4 | 8 (active-low)|
+| `esp32-devkit` | deprecated | 5 | 16 | 17 | 4 | 2 |
+| `esp32c6-devkit` | builds only | 8 | 4 | 5 | 9 | 15 |
+
+The `esp32s3-zero` profile is structurally validated (the firmware
+builds and the pinmap is correct for the AliExpress S3-Zero / S3-Mini
+clones) but Ravi's bench currently only has C3s β full hardware
+validation pending arrival of S3 units.
+
+Profiles defined in
+[`firmware/components/board/board.c`](../firmware/components/board/board.c).
+Adding a new board = +1 entry there + a build target in
+`.github/workflows/firmware.yml`.
+
+## Supported sensors (v6.0)
+
+| Driver id | Sensor | Targets | x/y? |
+| ---------- | --------------- | ------- | ---- |
+| `ld2410` | HiLink LD2410(B/C) | 1 | no |
+| `ld2412` | HiLink LD2412 | 1 | no |
+| `ld2420` | HiLink LD2420 | 1 (presence only) | no |
+| `ld2450` | HiLink LD2450 | up to 3 | yes (LD2450 only) |
+| `sim` | Synthetic | scripted | optional |
+
+Switch sensors at runtime via the web UI without reflashing β the
+driver registry compiles every driver in and selects one from NVS at
+boot.
+
+## Troubleshooting
+
+### Flash fails with "Failed to connect to ESP32-C3: No serial data received"
+
+**Symptom**: `idf.py flash` fails repeatedly. The chip enumerates as
+`/dev/cu.usbmodem*` (so USB-CDC is up) but esptool's SYNC packets
+go unanswered. Sometimes the chip feels warm.
+
+**Diagnosis ladder** β try in order:
+
+1. **Check the port isn't being held by another process.**
+ ```sh
+ lsof /dev/cu.usbmodem*
+ ```
+ Common culprits on macOS: `LG Calibration` (LG monitor calibration
+ daemon), Arduino IDE serial monitor, VSCode serial monitor. Kill
+ any holders before retrying.
+
+2. **Force the C3 into ROM download mode.** On most C3 SuperMini
+ clones with two surface-mount buttons (RST + BOOT):
+ - Hold `BOOT`.
+ - While holding `BOOT`, tap `RST`.
+ - Wait 1 s. Release `BOOT`.
+ - Retry `idf.py flash`.
+
+3. **Hold BOOT throughout the flash.** Some clones need `BOOT` held
+ continuously, not just sampled at reset. Run `idf.py flash` with
+ `BOOT` still pressed; release only after flash completes.
+
+4. **For single-button boards**: `BOOT` is often a tiny solder pad on
+ the back, or `BOOT = GPIO 9`. Bridge GPIO 9 to GND with tweezers
+ while pressing `RST`.
+
+5. **`--before usb_reset`** (the C3's USB-Serial-JTAG-specific reset).
+ ```sh
+ python -m esptool --chip esp32c3 -p /dev/cu.usbmodem... \
+ -b 460800 --before usb_reset --after hard_reset \
+ write_flash @flash_args
+ ```
+
+6. **macOS USB-CDC stuck state β restart the Mac.** This is the known
+ final-resort fix when the chip enumerates but esptool can't sync
+ despite all of the above. macOS sometimes caches a stale USB-CDC
+ endpoint state for the C3's USB-Serial-JTAG and won't release it
+ until reboot. Confirmed by Ravi as the working recovery on
+ 2026-05-05.
+
+### Onboard LED stays solid after boot
+
+Expected during PR #1 β `app_main` finishes setup and switches to
+`STATUS_LED_AP_MODE` (slow 1 Hz blink). If it stays solid, you're on
+PR #1's `BOOT` pattern still, which means `app_main` crashed before
+reaching the `set_pattern(AP_MODE)` call. Check the serial log over
+USB-Serial-JTAG (the C3's onboard USB IS the serial console).
+
+### Where do I see logs?
+
+The C3 SuperMini routes ESP-IDF console over its built-in USB-Serial-
+JTAG peripheral. Connect via:
+
+```sh
+. $IDF_PATH/export.sh
+idf.py -p /dev/cu.usbmodem... monitor
+```
+
+or any serial terminal at 115200 baud. Logs are also mirrored to a
+16 KB in-RAM ring buffer accessible at `GET /api/logs` once PR #2's
+web server is up.
+
+### Device boots but second one isn't visible (no AP, no STA)
+
+**Symptom**: After flashing, the device serial output shows boot logs
+but no AP `AmbiSense-XXXX` shows up on a phone scan and the device
+never joins Wi-Fi. First device works fine.
+
+**Most common cause**: stale NVS holding a board profile for a
+different MCU (e.g., `esp32-devkit` saved on a C3 from a prior test
+flash). v6.0 ships an MCU-mismatch boot guard that catches this on
+new boots, but if you're upgrading from an alpha build the safest
+recovery is:
+
+```sh
+idf.py -p /dev/cu.usbmodemXXXXXXX erase-flash
+idf.py -p /dev/cu.usbmodemXXXXXXX flash
+```
+
+The erase-flash wipes the NVS partition so the device boots with
+factory defaults. Confirm with `idf.py monitor` β you should see
+`Board profile (default): esp32c3-supermini (ESP32-C3 SuperMini)`
+followed by netmgr starting AP.
+
+### Slider in web UI throws ERR_CONNECTION_RESET
+
+**Symptom**: Dragging a slider in the LED or Motion screen flood-fires
+`POST /api/settings` and the browser console fills with
+`ERR_CONNECTION_RESET` / `ERR_EMPTY_RESPONSE`.
+
+**Cause**: The C3 is single-core. The HTTP server, ESP-NOW broadcast,
+radar UART, motion smoother, and LED render task all run on one
+RISC-V core. Sliders fire `onChange` ~30 times/second; each one was
+posting + reloading at full rate, saturating the httpd's
+`max_open_sockets = 7`.
+
+**Fix**: v6.0 adds a 300 ms debounced-save on the client side
+(`useDebouncedSave` in `frontend/src/screens.tsx`). The slider only
+POSTs once you stop dragging, and multiple slider changes within
+300 ms get coalesced into a single batched request body. If you
+build the UI yourself, make sure you're on commit `0b63b6e` or later.
+
+### Brownout reset loop
+
+The C3's brownout detector is configured at threshold level 7 (~2.7 V).
+Brownouts on a powered-only-by-USB C3 driving a long LED strip from
+the same rail are common. v6 expects the **LED strip on its own PSU**;
+running them off the C3's 5 V/3.3 V rails will trigger the brownout
+detector and reboot you in a loop.
+
+If you must run a few LEDs from USB power for testing, keep `count β€ 30`
+and `brightness β€ 100/255`.
diff --git a/docs/V6-ARCHITECTURE.md b/docs/V6-ARCHITECTURE.md
new file mode 100644
index 0000000..7ff9e3c
--- /dev/null
+++ b/docs/V6-ARCHITECTURE.md
@@ -0,0 +1,246 @@
+# AmbiSense v6 β Architecture (locked decisions)
+
+Status: **active** as of 2026-05-05. This document captures decisions that
+must not be relitigated without an explicit conversation. If you're picking
+up the v6 rewrite cold, read this first.
+
+## Why v6 exists
+
+v5.1.1 (Arduino) works but is structurally constrained:
+
+- Every subsystem runs cooperatively in `loop()` β radar reads, LED
+ rendering, HTTP serving, ESP-NOW. A slow web request stalls the LEDs;
+ a heavy Fire-mode frame stalls radar reads.
+- EEPROM byte-offset layout (320 bytes across 6 sections) β fragile, no
+ versioning, no atomicity.
+- One radar driver hard-coded; no path to LD2450 multi-target tracking.
+- Master/slave ESP-NOW with implicit topology β equal LED-segment splits
+ break asymmetric stairs (3-step landing + 12-step main flight).
+- WiFi channel pinned to 6 even when the master joins a router on
+ channel 11 β silent failure.
+- No OTA, no captive portal, no auth, plaintext WiFi creds in EEPROM.
+
+v6 is an ESP-IDF + FreeRTOS rewrite that fixes all of the above while
+preserving the v5 visual modes, the user-facing API surface (most
+endpoints kept compatible), and the master-slave-style coordination
+behaviour for U/L stair installs.
+
+---
+
+## Target hardware
+
+| Profile | Validated | Default LED pin | Default radar pins |
+| --------------------- | --------- | --------------- | ------------------ |
+| `esp32c3-supermini` | β
yes | GPIO 10 | RX 20 / TX 21 |
+| `esp32-devkit` | builds | GPIO 5 | RX 16 / TX 17 |
+| `esp32s3-zero` | builds | GPIO 21 | RX 4 / TX 5 |
+| `esp32c6-devkit` | builds | GPIO 8 | RX 4 / TX 5 |
+
+Profiles ship in `firmware/components/board/board.c`. Each declares an
+`unsafe_pin_mask` covering strapping pins, USB-Serial-JTAG D-/D+, and
+internal SPI flash. The web UI (PR #5) will refuse pin remaps that fall
+on unsafe pins.
+
+The C3 SuperMini is the primary target for v6.0. Other boards are
+"compile-clean" until the user gets hardware in hand.
+
+## Target sensors (radar abstraction layer)
+
+A driver registry compiled into `components/radar/`. All drivers linked
+in; one selected at runtime via the `board.radar_kind` NVS key. Adding a
+new sensor = +1 file + 1 dropdown entry, no firmware reflash needed.
+
+| Driver id | Sensor | Tier | Notes |
+| ---------- | ---------------- | ----- | ----------------------------------- |
+| `ld2410` | HiLink LD2410(B/C)| v1 | Single target; existing v5 hardware |
+| `ld2412` | HiLink LD2412 | v1 | Per-gate sensitivity |
+| `ld2420` | HiLink LD2420 | v1 | Presence only (no distance) |
+| `ld2450` | HiLink LD2450 | v1 | Up to 3 targets, x/y/speed |
+| `sim` | Simulator | v1 | Synthetic traces for desk testing |
+
+**One radar per device.** The C3 has only one usable UART beyond the
+console, and the user explicitly confirmed this constraint. Multi-radar
+fusion happens at the mesh level (each device contributes its sensor).
+
+## Mesh model: peer mesh, NOT master/slave
+
+Every device:
+
+1. Has the **full topology config** in NVS (which segments exist, which
+ device owns each segment, sensor positions in cm along the strip).
+2. **Broadcasts its radar reading at 5 Hz** to all peers via ESP-NOW.
+3. Runs the **same fusion algorithm locally** on the merged peer stream
+ and arrives at the same global "active person position".
+4. Renders **only its own LED segment** on its **own local strip**.
+
+Properties:
+
+- **No leader required for control.** Any device can drop and the others
+ keep working at degraded fusion accuracy.
+- **Web UI host = elected coordinator** (lowest-MAC peer). User browses
+ to `ambisense.local`, mDNS resolves to whoever is elected. No "which
+ IP do I open?" confusion.
+- **Config gossip.** Any device accepts a config write; gossip propagates
+ with a `config_version` stamp. Lex tiebreaker on MAC for simultaneous
+ writes.
+
+### Critical physical fact: each device has its OWN local strip
+
+LED strips need power injection on both ends for long runs and the data
+signal degrades over distance. We do **not** chain a single strip across
+multiple devices. Each device drives its own physical strip; the "global
+LED address space" is purely virtual:
+
+```
+device A (segment 0): physical pixels 0..99 == virtual 0..99
+device B (segment 1): physical pixels 0..99 == virtual 100..199
+device C (segment 2): physical pixels 0..99 == virtual 200..299
+```
+
+When the active person is at virtual position 250:
+
+- A renders background only (250 not in 0..99).
+- B renders background only (250 not in 100..199).
+- C renders the moving light at *local* pixel 50 (250 β 200).
+
+This shrinks ESP-NOW bandwidth dramatically β peers exchange ~24-byte
+`global_state_t` frames (active position + mode + color + effect tick),
+not pixel-level commands. ~600 B/s mesh chatter for a 5-device install.
+
+### Wire protocol (PR #4 will implement)
+
+```c
+typedef struct { // ESP-NOW, broadcast every 200 ms
+ uint8_t msg_type; // 1=TARGET, 2=HEARTBEAT, 3=CONFIG_GOSSIP, 4=CHAN_ANNOUNCE
+ uint8_t device_idx;
+ uint16_t config_version;
+ uint16_t distance_cm;
+ int16_t x_cm, y_cm; // valid for LD2450, else 0
+ int16_t velocity_cms;
+ uint8_t energy;
+ uint8_t flags; // bit0=primary_target_present, bit1=is_coordinator
+ uint64_t ts_us;
+} peer_msg_t;
+```
+
+Channel-follow-STA: when any device joins a router, it broadcasts
+`CHAN_ANNOUNCE`; peers update via `esp_wifi_set_channel()`. Solves the
+v5 "channel 6 forced, router on 11, mesh dies" silent failure.
+
+Encrypted ESP-NOW: PMK/LMK pairing during a 3-second-button-hold
+pairing window. Stops a neighbour with the same firmware from joining
+your mesh accidentally.
+
+---
+
+## Software structure
+
+```
+firmware/
+βββ CMakeLists.txt # IDF project root
+βββ partitions.csv # NVS + 2x OTA + LittleFS + coredump
+βββ sdkconfig.defaults # Common knobs (WDT, brownout, coredump, β¦)
+βββ sdkconfig.defaults.esp32c3 # C3-specific (USB-Serial-JTAG console, brownout)
+βββ main/main.c # app_main: bring up tasks; no business logic
+βββ components/
+ βββ board/ # PR #1 β β board profile struct + 4 profiles
+ βββ settings/ # PR #1 β β NVS facade replacing v5 EEPROM
+ βββ status_led/ # PR #1 β β pattern-driven LED in own task
+ βββ netmgr/ # PR #2 β Wi-Fi STA/AP + mDNS + captive DNS
+ βββ webui/ # PR #2 β esp_http_server + LittleFS + auth
+ βββ ota/ # PR #2 β esp_https_ota wrapper
+ βββ radar/ # PR #3 β driver registry (LD2410/2412/2420/2450/sim)
+ βββ motion/ # PR #3 β PI smoother (port of v5 algorithm)
+ βββ led_engine/ # PR #3 β 11 modes via led_strip RMT
+ βββ mesh/ # PR #4 β ESP-NOW peer mesh
+ βββ topology/ # PR #4 β explicit L/U/asymmetric stair model
+```
+
+### FreeRTOS task model
+
+| Task | Pri | Stack | Period | Responsibility |
+| ----------------- | --- | ----- | ----------- | ----------------------------------- |
+| `radar_task` | 6 | 3 KB | UART event | Read radar bytes β `radar_frame_t` |
+| `motion_task` | 5 | 4 KB | 50 Hz | PI smoother β publishes `target_t` |
+| `mesh_rx_task` | 5 | 4 KB | event | ESP-NOW callbacks β `target_q` |
+| `mesh_tx_task` | 4 | 3 KB | 5 Hz | Broadcast our reading; topology gossip |
+| `led_render_task` | 4 | 6 KB | 60 Hz | Read fused target β framebuffer β `led_strip_refresh()` |
+| `web_task` | 3 | 6 KB | event | HTTPD handler thread |
+| `health_task` | 2 | 2 KB | 1 Hz | Heap watch, peer timeout, status LED |
+
+The single integration point is `target_q` β radar local + ESP-NOW
+remote both push into it; motion fusion + LED render both consume it.
+This collapses v5's four ad-hoc paths in `processRadarReading()`
+(master / slave / standalone / no-slaves) into one uniform pipeline.
+
+---
+
+## NVS schema (replacing v5's 320-byte EEPROM map)
+
+| Namespace | Keys (representative) |
+| --------- | --------------------- |
+| `sys` | `device_name` |
+| `board` | `id`, `led_pin`, `radar_rx`, `radar_tx`, `button`, `status_led`, `radar_kind` |
+| `led` | `count`, `brightness`, `r/g/b`, `mode`, `span`, `center_shift`, `trail`, `dir_light`, `bg_mode`, `effect_speed`, `effect_intensity` |
+| `dist` | `min_cm`, `max_cm` |
+| `motion` | `enabled`, `pos_smooth`, `vel_smooth`, `predict`, `p_gain`, `i_gain` |
+| `mesh` | `peers` (blob: count + 6ΓN MAC array), `pmk`, `channel`, `priority_mode` |
+| `topo` | `kind` (straight/L/U/custom), `total_leds`, `segments` (blob) |
+| `wifi` | `ssid`, `pass` (encrypted w/ chip-derived key), `static_ip` (optional), `mdns_name` |
+| `auth` | `admin_pass_hash` (PBKDF2-SHA256, 250k rounds) |
+
+NVS is journaled (atomic per-key writes), wear-levelled, typed (no
+manual hi/lo byte unpacking), and versionable. Replaces v5's manual
+XOR-CRC sectioned layout entirely.
+
+No migration shim from v5 EEPROM β the user explicitly confirmed v6 is
+a clean cutover (no backwards compatibility with Arduino fleet).
+
+---
+
+## HTTP API
+
+The PR #1 design preserves every existing v5 endpoint (compatibility for
+external integrations like Home Assistant), and adds the missing v6
+surface. See `docs/V6-ROADMAP.md` for the per-PR endpoint deliveries.
+
+New endpoints summary:
+
+```
+POST /api/auth/login β cookie session
+WS /api/live β distance + RSSI + heap @ 5 Hz, replaces XHR polling
+GET /api/board/profiles β board dropdown
+POST /api/board β save board id + pin overrides; reboot
+GET /api/radar/kinds β ld2410 | ld2412 | ld2420 | ld2450 | sim
+POST /api/topology β persist L/U/custom + per-segment LED ranges
+POST /api/ota β multipart firmware upload
+POST /api/sim/trace β simulator-driver: replay a recorded distance trace
+GET /api/version β app version + git sha + idf version + free heap
+GET /api/logs β ring buffer of recent ESP_LOG output
+```
+
+---
+
+## Open decisions (locked for v6.0)
+
+These were resolved by the user with "decide for me":
+
+| Decision | Choice |
+| ------------ | ------------------------------------------------------------ |
+| Boards in v1 | All four profiles ship; only C3 validated, others build-clean |
+| Auth default | OFF; banner until configured; PBKDF2-SHA256 hash |
+| OTA signing | Unsigned for v6.0; signed-OTA on the v6.x roadmap |
+| UI framework | Preact + Tailwind + Vite + TypeScript; bundle target <80 KB gz |
+| Mesh model | Peer mesh with elected coordinator (lowest-MAC) |
+| MQTT | Off by default; HA auto-discovery format when enabled |
+| Repo strategy | Same repo; `legacy/v5-arduino` archive; `v6-idf-rewrite` working branch; tagged releases `v6.0.0-alpha.N` |
+
+## What's NOT in v6.0 (deferred)
+
+- BLE Mesh / Thread / Matter (would require C6/S3 only β rules out C3)
+- Simultaneous LD2410 + LD2450 on one board (C3 has only one usable UART)
+- Signed OTA (defer until update flow is exercised)
+- Multi-room / cross-house mesh (β€5 nodes per install is the design point)
+- Anonymous telemetry / phone-home (never)
+
+These can be added later without breaking the architecture.
diff --git a/docs/V6-ROADMAP.md b/docs/V6-ROADMAP.md
new file mode 100644
index 0000000..48f7276
--- /dev/null
+++ b/docs/V6-ROADMAP.md
@@ -0,0 +1,235 @@
+# AmbiSense v6 β PR-by-PR roadmap
+
+> **Status (2026-05-05): v6.0.0 RELEASED.** All five planned PRs landed
+> plus a post-PR-5 polish pass (Kalman motion, asymmetric pairing,
+> debounced UI saves, mobile CSS, board MCU-mismatch boot guard). See
+> the [v6.0.0 release page](https://github.com/Techposts/AmbiSense/releases/tag/v6.0.0)
+> for the user-facing summary.
+>
+> v6.x roadmap (post-6.0.0 work) is at the bottom of this file.
+
+Five PRs. Each is independently flashable and validated on real C3
+hardware before the next starts. Releases tagged `v6.0.0-alpha.N` from
+PR #2 onwards; final `v6.0.0` ships with PR #5.
+
+For locked architectural decisions see [`V6-ARCHITECTURE.md`](V6-ARCHITECTURE.md).
+
+---
+
+## PR #1 β IDF skeleton
+
+**Status: β
MERGED on `v6-idf-rewrite`, pushed to origin (2026-05-05).**
+
+Delivered:
+- Repo housekeeping: legacy v5 moved under `legacy/AmbiSense/`,
+ branches `legacy/v5-arduino` and `v6-idf-rewrite` created.
+- ESP-IDF v5.3-compatible project scaffold under `firmware/`.
+- Custom partition table: 16 KB NVS + 8 KB OTA data + 1408 KB Γ 2 OTA
+ app slots + 960 KB LittleFS + 64 KB coredump (4 MB total).
+- `sdkconfig.defaults` with task watchdog, brownout detector,
+ bootloader rollback, coredump-to-flash, esp_http_server WS support.
+- `components/board/` β profile struct + 4 ship-ready profiles
+ (`esp32c3-supermini` validated; others build-clean, untested).
+ `unsafe_pin_mask` blocks UI pin remap to strapping/USB/flash GPIOs.
+- `components/settings/` β NVS facade replacing v5's 320-byte EEPROM
+ layout. PR #1 only exposes the `board` namespace; other namespaces
+ populated as their owners come online.
+- `components/status_led/` β pattern-driven LED in its own FreeRTOS task.
+ Six patterns (BOOT, AP_MODE, STA_MODE, OTA, ERROR, PANIC) cover every
+ user-visible state.
+- `main/main.c` β resolves board profile (NVS override β compile-time
+ default), applies per-pin NVS overrides while rejecting unsafe pins,
+ spawns status_led task.
+- `frontend/design-source/` β full Claude Design handoff bundle
+ preserved for PR #5 to build against.
+- `.github/workflows/firmware.yml` β IDF build matrix across all four
+ targets on every push/PR; uploads tagged firmware artifacts.
+
+**Build numbers** (C3 target):
+- `ambisense.bin`: 0x30CF0 bytes (~195 KB)
+- App slot free: 0x12F310 bytes (86%)
+- Bootloader free: 35%
+
+**Hardware validation status**: blocked on a one-off macOS USB-CDC
+enumeration issue (the chip enumerates but esptool can't sync). Not a
+firmware bug β see [`HARDWARE.md`](HARDWARE.md). Will be flashed once
+the user retries after a Mac restart.
+
+---
+
+## PR #2 β Wi-Fi, web shell, OTA, auth scaffold
+
+**Status: not started.**
+
+Scope:
+- `components/netmgr/` β Wi-Fi STA with fallback to AP, mDNS hostname,
+ captive-portal DNS responder for AP mode (auto-pop on iOS/Android/
+ Win11), Wi-Fi event loop integration.
+- `components/webui/` β esp_http_server, LittleFS-served static UI
+ (placeholder bundle), JSON settings round-trip for every NVS key,
+ cookie-based auth (off by default, PBKDF2-SHA256 password hash),
+ WebSocket endpoint stub at `/api/live`.
+- `components/ota/` β `esp_https_ota` wrapper, `POST /api/ota` multipart
+ upload, two-stage commit (write β verify β mark valid β reboot).
+- Status LED transitions: BOOT β AP_MODE while waiting for credentials,
+ STA_MODE heartbeat once connected.
+- `GET /api/version`, `GET /api/logs` (ring buffer mirror of `ESP_LOG*`).
+
+**Done criterion**: from a stock C3, connect phone to `AmbiSense-XXXX`
+AP, captive portal pops, configure home Wi-Fi, device reboots into STA
+mode, browse to `http://ambisense.local`, see placeholder dashboard,
+upload a `.bin` firmware via OTA, device reboots into new firmware.
+
+**Tag on completion**: `v6.0.0-alpha.1`.
+
+---
+
+## PR #3 β Radar driver registry, motion, LED engine
+
+**Status: not started.**
+
+Scope:
+- `components/radar/` β driver registry pattern with one driver per
+ sensor: `ld2410.c`, `ld2412.c`, `ld2420.c`, `ld2450.c`, `sim.c`.
+ Selected at runtime via `board.radar_kind` NVS key. Common
+ `radar_frame_t` API; LD2450's x/y/multi-target fields ignored by
+ drivers that don't provide them.
+- `components/motion/` β port of v5's PI smoother
+ (`legacy/AmbiSense/radar_manager.cpp:38-198`). Same algorithm, runs
+ in its own task at 50 Hz, output published to `target_q`.
+- `components/led_engine/` β port of all 11 visual modes
+ (`legacy/AmbiSense/led_controller.cpp` lines 273β650). RMT-backed
+ `led_strip` driver replaces `Adafruit_NeoPixel`. Render task at
+ 60 Hz consumes `target_q`, writes framebuffer, refreshes strip
+ asynchronously (non-blocking, unlike v5's `strip.show()`).
+- `POST /api/sim/trace` β accept JSON-encoded distance traces for the
+ simulator driver. Lets you debug LED modes without standing in front
+ of a sensor.
+- UI placeholder gets the LED preview canvas wired to live state.
+
+**Done criterion**: standalone C3 + LD2450 + 30 LED test strip mimics
+v5 visual behaviour at parity for all 11 modes; web request load no
+longer glitches LED rendering; simulator replays a recorded trace
+identically to a live one.
+
+**Tag on completion**: `v6.0.0-alpha.2`.
+
+---
+
+## PR #4 β Peer mesh, topology, ESP-NOW
+
+**Status: not started.**
+
+Scope:
+- `components/mesh/` β ESP-NOW peer mesh per the wire protocol in
+ [`V6-ARCHITECTURE.md`](V6-ARCHITECTURE.md#wire-protocol).
+ Channel-follow-STA, encrypted ESP-NOW (PMK/LMK), 3-second-button-
+ hold pairing window, active heartbeat, 10 s health timeout.
+- `components/topology/` β explicit topology config in NVS (straight /
+ L / U / asymmetric custom) with per-segment device + LED-range
+ assignments. Replaces v5's implicit-from-count model that broke
+ asymmetric stairs.
+- All 4 sensor priority modes preserved as fusion algorithms (MOST_RECENT,
+ SLAVE_FIRST, MASTER_FIRST, ZONE_BASED) β but reframed as peer-fusion
+ policies rather than master-decides logic.
+- Coordinator election (lowest-MAC peer serves the web UI; mDNS and
+ captive portal point at coordinator's IP).
+- Config gossip with version-stamped `CONFIG_GOSSIP` packets; lex
+ tiebreaker on MAC for simultaneous edits.
+
+**Done criterion**: 2 devices on a U-stair, kill any one β the others
+keep tracking; configure asymmetric segments and verify visually;
+coordinator survives; rebooting the coordinator triggers a new election
+within 5 s.
+
+**Tag on completion**: `v6.0.0-alpha.3`.
+
+---
+
+## PR #5 β Real UI, MQTT, polish
+
+**Status: not started.** Design source already in repo at
+`frontend/design-source/` (Claude Design handoff: tokens.css + 7
+screen JSXs).
+
+Scope:
+- `frontend/` β Vite + Preact + Tailwind + TypeScript scaffold. Lift
+ the design tokens from `frontend/design-source/project/tokens.css`
+ into `tailwind.config.ts`. Port each of the 7 screens from JSX into
+ Preact components. Bundle target <80 KB gzipped.
+- WebSocket live data wired to `/api/live` (replace polling-based
+ placeholder from PR #2).
+- OTA UI: drag-drop `.bin`, progress bar, 30 s reboot overlay polling
+ `/api/version` to know when to dismiss.
+- Pin remap UI with guard rails β unsafe pins shown disabled with
+ tooltip, "reboot to apply" affordance.
+- LD2450 2-D zone editor (only visible when `radar_kind=ld2450`) β
+ drag-define exclusion zones in x/y space.
+- Factory reset flow with type-device-name confirmation.
+- MQTT publisher: off by default, system-tab toggle, Home Assistant
+ auto-discovery payload format. Publishes `{distance, mode, state}`,
+ subscribes to `cmd/*`.
+- README rewrite for v6, hardware photos, install guide, HA integration
+ re-validation against v6 endpoints.
+
+**Done criterion**: full UI works on phone + desktop; all flows from
+the design covered; MQTT integration tested with a real Home Assistant;
+clean release notes.
+
+**Tag on completion**: `v6.0.0`. Promote `v6-idf-rewrite` β `main`.
+Move v5 README content fully behind a "v5 legacy" link.
+
+---
+
+## Tag/release cadence
+
+| Tag | Trigger | Contents |
+| ------------------ | -------------- | --------------------- |
+| `v5.1.1` | (already exists) | last Arduino release |
+| `v6.0.0-alpha.0` | PR #1 merge | skeleton boots only |
+| `v6.0.0-alpha.1` | PR #2 merge | + Wi-Fi, web, OTA |
+| `v6.0.0-alpha.2` | PR #3 merge | + radar + LED engine |
+| `v6.0.0-alpha.3` | PR #4 merge | + peer mesh |
+| `v6.0.0` | PR #5 merge | feature complete |
+
+CI auto-attaches per-board firmware artifacts to tag pushes.
+
+---
+
+## v6.x roadmap (post-6.0.0)
+
+These are tracked but did NOT ship in 6.0.0. See the v6.0.0 release
+notes for the user-facing version of the same list.
+
+### Hardening
+- **Encrypted ESP-NOW** β derive a PMK from a user mesh password,
+ enable per-peer LMK, store in NVS namespace `mesh.pmk`. Targets are
+ defined in `mesh.h` (the `mesh_event_cb_t` plumbing is already in
+ place); the actual `esp_now_set_pmk` call and UI password field are
+ v6.1 work.
+- **Signed OTA** β `esp_secure_boot` + signed `.bin` with rollback. The
+ bootloader rollback path is already armed; signing keys + UI
+ workflow are pending.
+- **Persistent sessions** β auth tokens currently live in RAM, lost on
+ reboot. Move to NVS with explicit revocation list.
+
+### UX / scale
+- **Auto-topology learning** β "walk through your stairs" mode where
+ the device records distance histograms over a 60 s window and
+ proposes segment boundaries automatically.
+- **Dual-core pinning (S3 / classic)** β `xTaskCreatePinnedToCore` for
+ Wi-Fi/HTTP on core 0 and radar+LED+motion on core 1. Lifts the
+ HTTP-saturates-render limitation we currently work around with the
+ client-side debounce.
+- **LED count beyond 300** β verified; lift the documented soft cap to
+ the theoretical 1500-pixel limit per device.
+- **Realistic `sim` radar** β replay captured LD2410 frame logs
+ instead of emitting a slow sine.
+
+### Misc
+- **OTA preserves paired peers** β currently a factory reset wipes the
+ topology blob too; needs a "keep mesh config" toggle.
+- **`esp32s3-zero` profile validation** β pinmap is correct in the
+ profile; needs a hardware bring-up + photo for HARDWARE.md once an
+ S3-Zero arrives on bench.
+- **Factory reset preserves Wi-Fi** option.
diff --git a/firmware/.gitignore b/firmware/.gitignore
new file mode 100644
index 0000000..5e4dce3
--- /dev/null
+++ b/firmware/.gitignore
@@ -0,0 +1,12 @@
+# IDF build artifacts
+build/
+sdkconfig
+sdkconfig.old
+managed_components/
+dependencies.lock
+
+# Editor / OS noise
+.vscode/
+.cache/
+*.swp
+.DS_Store
diff --git a/firmware/CMakeLists.txt b/firmware/CMakeLists.txt
new file mode 100644
index 0000000..f6cdae5
--- /dev/null
+++ b/firmware/CMakeLists.txt
@@ -0,0 +1,13 @@
+cmake_minimum_required(VERSION 3.16)
+
+# AmbiSense v6 β ESP-IDF firmware
+#
+# Build with:
+# . $IDF_PATH/export.sh
+# idf.py set-target esp32c3 # or esp32, esp32s3, esp32c6
+# idf.py build flash monitor
+
+set(EXTRA_COMPONENT_DIRS "${CMAKE_CURRENT_LIST_DIR}/components")
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(ambisense)
diff --git a/firmware/components/auth/CMakeLists.txt b/firmware/components/auth/CMakeLists.txt
new file mode 100644
index 0000000..4f987d9
--- /dev/null
+++ b/firmware/components/auth/CMakeLists.txt
@@ -0,0 +1,5 @@
+idf_component_register(
+ SRCS "auth.c"
+ INCLUDE_DIRS "include"
+ REQUIRES settings mbedtls log esp_system freertos
+)
diff --git a/firmware/components/auth/auth.c b/firmware/components/auth/auth.c
new file mode 100644
index 0000000..1c2bdc4
--- /dev/null
+++ b/firmware/components/auth/auth.c
@@ -0,0 +1,210 @@
+#include "auth.h"
+
+#include