KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agent #developer-tools #codex #typescript #cli #deepseek-harness #claude-code #ai-agents #mcp #rust

walking-controllers

★ 160 Open GitHub ↗

Bipedal locomotion software for the humanoid robot platform iCub.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# walking-controllers

The **walking-controllers** project is a _suite_ of modules for achieving bipedal locomotion on humanoid robots such as iCub or ergoCub.

The suite includes:

* **Walking_module**: this is the main module and it implements all the controller architecture that allows the robot to walk.
* **Joypad_module**: this module allows using the Joypad as reference input for the trajectory generated by the Walking Module
* **WalkingLogger_module**: an module that can be useful to dump data coming from the Walking Module

# Overview
- [walking-controllers](#walking-controllers)
- [Overview](#overview)
- [:orange\_book: Some theory behind the code](#orange_book-some-theory-behind-the-code)
  - [Reference paper](#reference-paper)
- [:page\_facing\_up: Dependencies](#page_facing_up-dependencies)
- [:hammer: Build the suite](#hammer-build-the-suite)
  - [Linux/macOs](#linuxmacos)
- [:computer: How to run the simulation](#computer-how-to-run-the-simulation)
      - [Additional Dependencies](#additional-dependencies)
      - [How to run](#how-to-run)
  - [How to run the Joypad Module](#how-to-run-the-joypad-module)
  - [How to walk sideways](#how-to-walk-sideways)
  - [How to control the robot from YARP port](#how-to-control-the-robot-from-yarp-port)
  - [How to dump data](#how-to-dump-data)
  - [Some interesting parameters](#some-interesting-parameters)
    - [Inverse Kinematics configuration](#inverse-kinematics-configuration)
- [:running: How to test on the robot](#running-how-to-test-on-the-robot)
  - [:warning: Warning](#warning-warning)
  - [Mantainers](#mantainers)

# :orange_book: Some theory behind the code

This module allows humanoid robots walking using the position control interface.
It implements the following architecture
![controller_architecture](https://user-images.githubusercontent.com/16744101/37352869-757896b4-26de-11e8-97bc-10700add7759.jpg)
where two controller loops can be distinguished:
* an inner ZMP-CoM control loop http://ieeexplore.ieee.org/stamp/stamp.jsp?tp=&arnumber=4359259&tag=1;
* an outer DCM control loop:
   * model predictive controller;
   * reactive controller.

Two different inverse kinematics solver are implemented:
* a standard non-linear IK solver;
* a standard QP Jacobian based IK solver.

## Reference paper
A paper describing some of the algorithms implemented in this repository  can be downloaded [here](https://arxiv.org/abs/1809.02167).
If you're going to use the code developed for your work, please quote it within any resulting publication:
```
G. Romualdi, S. Dafarra, Y. Hu, D. Pucci "A Benchmarking of DCM Based
Architectures for Position and Velocity Controlled Walking of Humanoid Robots",
2018
```

The bibtex code for including this citation is provided:
```
@misc{1809.02167,
Author = {Giulio Romualdi and Stefano Dafarra and Yue Hu and Daniele Pucci},
Title = {A Benchmarking of DCM Based Architectures for Position and Velocity Controlled Walking of Humanoid Robots},
Year = {2018},
Eprint = {arXiv:1809.02167},
}
```

# :page_facing_up: Dependencies
* [YARP](http://www.yarp.it/): to handle the comunication with the robot;
* [trintrin](https://github.com/ami-iit/trintrin): a library with common messages for interprocess communication in robotics applications.
* [iDynTree](https://github.com/robotology/idyntree): to handle the robot kinematics;
* [iCubContrib](https://github.com/robotology/icub-contrib-common): to configure the modules;
* [icub-main](https://github.com/robotology/icub-main): to smooth and integrate signals;
* [osqp-eigen](https://github.com/robotology/osqp-eigen): to solve the MPC problem;
* [qpOASES](https://github.com/robotology-dependencies/qpOASES): to solve the IK problem;
* [Unicycle footstep planner](https://github.com/robotology/unicycle-footstep-planner): to generate a trajectory for the DCM;
* [bipedal-locomotion-framework](https://github.com/ami-iit/bipedal-locomotion-framework): for locomotion functionalities;
* [Gazebo](http://gazebosim.org/): for the simulation (tested Gazebo 8, 9 and 10);
* [Catch2](https://github.com/catchorg/Catch2): to compile the tests.

# :hammer: Build the suite
## Linux/macOs

```sh
git clone https://github.com/robotology/walking-controllers.git
cd walking-controllers
mkdir build && cd build
cmake ../
make
[sudo] make install
```
Notice: `sudo` is not necessary if you specify the `CMAKE_INSTALL_PREFIX`. In this case it is necessary to add in the `.bashrc` or `.bash_profile` the following lines:
```sh
export WalkingControllers_INSTALL_DIR=/path/where/you/installed/
export PATH=$PATH:$WalkingControllers_INSTALL_DIR/bin
export YARP_DATA_DIRS=$YARP_DATA_DIRS:$WalkingControllers_INSTALL_DIR/share/ICUBcontrib
```

# :computer: How to run the simulation
#### Additional Dependencies
In order to run the simulation, the following additional dependency are required:
* [`gazebo-yarp-plugins`](https://github.com/robotology/gazebo-yarp-plugins)
* [`whole-body-estimators`](https://github.com/robotology/whole-body-estimators)
* [`icub-models`](https://github.com/robotology/icub-models)
* [`ergocub-software`](https://github.com/icub-tech-iit/ergocub-software)

#### How to run
1. Set the `YARP_ROBOT_NAME` environment variable according to the chosen Gazebo model for instance for the model `ergoCubGazeboV1`:
   ```console
   export YARP_ROBOT_NAME="ergoCubGazeboV1"
   ```
2. Run `yarpserver`
   ```console
   yarpserver --write
   ```
3. Run gazebo and drag and drop robot model (e.g. `ergoCubGazeboV1`):

```console
    export YARP_CLOCK=/clock
    gazebo -slibgazebo_yarp_clock.so
    ```
4. Run `whole-body-dynamics`, for instance for the model `ergoCubGazeboV1`:

```console
   yarprobotinterface --config conf/launch_wholebodydynamics_ecub.xml
    ```
5. Run the walking module
    ```console
    YARP_CLOCK=/clock WalkingModule
    ```
6. communicate with the `WalkingModule`:
   ```
   yarp rpc /walking-coordinator/rpc
   ```
   the following commands are allowed:
   * `prepareRobot`: put ergoCub in the home position;
   * `startWalking`: run the controller;
   * `pauseWalking`: the controller is paused, you can start again the
     controller sending `startWalking` command;
   * `stopWalking`: the controller is stopped, in order to start again the
     controller you have to prepare again the robot.
   * `setGoal (x, y, k)`: send the desired input to the planner. Send this command after `startWalking`.

Example sequence:
   ```
   prepareRobot
   startWalking
   setGoal (1.0, 0.0, 0.0)
   setGoal (1.0, 0.0, 0.0)
   stopWalking
   ```

## How to run the Joypad Module
The Joypad application, called `WalkingJoypadModule`, allows you to send all the rpc commands using the buttons. The application processes the button press events associating them to the pre-defined rpc commands which are then sent through Yarp to the Walking Coordinator module. The joypad keys mapping is as follows:
 * `A` for preparing the robot
 * `B` for start walking
 * `Y` for pause walking
 * `X` for stop walking

Suppose that you want to run the Joypad application, called `WalkingJoypadModule` in the same machine where the physical device is connected. The only thing that you have to do is running the following command from the terminal:

``` sh
YARP_CLOCK=/clock WalkingJoypadModule
```
The application will take care to open an [`SDLJoypad`](http://www.yarp.it/classyarp_1_1dev_1_1SDLJoypad.html) device.

While, if you want to run the `WalkingJoypadModule` in a machine that is different form the one where the physical devce is connected. The
[`JoypadControlServer`](http://www.yarp.it/classyarp_1_1dev_1_1JoypadControlServer.html) -
[`JoypadControlClient`](http://www.yarp.it/classyarp_1_1dev_1_1JoypadControlClient.html)
architecture is required. In details:
1. Run the `JoypadControlServer` device in the computer where the joypad is
   physically connected:

``` sh
    YARP_CLOCK=/clock yarpdev --device JoypadControlServer --use_separate_ports 1 --period 10 --name /joypadDevice/xbox --subdevice SDLJoypad --sticks 0
   
    ```
2. Run the `WalkingJoypadModule` in the other computer

```
    YARP_CLOCK=/clock WalkingJoypadModule --device JoypadControlClient --local /joypadInput --remote /joypadDevice/xbox
    ```
    
## How to walk sideways
In order to enable the sideways walking it is necessary to set the parameter ``controlType`` to ``direct`` in the ``plannerParams`` configuration file. In this configuration, the goal set with ``setGoal`` is interpreted as a desired velocity reference for the unicycle. In this case, ``setGoal`` expects three doubles that represent the forward velocity, angular velocity, and lateral velocity. For example
```
setGoal (0.0 0.0 1.0)
```
will command the robot to step sideways to the left.

In case the planner fails in finding a solution, it is possible to reduce the values in ``saturationFactors`` in the ``plannerParams`` file. These numbers represent conservative factors that multiply the unicycle velocity saturations computed from the other parameters, like the ``minStepDuration``. The first number multiplies the saturation for the linear and lateral velocity. The second number multiplies the angular velocity saturation. Suggested values for ``saturationFactors``:
- ``personFollowing`` case: ``(0.9, 0.7)``
- ``direct`` case: ``(0.7, 0.7)``

## How to control the robot from YARP port
The ``WalkingModule`` opens a port named by default ``/walking-coordinator/goal:i`` (it can be edited from the main configuration file). This port expects a vector of double of size 2 if the ``controlType`` in ``plannerParams`` is set to ``personFollowing``, or 3 if the value is ``direct``. In the first case, they represent the x and y position in a robot centered frame of the desired point to reach. In the second case, they represent the desired unicycle velocities.

The range of the numbers is expected to be ``[-1, +1]``. Some scaling can be applied in the main configuration file through the parameter ``goal_port_scaling``. Suggested scaling:
- ``personFollowing`` case: ``(10.0, 10.0, 1.0)`` (the third input is not considered) 
- ``direct`` case: ``(0.5, 1.0, 0.5)``

## How to dump data

Before running `WalkingModule` check if `dump_data` is set to 1. This parameter is set in a configuration `ini` file depending on the control mode, for instance controlling from the joypad: `src/WalkingModule/app/robots/${YARP_ROBOT_NAME}/dcm_walking_with_joypad.ini`. [Example for the model `ergoCubGazeboV1`](src/WalkingModule/app/robots/ergoCubGazeboV1/dcm_walking_with_joypad.ini#L12) Then you can log your data with [`YarpRobotLoggerDevice`](https://github.com/ami-iit/bipedal-locomotion-framework/tree/master/devices/YarpRobotLoggerDevice).

## Some interesting parameters
You can change the DCM controller and the inverse kinematics solver by editing [these parameters](src/WalkingModule/app/robots/ergoCubGazeboV1/dcm_walking_with_joypad.ini#L22-L57).

### Inverse Kinematics configuration
The Inverse Kinematics block configuration can be set through the file `src/WalkingModule/app/robots/ergoCubGazeboV1/dcm_walking/joint_retargeting/inverseKinematics.ini`.

The Inverse Kinematics block uses an open source package for large-scale optimisation, IPOPT (Interior Point Optimizer), which requires other packages like BLAS (Basic Linear Algebra Sub-routines), LAPACK (Linear Algebra PACKage) and a sparse symmetric indefinite linear solver ([MAxx, HSLMAxx](http://www.hsl.rl.ac.uk/), MUMPS, PARDISO etc). Further documentation can be found at https://coin-or.github.io/Ipopt and https://coin-or.github.io/Ipopt/INSTALL.html#EXTERNALCODE. The package IPOPT installed with the superbuild (via homebrew or conda) is built with the solver [MUMPS](http://mumps.enseeiht.fr/) by default, which is reflected in the default configuration of the Inverse Kinematics block src/WalkingModule/app/robots/ergoCubGazeboV1/dcm_walking/joypad_control/inverseKinematics.ini#L14-L17:
```sh
# solver paramenters
solver-verbosity        0
solver_name             mumps
max-cpu-time            20
```

For instance, for using MA27 solver instead of MUMPS, replace `mumps` by `ma27`.

:warning: HSL solvers are not compiled with IPOPT by default. Refer to https://coin-or.github.io/Ipopt/INSTALL.html#EXTERNALCODE for further documentation.

In case you encounter issues when starting the Walking Module with the selected options, you can increase the verbosity to 1 for additional debug information.

# :running: How to test on the robot

You can follows the same instructions of the simulation section without using `YARP_CLOCK=/clock`. Make sure your `YARP_ROBOT_NAME` is coherent with the name of the robot (e.g. ``ergoCubSN000``)

## :warning: Warning
Currently the supported robots are only:
- ``iCubGazeboV3``
- ``ergoCubGazeboV1``
- ``ergoCubSN000``

Yet, it is possible to use these controllers provided that the robot has powerful enough legs. In this case, the user should define the robot specific configuration files (those of ``ergoCubSN000`` are a good starting point). If you want to try these, feel free to open an issue to track your progress.

:warning: The IIT STRAIN F/T sensors mounted on older versions of iCub may suffer from saturations due to the strong impacts the robot has with the ground, which may lead to a failure of the controller. It is suggested to use these controllers with IIT STRAIN2 sensors only to avoid such saturations.

## Mantainers

* Giulio Romualdi ([@GiulioRomualdi](https://github.com/GiulioRomualdi))
* Stefano Dafarra ([@S-Dafarra](https://github.com/S-Dafarra))

walking-controllers

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README