Arm kit installation process
How to install your Arm kit.
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!
What do I need?
To program and control your robot, you have two main options:
- Directly control it via ROS2 Foxy: this gives you lower level access to the robot and full interoperability with ROS. Yet ROS can be complex, so if you are not familiar with it, that’s probably not what you are looking for.
- Use our specific Python SDK: simple Python’s API to let you quickly start controlling your robot. It gives you access to all main robot features. If you are not familiar with ROS, we advise you to use our SDK first.
In the following, we will show you how to install everything needed to start programming your robot. If you want to only use ROS2, we will tell you which steps can be skipped.
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.
Reachy runs on ROS 2 Foxy. So first of all, you need to install it.
For more information on ROS2 and how to install it, please refer to the official documentation: https://index.ros.org/doc/ros2/Installation/Foxy/Linux-Install-Debians/
You will also need to install colcon the build tool from ROS2.
sudo apt install python3-colcon-common-extensions
Create a ROS workspace for Reachy
Note: If you are familiar with ROS2, please feel free to use your custom installation.
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
Finally, source your .bashrc file:
Clone the requested ROS repositories from GitHub
~/reachy_ws/src, clone the following repositories (check here if you are not familiar with git):
To use Reachy directly with ROS:
To use Reachy through the SDK:
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
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>
Clone the other requested repositories from Github
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:
Requested in all cases:
To use Reachy through the SDK:
cd ~/dev git clone https://github.com/pollen-robotics/reachy_pyluos_hal.git git clone https://github.com/pollen-robotics/reachy-sdk-api.git
Then install them
cd ~/dev/reachy_pyluos_hal pip3 install -e . cd ~/dev/reachy-sdk-api pip3 install -e python
reachy-sdk can either be installed from source or using pip.
- from source
cd ~/dev git clone https://github.com/pollen-robotics/reachy-sdk.git cd ~/dev/reachy-sdk pip3 install -e .
- using pip
pip3 install reachy-sdk
To learn more on the repositories content and usage, please refer to README.md files in each repository.
Install the dependencies
Some Python dependencies need to be installed as extra.
Dependencies: numpy, scipy, pyquaternion, zoom_kurokesu, pykdl
If one of them is missing:
- Using pip install:
pip3 install numpy pip3 install scipy pip3 install pyquaternion pip3 install zoom_kurokesu
- Using apt install:
sudo apt install python3-pykdl
We also recommend you to install the jupyter and matplotlib libraries.
pip3 install jupyter pip3 install matplotlib
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 environment variable REACHY_MODEL that designates your model.
For example, to configure only a right arm:
Make sure to source your bashrc file to take the modification into account:
To use other methods to change your configuration, please read
~/dev/reachy_pyluos_hal/reachy_pyluos_hal/tools/reachy_identify_model.py or go to https://github.com/pollen-robotics/reachy_pyluos_hal/blob/main/reachy_pyluos_hal/tools/reachy_identify_model.py.
Start everything up
If you are using ROS, you will 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 reachy_sdk_server.launch.py
Generate a system.d file for auto-startup
If you want the reachy_sdk_server launch file to be started 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
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.