DFKI Quadruped

This repo contains the quadruped controller used at DFKI’s underactuated lab. It mainly contains a simulation, dynamic walking controller using MPC, WBC and different Gait Sequencers and hardware drivers to be used with different quadrupeds.

• To install the whole software stack please refer to Installation
• To run the simulated experiments from our paper Benchmarking Different QP Formulations and Solvers for Dynamic Quadrupedal Walking please refer to section Run the solver comparison experiments
• To run the controller in simulation or on your own hardware (EXPERIMENTAL), pleae refer to Run the software stack

Authors

• Shubham Vyas (Project Leader)
• Rohit Kumar (Project Leader)
• Franek Stark (Software Maintainer)
• Hannah Isermann
• Jakob Middelberg
• Jonas Haack
• Mihaela Popescu
• Lasse Shala

Citation

If you use this code in your scientific work, please cite our paper:

@misc{stark_benchmarking_2025,
title = {Benchmarking {Different} {QP} {Formulations} and {Solvers} for {Dynamic} {Quadrupedal} {Walking}},
url = {http://arxiv.org/abs/2502.01329},
doi = {10.48550/arXiv.2502.01329},
author = {Stark, Franek and Middelberg, Jakob and Mronga, Dennis and Vyas, Shubham and Kirchner, Frank},
month = feb,
year = {2025},
note = {Accepted for the International Conference on Robotics and Automation (ICRA) 2025},
}

Acknowledgements

This work has been performed in the AAPLE project funded by the German Federal Ministry for Economic Affairs and Climate Action (BMWK) (Grant Number: 50WK2275). And it is additionally supported by the M-RoCK project funded by the German Aerospace Center (DLR) with federal funds (Grant Number: FKZ 01IW21002) from the Federal Ministry of Education and Research (BMBF). Further, it is additionally supported with project funds from the federal state of Bremen for setting up the Underactuated Robotics Lab (Grant Number: 201-001-10-3/2023-3-2).

Contributing

Please use the issue tracker, to submit bug reports and feature requests. lease use merge requests as described here to add/adapt functionality.

Requirements / Dependencies

• The requirements are all external and will be automatically installed when using the docker image, a full list can be found under DEPENDENCIES.

Installation

1. Build the docker image:

• If you want to build the image yourself, use the build_new_image.sh script.

    ./build_new_image.sh
    

> **Note:** If you already started a container before and saved important data to it, make a backup, since this script will delete all previously created containers with the "dfki_quad" label.

2. Starting and accessing containers

• You can start a new container by executing the run_docker.sh script.

    ./run_docker.sh
    

• If you need more than one terminal, you can use the new_docker_shell.sh script. This will launch a new shell for the already running container.

    ./new_docker_shell.sh
    

• Connected gampads will automatically be accessible from within the container. If not, simply rerun the run_docker.sh script. Currently, most scripts support Logitech F310 type gamepads. For other gamepads (e.g. xbox360) axes mapping might be different.

  Note: If you want to create a new container (e.g. for rebuiling the software stack), you can use the reset_docker_container.sh script. This will delete all current containers with the “dfki_quad” label. After that, you can proceed with the run_docker.sh script, which will create a new container for you.

3. Building the software stack

• Inside the container, build the packages and run a simulation by running the following commands.

  Note: The --symlink-install option enables you to change yaml and python files without rebuilding. If you want to use it, you have to use it consistently, as it cannot overwrite compilations without this option. Use $ rm -r build/ install/ log/ to remove former compilations if you want to compile with this option the first time.

  a) For the ulab quad:

     colcon build --symlink-install --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDS=1 -DROBOT_NAME=ulab
     source install/setup.bash
     source ~/setup_ulab_workspace.bash
     

b) For the unitree quad:

     colcon build --symlink-install --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDS=1 -DROBOT_NAME=go2
     source install/setup.bash
     source ~/setup_go2_workspace.bash
     

> **Note:** The unitree software stack requires cyclone dds, which will be setup by the last command. This means that your network interface need to be configured in this script. If you just want to use the simulation, independent from the build command, please just source `setup_ulab_workspace.bash`.

Run the solver comparison experiments

If you want to repoduce the results from Benchmarking Different QP Formulations and Solvers for Dynamic Quadrupedal Walking follow the following instruction:

Note: If you just want to recreate the plots, you can use our Dataset and jump directly to step (5).

1. Installation

