Installation

An overview on the installation process of both the real and the simulated robot are discussed here.

Note

As a prerequsite, we suggest you to go through the tutorial on creating and building a ros2 package.

Distributions

Distros Humble, Jazzy, Kilted, Rolling
../_images/humble.png ../_images/jazzy.png ../_images/kilted.png ../_images/rolling.png

Please follow the list of distributions to know the available active distribution.

Tip

User will be directed to the installation of the distro by pressing the corresponding image.

Warning

Rolling distro is specific for the developers and there are chances to find code that breaks your process or your hardware. Using Rolling distro is encouraged, only if you are developing a package based on the robot, else use other distros.

Packages for Robot-PC

Tip

If you have a brand new robot from us, please skip this entire section and go to Packages for Client-PC

The first step is to install the neobotix-robot-setup-tools Debian package. This package installs and configures essential tools such as SSH and VNC. Additionally, it sets up all necessary udev rules, which are critical for enabling communication between the robot’s PC and its internal components. Please follow the instruction given here in the Installation on the robot-PC

ROS 2 does not use catkin for building the package unlike ROS (1), rather it employs ament_cmake as the default.

  • Before continuing with this tutorial, make sure you have sourced your corresponding ROS-Distro:

    source /opt/ros/your-ros-distro/setup.bash

Follow the simple 3-step process to create your ros-workspace with all the necessary packages:

  1. Open a terminal and clone the robot-setup-tool from GitHub.

    For noble (Ubuntu 24, Jazzy and above):

    git clone --branch noble https://github.com/neobotix/robot-setup-tool.git

    For jammy (Ubuntu 22, Humble):

    git clone --branch jammy https://github.com/neobotix/robot-setup-tool.git

  2. Go to the robot-setup-tool directory:

    cd robot-setup-tool/package-setup

  3. Run the bash file:

    For Humble:

    ./setup-mp(?)_(?)00.sh

    Please fill the (?) depending on your robot.

    Robots mpo_700, mpo_500, mp_400, mp_500, rox

    For Jazzy and Above:

    ./setup-mp_robot.sh

    ./setup-rox.sh

Additional Step for ROX

In case you have a ROX robot delivered before October 2024, the relayboard_v3 will have an old firmware. Therefore, please checkout version 0.2.1 of the neo_relayboard_v3 ROS 2 package using version control:

cd ~/ros2_workspace/src/neo_relayboard_v3
git checkout 0.2.1
cd ~/ros2_workspace
colcon build --symlink-install

Packages for Client-PC

Creating a ROS workspace

The ROS workspace contains the packages needed on your Client PC. See below on how to initialize it from a terminal:

mkdir -p ros_workspace/src

Downloading the required Neobotix ROS-Packages

Neobotix Robots

Below is an example with neo_mp_400, please choose the robot from the list below.

Robots mpo_700, mpo_500, mp_400, mp_500, rox 
git clone --branch $ROS_DISTRO https://github.com/neobotix/neo_mp_400-2

neo_msgs2

This is essential, when a topic relevant to neobotix modules are used.

git clone https://github.com/neobotix/neo_msgs2.git

neo_srvs2

This is essential, when a service relevant to neobotix modules are used.

git clone https://github.com/neobotix/neo_srvs2.git

Once all the packages are installed:

cd your_colcon_workspace
colcon build --symlink-install
. install/setup.bash

Robot Middleware (RMW)

For Humble:

We highly recommend to utilize rmw_cyclonedds. To install it:

sudo apt install ros-$ROS_DISTRO-rmw-cyclonedds-cpp

For Jazzy and Rolling:

We recommend to either use rmw_zenoh or rmw_cyclonedds.

To install Zenoh, please follow the instructions given in the official rmw_zenoh docs.

Sourcing the workspace

Note

. install/setup.bash does not need to be done each time after a package has been built, if the following step has been done.

echo "source your_colcon_workspace/install/setup.bash" >> ~/.bashrc

From the binaries

MoveIt2

Note

Required only for mobile manipulators

sudo apt-get install ros-$ROS_DISTRO-ros2-control ros-$ROS_DISTRO-ros2-controllers \
ros-$ROS_DISTRO-rqt_joint_trajectory_controller ros-$ROS_DISTRO-moveit-*

Packages for Simulation

Note

  • You can safely skip this step for the real robot.
  • We do not have support for ROX in classic Gazebo.

Warning

Before continuing with this tutorial, make sure you have sourced your corresponding ROS-Distro.

Requirements for Gz Sim

There is currently no official documentation outlining the exact system requirements for the modern Gazebo (Gz Sim). However, based on our experience and its dependency on similar simulation libraries and rendering engines, we believe the system requirements are comparable to those of Gazebo Classic.

Recommended minimum specifications to run Gz Sim effectively:

CPU       : Quad-core Intel i5 or equivalent
RAM       : 8 GB or more (16 GB recommended for complex simulations)
Storage   : SSD with at least 20 GB of free space
GPU       : Dedicated GPU with 1 GB or more of VRAM (NVIDIA preferred)

Note

A dedicated GPU with proper driver support is crucial for smooth visualization and sensor simulation in Gz Sim.

Warning

Running simulations on systems below these specifications may lead to reduced performance, crashes, or incomplete rendering.

Simulation Setup

Follow the simple 3-step process to create your ros-workspace with all the necessary packages:

  1. Open a terminal and clone the robot-setup-tool from GitHub depending on the Ubuntu version you have installed:

    For noble:

    git clone --branch noble https://github.com/neobotix/robot-setup-tool.git

    For jammy:

    git clone --branch jammy https://github.com/neobotix/robot-setup-tool.git

  2. Go to the robot-setup-tool directory:

    cd robot-setup-tool/package-setup

  3. Run the bash file:

    For noble:

    For ROX please run the following command:

    ./setup-rox-simulation.sh

    Attention

    Only ROX robots are available.

    For MP-series please run the following command:

    ./setup-mp-simulation.sh

    For jammy:

    For ROX please run the following command:

    ./setup-rox-simulation.sh

    For MP-series please run the following command:

    ./setup-simulation.sh

Note

For Jazzy and Rolling, to install RMW Zenoh, please follow the instructions given below under the manual workspace setup.

MoveIt2

Attention

This is only required for Humble

sudo apt-get install ros-$ROS_DISTRO-ros2-control ros-$ROS_DISTRO-ros2-controllers \
ros-$ROS_DISTRO-rqt_joint_trajectory_controller ros-$ROS_DISTRO-moveit-*

Robot Middleware (RMW)

Note

Please check the middleware that is delivered as part of the robot. Accordingly follow the steps given below.

For Humble:

We highly recommend to utilize rmw_cyclonedds. To install it:

sudo apt install ros-$ROS_DISTRO-rmw-cyclonedds-cpp

For Jazzy and Rolling:

We recommend to either use rmw_zenoh or rmw_cyclonedds.

To install Zenoh, please follow the instructions given in the official rmw_zenoh docs.