Software Packages and Libraries

This page covers ROS packages and software libraries for maritime robotics control, localization, perception, communication, and utilities.

Thrust Allocation and Control

Thrust allocation is a critical component for marine vehicles with multiple thrusters. These modules determine how to distribute control forces across actuators to achieve desired vehicle motion.

Theory

Thrust allocation solves the problem: given a desired force/torque $\tau$ on the vehicle, determine actuator commands (forces $f$ or utilizations $u$) that best satisfy:

$$ \tau = T(\alpha)f(u) $$

Where $T$ is the thrust allocation matrix and $\alpha$ represents actuator orientations.

Packages

Package Method ROS Version Last Update
MVP-Control Quadratic Programming ROS/ROS 2 11/2025
thruster_manager (CNR) Pseudo-inverse ROS 04/2025
thruster_allocation_matrix_controller Pseudo-inverse ROS 2 07/2025

Table last updated on December 31th, 2025 at 05:26:07 PM UTC

MVP-Control

Implements control allocation using quadratic programming (QP) optimization.

Features: - Handles thruster saturation - Accounts for thruster dead zones - Supports azimuth thrusters - ROS and ROS 2 compatible

CentraleNantes Thruster Manager

Uses URDF to extract thruster configuration and computes the pseudo-inverse of the thrust allocation matrix.

Features: - URDF-based configuration - Simple inverse method: $f = T^{-1} \tau$ - Well-documented - ROS 1

Robotic Decision Making Lab Controllers

Modern ROS 2 controller using predefined inverse of thrust allocation matrix.

Features: - ROS 2 native - Integration with ros2_control - Clean architecture

Known Issues: Thrust Allocation

⚠️ Pseudo-inverse methods (thruster_manager, thruster_allocation_matrix_controller):

  1. No Saturation Handling
  2. Issue: Commanded forces can exceed thruster limits
  3. Symptom: Some thrusters saturate while others underutilized
  4. Impact: Poor control performance, vehicle instability

  5. Solution: Use QP-based allocator (MVP-Control) or implement soft limits

  6. Singular Configurations

  7. Issue: Matrix becomes singular when thrusters are aligned
  8. Symptom: Division by zero, NaN outputs
  9. Impact: Control failure

  10. Solution: Check allocation matrix condition number, reposition thrusters

  11. Dead Zone Ignored

  12. Issue: Many thrusters have dead zones at low thrust
  13. Symptom: Small commanded thrusts produce zero output
  14. Impact: Poor low-speed control, limit cycles
  15. Solution: Use allocator with dead zone compensation (MVP-Control)

⚠️ QP-based methods (MVP-Control):

  1. Computational Cost
  2. Issue: Solve time can spike under heavy constraints
  3. Symptom: Control loop jitter, occasional delays
  4. Impact: Reduced control bandwidth

  5. Solution: Monitor solve time, use a faster QP solver (e.g., OSQP), reduce control rate if needed

  6. Configuration Complexity

  7. Issue: More parameters to tune (weights, constraints)
  8. Symptom: Unexpected allocation behavior
  9. Impact: Time to tune system
  10. Solution: Start with default weights, tune incrementally

Decision Guide: - Use pseudo-inverse if: Square allocation matrix, known unsaturated operation, and you need very low solver latency - Use QP if: Non-square matrix, saturation inevitable (real vehicles), need optimal allocation

Motion Control

Dynamic Positioning (DP) / Station Keeping

Systems for maintaining position and heading, commonly used for: - ROV operations - Survey missions - Intervention tasks

Approaches: - PID control with feed-forward - Model Predictive Control (MPC) - Sliding mode control

Path Following and Guidance

Algorithms for following desired trajectories:

Line-of-Sight (LOS): - Classic marine control approach - Handles cross-track error - Works well with currents

Path Following: - Carrot-following - Pure pursuit - Vector field methods

Packages: * MVP-Mission: Behavior-based mission planner with guidance behaviors

Low-Level Controllers

Integration with ROS 2 control framework:

  • ros2_control: Standard ROS 2 controller framework
  • Hardware abstraction
  • Controller lifecycle management
  • Standard interfaces

Localization

Localization is challenging in maritime environments due to lack of GPS underwater and environmental factors.

DVL-Based Navigation

Doppler Velocity Log integration for dead-reckoning:

Approaches: - DVL + IMU fusion (Extended Kalman Filter) - DVL bottom-track for position updates - Water-track for mid-water navigation

Acoustic Positioning

USBL/LBL Integration: - Acoustic position fixes - Outlier rejection - Integration with INS

Sensor Fusion

Multi-sensor integration for robust localization:

Common Sensor Combinations: - DVL + IMU + Depth: Standard AUV setup - GPS + IMU + Compass: Surface vehicle navigation - USBL + DVL + IMU: High-accuracy underwater positioning

Packages: * Mesh Navigation: Mesh-based localization and navigation * robot_localization: EKF and UKF implementations for sensor fusion

Known Issues: Localization

⚠️ DVL Integration:

  1. Bottom-Lock Failures
  2. Issue: Bottom lock can fail at higher altitudes or over soft sediment
  3. Symptoms: DVL reports invalid velocity or switches to water-track
  4. Impact: Position estimate degrades to IMU-only dead-reckoning (poor)

  5. Solutions:

    • Operate within bottom-lock range when possible
    • Reduce altitude for critical maneuvers
    • Surface for GPS fix if bottom-lock lost

  6. Acoustic Interference

  7. Issue: DVL interferes with sonar, acoustic modems
  8. Symptoms: Corrupted sonar images, modem packet loss
  9. Impact: Can't use DVL + sonar simultaneously

  10. Solutions:

    • Stagger ping timing (DVL then sonar)
    • Use different frequencies if possible
    • Time-multiplex: DVL during transit, sonar during survey stops

  11. Thruster Cavitation Noise

  12. Issue: Thruster bubbles mask DVL acoustic returns
  13. Symptoms: Erratic velocity readings during high thrust
  14. Impact: Poor navigation during aggressive maneuvers

  15. Solutions:

    • Mount DVL away from thrusters
    • Use vibration damping mounts
    • Reduce thruster noise via PWM frequency tuning

  16. Water-Track Inaccuracy

  17. Issue: Water-track assumes no current (rarely true)
  18. Symptoms: Position drift when using water-track
  19. Impact: Significant velocity error in currents
  20. Solution: Avoid water-track mode; surface for GPS fix instead

⚠️ Sensor Fusion (robot_localization):

  1. EKF Divergence
  2. Root Causes:
    • Sensor timestamp mismatch (using wall time instead of ROS time)
    • Incorrect covariances (too confident in bad sensor)
    • Bad initial state
    • TF tree broken or missing transforms
  3. Symptoms:
    • Position estimate jumps
    • High innovation values
    • Covariance growing unbounded

  4. Debug: ```bash # Check TF tree ros2 run tf2_tools view_frames

    # Monitor EKF diagnostics ros2 topic echo /diagnostics

    # Verify sensor timestamps ros2 topic echo /dvl/velocity --field header.stamp ros2 topic echo /imu/data --field header.stamp `` - **Solutions:** - Ensure all sensors usenode.get_clock().now()nottime.time()` - Reduce sensor covariance (increase uncertainty) - Increase process noise - Reset EKF and reinitialize - Disable faulty sensor temporarily

  5. Discontinuous Measurements (GPS, USBL)

  6. Issue: GPS only available at surface; USBL updates are intermittent
  7. Symptoms: Position jumps when measurement arrives
  8. Impact: Control instability if not handled properly

  9. Solutions:

    • Use pose1_relative: false for absolute measurements
    • Tune covariance higher for USBL (reflects uncertainty)
    • Enable outlier rejection for USBL
    • Consider separate EKF for global vs local frame

  10. Covariance Tuning Difficulty

  11. Issue: Process noise and sensor covariances non-intuitive
  12. Symptoms: EKF trusts wrong sensor, or diverges
  13. Impact: Weeks of tuning time
  14. Approach:
    1. Start with manufacturer sensor covariances
    2. Set process noise conservatively high
    3. Tune one sensor at a time
    4. Monitor innovation (should be zero-mean)
    5. Use rqt_multiplot to visualize