• If not yet done, build the docker image and install the software stack using the GO2 quadruped option:

    https://github.com/dfki-ric-underactuated-lab/dfki-quad
    cd dfki-quad
    ./build_new_image.sh
    ./run_docker.sh
    cbg # This is a shorthand to build the software stack using the -DROBOT_NAME=go2 option
    sr # This is a shorthand to ~/setup_ulab_workspace.bash, which is nececarry since the simulation is used and not a real system
    

Note: If you want to run the simulation and the controller on two different machines, like in the paper, the installation has to be done on both.

2. Simulation Machine: Start the simulation

• On the machine that should run the simulation run the container and start the simulation

    sr # This sources the ros environment for the simulation
    export ROS_DOMAIN_ID=123 # Make sure both machines run on the same ROS 2 Domain ID
    ros2 launch simulator simulator.launch.py sim:=go2 
    

• Visualization will be rendered (if configured) and can be seen in the browser (URL will be shown in the terminal, often localhost:7000).

3. Target computer: Run the experiments

• Run the automatic script which runs the set of experiments from the simulation automatically for both prediction horizons:

    # Outside of docker run:
    ./automatic_solver_experiments.sh <pc_name> <test_preset> 123 main 20 N10_prediction_horizon 10
    
    # <pc_name> specfies the name of the target computer which is used to label the experiments (in the paper this was out of [arm_orin, desktop_pc, latte_panda])

    # <test_preset> specifies which test preset should be run for the paper this is both [mpc, wbc]

    # 123 is the ROS_DOMAIN_ID on which the simulation runs

    # main 20 is the branch and the corresponding prediction horizon on that branch
    # N10_prediction_horizon 10 is the branch and the corresponding prediction horizon on that branch
    

> **Note:** The test script will spin a docker container, build the project and run all experiments (i.e. combinations of MPC solvers, WBC solvers, condensing levels, etc.). For each experiment it first runs the standing and then the trot scenario.
If a single experiment fails (*the terminal might show errors etc.*), the script will after a while automatically restart the experiment and mark the old one as failed, it will repeat this as often as specified above.
The full script might take depending on your system at least one hour. Please wait until the script tells you that it is finished.

• The automatic script saves the experiment sets to folders under ws/src/solver_experiments/The folders are named automatically in the following way, such that it can be later imported into the plotting script: <target_platform>-N<precition_horizon>-<experiment_name_tag>
  • <target_platform> indicates on which target computer the controller was executed, e.g. arm_orin.
  • <prediciton_horizon> indicates whith which MPC prediction horizon the experiments were executed, e.g. 10.
  • <experiment_name_tag> contains the test preset and a timestamp
• Optional If you with to run your own set of experiments you can change the underlying python script which is runned by the automatic_solver_experiments.sh:
  • The experiments are run from the script ws/src/solver_experiments/solver_experiments/solver_experiments.py
  • The experimemts can be configured the following way:
    • Line 626 sets which MPC solvers are included in the tests
    • Line 637 sets which condensed levels are tested for MPC solvers with a sparse interface
    • Line 633 sets which modes are included into the tests for the HPIPM MPC solver
    • Line 638 sets which WBC solvers are included in the tests
    • Line 639 sets which WBC scenes/formulations are included in the tests
    • Line 645 sets how often an experiment is repeated until it is considered as ‘failed’
    • Line 634 sets which OSQP backends are included in the tests
    • Line 640 sets which solver tolerances are included in the tests
    • Lines 649ff define the test presets as used by the automatic experiment script

5. Generate the plots

• Assuming all different experiment result folders (named in the scheme defined above) containing the single experiments have been moved to one empty root folder, the plots can be generated.
• The jupyter notebook ws/src/solver_experiments/evaluation_scripts/comparison_paper.ipynb defines at the beginning in the variable result_path the location of that root folder:

    sr # shorthand to source the types needed to load the ros bags
    jupyter notebook --allow-root src/solver_experiments/evaluaion_scripts/comparison_paper.ipynb
    

> **Note:** It is recommended to run the python scripts and Jupyter notebook from the docker image as all dependencies are installed there. * After the location has been set, run the script and the plots are being generated. This might take a while.

Run the software stack

You can run the software stack using the simulation or using a real hardware (for example the Unitree GO2 in the education version). Currently simulation supports either the GO2 or the dfki in house quadruped.

Following components have to be launched to run the software stack:

• Hardware driver or Simulation
• Leg Driver
• Dynamic walking controller
• When on the real system: State estimation

Please find instructions for all components below.

Note: Almost all commands in this section need to run in seperate terminals.

Robot selection

