Implement generic, URI-based robot configuration system for URDF customization

[Copilot]

Individual Hunter robot instances have idiosyncratic differences in sensor mount positions due to manufacturing tolerances and calibration. Currently, all sensor poses are hardcoded in hunter_pltf.urdf.xacro, requiring separate xacro files per robot or manual editing.

This PR implements a generic, reusable YAML-based configuration system that allows customization of sensor poses for individual robot instances without creating separate xacro files. The system works with any robot and URDF, not just Hunter platform.

Implementation Summary

Complete generic configuration system with:

• URI support: Load configs from local files, absolute paths, file:// URLs, or https:// URLs
• Generic YAML-to-xacro mapping: Automatically flattens nested YAML structures to xacro arguments (no hardcoded sensor names)
• Reusable design: Works with any URDF/robot type (mobile robots, manipulators, drones, etc.)
• Per-robot YAML config files in config/robots/ (e.g., hunter_01.yaml)
• default.yaml baseline with all standard sensor poses
• Robot-specific configs contain only deltas/overrides (inheritance-based)
• Launch files load YAML and pass parameters to xacro via arguments
• Xacro files parameterized to accept all sensor poses with fallback defaults

Files Created

Configuration Files

1. config/robots/default.yaml (156 lines) - Baseline configuration with all 7 sensors
2. config/robots/hunter_01.yaml (86 lines) - Fully documented example with calibrated values
3. config/robots/config_loader.py (305 lines) - Generic Python utility for loading and merging configurations from any URI
4. config/robots/README.md (280+ lines) - Complete documentation covering usage, calibration, URI loading, and generic mapping
5. config/robots/EXAMPLE_USAGE.md (272 lines) - Practical examples and comparison tables
6. config/robots/GENERIC_USAGE.md (443 lines) - Examples for mobile robots, manipulators, and drones showing reusability

Modified Files

1. description/hunter_pltf.urdf.xacro - Added 60+ xacro:arg parameters for all sensor poses
2. launch/pltf_rsp.launch.py - Integrated config loader with robot_id argument
3. hunter_pltf_bringup/launch/hunter_pltf_bringup.launch.py - Added robot_id support
4. hunter_pltf_gazebo/launch/launch_sim.launch.py - Added robot_id support for simulation
5. CMakeLists.txt - Added config directory to install targets
6. .gitignore - Added Python cache file patterns

Configuration Structure

# config/robots/hunter_01.yaml
robot_id: "hunter_01"
# Calibration date: 2024-11-10
# Notes: Minor adjustments for manufacturing tolerances

sensors:
  imu:
    x: -0.251  # Override only what differs (1mm adjustment)
    y: 0.001
    z: 0.471
    # roll, pitch, yaw, topic inherited from default
  
  front_camera:
    x: 0.552   # 2mm adjustment
    y: 0.001
    z: 0.721
  
  front_lidar:
    x: 0.561
    y: 0.236
    z: 0.461
    roll_real: -0.0175  # Calibrated orientation for real hardware
    pitch_real: 0.001
    yaw_real: 0.0088

Key Features

✅ URI-based loading - Load configs from anywhere:

• Simple robot IDs: robot_id:=hunter_01 (looks in config/robots/)
• Absolute paths: robot_id:=/path/to/config.yaml
• File URLs: robot_id:=file:///path/to/config.yaml
• Remote HTTPS: robot_id:=https://example.com/config.yaml

✅ Generic YAML-to-xacro mapping - Works with any URDF:

• Automatically flattens nested structures (sensors.imu.x → imu_x)
• No hardcoded sensor names
• Configurable prefix (sensors, joints, links, etc.)
• Dynamic _sim/_real suffix handling

✅ Reusable for any robot - Not Hunter-specific:

• Mobile robots (lasers, cameras)
• Manipulators (joints, gripper)
• Drones (cameras, propellers)
• Any custom robot type

✅ Inheritance-based configuration - Robot-specific files only specify differences from default

✅ All sensors configurable - 7 sensors with full 6-DOF pose control:

