Skip to main content

Quick Start Guide

This step by step quick start guide for running OpenMANIPULATOR-X on ROSTM 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.

tip

NOTE

  • OpenMANIPULATOR-X is operable as a standalone device without ROS when connected with an Arduino programmed OpenCR1.0.

  • Please select Arduino at the top of each page as below to find more details.

Setup​

Docker Environment​

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
warning

WARNING: When stopping the container, you'll be asked for confirmation as this will remove all unsaved data in the container.

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
danger

IMPORTANT: Data Persistence Rules:

  • Data in /workspace inside the container is saved to docker/workspace on your host
  • Container restart (using docker restart) maintains all data
  • Container removal (using container.sh stop) will remove all data except what's in the mapped /workspace directory
  • Always save your work in the /workspace directory to ensure it persists after container removal
tip

Setup Complete: Docker environment is now ready! Please proceed to the next section to configure the Communication Interface.

Install Ubuntu on PC​

info
info

NOTE: For ROS 2 Jazzy, we recommend using Docker for a more reliable and isolated development environment. Please refer to the Docker Environment section for Docker installation instructions.

:::

warning

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.

Install ROS on PC​

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

Install ROS Packages​

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

Communication Interface​

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.

Option 1(Recommended) : Use U2D2 as a communication interface

U2D2 Connection​

Connect micro USB (connected to PC), DYNAMIXEL's(OpenMANIPULATOR-X), and 12V Power to U2D2 and U2D2 power hub board as shown below.

info

NOTE : Please refer to U2D2 e-Manual and U2D2 power hub board e-manual for detailed connection of U2D2 and U2D2 power hub board.

USB Latency Timer Setting​

info
Option 1: Using Docker​

If you are using the Docker environment, the USB latency timer setting is already configured. You can proceed directly to the next section.

Option 2: Host Installation​

In Linux(Ubuntu platform) environment, USB latency time is set to 16ms by default. Follow the steps below to set the communication latency time to the lowest value (1ms) between DYNAMIXEL's and PC connected via USB.

Open a terminal window and enter the following command to set usb latency time. The command below will set the USB latency to 1 ms.

note

TIP: You can open a new terminal window by pressing CTRL + ALT + T.

$ ros2 run open_manipulator_bringup om_create_udev_rules
note

TIP: If you would like to see the current latency, enter the following command in the terminal.

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

Option 2 : Use OpenCR as a communication interface

This section describes how to set up OpenCR as a communication board between ROS Packages of PC and DYNAMIXEL's of OpenMANIPULATOR-X.

OpenCR Connection​

Connect micro USB (connected to PC), DYNAMIXEL's(OpenMANIPULATOR-X), and 12V Power to OpenCR as shown below.

Upload Source code​

  1. Set up the Arduino IDE for OpenCR (Instructions)

  2. Connect OpenCR to the PC.

  3. Open the example from File > Examples > OpenCR > 10.Etc > usb_to_dxl

Open the usb to dxl example.

  1. Upload the example to OpenCR.

  2. When the upload is completed, the following comments are displayed in the log window.

warning

FAQ
If upload fails, try with Recovery Mode

  1. Turn on the power of the OpenCR board.
  2. Hold down the PUSH SW2 button.
  3. Press the Reset button.
  4. Release the Reset button.
  5. Release the PUSH SW2 button.

The STATUS LED should blink every 100ms after entering Recovery Mode successfully.

Last updated on