• When running a launch file, the used robot and whether it is on the real system or in simulation has to be specified. For this, it is required to set either the parameter sim or the parameter real to ulab for the dfki dog or to go2 for the unitree. For this, you have to append either sim:=ulab, sim:=go2, real:=ulab or real:=go2 to the launch commands. Eg. for the MPC controller:

    ros2 launch controllers mit_controller.launch.py sim:=ulab
    # or
    ros2 launch controllers mit_controller.launch.py real:=go2
    # ...
    

Running the Simulation

• In order to run the simulation, start the simulation node:

    ros2 launch simulator simulator.launch.py sim:=go2   # or sim:=ulab
    

• All parameters can be set in the src/simulator/config/simulator_params_*.yaml file (there is one configuration file per robot). The parameter visualisation specifies if the simulator also shows a Meshcat visualisation.

• Visualization will be rendered (if configured) and can be seen in the browser (URL will be shown in the terminal, often localhost:7000) #### Simulation clock The simulator can run faster or slower than realtime. This can be specified via the parameter simulator_realtime_rate in the config file. A value of 0.0 means that the simulator will run as fast as possible. Note that also for other values (1.0 refers to realtime, 0.5 to half of realtime, 2.0 to double of realtime) this is only an upper bound, meaning that the simulator might run slower.

• In order to synchronize the rest of the software stack the simulator publishes the simulation time on the ` /clock topic (following the ROS 2 convention). **To synchronize other nodes, instead of following the computer time (in ROS also known as wall time), they have to listen to this clock topic.** This can be archived by setting the use_sim_time parameter to True` when launching the respective node. This parameter is automatically set to correctly when using the provided launch files.

  Note on developing nodes that use a timer or follow a clock:
  Depending on the use_sim_time the call node->get_clock() will return a clock that follows the system’s time (wall time) or the /clock topic. To create a timer based on this setting use the following call: rclcpp::create_timer(node, node->get_clock(),...) Using the call node->create_wall_timer(...) will create a timer that follows the system time, ignoring the use_sim_time setting.
  It is very important to consider for each timer if it should follow the simulation or real-time during simulation! Making the wrong decision may result in undesired behaviour during simulation.

  #### Reset simulation

• The simulation offers a service /reset_sim of type ResetSimulation.srv which will reset the simulation and place the robot to a requested pose. This call might take a few seconds. The joint positions and PID gains will be set to the original initial value. It returns on a successful reset.

    ros2 service call /reset_sim interfaces/srv/ResetSimulation "{pose: {position: {z: 0.4}, orientation: {w: 1.0, x: 0, y: 0,  z: 0.0}}, joint_positions: [-0.03287414616578515, 0.7382670992579555, -1.6656333683908857, 0.022376335027853064, 0.7301659339175386, -1.6657410165323536, -0.03343962015375848, 0.7507916433141004, -1.6985474687285194, 0.02383046084651509, 0.7426327340796195, -1.6989789512741746]}"
    

#### Manual step the simulation * Normally the simulation starts and runs with a target frequency as specified by the parameter `simulator_realtime_rate`. In order to step the simulation manually the parameter `manually_step_sim` in the simulator's config file has to be set to `true`. The simulator then provides a service `/step_sim` of type [StepSimulation.srv](ws/src/interfaces/srv/StepSimulation.srv) which will advance the simulation by the amount of seconds specified in the request.

    ros2 service call /step_sim interfaces/srv/StepSimulation dt:\ 10.0\ 

    

Running the real Hardware

Disclaimer: This is research code, this code can destroy your hardware or harm yourself!
———————— USE THIS SOFTWARE ON YOUR OWN RISK —————————-
When working with a real system be careful and mind the following safety measures:

• Brushless motors can be very powerful, moving with tremendous force and speed. Always limit the range of motion, power, force and speed using configurable parameters, current limited supplies, and mechanical design.
  • Make sure you have access to emergency stop while doing experiments.

Unitree GO2 Edu

1. Connect the target computer (that should run the controller, leg driver, hardware driver, state estimation) via ethernet to the quadruped, and make sure it is configured as described here.
2. Install build docker, install the software stack using the GO2 option, as described above.
3. On the target computer launch a shell (maybe via ssh) and start the hardware driver:

   ./run_docker # if not already done, or maybe ./new_docker_shell
    sg # This is a shorthand to source the workspace and set the correct ROS DDS, FOR THE GO2 QUAD THIS HAS TO BE DONE IN EVERY SHELL
   ros2 launch drivers unitree_ros2_motor_driver.launch.py 
   

