Quick Start Guide

This step by step quick start guide for running OpenMANIPULATOR-X on ROS^TM will guide you to operate the OpenMANIPULATOR-X for the first time.

In order to run this Quick Start Guide, you should be prepared with below items.

• OpenMANIPULATOR-X
• Communication Interface (Use either option you prefer)
  • Option 1 : DYNAMIXEL Starter Set
  • Option 2 : OpenCR1.0
• Power supply
  • ROBOTIS SMPS 12V 5A PS-10 recommended (included in the DYNAMIXEL Starter Set)

This step by step quick start guide for running OpenMANIPULATOR-X on ROS^TM will guide you to operate the OpenMANIPULATOR-X for the first time.

In order to run this Quick Start Guide, you should be prepared with below items.

• OpenMANIPULATOR-X
• Communication Interface (Use either option you prefer)
  • Option 1 : DYNAMIXEL Starter Set
  • Option 2 : OpenCR1.0
• Power supply
  • ROBOTIS SMPS 12V 5A PS-10 recommended (included in the DYNAMIXEL Starter Set)

This step by step quick start guide for running OpenMANIPULATOR-X on ROS^TM will guide you to operate the OpenMANIPULATOR-X for the first time.

In order to run this Quick Start Guide, you should be prepared with below items.

• OpenMANIPULATOR-X
• Communication Interface (Use either option you prefer)
  • Option 1 : DYNAMIXEL Starter Set
  • Option 2 : OpenCR1.0
• Power supply
  • ROBOTIS SMPS 12V 5A PS-10 recommended (included in the DYNAMIXEL Starter Set)

This step by step quick start guide for running OpenMANIPULATOR-X with Arduino will guide you to operate the OpenMANIPULATOR-X for the first time.

In order to run this Quick Start Guide, you should be prepared with below items.

• OpenMANIPULATOR-X
• Arduino Embedded Controller OpenCR1.0
• Power supply
  • ROBOTIS SMPS 12V 5A PS-10 recommended

This method provides an isolated environment with all dependencies pre-installed.

Install Docker and Docker Compose

Container Engine: Docker Engine

Follow the official Docker installation guide and complete the post-installation steps.

Required steps:

1. Install Docker Engine using the repository method
2. Add your user to the docker group
3. Enable Docker to start on boot
4. Verify installation with docker run hello-world

Clone the Repository

$ git clone -b jazzy https://github.com/ROBOTIS-GIT/open_manipulator.git
$ cd open_manipulator

Container Management

The repository includes a container management script with the following commands:

# Show help
$ ./docker/container.sh help

# Start container
$ ./docker/container.sh start

# Enter the running container
$ ./docker/container.sh enter

# Stop and remove the container
$ ./docker/container.sh stop

Data Persistence

The container maps the following directories for data persistence:

• ./docker/workspace:/workspace - The workspace directory inside the docker folder is mapped to /workspace inside the container

This method provides an isolated environment with all dependencies pre-installed.

NOTE: Docker Environment is supported for ROS 2 Humble, but detailed manual documentation is provided starting from the Jazzy version. Please refer to the Jazzy Docker Environment for comprehensive setup instructions.

Install Docker and Docker Compose

Container Engine: Docker Engine

Follow the official Docker installation guide and complete the post-installation steps.

Required steps:

1. Install Docker Engine using the repository method
2. Add your user to the docker group
3. Enable Docker to start on boot
4. Verify installation with docker run hello-world

Clone the Repository

$ git clone -b humble https://github.com/ROBOTIS-GIT/open_manipulator.git
$ cd open_manipulator

Container Management

Use Docker Compose to manage the container:

# Start container
$ docker compose up -d --build

# Stop and remove the container
$ docker compose down

Data Persistence

The container maps the following directories for data persistence:

• ./docker/workspace:/workspace - The workspace directory inside the docker folder is mapped to /workspace inside the container

Docker Environment is not supported for ROS Noetic. Please use the Host Installation method below.

Not required.

Installing Ubuntu on a PC or laptop may differ by model. Please contact the manufacturer or community for more details.