• IMU (rear at GPS base) - x, y, z, roll, pitch, yaw, topic
• IMU1 (front) - x, y, z, roll, pitch, yaw, topic
• Front depth camera - x, y, z, roll, pitch, yaw
• Back depth camera - x, y, z, roll, pitch, yaw
• GPS base antenna - x, y, z, roll, pitch, yaw
• Front Mid-360 LiDAR - x, y, z, separate RPY for sim/real, topic
• Back Mid-360 LiDAR - x, y, z, separate RPY for sim/real, topic

✅ Simulation vs real hardware - Separate LiDAR orientations for sim and real deployments

✅ Launch argument support - robot_id parameter in all launch files

✅ Backward compatible - Defaults to baseline configuration if no robot_id specified

✅ Comprehensive documentation - 1000+ lines of documentation with usage examples, troubleshooting, and examples for different robot types

Usage Examples

Default configuration (backward compatible):

ros2 launch hunter_pltf_description pltf_rsp.launch.py
ros2 launch hunter_pltf_gazebo launch_sim.launch.py
ros2 launch hunter_pltf_bringup hunter_pltf_bringup.launch.py

Hunter-01 configuration:

ros2 launch hunter_pltf_description pltf_rsp.launch.py robot_id:=hunter_01
ros2 launch hunter_pltf_gazebo launch_sim.launch.py robot_id:=hunter_01
ros2 launch hunter_pltf_bringup hunter_pltf_bringup.launch.py robot_id:=hunter_01

Load from absolute path:

ros2 launch hunter_pltf_description pltf_rsp.launch.py robot_id:=/path/to/my_robot.yaml

Load from remote URL:

ros2 launch hunter_pltf_description pltf_rsp.launch.py robot_id:=https://config.example.com/robots/hunter_01.yaml

Test configuration:

cd config/robots
python3 config_loader.py hunter_01 true  # Test in simulation mode
python3 config_loader.py hunter_01 false # Test in real mode
python3 config_loader.py /path/to/config.yaml true  # Test from path

Generic Usage (Any Robot)

The system automatically works with any robot structure:

# mobile_robot.yaml
sensors:
  laser:
    x: 0.15        # → laser_x:=0.15
    range: 30.0    # → laser_range:=30.0

# manipulator.yaml
joints:
  shoulder:
    position: 0.0  # → shoulder_position:=0.0
    velocity: 2.0  # → shoulder_velocity:=2.0

See GENERIC_USAGE.md for complete examples with mobile robots, manipulators, and drones.

Hunter-01 Example

The hunter_01.yaml demonstrates realistic calibration with:

• Position variations: ±1-3mm from baseline (typical manufacturing tolerance)
• Orientation variations: <1° from baseline (typical mounting tolerance)
• Only 14 overridden parameters out of 60+ available
• Documented calibration date and notes

Validation

