# HƯỚNG DẪN TUNING NAVIGATION - COMPLETE GUIDE

**Document:** Robot Navigation Tuning System - Comprehensive Guide
**Last Updated:** 2026-02-01
**Version:** 2.0 (Updated with Adaptive Pure Pursuit)
**Status:** Manual Tuning + Parameter Documentation

---

## 📋 MỤC LỤC

1. [Tổng Quan Hệ Thống](#tổng-quan-hệ-thống)
2. [Quick Start - Workflow Cơ Bản](#quick-start)
3. [Parameter Reference](#parameter-reference)
4. [Troubleshooting Scenarios](#troubleshooting-scenarios)
5. [Advanced Tuning Techniques](#advanced-tuning)
6. [Best Practices](#best-practices)

---

## 🎯 TỔNG QUAN HỆ THỐNG

### Loại Tuning Hiện Tại: **MANUAL TUNING** ✅

**Tính năng đã có:**
- ✅ Manual parameter adjustment UI
- ✅ Single test execution
- ✅ Batch testing (nhiều scenarios)
- ✅ Configuration comparison
- ✅ Real-time visualization
- ✅ Metrics calculation và scoring
- ✅ **NEW:** Adaptive Pure Pursuit (distance + curvature based)
- ✅ **NEW:** 3-Phase Final Approach Controller
- ✅ **NEW:** Comprehensive parameter documentation

**Tính năng chưa có (Future):**
- ❌ Automated optimization (Bayesian, Grid Search)
- ❌ Auto-tuning algorithms
- ❌ AI-based parameter suggestion

---

## 🚀 QUICK START

### Workflow 1: First-Time Setup (15 phút)

```
┌─────────────────────────────────────┐
│ 1. Load Default Configuration      │
│    - Access: /navigation/tuning     │
│    - Select "Balanced Default"      │
│    Time: 2 phút                     │
└─────────────────────────────────────┘
           ↓
┌─────────────────────────────────────┐
│ 2. Baseline Test                    │
│    - Scenario: "Straight Line 10m" │
│    - Click "Start Test"             │
│    - Observe visualization          │
│    Time: 3 phút                     │
└─────────────────────────────────────┘
           ↓
┌─────────────────────────────────────┐
│ 3. Review Metrics                   │
│    Overall Score: ____/100          │
│    - CTE RMS: ____m                 │
│    - Heading Error: ____°           │
│    - Jerk: ____m/s³                 │
│    Time: 5 phút                     │
└─────────────────────────────────────┘
           ↓
┌─────────────────────────────────────┐
│ 4. Decision Tree                    │
│    Score > 80  → Test more scenarios│
│    Score 60-80 → Manual tuning      │
│    Score < 60  → Check hardware     │
│    Time: 5 phút                     │
└─────────────────────────────────────┘
```

**Kết quả mong đợi:** Hiểu được performance baseline của robot

---

### Workflow 2: Multi-Scenario Validation (20 phút)

```
1. Setup Batch Test
   Scenarios:
   ☑ Straight Line 10m
   ☑ Circle 2m Radius
   ☑ Circle 0.5m Radius (challenging)

2. Run & Monitor (15 phút)
   - Auto run từng scenario
   - Track progress bar
   - View real-time plots

3. Compare Results (5 phút)
   Scenario           Score  CTE RMS  Decision
   ─────────────────  ─────  ───────  ────────
   Straight Line      85     0.05m    ✓ Pass
   Circle 2m          78     0.08m    ⚠ Tune
   Circle 0.5m        65     0.12m    ✗ Need work
```

---

## 📚 PARAMETER REFERENCE

### Pure Pursuit Configuration

#### **Basic Lookahead Parameters**

##### `LookaheadMin` (meters)
**Default:** 0.3m
**Meaning:** Điểm gần nhất phía trước mà robot hướng đến

**↑ Tăng (0.4-0.6m):**
- ✓ Smoother tracking trên đường thẳng
- ✓ Ít reactive, predictive hơn
- ✗ Có thể cắt góc trên curves
- ✗ Kém chính xác ở low speed

**↓ Giảm (0.2-0.25m):**
- ✓ Tracking curves chặt hơn
- ✓ Chính xác hơn ở low speed
- ✗ Jittery/oscillation nhiều hơn
- ✗ Nhạy với noise

**Tuning Tips:**
- Warehouse AGV: 0.4-0.5m (smooth)
- Tight spaces: 0.25-0.3m (precision)
- Start: 0.3m (balanced)

**UI Location:** `Pure Pursuit Tab > Basic Lookahead > LookaheadMin`

---

##### `Kdd` (seconds)
**Default:** 1.0s
**Formula:** `lookahead = LookaheadMin + Kdd × |velocity|`

**↑ Tăng (1.2-1.5s):**
- ✓ Look xa hơn ở high speed → smoother
- ✓ Tốt cho fast robots (>1.5 m/s)
- ✗ Có thể quá predictive (overshoot)

**↓ Giảm (0.7-0.9s):**
- ✓ Reactive control hơn
- ✓ Tốt cho slow robots
- ✗ Jittery ở high speed

**Tuning Tips:**
- Check formula: At 1.0m/s → lookahead = 0.3 + 1.0×1.0 = 1.3m
- Slow robot (<0.5 m/s): Kdd = 0.8-1.0
- Fast robot (>1.5 m/s): Kdd = 1.2-1.5

**UI Location:** `Pure Pursuit Tab > Basic Lookahead > Kdd`

---

##### `LookaheadMax` (meters)
**Default:** 2.0m
**Meaning:** Upper limit cho lookahead distance

**↑ Tăng (2.5-3.0m):**
- ✓ Very smooth ở high speed
- ✓ Tốt cho long straight paths
- ✗ Cắt góc aggressive
- ✗ Phản ứng chậm với path changes

**↓ Giảm (1.5-1.8m):**
- ✓ Tighter path following
- ✓ Tốt cho complex paths
- ✗ Kém smooth ở high speed

**Tuning Tips:**
- Must be: `LookaheadMax > LookaheadMin + Kdd × MaxVelocity`
- Example: MaxVel=1.5m/s → need ≥ 0.3+1.0×1.5 = 1.8m

**UI Location:** `Pure Pursuit Tab > Basic Lookahead > LookaheadMax`

---

#### **Adaptive Lookahead Parameters** (NEW in v2.0)

##### `GoalRegionDistance` (meters)
**Default:** 1.5m
**Meaning:** Bắt đầu giảm lookahead khi trong khoảng này từ goal

**How it works:**
```
Distance > 1.5m: lookahead = 100% (normal)
Distance = 1.0m: lookahead = 83%
Distance = 0.5m: lookahead = 67%
Distance = 0.0m: lookahead = 50%
```

**↑ Tăng (2.0-3.0m):**
- ✓ Earlier precision mode
- ✓ Smoother deceleration
- ✗ Slower overall

**↓ Giảm (0.8-1.2m):**
- ✓ Faster approach
- ✗ Abrupt gần goal

**Tuning Tips:**
- Fast robot: Tăng (need more brake distance)
- Short paths: 1.0-1.5m
- Long paths: 2.0-2.5m

**UI Location:** `Pure Pursuit Tab > Adaptive > GoalRegionDistance`

---

##### `KCurvature`
**Default:** 2.0
**Formula:** `curvatureFactor = 1 / (1 + KCurvature × curvature)`

**How it works:**
```
Straight path (k=0):   curvatureFactor = 1.0 (100% lookahead)
Gentle curve (k=0.5):  curvatureFactor = 0.67 (67% lookahead)
Sharp curve (k=1.0):   curvatureFactor = 0.33 (33% lookahead)
```

**↑ Tăng (3.0-5.0):**
- ✓ Tighter tracking trên curves
- ✓ Ít cắt góc
- ✗ Có thể quá reactive
- ✗ Oscillation trên curves

**↓ Giảm (1.0-1.5):**
- ✓ Smoother trên curves
- ✗ Cắt góc nhiều hơn
- ✗ Kém precise

**Tuning Tips:**
- Warehouse (gentle curves): 1.5-2.0
- Tight spaces (sharp curves): 3.0-4.0
- If cutting corners: Tăng KCurvature

**UI Location:** `Pure Pursuit Tab > Adaptive > KCurvature`

---

#### **Final Approach Parameters**

##### `FinalApproachThreshold` (meters)
**Default:** 0.2m
**Meaning:** Khoảng cách activate final approach mode

**Behavior:**
- Distance > 0.2m: Normal Pure Pursuit tracking
- Distance ≤ 0.2m: Switch to 3-phase final approach controller

**3 Phases:**
1. **Phase 1:** Approach position (distance > 3cm)
2. **Phase 2:** Align heading (position OK, heading error > 3°)
3. **Phase 3:** Goal reached (both OK)

**↑ Tăng (0.3-0.5m):**
- ✓ Earlier slow down → smoother
- ✗ Takes longer

**↓ Giảm (0.1-0.15m):**
- ✓ Faster approach
- ✗ Abrupt/jerky

**Tuning Tips:**
- Should be: `> PositionTolerance × 3`
- High precision: 0.3-0.5m
- Speed priority: 0.15-0.2m

**UI Location:** `Pure Pursuit Tab > Final Approach > Threshold`

---

##### `PositionTolerance` (meters)
**Default:** 0.03m (3cm)
**Meaning:** Robot cần ở gần goal bao nhiêu

**↑ Tăng (0.05-0.08m):**
- ✓ Faster goal reaching
- ✗ Lower precision

**↓ Giảm (0.01-0.02m):**
- ✓ Higher precision
- ✗ May never reach (nếu localization error lớn)

**Critical Constraint:**
```
PositionTolerance >= 2 × Localization_RMS_Error
```

**Tuning Tips:**
- Typical localization: 1-2cm → use 0.03-0.05m
- High precision app: 0.02m (if localization allows)
- Cannot be < localization capability

**UI Location:** `Pure Pursuit Tab > Final Approach > PositionTolerance`

---

##### `HeadingTolerance` (degrees)
**Default:** 3.0°
**Meaning:** Robot heading phải align trong khoảng này

**Phase 2 Behavior:**
- Position đạt → Stop linear motion
- Rotate in-place để align heading
- Khi heading error < 3° → Done

**↑ Tăng (5-10°):**
- ✓ Faster completion
- ✗ Robot may face wrong direction

**↓ Giảm (1-2°):**
- ✓ Very precise alignment
- ✗ Takes much longer
- ✗ May oscillate

**Tuning Tips:**
- Docking/charging: 2-3° (precision critical)
- General navigation: 5-8°
- No heading requirement: 10-15° (fast)

**UI Location:** `Pure Pursuit Tab > Final Approach > HeadingTolerance`

---

### Navigation Limits

##### `MaxLinearVelocity` (m/s)
**Default:** 1.5 m/s
**Meaning:** Top speed during navigation

**Safety Check:**
```
Braking distance = v² / (2 × deceleration)
At 1.5 m/s, 0.5 m/s² decel → 2.25m braking distance
```

**Tuning Tips:**
- MUST match motor controller limits
- Warehouse AGV: 1.0-1.5 m/s
- Outdoor: 2.0-3.0 m/s
- Crowded areas: 0.5-0.8 m/s

**UI Location:** `Navigation Limits Tab > MaxLinearVelocity`

---

## 🛠️ TROUBLESHOOTING SCENARIOS

### Scenario 1: Robot Oscillates (Dao động)

**Triệu chứng:**
- ✗ Robot swing qua lại
- ✗ Angular velocity thay đổi liên tục
- ✗ Path không smooth
- **Metrics:** High velocity StdDev, high jerk

**Root Causes & Solutions:**

| Cause | Parameter | Action | Priority |
|-------|-----------|--------|----------|
| Lookahead quá ngắn | `LookaheadMin` | 0.3 → 0.4m | ⭐⭐⭐ |
| Curvature sensitivity cao | `KCurvature` | 2.0 → 1.5 | ⭐⭐ |
| Angular gain lớn | `MaxAngularVelocity` | 1.5 → 1.2 rad/s | ⭐⭐ |
| Signal noise | `AlphaFilter` | 0.3 → 0.2 | ⭐ |
| PID Kd thấp | `MovePidConfig.Kd` | +0.1-0.2 | ⭐⭐ |

**Step-by-Step Fix:**
```
1. Tăng LookaheadMin: 0.3 → 0.4m
   └─> Test → Still oscillate?
2. Giảm KCurvature: 2.0 → 1.5
   └─> Test → Still oscillate?
3. Giảm MaxAngularVelocity: 1.5 → 1.2 rad/s
   └─> Test → Still oscillate?
4. Increase damping: MovePidConfig.Kd +0.1
```

**Expected Improvement:**
- Velocity StdDev: 0.3 → 0.15 m/s
- Max Jerk: 6.0 → 3.5 m/s³
- Overall Score: +10-15 points

---

### Scenario 2: Robot Cuts Corners (Cắt góc)

**Triệu chứng:**
- ✗ Robot không follow đường cong chặt
- ✗ Cross-track error lớn trên curves
- ✗ Shortcut qua góc
- **Metrics:** CTE RMS > 0.10m, Path Length Ratio < 1.0

**Root Causes & Solutions:**

| Cause | Parameter | Action | Priority |
|-------|-----------|--------|----------|
| Lookahead quá dài | `LookaheadMax` | 2.0 → 1.5m | ⭐⭐⭐ |
| Không adapt curvature | `KCurvature` | 2.0 → 3.0-4.0 | ⭐⭐⭐ |
| Lookahead time lớn | `MaxLookaheadTimeRatio` | 2.0 → 1.5s | ⭐⭐ |

**Step-by-Step Fix:**
```
1. Tăng KCurvature: 2.0 → 3.0
   └─> Test on sharp curve
2. Vẫn cut? → Giảm LookaheadMax: 2.0 → 1.8m
   └─> Check CTE RMS improvement
3. Fine-tune: MaxLookaheadTimeRatio: 2.0 → 1.7s
```

**Test Case:**
- Circle 0.5m Radius (challenging)
- Goal: CTE RMS < 0.08m

---

### Scenario 3: Poor Goal Precision

**Triệu chứng:**
- ✗ Robot không dừng đúng vị trí
- ✗ Heading sai khi đến goal
- ✗ Overshoot hoặc undershoot
- **Metrics:** Final position error > 5cm, heading error > 5°

**Diagnosis:**
```
Check Phase Logs:
FA-P1: DTG=0.085m, AErr=8.3°, LV=0.15, AV=0.12
                    ^^^^^ Heading error cao
FA-P2: HErr=2.1°, AV=0.08 (Aligning heading)
                    ^^^^^ Good alignment
FA-P3: Goal reached! DTG=0.02m, HErr=1.5°
                           ^^^^^ Position OK
```

**Root Causes & Solutions:**

| Cause | Parameter | Action | Priority |
|-------|-----------|--------|----------|
| Position tolerance lớn | `PositionTolerance` | 0.03 → 0.02m | ⭐⭐⭐ |
| Final approach xa | `FinalApproachThreshold` | 0.2 → 0.15m | ⭐⭐ |
| Angular gain thấp | `FinalKdAngular` | 2.0 → 2.5-3.0 | ⭐⭐⭐ |
| Goal region lớn | `GoalRegionDistance` | 1.5 → 1.0m | ⭐ |

**Special Case: Heading Issues**
```
If position OK but heading wrong:
1. Check CalculateGoalHeading() logic
2. Tăng FinalKdAngular: 2.0 → 3.0
3. Giảm HeadingTolerance: 3° → 2° (stricter)
4. Increase FinalApproachMaxAngularVel: 0.3 → 0.4 rad/s (faster rotation)
```

---

### Scenario 4: High Speed Instability

**Triệu chứng:**
- ✗ Không stable ở tốc độ cao
- ✗ Overshoot nhiều
- ✗ Hard braking
- **Metrics:** High jerk ở cuối path, position overshoot

**Root Causes & Solutions:**

| Cause | Parameter | Action | Priority |
|-------|-----------|--------|----------|
| Lookahead không đủ xa | `LookaheadMax` | 2.0 → 2.5-3.0m | ⭐⭐⭐ |
| Kdd quá nhỏ | `Kdd` | 1.0 → 1.2-1.5s | ⭐⭐⭐ |
| Goal region ngắn | `GoalRegionDistance` | 1.5 → 2.0-2.5m | ⭐⭐⭐ |

**Formula Check:**
```
Braking Distance = v² / (2 × decel)
At 1.5 m/s, 0.5 m/s² → 2.25m

GoalRegionDistance should be ≥ Braking Distance
→ Set GoalRegionDistance = 2.5m (safety margin)
```

---

## 🎓 ADVANCED TUNING

### Tuning Hierarchy (Làm theo thứ tự này)

**Priority 1: Basic Lookahead**
```
1. LookaheadMin → Base stability
2. KCurvature → Curve handling
3. Kdd → Velocity scaling
4. LookaheadMax → High-speed limit
```

**Priority 2: Final Approach**
```
1. PositionTolerance → Must match localization
2. FinalApproachThreshold → When to slow down
3. FinalKdAngular → Heading control gain
4. HeadingTolerance → Strictness
```

**Priority 3: Adaptive Features**
```
1. GoalRegionDistance → Brake distance
2. KCurvature → Curve tightness
3. Time ratios → Preview distance
```

---

### Parameter Interactions (Quan trọng!)

#### Interaction 1: LookaheadMin ↔ KCurvature
```
Combination               Result              When to Use
─────────────────────     ─────────────────   ──────────────
High LookaheadMin +       Cut corners         ✗ Avoid
Low KCurvature            severely

Low LookaheadMin +        May oscillate       ⚠ Careful
High KCurvature           on curves

Medium LookaheadMin +     Balanced            ✓ Recommended
Medium KCurvature         (0.3-0.4m, 2.0)
```

#### Interaction 2: MaxLinearVelocity ↔ GoalRegionDistance
```
Speed    Goal Region    Result
───────  ─────────────  ───────────────────────────
1.5 m/s  1.0m           ✗ Insufficient brake distance
1.5 m/s  2.5m           ✓ Safe, smooth approach
0.5 m/s  2.5m           ⚠ Too early slow down
```

**Formula:**
```csharp
GoalRegionDistance ≥ MaxLinearVelocity² / (2 × deceleration)
```

---

### Preset Configurations (Quick Start)

#### **Preset 1: Warehouse Standard**
```json
{
  "Name": "Warehouse Standard",
  "Description": "Smooth, wide corridors, medium speed",
  "PurePursuitConfig": {
    "LookaheadMin": 0.4,
    "Kdd": 1.0,
    "LookaheadMax": 2.0,
    "KCurvature": 1.5,
    "MaxAngularVelocity": 1.2,
    "FinalApproachThreshold": 0.2,
    "PositionTolerance": 0.04,
    "HeadingTolerance": 5.0,
    "GoalRegionDistance": 1.5
  },
  "NavigationConfig": {
    "MaxLinearVelocity": 1.2
  }
}
```
**Use case:** Kho hàng rộng, ít chướng ngại

---

#### **Preset 2: Tight Precision**
```json
{
  "Name": "Tight Precision",
  "Description": "Narrow spaces, docking, high precision",
  "PurePursuitConfig": {
    "LookaheadMin": 0.25,
    "Kdd": 0.8,
    "LookaheadMax": 1.5,
    "KCurvature": 3.0,
    "MaxAngularVelocity": 1.0,
    "FinalApproachThreshold": 0.3,
    "PositionTolerance": 0.02,
    "HeadingTolerance": 2.0,
    "GoalRegionDistance": 1.0
  },
  "NavigationConfig": {
    "MaxLinearVelocity": 0.8
  }
}
```
**Use case:** Docking, charging, tight spaces

---

#### **Preset 3: High Speed**
```json
{
  "Name": "High Speed",
  "Description": "Fast navigation, long straight paths",
  "PurePursuitConfig": {
    "LookaheadMin": 0.5,
    "Kdd": 1.5,
    "LookaheadMax": 3.0,
    "KCurvature": 2.0,
    "MaxAngularVelocity": 2.0,
    "FinalApproachThreshold": 0.15,
    "PositionTolerance": 0.05,
    "HeadingTolerance": 8.0,
    "GoalRegionDistance": 2.5
  },
  "NavigationConfig": {
    "MaxLinearVelocity": 2.0
  }
}
```
**Use case:** Outdoor, tốc độ cao, đường thẳng dài

---

## 📊 COMPARISON WORKFLOW

### How to Compare Two Configurations

**Step 1: Setup Comparison**
```
UI: Configuration Comparison Tab
├─ Config A: "Balanced Default"
├─ Config B: "Tuned_v1"
└─ Scenario: "Circle 2m Radius"

Click: "Run Comparison"
```

**Step 2: Monitor Execution**
```
Progress:
[████████████░░░░░░░░] 60% (Config A Complete)

Real-time Plot:
- Blue line: Config A trajectory
- Red line: Config B trajectory
- Green line: Reference path
```

**Step 3: Review Results**
```
Metric               Config A    Config B    Improvement
───────────────────  ──────────  ──────────  ───────────
Overall Score        72          84          +12 ✓
CTE RMS (m)          0.095       0.062       -35% ✓
Heading Error (°)    4.2         2.8         -33% ✓
Max Jerk (m/s³)      5.8         3.9         -33% ✓
Completion Time (s)  12.5        11.8        -6% ✓
```

**Decision:**
- All metrics improved → ✓ Config B is better, save it
- Mixed results → Need further tuning
- Worse results → Revert, try different approach

---

## ⚠️ BEST PRACTICES & SAFETY

### 1. Tuning Safety

**Safety Monitoring (Auto Abort):**
```
Test sẽ stop nếu:
- Cross-track error > 0.5m
- Heading error > 45°
- Sustained tracking error > 3s
- Velocity exceeds motor limits
```

**Before Tuning:**
- ✓ Check hardware health
- ✓ Verify sensor calibration
- ✓ Test in safe environment
- ✓ Have emergency stop ready

### 2. Parameter Validation

**Automatic Constraints:**
```csharp
// System validates these automatically:
LookaheadMax > LookaheadMin
GoodTrackingBlend < PoorTrackingBlend
MaxLinearVelocity <= Motor_Max_Velocity
PositionTolerance >= 2 × Localization_Error
```

**If validation fails:**
- Red border on parameter field
- Tooltip shows violation
- Cannot save until fixed

### 3. Incremental Changes

**Rule of Thumb:**
```
Change 1-2 parameters per iteration
Max change: ±30% of current value
Test after each change
```

**Example:**
```
❌ Bad:
  LookaheadMin: 0.3 → 0.6 (+100%)
  Kdd: 1.0 → 1.5 (+50%)
  KCurvature: 2.0 → 4.0 (+100%)
  → Too many changes, can't isolate effect

✓ Good:
  LookaheadMin: 0.3 → 0.35 (+17%)
  Test → Evaluate → Next change
```

### 4. Documentation

**Every Configuration Should Have:**
```json
{
  "Name": "Tuned_2026-02-01_v3",
  "Description": "Increased KCurvature to 3.0 to reduce corner cutting on tight curves. Improved CTE RMS from 0.095m to 0.062m on Circle 2m scenario.",
  "CreatedBy": "User Name",
  "BaseConfig": "Balanced Default",
  "TestResults": [
    {
      "Scenario": "Circle 2m",
      "Score": 84,
      "CTE_RMS": 0.062
    }
  ]
}
```

### 5. Multi-Scenario Validation

**Minimum Test Matrix:**
```
Scenario             Min Score  Critical Metrics
───────────────────  ─────────  ────────────────────
Straight Line 10m    > 80       CTE RMS < 0.05m
Circle 2m Radius     > 75       CTE RMS < 0.08m
Circle 0.5m Radius   > 65       CTE RMS < 0.12m
```

**Full Validation (Before Deployment):**
- All 3 scenarios > thresholds
- No safety violations
- Smooth trajectories (visual check)
- Repeatable results (run 3 times)

---

## 📖 WORKFLOW EXAMPLES

### Example 1: Fix Oscillation Issue

**Initial State:**
```
Scenario: Straight Line 10m
Score: 68/100
Issues:
- Velocity StdDev: 0.32 m/s (high)
- Max Jerk: 6.2 m/s³ (high)
- Visual: Robot swings left-right
```

**Iteration 1:**
```
Change: LookaheadMin: 0.3 → 0.4m
Reason: Increase preview distance
Result:
  Score: 68 → 75 (+7)
  Velocity StdDev: 0.32 → 0.22 (-31%)
  Still some oscillation → Continue
```

**Iteration 2:**
```
Change: KCurvature: 2.0 → 1.5
Reason: Less aggressive on curves
Result:
  Score: 75 → 79 (+4)
  Max Jerk: 6.2 → 4.5 (-27%)
  Better but not perfect → Continue
```

**Iteration 3:**
```
Change: MovePidConfig.Kd: 0.6 → 0.8
Reason: Add damping
Result:
  Score: 79 → 83 (+4)
  Velocity StdDev: 0.22 → 0.15 (-32%)
  Visual: Smooth tracking ✓
  PASS! Save as "Smooth_v1"
```

**Total Time:** 25 phút (3 iterations × ~8 phút/iteration)

---

### Example 2: Improve Goal Precision

**Initial State:**
```
Scenario: Docking Test
Issues:
- Final position error: 8cm (target: <3cm)
- Final heading error: 6° (target: <3°)
```

**Analysis:**
```
Phase Logs:
FA-P1: DTG=0.18m, AErr=12°, LV=0.20
      └─> Slow approach OK
FA-P2: HErr=6.2°, AV=0.15
      └─> Heading alignment too slow
FA-P3: Not reached (timeout)
```

**Iteration 1:**
```
Change: FinalKdAngular: 2.0 → 3.0
Reason: Faster heading correction
Result:
  Final heading error: 6° → 3.5°
  Better but still over target
```

**Iteration 2:**
```
Changes:
  - HeadingTolerance: 3° → 2° (stricter)
  - FinalApproachMaxAngularVel: 0.3 → 0.4 (faster rotation)
Result:
  Final heading error: 3.5° → 2.1° ✓
  Final position: 8cm → 2.5cm ✓
  PASS!
```

---

## 🔮 FUTURE FEATURES

### Planned: Automated Optimization (Phase 3)

**Status:** Not yet implemented

**Algorithms Under Consideration:**
- Bayesian Optimization (most promising)
- Grid Search (exhaustive but slow)
- Genetic Algorithm (for multi-objective)

**Estimated Workflow:**
```
1. Select parameters to optimize
   ☑ LookaheadMin, Kdd, KCurvature
   ☐ (Lock other parameters)

2. Define objective function
   Minimize: 0.6×CTE_RMS + 0.2×Jerk + 0.2×Time

3. Set constraints
   LookaheadMin: [0.2, 0.6]
   Kdd: [0.7, 1.5]
   ...

4. Run optimization (30-60 phút)
   Progress: [████░░░░] 50% (25/50 iterations)

5. Review best parameters
   Best Score: 87 (iteration 38)

6. Validate on test scenarios
```

**Timeline:** Q2 2026 (planned)

---

## ❓ FAQ

**Q: Nên tune bao nhiêu parameters cùng lúc?**
A: 1-2 parameters per iteration. Tune theo nhóm (Pure Pursuit → PID → Velocity).

**Q: Làm sao biết tuning có hiệu quả?**
A: Use Comparison tool. Overall Score tăng ≥5 điểm + visual improvement.

**Q: Robot vẫn oscillate sau khi tăng LookaheadMin?**
A: Try giảm KCurvature hoặc tăng PID Kd (damping).

**Q: Goal precision kém dù đã giảm PositionTolerance?**
A: Check localization error. PositionTolerance không thể < 2× localization RMS error.

**Q: Cần test bao nhiêu scenarios?**
A: Minimum 3 (Straight, Circle 2m, Circle 0.5m). Recommend 5+ for robustness.

**Q: Làm sao load preset vào UI?**
A: Configuration dropdown → Select preset name → Click "Load".

**Q: Configuration comparison cho kết quả khác nhau mỗi lần?**
A: Check randomness in test scenario. Some scenarios có stochastic elements. Run multiple times và average.

**Q: Tôi có thể export configuration không?**
A: Yes, click "Export JSON" button. File có thể import vào hệ thống khác.

---

## 📚 RELATED DOCUMENTATION

- **Parameter XML Docs:** Hover over any parameter in code to see inline documentation
- **Architecture:** `# ROBOT TUNING SYSTEM - COMPLETE ARCHITE.md`
- **Database Schema:** `# DATABASE SCHEMA & API SPECIFICATIONS.md`
- **Implementation Progress:** `IMPLEMENTATION_PROGRESS.md`
- **Algorithm Details:** `PurePursuitSimplified.cs` (inline comments)

---

## 📊 METRICS REFERENCE

### Tracking Accuracy Metrics

**CTE RMS (Cross-Track Error):**
- Measure: Khoảng cách vuông góc từ robot đến path
- Unit: meters
- Target: < 0.08m (good), < 0.05m (excellent)

**Heading Error RMS:**
- Measure: Sai số góc giữa robot heading và path tangent
- Unit: degrees
- Target: < 5° (good), < 3° (excellent)

**Goal Position Error:**
- Measure: Khoảng cách từ final position đến goal
- Unit: meters
- Target: < 0.05m (good), < 0.03m (excellent)

### Smoothness Metrics

**Max Jerk:**
- Measure: Tốc độ thay đổi acceleration lớn nhất
- Unit: m/s³
- Target: < 5.0 (good), < 3.0 (excellent)

**Velocity StdDev:**
- Measure: Độ ổn định của velocity
- Unit: m/s
- Target: < 0.2 (good), < 0.1 (excellent)

### Efficiency Metrics

**Path Length Ratio:**
- Measure: Actual path length / Reference path length
- Target: 1.0-1.05 (good), 1.0-1.02 (excellent)

**Completion Time:**
- Measure: Thời gian hoàn thành so với expected
- Depends on: MaxLinearVelocity, path complexity

---

**Document Version:** 2.0
**Last Updated:** 2026-02-01
**Changelog:**
- v2.0 (2026-02-01): Added Adaptive PP parameters, 3-phase final approach, comprehensive parameter docs
- v1.0 (2026-01-27): Initial manual tuning workflow