Quad-SDK: a full stack framework for agile quadrupeds

Quad-SDK vertically integrates the whole legged robot stack

Quad-SDK is an open source, ROS based full stack software framework for agile quadrupedal locomotion, developed by the Robomechanics Lab at Carnegie Mellon University. The design goal stated in the README is vertical integration of planning, control, estimation, communication and development tools, so that agile locomotion works in simulation and on hardware with minimal changes between platforms.

That verticality is the whole argument. Most robotics stacks are assembled from separate pieces, and the interface friction between a planner, a controller and a state estimator is where a lot of research time disappears. By owning the seams, Quad-SDK lets a lab swap one component without rewriting the others. The README describes the modular architecture as allowing researchers to experiment with their own implementations of different components while leveraging the existing framework, and the keyword list of legged robotics, quadrupeds, planning, control, leaping and ROS makes the intended research domain clear.

The scope includes the parts a locomotion stack needs beyond algorithms. There is Gazebo simulation support, a suite of visualization and data processing tools for rapid development, and a quad_logger package for recording runs. The 2023 update entry adds an Extended Kalman Filter for onboard state estimation and a controller for walking through entanglements, described as letting the robot disentangle itself from vine-like obstructions.

The audience is academic robotics groups, and the reference to the ICRA Workshop on Legged Robots publication makes the setting explicit.

The repository top level is a map of the locomotion pipeline

The directory listing of the repository reads like a data flow diagram. Each package owns one stage of the problem.

global_body_planner/ and local_planner/ hold the two planning layers, nmpc_controller/ holds the nonlinear model predictive controller, robot_driver/ holds the interface down to the robot hardware, quad_simulator/ holds the simulation side, quad_msgs/ holds the message definitions, quad_utils/ holds shared utilities and launch files, and quad_logger/ handles logging. external/ is where third party dependencies are vendored, scripts/ holds helper scripts, and doc/ holds documentation assets along with a Doxyfile at the root, so the code is set up for Doxygen output.

The split tells you something about the framework's opinion. Planning is not one thing but two, a global body planner and a local planner, which matches the separation of concerns in legged locomotion where a global plan is computed in the world frame and a local planner produces motions the controller can track. The controller is NMPC based, which means the receding horizon optimisation runs on board and its cost is the thing that determines how fast the loop can run.

The message package is the contract. quad_msgs/ is where the interfaces between these stages are declared, and it is the first place to look when you intend to replace a planner or a controller, because a custom component has to speak the same messages as the rest of the stack.

The CircleCI directory at the top level indicates the build is exercised automatically, and the setup.sh script at the root is the single entry point for dependencies.

Launching the Gazebo simulation and standing the robot

The quick start path in the README is a short sequence of ROS commands, and it starts with the simulator:

roslaunch quad_utils quad_gazebo.launch

That brings up the Gazebo simulation with the robot loaded. The robot then has to be put into a standing state, which the README does with a single message published on the control topic:

rostopic pub /robot_1/control/mode std_msgs/UInt8 "data: 1"

The value 1 selects the standing mode, and the topic name shows that the framework addresses the robot as robot_1, which is a convention that pays off when you bring up a second robot or work across multiple machines.

Once the robot is standing, you drive the stack. The two documented reference modes differ in what consumes the twist command. With twist input, the local planner tracks a commanded velocity:

roslaunch quad_utils quad_plan.launch reference:=twist logging:=true
rosrun teleop_twist_keyboard teleop_twist_keyboard.py cmd_vel:=/robot_1/cmd_vel

The teleop keyboard node republishes key presses onto cmd_vel, remapped so it reaches robot_1 rather than the default topic.

With the global planner instead, the same launch file is given a different reference value:

roslaunch quad_utils quad_plan.launch reference:=gbpl logging:=true

Here gbpl selects the global body planner as the reference source. The logging:=true argument is available in both modes and turns on the logging package for the run, which is how you get data out of the simulation for later analysis.

ROS Melodic and Noetic, and a branch split that follows

This is the constraint that decides whether Quad-SDK fits your machine. The packages have been tested under ROS Melodic on Ubuntu 18.04 and ROS Noetic on Ubuntu 20.04, and the README is explicit that the main branch is for ROS Melodic while the devel branch is for ROS Noetic.

Two things follow from that. First, the operating system versions are not incidental, they are the tested combinations, and Ubuntu 18.04 and 20.04 are both well past their standard support windows, which means the environment you reproduce it in is an environment you have to maintain yourself. Second, because the ROS version is tied to the branch, you are choosing between them at checkout time rather than at build time. If your lab has machines on Noetic you use the devel branch, and then you are tracking a branch that has no tagged release, since the repository publishes no GitHub releases.

