adds docs, improves ux

Author: jctoledo

CLAUDE.md

@@ -514,6 +514,121 @@ Dashboard validates threshold ranges before sending to ESP32:
 **Changed from WebSocket (ap_enabled branch):**
 Originally used WebSocket push at 30Hz but this caused thread starvation. Refactored to HTTP polling for reliability.
 
+### Autotune System
+
+**Overview:**
+Autotune learns vehicle-specific mode detection thresholds from a calibration drive. Instead of generic presets, thresholds are derived from actual sensor data captured during normal driving.
+
+**Why Autotune?**
+- Every vehicle has different suspension, tire grip, weight distribution
+- Generic thresholds may trigger too early (sensitive car) or too late (stiff car)
+- Calibration captures your specific vehicle's g-force characteristics
+
+**Data Flow:**
+```
+Telemetry → Event Detection → Categorization → Median Calculation → Scaling → All Profiles
+    │              │                │                  │                │           │
+    └─►ax,ay,wz    └─►EMA filter    └─►ACCEL/BRAKE/    └─►P50 values    └─►×scale   └─►localStorage
+                      α=0.35           CORNER bins         (robust)        factors     bb_profiles
+```
+
+**Event Detection Algorithm:**
+```javascript
+// Detect events from telemetry stream
+const EMA_ALPHA = 0.35;          // Smoothing factor
+const EVENT_MIN_DURATION = 200;  // ms - reject transients
+const EVENT_TIMEOUT = 300;       // ms - gap to end event
+
+// Smooth raw sensor data
+ax_ema = ax_ema * (1 - EMA_ALPHA) + raw_ax * EMA_ALPHA;
+
+// Detect event start/end based on magnitude threshold
+// Record peak values during event
+// Categorize: positive ax → ACCEL, negative ax → BRAKE, high ay+wz → CORNER
+```
+
+**Threshold Calculation:**
+```javascript
+// For each event category (ACCEL, BRAKE, CORNER):
+const sortedPeaks = events.map(e => e.peak).sort((a,b) => a - b);
+const P50 = sortedPeaks[Math.floor(sortedPeaks.length * 0.5)];  // Median
+
+// Entry threshold: 70% of median (triggers before typical peak)
+const entry = P50 * 0.7;
+
+// Exit threshold: 50% of entry (hysteresis prevents oscillation)
+const exit = entry * 0.5;
+```
+
+**Profile Scaling System:**
+Single city calibration generates all 4 profiles using physics-based multipliers:
+
+```javascript
+const PROFILE_SCALES = {
+  track:   { acc: 2.5, brake: 2.0, lat: 3.0, yaw: 2.5, min_speed: 5.0 },
+  canyon:  { acc: 1.5, brake: 1.5, lat: 1.8, yaw: 1.6, min_speed: 3.0 },
+  city:    { acc: 1.0, brake: 1.0, lat: 1.0, yaw: 1.0, min_speed: 2.0 },
+  highway: { acc: 0.8, brake: 0.7, lat: 0.6, yaw: 0.6, min_speed: 12.0 }
+};
+
+// Scale from city baseline
+track.acc_entry = city.acc_entry * 2.5;  // Track expects 2.5× higher g-forces
+highway.lat_entry = city.lat_entry * 0.6; // Highway lane changes are gentler
+```
+
+**localStorage Data Structure:**
+```javascript
+// Stored as 'bb_profiles' in localStorage
+{
+  "track": {
+    "acc": 0.25,      // Entry threshold (g, converted to m/s²)
+    "acc_exit": 0.125,
+    "brake": 0.36,
+    "brake_exit": 0.18,
+    "lat": 0.36,
+    "lat_exit": 0.18,
+    "yaw": 0.125,
+    "min_speed": 5.0,
+    "desc": "Racing/track days"
+  },
+  "canyon": { ... },
+  "city": { ... },
+  "highway": { ... },
+  "calibrated_at": "2024-01-15T10:30:00.000Z",
+  "vehicle_id": "optional-user-label"
+}
+```
+
+**Physics Validation Metrics:**
+Autotune validates calibration quality using physics cross-checks:
+- GPS↔Sensor speed correlation (should be >0.8)
+- Accel events should show speed increasing
+- Brake events should show speed decreasing
+- Lateral events should correlate with heading change
+- Centripetal validation: ay ≈ v²/r (from wz)
+
+**Confidence Levels:**
+Based on sample count per event category:
+- HIGH: n ≥ 15 events (median very stable)
+- MEDIUM: n = 8-14 events (usable, some variance)
+- LOW: n = 3-7 events (may need more driving)
+- INSUFFICIENT: n < 3 (cannot compute reliable threshold)
+
+**Export Format:**
+JSON export includes:
+- All 4 scaled profiles with thresholds
+- Raw event data (peaks, durations, timestamps)
+- Scaling factors used
+- Validation metrics
+- Confidence per category
+- Timestamp and optional vehicle ID
+
+**Integration with Dashboard:**
+- Preset buttons show green calibration dot when `bb_profiles` exists
+- Clicking preset loads calibrated values (or defaults if uncalibrated)
+- Export button downloads comprehensive JSON for analysis
+- Progress bar shows real-time event capture during calibration
+
 ### udp_stream.rs - UDP Client (Station Mode)
 
 **Features:**

