Home

Welcome to the topological_navigation wiki!

Topological Navigation for ROS2

Overview

The Topological Navigation stack is a comprehensive ROS2 framework for robot navigation based on topological maps. It provides a graph-based approach to navigation where the environment is represented as a network of nodes connected by edges, each with specific properties and navigation behaviors.

This framework is particularly useful for:

• Large-scale indoor/outdoor navigation
• Navigation with specific constraints or behaviors at different locations
• Complex environments where traditional metric navigation alone is insufficient
• Scenarios requiring different navigation behaviors in different areas

Repository Structure

The repository consists of four main ROS2 packages:

1. topological_navigation - Core navigation functionality
2. topological_navigation_msgs - Message and service definitions
3. topological_rviz_tools - RViz-based visualization and editing tools
4. topological_utils - Utility tools for map management

Package Details

1. topological_navigation

The core package implementing topological navigation functionality.

Key Components:

• Map Management

  • manager.py: Core map management functionality
  • load_maps_from_yaml.py: YAML map loading utilities
  • topological_map.py: Map representation and handling

• Navigation

  • navigation.py: Main navigation node
  • route_search.py: Path planning in topological space
  • edge_controller.py: Edge traversal management
  • node_controller.py: Node behavior management

• Behaviors and Policies

  • policies.py: Navigation policy implementation
  • restrictions_impl.py: Navigation restrictions handling
  • edge_action_manager.py: Edge action execution

Features:

• Topological map management
• Route planning and execution
• Navigation action servers
• Navigation statistics and monitoring
• Dynamic reconfiguration support
• Multi-robot support through restrictions

2. topological_navigation_msgs

Defines the message and service interfaces for topological navigation.

Key Message Types:

• TopologicalMap: Map representation
• TopologicalNode: Node definition
• Edge: Edge definition with properties
• NavigateToAction: Navigation action interface

Services:

• Map management services
• Node/edge manipulation services
• Route planning services

3. topological_rviz_tools

Provides RViz plugins for visualizing and editing topological maps.

Features:

• Interactive map visualization
• Node addition/removal tools
• Edge creation/modification tools
• Property editing interface
• Real-time navigation visualization

Components:

• Node creation tool
• Edge creation tool
• Property panel
• Visualization markers

4. topological_utils

Utility package for map management and conversion.

Key Utilities:

• Map format conversion (YAML/JSON)
• Map manipulation tools
• Waypoint management
• Map analysis tools
• Visualization utilities

Scripts:

• add_node.py: Add nodes to existing maps
• map_export.py: Export maps to various formats
• plot_topo_map.py: Visualization tools
• Various map conversion and management tools

Usage Examples

1. Creating a Topological Map

# Launch RViz with topological tools
ros2 launch topological_rviz_tools rviz.launch.py

# Convert waypoints to a topological map
ros2 run topological_utils waypoints_to_yaml_tmap input_waypoints.yaml output_map.yaml

# Load a map from YAML
ros2 run topological_utils load_yaml_map map_file.yaml

2. Running Navigation

# Launch the navigation stack
ros2 launch topological_navigation navigation.launch.py map:=map_file.yaml

# Send a navigation goal
ros2 action send_goal /topological_navigation/navigate_to topological_navigation_msgs/action/NavigateTo "goal_node: 'WayPoint1'"

3. Map Management

# Add a new node
ros2 run topological_utils add_node "map_name" "node_name" [x] [y]

# Export map to YAML
ros2 run topological_utils map_to_yaml map_name output.yaml

# Add an edge between nodes
ros2 run topological_utils add_edge "map_name" "node1" "node2"

Configuration

Node Properties

properties:
  xy_goal_tolerance: 0.3
  yaw_goal_tolerance: 0.1

Edge Properties

edge:
  action: "NavigateToPose"
  action_type: "geometry_msgs/PoseStamped"
  restrictions_planning: "True"
  restrictions_runtime: "obstacleFree_1"

Best Practices

1. Map Organization

   • Use meaningful node names
   • Group related nodes with common prefixes
   • Document special nodes/edges

2. Navigation Setup

   • Configure appropriate tolerances
   • Set up meaningful restrictions
   • Test edge traversability

3. Performance Optimization

   • Keep map size manageable
   • Use appropriate goal tolerances
   • Configure edge restrictions properly

Common Workflows

1. Initial Setup

   • Create/import metric map
   • Add topological nodes
   • Connect nodes with edges
   • Configure node/edge properties

2. Map Maintenance

   • Regular validation of edges
   • Update restrictions as needed
   • Monitor navigation statistics
   • Adjust tolerances based on performance

3. Integration

   • Configure robot-specific parameters
   • Set up appropriate recovery behaviors
   • Integrate with other navigation components
   • Configure visualization tools

Troubleshooting

Common issues and solutions:

1. Navigation Failures

   • Check edge traversability
   • Verify node positions
   • Review restriction settings
   • Check robot localization

2. Map Issues

   • Validate YAML syntax
   • Check node coordinates
   • Verify edge connections
   • Review restriction configurations

3. Performance Issues

   • Optimize map size
   • Adjust tolerances
   • Review edge restrictions
   • Check system resources