# jizhang-cmu/autonomy_stack_go2 architecture

> Architecture diagram of the GitHub repository jizhang-cmu/autonomy_stack_go2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jizhang-cmu/autonomy_stack_go2
- Repository: https://github.com/jizhang-cmu/autonomy_stack_go2

## Overview

This is a ROS 2 autonomy stack for the Unitree Go2. The principal workflow is: onboard lidar/IMU data is processed by SLAM, terrain and scan analysis produce navigable context, and either waypoint/joystick control or the optional FAR route planner supplies targets to local collision avoidance and path following. Sport API messages command the robot. RViz tools provide goals, waypoints, and teleoperation; Unity simulation and the ROS-TCP endpoint support external simulation and control. Several subsystem links are inferred from documented responsibilities because most node implementations were not sampled.

Main entry points: [`src/route_planner/far_planner/src/far_planner.cpp`](https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/route_planner/far_planner/src/far_planner.cpp) (FAR Route Planner), [`src/base_autonomy/local_planner/src/localPlanner.cpp`](https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/base_autonomy/local_planner/src/localPlanner.cpp) (Local Planner), [`src/base_autonomy/vehicle_simulator/src/vehicleSimulator.cpp`](https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/base_autonomy/vehicle_simulator/src/vehicleSimulator.cpp) (Vehicle Simulator), [`src/base_autonomy/sensor_scan_generation/src/sensorScanGeneration.cpp`](https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/base_autonomy/sensor_scan_generation/src/sensorScanGeneration.cpp) (Scan Generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sensing["Sensing Localization"]
  node_scan_generation["Scan Generation"]
  node_slam["SLAM Estimator<br/>[laserMapping.cpp]"]
  node_terrain_analysis["Terrain Analysis"]
  node_terrain_ext["Terrain Extension"]
end

subgraph group_mapping["Mapping Planning"]
  node_far_planner["FAR Route Planner<br/>[far_planner.cpp]"]
  node_map_handler["Map Handler<br/>[map_handler.cpp]"]
  node_scan_handler["Scan Handler<br/>[scan_handler.cpp]"]
  node_boundary_handler["Boundary Handler"]
  node_graph_decoder["Graph Decoder<br/>[decoder_node.cpp]"]
end

subgraph group_control["Control Execution"]
  node_local_planner["Local Planner<br/>[localPlanner.cpp]"]
  node_path_follower["Path Follower<br/>[pathFollower.cpp]"]
  node_sport_api["Sport API"]
end

subgraph group_interfaces["User Simulation"]
  node_waypoint_ui["Waypoint Tool<br/>[waypoint_tool.cpp]"]
  node_goalpoint_ui["Goalpoint Tool<br/>[goalpoint_tool.cpp]"]
  node_teleop_ui["Teleop Panel<br/>[teleop_panel.cpp]"]
  node_visualization["Visualization Tools"]
  node_vehicle_sim["Vehicle Simulator"]
  node_tcp_endpoint["ROS TCP Endpoint<br/>[server.py]"]
end

node_go2_sensors(("Go2 Sensors"))
node_user(("Operator"))
node_unity["Unity Simulation"]
node_go2_robot["Go2 Robot"]

node_go2_sensors -->|"provides scans"| node_scan_generation
node_go2_sensors -->|"provides lidar IMU"| node_slam
node_scan_generation -->|"generates scans"| node_terrain_analysis
node_slam -->|"publishes pose"| node_far_planner
node_terrain_analysis -->|"provides terrain"| node_local_planner
node_terrain_ext -.->|"extends terrain"| node_local_planner
node_far_planner -->|"updates map"| node_map_handler
node_far_planner -->|"processes scans"| node_scan_handler
node_far_planner -->|"extracts boundaries"| node_boundary_handler
node_far_planner -->|"publishes graph"| node_graph_decoder
node_goalpoint_ui -->|"sends goal"| node_far_planner
node_waypoint_ui -->|"sends waypoint"| node_local_planner
node_teleop_ui -->|"sends velocity"| node_local_planner
node_far_planner -.->|"sends route"| node_local_planner
node_local_planner -->|"computes following"| node_path_follower
node_path_follower -->|"creates commands"| node_sport_api
node_sport_api -->|"commands motion"| node_go2_robot
node_user -->|"sets waypoint"| node_waypoint_ui
node_user -->|"sets goal"| node_goalpoint_ui
node_user -->|"drives robot"| node_teleop_ui
node_unity -.->|"provides environment"| node_vehicle_sim
node_vehicle_sim -.->|"simulates sensors"| node_go2_sensors
node_tcp_endpoint -.->|"bridges ROS TCP"| node_vehicle_sim
node_visualization -->|"shows state"| node_user

click node_scan_generation "https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/base_autonomy/sensor_scan_generation/src/sensorScanGeneration.cpp"
click node_slam "https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/slam/point_lio_unilidar/src/laserMapping.cpp"
click node_terrain_analysis "https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/base_autonomy/terrain_analysis/src/terrainAnalysis.cpp"
click node_terrain_ext "https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/base_autonomy/terrain_analysis_ext/src/terrainAnalysisExt.cpp"
click node_far_planner "https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/route_planner/far_planner/src/far_planner.cpp"
click node_map_handler "https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/route_planner/far_planner/src/map_handler.cpp"
click node_scan_handler "https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/route_planner/far_planner/src/scan_handler.cpp"
click node_boundary_handler "https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/route_planner/boundary_handler/src/graph_extractor.cpp"
click node_graph_decoder "https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/route_planner/graph_decoder/src/decoder_node.cpp"
click node_local_planner "https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/base_autonomy/local_planner/src/localPlanner.cpp"
click node_path_follower "https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/base_autonomy/local_planner/src/pathFollower.cpp"
click node_sport_api "https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/utilities/unitree_pkgs/go2_sport_api/src/common/ros2_sport_client.cpp"
click node_waypoint_ui "https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/utilities/waypoint_rviz_plugin/src/waypoint_tool.cpp"
click node_goalpoint_ui "https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/utilities/goalpoint_rviz_plugin/src/goalpoint_tool.cpp"
click node_teleop_ui "https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/utilities/teleop_rviz_plugin/src/teleop_panel.cpp"
click node_visualization "https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/base_autonomy/visualization_tools/src/visualizationTools.cpp"
click node_vehicle_sim "https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/base_autonomy/vehicle_simulator/src/vehicleSimulator.cpp"
click node_tcp_endpoint "https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/utilities/ROS-TCP-Endpoint/ros_tcp_endpoint/server.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_scan_generation,node_slam,node_terrain_analysis,node_terrain_ext toneBlue
class node_far_planner,node_map_handler,node_scan_handler,node_boundary_handler,node_graph_decoder toneAmber
class node_local_planner,node_path_follower,node_sport_api toneMint
class node_waypoint_ui,node_goalpoint_ui,node_teleop_ui,node_visualization,node_vehicle_sim,node_tcp_endpoint toneRose
class node_go2_sensors,node_user,node_unity,node_go2_robot toneIndigo
```

## Components

### Sensing Localization

- [Scan Generation](https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/base_autonomy/sensor_scan_generation/src/sensorScanGeneration.cpp): `src/base_autonomy/sensor_scan_generation/src/sensorScanGeneration.cpp`
- [SLAM Estimator](https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/slam/point_lio_unilidar/src/laserMapping.cpp): `src/slam/point_lio_unilidar/src/laserMapping.cpp`
- [Terrain Analysis](https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/base_autonomy/terrain_analysis/src/terrainAnalysis.cpp): `src/base_autonomy/terrain_analysis/src/terrainAnalysis.cpp`
- [Terrain Extension](https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/base_autonomy/terrain_analysis_ext/src/terrainAnalysisExt.cpp): `src/base_autonomy/terrain_analysis_ext/src/terrainAnalysisExt.cpp`

### Mapping Planning

- [FAR Route Planner](https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/route_planner/far_planner/src/far_planner.cpp): `src/route_planner/far_planner/src/far_planner.cpp`
- [Map Handler](https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/route_planner/far_planner/src/map_handler.cpp): `src/route_planner/far_planner/src/map_handler.cpp`
- [Scan Handler](https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/route_planner/far_planner/src/scan_handler.cpp): `src/route_planner/far_planner/src/scan_handler.cpp`
- [Boundary Handler](https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/route_planner/boundary_handler/src/graph_extractor.cpp): `src/route_planner/boundary_handler/src/graph_extractor.cpp`
- [Graph Decoder](https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/route_planner/graph_decoder/src/decoder_node.cpp): `src/route_planner/graph_decoder/src/decoder_node.cpp`

### Control Execution

- [Local Planner](https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/base_autonomy/local_planner/src/localPlanner.cpp): `src/base_autonomy/local_planner/src/localPlanner.cpp`
- [Path Follower](https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/base_autonomy/local_planner/src/pathFollower.cpp): `src/base_autonomy/local_planner/src/pathFollower.cpp`
- [Sport API](https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/utilities/unitree_pkgs/go2_sport_api/src/common/ros2_sport_client.cpp): `src/utilities/unitree_pkgs/go2_sport_api/src/common/ros2_sport_client.cpp`

### User Simulation

- [Waypoint Tool](https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/utilities/waypoint_rviz_plugin/src/waypoint_tool.cpp): `src/utilities/waypoint_rviz_plugin/src/waypoint_tool.cpp`
- [Goalpoint Tool](https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/utilities/goalpoint_rviz_plugin/src/goalpoint_tool.cpp): `src/utilities/goalpoint_rviz_plugin/src/goalpoint_tool.cpp`
- [Teleop Panel](https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/utilities/teleop_rviz_plugin/src/teleop_panel.cpp): `src/utilities/teleop_rviz_plugin/src/teleop_panel.cpp`
- [Visualization Tools](https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/base_autonomy/visualization_tools/src/visualizationTools.cpp): `src/base_autonomy/visualization_tools/src/visualizationTools.cpp`
- [Vehicle Simulator](https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/base_autonomy/vehicle_simulator/src/vehicleSimulator.cpp): `src/base_autonomy/vehicle_simulator/src/vehicleSimulator.cpp`
- [ROS TCP Endpoint](https://github.com/jizhang-cmu/autonomy_stack_go2/blob/foxy-humble/src/utilities/ROS-TCP-Endpoint/ros_tcp_endpoint/server.py): `src/utilities/ROS-TCP-Endpoint/ros_tcp_endpoint/server.py`

### Other components

- **Go2 Sensors**
- **Operator**
- **Unity Simulation**
- **Go2 Robot**

## Connections

- Go2 Sensors → Scan Generation: provides scans
- Go2 Sensors → SLAM Estimator: provides lidar IMU
- Scan Generation → Terrain Analysis: generates scans
- SLAM Estimator → FAR Route Planner: publishes pose
- Terrain Analysis → Local Planner: provides terrain
- Terrain Extension → Local Planner: extends terrain
- FAR Route Planner → Map Handler: updates map
- FAR Route Planner → Scan Handler: processes scans
- FAR Route Planner → Boundary Handler: extracts boundaries
- FAR Route Planner → Graph Decoder: publishes graph
- Goalpoint Tool → FAR Route Planner: sends goal
- Waypoint Tool → Local Planner: sends waypoint
- Teleop Panel → Local Planner: sends velocity
- FAR Route Planner → Local Planner: sends route
- Local Planner → Path Follower: computes following
- Path Follower → Sport API: creates commands
- Sport API → Go2 Robot: commands motion
- Operator → Waypoint Tool: sets waypoint
- Operator → Goalpoint Tool: sets goal
- Operator → Teleop Panel: drives robot
- Unity Simulation → Vehicle Simulator: provides environment
- Vehicle Simulator → Go2 Sensors: simulates sensors
- ROS TCP Endpoint → Vehicle Simulator: bridges ROS TCP
- Visualization Tools → Operator: shows state
