Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Ardupilot/ardupilot/llms.txt

Use this file to discover all available pages before exploring further.

ArduSub is the ArduPilot firmware for underwater vehicles. It targets remotely operated vehicles (ROVs) operated by a topside joystick, as well as autonomous underwater vehicles (AUVs) executing pre-planned missions. The vehicle code lives in ArduSub/ and compiles to the ardusub binary. ArduSub shares the same core library stack as every other ArduPilot vehicle while adding subsystems specific to underwater operation: leak detection, depth pressure sensing, and thruster mixing for vectored-thrust frames.

Flight modes

11 modes from manual pass-through to fully autonomous waypoint navigation and depth tracking.

Depth hold

AltHold and SurfTrak modes maintain a constant depth or constant distance above the seafloor.

Leak detection

The AP_LeakDetector library monitors leak sensors and triggers configurable failsafe responses.

Joystick control

joystick.cpp maps a six-degrees-of-freedom joystick to thruster outputs for manual ROV piloting.

​
Supported vehicle types

ArduSub supports multiple underwater vehicle configurations selected through the FRAME_CONFIG parameter.
Vehicle typeDescription
BlueROV2 (Heavy)8-thruster vectored frame, the reference platform for ArduSub development
BlueROV2 (Standard)6-thruster frame with 4 horizontal and 2 vertical thrusters
Vectored 6DOFGeneric 6-degree-of-freedom thruster layout
SimpleROV3-thruster basic frame for entry-level builds
CustomConfigurable thruster count and orientation via MOT_ parameters
ArduSub supports the Blue Robotics Navigator board — a Raspberry Pi HAT with IMU, barometer, and PWM outputs — as a low-cost Linux-based autopilot. Build with ./waf configure --board navigator when targeting this hardware.

​
Flight modes

All modes are defined in ArduSub/mode.h. Mode numbers match the values reported to ground stations over MAVLink.
#ModeGPS requiredDescription
0StabilizeNoAttitude-stabilized with manual depth control
1AcroNoBody-frame angular rate control, manual throttle
2AltHoldNoAttitude-stabilized with automatic depth hold
3AutoYesFully automatic waypoint mission
4GuidedYesNavigate to GCS-commanded positions
7CircleYesAutomatic circular orbit at constant depth
9SurfaceNoAutomatically ascend to the surface; pilot keeps horizontal control
16PosHoldYesAutomatic 3D position hold with manual override
19ManualNoDirect pass-through to thrusters, no stabilization
20MotorDetectNoAutomated motor orientation and direction detection
21SurfTrakNoHold a constant distance above the seafloor using a downward rangefinder

​
Key features

SurfTrak mode

Tracks a configurable range above the seafloor using a downward-facing rangefinder or USBL, ideal for bottom surveys.

Leak detection

AP_LeakDetector polls one or more leak sensors and can trigger emergency surface ascent.

6-DOF thruster mixing

The motor mixing system supports fully vectored frames with independent surge, sway, heave, roll, pitch, and yaw axes.

Joystick input

joystick.cpp decodes MAVLink MANUAL_CONTROL messages so a gamepad or joystick controls the ROV directly.

Script buttons

script_button.cpp maps button inputs to Lua script triggers, enabling custom topside panel controls.

Underwater positioning

ArduSub accepts external position updates from USBL, LBL, or DVL systems via MAVLink VISION_POSITION_ESTIMATE.

​
Depth and altitude control

ArduSub uses barometric pressure from a water-rated depth sensor (e.g., Blue Robotics Bar30) for depth estimation. The sensor is read through the standard AP_Baro library, which reports depth when the vehicle is detected as underwater.
Holds a constant depth using the barometric depth reading. The pilot controls roll, pitch, and yaw while the autopilot manages the vertical thrusters to maintain depth. Depth setpoint is updated by the pilot’s vertical joystick input.

​
Building

1

Configure the build system

# SITL simulation
./waf configure --board sitl

# Blue Robotics Navigator board (Raspberry Pi HAT)
./waf configure --board navigator

# Standard Pixhawk-family board
./waf configure --board CubeOrange
2

Build ArduSub

./waf sub
Output binary: build/<board>/bin/ardusub

​
Libraries linked by wscript

The ArduSub/wscript file lists the vehicle-specific libraries added on top of the common set.
LibraryPurpose
AC_AttitudeControlRoll, pitch, yaw, and depth attitude controllers
AC_WPNavWaypoint, loiter, and circle navigation
AP_CameraCamera trigger control
AP_InertialNavInertial navigation blending for position hold
AP_JSButtonJoystick button mapping to vehicle actions
AP_LeakDetectorLeak sensor polling and failsafe triggering
AP_MotorsThruster output mixing and PWM generation
AP_TemperatureSensorOnboard temperature monitoring

​
Testing in simulation

# Build and run the full ArduSub test suite
Tools/autotest/autotest.py build.Sub test.Sub

# Run a specific test
Tools/autotest/autotest.py build.Sub test.Sub.DiveManual
SITL simulation for ArduSub uses a simplified hydrodynamics model. Thruster thrust curves, buoyancy, and drag are approximated. Always verify depth controller tuning on the actual vehicle in a controlled tank before open-water deployment.
See the SITL guide for how to run simulated underwater missions and how to connect QGroundControl or the Blue Robotics companion app to the SITL instance.

Build docs developers (and LLMs) love

Get started for freeTalk to us