✅ Python syntax validated (all .py files)
✅ XML syntax validated (all .xacro files)
✅ YAML syntax validated (all .yaml files)
✅ Config loader tested with default and hunter_01
✅ Inheritance system verified (overrides work correctly)
✅ URI loading tested (paths, file://, https:// detection)
✅ Generic mapping tested with multiple robot types

Creating New Robot Configurations

1. Copy hunter_01.yaml as template (or create your own structure)
2. Update robot_id and calibration notes
3. Specify only values that differ from default
4. Test with config_loader.py
5. Use in launch files with robot_id:=<your_robot> or full URI

Reusability for Other Projects

This configuration system can be used in any ROS project:

• Copy config_loader.py to your project
• Structure your YAML to match your xacro argument names
• Use get_xacro_args_from_config() for automatic mapping
• See GENERIC_USAGE.md for integration examples

Fixes #25

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Make URDF configurable for instances of inidivdual robots (instantiate a generic URDF)</issue_title>
<issue_description>We need a general approach how we can account for changes in the poses of joints in the URDF for individual robot.

While the structure of each robot platform is the same and generated from the urdf/xacro setup in hunter_pltf_description/description, there are small idiosyncratic differences for each robot, e.g. around tolerances for mount points of sensors, antennas, etc.

We need a generalisable approach to inject the instance-specific information into the URDF tree, while trying to fix the structure of the platform and maximising re-use. So we don't want individual xacro files for each instance of a robot, but rather use either environment variables or small robot-specific yaml files (one ofr each specific robot instance).

</issue_description>

<agent_instructions>
Do not implement a solution yet, but rather generate a plan, exploring different options for a solution an discussing their pros and cons. Share this with the user. Only implement a solution in code when explicitily asked in subsequent comments.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes Make URDF configurable for instances of inidivdual robots (instantiate a generic URDF) #25

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[marc-hanheide]

@copilot The proposed solution is indeed a preferred one. Implement it with the example for hunter-01. Ensure that's sensible defaults are implemented, but for the example of hunter-01 create a full documented yaml config file that is passed to the launch file for simulation and real robot. Make all sensor pose configurable this way.

[marc-hanheide]

for the attention of @LeonardoGuevara @ibrahimhroob @gpdas

[Copilot]

@copilot The proposed solution is indeed a preferred one. Implement it with the example for hunter-01. Ensure that's sensible defaults are implemented, but for the example of hunter-01 create a full...

Implemented the YAML-based configuration system with a complete example for hunter_01:

Configuration files:

• config/robots/default.yaml - baseline sensor poses for all 7 sensors
• config/robots/hunter_01.yaml - fully documented example with calibrated values showing typical ±1-3mm position and <1° orientation variations
• config/robots/README.md - comprehensive documentation (200+ lines) covering usage, calibration guidelines, and troubleshooting

All sensors are now configurable:

• IMUs (2), depth cameras (2), GPS, LiDAR (2)
• Separate orientations for simulation vs real hardware
• Inheritance-based: robot configs only specify differences from default

Usage:

# Default
ros2 launch hunter_pltf_description pltf_rsp.launch.py

# Hunter-01 (simulation)
ros2 launch hunter_pltf_gazebo launch_sim.launch.py robot_id:=hunter_01

# Hunter-01 (real robot)
ros2 launch hunter_pltf_bringup hunter_pltf_bringup.launch.py robot_id:=hunter_01

All launch files updated with robot_id argument. Validated: Python syntax, XML, YAML, and config loader functionality.

Commits: 44e78f1, 2da0b84, 4030f9b

[marc-hanheide]

@copilot, try to address the individual comments to craft a more generic, reusable solution.

[marc-hanheide]

@copilot this assumes that robot configurations are always stored within this repository under config/robots, which is not a valid assumption. Robot specific configurations may well be stored in arbitrary files paths or even online (accessible via https). Amend the implementation to allow passing in URIs.

[Copilot]

Implemented URI support. The system now accepts:

• Simple robot IDs: robot_id:=hunter_01 (looks in config/robots/)
• Absolute paths: robot_id:=/path/to/config.yaml
• File URLs: robot_id:=file:///path/to/config.yaml
• HTTPS URLs: robot_id:=https://example.com/config.yaml

The load_robot_config() function auto-detects the input type and uses load_yaml_from_uri() which handles all URI schemes. Tested with local paths and URLs.

Commit: 4e80dd5

[marc-hanheide]

@copilot the get_xacro_args file is now very specific to the URDF. Is it possible to make an implementation that is more flexible and re-usable to be working with other URDFs, i.e., not referring to specific, hard-coded arguments, but directly expose the arguments of a URDF?

[Copilot]

Replaced hardcoded logic with generic flatten_dict() and get_xacro_args_from_config(). The system now:

• Automatically flattens any nested YAML structure (e.g., sensors.imu.x → imu_x)
• Works with any URDF (not Hunter-specific)
• Handles _sim/_real suffixes dynamically
• No hardcoded sensor names

Example: Any YAML structure like manipulator.joint1.position automatically becomes joint1_position.

The old get_xacro_args() is now just a wrapper for backward compatibility.

Commit: 4e80dd5

[Copilot]

@copilot, try to address the individual comments to craft a more generic, reusable solution.

Crafted a more generic, reusable solution:

URI Support:

• Load configs from local files, absolute paths, file:// URLs, or https:// URLs
• No assumption about config location

Generic Mapping:

• Automatic flattening of nested YAML to flat xacro arguments
• No hardcoded sensor names - works with any URDF structure
• Dynamic _sim/_real suffix handling

Reusable:

• Not Hunter-specific
• Configurable prefix (default: 'sensors')
• Works with any robot/URDF

Updated documentation with examples showing usage for other robots.

Commit: 4e80dd5