README.md

@@ -643,6 +643,69 @@ You can trigger recalibration from the dashboard:
 
 ---
 
+## Autotune (Threshold Calibration)
+
+The **Autotune** feature learns your vehicle's characteristics from a single city drive and automatically generates optimized thresholds for all 4 driving profiles.
+
+### Why Autotune?
+
+Default presets use generic thresholds, but every vehicle is different:
+- A sports car can pull 1.0g lateral; a minivan might max at 0.5g
+- Your driving style affects typical G-forces
+- One calibration drive personalizes ALL presets to YOUR vehicle
+
+### How to Use Autotune
+
+1. **Open the dashboard** at `http://192.168.71.1`
+2. **Tap "Autotune"** in the menu
+3. **Wait for GPS lock** (required before starting)
+4. **Select a scenario** (Guided, Parking Lot, or Free Drive)
+5. **Tap "Start Calibration"** and drive normally for 10-20 minutes
+6. **Collect events**: accelerations, brakes, and turns
+7. **Review results** - the system generates all 4 profiles
+8. **Tap "Apply"** to save and activate
+
+### What Gets Generated
+
+From your city driving baseline, Autotune generates 4 vehicle-specific profiles:
+
+| Profile | Scaling | Use Case |
+|---------|---------|----------|
+| **Track** | 2.0-3.0× baseline | Racing, track days |
+| **Canyon** | 1.5-1.8× baseline | Spirited mountain roads |
+| **City** | 1.0× (your baseline) | Daily driving |
+| **Highway** | 0.6-0.8× baseline | Highway cruising |
+
+### Confidence Levels
+
+The more events you collect, the more accurate the thresholds:
+
+| Events | Confidence | Recommendation |
+|--------|------------|----------------|
+| 3-7 each | Low | Keep driving |
+| 8-14 each | Medium | Good for most uses |
+| 15+ each | High | Excellent accuracy |
+
+### Export Data
+
+Autotune exports comprehensive JSON for analysis:
+- All 4 generated profiles
+- Raw event data (peaks, durations, speed changes)
+- Physics validation metrics
+- Scaling factors used
+
+This data helps evaluate calibration quality and can be used for post-analysis.
+
+### Tips for Best Results
+
+- **Drive normally** - don't exaggerate maneuvers
+- **Include variety** - different turn directions, brake intensities
+- **Flat ground preferred** - inclines can affect readings
+- **More driving = better** - the progress bar is just the minimum
+- **GPS lock required** - ensures accurate speed validation
+
+---
+
 ## Mobile Dashboard
 
 The firmware includes a built-in web dashboard that runs directly on the ESP32. No external server needed - just connect your phone and view live telemetry.

docs/index.html

@@ -1063,6 +1063,21 @@ <h3>ZUPT</h3>
                         <p>Zero-velocity updates prevent drift. Bias continuously estimated when stationary.</p>
                     </div>
 
+                    <div class="feature-card">
+                        <div class="feature-icon">
+                            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                                <path d="M12 20V10"/>
+                                <path d="M18 20V4"/>
+                                <path d="M6 20v-4"/>
+                                <circle cx="12" cy="7" r="2"/>
+                                <circle cx="6" cy="13" r="2"/>
+                                <circle cx="18" cy="7" r="2"/>
+                            </svg>
+                        </div>
+                        <h3>Autotune</h3>
+                        <p>Learn vehicle-specific thresholds from a calibration drive. One city drive generates all 4 profiles.</p>
+                    </div>
+
                     <div class="feature-card">
                         <div class="feature-icon">
                             <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