ROS 2 Jazzy is supported on Ubuntu 24.04.
Please refer to the Ubuntu installation tutorial below.

• Download Ubuntu

• Official Ubuntu Installation Tutorial

Installing Ubuntu on a PC or laptop may differ by model. Please contact the manufacturer or community for more details.

ROS 2 Humble is supported on Ubuntu 22.04.
Please refer to the Ubuntu installation tutorial below.

• Download Ubuntu

• Official Ubuntu Installation Tutorial

Installing Ubuntu on a PC or laptop may differ by model. Please contact the manufacturer or community for more details.

ROS Noetic is supported on Ubuntu 20.04.
Please refer to the Ubuntu installation tutorial below.

• Download Ubuntu

• Official Ubuntu Installation Tutorial

WARNING : This Arduino instruction does not require ROS to operate OpenMANIPULATOR-X.
When operating with ROS, the PC becomes the main controller.
On the other hands, when operating with Arduino, the OpenCR becomes the main controller.

OpenMANIPULATOR-X is compatible with OpenCR. We offer API to easily control manipulator.
This API supports DYNAMIXEL, DYNAMIXEL-X including protocol 1.0 and 2.0. Furthermore, this code can be used for OpenMANIPULATOR Friends.
User can write the code in Arduino IDE and simulate or control using Processing GUI.

NOTE : Processing source code is tested in Processing v3.5.4.

1. Install Arduino IDE and setup OpenCR developing environment.
   • Setup Arduino IDE for OpenCR 1.0 (Windows)
   • Setup Arduino IDE for OpenCR 1.0 (Linux)
   • Setup Arduino IDE for OpenCR 1.0 (Mac)

2. Connect OpenCR to PC with a micro USB cable.

3. Run Arduino IDE and open the example.
   Go to Examples > OpenManipulator > example > Chain > open_manipulator_chain.
   

4. Upload the example to OpenCR.
   

5. When the upload is completed, the following message will be displayed in the output window.
   

WARNING
Please be aware that OpenCR board manager does not support Arduino IDE on ARM based SBC such as Raspberry Pi or NVidia Jetson.

Now let’s setup the Processing GUI tool for easier control of OpenMANIPULATOR-X.

1. Download and install the Processing.

   • https://processing.org/download/

   NOTE : Processing source code is tested in Processing v3.5.4.

2. Launch Processing and go to Tools > Add Tool...

   

3. In the Libraries tab, search for ControlP5 and install it.

   

4. Download processing source code for OpenMANIPULATOR.

   • Direct Download(Zip)
   • or use Git tool

     $ git clone https://github.com/ROBOTIS-GIT/open_manipulator_processing.git
     

Please follow the official ROS 2 documentation to install the ROS 2 Jazzy.
For most Linux users, Debian package installation method is strongly recommended.

Please follow the official ROS 2 documentation to install the ROS 2 Humble.
For most Linux users, Debian package installation method is strongly recommended.

For beginners, it is strongly recommended to install ROS with the script provided in the below command.

$ sudo apt update
$ wget https://raw.githubusercontent.com/ROBOTIS-GIT/robotis_tools/master/install_ros_noetic.sh
$ chmod 755 ./install_ros_noetic.sh
$ bash ./install_ros_noetic.sh

Not required.

Supported ROS Version: ROS 2 Jazzy
This package is compatible only with ROS 2 Jazzy. Ensure that ROS 2 Jazzy is properly installed.

USB Port Permissions

To enable communication with the hardware, add your user to the dialout group:

$ sudo usermod -aG dialout $USER

A login and logout are required.

Clone the Repository

$ mkdir -p ros2_ws/src
$ cd ~/ros2_ws/src
$ git clone -b jazzy https://github.com/ROBOTIS-GIT/DynamixelSDK.git && \
  git clone -b jazzy https://github.com/ROBOTIS-GIT/dynamixel_interfaces.git && \
  git clone -b jazzy https://github.com/ROBOTIS-GIT/dynamixel_hardware_interface.git && \
  git clone -b jazzy https://github.com/ROBOTIS-GIT/open_manipulator.git

Install ROS 2 Dependencies

