Locosim is didactic framework to learn/test basic controllers schemes on quadrupeds (HyQ/Solo/Aliengo/Go1 robots are supported) and manipulators (UR5 robot is supported). Locosim has been successfully tested on Ur5, Aliengo and Go1 robots and to my knowledge is the first Easy-to-Use interface to the new Unitree Quadruped robot Go1. If you just bought one Go1 robot and you want to give a try, follow this wiki!
Locosim is composed by a roscontrol node called ros_impedance_controller (written in C++) that interfaces the python ros node (where the controller is written) to a Gazebo simulator. All the didactic labs have a description, with exercises of increasing complexity, in the folder lab_descriptions inside robot_control submodule. For each controller, plotting / logging utilities are available to evaluate the results together with a configuration file (LX_conf.py) to change the controller parameters.
You have 3 ways to install Locosim code with all its dependencies: 1) with a virtual machine 2) with docker 3) by manual installation of dependencies.
First install the free software VMWare Player (the "player" keyword is for free personal use in the VMware software). For Linux / Windows system you can find it here for MAC here (you need to create an account I am sorry).
Then, download the following virtual machine and run the file VM ROBO.vmx to open it. You will have now a fully working Ubuntu 20 system with all the needed dependencies, code and Pycharm IDE already installed. The lab experiments that are present in: robot_control/lab_exercises you can find a detailed description of them in robot_control/lab_exercises/lab_descriptions.
IMPORTANT NOTE! To be able to update the submodules you need to generate you SSH key inside the virtual machine a store it in your Github account as explained here.
COMPATIBILITY ISSUES: This virtual machine works with x86-64 processors, but not for new MAC M1/M2 that employ ARM processors, the only solution is to install a parallel/multipass virtual machine and install natively all the dependencies inside there. Remember that on MAC you need to replace "sudo apt install package_name" with "brew install package_name". The easiest way is to follow a detailed wiki here, made by Federico Natali.
You can alternatively use a docker image with Ubuntu 20 and all the required dependencies already installed (you will need only to clone the code and compile it), by following this wiki. Docker has been tested to work with windows machines, Linux and old MACs (not ARM processors).
Locosim is compatible with Ubuntu 16/18/20. The installation instructions have been generalized accordingly. You need replace four strings (PYTHON_PREFIX, PYTHON_VERSION, PIP_PREFIX, ROS_VERSION) with the appropriate values according to your operating systems as follows:
| Ubuntu 16: | Ubuntu 18: | Ubuntu 20: |
|---|---|---|
| PYTHON_PREFIX = python | PYTHON_PREFIX = python3 | PYTHON_PREFIX = python3 |
| PYTHON_VERSION = 2.7 | PYTHON_VERSION = 3.5 | PYTHON_VERSION = 3.8 |
| ROBOTPKG_PYTHON_VERSION=py27 | ROBOTPKG_PYTHON_VERSION=py35 | ROBOTPKG_PYTHON_VERSION=py38 |
| PIP_PREFIX = pip | PIP_PREFIX = pip3 | PIP_PREFIX = pip3 |
| ROS_VERSION = kinetic | ROS_VERSION = bionic | ROS_VERSION = noetic |
NOTE: ROS is no longer supported (only ROS2) on Ubuntu 22 hence is not possible to install Locosim on Ubuntu 22.
setup your source list:
sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list'
Set up your keys:
curl -sSL 'http://keyserver.ubuntu.com/pks/lookup?op=get&search=0xC1CF6E31E6BADE8868B172B4F42ED6FBAB17C654' | sudo apt-key add -
install ROS main distro:
sudo apt-get install ros-ROS_VERSION-desktop-full
install ROS packages:
sudo apt-get install ros-ROS_VERSION-urdfdom-py
sudo apt-get install ros-ROS_VERSION-srdfdom
sudo apt-get install ros-ROS_VERSION-joint-state-publisher
sudo apt-get install ros-ROS_VERSION-joint-state-publisher-gui
sudo apt-get install ros-ROS_VERSION-joint-state-controller
sudo apt-get install ros-ROS_VERSION-gazebo-msgs
sudo apt-get install ros-ROS_VERSION-control-toolbox
sudo apt-get install ros-ROS_VERSION-gazebo-ros
sudo apt-get install ros-ROS_VERSION-controller-manager
sudo apt install ros-ROS_VERSION-joint-trajectory-controller
This packages are needed if you want to see the PointCloud published by a realsense camera attached at the endeffector. To activate it, you should load the xacro of the ur5 with the flag "vision_sensor:=true".
sudo apt-get install ros-ROS_VERSION-openni2-launch
sudo apt-get install ros-ROS_VERSION-openni2-camera
sudo apt install ros-ROS_VERSION-realsense2-description
Unfortunately grasping in Gazebo is still an open issue, I impelented grasping using this plugin that creates a fixed link between the gripper and the object to be grasped. To activate the grasping plugin set gripper_sim parameter to True in your configuration file. The following dependencies are required:
sudo apt-get install ros-ROS_VERSION-eigen-conversions
sudo apt-get install ros-ROS_VERSION-object-recognition-msgs
sudo apt install ros-ROS_VERSION-roslint
You can check which parameters have to be tuned looking to the following wiki
Add robotpkg as source repository to apt:
sudo sh -c "echo 'deb [arch=amd64] http://robotpkg.openrobots.org/packages/debian/pub $(lsb_release -sc) robotpkg' >> /etc/apt/sources.list.d/robotpkg.list"
sudo sh -c "echo 'deb [arch=amd64] http://robotpkg.openrobots.org/wip/packages/debian/pub $(lsb_release -sc) robotpkg' >> /etc/apt/sources.list.d/robotpkg.list"
Register the authentication certificate of robotpkg:
sudo apt install -qqy lsb-release gnupg2 curl
curl http://robotpkg.openrobots.org/packages/debian/robotpkg.key | sudo apt-key add -
You need to run at least once apt update to fetch the package descriptions:
sudo apt-get update
Now you can install Pinocchio and the required libraries:
sudo apt install robotpkg-PINOCCHIO_PYTHON_VERSION-eigenpy
sudo apt install robotpkg-PINOCCHIO_PYTHON_VERSION-pinocchio
sudo apt-get install robotpkg-PINOCCHIO_PYTHON_VERSION-quadprog
NOTE: If you have issues in installing robotpkg libraries you can try to install them through ROS as:
sudo apt-get install ros-ROS_VERSION-LIBNAME
sudo apt-get install PYTHON_PREFIX-scipy
sudo apt-get install PYTHON_PREFIX-matplotlib
sudo apt-get install PYTHON_PREFIX-termcolor
sudo apt install python3-pip
PIP_PREFIX install cvxpy==1.2.0
Now that you installed all the dependencies you are ready to get the code, but first you need to create a ros workspace to out the code in:
mkdir -p ~/ros_ws/src
cd ~/ros_ws/src
Now you need to call the following line manually (next you will see that it will be done automatically in the .bashrc)
source /opt/ros/ROS_VERSION/setup.bash
cd ~/ros_ws/
catkin_make
cd ~/ros_ws/src/
Now you can clone the repository inside the ROS workspace you just created:
git clone https://github.com/mfocchi/locosim.git
remember to update its submodules (robot_control and ros_impedance_controller) running this command in the locosim root:
git submodule update --init --recursive
IMPORTANT NOTE! you will not be able to checkout the submodules unless you generate and add your SSH key to your Github account, as explained here.
now recompile again (then this step won't bee needed anymore if you just work in python unless you do not modify / create additional ROS packages)
cd ~/ros_ws/
catkin_make install
the install step install the ros packages inside the "$HOME/ros_ws/install" folder rather than the devel folder. This folder will be added to the ROS_PACKAGE_PATH instead of the devel one.
Finally, run (you should do it any time you add a new ros package)
rospack profile
There are some additional utilities that I strongly suggest to install. You can find the list here.
gedit ~/.bashrc
copy the following lines (at the end of the .bashrc), remember to replace the string PYTHON_VERSION with the appropriate version name as explained in software versions section:
source /opt/ros/ROS_VERSION/setup.bash
source $HOME/ros_ws/install/setup.bash
export PATH=/opt/openrobots/bin:$PATH
export LOCOSIM_DIR=$HOME/ros_ws/src/locosim
export PYTHONPATH=/opt/openrobots/lib/pythonPYTHON_VERSION/site-packages:$LOCOSIM_DIR/robot_control:$PYTHONPATH
export ROS_PACKAGE_PATH=$ROS_PACKAGE_PATH:/opt/openrobots/share/
the .bashrc is a file that is automatically sourced whenever you open a new terminal.
NOTE: people with some operating systems like ARCH LINUX, might need to add "export ROS_IP=127.0.0.1" to the .bashrc.
Whenever you modify some of the ROS packages (e.g. the ones that contain the xacro fles inside the robot_description folder), you need to install them to be sure they are been updated in the ROS install folder.
cd ~/ros_ws/
catkin_make install
IMPORTANT!
The first time you compile the code the install folder is not existing, therefore won't be added to the PYTHONPATH with the command source $HOME/ros_ws/install/setup.bash, and you won't be able to import the package ros_impedance_controller. Therefore, only once, after the first time that you compile, run again :
source .bashrc
We recommend to use an IDE to run and edit the python files, like Pycharm community. To install it, you just need to download and unzip the program:
https://download.jetbrains.com/python/pycharm-community-2021.1.1.tar.gz
and unzip it inside the docker (e.g. copy it inside the ~/trento_lab_home folder.
IMPORTANT! I ask you to download this specific version (2021.1.1) that I am sure it works, because the newer ones seem to be failing to load environment variables!
- To run Pycharm community type (if you are lazy you can create an alias...):
$ pycharm_folder/bin/pycharm.sh
-
remember to run pycharm-community from the terminal otherwise it does not load the environment variables loaded inside the .bashrc.
-
click "Open File or Project" and open the folder robot_control. Then launch one of the labs in locosim/robot_control/lab_exercises or in locosim/robot_control/base_controllers (e.g. base_controller_fixed.py) right click on the code and selecting "Run File in Pyhton Console"
-
the first time you run the code you will be suggested to select the appropriate interpreter (/usr/binpython3.8). Following this procedure you will be sure that the run setting will be stored, next time that you start Pycharm.
IMPORTANT! To be able to keep the plots alive at the end of the program and to have access to variables, you need to "Edit Configurations..." and tick "Run with Python Console". Otherwise the plot will immediately close.
To run from a terminal we use the interactive option that allows when you close the program have access to variables:
$ python3 -i $LOCOSIM_DIR/robot_control/base_controllers/base_controller.py
to exit from python3 console type CTRL+Z
These packages are needed if you are willing to do experiments with the real robots
With the Ur5 robot you need to install these additional packages:
sudo apt install ros-ROS_VERSION-ur-msgs
sudo apt install ros-ROS_VERSION-scaled-joint-trajectory-controller
plus clone the ur_robot_driver package wherever inside the ros_ws/src folder:
git clone git@github.com:mfocchi/universal_robots_ros_driver.git
sudo apt-get install apt-get install liblcms2-2
sudo apt-get install apt-get install liblcms-bin
- Most of virtual machines including Virtualbox, do not have support for GPU. This means that if you run Gazebo Graphical User Interface (GUI) it can become very slow. A way to mitigate this is to avoid to start the Gazebo GUI and only start the gzserver process that will compute the dynamics, you will keep the visualization in Rviz. This is referred to planners that employ BaseController or BaseControllerFixed classes. In the Python code where you start the simulator you need to pass this additional argument as follows:
additional_args = 'gui:=false'
p.startSimulator(..., additional_args =additional_args)
- Another annoying point is the default timeout to kill Gazebo that is by default very long. You can change it (e.g. to 0.1s) by setting the _TIMEOUT_SIGINT = 0.1 and _TIMEOUT_SIGTERM = 0.1:
sudo gedit /opt/ros/ROS_VERSION/lib/PYTHON_PREFIX/dist-packages/roslaunch/nodeprocess.py
this will cause ROS to send a kill signal much sooner.
- if you get this annoying warning:
Warning: TF_REPEATED_DATA ignoring data with redundant timestamp for frame...
a dirty hack to fix it is to clone this repository in your workspace:
git clone --branch throttle-tf-repeated-data-error git@github.com:BadgerTechnologies/geometry2.git