@@ -1127,6 +1142,10 @@ <h3>Dashboard Features</h3>
                                 <svg class="icon-check" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M20 6L9 17l-5-5"/></svg>
                                 Driving presets: Track, Canyon, City, Highway, Custom
                             </li>
+                            <li>
+                                <svg class="icon-check" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M20 6L9 17l-5-5"/></svg>
+                                Autotune: calibrate thresholds to your vehicle
+                            </li>
                             <li>
                                 <svg class="icon-check" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M20 6L9 17l-5-5"/></svg>
                                 Record & export to CSV

sensors/blackbox/src/websocket_server.rs

@@ -663,14 +663,6 @@ body{font-family:-apple-system,system-ui,sans-serif;background:#0a0a0f;color:#f0
 .main{flex:1;padding:12px;display:flex;flex-direction:column;gap:10px;overflow-y:auto}
 .card{background:#111;border-radius:10px;padding:14px;border:1px solid #1a1a24}
 .card-title{font-size:11px;color:#555;text-transform:uppercase;letter-spacing:1px;margin-bottom:10px;display:flex;justify-content:space-between;align-items:center}
-.scenario-grid{display:grid;grid-template-columns:1fr 1fr;gap:8px}
-.scenario{background:#0a0a0f;border:2px solid #1a1a24;border-radius:10px;padding:12px;cursor:pointer;transition:all .2s}
-.scenario.active{border-color:#3b82f6;background:linear-gradient(135deg,#0f1a2e,#0a0a0f)}
-.scenario:active{transform:scale(0.98)}
-.scenario-icon{font-size:24px;margin-bottom:6px}
-.scenario-name{font-size:12px;font-weight:600;color:#f0f0f0}
-.scenario-desc{font-size:9px;color:#555;margin-top:4px;line-height:1.3}
-.scenario-time{font-size:8px;color:#3b82f6;margin-top:6px}
 .instructions{background:#0f1a2e;border:1px solid #1e3a5f;border-radius:8px;padding:12px;margin-top:10px}
 .instructions-title{font-size:10px;color:#60a5fa;font-weight:600;margin-bottom:8px}
 .instructions-text{font-size:11px;color:#888;line-height:1.5}
@@ -742,45 +734,27 @@ body{font-family:-apple-system,system-ui,sans-serif;background:#0a0a0f;color:#f0
 <div class="hdr"><a href="/" class="back">← Dashboard</a><div class="logo">AUTOTUNE</div></div>
 <div class="main">
 
-<div class="card" id="scenario-card">
-<div class="card-title">Select Calibration Scenario</div>
-<div class="scenario-grid">
-<div class="scenario active" data-scenario="guided">
-<div class="scenario-icon">🎯</div>
-<div class="scenario-name">Guided</div>
-<div class="scenario-desc">Best accuracy. Perform specific maneuvers when prompted.</div>
-<div class="scenario-time">~3 min</div>
-</div>
-<div class="scenario" data-scenario="city">
-<div class="scenario-icon">🏙️</div>
-<div class="scenario-name">City Loop</div>
-<div class="scenario-desc">Drive around the block 5-10 times. Stop signs, turns, traffic.</div>
-<div class="scenario-time">~5 min</div>
-</div>
-<div class="scenario" data-scenario="highway">
-<div class="scenario-icon">🛣️</div>
-<div class="scenario-name">Highway</div>
-<div class="scenario-desc">Highway driving with lane changes and on/off ramps.</div>
-<div class="scenario-time">~5 min</div>
-</div>
-<div class="scenario" data-scenario="parking">
-<div class="scenario-icon">🅿️</div>
-<div class="scenario-name">Parking Lot</div>
-<div class="scenario-desc">Empty lot. Hard stops, tight turns, figure-8s for max G.</div>
-<div class="scenario-time">~2 min</div>
-</div>
+<div class="card">
+<div class="card-title">Calibration Drive</div>
+<div style="text-align:center;padding:8px 0">
+<div style="font-size:28px;margin-bottom:4px">🚗</div>
+<div style="font-size:14px;font-weight:600;color:#60a5fa">Drive normally for 10-20 minutes</div>
+<div style="font-size:11px;color:#666;margin-top:4px">One drive generates all 4 profiles (Track, Canyon, City, Highway)</div>
 </div>
-<div class="instructions" id="instructions">
-<div class="instructions-title">📋 Guided Calibration Instructions</div>
-<div class="instructions-text" id="instructions-text">
+<div class="instructions">
+<div class="instructions-title">📋 How It Works</div>
+<div class="instructions-text">
 <ol>
-<li>Find a safe, quiet road or empty parking lot</li>
-<li>Press Start - events are auto-detected as you drive</li>
-<li><b>Accelerate</b> firmly 5+ times (from stops or slow speed)</li>
-<li><b>Brake</b> normally 5+ times (to stops or slow down)</li>
-<li><b>Turn</b> at intersections or make 10+ turns in a lot</li>
-<li>Drive as you <i>normally</i> would - don't overdo it!</li>
+<li>Press <b>Start Calibration</b> below</li>
+<li>Drive around your neighborhood normally</li>
+<li>Include stops, turns, and normal acceleration</li>
+<li>The system auto-detects driving events</li>
+<li>When progress bar fills, you have enough data</li>
+<li>Press <b>Apply</b> to save all 4 profiles</li>
 </ol>
+<div style="margin-top:8px;padding:8px;background:#0a1a0a;border-radius:6px;font-size:10px;color:#22c55e">
+<b>Tip:</b> More driving = better accuracy. 15+ events per category is ideal.
+</div>
 </div>
 </div>
 </div>
@@ -857,7 +831,7 @@ const MIN_SPEED_KMH=7.2; // Must match mode.rs min_speed (2.0 m/s = 7.2 km/h)
 const EMA_ALPHA=0.35; // Must match mode.rs EMA alpha for accurate simulation
 
 // State
-let scenario='guided';
+let scenario='neighborhood'; // Single calibration mode - drive normally
 let recording=false;
 let startTime=0;
 let lastSeq=0;
@@ -892,45 +866,6 @@ let gpsAccelCorr=[];  // correlation between GPS accel and velocity accel
 let centCorr=[];      // lat_g vs v*omega correlation
 let headingVsGyro=[]; // GPS heading rate vs gyro wz
 
-// Scenario instructions
-const INSTRUCTIONS={
-guided:`<ol>
-<li>Find a safe road or empty parking lot</li>
-<li><b>Calibrate on level ground</b> - inclines affect accuracy!</li>
-<li>Press Start - events auto-detect as you drive</li>
-<li><b>Accelerate</b> firmly 5+ times from slow/stop</li>
-<li><b>Brake</b> normally 5+ times to slow/stop</li>
-<li><b>Turn</b> 10+ times at normal driving speed</li>
-<li>Drive as you <i>normally</i> would!</li>
-</ol>`,
-city:`<ol>
-<li>Drive around the block or a few city blocks</li>
-<li>Include: stop signs, traffic lights, turns</li>
-<li>5-10 loops captures enough events</li>
-<li>Normal city driving - no need to rush</li>
-</ol>`,
-highway:`<ol>
-<li>Merge onto highway, cruise at speed</li>
-<li>Make 3-5 lane changes</li>
-<li>Use on/off ramps for accel/brake</li>
-<li>One exit-and-re-enter cycle works</li>
-</ol>`,
-parking:`<ol>
-<li>Empty <b>flat</b> parking lot is ideal</li>
-<li>Start/stop on level ground (not inclines!)</li>
-<li>5 firm accelerations from stop</li>
-<li>5 firm (safe) braking stops</li>
-<li>Figure-8s or circles for turn data</li>
-<li>Cleanest calibration data!</li>
-</ol>`
-};
-
-function selectScenario(s){
-    scenario=s;
-    document.querySelectorAll('.scenario').forEach(el=>el.classList.toggle('active',el.dataset.scenario===s));
-    $('instructions-text').innerHTML=INSTRUCTIONS[s];
-}
-
 function parsePacket(buf){
     const d=new DataView(buf);
     return{
@@ -1564,11 +1499,9 @@ function toggleRecording(){
 
         btn.textContent='Stop Calibration';
         btn.className='btn btn-start recording';
-        $('scenario-card').style.opacity='0.5';
     }else{
         btn.textContent='Start Calibration';
         btn.className='btn btn-start';
-        $('scenario-card').style.opacity='1';
         computeSuggestions();
         $('report').textContent=generateReport();
         $('report-card').style.display='block';
@@ -1582,7 +1515,6 @@ setInterval(()=>{
     }
 },1000);
 
-document.querySelectorAll('.scenario').forEach(el=>el.onclick=()=>selectScenario(el.dataset.scenario));
 $('btn-start').onclick=toggleRecording;
 $('btn-apply').onclick=applySettings;
 $('btn-export').onclick=exportReport;