Skip to content

1. Getting Started with Quad SDK

Jump to bottom
dologan edited this page Apr 24, 2024 · 36 revisions

Welcome to the Quad-SDK Wiki!

Quad-SDK is designed to enable rapid deployment of autonomous agility to quadruped platforms. This Wiki provides support to new and advanced users on how to install, use, and in some cases extend the software. Numbered pages within this Wiki are meant to guide users through key features of the SDK, while remaining pages offer brief insight into other sections of the code. These pages will be continually updated as features are added - if you find anything missing or in need of correction, please request updates via the Issue Tracker.

Build

Quad-SDK uses the Catkin Tools build system, and comes with a setup script that automatically installs the required dependencies. Note: Main has been tested with Ubuntu 18.04, ROS Melodic, while Devel has been tested on Ubuntu 20.04, ROS Noetic.

Setup repo

  1. Install Ubuntu (18.04/20.04) (dual boot or VM) (help) or use a WSL setup
  2. Install ROS Melodic/Noetic (full install recommended) (help)
  3. (Required for Local Planner) Get HSL solver for IPOPT (help) (Note: For users using free license of HSL solver, there is a separate step to follow below.)
  4. Create catkin workspace (help)
  5. Setup repo
cd ~/catkin_ws
source devel/setup.bash
cd src
git clone https://github.com/robomechanics/quad-sdk.git
cd quad-sdk
git checkout devel # for melodic, checkout main, for noetic, checkout devel
cp -r /path/to/coinhsl ./external/ipopt/coinhsl # verify that quad-sdk/external/ipopt/coinhsl/ma27/ma27d.f is a valid path)
chmod +x setup.sh && ./setup.sh
cd ~/catkin_ws
catkin build
  1. (Only for users using free license of HSL solver): Go to line 208 of nmpc_controller/src/nmpc_controller.cpp and change the linear_solver setting from ma57 to ma27. Recompile the program.

Note that the main branch is the default which contains stable, tested code. Check out devel for the most up-to-date code (at your own risk).

Dependencies

In addition to the ROS standard dependencies, the following packages are installed by the setup.sh script:

Test

Always do this before pushing to any branch to confirm that tests will pass.

roslaunch quad_utils load_global_params.launch load_robot_params:=true
cd ~/catkin_ws
catkin run_tests

Extend

WSL Setup

1. Install WSL

Install WSL on your system via MicrosoftStore.

Now, open Turn Windows features on or off:

  • check Windows Subsystem for Linux

2. Set WSL 2 as your default version

Open PowerShell and paste the following command:

wsl --set-default-version 2

To check:

wsl -l -v

If the output after is:

 NAME            STATE           VERSION
* Ubuntu-20.04    Stopped         2

Then, congratulations. It was a successful step.

3. Follow through with the rest of setup repo

Continue with step 2 of setup repo to install ROS Noetic and the necessary dependencies provided through the setup.sh script.

4. Setting up ROS for Graphical Output (GUI)

Install an X Server on Windows to run simulations properly, VcXsrv (recommended).

Then, configure WSL to use it. To do so, modify .bashrc as follows:

export DISPLAY=$(awk '/nameserver / {print $2; exit}' /etc/resolv.conf 2>/dev/null):0
source ~/.bashrc

OR

Simply add export DISPLAY=$(awk '/nameserver / {print $2; exit}' /etc/resolv.conf 2>/dev/null):0 inside .bashrc file.

Finally, launch VcXsrv from the start menu. Change settings:

  • Check Multiple Windows option
  • Make sure Display Number is set from -1 to 0.
  • Uncheck Native opengl. Otherwise, applications such as rviz do not run as expected.
  • Check Disable access control. Otherwise, applications within WSL cannot access the x server.

Note: These settings might look different depending on when in the future you have downloaded VcXsrv.

Warning: Everytime you re-start your PC, you need to check and un-check the options again (mentioned above).

5. Test installation by launching simulation.

If seg faults,

cd 
roscore

and open another bash

export LIBGL_ALWAYS_INDIRECT=0

Try rviz again.

Setup new branch

Please follow the branch naming convention detailed below.

cd ~/catkin_ws/src/quad-sdk
git checkout -b <ros-distro>_<base-branch>_<package>_<description>
git push --set-upstream origin <ros-distro>_<base-branch>_<package>_<description>

Lint formatting

The main and devel branches are protected to ensure proper code style. We follow the Google Style Guide and run the following script within our Continuous Integration scripts to ensure proper formatting. Please run this script on your own branch before submitting a PR (we recommend configuring your text editor to automatically format your documents to follow this guide).

cd ~/catkin_ws/src/quad-sdk
./scripts/lint_soft.sh

Submitting Pull Requests

For external users, please provide a brief description of any added functionality detailing what changes are expected to accomplish. This helps streamline the code review process.

Create new package

cd ~/catkin_ws/src/quad-sdk
catkin_create_pkg quad_package_name roscpp std_msgs *other-rosdeps-here*

After creating a package, open package.xml and modify the package owner and contact info to be yourself.

You can also copy and existing package and edit its contents, just be sure to update the contents fully (including the package.xml and CMake Lists.txt).

Create documentation

cd ~/catkin_ws/src/quad-sdk
doxygen Doxyfile
firefox docs/index.html

The repository is configured such that the Doxygen page will automatically update with any changes to the main branch.

Create new custom messages

Custom messages can be placed in quad_msgs/msg. See the ROS Tutorials for details on message creation. Add your message filename to the add_message_files() in quad_msgs/CMakeLists.txt, and add quad_msgs as a dependency to your package. To implement and namespace your messages, refer to this tutorial.

Ghost SDK Documentation (for Spirit users)

See the documentation here. Must have access to their repository.

Clone this wiki locally