ROS 2 Humble workspace for the BRACU Duburi AUV 4.2. Controls the vehicle through a Pixhawk 2.4.8 running ArduSub via pymavlink. Perception via YOLO11 object detection with CUDA-accelerated inference, Kalman-filtered tracking, and PID-based visual servoing.

~40 Python source files · 8 packages · ~6 500 lines

1. Hardware
2. Packages & Codebase Structure
3. Build & Quick Start
4. Architecture
5. Configuration Profiles
6. Using the Duburi CLI (Runner)
7. Planning Missions Without the Runner
8. Logging
9. Vision & Perception
10. Simulation: Gazebo and ArduSub SITL
11. Topics & Messages
12. Inspector Parameters
13. Troubleshooting
14. Analysis & Documentation
15. Dependencies
16. License

The inspector (the core MAVLink bridge) is decomposed into focused modules:

mavlink_inspector/
├── inspector_node.py       (641 lines)  Thin orchestrator — timers, publishers, wiring
├── command_handler.py      (440 lines)  DriverCommand dispatch table → handlers
├── movement_commands.py    (399 lines)  MOVEMENTS registry — 30+ movement handlers
├── connection_manager.py   (246 lines)  Serial lifecycle, heartbeat, reconnect with backoff
├── rc_controller.py        (206 lines)  PWM math, channel constants, trapezoidal ramp
├── pid_controller.py       (162 lines)  Generic PID — deadband, anti-windup, EMA derivative
└── telemetry_parser.py     (159 lines)  MAVLink message dispatch → vehicle state

mavlink_driver/
├── driver_client.py        (262 lines)  make_command() factory + all movement functions
├── mission_parser.py       (245 lines)  parse_file_command() for mission files
├── mission_executor.py     (318 lines)  Autonomous mission runner node
├── just_commands.py        (115 lines)  just_* instant (no-ramp) movement variants
└── teleop_driver.py        (~70 lines)  Twist → TeleopCommand on /driver/teleop

mavlink_runner/
├── command_parser.py       (~280 lines) parse_command() — uses duburi_common.command_vocabulary
├── runner.py               (268 lines)  Interactive REPL node with readline
├── constants.py            (~50 lines)  HELP_TEXT, re-exports from duburi_common.constants
└── status_display.py        (75 lines)  ANSI dashboard (battery, heading, servos)

Full module map with every class, function, and import path: see analysis/12_CODE_REFERENCE.md

# ROS 2 Humble must be sourced
source /opt/ros/humble/setup.bash

# Python deps
pip install pymavlink ultralytics opencv-python

cd /home/duburi/workspaces/duburi_ws
colcon build            # builds all 8 packages (~5s clean)
source install/setup.bash

rm -rf build install log && colcon build
source install/setup.bash

# Terminal 1: Inspector (connects to Pixhawk) — start first, always
ros2 run mavlink_inspector inspector

# Terminal 2: Interactive CLI
ros2 run mavlink_runner runner

# Terminal 3 (optional): Logger
ros2 run mavlink_logger logger

# Terminal 1: Camera streaming (multi-camera manager)
ros2 run vision_inspector camera_manager

# Terminal 2: YOLO detection (GPU)
ros2 run vision detector_node --ros-args -p enable_display:=True

# Terminal 3 (optional): Visual servoing alignment
ros2 run vision alignment_controller

# Inspector + logger together
ros2 launch mavlink_inspector duburi_control.launch.py

# With custom config profile
ros2 launch mavlink_inspector duburi_control.launch.py \
    params_file:=$(ros2 pkg prefix mavlink_inspector)/share/mavlink_inspector/config/pool_test.yaml

# With individual overrides
ros2 launch mavlink_inspector duburi_control.launch.py \
    connection_port:=/dev/ttyACM1 enable_logger:=true

# Camera + detector together
ros2 launch vision vision.launch.py enable_display:=True confidence:=0.4

Software-in-the-loop stack used for autonomous testing without the pool: Gazebo Harmonic (gz sim 8) ↔ ArduPilot ArduSub JSON ↔ mavlink_inspector over UDP (same ROS 2 graph as hardware).

Deep dive (architecture, ports, GPU lab planning, optional simulators):
analysis/17_SIMULATION_GAZEBO_ARUDSUB_SITL.md

Verify versions:

