System Failure Injection

System failure injection allows you to induce different types of sensor and system failures, either via MAVLink (using MAV_CMD_INJECT_FAILURE or via the MAVSDK failure plugin), or "manually" via a PX4 console like the MAVLink shell. This enables easier testing of safety failsafe behaviour, and more generally, of how PX4 behaves when systems and sensors stop working correctly.

Failure injection is disabled by default, and can be enabled using the SYS_FAILURE_EN parameter.

Failures can be injected both in simulation and on real hardware; this requires firmware built with the failure-injection module. The command always goes through the same firmware failure-injection module — whether it arrives over MAVLink or from the console, the accepted combinations are identical. What differs is whether a consumer applies the failure, and that depends on the environment.

Supported Failure Types

The table lists the failure types that actually take effect per environment: off, stuck, wrong (ok is not listed, but clears an active injection on all environments). A — means the module still accepts the command, but no consumer applies it in that environment.

Component	Gazebo (gz)	SIH	simulator_mavlink (Gazebo Classic/JMAVSim)	硬件
gyro	off, stuck	off, stuck	off, stuck	off, stuck
accel	off, stuck	off, stuck	off, stuck	off, stuck
mag	off, stuck	off, stuck	off, stuck	off, stuck
baro	off, stuck	off, stuck	off, stuck	off, stuck
distance_sensor	off, stuck	off, stuck	off, stuck	off, stuck
gps	—	off, stuck, wrong	off, stuck, wrong	off, stuck, wrong
airspeed	off, stuck, wrong	—	off, wrong	—
vio	—	—	off	—
battery	off, wrong	off, wrong	off, wrong	off, wrong
traffic	off	off	off	off
motor	off	off	off	off
esc	off, wrong	off, wrong	off, wrong	off, wrong

INFO

