Arm Installation Process
You decided to buy an Arm kit, you have a few things to install on your computer. Don’t worry, we will go step by step to guide you through the installation process!
The low-level software used to control the robot has been developed to work on Linux Ubuntu 22.04. While it should work on other OS, we strongly recommend using the same version.
Reachy’s software installation is divided into two main parts:
- installing ROS2 Humble and the ROS2 packages developped for Reachy
- installing the Python packages developped for Reachy
If you are not familiar with ROS, it stands for Robotics Operating System and is basically a set of software libraries and tools that help build robot applications. It is commonly used in Robotics. You don’t need to know how to use ROS to work with Reachy thanks to the Python SDK that we developped but if you want to learn about ROS, we suggest taking a look at their great tutorials.
Also, you can check this page to know more about how Reachy’s software is organised.
Now back to the installation!
Install ROS2 Humble
As explained above, Reachy’s software runs on ROS 2 Humble so first of all, you need to install it on your computer. Based on the official ROS2 documentation, here are the steps to do the installation. In a terminal, in your computer:
sudo apt update && sudo apt install -y locales
sudo locale-gen en_US en_US.UTF-8
sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
sudo apt install -y software-properties-common
sudo add-apt-repository universe
sudo apt update && sudo apt install -y curl
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(. /etc/os-release && echo $UBUNTU_CODENAME) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null
sudo apt update
vcs import src < ros2_control.repos
sudo apt install -y ros-humble-desktop
sudo apt install -y ros-dev-tools
sudo apt install -y ros-humble-tf-transformations
sudo apt install -y ros-humble-compressed-image-transport
sudo apt install -y python3-colcon-common-extensions
Check that the installation went well
To make sure that ROS2 Humble has been successfully installed, you can run the test example from ROS2 Humble. Taken from the ROS2 Humble documentation.
Install Reachy’s ROS2 packages
Create a dedicated workspace
Now that you have installed ROS, you need to create a ROS workspace to install the specific ROS packages for Reachy.
Create it in your $HOME folder:
mkdir -p ~/reachy_ws/src
Build your empty workspace once to set everything up.
colcon build --symlink-install
Once done, add commands to your .bashrc file so that you won’t have to type them in each new terminal.
echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
echo "source /home/reachy/reachy_ws/install/setup.bash" >> ~/.bashrc
echo "source /usr/share/colcon_cd/function/colcon_cd.sh" >> ~/.bashrc
echo "export _colcon_cd_root=~/ros2_install" >> ~/.bashrc
echo 'export LC_NUMERIC="en_US.UTF-8"' >> ~/.bashrc
echo "export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp" >> ~/.bashrc
echo "export ROS_DOMAIN_ID=1" >> ~/.bashrc
In the seconde line, replace the reachy in /home/reachy/reachy_ws/install/setup.bash with your username.
Finally, source your .bashrc file:
Install git lfs
sudo apt-get install -y git-lfs
git lfs install
Clone Reachy’s ROS2 packages
Now you’re ready to install Reachy’s ROS2 packages in the workspace you just created.
git clone https://github.com/pollen-robotics/reachy_2023.git
Once everything cloned in your ROS2 workspace, install the dependencies and build the packages:
pip3 install -r ./src/reachy_2023/requirements.txt
colcon build --symlink-install
Install Reachy’s Python packages
Some of Reachy’s Python packages have dependencies that you should install. The dependencies are numpy, scipy, pyquaternion, sklearn, pykdl.
- Using pip install:
pip3 install numpy
pip3 install scipy
pip3 install pyquaternion
pip3 install sklearn
We also recommend to install the jupyter and matplotlib libraries.
pip3 install jupyter
pip3 install matplotlib
Cloning the Python packages
Create another folder dev that will contain all the packages used with Reachy that are not based on ROS.
In this folder you will need the following repositories:
git clone https://github.com/pollen-robotics/reachy-sdk-api.git
git clone https://github.com/pollen-robotics/reachy-sdk.git
Install the packages after the cloning.
pip3 install -e python
pip3 install -e .
To learn more on the repositories content and usage, please refer to README.md files in each repository.
RUST is needed to enable the communication between the hardware and the ROS packages.
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
echo "" >> ~/.bashrc
echo "# RUST" >> ~/.bashrc
echo 'source "$HOME/.cargo/env"' >> ~/.bashrc
Open ports for serial use
By default, on a Ubuntu install, when using serial, users do not have the right to access the ports. Give rights to open
sudo usermod -a -G tty <usr_name>
sudo usermod -a -G dialout <usr_name>
sudo usermod -a -G input <usr_name>
Set the correct configuration file
As Reachy software is meant to work with different robot configurations. Several configuration files are available.
By default, the configuration is set to a full robot. You need to modify it to your own configuration.
And add an config file with your model as ~/.reachy.yaml.
For example, to configure only a right arm:
Make sure to source your .bashrc file to take the modification into account:
If you want to work directly at the ROS level
If you prefer using the ROS2 packages instead of the Python SDK, you can find bring up launch file to set your robot up. In particular, you can run:
ros2 launch reachy_bringup reachy.launch.py
If you want to use the SDK, we provide a specific argument that starts everything (including the above mentioned ROS packages) at once:
ros2 launch reachy_bringup reachy.launch.py start_sdk_server:=true
For more information, check the page Working with ROS2 Humble
Everything should now be installed and running on your computer to start working with Reachy! Let’s check this out.
The output in the terminal should look like this:
Especially, you should see the line: SDK ready to be served!.
Finally you can check that you can connect to the arm using Reachy’s Python SDK.
In a python terminal:
>>> from reachy_sdk import ReachySDK
>>> reachy = ReachySDK(host='localhost')
For a robotic right arm, the outputs should look like this:
If both of these are ok the arm’s software installation should have went well!