# wilselby/ros_quadrotor_simulator architecture

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

- Interactive diagram: https://gitdiagram.com/wilselby/ros_quadrotor_simulator
- Repository: https://github.com/wilselby/ros_quadrotor_simulator

## Overview

1. This repository is a ROS catkin workspace organized around one central system: a simulated quadrotor that can be driven manually, flown by waypoint, or used for 2D/3D autonomous navigation in Gazebo.

2. The architecture is layered. At the bottom is the vehicle model and simulation environment; above that are control nodes; above that are navigation/planning stacks; and at the edge are human inputs such as an Xbox joystick and preauthored waypoint files.

3. `quad_description` is the robot-model layer. It contains the quadrotor URDF/Xacro, meshes, sensor macros, RViz configs, and map/planner parameter files. This package defines what the robot is physically and what sensors or attachments it exposes to the rest of the system.

4. `quad_gazebo` is the simulation runtime layer. It provides Gazebo worlds, spawn launch files, and launch compositions that place the quadrotor into specific environments such as empty, kitchen, outdoor, and Willow Garage scenes. This is where the model and the control stack are bound into a live simulator.

5. `quad_control` is the main flight-control subsystem. It contains a reusable controller library plus separate nodes for attitude control, position control, and waypoint publishing. The waypoint node reads text files from `quad_control/resource` and emits timed `[x, y, z, yaw]` missions, while the attitude/position nodes translate higher-level commands into the control signals used by the simulated vehicle.

6. `quad_joystick_interface` is the manual input boundary. It wraps the ROS joystick integration and turns Xbox controller input into ROS messages that the quadrotor controllers consume. In the documented behavior, the controller buttons gate modes such as GPS/position mode, takeoff, landing, autonomous mode, and 3D navigation mode.

7. `quad_2dnav` is the 2D autonomy stack. It packages map assets, AMCL launch files, and Navigation Stack parameter YAMLs for costmaps and local planning. Its data flow is the classic ROS 2D navigation loop: sensor/localization data feed map-based localization and planning, and the planner produces motion commands back to the vehicle controller.

8. `quad_3dnav` is the 3D planning and execution stack built around MoveIt. It contains MoveIt configuration files for kinematics, joint limits, OMPL planning, controllers, sensors, and the quadrotor SRDF, plus launch files for move_group, trajectory execution, sensor management, and a warehouse database for stored planning data.

9. Two packages act as bridges into MoveIt’s execution model: `action_controller` and `moveit_simple_controller_manager`. `action_controller` defines a custom `MultiDofFollowJointTrajectory` action and translates MoveIt trajectories into quadrotor velocity commands. `moveit_simple_controller_manager` provides a custom controller-manager plugin and controller-handle classes so MoveIt can treat the quadrotor as a controllable multi-DOF platform rather than a standard manipulator.

10. The main external dependencies that shape the architecture are ROS, Gazebo, MoveIt, the ROS navigation stack, joystick support, and the ROS map server. There is also a MoveIt warehouse database path in the 3D nav package, indicating optional persistence of planning data and configurations.

11. The dominant data flows are: joystick input → quad control nodes → simulated flight in Gazebo; waypoint files → waypoint publisher → position controller → Gazebo; map/sensor data → 2D navigation stack → velocity commands; and MoveIt goals/trajectories → custom controller manager/action controller → quad velocity commands for 3D flight.

12. In diagram terms, the clean boundaries are: vehicle description, simulation environment, control nodes, human input, 2D navigation, 3D planning, and MoveIt bridging. The repository is less a single application than a ROS integration stack that wires these subsystems together through launch files, parameter YAMLs, and ROS messages/actions.

