# purduelunabotics/purdue_lunabotics architecture

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

- Interactive diagram: https://gitdiagram.com/purduelunabotics/purdue_lunabotics
- Repository: https://github.com/purduelunabotics/purdue_lunabotics

## Overview

This repository is a ROS 2 robotics stack for Purdue Lunabotics, spanning autonomous behavior, teleoperation, navigation, perception, simulation, and embedded robot control. A principal workflow is an operator or autonomy state machine producing motion and mechanism commands; navigation and perception support robot operation, while embedded firmware interfaces with physical actuators. The graph preserves these documented and tree-visible subsystems. Some links are dashed because the sampled excerpts do not show their runtime wiring.

Main entry points: [`lunabot_behavior/lunabot_behavior/state_manager.py`](https://github.com/purduelunabotics/purdue_lunabotics/blob/master/lunabot_behavior/lunabot_behavior/state_manager.py) (State manager), [`lunabot_embedded/src/teensy_driver_node.cpp`](https://github.com/purduelunabotics/purdue_lunabotics/blob/master/lunabot_embedded/src/teensy_driver_node.cpp) (Teensy driver), [`lunabot_nav/src/nav2_bridge.cpp`](https://github.com/purduelunabotics/purdue_lunabotics/blob/master/lunabot_nav/src/nav2_bridge.cpp) (Nav2 bridge), [`lunabot_msgs`](https://github.com/purduelunabotics/purdue_lunabotics/tree/master/lunabot_msgs) (Robot messages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_behavior["Autonomous behavior"]
  node_behavior_manager["State manager<br/>[state_manager.py]"]
  node_behavior_states["Behavior states"]
  node_main_state_machine["Main state machine<br/>[main_states.py]"]
end

subgraph group_robot_io["Robot control and I/O"]
  node_manual_control["Manual controller"]
  node_drive_control["Drive controllers"]
  node_control_algorithms["Control algorithms<br/>[pid_controller.py]"]
  node_embedded_node["Teensy driver"]
  node_firmware_drivers["Firmware drivers"]
  node_hid["USB HID<br/>[hid.c]"]
end

subgraph group_navigation["Navigation and perception"]
  node_navigation_bridge["Nav2 bridge<br/>[nav2_bridge.cpp]"]
  node_path_planner["STheta* planner<br/>[stheta_star.cpp]"]
  node_perception["Perception nodes"]
end

subgraph group_simulation["Simulation and description"]
  node_sim_control["Gazebo control<br/>[gz_system.cpp]"]
  node_sim_plugin["Gazebo ROS plugin"]
  node_robot_description["Robot description"]
end

subgraph group_interfaces["Messages and configuration"]
  node_led_config["LED colors<br/>[led_colors.py]"]
  node_robot_messages["Robot messages"]
end

node_operator(("Operator"))
node_gazebo["Gazebo simulator"]
node_robot["Robot hardware"]

node_operator -->|"sends joystick input"| node_manual_control
node_manual_control -->|"publishes effort"| node_robot_messages
node_main_state_machine -->|"starts manager"| node_behavior_manager
node_behavior_manager -->|"runs state"| node_behavior_states
node_behavior_manager -->|"encodes colors"| node_led_config
node_behavior_manager -->|"handles events"| node_robot_messages
node_navigation_bridge -.->|"requests paths"| node_path_planner
node_perception -.->|"provides observations"| node_navigation_bridge
node_drive_control -.->|"uses control"| node_control_algorithms
node_embedded_node -->|"uses HID"| node_hid
node_embedded_node -.->|"exchanges commands"| node_firmware_drivers
node_robot_messages -->|"defines payloads"| node_embedded_node
node_sim_plugin -->|"loads system"| node_sim_control
node_sim_control -->|"reads and writes joints"| node_gazebo
node_robot_description -.->|"launches simulation"| node_gazebo
node_behavior_manager -.->|"requests navigation"| node_navigation_bridge
node_drive_control -.->|"commands drive"| node_robot
node_firmware_drivers -.->|"drives actuators"| node_robot

click node_behavior_manager "https://github.com/purduelunabotics/purdue_lunabotics/blob/master/lunabot_behavior/lunabot_behavior/state_manager.py"
click node_behavior_states "https://github.com/purduelunabotics/purdue_lunabotics/tree/master/lunabot_behavior/lunabot_behavior/states"
click node_main_state_machine "https://github.com/purduelunabotics/purdue_lunabotics/blob/master/lunabot_behavior/lunabot_behavior/main_states.py"
click node_manual_control "https://github.com/purduelunabotics/purdue_lunabotics/blob/master/lunabot_control/src/lunabot_control/manual_controller.py"
click node_drive_control "https://github.com/purduelunabotics/purdue_lunabotics/blob/master/lunabot_control/src/lunabot_control/differential_drive_controller.py"
click node_control_algorithms "https://github.com/purduelunabotics/purdue_lunabotics/blob/master/lunabot_control/src/lunabot_control/pid_controller.py"
click node_embedded_node "https://github.com/purduelunabotics/purdue_lunabotics/blob/master/lunabot_embedded/src/teensy_driver_node.cpp"
click node_firmware_drivers "https://github.com/purduelunabotics/purdue_lunabotics/tree/master/lunabot_embedded/firmware/teensy_main/lib/lunabot_drivers"
click node_hid "https://github.com/purduelunabotics/purdue_lunabotics/blob/master/lunabot_embedded/src/hid.c"
click node_navigation_bridge "https://github.com/purduelunabotics/purdue_lunabotics/blob/master/lunabot_nav/src/nav2_bridge.cpp"
click node_path_planner "https://github.com/purduelunabotics/purdue_lunabotics/blob/master/lunabot_nav/src/stheta_star.cpp"
click node_perception "https://github.com/purduelunabotics/purdue_lunabotics/tree/master/lunabot_perception"
click node_sim_control "https://github.com/purduelunabotics/purdue_lunabotics/blob/master/gz_ros2_control/src/gz_system.cpp"
click node_sim_plugin "https://github.com/purduelunabotics/purdue_lunabotics/blob/master/gz_ros2_control/src/gz_ros2_control_plugin.cpp"
click node_robot_description "https://github.com/purduelunabotics/purdue_lunabotics/blob/master/lunabot_description/launch/robot_description.launch.py"
click node_led_config "https://github.com/purduelunabotics/purdue_lunabotics/blob/master/lunabot_config/lunabot_config/led_colors.py"
click node_robot_messages "https://github.com/purduelunabotics/purdue_lunabotics/tree/master/lunabot_msgs"

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_behavior_manager,node_behavior_states,node_main_state_machine toneBlue
class node_manual_control,node_drive_control,node_control_algorithms,node_embedded_node,node_firmware_drivers,node_hid toneAmber
class node_navigation_bridge,node_path_planner,node_perception toneMint
class node_sim_control,node_sim_plugin,node_robot_description toneRose
class node_led_config,node_robot_messages,node_operator,node_gazebo,node_robot toneIndigo
```

## Components

### Autonomous behavior

- [State manager](https://github.com/purduelunabotics/purdue_lunabotics/blob/master/lunabot_behavior/lunabot_behavior/state_manager.py): `lunabot_behavior/lunabot_behavior/state_manager.py`
- [Behavior states](https://github.com/purduelunabotics/purdue_lunabotics/tree/master/lunabot_behavior/lunabot_behavior/states): `lunabot_behavior/lunabot_behavior/states`
- [Main state machine](https://github.com/purduelunabotics/purdue_lunabotics/blob/master/lunabot_behavior/lunabot_behavior/main_states.py): `lunabot_behavior/lunabot_behavior/main_states.py`

### Robot control and I/O

- [Manual controller](https://github.com/purduelunabotics/purdue_lunabotics/blob/master/lunabot_control/src/lunabot_control/manual_controller.py): `lunabot_control/src/lunabot_control/manual_controller.py`
- [Drive controllers](https://github.com/purduelunabotics/purdue_lunabotics/blob/master/lunabot_control/src/lunabot_control/differential_drive_controller.py): `lunabot_control/src/lunabot_control/differential_drive_controller.py`
- [Control algorithms](https://github.com/purduelunabotics/purdue_lunabotics/blob/master/lunabot_control/src/lunabot_control/pid_controller.py): `lunabot_control/src/lunabot_control/pid_controller.py`
- [Teensy driver](https://github.com/purduelunabotics/purdue_lunabotics/blob/master/lunabot_embedded/src/teensy_driver_node.cpp): `lunabot_embedded/src/teensy_driver_node.cpp`
- [Firmware drivers](https://github.com/purduelunabotics/purdue_lunabotics/tree/master/lunabot_embedded/firmware/teensy_main/lib/lunabot_drivers): `lunabot_embedded/firmware/teensy_main/lib/lunabot_drivers`
- [USB HID](https://github.com/purduelunabotics/purdue_lunabotics/blob/master/lunabot_embedded/src/hid.c): `lunabot_embedded/src/hid.c`

### Navigation and perception

- [Nav2 bridge](https://github.com/purduelunabotics/purdue_lunabotics/blob/master/lunabot_nav/src/nav2_bridge.cpp): `lunabot_nav/src/nav2_bridge.cpp`
- [STheta* planner](https://github.com/purduelunabotics/purdue_lunabotics/blob/master/lunabot_nav/src/stheta_star.cpp): `lunabot_nav/src/stheta_star.cpp`
- [Perception nodes](https://github.com/purduelunabotics/purdue_lunabotics/tree/master/lunabot_perception): `lunabot_perception`

### Simulation and description

- [Gazebo control](https://github.com/purduelunabotics/purdue_lunabotics/blob/master/gz_ros2_control/src/gz_system.cpp): `gz_ros2_control/src/gz_system.cpp`
- [Gazebo ROS plugin](https://github.com/purduelunabotics/purdue_lunabotics/blob/master/gz_ros2_control/src/gz_ros2_control_plugin.cpp): `gz_ros2_control/src/gz_ros2_control_plugin.cpp`
- [Robot description](https://github.com/purduelunabotics/purdue_lunabotics/blob/master/lunabot_description/launch/robot_description.launch.py): `lunabot_description/launch/robot_description.launch.py`

### Messages and configuration

- [LED colors](https://github.com/purduelunabotics/purdue_lunabotics/blob/master/lunabot_config/lunabot_config/led_colors.py): `lunabot_config/lunabot_config/led_colors.py`
- [Robot messages](https://github.com/purduelunabotics/purdue_lunabotics/tree/master/lunabot_msgs): `lunabot_msgs`

### Other components

- **Operator**
- **Gazebo simulator**
- **Robot hardware**

## Connections

- Operator → Manual controller: sends joystick input (evidence: `lunabot_control/src/lunabot_control/manual_controller.py`)
- Manual controller → Robot messages: publishes effort (evidence: `lunabot_control/src/lunabot_control/manual_controller.py`)
- Main state machine → State manager: starts manager (evidence: `lunabot_behavior/lunabot_behavior/main_states.py`)
- State manager → Behavior states: runs state (evidence: `lunabot_behavior/lunabot_behavior/state_manager.py`)
- State manager → LED colors: encodes colors (evidence: `lunabot_behavior/lunabot_behavior/state_manager.py`)
- State manager → Robot messages: handles events (evidence: `lunabot_behavior/lunabot_behavior/state_manager.py`)
- Nav2 bridge → STheta* planner: requests paths
- Perception nodes → Nav2 bridge: provides observations
- Drive controllers → Control algorithms: uses control
- Teensy driver → USB HID: uses HID (evidence: `lunabot_embedded/src/teensy_driver_node.cpp`)
- Teensy driver → Firmware drivers: exchanges commands
- Robot messages → Teensy driver: defines payloads (evidence: `lunabot_embedded/src/teensy_driver_node.cpp`)
- Gazebo ROS plugin → Gazebo control: loads system (evidence: `gz_ros2_control/src/gz_ros2_control_plugin.cpp`)
- Gazebo control → Gazebo simulator: reads and writes joints (evidence: `gz_ros2_control/src/gz_system.cpp`)
- Robot description → Gazebo simulator: launches simulation
- State manager → Nav2 bridge: requests navigation
- Drive controllers → Robot hardware: commands drive
- Firmware drivers → Robot hardware: drives actuators