⚠️ Acoustic Positioning (USBL):

  1. Outlier Measurements
  2. Issue: Multipath, biologics cause bad USBL fixes
  3. Symptoms: Large position jumps
  4. Impact: EKF divergence if outlier accepted

  5. Solutions:

    • Enable Mahalanobis distance outlier rejection in EKF
    • Pre-filter USBL with median filter
    • Use appropriately conservative covariance for USBL

  6. Shadow Zones

  7. Issue: Thermoclines bend sound, create shadow zones
  8. Symptoms: No USBL fixes in certain locations
  9. Impact: Fall back to DVL+IMU-only navigation (drift)
  10. Solutions:
    • Plan missions to avoid known thermoclines
    • Use LBL instead of USBL for critical areas
    • Monitor USBL signal strength

Decision Guide: - Pure Underwater (no surface): DVL + IMU + Depth is standard; add USBL for long-range missions - Shallow Water: Can surface frequently for GPS, DVL less critical - Survey Missions: USBL or LBL essential for georeferenced data - ROV (Tethered): IMU + Depth sufficient, topside provides position

Perception

Processing sensor data to understand the environment.

Sonar Processing

Point Cloud Generation: - Convert sonar data to 3D point clouds - Registration and mapping - Object detection

Imaging Sonar: - Feature extraction - Target classification - SLAM with imaging sonar

Underwater Vision

Challenges: - Color correction - Enhancement in turbid water - Lighting compensation

Approaches: - Deep learning for object detection - Stereo vision for 3D reconstruction - Visual odometry (in clear water)

Object Detection

Maritime-Specific Targets: - Buoys and markers - Pipelines and cables - Marine structures (wrecks, platforms) - Docking stations

Communication

Acoustic Communication

Underwater acoustic communication is essential for commanding and monitoring submerged vehicles.

WHOI ros_acomms ⭐

ros_acomms | Documentation

Woods Hole Oceanographic Institution's ROS-based acoustic communication stack. See the project documentation for deployment history and supported configurations.

Core Features: - Transport ROS messages over underwater acoustic links - Efficient message marshalling (manual configuration or automatic introspection) - Modular modem driver architecture - Message queue management for link optimization - Media Access Control (MAC) engines - Acoustic link simulator with ray-tracing model for development

Supported Hardware: - WHOI Micro-Modem family (primary target) - Iridium satellite links (low-throughput mode) - Extensible to other acoustic modems via modular driver interface

Real-World Applications: - Remote redirection of deployed AUVs - Near real-time vehicle telemetry streaming - Sensor data transmission from underwater vehicles - Multi-vehicle coordination and swarm operations

Performance: - Acoustic throughput and latency vary widely by modem, configuration, and environment - Range depends on modem specs and environmental conditions

ROS Version: ROS 1 (ROS 2 migration status unknown)

Publications: - E. Gallimore, T. Schneider, H. Schmidt, "ROS Message Transport over Underwater Acoustic Links with ros_acomms," IEEE/OES AUV 2022

Why Use It: ros_acomms provides an end-to-end acoustic communications stack for ROS; see the documentation for feature and configuration details.

Known Issues: Acoustic Communication

⚠️ ros_acomms Limitations:

  1. Low Bandwidth Constraints
  2. Limitation: Acoustic links have much lower throughput than RF
  3. Impact: Can't stream video, send large files, or do real-time control
  4. Suitable for:
    • Status updates (position, battery, mission state)
    • Waypoint updates
    • Emergency commands (abort, surface)
    • Sparse sensor data (temperature, depth readings)

  5. NOT suitable for:

    • Camera feeds
    • Real-time teleoperation
    • Large map transfers
    • High-rate control loops

  6. High Latency

  7. Typical: Seconds of one-way latency
  8. Impact: Round-trip command-response can be slow
  9. Implications:
    • Vehicle must operate autonomously between commands
    • Can't rely on acoustic link for critical safety functions
    • Mission updates must account for propagation delay

  10. Solutions:

    • Design missions for autonomous execution
    • Use acoustic only for monitoring and high-level redirection
    • Implement time-stamped commands

  11. Packet Loss and Dropouts

  12. Causes:
    • Multipath (shallow water, near structures)
    • Thermoclines bending sound
    • Biologics (snapping shrimp interference)
    • Surface conditions (bubbles from waves)
    • Vehicle orientation (directionality of transducers)
  13. Typical: Packet loss can be significant in challenging conditions

  14. Solutions:

    • Implement retry logic and acknowledgments
    • Use redundant critical messages
    • Accept that some messages will be lost
    • Queue important messages with ros_acomms queue manager

  15. Environmental Sensitivity

  16. Issue: Performance varies drastically with conditions
  17. Factors:
    • Water temperature (affects sound speed)
    • Salinity (affects absorption)
    • Depth (pressure effects)
    • Sea state (surface noise)
    • Time of day (biologics, shipping traffic)
  18. Impact: Range can vary widely between good and bad conditions

  19. Solutions:

    • Test in actual deployment environment
    • Have a fallback plan if acoustic fails
    • Don't rely solely on acoustic for critical functions

  20. Range Limitations

  21. Typical Ranges: Range depends on modem specs, water conditions, and installation
  22. Trade-off: Range vs bandwidth (longer range = slower rate)

  23. Solutions:

    • Size modem and data rate to mission requirements
    • Plan vehicle operations within reliable acoustic range
    • Use surface relays for longer-range missions

  24. ROS 1 Only

  25. Issue: ros_acomms not yet ported to ROS 2
  26. Impact: Must bridge ROS 2 system to ROS 1 for acoustic comms
  27. Workarounds:
    • Use ROS 1 ↔ ROS 2 bridge
    • Implement custom ROS 2 acoustic driver (significant effort)
    • Run acoustic comms in separate ROS 1 container