Main entry points: [`quad_control`](https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_control) (Quad control), [`quad_description`](https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_description) (Quad model), [`quad_3dnav`](https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_3dnav) (3D nav), [`quad_gazebo`](https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_gazebo) (Quad Gazebo)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Model"]
  node_quad_description["Quad model<br/>robot description package"]
  node_quad_description_urdf["URDF/Xacro<br/>robot model files"]
  node_quad_description_sensors["Sensors<br/>sensor macros"]
  node_quad_description_meshes["Meshes<br/>visual assets"]
  node_quad_description_maps["Map params<br/>navigation params"]
end

subgraph group_g2["Simulation"]
  node_quad_gazebo["Quad Gazebo<br/>simulation package"]
  node_quad_gazebo_worlds["Worlds"]
  node_quad_gazebo_spawn["Spawn launch"]
  node_quad_gazebo_world_launch["World launch<br/>world composition<br/>[quad_world.launch]"]
end

subgraph group_g3["Control"]
  node_quad_control["Quad control<br/>flight control package"]
  node_quad_control_lib["Controller lib<br/>control library"]
  node_quad_attitude_node["Attitude node<br/>ROS node"]
  node_quad_position_node["Position node<br/>ROS node"]
  node_quad_waypoint_node["Waypoint node<br/>ROS node"]
  node_quad_waypoints["Waypoint files<br/>mission resources"]
end

subgraph group_g4["Input"]
  node_quad_joystick_interface["Joystick interface<br/>input package"]
  node_quad_joy["Joy bridge<br/>joystick node<br/>[joy.cpp]"]
end

subgraph group_g5["2D Nav"]
  node_quad_2dnav["2D nav<br/>navigation package"]
  node_quad_2dnav_launch["Nav launch<br/>navigation launch"]
  node_quad_2dnav_maps["Nav maps<br/>map assets"]
end

subgraph group_g6["3D Nav"]
  node_quad_3dnav["3D nav<br/>MoveIt package"]
  node_quad_3dnav_config["MoveIt config<br/>planning config"]
  node_quad_3dnav_launch["MoveIt launch<br/>planning launch"]
  node_quad_warehouse[("Warehouse DB<br/>planning storage")]
end

subgraph group_g7["MoveIt Bridge"]
  node_action_controller["Action controller<br/>MoveIt action bridge"]
  node_action_controller_action["MDof action<br/>ROS action"]
  node_moveit_simple_controller_manager["Controller mgr<br/>MoveIt plugin"]
  node_moveit_handles["Controller handles<br/>plugin handles"]
end

node_quad_description -->|"defines"| node_quad_description_urdf
node_quad_description -->|"exposes"| node_quad_description_sensors
node_quad_description -->|"includes"| node_quad_description_meshes
node_quad_description -->|"ships"| node_quad_description_maps
node_quad_description -.->|"binds into"| node_quad_gazebo
node_quad_gazebo -->|"runs in"| node_quad_gazebo_worlds
node_quad_gazebo -->|"spawns"| node_quad_gazebo_spawn
node_quad_gazebo -->|"composes"| node_quad_gazebo_world_launch
node_quad_gazebo -.->|"hosts"| node_quad_control
node_quad_control -->|"shared logic"| node_quad_control_lib
node_quad_control -->|"executes"| node_quad_attitude_node
node_quad_control -->|"executes"| node_quad_position_node
node_quad_control -->|"executes"| node_quad_waypoint_node
node_quad_waypoint_node -->|"reads"| node_quad_waypoints
node_quad_joystick_interface -->|"runs"| node_quad_joy
node_quad_joy -->|"commands"| node_quad_control
node_quad_2dnav -->|"launches"| node_quad_2dnav_launch
node_quad_2dnav -->|"uses"| node_quad_2dnav_maps
node_quad_2dnav -.->|"outputs"| node_quad_control
node_quad_3dnav -->|"configures"| node_quad_3dnav_config
node_quad_3dnav -->|"orchestrates"| node_quad_3dnav_launch
node_quad_3dnav -.->|"persists"| node_quad_warehouse
node_quad_3dnav -.->|"bridged by"| node_action_controller
node_quad_3dnav -.->|"bridged by"| node_moveit_simple_controller_manager
node_action_controller -->|"defines"| node_action_controller_action
node_action_controller -.->|"drives"| node_quad_control
node_moveit_simple_controller_manager -->|"implements"| node_moveit_handles
node_moveit_simple_controller_manager -.->|"targets"| node_quad_control