source /opt/ros/humble/setup.bash
ros2 doctor --report | head -5
gz sim --version
dpkg -l | grep -E 'ros-humble-ros-gzharmonic|gz-sim8-cli' | head -5

sim_vehicle.py --out=udp:HOST:PORT sends MAVLink UDP datagrams to that address. The inspector must listen on UDP with the same host/port:

-p connection_port:=udpin:127.0.0.1:5760

Using tcp:127.0.0.1:5760 connects to TCP port 5760 (SITL’s primary MAVLink TCP listener). That is not the same socket as the UDP --out stream; you may see connect + sparse heartbeats then heartbeat loss. Always pair --out=udp:… with connection_port:=udpin:… (same host and port).

Run in separate terminals. Order matters: Gazebo first (JSON plugin), then SITL, then bridge, then Duburi.

1 — Gazebo (from a directory / env where the world resolves)

source /opt/ros/humble/setup.bash
gz sim -r bluerov2_underwater.world

-r runs the simulation (unpaused). Use gz sim, not legacy ign gazebo, so the generation matches Harmonic.

2 — ArduSub SITL + MAVProxy UDP output

From your ArduPilot tree (after . ~/.profile or equivalent so sim_vehicle.py is on PATH):

cd /path/to/ardupilot
sim_vehicle.py -v ArduSub -f vectored --model JSON \
  --out=udp:127.0.0.1:5760 --console

Adjust -f vectored / frame if your Gazebo model expects another SITL frame (some stacks use vectored_6dof). Keep --out port aligned with udpin below.

3 — ROS 2 ↔ Gazebo bridge (camera + clock example)

source /opt/ros/humble/setup.bash
ros2 run ros_gz_bridge parameter_bridge \
  /camera@sensor_msgs/msg/Image@gz.msgs.Image \
  /clock@rosgraph_msgs/msg/Clock@gz.msgs.Clock

Topic names must match your world’s sensor topics; adjust if your SDF uses different gz topic names.

4 — Duburi workspace + mavlink_inspector (UDP in)

cd /path/to/Duburi_ws
source /opt/ros/humble/setup.bash
source install/setup.bash
ros2 run mavlink_inspector inspector --ros-args \
  -p connection_port:=udpin:127.0.0.1:5760

5 — Optional: runner, logger, vision

ros2 run mavlink_runner runner
# ros2 run mavlink_logger logger
# vision stack as in [Quick Start — Perception](#quick-start--perception)

1. gz sim -r <world>
2. sim_vehicle.py … --model JSON --out=udp:127.0.0.1:<PORT> --console
3. ros2 run ros_gz_bridge parameter_bridge …
4. ros2 run mavlink_inspector inspector --ros-args -p connection_port:=udpin:127.0.0.1:<PORT>
5. Same <PORT> everywhere.

flowchart TB
    subgraph Hardware["Hardware Layer"]
        PIX[Pixhawk 2.4.8<br/>ArduSub Firmware]
        CAM[USB Camera]
        THR[T200 Thrusters]
    end
    
    subgraph Controls["Control Stack"]
        INS[mavlink_inspector<br/>7 modules]
        RUN[mavlink_runner<br/>Interactive CLI]
        EXE[mission_executor<br/>Autonomous missions]
        TEL[teleop_driver<br/>Joystick input]
        LOG[mavlink_logger]
    end
    
    subgraph Perception["Vision Stack"]
        CM[camera_manager<br/>Multi-camera]
        DET[detector_node<br/>YOLO11 + CUDA]
        ALN[alignment_controller<br/>Visual servo]
    end
    
    subgraph Shared["Shared"]
        INT[duburi_interfaces<br/>ROS2 messages]
        COM[duburi_common<br/>Constants + vocab]
    end
    
    PIX <-->|MAVLink| INS
    INS -->|RC Override| THR
    CAM --> CM
    CM -->|/camera/image| DET
    DET -->|/detections| ALN
    ALN -->|DriverCommand| INS
    RUN -->|DriverCommand| INS
    EXE -->|DriverCommand| INS
    TEL -->|TeleopCommand| INS
    INS -->|VehicleState| LOG

flowchart LR
    subgraph inspector_node["inspector_node.py (orchestrator)"]
        direction TB
    end
    
    CM[connection_manager<br/>Serial I/O, reconnect] --> inspector_node
    TP[telemetry_parser<br/>MAVLink → state] --> inspector_node
    CH[command_handler<br/>Dispatch table] --> inspector_node
    MC[movement_commands<br/>30+ handlers] --> CH
    RC[rc_controller<br/>PWM ramp] --> inspector_node
    PID[pid_controller ×2<br/>depth + yaw] --> inspector_node

