Files
BQP/docs/RobotApp-TunningNav/# CONFIGURATION, WORKFLOWS & IMPLEMENTAT.md
2026-07-13 09:25:40 +07:00

888 lines
24 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# CONFIGURATION, WORKFLOWS & IMPLEMENTATION GUIDE
**Document:** Part 5 of Robot Tuning System Architecture
**Coverage:** Default configurations, tuning workflows, implementation phases, and testing strategy
---
## DEFAULT CONFIGURATIONS
All default values with detailed justifications.
---
### 1. Robot Physical Configuration
```csharp
public static class DefaultConfigurations
{
public static RobotPhysicalConfig Physical => new()
{
// Wheelbase: Distance between left and right wheels
// Typical for small indoor robot: 0.3-0.5m
// Affects: Turning radius, stability
Wheelbase = 0.35f, // meters
// Wheel radius: Affects odometry calculations
// Typical: 0.05-0.1m for small robots
WheelRadius = 0.075f, // meters
// Max linear velocity: User-specified
MaxLinearVelocity = 1.5f, // m/s
// Max angular velocity: Calculated from max linear velocity
// ω_max ≈ 2 * v_max / wheelbase
// Conservative estimate: 2 * 1.5 / 0.35 ≈ 8.57 rad/s
// Use 6 rad/s for safety margin (~343°/s)
MaxAngularVelocity = 6.0f, // rad/s
// Max linear acceleration: For smooth motion
// 1.0 m/s² means 0 → 1.5 m/s in 1.5 seconds
// Typical range: 0.5-2.0 m/s²
MaxLinearAcceleration = 1.0f, // m/s²
// Max angular acceleration: User-specified
MaxAngularAcceleration = 1.0f, // rad/s²
// Robot mass: Estimated for small mobile robot
Mass = 25.0f // kg
};
}
```
---
### 2. Control Timing Configuration
```csharp
public static ControlTimingConfig Timing => new()
{
// Control loop frequency: 50Hz (20ms per cycle)
// Justification:
// - 10Hz: Too slow, robot will oscillate
// - 50Hz: Optimal for indoor navigation (balance performance/CPU)
// - 100Hz: Better but requires more CPU, marginal gains
// - 200Hz+: Overkill for this application
ControlLoopFrequency = 50, // Hz
// Encoder sampling: Match or exceed control frequency
EncoderSamplingRate = 50, // Hz
// Motor command rate: Match control frequency
MotorCommandRate = 50 // Hz
};
```
---
### 3. PID Controller Configuration
```csharp
public static VelocityPIDConfig PID => new()
{
// Kp: Proportional gain
// Higher Kp = faster response but more overshoot
// Starting point: 0.8 (moderate response)
// Tuning range: 0.1-5.0
Kp = 0.8f,
// Ki: Integral gain
// Eliminates steady-state error
// Keep small to avoid windup
// Starting point: 0.1
// Tuning range: 0.0-2.0
Ki = 0.1f,
// Kd: Derivative gain
// Dampens oscillations, smooths response
// Starting point: 0.05 (gentle damping)
// Tuning range: 0.0-1.0
Kd = 0.05f,
// Velocity limits
MaxVelocity = 1.5f, // m/s (from physical config)
MinVelocity = 0.1f, // m/s (minimum for robot to move)
// Anti-windup: Prevent integral term from growing unbounded
IntegralWindupLimit = 0.5f, // m/s
// Output saturation: Ensure output stays within limits
OutputSaturationEnabled = true
};
```
**PID Tuning Guidelines:**
- Start with Kp only (Ki=0, Kd=0), increase until oscillation
- Reduce Kp to 60% of oscillation value
- Add Kd to dampen remaining oscillation
- Add Ki last, only if steady-state error exists
---
### 4. Velocity Estimator Configuration
```csharp
public static VelocityEstimatorConfig Estimator => new()
{
// Alpha filter: Exponential moving average for encoder
// Lower α (0.1-0.2): More filtering, more lag
// Higher α (0.3-0.4): Less filtering, more responsive
// Recommended: 0.3 for balance
AlphaFilter = 0.3f,
// Blend ratio bounds
MinBlendRatio = 0.15f, // Min 15% model, 85% encoder
MaxBlendRatio = 0.8f, // Max 80% model, 20% encoder
DefaultBlendRatio = 0.6f, // Start with 60% model
// Adaptive blending thresholds
GoodTrackingThreshold = 0.12f, // < 12% error
ModerateTrackingThreshold = 0.3f, // < 30% error
// CORRECTED blend ratios (based on architecture review):
// Good tracking → trust encoder more (model prediction matches reality)
GoodTrackingBlend = 0.3f, // 30% model, 70% encoder
// Moderate tracking → balanced
ModerateTrackingBlend = 0.5f, // 50-50 blend
// Poor tracking → trust model more (encoder may have slip)
PoorTrackingBlend = 0.7f, // 70% model, 30% encoder
// Confidence decay: How fast confidence drops
// 0.98 = slow decay (1% per cycle at 50Hz = ~2s to halve)
// 0.95 = medium decay
// 0.90 = fast decay
ConfidenceDecayRate = 0.98f,
// Minimum confidence floor
MinConfidence = 0.3f // Never go below 30%
};
```
---
### 5. Pure Pursuit Configuration
```csharp
public static PurePursuitConfig PurePursuit => new()
{
// Lookahead minimum: Smallest lookahead distance
// Too small: Oscillation, overshoot corners
// Too large: Cuts corners, poor tracking
// Recommended: 0.2-0.4m for indoor robot
LookaheadMin = 0.3f, // meters
// Kdd: Lookahead velocity scaling factor
// lookahead = LookaheadMin + Kdd * |velocity|
// Kdd = 1.0 means 1 second lookahead time
// Kdd = 0.5 means 0.5 second lookahead
// Recommended: 0.8-1.5
Kdd = 1.0f, // seconds
// Lookahead maximum: Cap lookahead distance
// Prevents looking too far ahead at high speeds
// Recommended: 1.5-3.0m
LookaheadMax = 2.0f // meters
};
```
**Pure Pursuit Tuning Guidelines:**
- Increase Kdd for smoother, more predictive tracking
- Decrease Kdd for tighter, more reactive tracking
- Increase LookaheadMin if robot oscillates
- Decrease LookaheadMin if robot cuts corners
---
### 6. Path Following Configuration
```csharp
public static PathFollowingConfig PathFollowing => new()
{
// Waypoint tolerance: How close to consider waypoint "reached"
WaypointTolerance = 0.15f, // 15cm
// Final goal tolerance: Tighter tolerance for final goal
FinalGoalTolerance = 0.05f, // 5cm
// Goal heading tolerance: Acceptable heading error at goal
GoalHeadingTolerance = 5f * MathF.PI / 180f, // 5 degrees
// Stop distance: When to start preparing to stop
StopDistance = 0.1f, // 10cm before goal
// Stop velocity: Threshold to consider robot "stopped"
StopVelocity = 0.05f // 5cm/s
};
```
---
### 7. Safety Configuration
```csharp
public static SafetyConfig Safety => new()
{
// Max cross-track error before abort
// 0.5m is reasonable for 10x20m indoor space
MaxCrossTrackError = 0.5f, // meters
// Max heading error before abort
// 45° means robot is severely off course
MaxHeadingError = 45f * MathF.PI / 180f, // radians
// Sustained error duration before abort
// 3 seconds allows recovery from temporary issues
MaxTrackingErrorDuration = 3000, // milliseconds
// Obstacle safety distances (for future sensors)
MinObstacleDistance = 0.3f, // 30cm emergency stop
SafetyStopDistance = 0.5f, // 50cm slow down
// Emergency deceleration limit
EmergencyStopDeceleration = 2.0f // m/s²
};
```
---
### 8. Acceptance Criteria Configuration
```csharp
public static AcceptanceCriteria Criteria => new()
{
// PRIMARY: Tracking Accuracy (50% weight)
// Cross-track error RMS: 10cm is good for indoor robot
MaxCrossTrackErrorRMS = 0.10f, // meters
// Peak CTE: Allow double RMS as occasional spike
MaxCrossTrackErrorPeak = 0.20f, // meters
// Heading error: 10° RMS is acceptable
MaxHeadingErrorRMS = 10f * MathF.PI / 180f, // radians
// Goal position error: 5cm final accuracy
MaxGoalPositionError = 0.05f, // meters
// Goal heading error: 5° final accuracy
MaxGoalHeadingError = 5f * MathF.PI / 180f, // radians
// SECONDARY: Smoothness (30% weight)
// Max jerk: 5 m/s³ is smooth for human comfort
MaxJerk = 5.0f, // m/s³
// Max angular jerk: 10 rad/s³
MaxAngularJerk = 10.0f, // rad/s³
// TERTIARY: Efficiency (20% weight)
// Path length ratio: <15% deviation from optimal
MaxPathLengthRatio = 1.15f, // 115% of optimal
// Success rate: 90% of runs should pass
MinSuccessRate = 0.90f // 90%
};
```
---
### 9. Scoring Weights
```csharp
public static ScoringWeights Weights => new()
{
// How much each category contributes to overall score
TrackingAccuracy = 0.5f, // 50%
Smoothness = 0.3f, // 30%
Efficiency = 0.2f // 20%
};
```
---
### 10. Parameter Bounds
```csharp
public static class ParameterBounds
{
// PID bounds
public static Range KpRange = new(0.1f, 5.0f);
public static Range KiRange = new(0.0f, 2.0f);
public static Range KdRange = new(0.0f, 1.0f);
// Estimator bounds
public static Range AlphaFilterRange = new(0.05f, 0.5f);
public static Range BlendRatioRange = new(0.1f, 0.9f);
public static Range ConfidenceDecayRange = new(0.90f, 0.99f);
// Pure Pursuit bounds
public static Range KddRange = new(0.3f, 2.0f);
public static Range LookaheadMinRange = new(0.1f, 0.5f);
public static Range LookaheadMaxRange = new(0.5f, 3.0f);
// Validation rules
public static List<ValidationRule> Rules => new()
{
new ValidationRule
{
Name = "LookaheadOrdering",
Check = (p) => p.PurePursuit.LookaheadMax > p.PurePursuit.LookaheadMin,
Message = "LookaheadMax must be greater than LookaheadMin"
},
new ValidationRule
{
Name = "BlendRatioOrdering",
Check = (p) => p.Estimator.GoodTrackingBlend <= p.Estimator.PoorTrackingBlend,
Message = "GoodTrackingBlend should be less than PoorTrackingBlend"
},
new ValidationRule
{
Name = "VelocityLimit",
Check = (p) => p.PID.MaxVelocity <= p.Physical.MaxLinearVelocity,
Message = "PID MaxVelocity cannot exceed physical limit"
}
};
}
```
---
## TUNING WORKFLOWS
Detailed step-by-step workflows for different tuning scenarios.
---
### Workflow 1: Quick Start (First-Time User)
**Goal:** Get robot moving with default settings and validate basic functionality.
**Steps:**
1. **Load Default Configuration** (5 min)
- Open dashboard
- Navigate to Configuration → Robot Settings
- Verify physical parameters (wheelbase, wheel radius)
- Click "Load Default Preset"
2. **Run Baseline Test** (2 min)
- Select Test Scenario: "Straight Line 10m"
- Click "Run Test"
- Observe real-time visualization
- Wait for completion
3. **Review Results** (3 min)
- Check overall score
- Identify which metrics fail (if any)
- Note: CTE RMS, jerk, smoothness
4. **Decision Point:**
- Score > 80: Proceed to Workflow 2 (test other trajectories)
- Score 60-80: Proceed to Workflow 3 (manual tuning)
- Score < 60: Check robot hardware, retry
**Expected Outcome:** Baseline performance established, ready for tuning.
---
### Workflow 2: Multi-Scenario Validation
**Goal:** Test current configuration across all trajectory types.
**Steps:**
1. **Setup Batch Test** (2 min)
- Navigate to Tuning → Parameter Comparison
- Select all scenarios:
- Straight Line 10m
- Circle 2m Radius
- Circle 0.5m Radius
- Select current parameter set
- Click "Run Batch"
2. **Monitor Progress** (10-15 min)
- Watch each test in sequence
- Note any failures or safety violations
3. **Analyze Comparison** (5 min)
- View comparison table
- Identify weakest scenario
- Check metric breakdown per scenario
4. **Decision Point:**
- All scenarios pass: Configuration is robust
- One scenario fails: Tune for that specific case
- Multiple scenarios fail: Need general tuning (Workflow 3)
---
### Workflow 3: Manual Iterative Tuning
**Goal:** Hand-tune parameters to improve specific metrics.
**Steps:**
**Phase 1: Improve Tracking Accuracy (if CTE RMS > 0.10m)**
1. **Diagnose Issue:**
- View trajectory plot
- Check if robot overshoots or undershoots corners
- Check if error is consistent or oscillating
2. **If Robot Overshoots (cuts corners):**
- Decrease Pure Pursuit LookaheadMin: 0.3 → 0.25
- Decrease Kdd: 1.0 → 0.8
- Run test, check improvement
3. **If Robot Undershoots (goes wide):**
- Increase Pure Pursuit LookaheadMin: 0.3 → 0.35
- Increase Kdd: 1.0 → 1.2
- Run test, check improvement
4. **If Robot Oscillates:**
- Increase PID Kd: 0.05 → 0.15 (more damping)
- Increase Estimator AlphaFilter: 0.3 → 0.4 (more smoothing)
- Run test, check improvement
5. **If Robot is Sluggish:**
- Increase PID Kp: 0.8 → 1.2 (faster response)
- Run test, check for overshoot
**Phase 2: Improve Smoothness (if Jerk > 5.0 m/s³)**
1. **Increase Damping:**
- Increase PID Kd: current → +0.1
- Run test
2. **Smooth Velocity Estimates:**
- Decrease Estimator AlphaFilter: 0.3 → 0.2
- Run test
3. **Reduce Aggressiveness:**
- Decrease PID Kp: current → -0.2
- Run test
**Phase 3: Verify and Save**
1. **Run Full Validation:**
- Test all scenarios with new parameters
- Ensure no regressions
2. **Save Configuration:**
- Name: "Tuned_[Date]_v1"
- Add description of changes
- Click "Save"
**Iteration:** Repeat phases as needed, aiming for <5 iterations.
---
### Workflow 4: Automated Optimization (Advanced)
**Goal:** Use algorithm to find optimal parameters automatically.
**Steps:**
1. **Configure Optimization** (5 min)
- Navigate to Tuning → Auto Tuning
- Select algorithm: Bayesian Optimization
- Select parameters to tune:
- ☑ PID: Kp, Ki, Kd
- ☑ Pure Pursuit: Kdd
- ☐ Estimator: (keep fixed for first run)
- Set constraints:
- Max iterations: 30
- Early stopping: 1% improvement threshold
2. **Define Objective** (2 min)
- Primary metric: Cross-Track Error RMS
- Secondary metric: Max Jerk (weight: 0.3)
- Test scenario: Circle 2m Radius
3. **Start Optimization** (30-60 min)
- Click "Start Optimization"
- Monitor progress dashboard
- View live updates of best parameters found
4. **Review Results** (10 min)
- Check final parameters
- Compare to baseline
- Review improvement %
5. **Validate on Other Scenarios** (15 min)
- Run batch test with optimized parameters
- Ensure no regressions on other trajectories
6. **Save or Iterate:**
- If satisfied: Save as "Optimized_v1"
- If not: Adjust weights, re-run optimization
---
### Workflow 5: A/B Testing Configurations
**Goal:** Compare two parameter sets side-by-side.
**Steps:**
1. **Select Configurations** (2 min)
- Config A: "Default"
- Config B: "Tuned_v1"
2. **Choose Test Scenario** (1 min)
- Straight Line 10m
3. **Run Comparison** (5 min)
- Click "Run Comparison"
- System runs both tests sequentially
4. **Analyze Results** (5 min)
- View side-by-side metrics table
- Check trajectory overlay plot
- Identify winner
5. **Statistical Significance** (optional)
- Run 10 trials each
- Compare mean ± std deviation
- Determine if difference is significant
---
## IMPLEMENTATION PHASES
Phased approach to building the system, prioritized by value and complexity.
---
### Phase 0: MVP (Weeks 1-3)
**Goal:** Core functionality for manual tuning.
**Features:**
- ✅ Single test execution
- ✅ Manual parameter adjustment UI
- ✅ Real-time visualization (2D trajectory)
- ✅ Basic metrics calculation
- ✅ Save/load configurations
- ✅ Data logging
**Deliverables:**
1. Working Blazor dashboard
2. Integrated controllers (PID, Estimator, Pure Pursuit)
3. Basic test executor
4. SQLite database with core tables
5. Real-time SignalR updates
**Tech Stack:**
- Blazor Server
- Entity Framework Core + SQLite
- SignalR
- Plotly.NET for charts
**Testing:**
- Unit tests for controllers
- Integration test for one full test run
- Manual UI testing
**Success Criteria:**
- User can run a test and see results
- Parameters can be adjusted and re-run
- Metrics are calculated correctly
---
### Phase 1: Enhanced Tuning (Weeks 4-6)
**Goal:** Multi-scenario testing and comparison.
**Features:**
- ✅ Batch testing
- ✅ Configuration comparison
- ✅ Test history viewer
- ✅ Safety monitoring with abort
- ✅ Parameter validation
- ✅ CSV export
**Deliverables:**
1. Batch test executor
2. Comparison UI components
3. Enhanced database queries
4. Safety monitor implementation
5. Report generation (HTML/CSV)
**Testing:**
- Batch test with 3 scenarios
- Comparison test with 3 configs
- Safety violation test
**Success Criteria:**
- Batch tests complete without manual intervention
- Comparison clearly shows best configuration
- Safety system aborts on violations
---
### Phase 2: Advanced Analytics (Weeks 7-9) - OPTIONAL
**Goal:** Deep insights and semi-automated tuning.
**Features:**
- ⭕ Statistical analysis
- ⭕ Trend analysis over time
- ⭕ Parameter sensitivity analysis
- ⭕ Tuning suggestions
- ⭕ PDF report generation
**Deliverables:**
1. Statistics calculator
2. Trend visualization
3. Suggestion engine (rule-based)
4. PDF generator
**Testing:**
- Historical data analysis (50+ tests)
- Suggestion accuracy validation
**Success Criteria:**
- Trends clearly visible
- Suggestions improve results
---
### Phase 3: Automated Optimization (Weeks 10-13) - FUTURE
**Goal:** Hands-off parameter optimization.
**Features:**
- ❌ Grid search
- ❌ Random search
- ❌ Bayesian optimization
- ❌ Genetic algorithm
- ❌ Multi-objective optimization
**Deliverables:**
1. Optimization framework
2. Multiple algorithm implementations
3. Hyperparameter tuning for optimizers
4. Parallel evaluation (if multiple robots)
**Complexity:** Very High (requires ML libraries)
**Testing:**
- Benchmark against manual tuning
- Convergence tests
- Robustness tests
**Success Criteria:**
- Automated optimization finds better params than manual in <1 hour
- Reproducible results
---
## TESTING STRATEGY
Comprehensive testing at all levels.
---
### 1. Unit Tests
**Coverage Target:** >80% for domain logic
**Key Tests:**
```csharp
// PID Controller Tests
[Fact]
public void PIDController_ProportionalOnly_CorrectOutput()
{
var config = new VelocityPIDConfig { Kp = 1.0f, Ki = 0, Kd = 0 };
var pid = new PIDController(config);
var output = pid.Calculate(error: 1.0f, dt: 0.02f);
Assert.Equal(1.0f, output, precision: 2);
}
[Fact]
public void PIDController_IntegralWindup_Clamped()
{
var config = new VelocityPIDConfig
{
Kp = 0,
Ki = 1.0f,
Kd = 0,
IntegralWindupLimit = 0.5f
};
var pid = new PIDController(config);
// Accumulate large error
for (int i = 0; i < 100; i++)
pid.Calculate(error: 1.0f, dt: 0.02f);
var output = pid.Calculate(error: 1.0f, dt: 0.02f);
Assert.True(output <= 0.5f);
}
// Velocity Estimator Tests
[Fact]
public void VelocityEstimator_GoodTracking_TrustsEncoder()
{
var config = DefaultConfigurations.Estimator;
var estimator = new VelocityEstimator(config, new VelocitySignalProcessingConfig());
var vHybrid = estimator.EstimateVelocity(
vCmd: 1.0f,
vActual: 0.95f, // Close to command (good tracking)
dt: 0.02f
);
// Should blend more toward encoder (0.95) than model
Assert.True(vHybrid > 0.93f && vHybrid < 0.97f);
}
// Pure Pursuit Tests
[Fact]
public void PurePursuit_LookaheadScalesWithVelocity()
{
var config = new PurePursuitConfig
{
LookaheadMin = 0.3f,
Kdd = 1.0f,
LookaheadMax = 2.0f
};
var pp = new PurePursuitController(config);
var path = CreateStraightLinePath(10);
var pose = new Pose2D(0, 0, 0);
pp.Calculate(pose, velocity: 0.5f, confidence: 1.0f, path);
var lookahead1 = pp.GetLookaheadDistance();
pp.Calculate(pose, velocity: 1.0f, confidence: 1.0f, path);
var lookahead2 = pp.GetLookaheadDistance();
Assert.True(lookahead2 > lookahead1);
}
```
---
### 2. Integration Tests
```csharp
[Fact]
public async Task FullTestRun_StraightLine_Completes()
{
// Arrange
var scenario = CreateStraightLineScenario(10);
var parameters = DefaultConfigurations.GetDefaultPreset();
var orchestrator = CreateOrchestrator();
// Act
var result = await orchestrator.RunSingleTest(scenario, parameters);
// Assert
Assert.Equal(TestStatus.Completed, result.Status);
Assert.NotNull(result.Metrics);
Assert.True(result.Metrics.CrossTrackErrorRMS < 0.20f);
}
[Fact]
public async Task SafetyMonitor_ExcessiveCTE_AbortsTest()
{
// Arrange
var scenario = CreateCircleScenario(0.5f); // Tight circle
var parameters = CreateBadParameters(); // Intentionally bad
var orchestrator = CreateOrchestrator();
// Act
var result = await orchestrator.RunSingleTest(scenario, parameters);
// Assert
Assert.Equal(TestStatus.Aborted, result.Status);
Assert.True(result.SafetyViolations.Any(v => v.Type == ViolationType.CrossTrackError));
}
```
---
### 3. Performance Tests
```csharp
[Fact]
public void ControlLoop_MaintainsFrequency()
{
var executor = CreateTestExecutor();
var scenario = CreateStraightLineScenario(5);
var parameters = DefaultConfigurations.GetDefaultPreset();
var timestamps = new List<long>();
executor.ExecuteAsync(
onStateUpdate: state => timestamps.Add(state.TimestampMs)
).Wait();
// Calculate actual frequency
var intervals = timestamps.Zip(timestamps.Skip(1), (a, b) => b - a);
var avgInterval = intervals.Average();
var actualFrequency = 1000.0 / avgInterval;
Assert.InRange(actualFrequency, 48, 52); // 50Hz ± 2Hz
}
```
---
### 4. End-to-End Tests
**Manual Test Plan:**
1. **Happy Path Test**
- Load default config
- Run straight line test
- Verify metrics displayed
- Save configuration
- Reload and verify
2. **Error Handling Test**
- Set invalid parameter (Kp = 100)
- Attempt to run test
- Verify error message shown
- Verify test doesn't start
3. **Real-time Update Test**
- Start test
- Verify UI updates at ~10Hz
- Pause test
- Verify pause works
- Resume and complete
4. **Comparison Test**
- Create 2 configs
- Run comparison
- Verify side-by-side display
- Export results
---
## DEPLOYMENT CHECKLIST
Pre-deployment validation:
- [ ] All unit tests pass
- [ ] Integration tests pass
- [ ] Performance tests pass
- [ ] Manual E2E tests completed
- [ ] Database migrations created
- [ ] Default data seeded
- [ ] Configuration files reviewed
- [ ] Robot hardware tested
- [ ] Emergency stop tested
- [ ] Documentation complete
- [ ] User manual created
---
This completes the Configuration, Workflows & Implementation Guide.