Edit on GitHub

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.

NOTE

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

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

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.

NOTE

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

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

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.

Setup

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.

  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.

FAQ

  • If firmware upload fails, try uploading with the recovery mode. Below sequence activates the recovery mode of OpenCR. Under the recovery mode, the STATUS led of [OpenCR] will blink periodically.
    1. Hold down the PUSH SW2 button.
    2. Press the Reset button.
    3. Release the Reset button.
    4. Release the PUSH SW2 button.

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.

    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

Install Ubuntu on PC

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.

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.

Not required.

Install ROS on PC

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

Click to expand : Manual ROS Installation

Please be aware that this manual installation takes a lot more time than installing with the script, but allows flexible choice of package installation. This instruction is not recommended for the beginners.
Below instruction is based on the official ROS Kinetic installation guide.

  1. Setup the sources.list 
    $ sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list'
  2. Set up the keys 
    $ sudo apt install curl
$ curl -s https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | sudo apt-key add -
  3. Install ROS 
    $ sudo apt update
$ sudo apt install ros-noetic-desktop-full
  4. Dependencies for building packages 
    $ sudo apt install python3-rosdep python3-rosinstall python3-rosinstall-generator python3-wstool build-essential
  5. Initialize rosdep 
    $ sudo rosdep init
$ rosdep update
  6. ROS Environment setup
    Please do NOT enter below commands if you have installed ROS with the script file.
    The install_ros_noetic.sh script file automatically configures the basic ROS environment. 
    $ sudo apt install git
$ mkdir -p ~/catkin_ws/src
$ catkin_init_workspace
$ cd ~/catkin_ws && catkin_make
$ echo "source /opt/ros/noetic/setup.bash" >> ~/.bashrc
$ echo "source ~/catkin_ws/devel/setup.bash" >> ~/.bashrc
$ echo "export ROS_MASTER_URI=http://localhost:11311" >> ~/.bashrc
$ echo "export ROS_HOSTNAME=localhost" >> ~/.bashrc"
$ source ~/.bashrc

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

Not required.

Install ROS Packages

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

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

$ sudo apt install \
  ros-humble-dynamixel-sdk \
  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/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

Not required.

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

Connection

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

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

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 run the roscore.

$ roscore

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

While the roscore running, open a new terminal window and enter the following command to set usb latency time. The command below will set the USB latency to 1 ms.

$ rosrun open_manipulator_controller create_udev_rules

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.
If you want to operate OpenMANIPULATOR-X on embedded system (OpenCR) without ROS, please select the Arduino tab at the top of the page.

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.

  4. Upload the example to OpenCR.

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

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.

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

Connection

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

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

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.

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

$ ros2 run open_manipulator_x_bringup create_udev_rules

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.

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.

  4. Upload the example to OpenCR.

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

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.

Not required.