1. Inspector connects to Pixhawk on /dev/ttyACM0, reads MAVLink at 50 Hz
2. TelemetryParser converts MAVLink messages → VehicleState (published 10 Hz)
3. Upstream nodes (runner, executor, teleop) publish DriverCommand to /driver/command
4. CommandHandler routes commands through dispatch tables to movement handlers
5. RcController applies trapezoidal velocity ramp at 20 Hz
6. PidController (depth + yaw) overrides channels when active
7. Inspector sends merged RC override to Pixhawk every 50ms

Three YAML config profiles live in src/mavlink_inspector/config/:

# Use a profile at launch
ros2 launch mavlink_inspector duburi_control.launch.py \
    params_file:=src/mavlink_inspector/config/pool_test.yaml

# Or with ros2 run
ros2 run mavlink_inspector inspector --ros-args \
    --params-file src/mavlink_inspector/config/pool_test.yaml

# Override individual params on top of a profile
ros2 run mavlink_inspector inspector --ros-args \
    --params-file src/mavlink_inspector/config/defaults.yaml \
    -p depth_kp:=600.0 -p depth_tolerance:=0.1

Copy defaults.yaml and modify as needed:

cp src/mavlink_inspector/config/defaults.yaml src/mavlink_inspector/config/my_pool.yaml
# Edit my_pool.yaml, then:
colcon build --packages-select mavlink_inspector
ros2 launch mavlink_inspector duburi_control.launch.py \
    params_file:=src/mavlink_inspector/config/my_pool.yaml

The runner provides an interactive prompt for direct control and file-based missions.

All old command names (dive, p_dive, yaw, p_yaw, p_turn) are kept as backward-compatible aliases.

ros2 run mavlink_runner runner

• Up/Down – Command history
• Left/Right – Cursor movement
• History stored in ~/.duburi_history

• Gain 0–100% (default 50%)
• Duration in seconds (Ns); omit for indefinite
• Order of gain/duration doesn't matter

Move in two horizontal directions at once. Speed is automatically scaled by $1/\sqrt{2} ≈ 71%$ per axis so the resultant velocity vector matches your requested speed — the AUV doesn't go faster diagonally.

Valid combinations: Any pair of {forward, back} × {left, right}. Conflicting directions (e.g. forward-back) are rejected.

Why only horizontal? Vertical movement (up/down) should use ~depth or depth for PID-controlled depth hold. Raw throttle without PID drifts and is unreliable in water.

Two depth control strategies are available. Use bare command for ArduSub firmware, ~ prefix for software PID:

• depth uses ArduSub’s built-in ALT_HOLD. Pixhawk’s firmware PID controls the throttle.
• ~depth is our software PID running at 20 Hz. Auto-switches to STABILIZE mode. Overrides CH_THROTTLE each tick. Uses derivative-on-measurement and conditional integration to prevent overshoot.
• Both depth modes can be combined with forward/lateral movement — they only control the vertical axis.
• Aliases: dive = depth, p_dive = ~depth

Use bare command for bang-bang (fast, snappy), ~ prefix for PID (smooth, precise):

• heading completes once the heading is within 5° of target.
• ~heading completes once within 3° (PID is smoother and more precise).
• Both are software-only — ArduSub doesn’t provide heading PID in MANUAL mode.
• Aliases: yaw = heading, p_yaw = ~heading

• Turns are computed from the current heading (requires telemetry from inspector).
• Aliases: p_turn = ~turn

The go command is the most powerful: it moves the AUV in a direction while simultaneously PID-yawing to a target heading. This is essential for competition tasks where you need to approach a gate at a specific angle.

go forward 90 60% 5s

1. Tick 0 (instantly): Inspector sets BOTH:
   • _current_movement → CH_FORWARD=1740 (60%) (only the channels the command owns)
   • _yaw_to_heading → PID targeting 90°
2. Every 50ms (20 Hz): The RC override layer builds one combined PWM message:
   • Layer 2: forward thrust from _current_movement (ramped toward target)
   • Layer 3: depth PID overrides CH_THROTTLE (if p_dive active)
   • Layer 4: yaw PID overrides CH_YAW with correction toward 90°
