Skip to content

feat(failsafe): document priority axioms, add conflict resolution tests, and A3 fallback notification#26948

Draft
Rpirayesh wants to merge 3 commits intoPX4:mainfrom
Rpirayesh:feature/failsafe-priority-framework-docs-tests
Draft

feat(failsafe): document priority axioms, add conflict resolution tests, and A3 fallback notification#26948
Rpirayesh wants to merge 3 commits intoPX4:mainfrom
Rpirayesh:feature/failsafe-priority-framework-docs-tests

Conversation

@Rpirayesh
Copy link
Copy Markdown

Summary

The failsafe priority framework applies five axioms (A1–A5) to resolve conflicting failure conditions, but these rules were undocumented and untested. When the framework silently degraded from RTL to Land (e.g., GPS lost mid-RTL), operators received no notification.

This PR addresses all three gaps:

  • Documentation — inline comments with worked examples for each axiom in failsafe.cpp and framework.cpp
  • Unit tests — 4 new GoogleTest cases covering the highest-risk conflict scenarios
  • Operator notificationnotifyA3Fallback() fires a mavlink_log_critical + structured event when the framework degrades an action, with an anti-spam guard (fires at most once per worsening step)
  • Log validatorvalidate_a3_fallback_log.py verifies A3 fallback event counts from ULogs

Files Changed

File Change
failsafe.cpp Priority axiom comments with worked examples (navigator_failure, geofence, battery)
failsafe_test.cpp 4 new tests + FailsafeTesterWithFallbackCapture fixture
framework.cpp A3 fallback event emission, competing-conditions diagnostic
framework.h notifyA3Fallback() virtual method
validate_a3_fallback_log.py Post-flight ULog validator for A3 fallback chain

New Tests

Test Axiom
conflict_higher_priority_wins A1 — highest severity dominates
conflict_geofence_breach_during_rtl A4 — duplicate RTL downgrades to Warn
rtl_fallback_to_land_when_home_invalid A3 — RTL→Land when home unavailable
land_overrides_active_rtl_without_delay A1 + clearDelayIfNeeded

Testing

make tests TESTFILTER=failsafe

…fallback notification

Hardens the failsafe priority resolution framework with three changes:

1. Inline documentation: adds worked examples for axioms A1/A3/A4/A5
   directly in failsafe.cpp covering navigator_failure, geofence breach,
   and battery escalation edge cases.

2. Unit tests: four new GoogleTest cases exercise the highest-risk
   conflict scenarios — simultaneous conditions (A1), duplicate RTL
   suppression (A4), RTL→Land fallback when home is invalid (A3), and
   Land overriding active RTL without a Hold interlude.

3. A3 fallback notification: notifyA3Fallback() emits a mavlink_log_critical
   and structured event when the framework silently degrades an action
   (e.g. RTL→Land due to GPS loss), with an anti-spam guard that fires
   at most once per worsening step. Includes a Python post-flight log
   validator (validate_a3_fallback_log.py) to verify event counts from ULogs.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant