Skip to content

Home

Jump to bottom
Marc Hanheide edited this page Oct 15, 2026 · 4 revisions

Topological Navigation for ROS 2

A ROS 2 framework for graph-based topological navigation of autonomous mobile robots. The environment is represented as a graph of nodes (waypoints with an influence zone) connected by edges (traversable paths). Each edge names an action (for example a Nav2 NavigateToPose goal or a row traversal), which is executed through pluggable, map-defined action templates.

Originally developed for the STRANDS project, the framework is now used in agricultural robotics (vineyards, orchards, crop rows).

Version 4.0.0 and later are ROS 2 only and are tested on Humble and Jazzy. The ROS 1 version (3.x and earlier) is no longer maintained and the ROS 1 era wiki pages are marked as legacy.

This wiki complements the READMEs and the doc/ folder in the repository. The READMEs are the reference for launch arguments, node parameters, topics, services and actions.

Wiki pages

Page Content
Quick Topological Navigation in simulation tutorial Run the full stack with a simulated robot, send goals, create a map
Topological Navigation 2 Architecture: nodes, data flow, packages
Topological YAML Format The .tmap2.yaml / .tmap3.yaml map format
Topological Map Definition The topological_navigation_msgs map message types
Topological Navigation 2 Testing Running the unit, integration and CI tests
Topological Navigation Restrictions Legacy (ROS 1) restrictions, not implemented in ROS 2
Useful Mongodb Queries and Updates Legacy (ROS 1) MongoDB storage, not used in ROS 2

Repository structure

Package Type Purpose
topological_navigation ament_python Core stack: map manager, localisation, navigation server, map recorder, CLI tools
topological_navigation_msgs ament_cmake Messages, services and actions
topological_navigation_visual ament_python RViz visualiser and interactive editor, browser web app
topological_nav_simulator ament_python Fake Nav2 action servers with a virtual robot, for testing without hardware

Quick start

# Build
mkdir -p ~/ws/src && cd ~/ws/src
git clone https://github.com/LCAS/topological_navigation.git
cd ~/ws && rosdep install --from-paths src --ignore-src -r -y
colcon build --symlink-install && source install/setup.bash

# Full stack with a simulated robot (map manager, localisation, navigation,
# fake Nav2, visualiser, RViz and web app on http://localhost:8083/)
ros2 launch topological_navigation topological_navigation.launch.py

# Send the robot to a node
ros2 action send_goal /topological_navigation \
    topological_navigation_msgs/action/GotoNode "{target: 'node_name'}"

Executables

Package Executable Description
topological_navigation map_manager2.py Loads a map, validates it, publishes it on /topological_map_2
localisation2.py Publishes /current_node, /closest_node, /closest_edges
navigation2.py GotoNode and ExecutePolicyMode action servers
map_recorder.py Records a map while driving (/record action)
manual_topomapping.py Joystick driven waypoint recording
validate_map.py Validate a map against tmap-schema.yaml
convert_tmap.py Convert a legacy map to the tmap3 format
map_analyser.py Analyse, check, render (SVG), minify and merge maps (no ROS needed)
topo_stats.py Inspect the navigation statistics database (no ROS needed)
topomap_to_map_image.py Generate a Nav2 map image from a topological map
topological_navigation_visual topological_map_visualiser.py RViz markers and drag-and-drop editor
topological_visual.py Route and occupied node visualisation
topological_web_app.py Browser UI on port 8083
policy_marker.py Policy arrow markers
topological_nav_simulator fake_nav2_server Fake navigate_to_pose, navigate_through_poses, follow_waypoints

Further documentation (in the repository)

Clone this wiki locally