# maxhawksby/go2-fusion architecture

> Architecture diagram of the GitHub repository maxhawksby/go2-fusion, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maxhawksby/go2-fusion
- Repository: https://github.com/maxhawksby/go2-fusion

## Overview

Oak is a ROS 2 software stack for a Unitree Go2 robot. The principal workflow is operator- or autonomy-generated motion and sensor data flowing through ROS nodes: the driver connects to the robot, perception and mapping support exploration, and viewers expose results. The README also documents AI/voice, object detection, simulation, and lab measurement capabilities. Some subsystem links are documented only at product level; source-level links below rely on the supplied excerpts and SOURCE INDEX, so unsampled integrations are not asserted.

Main entry points: [`src/go2_auto_mapper/go2_auto_mapper/explorer.py`](https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_auto_mapper/go2_auto_mapper/explorer.py) (Frontier explorer), [`src/go2_llm_agent/go2_llm_agent/agent.py`](https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_llm_agent/go2_llm_agent/agent.py) (Language agent), [`src/go2_robot_sdk/go2_robot_sdk/presentation/go2_driver_node.py`](https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_robot_sdk/go2_robot_sdk/presentation/go2_driver_node.py) (Go2 driver), [`src/go2_robot_sdk/go2_robot_sdk/infrastructure/webrtc`](https://github.com/maxhawksby/go2-fusion/tree/master/src/go2_robot_sdk/go2_robot_sdk/infrastructure/webrtc) (WebRTC link)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Robot control"]
  node_keyboard["Keyboard teleop<br/>[keyboard_teleop.py]"]
  node_mux["Command mux"]
  node_driver["Go2 driver<br/>[go2_driver_node.py]"]
  node_control_service["Control service"]
  node_webrtc["WebRTC link"]
  node_data_service["Robot data service"]
end

subgraph group_sensing["Sensing and perception"]
  node_lidar["Lidar processing<br/>[point_map.py]"]
  node_object_detector["Object detector<br/>[detector_node.py]"]
  node_coco_detector["COCO detector"]
end

subgraph group_navigation["Mapping and navigation"]
  node_explorer["Frontier explorer<br/>[explorer.py]"]
  node_frontier["Frontier scoring"]
  node_obstacles["Obstacle sensing"]
  node_recovery["Recovery logic<br/>[recovery.py]"]
  node_social_space["Social space<br/>[social_space.py]"]
  node_vlm["Vision ranking<br/>[vlm_ranking.py]"]
  node_map_viewer["Map viewer"]
  node_rviz_mapper["Mapper panel"]
end

subgraph group_interaction["AI and interaction"]
  node_agent["Language agent<br/>[agent.py]"]
  node_motion_bridge["Motion bridge<br/>[ros2_motion.py]"]
  node_speech["Speech output<br/>[tts_node.py]"]
end

subgraph group_validation["Simulation and measurement"]
  node_simulator["Simulation tools<br/>[world_tools.py]"]
  node_trials["Exploration trials<br/>[trials.py]"]
  node_scoreboard["Lab measurement<br/>[lab_measure.py]"]
end

node_operator(("Operator"))
node_nav2["Nav2"]
node_robot["Unitree Go2"]

node_operator -->|"drives"| node_keyboard
node_operator -->|"controls"| node_rviz_mapper
node_keyboard -->|"publishes commands"| node_mux
node_mux -->|"selects control"| node_driver
node_driver -->|"uses services"| node_control_service
node_control_service -.->|"sends commands"| node_webrtc
node_robot -->|"streams data"| node_webrtc
node_webrtc -.->|"delivers messages"| node_data_service
node_data_service -->|"publishes lidar"| node_lidar
node_lidar -.->|"supplies map inputs"| node_explorer
node_robot -->|"provides camera feed"| node_object_detector
node_object_detector -.->|"provides detections"| node_agent
node_explorer -->|"scores frontiers"| node_frontier
node_explorer -->|"checks obstacles"| node_obstacles
node_explorer -->|"uses recovery"| node_recovery
node_explorer -->|"uses social costs"| node_social_space
node_explorer -->|"ranks views"| node_vlm
node_explorer -->|"sends navigation goals"| node_nav2
node_explorer -.->|"exposes controls"| node_rviz_mapper
node_operator -->|"gives instructions"| node_agent
node_agent -->|"dispatches actions"| node_motion_bridge
node_motion_bridge -.->|"commands motion"| node_driver
node_agent -.->|"requests speech"| node_speech
node_operator -->|"views maps"| node_map_viewer
node_simulator -->|"runs trial worlds"| node_trials
node_trials -.->|"evaluates exploration"| node_explorer
node_scoreboard -.->|"reports measurements"| node_operator

click node_keyboard "https://github.com/maxhawksby/go2-fusion/blob/master/src/keyboard_teleop/keyboard_teleop/keyboard_teleop.py"
click node_driver "https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_robot_sdk/go2_robot_sdk/presentation/go2_driver_node.py"
click node_control_service "https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_robot_sdk/go2_robot_sdk/application/services/robot_control_service.py"
click node_webrtc "https://github.com/maxhawksby/go2-fusion/tree/master/src/go2_robot_sdk/go2_robot_sdk/infrastructure/webrtc"
click node_data_service "https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_robot_sdk/go2_robot_sdk/application/services/robot_data_service.py"
click node_lidar "https://github.com/maxhawksby/go2-fusion/blob/master/src/lidar_processor/lidar_processor/point_map.py"
click node_object_detector "https://github.com/maxhawksby/go2-fusion/blob/master/src/object_detection/object_detection/detector_node.py"
click node_coco_detector "https://github.com/maxhawksby/go2-fusion/blob/master/src/coco_detector/coco_detector/coco_detector_node.py"
click node_explorer "https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_auto_mapper/go2_auto_mapper/explorer.py"
click node_frontier "https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_auto_mapper/go2_auto_mapper/frontier_scoring.py"
click node_obstacles "https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_auto_mapper/go2_auto_mapper/obstacle_sensing.py"
click node_recovery "https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_auto_mapper/go2_auto_mapper/recovery.py"
click node_social_space "https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_auto_mapper/go2_auto_mapper/social_space.py"
click node_vlm "https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_auto_mapper/go2_auto_mapper/vlm_ranking.py"
click node_map_viewer "https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_map_viewer_cpp/src/map_viewer_node.cpp"
click node_rviz_mapper "https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_rviz_plugins/src/auto_mapper_panel.cpp"
click node_agent "https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_llm_agent/go2_llm_agent/agent.py"
click node_motion_bridge "https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_llm_agent/go2_llm_agent/ros2_motion.py"
click node_speech "https://github.com/maxhawksby/go2-fusion/blob/master/src/speech_processor/speech_processor/tts_node.py"
click node_simulator "https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_sim/go2_sim/world_tools.py"
click node_trials "https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_sim/go2_sim/trials.py"
click node_scoreboard "https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_scoreboard/go2_scoreboard/lab_measure.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_keyboard,node_mux,node_driver,node_control_service,node_webrtc,node_data_service toneBlue
class node_lidar,node_object_detector,node_coco_detector toneAmber
class node_explorer,node_frontier,node_obstacles,node_recovery,node_social_space,node_vlm,node_map_viewer,node_rviz_mapper toneMint
class node_agent,node_motion_bridge,node_speech toneRose
class node_simulator,node_trials,node_scoreboard,node_operator,node_nav2,node_robot toneIndigo
```

## Components

### Robot control

- [Keyboard teleop](https://github.com/maxhawksby/go2-fusion/blob/master/src/keyboard_teleop/keyboard_teleop/keyboard_teleop.py): `src/keyboard_teleop/keyboard_teleop/keyboard_teleop.py`
- **Command mux**
- [Go2 driver](https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_robot_sdk/go2_robot_sdk/presentation/go2_driver_node.py): `src/go2_robot_sdk/go2_robot_sdk/presentation/go2_driver_node.py`
- [Control service](https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_robot_sdk/go2_robot_sdk/application/services/robot_control_service.py): `src/go2_robot_sdk/go2_robot_sdk/application/services/robot_control_service.py`
- [WebRTC link](https://github.com/maxhawksby/go2-fusion/tree/master/src/go2_robot_sdk/go2_robot_sdk/infrastructure/webrtc): `src/go2_robot_sdk/go2_robot_sdk/infrastructure/webrtc`
- [Robot data service](https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_robot_sdk/go2_robot_sdk/application/services/robot_data_service.py): `src/go2_robot_sdk/go2_robot_sdk/application/services/robot_data_service.py`

### Sensing and perception

- [Lidar processing](https://github.com/maxhawksby/go2-fusion/blob/master/src/lidar_processor/lidar_processor/point_map.py): `src/lidar_processor/lidar_processor/point_map.py`
- [Object detector](https://github.com/maxhawksby/go2-fusion/blob/master/src/object_detection/object_detection/detector_node.py): `src/object_detection/object_detection/detector_node.py`
- [COCO detector](https://github.com/maxhawksby/go2-fusion/blob/master/src/coco_detector/coco_detector/coco_detector_node.py): `src/coco_detector/coco_detector/coco_detector_node.py`

### Mapping and navigation

- [Frontier explorer](https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_auto_mapper/go2_auto_mapper/explorer.py): `src/go2_auto_mapper/go2_auto_mapper/explorer.py`
- [Frontier scoring](https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_auto_mapper/go2_auto_mapper/frontier_scoring.py): `src/go2_auto_mapper/go2_auto_mapper/frontier_scoring.py`
- [Obstacle sensing](https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_auto_mapper/go2_auto_mapper/obstacle_sensing.py): `src/go2_auto_mapper/go2_auto_mapper/obstacle_sensing.py`
- [Recovery logic](https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_auto_mapper/go2_auto_mapper/recovery.py): `src/go2_auto_mapper/go2_auto_mapper/recovery.py`
- [Social space](https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_auto_mapper/go2_auto_mapper/social_space.py): `src/go2_auto_mapper/go2_auto_mapper/social_space.py`
- [Vision ranking](https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_auto_mapper/go2_auto_mapper/vlm_ranking.py): `src/go2_auto_mapper/go2_auto_mapper/vlm_ranking.py`
- [Map viewer](https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_map_viewer_cpp/src/map_viewer_node.cpp): `src/go2_map_viewer_cpp/src/map_viewer_node.cpp`
- [Mapper panel](https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_rviz_plugins/src/auto_mapper_panel.cpp): `src/go2_rviz_plugins/src/auto_mapper_panel.cpp`

### AI and interaction

- [Language agent](https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_llm_agent/go2_llm_agent/agent.py): `src/go2_llm_agent/go2_llm_agent/agent.py`
- [Motion bridge](https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_llm_agent/go2_llm_agent/ros2_motion.py): `src/go2_llm_agent/go2_llm_agent/ros2_motion.py`
- [Speech output](https://github.com/maxhawksby/go2-fusion/blob/master/src/speech_processor/speech_processor/tts_node.py): `src/speech_processor/speech_processor/tts_node.py`

### Simulation and measurement

- [Simulation tools](https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_sim/go2_sim/world_tools.py): `src/go2_sim/go2_sim/world_tools.py`
- [Exploration trials](https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_sim/go2_sim/trials.py): `src/go2_sim/go2_sim/trials.py`
- [Lab measurement](https://github.com/maxhawksby/go2-fusion/blob/master/src/go2_scoreboard/go2_scoreboard/lab_measure.py): `src/go2_scoreboard/go2_scoreboard/lab_measure.py`

### Other components

- **Operator**
- **Nav2**
- **Unitree Go2**

## Connections

- Operator → Keyboard teleop: drives (evidence: `README.md`)
- Operator → Mapper panel: controls (evidence: `README.md`)
- Keyboard teleop → Command mux: publishes commands (evidence: `README.md`)
- Command mux → Go2 driver: selects control (evidence: `README.md`)
- Go2 driver → Control service: uses services (evidence: `src/go2_robot_sdk/go2_robot_sdk/presentation/go2_driver_node.py`)
- Control service → WebRTC link: sends commands
- Unitree Go2 → WebRTC link: streams data (evidence: `README.md`)
- WebRTC link → Robot data service: delivers messages
- Robot data service → Lidar processing: publishes lidar (evidence: `src/go2_robot_sdk/go2_robot_sdk/application/services/robot_data_service.py`)
- Lidar processing → Frontier explorer: supplies map inputs
- Unitree Go2 → Object detector: provides camera feed (evidence: `README.md`)
- Object detector → Language agent: provides detections
- Frontier explorer → Frontier scoring: scores frontiers (evidence: `src/go2_auto_mapper/go2_auto_mapper/explorer.py`)
- Frontier explorer → Obstacle sensing: checks obstacles (evidence: `src/go2_auto_mapper/go2_auto_mapper/explorer.py`)
- Frontier explorer → Recovery logic: uses recovery (evidence: `src/go2_auto_mapper/go2_auto_mapper/explorer.py`)
- Frontier explorer → Social space: uses social costs (evidence: `src/go2_auto_mapper/go2_auto_mapper/explorer.py`)
- Frontier explorer → Vision ranking: ranks views (evidence: `src/go2_auto_mapper/go2_auto_mapper/explorer.py`)
- Frontier explorer → Nav2: sends navigation goals (evidence: `src/go2_auto_mapper/go2_auto_mapper/explorer.py`)
- Frontier explorer → Mapper panel: exposes controls
- Operator → Language agent: gives instructions (evidence: `README.md`)
- Language agent → Motion bridge: dispatches actions (evidence: `src/go2_llm_agent/go2_llm_agent/agent.py`)
- Motion bridge → Go2 driver: commands motion
- Language agent → Speech output: requests speech
- Operator → Map viewer: views maps (evidence: `README.md`)
- Simulation tools → Exploration trials: runs trial worlds (evidence: `src/go2_sim/go2_sim/trials.py`)
- Exploration trials → Frontier explorer: evaluates exploration
- Lab measurement → Operator: reports measurements
