I150/docs/RobotApp-TunningNav/TUNING_WORKFLOW_GUIDE.md

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
2. Quick Start - Workflow Cơ Bản
3. Parameter Reference
4. Troubleshooting Scenarios
5. Advanced Tuning Techniques
6. 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:

GoalRegionDistance ≥ MaxLinearVelocity² / (2 × deceleration)

---

Preset Configurations (Quick Start)

Preset 1: Warehouse Standard

{
  "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

{
  "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

{
  "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:

// 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:

{
  "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