3. The AUV moves forward AND rotates toward 90° simultaneously from the first tick.
4. When heading 90° is reached (within 3°): yaw PID output goes to zero. Forward thrust continues.
5. After 5 seconds: movement expires. Ramp smoothly decelerates to neutral. AUV stops.

Key insight: go doesn't "first turn, then move." Translation and rotation happen in parallel from the very start.

go only controls horizontal translation + yaw. To also hold depth:

Duburi > p_dive 0.5; go forward 90 60% 10s

Can also be written with new names: Duburi > ~depth 0.5; go forward 90 60% 10s

This holds 0.5m depth (Layer 3) while moving forward toward 90° (Layers 2+4).

Move in an arbitrary direction relative to the AUV body using a bearing angle. The bearing is decomposed into forward + lateral channels using cos/sin.

Bearing reference: 0° = forward, 90° = right, 180° = backward, 270° = left.

Why use at instead of move forward-right? Diagonals use fixed √2 scaling at 45°. at lets you move at any arbitrary angle (e.g. 30°, 60°, 120°).

The cruise command combines body-frame vector movement, depth PID, and heading PID into a single coordinated manoeuvre. This is the most comprehensive command — the AUV moves in a direction, holds a heading, and maintains depth simultaneously.

• bearing — body-frame thrust direction (0° = forward)
• heading — target compass heading for yaw PID
• depth — target depth in meters for depth PID (0 = current depth)

All movement commands accept a just prefix that bypasses PWM ramping for instant thruster response. This is useful for emergency manoeuvres or when you need raw bang-bang control.

When to use just: Emergency stops/corrections, testing thruster response, or when ramp delay is unacceptable. For normal operation, ramped commands are preferred — they're gentler on thrusters and produce smoother motion.

Every 50ms, the inspector builds a single PWM message from 4 layers:

Layer 1: Neutral (1500) on all channels ─── baseline
Layer 2: Active movement (ramped) ─── sets only the channels the command owns
Layer 3: Depth PID ─── OVERRIDES CH_THROTTLE (if p_dive active)
Layer 4: Yaw PID ─── OVERRIDES CH_YAW (if go/p_yaw/yaw active)

Higher layers override lower ones. Movement commands (DESIGN 5) only set the channels they control:

• move forward → sets CH_FORWARD only
• move forward-right → sets CH_FORWARD + CH_LATERAL only
• move up → sets CH_THROTTLE only
• yaw left → sets CH_YAW only

PWM values are ramped (smooth acceleration) by default. just * variants bypass ramping for instant response.

Examples:

• move forward alone → Layer 2 sets forward thrust
• move forward + p_dive 0.5 → Layer 2 sets forward, Layer 3 overwrites throttle
• go forward 90 → Layer 2 sets forward, Layer 4 adds yaw PID
• go forward-right 45 + p_dive 0.3 → Layers 2+3+4 all active simultaneously

Arm/disarm print confirmation when events are received.

Execute multiple commands on one line (runner waits for duration before next):

Duburi > arm; move forward 50% 5s; move left 50% 2s; stop; disarm

Duburi > run <mission_name>
Duburi > run example_gate
Duburi > list missions

Mission file locations (in order):

1. ./missions/ (current directory)
2. mavlink_runner/missions/
3. ~/.duburi/missions/

Example mission file (missions/example_gate.txt):

# Example gate mission — approach gate at heading 90°
arm
mode MANUAL
sleep 2
~depth 0.5                    # hold 0.5m depth (software PID)
sleep 3
go forward 90 60% 8s          # move forward + PID yaw to 90°
sleep 9
forward-right 50% 3s          # diagonal adjustment
sleep 4
stop
surface
sleep 5
disarm

# Compound movement demo
arm
mode MANUAL
sleep 2
~depth 0.3                    # hold depth (PID)
sleep 3
go forward-right 45 50% 5s    # diagonal + heading 45°
sleep 6
go left 270 60% 3s            # strafe left at heading 270°
sleep 4
stop
disarm

