From 5eb8ddde12bd563f049313b8a5a2001e73933cc2 Mon Sep 17 00:00:00 2001 From: Joe Date: Tue, 25 Aug 2026 23:57:00 -0400 Subject: [PATCH 1/2] fix(sensing-server): scale per-node smoothing to actual CSI rate DEBOUNCE_FRAMES, MOTION_EMA_ALPHA, and BASELINE_EMA_ALPHA were tuned assuming CSI frames arrive at ~10 FPS (per their own doc comments). smooth_and_classify_node() runs once per raw incoming UDP frame, and ESP32-C6 boards measured in the field run at ~48-50 FPS - about 5x faster. That silently compressed a ~0.4s debounce window to ~0.08s and a ~1s motion EMA to ~0.2s of real smoothing, letting per-frame CSI noise flip the reported motion_level almost directly instead of being smoothed - the reported UI "seizure" of rapid label flicker. Rather than hardcode a different fixed rate (which would just move the same bug to whatever chip/capture-mode/config next diverges from it), derive each frame's effective alpha and frame-count thresholds from the node's own measured csi_fps_ema, which is already tracked and burst-filtered elsewhere (observe_csi_frame_arrival). Time constants are back-derived from the original alphas at the assumed 10 FPS point, so behavior is unchanged for a node at exactly 10 FPS and now scales correctly to whatever rate a node actually runs at. smooth_and_classify() (simulated/WiFi-scan sources, already tick- gated at a known fixed cadence) is unaffected - not exhibiting this bug, left as-is. Co-Authored-By: claude-flow (cherry picked from commit d29d9fb02078b066be8557af24023c22e99fa3d1) --- .../wifi-densepose-sensing-server/src/main.rs | 49 +++++++++++++++++-- 1 file changed, 44 insertions(+), 5 deletions(-) diff --git a/v2/crates/wifi-densepose-sensing-server/src/main.rs b/v2/crates/wifi-densepose-sensing-server/src/main.rs index 3c6ca0428..81401b0ed 100644 --- a/v2/crates/wifi-densepose-sensing-server/src/main.rs +++ b/v2/crates/wifi-densepose-sensing-server/src/main.rs @@ -2639,14 +2639,44 @@ fn raw_classify(score: f64) -> String { } /// Debounce frames required before state transition (at ~10 FPS = ~0.4s). +/// Used only by [`smooth_and_classify`] (simulated / WiFi-scan sources, +/// which run on a fixed tick cadence close to this design point). const DEBOUNCE_FRAMES: u32 = 4; /// EMA alpha for motion smoothing (~1s time constant at 10 FPS). +/// Used only by [`smooth_and_classify`]; see above. const MOTION_EMA_ALPHA: f64 = 0.15; /// EMA alpha for slow-adapting baseline (~30s time constant at 10 FPS). +/// Used only by [`smooth_and_classify`]; see above. const BASELINE_EMA_ALPHA: f64 = 0.003; /// Number of warm-up frames before baseline subtraction kicks in. +/// Used only by [`smooth_and_classify`]; see above. const BASELINE_WARMUP: u64 = 50; +/// Debounce duration required before [`smooth_and_classify_node`] accepts a +/// state transition. Equivalent to the original `DEBOUNCE_FRAMES = 4` at the +/// assumed 10 FPS design point. +const NODE_DEBOUNCE_DURATION_SECS: f64 = 0.4; +/// Time constant for [`smooth_and_classify_node`]'s motion-score EMA, +/// derived from `MOTION_EMA_ALPHA` at the assumed 10 FPS design point +/// (τ = -T / ln(1-α)) so behavior is unchanged for a node running at +/// exactly 10 FPS. +/// +/// Frame-count/fixed-alpha smoothing silently scales with actual CSI +/// arrival rate. ESP32-C6 boards observed in the field run CSI at +/// ~48-50 FPS, not the assumed 10 FPS — ~5x faster — which made the +/// debounce trigger in ~0.08s instead of ~0.4s and compressed the "1s" +/// motion EMA to ~0.2s of real smoothing, letting raw per-frame noise +/// flip the reported label almost directly (the reported UI "seizure"). +/// Deriving a per-frame alpha from the node's actual measured +/// `csi_fps_ema` makes the smoothing strength invariant to arrival rate. +const NODE_MOTION_TIME_CONSTANT_SECS: f64 = 0.6154; +/// Time constant for [`smooth_and_classify_node`]'s baseline EMA, same +/// derivation as `NODE_MOTION_TIME_CONSTANT_SECS` from `BASELINE_EMA_ALPHA`. +const NODE_BASELINE_TIME_CONSTANT_SECS: f64 = 33.28; +/// Baseline warm-up duration before baseline subtraction kicks in for +/// [`smooth_and_classify_node`] (originally 50 frames at 10 FPS = 5s). +const NODE_BASELINE_WARMUP_SECS: f64 = 5.0; + /// Apply EMA smoothing, adaptive baseline subtraction, and hysteresis debounce /// to the raw classification. Mutates the smoothing state in `AppStateInner`. fn smooth_and_classify(state: &mut AppStateInner, raw: &mut ClassificationInfo, raw_motion: f64) { @@ -2700,18 +2730,27 @@ fn smooth_and_classify(state: &mut AppStateInner, raw: &mut ClassificationInfo, /// Per-node variant of `smooth_and_classify` that operates on a `NodeState` /// instead of `AppStateInner` (issue #249). fn smooth_and_classify_node(ns: &mut NodeState, raw: &mut ClassificationInfo, raw_motion: f64) { + // Derive this frame's effective time step from the node's actual + // measured CSI rate (already EMA-tracked, burst-filtered elsewhere — + // see `observe_csi_frame_arrival`) rather than assuming 10 FPS. + let fps = ns.csi_fps_ema.max(1.0); + let dt = 1.0 / fps; + let motion_alpha = 1.0 - (-dt / NODE_MOTION_TIME_CONSTANT_SECS).exp(); + let baseline_alpha = 1.0 - (-dt / NODE_BASELINE_TIME_CONSTANT_SECS).exp(); + let debounce_frames_needed = ((NODE_DEBOUNCE_DURATION_SECS * fps).round() as u32).max(1); + let warmup_frames_needed = ((NODE_BASELINE_WARMUP_SECS * fps).round() as u64).max(1); + ns.baseline_frames += 1; - if ns.baseline_frames < BASELINE_WARMUP { + if ns.baseline_frames < warmup_frames_needed { ns.baseline_motion = ns.baseline_motion * 0.9 + raw_motion * 0.1; } else if raw_motion < ns.smoothed_motion + 0.05 { ns.baseline_motion = - ns.baseline_motion * (1.0 - BASELINE_EMA_ALPHA) + raw_motion * BASELINE_EMA_ALPHA; + ns.baseline_motion * (1.0 - baseline_alpha) + raw_motion * baseline_alpha; } let adjusted = (raw_motion - ns.baseline_motion * 0.7).max(0.0); - ns.smoothed_motion = - ns.smoothed_motion * (1.0 - MOTION_EMA_ALPHA) + adjusted * MOTION_EMA_ALPHA; + ns.smoothed_motion = ns.smoothed_motion * (1.0 - motion_alpha) + adjusted * motion_alpha; let sm = ns.smoothed_motion; let candidate = raw_classify(sm); @@ -2721,7 +2760,7 @@ fn smooth_and_classify_node(ns: &mut NodeState, raw: &mut ClassificationInfo, ra ns.debounce_candidate = candidate; } else if candidate == ns.debounce_candidate { ns.debounce_counter += 1; - if ns.debounce_counter >= DEBOUNCE_FRAMES { + if ns.debounce_counter >= debounce_frames_needed { ns.current_motion_level = candidate; ns.debounce_counter = 0; } From 3621a211bdfa419aa71a8984d1c610d3d52d0fc5 Mon Sep 17 00:00:00 2001 From: Joe Date: Thu, 27 Aug 2026 21:23:02 -0400 Subject: [PATCH 2/2] fix(sensing-server): debounce the room-level classification too `fuse_room` recomputes its plurality vote fresh every cycle with no memory of its own, unlike each node's classification, which is debounced individually. With per-node confidences sitting near the classification boundary -- 44%, 83% and 53% observed simultaneously across three nodes -- whichever two of three happened to agree on a given cycle could flip the room-level result while every node's own reading was individually stable. The room read absent / present_still / absent / present_still in rapid succession. That cascaded into everything gating on presence: the persons array, the rendered figure appearing and disappearing, the live position dot. Each of those looked like its own bug, and none of them was. Adds the missing room-level hysteresis. A new candidate classification must be observed continuously for ROOM_DEBOUNCE_DURATION_SECS before it is adopted; an interrupted run restarts it. The threshold is a DURATION rather than a cycle count, for the same reason as the per-node fix in the previous commit: a count means a different real interval at every rate. Debouncing at the room level does not make the per-node debounce redundant. They answer different questions -- "is this node's reading stable" and "do the nodes agree stably" -- and the observed failure was agreement flapping while every individual reading held steady. Co-Authored-By: claude-flow --- .../wifi-densepose-sensing-server/src/main.rs | 163 +++++++++++++++++- 1 file changed, 161 insertions(+), 2 deletions(-) diff --git a/v2/crates/wifi-densepose-sensing-server/src/main.rs b/v2/crates/wifi-densepose-sensing-server/src/main.rs index 81401b0ed..60487c9cf 100644 --- a/v2/crates/wifi-densepose-sensing-server/src/main.rs +++ b/v2/crates/wifi-densepose-sensing-server/src/main.rs @@ -491,6 +491,57 @@ fn classification_from_room(room: &RoomInference) -> ClassificationInfo { } } +/// Minimum time a candidate room-level classification must be observed +/// *consistently* before the debounced room state actually flips to it. +/// +/// `fuse_room` recomputes its plurality vote fresh every cycle with no +/// memory of its own — unlike each node's own classification, which is +/// individually debounced (`smooth_and_classify_node`). Confirmed live +/// (2026-08-28) as a real source of "flapping": with per-node confidences +/// sitting near the classification boundary (44%/83%/53% observed), whichever +/// 2 of 3 nodes happen to agree can flip cycle-to-cycle even while each +/// node's own reading is individually stable. This adds the missing +/// room-level hysteresis, same idea as the per-node debounce, one layer up. +const ROOM_DEBOUNCE_DURATION_SECS: f64 = 1.5; + +/// Debounced counterpart to [`classification_from_room`] — apply this at +/// live call sites instead, so the room's `presence`/`motion_level` only +/// flips after `raw`'s new candidate class has been observed continuously +/// for [`ROOM_DEBOUNCE_DURATION_SECS`], not on the very first cycle it wins +/// `fuse_room`'s plurality vote. `confidence` is passed through un-debounced +/// (it's a continuous value, not a discrete state, so there's nothing to +/// flap) — only `motion_level`/`presence` are held back. +fn debounce_room_classification(state: &mut AppStateInner, raw: &RoomInference) -> ClassificationInfo { + let candidate = if raw.classification == "unavailable" { + "absent" + } else { + raw.classification.as_str() + }; + let now = std::time::Instant::now(); + + if candidate == state.room_debounced_level { + // Already stable in this state — reset any in-flight candidate. + state.room_debounce_candidate = candidate.to_string(); + state.room_debounce_since = None; + } else if candidate == state.room_debounce_candidate { + let since = *state.room_debounce_since.get_or_insert(now); + if now.duration_since(since).as_secs_f64() >= ROOM_DEBOUNCE_DURATION_SECS { + state.room_debounced_level = candidate.to_string(); + state.room_debounce_since = None; + } + } else { + // New candidate — restart the hold timer. + state.room_debounce_candidate = candidate.to_string(); + state.room_debounce_since = Some(now); + } + + ClassificationInfo { + motion_level: state.room_debounced_level.clone(), + presence: state.room_debounced_level != "absent", + confidence: raw.confidence, + } +} + /// ADR-297 — the window a node may be silent before it stops contributing to /// the fused room aggregate (its entities go stale/unavailable rather than /// holding a frozen online value). Mirrors the 10 s active-node filter used to @@ -612,6 +663,98 @@ mod issue_1554_room_classification_tests { } } +#[cfg(test)] +mod debounce_room_classification_tests { + //! `fuse_room`'s plurality vote has no memory of its own — confirmed live + //! (2026-08-28) as a real "flapping" source when per-node confidences sit + //! near the classification boundary: whichever 2 of 3 nodes happen to + //! agree on a given cycle can flip the room result even while each + //! node's own reading is individually stable. `debounce_room_classification` + //! adds the missing room-level hysteresis (same idea as each node's own + //! debounce, one layer up). + use super::{debounce_room_classification, AppStateInner, RoomInference}; + use std::time::{Duration, Instant}; + + fn room(classification: &str, confidence: f64) -> RoomInference { + RoomInference { + classification: classification.to_string(), + confidence, + contributing_nodes: 3, + } + } + + #[test] + fn single_cycle_candidate_does_not_flip_immediately() { + let mut state = AppStateInner::minimal(); + let c = debounce_room_classification(&mut state, &room("present_still", 0.6)); + assert_eq!(c.motion_level, "absent", "one cycle must not be enough to flip"); + assert!(!c.presence); + } + + #[test] + fn repeated_but_recent_candidate_still_does_not_flip() { + let mut state = AppStateInner::minimal(); + debounce_room_classification(&mut state, &room("present_still", 0.6)); + // Second cycle, essentially no time elapsed — still under the hold duration. + let c = debounce_room_classification(&mut state, &room("present_still", 0.6)); + assert_eq!(c.motion_level, "absent"); + } + + #[test] + fn candidate_sustained_past_hold_duration_flips() { + let mut state = AppStateInner::minimal(); + // Simulate "present_still" having already been the candidate for 2s + // (> ROOM_DEBOUNCE_DURATION_SECS = 1.5s) without needing to sleep in + // the test. + state.room_debounce_candidate = "present_still".to_string(); + state.room_debounce_since = Some(Instant::now() - Duration::from_secs(2)); + + let c = debounce_room_classification(&mut state, &room("present_still", 0.7)); + assert_eq!(c.motion_level, "present_still"); + assert!(c.presence); + } + + #[test] + fn flapping_candidate_resets_the_hold_timer() { + let mut state = AppStateInner::minimal(); + // "present_still" has been pending 1s (not yet enough to flip). + state.room_debounce_candidate = "present_still".to_string(); + state.room_debounce_since = Some(Instant::now() - Duration::from_secs(1)); + + // A different candidate arrives — this is exactly the flapping + // pattern (2-of-3 node agreement flipping cycle to cycle). The hold + // timer must restart for the new candidate, not carry over. + let c = debounce_room_classification(&mut state, &room("active", 0.5)); + assert_eq!(c.motion_level, "absent", "still debounced to the old stable state"); + assert_eq!(state.room_debounce_candidate, "active"); + assert!( + state.room_debounce_since.unwrap().elapsed() < Duration::from_millis(100), + "hold timer must have restarted for the new candidate" + ); + } + + #[test] + fn already_stable_state_reports_immediately_without_waiting() { + let mut state = AppStateInner::minimal(); + state.room_debounced_level = "present_moving".to_string(); + let c = debounce_room_classification(&mut state, &room("present_moving", 0.9)); + assert_eq!(c.motion_level, "present_moving", "no need to re-debounce an already-stable state"); + assert!(c.presence); + } + + #[test] + fn unavailable_room_debounces_toward_absent_like_any_other_candidate() { + let mut state = AppStateInner::minimal(); + state.room_debounced_level = "present_still".to_string(); + state.room_debounce_candidate = "absent".to_string(); + state.room_debounce_since = Some(Instant::now() - Duration::from_secs(2)); + + let c = debounce_room_classification(&mut state, &RoomInference::unavailable()); + assert_eq!(c.motion_level, "absent"); + assert!(!c.presence); + } +} + #[derive(Debug, Clone, Serialize, Deserialize)] struct SignalField { grid_size: [usize; 3], @@ -1410,6 +1553,15 @@ struct AppStateInner { /// Per-node sensing state for multi-node deployments. /// Keyed by `node_id` from the ESP32 frame header. node_states: HashMap, + /// Debounced room-level classification state — see + /// `debounce_room_classification`. `fuse_room` is a fresh, memoryless + /// plurality vote every cycle with no debounce of its own (unlike each + /// node's own classification, which is debounced individually), so with + /// per-node confidences sitting near a boundary the room-level result + /// can flip cycle-to-cycle even though each node's own reading is stable. + room_debounced_level: String, + room_debounce_candidate: String, + room_debounce_since: Option, // ── Accuracy sprint: Kalman tracker, multistatic fusion, eigenvalue counting ── /// Global Kalman-based pose tracker for stable person IDs and smoothed keypoints. pose_tracker: PoseTracker, @@ -1675,6 +1827,9 @@ impl AppStateInner { training_progress_tx: broadcast::channel::(256).0, adaptive_model: None, node_states: HashMap::new(), + room_debounced_level: "absent".to_string(), + room_debounce_candidate: "absent".to_string(), + room_debounce_since: None, pose_tracker: PoseTracker::new(), last_tracker_instant: None, multistatic_fuser: MultistaticFuser::new(), @@ -6607,7 +6762,7 @@ async fn udp_receiver_task( // node's own reading no longer overwrites the room's. The // old ad-hoc "boost confidence by node count" is replaced by // `room_inference`'s freshness-weighted multi-node confidence. - let classification = classification_from_room(&room_inference); + let classification = debounce_room_classification(&mut s, &room_inference); let signal_field = generate_signal_field( fused_features.mean_rssi, @@ -7076,6 +7231,7 @@ async fn udp_receiver_task( active_nodes.iter().filter_map(|ni| ni.node_inference.as_ref()), NODE_STALE_AFTER_MS, ); + let room_classification = debounce_room_classification(&mut s, &room_inference); let mut update = SensingUpdate { msg_type: "sensing_update".to_string(), @@ -7089,7 +7245,7 @@ async fn udp_receiver_task( // `classification` (this node's own smoothed reading) // still drives `motion_score`/`total_persons` above, // which are legitimately this-packet-local. - classification: classification_from_room(&room_inference), + classification: room_classification, signal_field: generate_signal_field( fused_features.mean_rssi, motion_score, @@ -8686,6 +8842,9 @@ async fn main() { ); }), node_states: HashMap::new(), + room_debounced_level: "absent".to_string(), + room_debounce_candidate: "absent".to_string(), + room_debounce_since: None, // Accuracy sprint pose_tracker: PoseTracker::new(), last_tracker_instant: None,