• gps off | stuck | wrong on Gazebo (Gz): only available if SIM_GZ_EN_GPS is set to 0 to use the injectable simulated-GPS module. By default Gazebo publishes GPS from the simulator's own GNSS sensor (SIM_GZ_EN_GPS = 1), which is not injectable.
• airspeed off | stuck | wrong on Gazebo (Gz): only injectable when airspeed is provided by the simulated-airspeed module (SENS_EN_ARSPDSIM); worlds that model an airspeed sensor directly are not injected.
• battery wrong reports the remaining charge just below the SYS_FAIL_BAT_LVL warning threshold to trigger the battery failsafe; off stops publishing the battery status entirely.
• traffic off suppresses incoming reports and marks the ADS-B/FLARM link unhealthy.
• motor off also requires CA_FAILURE_MODE.
• esc off reports the addressed ESC as offline and blanks its telemetry; esc wrong keeps it online but reports implausible telemetry (voltage and current at 10% of the real value, RPM 10x). ESCs are addressed by motor instance (the ESC's actuator function), so -i 1 targets the ESC driving motor 1.
• On hardware, ESC injection is applied only by the UAVCAN (DroneCAN) ESC driver; the other ESC drivers (DShot, Cyphal, VOXL, TAP ESC) publish their telemetry unmodified.

Sensors delivered through the shared driver layer (IMU, magnetometer, barometer, rangefinder via the PX4* sensor wrappers) support off/stuck in every environment that uses that layer — including the Gazebo and SIH sensor simulators, which feed synthesized measurements through the same wrappers. The remaining gaps are backend-specific: GPS and airspeed are handled by dedicated simulator code (see the GPS and airspeed notes in the info box above), SIH does not simulate an injectable airspeed. Components not listed (optical_flow, servo, avoidance, rc_signal, mavlink_signal) are rejected everywhere (MAV_RESULT_UNSUPPORTED); see the note below on NACK behaviour.

INFO

PX4 may accept a command to set a particular failure mode even it that mode is not supported by your simulator.

All MAV_CMD_INJECT_FAILURE commands are handled internally by the failure-injection module, which acknowledges each command and republishes the active failures for the sensor/actuator simulators to apply. The failure-injection module will NACK the command with MAV_RESULT_UNSUPPORTED for failure combinations that are not implemented by PX4 or any simulator. However it the module will accept (respond with MAV_MISSION_ACCEPTED) for any other failure-type, even if it is not supported by your particular simulator.

Failure System Command

Failures can be injected using the failure system command from any PX4 console/shell (such as the QGC MAVLink Console or SITL pxh shell), specifying both the target and type of the failure.

Syntax

The full syntax of the failure command is:

failure <component> <failure_type> [-i <instance_number>] [-m <instance_bitmask>]

where:

• component:
  • 传感器：
    • gyro: Gyroscope
    • accel: Accelerometer
    • mag: Magnetometer
    • baro: Barometer
    • gps: Global navigation satellite system
    • optical_flow: Optical flow.
    • vio: Visual inertial odometry
    • distance_sensor: Distance sensor (rangefinder).
    • airspeed: Airspeed sensor
  • Systems:
    • battery: Battery
    • motor: Motor
    • esc: ESC telemetry
    • servo: Servo
    • avoidance: Obstacle/collision avoidance system
    • traffic: Traffic avoidance (ADS-B/transponder)
    • rc_signal: RC Signal
    • mavlink_signal: MAVLink data telemetry connection
• failure_type:
  • ok: Publish as normal (Disable failure injection)
  • off: Stop publishing
  • stuck: Constantly report the same value which can happen on a malfunctioning sensor
  • garbage: Publish random noise. This looks like reading uninitialized memory
  • wrong: Publish invalid values that still look reasonable/aren't "garbage"
  • slow: Publish at a reduced rate
  • delayed: Publish valid data with a significant delay
  • intermittent: Publish intermittently
• instance number (optional): Instance number of affected sensor. 0 (default) indicates all sensors of specified type.
• instance bitmask (optional): address several instances at once (bit 0 = first instance, bit 1 = second, …; decimal or 0x hex). Used only when -i is omitted. Example: -m 0x5 targets instances 1 and 3.

INFO

GPS implements only the off, stuck, and wrong failure modes; the other failure types have no effect on it. gps wrong makes the addressed receiver report the fix type selected by SYS_FAIL_GPS_WRG and the jamming state selected by SYS_FAIL_GPS_JAM (Unchanged keeps the receiver's own state), and leaves the reported position untouched.

RC Switch Trigger

A failure can also be injected from an RC switch, without a console or telemetry link. This is useful for in-flight hardware testing. It is configured with the following parameters:

• SYS_FAIL_RC_SRC: the auxiliary RC input that triggers the failure — 0 disables it, 1–6 select AUX1–AUX6 (mapped via RC_MAP_AUXn).
• SYS_FAIL_RC_UNIT: the affected component (the FAILURE_UNIT value; e.g. 101 = motor).
• SYS_FAIL_RC_MODE: the failure type (the FAILURE_TYPE value; e.g. 1 = off).
• SYS_FAIL_RC_INST: the affected instances, as a bitmask (bit 0 = instance 1, e.g. 5 = instances 1 and 3; 0 = all instances).

While the selected aux switch is on the configured failure is injected; switching it back off clears the failure. The injection goes through the same path as the console/MAVLink commands, so for a motor it stops the motor exactly as failure motor off does (which also requires CA_FAILURE_MODE).

MAVSDK Failure Plugin

The MAVSDK failure plugin can be used to programmatically inject failures. It is used in PX4 Integration Testing to simulate failure cases (for example, see PX4-Autopilot/test/mavsdk_tests/autopilot_tester.cpp).

The plugin API is a direct mapping of the failure command shown above, with a few additional error signals related to the connection.

Example: GPS

To test the GPS failsafe by stopping GPS:

1. Enable the SYS_FAILURE_EN parameter.

2. Enter the following commands on the MAVLink console or SITL pxh shell:

   # Stop GPS publishing
   failure gps off
   
   # Restart GPS publishing
   failure gps ok

Example: Motor

To stop a motor mid-flight without the system anticipating it or excluding it from allocation effectiveness:

1. Enable the SYS_FAILURE_EN parameter.

2. Enable CA_FAILURE_MODE parameter to allow turning off motors.

3. Enter the following commands on the MAVLink console or SITL pxh shell:

   # Turn off first motor
   failure motor off -i 1
   
   # Turn it back on
   failure motor ok -i 1

Example: Battery

To trigger the battery failsafe by reporting a depleted pack:

1. Enable the SYS_FAILURE_EN parameter.

2. Optionally select the injected warning level with SYS_FAIL_BAT_LVL: Warn, Critical or Emergency. The reported remaining charge is set just below the matching threshold (BAT_LOW_THR, BAT_CRIT_THR or BAT_EMERGEN_THR).

3. Enter the following commands on the MAVLink console or SITL pxh shell:

   # Report the battery as depleted at the SYS_FAIL_BAT_LVL warning level -> battery failsafe
   failure battery wrong
   
   # Stop publishing the battery status entirely
   failure battery off
   
   # Stop injecting the failure
   failure battery ok