Arm kit software installation

How to install Reachy's Arm kit software.

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!

Prerequisites

The low-level software used to control the robot has been developed to work on Linux Ubuntu 20.04. While it should work on other OS, we strongly recommend using the same version.

Presentation

Reachy’s software installation is divided into two main parts:

  • installing ROS2 Foxy 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 Foxy

As explained above, Reachy’s software runs on ROS 2 Foxy 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 curl gnupg2 lsb-release
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 $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null
sudo apt update
sudo apt install ros-foxy-desktop

sudo apt install -y python3-argcomplete
sudo apt install python3-colcon-common-extensions

Check that the installation went well

To make sure that ROS2 Foxy has been successfully installed, you can run the test example from ROS2 Foxy. Taken from the ROS2 Foxy documentation:

drawing

Your two terminals should look like this:

drawing

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.

cd ~/reachy_ws
source /opt/ros/foxy/setup.bash
colcon build 

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/foxy/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

In the seconde line, replace the reachy in /home/reachy/reachy_ws/install/setup.bash with your username.

Finally, source your .bashrc file:

source ~/.bashrc

Clone Reachy’s ROS2 packages

Now you’re ready to install Reachy’s ROS2 packages in the workspace you just created. The packages are the following:

cd ~/reachy_ws/src
git clone https://github.com/pollen-robotics/reachy_msgs.git
git clone https://github.com/pollen-robotics/reachy_controllers.git
git clone https://github.com/pollen-robotics/reachy_kinematics.git
git clone https://github.com/pollen-robotics/reachy_sdk_server.git

Once everything cloned in your ROS2 workspace, build the packages:

cd ~/reachy_ws
colcon build

Install Reachy’s Python packages

We recommend working in a virtual environment to install Reachy’s Python packages.

Dependencies

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
  • Using apt install:
sudo apt install python3-pykdl

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.

mkdir ~/dev

In this folder you will need the following repositories:

cd ~/dev
git clone https://github.com/pollen-robotics/reachy_pyluos_hal.git
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.

cd ~/dev/reachy_pyluos_hal
pip3 install -e .

cd ~/dev/reachy-sdk-api
pip3 install -e python

cd ~/dev/reachy-sdk
pip3 install -e .

To learn more on the repositories content and usage, please refer to README.md files in each repository.

Other

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 /dev/ttyUSB ports:

sudo usermod -a -G tty <usr_name>
sudo usermod -a -G dialout <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.

Open .bashrc:

nano ~/.bashrc

And add an environment variable REACHY_MODEL that designates your model.
For example, to configure only a right arm:

export REACHY_MODEL="robotic_arm_right"

Make sure to source your .bashrc file to take the modification into account:

source ~/.bashrc

Generate a system.d file for auto-startup

If you want that all Reachy’s ROS2 packages start automatically when your computer starts, you can use our systemd file:

cd ~/reachy_ws/src/reachy_sdk_server
bash generate-service-file.bash

This command should have created a file called reachy_sdk_server.service. To activate this service, you need to copy it to systemd:

sudo cp reachy_sdk_server.service /etc/systemd/system

Enable it for the service to be launched automatically when you restart your computer:

sudo systemctl enable reachy_sdk_server.service

You can manually start it doing:

sudo systemctl start reachy_sdk_server.service

Note: You need to connect the arm to your computer before starting a service. If you enabled the service, connect your arm to your computer before turning it on.

For more information on the services, please refer to section Using services.

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 launch files in each of our ROS packages to set them up. In particular, you can run:

ros2 launch reachy_kinematics kinematics.launch.py  
# (for description and kinematics)
ros2 launch reachy_controllers joint_state_controller.launch.py  
# (for joint_state, joint_goals, fans, sensors, etc.) 

If you want to use the SDK, we provide a specific launcher file that starts everything (including the above mentioned ROS packages) at once:

ros2 launch reachy_sdk_server run_everything_no_head.launch.py

For more information, check the page Working with ROS2 Foxy

Final checking

Everything should now be installed on your computer to start working with Reachy! Let’s check this out.

First, if you created reachy_sdk_server.service to start everything in background, stop it.

sudo systemctl stop reachy_sdk_server.service

Then, launch the ROS2 packages in a terminal:

cd ~/reachy_ws/ros2 launch reachy_sdk_server run_everything_no_head.launch.py

The output in the terminal should look like this:

drawing

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')

>>>reachy

For a robotic right arm, the outputs should look like this:

drawing

If both of these are ok the arm’s software installation should have went well!

Edit this page on GitHub