$ cd ~/ros2_ws
$ sudo rosdep init
$ rosdep update
$ rosdep install --from-paths src -y --ignore-src

Build the Package

$ colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release

Source the Workspace

$ source ~/ros2_ws/install/setup.bash

bashrc setting

Add the following to your ~/.bashrc for a convenient build alias:

$ echo "source /opt/ros/${ROS_DISTRO}/setup.bash" >> ~/.bashrc && \
  echo "source ~/ros2_ws/install/setup.bash" >> ~/.bashrc && \
  echo "alias cb='colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release'" >> ~/.bashrc
$ source ~/.bashrc

Create and apply udev rules

$ ros2 run open_manipulator_bringup om_create_udev_rules

Install dependent packages for OpenMANIPULATOR-X. Run the following commands in a terminal window.

$ sudo apt install \
  ros-humble-ros2-control \
  ros-humble-moveit* \
  ros-humble-gazebo-ros2-control \
  ros-humble-ros2-controllers \
  ros-humble-controller-manager \
  ros-humble-position-controllers \
  ros-humble-joint-state-broadcaster \
  ros-humble-joint-trajectory-controller \
  ros-humble-gripper-controllers \
  ros-humble-hardware-interface \
  ros-humble-xacro

$ mkdir -p colcon_ws/src
$ cd ~/colcon_ws/src/
$ git clone -b humble https://github.com/ROBOTIS-GIT/DynamixelSDK.git
$ git clone -b humble https://github.com/ROBOTIS-GIT/open_manipulator.git
$ git clone -b humble https://github.com/ROBOTIS-GIT/dynamixel_hardware_interface.git
$ git clone -b humble https://github.com/ROBOTIS-GIT/dynamixel_interfaces.git
$ cd ~/colcon_ws && colcon build --symlink-install

Set the ROS environment for PC

$ echo 'source /usr/share/gazebo/setup.sh' >> ~/.bashrc
$ echo 'source ~/colcon_ws/install/local_setup.bash' >> ~/.bashrc
$ source ~/.bashrc

The following commands will download OpenMANIPULATOR-X package source codes and build them.

1. Install dependent pacakges

   $ source ~/.bashrc
   $ sudo apt-get install ros-noetic-ros-controllers ros-noetic-gazebo* ros-noetic-moveit* ros-noetic-industrial-core
   $ sudo apt install ros-noetic-dynamixel-sdk ros-noetic-dynamixel-workbench*
   $ sudo apt install ros-noetic-robotis-manipulator
   

2. Download and build OpenMANIPULATOR-X packages

   $ cd ~/catkin_ws/src/
   $ git clone -b noetic https://github.com/ROBOTIS-GIT/open_manipulator.git
   $ git clone -b noetic https://github.com/ROBOTIS-GIT/open_manipulator_msgs.git
   $ git clone -b noetic https://github.com/ROBOTIS-GIT/open_manipulator_simulations.git
   $ git clone -b noetic https://github.com/ROBOTIS-GIT/open_manipulator_dependencies.git
   $ cd ~/catkin_ws && catkin_make
   

Not required.

There are two communication interface hardware options available for controlling the OpenMANIPULATOR-X. Please select one of the below options.
After completing this section, turn on the power switch and check if all DYNAMIXEL LED blink once.

$ ros2 run open_manipulator_bringup om_create_udev_rules

$ cat /sys/bus/usb-serial/devices/ttyUSB0/latency_timer

There are two communication interface hardware options available for controlling the OpenMANIPULATOR-X. Please select one of the below options.
After completing this section, turn on the power switch and check if all DYNAMIXEL LED blink once.

$ ros2 run open_manipulator_x_bringup create_udev_rules

$ cat /sys/bus/usb-serial/devices/ttyUSB0/latency_timer

There are two communication interface hardware options available for controlling the OpenMANIPULATOR-X. Please select one of the below options.
After completing this section, turn on the power switch and check if all DYNAMIXEL LED blink once.

$ roscore

$ rosrun open_manipulator_controller create_udev_rules

$ cat /sys/bus/usb-serial/devices/ttyUSB0/latency_timer

Not required.