Global Navigation Runtime Config

Location

Runtime config is under:

AppSettings:GlobalNavigation

In this repo, examples are already added to:

1. src/Rcs.Api/appsettings.Development.json
2. src/Rcs.Api/appsettings.Production.json

Coordinator

Path:

AppSettings:GlobalNavigation:Coordinator

Fields:

1. ResumeStablePassThreshold
   • Consecutive pass checks required before leaving hold/queue.
2. ResumeDispatchCooldownSeconds
   • Minimum interval between scheduler-triggered resume dispatches for same hold key.
3. ResumeScanIntervalMilliseconds
   • Poll interval for hold-resume scheduler to pick due requests.
4. HoldSecondsShort
   • Standard hold cooldown duration.
5. HoldSecondsQueue
   • Queue hold cooldown duration for junction occupancy.
6. QueueStaleSeconds
   • Expiration window for queue fairness tickets; stale robots are cleaned from queue.
7. ConflictEscalateNearestWaitThreshold
   • Fail streak threshold to try WaitNearest patch.
8. ConflictEscalateDetourThreshold
   • Fail streak threshold to try LocalDetour.
9. ConflictEscalateLateralYieldThreshold
   • Fail streak threshold to try LateralYield.
10. ConflictEscalateParkingThreshold
    • Fail streak threshold to try ParkingYield.
11. ConflictEscalateRetreatThreshold
    • Fail streak threshold to try Retreat.
12. ConflictEscalateReplanThreshold
    • Fail streak threshold to try ReplanTail.
13. EnableLateralYield
    • Enable/disable LateralYield.
14. EnableParkingYield
    • Enable/disable ParkingYield.
15. EnableRetreat
    • Enable/disable Retreat.
16. DecisionMetricsIntervalSeconds
    • Logging interval for [GlobalNav] DecisionMetrics.

PathCas

Path:

AppSettings:GlobalNavigation:PathCas

Fields:

1. MetricsIntervalSeconds
   • Logging interval for [PathCAS] metric line.
2. WindowDurationSeconds
   • Sliding window used for high-conflict detection.
3. HighConflictMinAttempts
   • Minimum attempts in window before conflict-ratio backoff is enabled.
4. HighConflictRatioThreshold
   • Conflict ratio threshold (0.0-1.0) to trigger backoff.
5. EnableHighConflictBackoff
   • Enable/disable jitter delay under high conflict ratio.
6. BackoffMinMs
   • Minimum jitter delay.
7. BackoffMaxMs
   • Maximum jitter delay.

Tuning Suggestion

1. If robots often oscillate at junctions:
   • increase ResumeStablePassThreshold from 2 to 3.
2. If congestion is short and frequent:
   • lower HoldSecondsShort to reduce idle wait.
3. If CAS conflict spikes under burst:
   • lower HighConflictRatioThreshold slightly and keep backoff enabled.
4. If parking/retreat causes too many long detours:
   • raise corresponding escalate thresholds by 1.
5. If side-lane yielding is overused in narrow maps:
   • increase ConflictEscalateLateralYieldThreshold or disable EnableLateralYield.
6. If queue blocking appears unfair at busy junctions:
   • tune QueueStaleSeconds (too high causes stale tickets, too low causes requeue churn).

Runtime Verification

Use provided scripts:

1. Hot reload smoke:
   • scripts/global-nav/Invoke-GlobalNavHotReloadSmoke.ps1
2. HTTP concurrency stress template:
   • scripts/global-nav/Invoke-PathCasHttpStressTemplate.ps1
3. Hold/queue/resume smoke:
   • scripts/global-nav/Invoke-GlobalNavHoldQueueResumeSmoke.ps1

Typical flow:

1. Keep service running with reloadOnChange=true default behavior.
2. Run hot reload smoke script and confirm log:
   • [GlobalNav] ConfigUpdated ...
3. Run stress template against your send-next endpoint and confirm logs:
   • [PathCAS] ...
   • [PathCAS] HighConflictBackoff ... when conflict is high.
   • [GlobalNav] ResumeMetrics ... for hold-resume scheduler behavior.
4. Run hold/queue/resume smoke with optional log parsing:
   • Example: powershell -File scripts/global-nav/Invoke-GlobalNavHoldQueueResumeSmoke.ps1 -ApiBaseUrl http://localhost:5000 -RobotManufacturer HUAHENG -RobotSerialNumber 1001 -LogPath logs/app.log
   • Confirm patterns: [GlobalNav] HoldEscalationCandidates queue turn pending ResumeDispatchTriggered [GlobalNav] ResumeMetrics

Hold Resume Trigger Flow

When SendNextSegment enters Hold or Queue:

1. Hold state is persisted with CAS and HoldUntilUtc.
2. A resume request is scheduled by IGlobalNavigationResumeScheduler.
3. SendNextSegment precheck will short-circuit while hold window is not reached.
4. Scheduler wakes at ResumeAtUtc, then validates:
   • cache PlanVersion still matches the scheduled version
   • RouteMode is still HoldingAtWaitNode or QueueingForJunction
   • for queue mode, robot ticket reaches queue head (fairness gate)
   • robot is not driving
5. If checks pass, scheduler triggers SendNextSegmentAsync(manufacturer, serialNumber).
6. If stale/transient (version changed, still driving, lock in progress), it skips or requeues.