• One command per line (or semicolon-separated on a line)
• # lines are comments
• sleep <seconds> / wait <seconds> — pause between commands
• pause — pause mission until Enter (runner) or external resume (executor)
• Runner waits for duration between commands
• Ctrl+C during mission executor aborts gracefully (sends stop, doesn't kill node)
• Second Ctrl+C forces exit

You can plan and run missions without using the interactive runner.

Predefined missions run as a ROS 2 node.

# Start inspector first
ros2 run mavlink_inspector inspector

# Run built-in pool test mission (after ~3s delay)
ros2 run mavlink_driver mission_executor

# With custom mission name (if supported by executor)
ros2 run mavlink_driver mission_executor --ros-args -p mission:=pool_test

The executor publishes DriverCommand messages to /driver/command with delays between steps.

Control the AUV by publishing DriverCommand to /driver/command.

# Arm
ros2 topic pub --once /driver/command duburi_interfaces/msg/DriverCommand "{command: 'arm'}"

# Move forward 50% for 5 seconds
ros2 topic pub --once /driver/command duburi_interfaces/msg/DriverCommand "{command: 'move_forward', duration: 5.0, speed: 50}"

# Diagonal: forward-right for 3 seconds
ros2 topic pub --once /driver/command duburi_interfaces/msg/DriverCommand "{command: 'move_forward_right', duration: 3.0, speed: 50}"

# Software PID depth hold at 0.5m
ros2 topic pub --once /driver/command duburi_interfaces/msg/DriverCommand "{command: 'pid_depth', depth: 0.5}"

# Go forward + PID yaw to 90°, 60% for 5s
ros2 topic pub --once /driver/command duburi_interfaces/msg/DriverCommand "{command: 'go_forward', angle: 90.0, duration: 5.0, speed: 60}"

# Go diagonal forward-right + PID yaw to 45°
ros2 topic pub --once /driver/command duburi_interfaces/msg/DriverCommand "{command: 'go_forward_right', angle: 45.0, duration: 5.0, speed: 50}"

# PID yaw to heading 260°
ros2 topic pub --once /driver/command duburi_interfaces/msg/DriverCommand "{command: 'pid_yaw_to_heading', angle: 260.0, speed: 50}"

# Stop
ros2 topic pub --once /driver/command duburi_interfaces/msg/DriverCommand "{command: 'stop'}"

# Disarm
ros2 topic pub --once /driver/command duburi_interfaces/msg/DriverCommand "{command: 'disarm'}"

Use mavlink_driver.driver_client to build your own mission node.

#!/usr/bin/env python3
import time
import rclpy
from rclpy.node import Node
from rclpy.qos import QoSProfile, ReliabilityPolicy
from duburi_interfaces.msg import DriverCommand
from mavlink_driver.driver_client import (
    arm, disarm, move_forward, move_left, move_combo,
    go_forward, go_combo, pid_depth, pid_depth_off,
    set_mode, stop, surface, set_depth,
    yaw_to_heading, pid_yaw,
    turn_left, pid_turn_left,
)

class MyMissionNode(Node):
    def __init__(self):
        super().__init__('my_mission')
        self._pub = self.create_publisher(
            DriverCommand, '/driver/command',
            QoSProfile(reliability=ReliabilityPolicy.RELIABLE, depth=10)
        )
        self._timer = self.create_timer(3.0, self._run_mission_once)

    def _publish(self, cmd, delay=0.5):
        self._pub.publish(cmd)
        if delay > 0:
            time.sleep(delay)

    def _run_mission_once(self):
        self._timer.cancel()
        self._publish(set_mode('MANUAL'))
        self._publish(arm(), delay=3.0)

        # Hold depth at 0.5m (software PID, works in MANUAL)
        self._publish(pid_depth(0.5), delay=3.0)

        # Move forward at 60% for 5s while PID-yawing to 90°
        self._publish(go_forward(angle=90, duration=5, speed=60))
        time.sleep(6)

        # Diagonal: forward-right at 50% for 3s
        self._publish(move_combo('forward-right', duration=3, speed=50))
        time.sleep(4)

        # Diagonal + heading: forward-left while yawing to 45°
        self._publish(go_combo('forward-left', angle=45, duration=4, speed=50))
        time.sleep(5)

        # Simple forward
        self._publish(move_forward(duration=3, speed=50))
        time.sleep(4)

        # Clean up
        self._publish(pid_depth_off())
        self._publish(stop())
        self._publish(surface(), delay=5.0)
        self._publish(disarm())

def main():
    rclpy.init()
    node = MyMissionNode()
    rclpy.spin(node)
    node.destroy_node()
    rclpy.shutdown()

if __name__ == '__main__':
    main()

Use missions/*.txt files as mission descriptions even when not using the runner:

1. With Runner: run example_gate
2. Without Runner: Replicate the sequence in mission_executor or your custom node
3. Scripting: Parse the file and publish DriverCommand via a small script

Use teleop_driver to drive the AUV with Twist messages (e.g., from a joystick or nav stack). The driver converts Twist to a dedicated TeleopCommand message on /driver/teleop, with clean axis semantics (linear_x/y/z, angular_z). When the joystick returns to centre, idle=true clears movement without disrupting active depth PID or heading hold.

ros2 run mavlink_driver teleop_driver
# Publish to /cmd_vel (geometry_msgs/Twist)
# Single axis:
ros2 topic pub /cmd_vel geometry_msgs/msg/Twist "{linear: {x: 0.5, y: 0.0, z: 0.0}, angular: {x: 0.0, y: 0.0, z: 0.0}}"
# Multi-axis (forward + right + up + yaw simultaneously):
ros2 topic pub /cmd_vel geometry_msgs/msg/Twist "{linear: {x: 0.5, y: 0.5, z: 0.3}, angular: {x: 0.0, y: 0.0, z: 0.3}}"

The inspector subscribes to /driver/teleop and applies RC overrides directly from TeleopCommand fields — no field overloading needed.

The logger creates session folders with rotating log files inside the workspace:

logs/
└── 2026-03-06_14-30-00/     # session timestamp
    ├── session.log           # all events + commands (RotatingFileHandler, 5 MB max, 3 backups)
    ├── events.log            # MAVLink events only
    ├── commands.log          # DriverCommand only
    └── state.csv             # throttled telemetry (1 Hz default)

# Start logger with defaults (logs/ in workspace root)
ros2 run mavlink_logger logger

# Custom log directory
ros2 run mavlink_logger logger --ros-args -p log_directory:=/path/to/logs

# Adjust rotation (10 MB max, 5 backups)
ros2 run mavlink_logger logger --ros-args -p max_log_bytes:=10485760 -p backup_count:=5

# Throttle state logging to 0.5 Hz
ros2 run mavlink_logger logger --ros-args -p state_log_interval:=2.0

The runner automatically monitors the inspector connection. If no VehicleState messages arrive for 5+ seconds, a yellow warning appears:

⚠ No telemetry for 8s — is mavlink_inspector running?

The warning auto-clears when messages resume. Also visible in the status dashboard as "Telemetry stale."

The perception stack handles camera input and object detection, publishing results as ROS 2 topics for downstream use.

# Standalone test (camera + YOLO, no ROS pipeline needed)
ros2 run vision detector_standalone --ros-args -p device_id:=0

# Full ROS pipeline
# Terminal 1: Camera streaming
ros2 run vision_inspector camera_node --ros-args -p device_id:=0

# Terminal 2: YOLO detection (GPU by default)
ros2 run vision detector_node --ros-args -p enable_display:=True

# Terminal 3: See detections
ros2 topic echo /vision/detections

camera_manager parameters:

# Enumerate cameras
ros2 run vision_inspector camera_enum

# Test a specific camera
ros2 run vision_inspector camera_test --ros-args -p device_id:=1

# Calibrate (9x6 checkerboard, 2.5cm squares)
ros2 run vision_inspector camera_calibrate --ros-args \
    -p board_width:=9 -p board_height:=6 -p square_size:=0.025

# Launch camera node with calibration
ros2 launch vision_inspector camera.launch.py \
    device_id:=0 calibration_file:=calibration/calibration_video0_20260306.yaml

detector_node parameters:

# Basic detection (GPU, prints to terminal)
ros2 run vision detector_node

# With display and custom model
ros2 run vision detector_node --ros-args \
    -p enable_display:=True -p model:=yolov8s.pt -p confidence:=0.3

# Filter specific classes (e.g. only persons and cars)
ros2 run vision detector_node --ros-args -p classes:="0,2"

# Force CPU mode
ros2 run vision detector_node --ros-args -p device:=cpu

# Via launch file
ros2 launch vision vision.launch.py enable_display:=True confidence:=0.4

The alignment_controller subscribes to /vision/detections and /mavlink/vehicle_state, runs PID loops (lateral, vertical, forward) to center the AUV on a detected target, and publishes DriverCommand to /driver/command. Uses simple-pid library with Kalman-filtered measurements.

Activation: Send alignment commands via runner or DriverCommand:

• lat_align / dep_align / align / align_forward — proportional fallback
• pid_lat_align / pid_dep_align / pid_align / pid_align_forward — PID-controlled
• vision_stop — stop alignment

Detection.msg – single detection:

DetectionArray.msg – per frame:

 USB Camera(s) ──► camera_manager ──► detector_node ──► /vision/detections
 /dev/videoN       (multi-cam)        (YOLO11 GPU)       (DetectionArray)
                       │                   │                    │
              /camera/<name>/image_raw   /vision/annotated   alignment_controller
              (sensor_msgs/Image)        (annotated frames)  (PID visual servo)
                                                                    │
                                                           /driver/command
                                                           (DriverCommand)

Normalized center coordinates (center_x, center_y) are designed for easy future MAVLink integration:

  center_x < 0.4 → target is left  → yaw_left
  center_x > 0.6 → target is right → yaw_right
  0.4–0.6        → centered        → move_forward

DriverCommand fields:

Command reference:

The inspector node accepts the following ROS parameters for tuning. All defaults are defined in src/mavlink_inspector/config/defaults.yaml — see Configuration Profiles for how to switch between pre-built profiles.

# Override parameters at launch
ros2 run mavlink_inspector inspector --ros-args \
  -p connection_port:=/dev/ttyACM1 \
  -p yaw_source:=attitude \
  -p depth_kp:=300.0 \
  -p depth_ki:=15.0

• Derivative on measurement — both depth and yaw PIDs use derivative-on-measurement (not derivative-on-error) to avoid PWM spikes when setpoint changes. Depth uses (depth - prev_depth)/dt, yaw uses the gyro-measured heading rate from ATTITUDE messages.
• Conditional integration — integral accumulation pauses when PID output is saturated (|output| ≥ 400 PWM), preventing windup during large transients.
• Yaw speed scaling — the speed parameter on pid_yaw_to_heading now clamps max PID output (lower speed = gentler corrections).

# Check if inspector is publishing
ros2 topic hz /mavlink/vehicle_state

# See current vehicle state
ros2 topic echo /mavlink/vehicle_state --once

# Check all active topics
ros2 topic list

# Check node health
ros2 node list
ros2 node info /mavlink_inspector

# Verify serial port
ls -la /dev/ttyACM*
dmesg | tail -20   # check USB connect/disconnect

The analysis/ folder contains detailed technical documents:

• ROS 2 Humble on Ubuntu 22.04
• pymavlink: pip install pymavlink or sudo apt install python3-pymavlink
• PyYAML: included with ROS 2 (used for config loading)

• Gazebo Harmonic (gz-harmonic, gz-sim8-cli) and ros-humble-ros-gzharmonic-bridge
• ArduPilot (SITL + sim_vehicle.py) and a Gazebo JSON BlueROV world (e.g. ardupilot_gazebo)

• OpenCV: pip install opencv-python or sudo apt install python3-opencv
• Ultralytics YOLO: pip install ultralytics
• Supervision: pip install supervision (annotation library)
• simple-pid: pip install simple-pid (visual servo PID controllers)
• PyTorch with CUDA 12.8: Required for GPU inference (auto-detected by ultralytics)
• v4l-utils (optional): sudo apt install v4l-utils — for camera_enum detailed device info

# Controls
pip install pymavlink

# Perception (GPU)
pip install opencv-python ultralytics supervision simple-pid
# Verify CUDA
python3 -c "import torch; print(f'CUDA: {torch.cuda.is_available()}, Device: {torch.cuda.get_device_name(0)}')"

Branch: Control-Redesign-V2 (testing)

V2 adds advanced control features for mission reliability:

graph LR
    subgraph "V2 Features"
        A[Convergence Gates] --> B[Wait for vehicle<br/>to stabilize]
        C[Rotate-in-Place] --> D[Sharp turns<br/>no drift]
        E[Cascade Control] --> F[Position→Velocity<br/>→Thrust]
        G[Gain Scheduling] --> H[Speed-adaptive<br/>PID gains]
        I[Multi-Source Sensors] --> J[DVL, External<br/>compass fallback]
    end

New Modules:

• velocity_control.py — VelocityEstimator, ConvergenceGate, CascadeController, GainScheduler
• sensor_sources.py — DVLSource, ExternalYawSource, SensorSourceManager

74+ configurable parameters — all features disabled by default for safety.

See analysis/design-decisions/control-stack-v2.md for full documentation.

Apache-2.0