Installation itself is delegated. The README points to the Quad-SDK wiki for installation, dependency and unit testing information, and states that all dependencies other than ROS itself are installed with the included setup script. The setup.sh file at the root of the repository is therefore the entry point for everything except the ROS installation itself.

For a new user this is the first thing to check, before any of the locomotion code. If you are on a current Ubuntu with a current ROS distribution, the framework as documented does not cover your environment, and the wiki is where you would find out how much of the setup script still applies.

Estimation and untangling: the state of the stack after the 2023 update

The Updates section records a Quad-SDK Update dated 10-01-2023 that added two pieces with a clear purpose. The first is an Extended Kalman Filter for reliable onboard state estimation, and the second is a controller designed for walking through entanglements, described as allowing the robot to disentangle itself from vine-like obstructions. The stated intent behind both is to enable more reliable outdoor locomotion, and the details are in an abstract hosted by the lab.

The EKF is the more consequential of the two for anyone building on the stack. Legged robots need a fused state estimate, meaning position, velocity and orientation, and the usual approach in this research area is to combine leg kinematics with an inertial measurement unit. When that fusion lives inside the framework rather than in each laboratory's own code, experiments become comparable to one another, and the estimator becomes a replaceable component like the planner.

The untangling controller is a narrower but telling addition. Getting a legged robot to work in terrain with vegetation is a different problem from walking on flat ground, and a controller that recovers from entanglement is a capability that most simulation stacks do not attempt.

What the README does not provide is a breakdown of the estimator's inputs, its tuning parameters or its convergence behaviour, and the wiki is the place the documentation continues.

Research code with a disclaimed fitness for purpose

The README states the licence plainly: the source code is released under an MIT Licence, and the LICENSE file sits at the top of the repository. MIT is permissive, with attribution and preservation of the licence text as the main conditions, and for academic code that people extend rather than redistribute, it is a reasonable choice.

The next sentence is the one that should shape your expectations. The project states that this is research code, that you should expect it to change often, and that any fitness for a particular purpose is disclaimed. That is a plain warning against treating Quad-SDK as a product dependency, and it is consistent with the absence of GitHub releases. There is no version to pin, so reproducibility has to come from committing the repository at a known commit in your own code or experiment configuration, which is a step you have to take yourself.

The authorship is also on the README. The authors listed are Joe Norby, Yanhao Yang, Ardalan Tajbakhsh, Jiming Ren, Justin K. Yim, Alexandra Stutt, Qishun Yu, Nikolai Flowers and Aaron M. Johnson, with the Robomechanics Lab at Carnegie Mellon University as the affiliation and Ardalan Tajbakhsh listed as maintainer.

For academic use the README asks that relevant publications be cited, and it lists the ICRA 2022 workshop abstract describing Quad-SDK as a full stack software framework for agile quadrupedal locomotion, plus the 2020 IROS paper on fast global motion planning for dynamic legged robots, which is the work behind the global planner package.

Where Quad-SDK is the wrong tool

There is a clear case where this framework is wrong: a team working on ROS 2 with a current Ubuntu. The tested matrix is Melodic on 18.04 and Noetic on 20.04, so the ROS 1 porting work and the operating system work both fall on you, and the setup script is written for the environments the project was tested on.

There is also a case where it is overkill, and it is worth being blunt about it. Quad-SDK is a full stack with a simulator, planners, a controller, an estimator and tooling. If your question is about one component, say a global planner for a particular gait, then adopting the whole stack to study it is the expensive path. The alternative approach is to take the specific paper and implement the algorithm yourself against your own simulator, which is more work up front and much less infrastructure to maintain afterwards.

A third mismatch is industrial deployment. The disclaimer about fitness for purpose, the absence of releases and the dependency on an external/ directory of vendored code all point to a framework built for experiments on a lab bench, not for a product fleet. Deploying it on robots that must run unattended means you own the stabilisation, the logging pipeline and the long term maintenance, because the upstream project states that it changes often.

Within research robotics, though, the framework is unusually complete for its scope, and the vertical integration argument is the reason it exists.

Editorial conclusion

Adopt Quad-SDK when you are a legged robotics researcher on ROS Melodic or Noetic who wants a working planner, controller, estimator and Gazebo simulation to swap components into, and skip it when you need ROS 2 Jazzy, a current Ubuntu, or a stable release that will not change under you, since the project states outright that it is research code that changes often. Verify three things before committing: which ROS distribution your target machine has, because the main branch targets Melodic on Ubuntu 18.04 and the devel branch targets Noetic on Ubuntu 20.04, that the setup.sh script resolves cleanly in your environment, and that the planner and controller you intend to replace match the interfaces in quad_msgs. The last push to main was on 2026-10-16 and the repository publishes no GitHub releases, so pin a commit rather than a tag.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. robomechanics/quad-sdk on GitHub