> **Note:** The target computer could also be the additional onbaord computer of the GO2 EDU. Details on how to acces the computer can be found [here](https://www.docs.quadruped.de/projects/go2/html/go2_driver.html#go2-network-interface).

Ulab quadruped

1. Connect the robot via ethernet to your computer.

2. Connect to robot via ssh:

    ssh ubuntu@10.0.0.20
    

password: ulab-dfki

1. Set date on robot:

   from a new terminal

   ssh ubuntu@10.0.0.20 "sudo date -s '$(date +"%Y-%m-%d %H:%M:%S")'"
   

1. source repo:

   ws
   

this is a shortcut for cd dfki-quad-ros2/ws && source .install/setup.bash

1. rezero legs: attach the 3d printed parts to the robot legs to bring them in streched out pose and use

   sh ~/dfki-quad-ros2/ws/src/drivers/scripts/zero_fl_leg.sh
   sh ~/dfki-quad-ros2/ws/src/drivers/scripts/zero_fr_leg.sh
   sh ~/dfki-quad-ros2/ws/src/drivers/scripts/zero_bl_leg.sh
   sh ~/dfki-quad-ros2/ws/src/drivers/scripts/zero_br_leg.sh
   

on the quadruped or

   sh ~/dfki-quad-ros2/ws/src/drivers/scripts/zero_single_leg.sh
   

on the single leg robot.

1. launch motor driver:

   ros2 launch drivers mjbots_ros2_motor_driver.launch.py
   

to change the parameters like the control frequency adapt the file src/drivers/config/mjbots_test_params.yaml.

1. stop motor driver with ctrl-c. In case the motors don’t stop you can use

   . src/drivers/scripts/shutdown.sh
   

and/or

   sudo killall  mjbots_ros2_motor_driver
   

**Troubleshooting**    - *interfaces* does not compile:

 deactivate pyenv using:

     pyenv deactivate
     

State estimation

• Start the state estimation with:

    # select robot with sim:=ulab, sim:=go2, real:=ulab or real:=go2
    ros2 launch state_estimation state_estimation.launch.py sim:=go2
    

Leg driver

• Start the leg driver with:

    # select robot with sim:=ulab, sim:=go2, real:=ulab or real:=go2
    ros2 launch drivers leg_driver_launch.py sim:=go2
    

Dynamic walking controller

• First make sure the robot is standing, this can be archived by:

    # select robot with sim:=ulab, sim:=go2, real:=ulab or real:=go2
    ros2 launch controllers quad_stand_up.launch.py sim:=go2
    

• Then launch the controller (it will also launch the gamepad driver)

    # select robot with sim:=ulab, sim:=go2, real:=ulab or real:=go2
    ros2 launch controllers mit_controller.launch.py sim:=go2
    

• This command will start the safe launch, which waits for a state message (coming from the simulation or state estimation) and makes sure that the state estimation is not drifting

Contributing to dfki-quad

Please inform the maintainer as early as possible about your planned feature developments, extensions, or bugfixes that you are working on. An easy way is to open an issue or a pull request in which you explain what you are trying to do.

Pull Requests

The preferred way to contribute to is to fork the [main repository](https://github.com/dfki-ric-underactuated-lab/dfki-quad) on GitHub, then submit a "pull request" (PR):

1. Create an account on GitHub if you do not already have one.

2. Fork the project repository: click on the ‘Fork’ button near the top of the page. This creates a copy of the code under your account on the GitHub server.

3. Clone this copy to your local disk:

    $ git clone git@github.com:YourLogin/dfki-ric-underactuated-lab/dfki-quad.git
   

4. Create a branch to hold your changes:

    $ git checkout -b my-feature
   

   and start making changes. Never work in the master branch!

5. Work on this copy, on your computer, using Git to do the version control. When you’re done editing, do::

    $ git add modified_files
    $ git commit
   

   to record your changes in Git, then push them to GitHub with::

   $ git push -u origin my-feature
   

Finally, go to the web page of the your fork of the bolero repo, and click ‘Pull request’ to send your changes to the maintainers for review. request.

Merge Policy

                pull request + 1 reviewer for everything else)

Usually it is not possible to push directly to the master branch of Software Name for anyone. Only tiny changes, urgent bugfixes, and maintenance commits can be pushed directly to the master branch by the maintainer without a review. “Tiny” means backwards compatibility is mandatory and all tests must succeed. No new feature must be added.

Developers have to submit pull requests. Those will be reviewed by at least one other developer and merged by the maintainer. New features must be documented and tested. Breaking changes must be discussed and announced in advance with deprecation warnings.