Locosim is a didactic framework to learn/test basic controllers schemes on quadruped robots (HyQ/Solo/Aliengo/Go1 are supported) and manipulators (UR5 is supported). Locosim has been successfully tested on Ur5, Aliengo and Go1 robots and (to my knowledge) is the first Open-Source Easy-to-Use interface to the new Unitree Quadruped robot Go1. If you just bought a 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 a 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 the Locosim code with all its dependencies: 1) with a virtual machine 2) with docker 3) by manual installation of dependencies.

First install the free version (16.0) of the 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:

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

sudo apt install ros-noetic-moveit

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

 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!

1. To run Pycharm community type (if you are lazy you can create an alias...):

$ pycharm_folder/bin/pycharm.sh

2. remember to run pycharm-community from the terminal otherwise it does not load the environment variables loaded inside the .bashrc.

3. 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"

4. 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

The driver for the UR5 has already been included in Locosim but is not compiled by default, hence you need to:

1. remove file CATKIN_IGNORE inside the ur_driver package
2. remove file CATKIN_IGNORE inside the zed_wrapper package
3. Install these additional packages:

sudo apt install ros-ROS_VERSION-ur-msgs

sudo apt install ros-ROS_VERSION-speed-scaling-interface

sudo apt install ros-ROS_VERSION-scaled-joint-trajectory-controller

sudo apt install ros-ROS_VERSION-industrial-robots-status-interface

sudo apt install ros-ROS_VERSION-speed-scaling-state-controller

sudo apt install ros-ROS_VERSION-ur-client-library

sudo apt install ros-ROS_VERSION-pass-through-controllers

4. recompile with catkin_make install.
5. add the following alias to your .bashrc

launch_robot='roslaunch ur_robot_driver ur5e_bringup.launch headless_mode:=true robot_ip:=192.168.0.100 kinematics_config:=$LOCOSIM_DIR/robot_hardware_interfaces/ur_driver/calibration_files/my_robot_calibration_X.yaml'

where X is {1,2}. For the robot with the soft gripper X = 2.

4. Trigger the robot workbench power switch on and press the on button on the UR5 Teach Pendant

5. Connect the Ethernet cable to the lab laptop and create a local LAN network where you set the IP of your machine to 192.168.0.101 (the robot IP will be 192.168.0.100, double check it using the UR5 "Teach Pendant")

6. Verify that you can ping the robot:

   ping 192.168.0.100
   

7. Where it says "Spegnimento" activate the robot pressing "Avvio" twice untill you see all the 5 green lights and you hear the release of the brakes. Set the "Remote Control" in the upper right corner of the "Teach Pendant"

8. Run the launch_robot alias to start the ur_driver. If you want to start the driver without the ZED camera (e.g. you do not have CUDA installed), append vision_sensor:=false to the command.

   launch_robot viswion_sensor:=false
   

   Conversely, if you want to launch only the ZED camera alone and see the data in rviz:

   roslaunch zed_wrapper zed2.launch rviz:=true
   

9. Run the ur5_generic.py with the real_robot flag set to True. The robot will move to the home configuration defined here.

10. For the usage and calibration of the ZED camera follow this instructions here.

Universal Robots + Gripper

You have 2 kind of gripper available in the ur5 robot: a rigid 3 finger gripper and a soft 2 finger gripper. Locosim seamlessly allows you to deal with both of them. By default, the 3 finger gripper is enabled, if you want to use the 2 finger one (soft_gripper) you need to:

1. set the soft_gripper flag to True (in Simulation)

2. append soft_gripper:=true to the launch_robot alias (on the real robot).

Universal Robots + ZED camera support

If you are willing to use the real ZED Camera on the real robot, the zed_wrapper package is not compiled by default, hence you need to:

1. remove the file CATKIN_IGNORE in the zed_wrapper package

2. Install CUDA (locosim is compatible only with version 12): https://developer.nvidia.com/cuda-downloads

3. Install the SDK library (locosim is compatible only with version 4.0.2) in: https://www.stereolabs.com/developers/release/

4. Recompile with catkin_make install

If you have issues remove the build/devel folder and recompile.

sudo apt-get install apt-get install liblcms2-2

sudo apt-get install apt-get install liblcms-bin

and follow this wiki!

1. 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)

2. 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.

3. 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 [email protected]:BadgerTechnologies/geometry2.git