⚠️ General Acoustic Communication Challenges:

  1. Hardware Availability
  2. Issue: Few affordable acoustic modems available
  3. Options:
    • WHOI Micro-Modem
    • EvoLogics
    • Teledyne Benthos
    • Budget options are limited

  4. Impact: Acoustic capability can add significant cost

  5. Integration Complexity

  6. Issue: Acoustic modems typically use serial or Ethernet
  7. Requirements:
    • Waterproof connectors
    • Power supply (varies by modem)
    • Transducer mounting and cabling
    • Topside modem (need two modems for communication)

  8. Time: Budget sufficient time for integration and field testing

  9. Testing Challenges

  10. Issue: Can't test acoustic in air (need water)
  11. Requirements:
    • Water tank or pool for testing
    • Lake/ocean for realistic range tests
    • Separate topside modem and power
  12. Cost: Field testing is expensive and time-consuming

Decision Guide: - Need acoustic if: Operating far from the surface, multi-hour missions, need status monitoring - Skip acoustic if: Tethered ROV, shallow water with frequent surfacing, budget-constrained - Alternative for budget projects: Pre-programmed autonomous missions, surface for communication - Critical insight: Most successful AUV missions are fully autonomous with acoustic as monitoring only

ns-3 UAN (Simulation Only)

ns-3 UAN - Underwater Acoustic Network simulation module.

Purpose: Research and development, protocol testing Status: Simulation framework (not for production deployment) Use Cases: Protocol development, network performance analysis, academic research

Characteristics of Underwater Acoustic Communication: - Low bandwidth compared to RF links - High latency (seconds) - Range depends on environment and modem specifications - Affected by water conditions (temperature, salinity, pressure) - Multipath propagation - Doppler effects from vehicle motion

Network Protocols

Handling underwater network challenges: - Delay-tolerant networking (DTN) - Acoustic channel modeling and prediction - Multi-hop communication - Time synchronization - Collision avoidance (TDMA, CDMA)

Mapping and SLAM

Underwater SLAM

Simultaneous Localization and Mapping in underwater environments:

Sensor Choices: - Sonar-based SLAM (most common) - Visual SLAM (clear water only) - DVL-aided SLAM

Challenges: - Feature-sparse environments - Dynamic water conditions - Computational constraints

Seafloor Mapping

Creating maps of the underwater environment: - Bathymetric mapping (depth maps) - Photomosaics - 3D reconstruction

Tools and Utilities

Geographic Conversions

Coordinate system transformations for marine robotics:

Common Conversions: - Lat/Lon ↔ UTM - Geodetic ↔ Cartesian - Local ENU (East-North-Up) frames

Libraries: - GeographicLib - proj4 - ROS tf2 for transformations

Visualization

RViz Plugins: - Sonar visualization - Bathymetric data display - Vehicle trajectory playback - Acoustic range visualization

Web-Based: - GIS integration - Mission planning interfaces - Real-time telemetry dashboards

Data Processing

Post-mission data analysis: - Bag file processing - Sensor data extraction - Map generation - Performance analysis

Sources

This page was last updated: December 31, 2025