mirror of
https://github.com/PX4/PX4-Autopilot.git
synced 2026-11-22 22:43:06 +08:00
* feat(motor_failure_detector): add current-residual detection library
Per-motor model-based motor-failure detector for multirotors. Predicts the
expected ESC current from the commanded actuator signal
(I_exp = current_slope_a*u + current_idle_a) and trips on a low-pass-filtered
residual held past a trip band for a persistence time. The command (not measured
rpm) is the fault-independent reference: a dead motor that draws no current while
still commanded produces a large residual, whereas a current-vs-rpm model would
mask a clean stop.
Band and persistence are configurable per residual direction. Undercurrent is the
fault-consistent side -- an open circuit, a shed propeller or a desync makes a
motor draw less than commanded -- while overcurrent covers a winding short,
mechanical jam or demagnetization. They are separate because the benign residual
is far from symmetric: a fast throttle increase draws acceleration current the
static model cannot predict, so overcurrent excursions are large and unbounded,
whereas an undercurrent residual is floored at -I_exp. A single band sized to
reject the overcurrent transients can therefore end up wider than the largest
undercurrent fault a motor can physically produce, which makes a full current
collapse undetectable rather than merely slow. Set undercurrent_threshold_a <= 0
to keep one symmetric band on the residual magnitude.
Built on PX4 primitives rather than hand-rolled equivalents: update() takes a
timestamp (esc_status.timestamp in flight, the log timestamp in replay) and
derives dt internally; the residual filter is a mathlib AlphaFilter; the
persistence debounce is a systemlib::Hysteresis per direction (with a sticky latch
on top, and reset across data gaps so a dropout can't complete a pending trip).
The data-gap threshold (kMaxGap = 0.3 s) is sized above the ~10 Hz arming-check
feed interval and below the 400 ms ESC-offline timeout: a live feed is never
mistaken for a gap (a smaller value equal to the feed interval reset the filter
and debounce on the majority of jittered ticks, so a sustained fault never
survived the persistence window -- offline replay: 0/100 sampling phases latched
vs 100/100 gap-free), while a genuine outage still resets and is handled by the
separate ESC liveness guard.
Includes an 18-case gtest spanning the failure-mode spectrum and edge cases:
healthy-never-trips (incl. high throttle), open-circuit and overcurrent trips,
severe prop-loss undercurrent, the missed ~50% partial loss (documents the
detection floor), the per-direction bands (a tighter undercurrent band catching a
collapse one symmetric band misses, band independence, per-side persistence),
persistence (short spike crosses-threshold-but-recovers), gap reset, the 10 Hz
feed vs. real-gap boundary, dropout-holds, multi-motor, the exclusion gate,
monitor-only, and reset/latch.
* refactor(motor_failure_detector): resolve the undercurrent band at configure time
An unset undercurrent threshold now mirrors the overcurrent band in
configure(), so update() runs the same two bands in every configuration and
no longer carries a second threshold test that reads like a repeat of the
disable gate. A symmetric band is the two-band case with equal bands.
Also name esc_status CONNECTED_ESC_MAX at kMaxMotors so the constant is
findable, use the PX4 time literals for the persistence conversions, and
drop the excluded temporary.
* feat(commander): use current-residual detector for the ESC motor-failure check
Replace the flat, instantaneous current check in EscChecks::checkMotorStatus with
the MotorFailureDetector library (added in the parent PR). Per motor it predicts
the expected ESC current from the commanded thrust
(I_exp = MOTFAIL_C2T*u + MOTFAIL_IDLE) and trips on the low-pass-filtered
residual, with an independent band and hold time per direction: MOTFAIL_UNDER held
for MOTFAIL_UND_TIME below the expectation, MOTFAIL_OVER held for MOTFAIL_OVR_TIME
above it.
Because the two directions need separate bands, the single band and hold time are
renamed to name the direction they act on: MOTFAIL_OFF -> MOTFAIL_OVER and
MOTFAIL_TIME -> MOTFAIL_OVR_TIME, migrated in param_translation.cpp. The old band
applied to both directions, so it carries over to the overcurrent side, and
MOTFAIL_UNDER defaults to 0, which keeps a single symmetric band -- an existing
vehicle behaves as before. MOTFAIL_IDLE also defaults to 0, and the whole check
stays gated by FD_ACT_EN (off by default).
The detector is driven off esc_status.timestamp, so a telemetry stall freezes the
filter instead of integrating stale current; the separate 400 ms ESC telemetry
timeout stays in checkEscOnline(). It is reconfigured from parameters while
disarmed, so a parameter change never resets a latched failure mid-flight. The
motor_failure_mask still feeds failure_detector_status via
FailureDetector::publishStatus, leaving the ControlAllocator reaction path
untouched.
The mask reports the detector's sticky latch alone, not whether the motor is
currently evaluable. That preserves the invariant the previous check spelled out
-- "Only set, never clear mid-air: stopping the motor in response could make it
appear healthy again" -- because handling a failure makes exactly that motor
unevaluable: the control allocator drops it, which publishes a NAN command,
which excludes it from the detector. Re-deriving the mask from the exclusion
state clears it, the allocator restores all motors, and the next check re-trips.
Measured in SIH on a hexarotor with a missing propeller: 83 mask transitions in
nine seconds, with a reversed recovery motor swinging between idle and near-full
reverse at the 10 Hz check rate. An ESC going offline after a real failure
retracts the report the same way. The latch is only ever set on a tick where the
motor was evaluable, so reporting it alone cannot report a motor that was never
judged.
* feat(motor_failure_detector): add offline ulog replay tool
Add a host tool that replays a recorded .ulg through the real MotorFailureDetector
and prints the per-motor trip verdict, for validating and tuning the detector
offline (EKF2-replay style: the real library drives recorded data, not a
re-implementation).
Built on ulog_cpp (PX4's C++ ULog library, added as a git submodule and built for
the posix host target only), so it reads ESC current, motor command and arming
state by field name from the log's own format -- one binary replays logs of any
PX4 message version with no rebuild. The feed mirrors the runtime in escCheck:
evaluated only while armed, at the runtime's 10 Hz cadence, with the per-ESC
current-report startup latch and reset-on-disarm. Config comes from the log's
MOTFAIL_* parameters with a built-in calibration fallback, and --set
MOTFAIL_NAME=value overrides any knob for what-if retuning. Because the runtime's
exact 10 Hz sample phase cannot be reconstructed offline, a single pass over the log
drives several detector instances on staggered grid offsets and reports a per-motor
peak band and trip fraction rather than a single phase's verdict, flagging when the
result is phase-dependent.
batch_replay.sh runs the tool over a folder of logs and summarizes each verdict
(OK / FAIL / SKIP) from its exit code.
Off by default so it never enters the firmware build or CI: it is a posix-only,
EXCLUDE_FROM_ALL host executable gated behind the MFD_REPLAY_TOOL cache option.
Build it with:
cmake -DMFD_REPLAY_TOOL=ON build/px4_sitl_default
ninja -C build/px4_sitl_default mfd_replay
* docs(motor_failure_detector): document the current-residual motor-failure check
Add a configuration page for motor failure detection, next to the other
actuator topics, and a developer page for the offline replay tool:
- what the check compares and why the under/overcurrent bands are separate
- the new MOTFAIL_* parameters, including the rename migration
- how to fit the current model and pick the bands from the vehicle's own
logs with mfd_replay / batch_replay.sh
The "Motor Failure Trigger" section in the failsafe page described the
pre-rename parameters, the unfiltered symmetric comparison and claimed the
failure was non-latching, so it is reduced to a summary of the trigger and
its action, pointing at the new page for the thresholds.
* docs(docs): Subedit for simpler introductions and terminology
* docs(docs): Improve upgrading from v1.18 section
* feat(motor_failure_detector): add current-model fitting tool
mfd_fit derives MOTFAIL_C2T and MOTFAIL_IDLE from recorded logs, so the model
and the thresholds are taken from the same data.
Like mfd_replay it reads ESC current, motor command and arming state through
ulog_cpp by field name, so one binary handles any log version. Each log is a
single streaming pass that accumulates only the sums a least-squares line needs,
so memory does not grow with the log or with the number of logs, and a whole
corpus can be fitted in one invocation.
Alongside the parameters it reports the residual spread the trip bands have to
clear, and each motor's bias against the shared model.
* docs(docs): document motor failure detection tuning and the fitting tool
Follow-up to review of the detection and replay pages:
- fix the link left behind by the Failure Response -> Failure Action rename
- drop the Multicopter badge: the check has no vehicle-type gate, so a VTOL's
multirotor motors and its forward-flight motor are both checked
- describe the model-fitting step without the statistics jargon
- state that only healthy logs may be used, for the fit and the thresholds
- document mfd_fit, and reduce the release note to a pointer
* feat(motor_failure_detector): report residual extremes and add a band sweep
The replay tool printed the largest residual magnitude, which hid whether an
excursion was above or below the model. Since the two trip bands are chosen per
direction, that left the reader running one band at a time to find out. It now
prints the signed minimum and maximum instead, so each band's headroom is
readable straight from the table.
Add sweep_matrix.sh alongside batch_replay.sh: it sweeps one band against its
hold time over a set of logs and prints how many logs false-trip at each pair,
so the lowest usable band per hold time is the first zero in a row.
Both tools now number motors from 1, matching the "Motor N ..." the vehicle
reports, rather than from 0.
* docs(docs): rework the motor failure calibration walkthrough
Follow a real calibration through both pages and fix what it ran into:
- the replay page's worked example is one vehicle end to end, with every
number and pasted output taken from that corpus
- the fitting tool, the single-log run and the band sweeps are ordered the way
the work is actually done, with replaying a whole fleet last
- the sweeps are shown as a matrix of false trips per (hold time, band), and
the grids are derived from the residual extremes rather than guessed
- commands match the output they produce, and say what they need: mfd_replay
without --set uses a fallback calibration that belongs to another vehicle
- vehicle_status is optional, not required, for the replay
- drop the repetition: batch_replay.sh, the hover-current ceiling and the
phase-sensitivity note were each explained two or three times
* fix(motor_failure_detector): separate configure and reset with the appropriate triggers
* refactor(motor_failure_detector): clarify leading edge hysteresis as trigger time compared to "persistence"
* fix(escCheck): encapsulate _motor_failure_direction handling into MotorFailureDetector
* fix(astyle): exclude ulog_cpp submodule form check
* fix(motor_failure_detector_tools): fail log replay when no log is present
* refactor(motor_failure_detector): Improve documentation
* fix(escCheck): check load per ESC not per motor function
This was already done in my original implementation. It supports checking multiple ESCs mapped to the same motor function individually. It's also consistent with other ESC checks that run for every ESC that reports telemetry.
* fix(motor_failure_detector): run update() per motor and consider individual telemetry timestamps
* fix(motor_failure_detector): simplify output interface to getters of actually used results
* fix(motor_failure_detector): inline what doesn't need to be separate
* fix(motor_failure_detector): make the bands independent and drop special cases
- Each trip band is now independent: a threshold <= 0 disables only that band. The undercurrent band no longer copies the overcurrent one.
- Drop the MOTFAIL_OFF/MOTFAIL_TIME parameter migration. The new parameters start at their defaults.
- Treat a non-finite current like a non-finite command (not evaluated, filter and debounce reset). No driver reports NaN current, so the path only existed for its test.
- Compute the residual as max(current, 0) - I_expected. Same as before, but written such that it's obvious: regeneration counts as 0A.
- Drop unnecessary trigger time parameter clamp to >= 0 before converting to unsigned microseconds, metadate already decalres that as out of range.
- Count each ESC sample once by its own timestamp in mfd_fit, like the motor_failure_detector.
* fix(motor_failure_detector): check all still considered online ESC telemetry
* fix(motor_failure_detector): declare all link dependencies
* fix(motor_failure_detector_tools): reuse log reading logic to reduce duplication
* fix(motor_failure_detector): replace reversible flag getting passed into the detector for separate handling
Having a NAN command already handles that.
* test(escChecks): add unit tests for load based failure detection
---------
Co-authored-by: Hamish Willee <hamishwillee@gmail.com>
Co-authored-by: Matthias Grob <maetugr@gmail.com>
Co-authored-by: Andrea Bernasconi <andrea.bernasconi@auterion.com>
124 lines
5.2 KiB
Plaintext
124 lines
5.2 KiB
Plaintext
[submodule "src/modules/mavlink/mavlink"]
|
|
path = src/modules/mavlink/mavlink
|
|
url = https://github.com/mavlink/mavlink.git
|
|
branch = master
|
|
[submodule "Tools/simulation/gazebo-classic/sitl_gazebo-classic"]
|
|
path = Tools/simulation/gazebo-classic/sitl_gazebo-classic
|
|
url = https://github.com/PX4/PX4-SITL_gazebo-classic.git
|
|
branch = main
|
|
[submodule "src/drivers/gps/devices"]
|
|
path = src/drivers/gps/devices
|
|
url = https://github.com/PX4/PX4-GPSDrivers.git
|
|
branch = main
|
|
[submodule "platforms/nuttx/NuttX/nuttx"]
|
|
path = platforms/nuttx/NuttX/nuttx
|
|
url = https://github.com/PX4/NuttX.git
|
|
branch = px4_firmware_nuttx-12.12.0+
|
|
[submodule "platforms/nuttx/NuttX/apps"]
|
|
path = platforms/nuttx/NuttX/apps
|
|
url = https://github.com/PX4/NuttX-apps.git
|
|
branch = px4_firmware_nuttx-12.12.0+
|
|
[submodule "Tools/flightgear_bridge"]
|
|
path = Tools/simulation/flightgear/flightgear_bridge
|
|
url = https://github.com/PX4/PX4-FlightGear-Bridge.git
|
|
[submodule "Tools/simulation/jsbsim/jsbsim_bridge"]
|
|
path = Tools/simulation/jsbsim/jsbsim_bridge
|
|
url = https://github.com/PX4/px4-jsbsim-bridge.git
|
|
[submodule "src/drivers/cyphal/libcanard"]
|
|
path = src/drivers/cyphal/libcanard
|
|
url = https://github.com/opencyphal/libcanard.git
|
|
[submodule "src/drivers/cyphal/public_regulated_data_types"]
|
|
path = src/drivers/cyphal/public_regulated_data_types
|
|
url = https://github.com/opencyphal/public_regulated_data_types.git
|
|
[submodule "src/drivers/cyphal/legacy_data_types"]
|
|
path = src/drivers/cyphal/legacy_data_types
|
|
url = https://github.com/PX4/public_regulated_data_types.git
|
|
branch = legacy
|
|
[submodule "src/lib/crypto/monocypher"]
|
|
path = src/lib/crypto/monocypher
|
|
url = https://github.com/PX4/Monocypher.git
|
|
branch = px4
|
|
[submodule "src/lib/events/libevents"]
|
|
path = src/lib/events/libevents
|
|
url = https://github.com/mavlink/libevents.git
|
|
branch = main
|
|
[submodule "src/lib/crypto/libtomcrypt"]
|
|
path = src/lib/crypto/libtomcrypt
|
|
url = https://github.com/PX4/libtomcrypt.git
|
|
branch = px4
|
|
[submodule "src/lib/crypto/libtommath"]
|
|
path = src/lib/crypto/libtommath
|
|
url = https://github.com/PX4/libtommath.git
|
|
branch = px4
|
|
[submodule "src/modules/uxrce_dds_client/Micro-XRCE-DDS-Client"]
|
|
path = src/modules/uxrce_dds_client/Micro-XRCE-DDS-Client
|
|
url = https://github.com/PX4/Micro-XRCE-DDS-Client.git
|
|
branch = px4
|
|
[submodule "src/lib/cdrstream/cyclonedds"]
|
|
path = src/lib/cdrstream/cyclonedds
|
|
url = https://github.com/px4/cyclonedds
|
|
[submodule "src/lib/cdrstream/rosidl"]
|
|
path = src/lib/cdrstream/rosidl
|
|
url = https://github.com/px4/rosidl
|
|
[submodule "src/modules/zenoh/zenoh-pico"]
|
|
path = src/modules/zenoh/zenoh-pico
|
|
url = https://github.com/px4/zenoh-pico
|
|
branch = dev/1.0.0-px4
|
|
[submodule "src/lib/heatshrink/heatshrink"]
|
|
path = src/lib/heatshrink/heatshrink
|
|
url = https://github.com/PX4/heatshrink.git
|
|
branch = px4
|
|
[submodule "src/modules/uxrce_dds_client/Micro-XRCE-DDS-Client-v3"]
|
|
path = src/modules/uxrce_dds_client/Micro-XRCE-DDS-Client-v3
|
|
url = https://github.com/PX4/Micro-XRCE-DDS-Client.git
|
|
branch = px4-release/3
|
|
[submodule "Tools/simulation/gz"]
|
|
path = Tools/simulation/gz
|
|
url = https://github.com/PX4/PX4-gazebo-models.git
|
|
branch = main
|
|
[submodule "boards/modalai/voxl2/libfc-sensor-api"]
|
|
path = boards/modalai/voxl2/libfc-sensor-api
|
|
url = https://gitlab.com/voxl-public/voxl-sdk/core-libs/libfc-sensor-api.git
|
|
[submodule "src/drivers/actuators/vertiq_io/iq-module-communication-cpp"]
|
|
path = src/drivers/actuators/vertiq_io/iq-module-communication-cpp
|
|
url = https://github.com/PX4/iq-module-communication-cpp.git
|
|
branch = master
|
|
[submodule "src/drivers/uavcan/libdronecan/dsdl"]
|
|
path = src/drivers/uavcan/libdronecan/dsdl
|
|
url = https://github.com/PX4/DSDL.git
|
|
[submodule "src/drivers/uavcan/libdronecan/libuavcan/dsdl_compiler/pydronecan"]
|
|
path = src/drivers/uavcan/libdronecan/libuavcan/dsdl_compiler/pydronecan
|
|
url = https://github.com/dronecan/pydronecan
|
|
[submodule "test/fuzztest"]
|
|
path = test/fuzztest
|
|
url = https://github.com/google/fuzztest.git
|
|
branch = main
|
|
[submodule "src/lib/tensorflow_lite_micro/tflite_micro"]
|
|
path = src/lib/tensorflow_lite_micro/tflite_micro
|
|
url = https://github.com/PX4/tflite-micro.git
|
|
branch = main
|
|
[submodule "src/drivers/ins/microstrain/mip_sdk"]
|
|
path = src/drivers/ins/microstrain/mip_sdk
|
|
url = https://github.com/PX4/LORD-MicroStrain_mip_sdk.git
|
|
[submodule "src/drivers/ins/sbgecom/sbgECom"]
|
|
path = src/drivers/ins/sbgecom/sbgECom
|
|
url = https://github.com/PX4/sbgECom.git
|
|
[submodule "src/modules/mc_raptor/blob"]
|
|
path = src/modules/mc_raptor/blob
|
|
url = https://github.com/rl-tools/px4-blob
|
|
[submodule "src/lib/rl_tools/rl_tools"]
|
|
path = src/lib/rl_tools/rl_tools
|
|
url = https://github.com/rl-tools/rl-tools.git
|
|
[submodule "libmodal-json"]
|
|
path = boards/modalai/voxl2/src/lib/mpa/libmodal-json
|
|
url = https://gitlab.com/voxl-public/voxl-sdk/core-libs/libmodal-json.git
|
|
[submodule "libmodal-pipe"]
|
|
path = boards/modalai/voxl2/src/lib/mpa/libmodal-pipe
|
|
url = https://gitlab.com/voxl-public/voxl-sdk/core-libs/libmodal-pipe.git
|
|
[submodule "src/modules/simulation/gz_plugins/optical_flow/PX4-OpticalFlow"]
|
|
path = src/modules/simulation/gz_plugins/optical_flow/PX4-OpticalFlow
|
|
url = https://github.com/PX4/PX4-OpticalFlow.git
|
|
[submodule "src/lib/ulog_cpp"]
|
|
path = src/lib/ulog_cpp
|
|
url = https://github.com/PX4/ulog_cpp.git
|