bipedal-locomotion-framework

---

⚠️ REPOSITORY UNDER DEVELOPMENT ⚠️
The libraries implemented in this repository are still experimental and we cannot guarantee stable API

---

The bipedal-locomotion-framework project is a suite of libraries for achieving bipedal locomotion on humanoid robots.

Table of content

• 📄 Mandatory dependencies
• 📙 Exported components
• 📦 Install with conda (recommended)
• 🔨 Build the suite
• 💻 Some utilities
• 🐍 Python
• 🏃 How to use the libraries
• ⚙️ Contributing
• 🧑‍💻 Maintainers

📄 Mandatory dependencies

The bipedal-locomotion-framework project is versatile and can be used to compile only some components.

The minimum required dependencies are Eigen3, iDynTree and spdlog. If you want to build the tests please remember to install Catch2. If you are interested in the Python bindings generation please install python3 and pybind11 in your system.

📙 Exported components

The bipedal-locomotion-framework project consists of several components. The components are stored in the src folder and their compilation depends on the installed dependencies.

Component	Description	Additional Dependencies
Framework	Interface library that gathers all the exported components, includable with the file BipedalLocomotion/Framework.h	-
AutoDiff	Bridge between CppAD and Eigen	CppAD
ContactModels	Models to describe the contact between robot and enviroment	-
Contacts	Syntactic description of a contact	manif nlohmann json
CommonConversions	Common conversion utilities used in the framework	-
ManifConversions	Library related conversion utilities used in the framework	manif
matioCppConversions	Library related conversion utilities used in the framework	matio-cpp
CasadiConversions	Library related conversion utilities used in the framework	CasADi
Estimators	Library containing observers	-
FloatingBaseEstimator	Library containing floating base estimators	manif
RobotDynamicsEstimator	Library containing floating base estimators	manif
GenericContainer	Data structure similar to span but resizable.	-
IK	Inverse kinematics	manif osqp-eigen
Math	Library containing mathematical algorithms	manif
ML	Library containing deep learning algorithms	onnxruntime
ParametersHandler	Library for retrieving parameters from configuration files	YARP (only if you want the YARP implementation) tomlplusplus (only if you want the toml implementation)
PerceptionInterface	Generic interface classes to adapt to perception data formats like images and point clouds	OpenCV PCL
PerceptionCapture	Library containing driver classes for perception devices	OpenCV PCL realsense2
PerceptionFeatures	Library containing perception algorithms useful for locomotion	OpenCV
Planners	Library containing planner useful for locomotion	manif CasADi qhull
ReducedModelControllers	Controller based on reduced models, e.g., CentroidalMPC	CasADi
RobotInterface	Library for communicating with the robot	YARP (only if you want the YARP implementation)
SimplifiedModelControllers	Controllers based on simplified models, i.e, LIPM.	-
System	Description of discrete and continuous dynamical systems	-
TSID	Task space inverse dynamics	manif lie-group-controllers
TextLogging	Helper library to display messages into the console	YARP (only if you want the YARP implementation) ros-humble (if you want the ros2 implementation)
YarpUtilities	Utilities library for retrieving data and from YARP structures	YARP

⚠️ Including BipedalLocomotion/Framework.h may result in higher compilation time because of the inclusion of headers which may not be used in your project. It is always suggested to follow the IWYU paradigm. This applies also to the CMake targets. It is suggested to link only the targets used in your project.

📦 Install with conda (recommended)

You can easily the library with conda using the following command

conda install -c conda-forge bipedal-locomotion-framework

conda will automatically install all the required dependencies.

🔨 Build the suite

The bipedal-locomotion-framework can be built on Windows, macOS, and Linux. The easiest way to compile the library is to use the robotology-superbuild. If you enable the profiles ROBOTOLOGY_ENABLE_DYNAMICS and ROBOTOLOGY_ENABLE_DYNAMICS_FULL_DEPS in the robotology-superbuild you will automatically clone and build bipedal-locomotion-framework and all the dependencies.

If you do not want to use the robotology-superbuild you can manually compile the code in the repository by running the following command in the terminal

git clone https://github.com/ami-iit/bipedal-locomotion-framework.git
cd bipedal-locomotion-framework
mkdir build && cd build
cmake -DCMAKE_INSTALL_PREFIX=<path/where/you/want/to/install> \
      -DCMAKE_BUILD_TYPE=Release \
cmake --build . --config Release --target install

Remark: If you manually compile the framework remember to install the dependencies required by the component you are interested in.

💻 Some utilities

The bipedal-locomotion-framework ships also some utilities that can help you in the everyday tests on a real robot. You can find them in the utilities folder. Each utility contains a well-documented README where you can find further details.

🐍 Python

bipedal-locomotion-framework also provides Python bindings. Only a small set of the components implemented in the library have the corresponding Python bindings.

If you want to compile the bindings please install python3 and pybind11 in your system then you can run the following CMake command in your build folder

cmake -DCMAKE_INSTALL_PREFIX=<path/where/you/want/to/install> \
      -DCMAKE_BUILD_TYPE=Release \
      -DFRAMEWORK_COMPILE_PYTHON_BINDINGS:BOOL=ON \
      -DPython3_ROOT_DIR=$(python3 -c "import sys; print(sys.prefix)") \
      -DFRAMEWORK_USE_Python3:BOOL=ON \
      -DFRAMEWORK_USE_pybind11:BOOL=ON .
cmake --build . --config Release --target install

Disclaimer: The Python bindings are currently supported on Linux.

🏃 How to use the libraries

The bipedal-locomotion-framework provides native CMake support which allows the library to be easily used in CMake projects.

bipedal-locomotion-framework exports the CMake targets presented in the Exported components section. The targets can be imported using the find_package command and used by calling target_link_libraries.

For instance, the Math component can be used as follows:

cmake_minimum_required(VERSION 3.0)
project(myproject)
find_package(BipedalLocomotionFramework COMPONENTS Math REQUIRED)
add_executable(example example.cpp)
target_link_libraries(example PRIVATE BipedalLocomotion::Math)

The list of the targets can be found in the table 📙 Exported components.

⚙️ Contributing

bipedal-locomotion-framework is an open-source project, and is thus built with your contributions. We strongly encourage you to open an issue with your feature request. Once the issue has been opened, you can also proceed with a pull request:rocket:

🧑‍💻 Maintainers

• Giulio Romualdi (@GiulioRomualdi)
• Stefano Dafarra (@S-Dafarra)