How wilselby/ros_quadrotor_simulator works
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 Quad control · quad_description Quad model · quad_3dnav 3D nav · quad_gazebo Quad Gazebo
Components 28
Model
Robot description, sensors, and planning assets
- Quad model · URDF/Xacro, meshes, sensor macros, RViz, and planning map params
quad_description - URDF/Xacro · Base multirotor structure and sensor/attachment composition
quad_description/urdf - Sensors · Camera, sonar, and static sensor Xacro definitions
quad_description/urdf/sensors - Meshes · Drone and sensor geometry used by URDF and RViz
quad_description/meshes - Map params · Costmap and base planner YAML plus map assets
quad_description/maps
Simulation
Gazebo worlds, spawn, and runtime launch composition
- Quad Gazebo · Gazebo worlds and launch files for spawning and running the quadrotor
quad_gazebo - Worlds · Empty, kitchen, outdoor, Willow Garage, and test scenes
quad_gazebo/worlds - Spawn launch · Launches that place the quadrotor and sensors into worlds
quad_gazebo/launch/spawn - World launch · Top-level launch composition for simulator runtime
quad_gazebo/launch/quad_world.launch
Control
Flight controllers and waypoint mission publisher
- Quad control · Reusable controller library plus attitude, position, and waypoint nodes
quad_control - Controller lib · Shared quadrotor control logic used by node executables
quad_control/src/library/quad_controller.cpp - Attitude node · Converts high-level attitude commands into thrust/attitude control outputs
quad_control/src/nodes/attitude_controller_node.cpp - Position node · Tracks position-level commands and produces vehicle control signals
quad_control/src/nodes/position_controller_node.cpp - Waypoint node · Reads mission text files and publishes timed waypoint sequences
quad_control/src/nodes/waypoint_publisher_node.cpp - Waypoint files · Preauthored [x,y,z,yaw] mission routes for kitchen and Willow Garage
quad_control/resource
Input
Manual joystick boundary into ROS
- Joystick interface · ROS joystick wrapper that maps Xbox input into controller commands
quad_joystick_interface - Joy bridge · Consumes joystick input and emits control-mode messages
quad_joystick_interface/src/joy.cpp
2D Nav
Map-based localization and navigation stack
- 2D nav · AMCL, map server inputs, and navigation stack parameters for planar autonomy
quad_2dnav - Nav launch · Launch compositions for AMCL and navigation scenarios
quad_2dnav/launch - Nav maps · Occupancy maps and local/global planner parameter files
quad_2dnav/maps
3D Nav
MoveIt planning, execution, and persistence
- 3D nav · MoveIt configuration and launch stack for 3D planning and execution
quad_3dnav - MoveIt config · SRDF, kinematics, OMPL, controller, and sensor YAMLs
quad_3dnav/config - MoveIt launch · Move group, trajectory execution, sensor manager, and warehouse launches
quad_3dnav/launch - Warehouse DB · MongoDB-backed storage for planning data and configurations
quad_3dnav/default_warehouse_mongo_db
MoveIt Bridge
Custom controller integration for quadrotor execution
- Action controller · Custom MultiDofFollowJointTrajectory action translating trajectories to velocity commands
action_controller - MDof action · Custom multi-DOF follow-joint-trajectory interface
action_controller/action/MultiDofFollowJointTrajectory.action - Controller mgr · Custom controller manager plugin and handles for quadrotor execution
moveit_simple_controller_manager - Controller handles · Action-based, follow-joint, gripper, and multi-DOF controller handles
moveit_simple_controller_manager/include/moveit_simple_controller_manager
Connections 28
- 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