Skip to content

4. Using the Software (ROS1)

Jump to bottom
ologandavid edited this page Oct 8, 2025 · 1 revision

This page describes how to use Quad-SDK, which primarily involves using the launch files which accompany the software. We also illustrate the node and topic structure during deployment. For advances users looking to modify or extend the software, we refer to the README files located in each main package as well as the API.

Launch Files

Quad-SDK contains several high-level launch files which allow convenient access to nodes across several packages. All launch files are located in quad_utils such that each can be called with roslaunch quad_utils <launch-file>.launch.

  • quad_gazebo.launch: Launches the simulation engine and initializes the control stack. Can support multiple robots.

    • robot_type The type of robot platform. Default: spirit. See this tutorial for details on how to add a new robot type.
    • multiple_robots Specifies whether more than one robot. Default: false.
    • gui Specifies whether to load the Gazebo GUI. Default: false.
    • paused Specifies whether to pause the simulation on startup. Default: false.
    • controller The controller to execute on the robot. Default: inverse_dynamics.
    • world The world file to load (if input_type:=mesh) . Default: flat (see World Files for other options).
    • live_plot Specifies whether to launch PlotJuggler for live plotting of data. Default: false.
    • dash Specifies whether or not to launch the rqt dashboard. Default: false.
    • logging Specifies if bagfiles should begin recording. Default: false.

  • quad_plan.launch: Launches the planning stack. Can support multiple robots.

    • reference The source of the reference plan. Default: gbpl (Global Body Planner for Legged Robots)
    • multiple_robots Specifies whether more than one robot. Default: false.
    • logging Specifies if bagfiles should begin recording. Default: false.
    • twist_input The source of the twist input if reference:=twist. Default: none (other options are keyboard or joy which respectively launch teleop_twist_keyboard or teleop_twist_joy).
    • leaping Specifies if leaping should be enabled if reference:=gbpl. Default: true.
    • ac Specifies if adaptive complexity MPC should be enabled (not yet supported). Default: false.
    • robot_type The type of robot platform. Default: spirit.

  • quad_visualization.launch: Launches visualization plugins for each robot as well as the requested GUIs. Can support multiple robots.

    • robot_type The type of robot platform. Default: spirit.
    • live_plot Specifies whether to launch PlotJuggler for live plotting of data. Default: false.
    • dash Specifies whether or not to launch the rqt dashboard. Default: false.

  • remote_driver.launch: Calls the visualization and mapping scripts and starts the remote heartbeat. Useful for remotely operating robot hardware.

    • map_input_type The type of input used for generating terrain data. Default: mesh.
    • world The world file to load (if input_type:=mesh) . Default: flat (see World Files for other options).
    • live_plot Specifies whether to launch PlotJuggler for live plotting of data. Default: false.
    • dash Specifies whether or not to launch the rqt dashboard. Default: false.
    • logging Specifies if bagfiles should begin recording. Default: false.

Quad-SDK also contains several component launch files which launch pieces of the stack independently.

  • quad_spawn.launch: Spawns a single robot and initializes its stack. Called by quad_gazebo.launch.

    • robot_type The type of robot platform. Default: spirit.
    • controller The controller to execute on the robot. Default: inverse_dynamics.
    • namespace The namespace of the robot. Default: 'robot_1'.
    • init_pose The starting pose of the robot. Default: -x 0.0 -y 0.0 -z 0.5.

  • robot_driver.launch: Launches node robot_driver to initialize the control and estimation loops. Also launches mocap and logging if requested.

    • is_hardware Specifies if the stack is being executed on hardware rather than sim. Default: true.
    • controller The controller to execute on the robot. Default: inverse_dynamics.
    • logging Specifies if bagfiles should begin recording. Default: false.
    • mocap Specifies if the motion capture node should be launched. Default: true.

  • planning.launch: Launches the planning and control stack.

    • reference The source of the reference plan. Default: twist (other option is gbpl to launch the Global Body Planner for Legged Robots).
    • twist_input The source of the twist input if reference:=twist. Default: none (other options are keyboard or joy which respectively launch teleop_twist_keyboard or teleop_twist_joy).
    • namespace The namespace of the nodes for multi-robot operation. Default: robot_1.
    • robot_type The type of robot platform. Default: spirit.
    • logging Specifies if bagfiles should begin recording. Default: false.
    • leaping Specifies if leaping should be enabled if reference:=gbpl. Default: true.
    • ac Specifies if adaptive complexity MPC should be enabled (not yet supported). Default: false.

  • mapping.launch: Launches nodes terrain_map_publisher and grid_map_visualization to expose terrain data.

    • robot_type The type of robot platform. Default: spirit.
    • input_type The type of input used for generating terrain data. Default: grid.

    If input_type:=mesh, the following arguments can be used to customize the environment:

    • world The world file to load. Default: step_20cm (see World Files for other options).
    • grid_map_resolution Specifies the resolution of the mesh (in m). Default: 0.05.

  • visualization_plugins.launch: Launches the visualization plugins to map data topics into RViz-readable topics.

    • namespace The namespace of the robot for proper remapping. Default: robot_1.
    • robot_type The type of robot platform. Default: spirit.

  • mocap.launch: Launches the mocap node to receive motion capture data.

  • logging.launch: Begins recording selected topics into bags. Records two copies - one with a timestamp located in quad_logger/bags/archive and one sans timestamp in quad_logger/bags.

    • namespace The namespace of the robot to indicate which topics to record. Default: robot_1.
    • bag_name The name of the recorded bag. Default: quad_log.

Common Roslaunch Calls

Launch the simulator with RViz visualization, stand the robot up, then execute a plan while logging:

roslaunch quad_utils quad_gazebo.launch
rostopic pub /robot_1/control/mode std_msgs/UInt8 "data: 1"
roslaunch quad_utils quad_plan.launch reference:=twist logging:=true
(for twist control input) rosrun teleop_twist_keyboard teleop_twist_keyboard.py cmd_vel:=/robot_1/cmd_vel

If your computer is not that powerful, you can slow down the simulation and relax the MPC solving time constraint by:

  1. change real_time_update_rate in the .world file (eg. flat.world)
  2. change "max_wall_time" and "max_cpu_time" of nmpc_controller.cpp make it match the actual time step you have.

For Teleop Keyboard Commands:

Moving around:
   u    i    o
   j    k    l
   m    ,    .
q/z : increase/decrease max speeds by 10%
w/x : increase/decrease only linear speed by 10%
e/c : increase/decrease only angular speed by 10%
anything else : stop

World Files

All the launch files listed above default to the flat world file, but there are a number of other options, some of which are shown below. See quad_simulator for a full list of included world files, and this tutorial to learn how to create your own. Note that seamless performance on all world files is not guaranteed - some of these are aspirational environments which we invite the broader community to collaborate towards solving!

rough_40cm_huge.png flat rough_25cm gap_40cm slope_20 step_20cm

Nodes and Topics

This graphic shows a high-level summary of the Quad-SDK architecture:

Quad-SDK Architecture

The actual implementation of this architecture for two simulated robots looks like this:

Quad-SDK ROS graph

Clone this wiki locally