click node_quad_description "https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_description"
click node_quad_description_urdf "https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_description/urdf"
click node_quad_description_sensors "https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_description/urdf/sensors"
click node_quad_description_meshes "https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_description/meshes"
click node_quad_description_maps "https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_description/maps"
click node_quad_gazebo "https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_gazebo"
click node_quad_gazebo_worlds "https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_gazebo/worlds"
click node_quad_gazebo_spawn "https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_gazebo/launch/spawn"
click node_quad_gazebo_world_launch "https://github.com/wilselby/ros_quadrotor_simulator/blob/master/quad_gazebo/launch/quad_world.launch"
click node_quad_control "https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_control"
click node_quad_control_lib "https://github.com/wilselby/ros_quadrotor_simulator/blob/master/quad_control/src/library/quad_controller.cpp"
click node_quad_attitude_node "https://github.com/wilselby/ros_quadrotor_simulator/blob/master/quad_control/src/nodes/attitude_controller_node.cpp"
click node_quad_position_node "https://github.com/wilselby/ros_quadrotor_simulator/blob/master/quad_control/src/nodes/position_controller_node.cpp"
click node_quad_waypoint_node "https://github.com/wilselby/ros_quadrotor_simulator/blob/master/quad_control/src/nodes/waypoint_publisher_node.cpp"
click node_quad_waypoints "https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_control/resource"
click node_quad_joystick_interface "https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_joystick_interface"
click node_quad_joy "https://github.com/wilselby/ros_quadrotor_simulator/blob/master/quad_joystick_interface/src/joy.cpp"
click node_quad_2dnav "https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_2dnav"
click node_quad_2dnav_launch "https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_2dnav/launch"
click node_quad_2dnav_maps "https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_2dnav/maps"
click node_quad_3dnav "https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_3dnav"
click node_quad_3dnav_config "https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_3dnav/config"
click node_quad_3dnav_launch "https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_3dnav/launch"
click node_quad_warehouse "https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_3dnav/default_warehouse_mongo_db"
click node_action_controller "https://github.com/wilselby/ros_quadrotor_simulator/tree/master/action_controller"
click node_action_controller_action "https://github.com/wilselby/ros_quadrotor_simulator/blob/master/action_controller/action/MultiDofFollowJointTrajectory.action"
click node_moveit_simple_controller_manager "https://github.com/wilselby/ros_quadrotor_simulator/tree/master/moveit_simple_controller_manager"
click node_moveit_handles "https://github.com/wilselby/ros_quadrotor_simulator/tree/master/moveit_simple_controller_manager/include/moveit_simple_controller_manager"

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_quad_description,node_quad_description_urdf,node_quad_description_sensors,node_quad_description_meshes,node_quad_description_maps,node_action_controller,node_action_controller_action,node_moveit_simple_controller_manager,node_moveit_handles toneBlue
class node_quad_gazebo,node_quad_gazebo_worlds,node_quad_gazebo_spawn,node_quad_gazebo_world_launch toneAmber
class node_quad_control,node_quad_control_lib,node_quad_attitude_node,node_quad_position_node,node_quad_waypoint_node,node_quad_waypoints toneMint
class node_quad_joystick_interface,node_quad_joy toneRose
class node_quad_2dnav,node_quad_2dnav_launch,node_quad_2dnav_maps toneIndigo
class node_quad_3dnav,node_quad_3dnav_config,node_quad_3dnav_launch,node_quad_warehouse toneTeal
```

## Components

### Model

Robot description, sensors, and planning assets

- [Quad model](https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_description): robot description package · URDF/Xacro, meshes, sensor macros, RViz, and planning map params · `quad_description`
- [URDF/Xacro](https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_description/urdf): robot model files · Base multirotor structure and sensor/attachment composition · `quad_description/urdf`
- [Sensors](https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_description/urdf/sensors): sensor macros · Camera, sonar, and static sensor Xacro definitions · `quad_description/urdf/sensors`
- [Meshes](https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_description/meshes): visual assets · Drone and sensor geometry used by URDF and RViz · `quad_description/meshes`
- [Map params](https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_description/maps): navigation params · Costmap and base planner YAML plus map assets · `quad_description/maps`

### Simulation

Gazebo worlds, spawn, and runtime launch composition

- [Quad Gazebo](https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_gazebo): simulation package · Gazebo worlds and launch files for spawning and running the quadrotor · `quad_gazebo`
- [Worlds](https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_gazebo/worlds): gazebo worlds · Empty, kitchen, outdoor, Willow Garage, and test scenes · `quad_gazebo/worlds`
- [Spawn launch](https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_gazebo/launch/spawn): spawn launch set · Launches that place the quadrotor and sensors into worlds · `quad_gazebo/launch/spawn`
- [World launch](https://github.com/wilselby/ros_quadrotor_simulator/blob/master/quad_gazebo/launch/quad_world.launch): world composition · Top-level launch composition for simulator runtime · `quad_gazebo/launch/quad_world.launch`

### Control

Flight controllers and waypoint mission publisher

- [Quad control](https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_control): flight control package · Reusable controller library plus attitude, position, and waypoint nodes · `quad_control`
- [Controller lib](https://github.com/wilselby/ros_quadrotor_simulator/blob/master/quad_control/src/library/quad_controller.cpp): control library · Shared quadrotor control logic used by node executables · `quad_control/src/library/quad_controller.cpp`
- [Attitude node](https://github.com/wilselby/ros_quadrotor_simulator/blob/master/quad_control/src/nodes/attitude_controller_node.cpp): ROS node · Converts high-level attitude commands into thrust/attitude control outputs · `quad_control/src/nodes/attitude_controller_node.cpp`
- [Position node](https://github.com/wilselby/ros_quadrotor_simulator/blob/master/quad_control/src/nodes/position_controller_node.cpp): ROS node · Tracks position-level commands and produces vehicle control signals · `quad_control/src/nodes/position_controller_node.cpp`
- [Waypoint node](https://github.com/wilselby/ros_quadrotor_simulator/blob/master/quad_control/src/nodes/waypoint_publisher_node.cpp): ROS node · Reads mission text files and publishes timed waypoint sequences · `quad_control/src/nodes/waypoint_publisher_node.cpp`
- [Waypoint files](https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_control/resource): mission resources · Preauthored [x,y,z,yaw] mission routes for kitchen and Willow Garage · `quad_control/resource`

### Input

Manual joystick boundary into ROS

- [Joystick interface](https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_joystick_interface): input package · ROS joystick wrapper that maps Xbox input into controller commands · `quad_joystick_interface`
- [Joy bridge](https://github.com/wilselby/ros_quadrotor_simulator/blob/master/quad_joystick_interface/src/joy.cpp): joystick node · Consumes joystick input and emits control-mode messages · `quad_joystick_interface/src/joy.cpp`

### 2D Nav

Map-based localization and navigation stack

- [2D nav](https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_2dnav): navigation package · AMCL, map server inputs, and navigation stack parameters for planar autonomy · `quad_2dnav`
- [Nav launch](https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_2dnav/launch): navigation launch · Launch compositions for AMCL and navigation scenarios · `quad_2dnav/launch`
- [Nav maps](https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_2dnav/maps): map assets · Occupancy maps and local/global planner parameter files · `quad_2dnav/maps`

### 3D Nav

MoveIt planning, execution, and persistence

- [3D nav](https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_3dnav): MoveIt package · MoveIt configuration and launch stack for 3D planning and execution · `quad_3dnav`
- [MoveIt config](https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_3dnav/config): planning config · SRDF, kinematics, OMPL, controller, and sensor YAMLs · `quad_3dnav/config`
- [MoveIt launch](https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_3dnav/launch): planning launch · Move group, trajectory execution, sensor manager, and warehouse launches · `quad_3dnav/launch`
- [Warehouse DB](https://github.com/wilselby/ros_quadrotor_simulator/tree/master/quad_3dnav/default_warehouse_mongo_db): planning storage · MongoDB-backed storage for planning data and configurations · `quad_3dnav/default_warehouse_mongo_db`

### MoveIt Bridge

Custom controller integration for quadrotor execution

- [Action controller](https://github.com/wilselby/ros_quadrotor_simulator/tree/master/action_controller): MoveIt action bridge · Custom MultiDofFollowJointTrajectory action translating trajectories to velocity commands · `action_controller`
- [MDof action](https://github.com/wilselby/ros_quadrotor_simulator/blob/master/action_controller/action/MultiDofFollowJointTrajectory.action): ROS action · Custom multi-DOF follow-joint-trajectory interface · `action_controller/action/MultiDofFollowJointTrajectory.action`
- [Controller mgr](https://github.com/wilselby/ros_quadrotor_simulator/tree/master/moveit_simple_controller_manager): MoveIt plugin · Custom controller manager plugin and handles for quadrotor execution · `moveit_simple_controller_manager`
- [Controller handles](https://github.com/wilselby/ros_quadrotor_simulator/tree/master/moveit_simple_controller_manager/include/moveit_simple_controller_manager): plugin handles · Action-based, follow-joint, gripper, and multi-DOF controller handles · `moveit_simple_controller_manager/include/moveit_simple_controller_manager`

## Connections

- Quad model → URDF/Xacro: defines · Robot structure and composition
- Quad model → Sensors: exposes · Sensor and attachment macros
- Quad model → Meshes: includes · Geometry assets for visualization and simulation
- Quad model → Map params: ships · Navigation and planner parameters
- Quad model → Quad Gazebo: binds into · Robot model used by simulation runtime
- Quad Gazebo → Worlds: runs in · Simulation environments
- Quad Gazebo → Spawn launch: spawns · Launches that insert quadrotor into worlds
- Quad Gazebo → World launch: composes · Top-level simulator launch
- Quad Gazebo → Quad control: hosts · Control stack drives the simulated vehicle
- Quad control → Controller lib: shared logic · Reusable controller code
- Quad control → Attitude node: executes · Attitude-level control node
- Quad control → Position node: executes · Position-level control node
- Quad control → Waypoint node: executes · Waypoint mission publisher node
- Waypoint node → Waypoint files: reads · Text mission files
- Joystick interface → Joy bridge: runs · Joystick-to-ROS input bridge
- Joy bridge → Quad control: commands · Manual mode and control inputs feed flight controllers
- 2D nav → Nav launch: launches · AMCL and navigation compositions
- 2D nav → Nav maps: uses · Maps and planner parameters
- 2D nav → Quad control: outputs · Navigation-generated motion commands to the vehicle controller
- 3D nav → MoveIt config: configures · MoveIt planning and controller behavior
- 3D nav → MoveIt launch: orchestrates · MoveIt runtime launch set
- 3D nav → Warehouse DB: persists · Optional planning data storage
- 3D nav → Action controller: bridged by · Execution path for multi-DOF trajectories
- 3D nav → Controller mgr: bridged by · Custom controller-manager plugin
- Action controller → MDof action: defines · Custom trajectory action interface
- Action controller → Quad control: drives · Converts trajectories into quad velocity commands
- Controller mgr → Controller handles: implements · Controller handle classes for MoveIt
- Controller mgr → Quad control: targets · Makes the quadrotor look like a controllable multi-DOF platform
