MAVLINKHUD

Companion Computer Failsafes

Executive Summary

When a Companion Computer (Raspberry Pi/Jetson) takes control of a drone, it becomes a single point of failure. If your Python script crashes or the USB cable vibrates loose, the drone must not fly away. ArduPilot provides a multi-layered "Deadman Switch" system to detect these failures and safely recover the vehicle.

Theory & Concepts

The most basic check is: "Is the computer still talking?"

  • Mechanism: The Companion Computer must send a HEARTBEAT message at least once every second.
  • Failure: If the heartbeat stops, ArduPilot assumes the link is broken. It triggers the GCS Failsafe.

2. The Command Stream (Logic Health)

Your computer might be alive (sending heartbeats) but your script might be frozen (not sending commands).

  • Mechanism: Guided Mode expects a constant stream of SET_POSITION_TARGET messages (e.g., 10Hz).
  • Failure: If the stream stops for GUIDED_TIMEOUT seconds, ArduPilot assumes the logic has crashed. It stops the drone instantly.

Architecture (The Engineer's View)

1. GCS Failsafe Logic

  • Monitor: GCS_MAVLINK::handle_heartbeat() updates last_heartbeat_time.
  • Trigger: Copter::failsafe_gcs_check() runs at 1Hz. If now - last_heartbeat > FS_GCS_TIMEOUT, it triggers.
  • Action: Depending on FS_GCS_ENABLE, it will:
    • 1: RTL.
    • 2: SmartRTL or RTL.
    • 3: SmartRTL or Land.
    • 4: Land.

2. Guided Mode Timeout

  • Monitor: ModeGuided tracks the timestamp of the last valid velocity/attitude command.
  • Action: If the timeout expires, the vehicle enters a "Brake" state (zero velocity target). It does not land or RTL; it just hovers, waiting for the computer to come back.

Key Parameters

Parameter Default Description
FS_GCS_ENABLE 1 0=Disabled, 1=RTL, 2=SmartRTL.
GUIDED_TIMEOUT 2.4 (seconds) Timeout for velocity/attitude stream.
SYSID_MYGCS 255 The System ID of the computer to track. If 0, it tracks the first GCS that talks to it.

Source Code Reference