Edit on GitHub

Tutorials

ROBOTIS-OP3 Bringup

Overview

This chapter explains how to run ROBOTIS-OP3. op3_bringup demo launches op3_manager.
Several modules of op3_manager are controlling ROBOTIS-OP3 and various topics and services transmit commands and report status.
The op3_manager cooperates with other programs such as op3_demo and op3_gui_demo.

Reference : op3_manager

Test environment

Getting started

Download & Build

Reference : Installing ROBOTIS ROS Package

Stop the Linux service that run default demo

ROBOTIS-OP3 runs default demo automatically. If you would run op3_bringup demo, you have to stop the default demo service.

$ sudo service OP3-demo stop
[sudo] password for robotis: 111111

Bringup

Type below commands in the terminal window.

$ roslaunch op3_bringup op3_bringup.launch

Note that, if op3_bringup package is missing, update the package to download the missing pacakge by following the given insturction.

$ cd ~/catkin_ws/src/ROBOTIS-OP3-Demo
$ git pull
$ cd ~/catkin_ws
$ catkin_make

Execution result

When op3_bringup runs, robot moves to initial posture.

  1. execution result screen

    If you get an error for offset.yaml, run op3_offset_tuner(server and client) and save the offset.

  2. execution result of ROBOTIS-OP3(Init pose in RVIZ)

  3. It’s ready to move, now user can control ROBOTIS-OP3 using a program such as op3_gui_demo.

  4. If user turn off the program, press ctrl+c in terminal window.

op3_bringup.launch

<?xml version="1.0" ?>
<launch>        
  <!-- OP3 Manager -->
  <include file="$(find op3_manager)/launch/op3_manager.launch" />

  <!-- UVC camera -->
  <node pkg="usb_cam" type="usb_cam_node" name="usb_cam_node" output="screen">
    <param name="video_device" type="string" value="/dev/video0" />
    <param name="image_width" type="int" value="1280" />
    <param name="image_height" type="int" value="720" />
    <param name="framerate " type="int" value="30" />
    <param name="camera_frame_id" type="string" value="cam_link" />
    <param name="camera_name" type="string" value="camera" />
  </node>
</launch>

Visualization

Type below commands in the terminal window for visualization.

$ roslaunch op3_bringup op3_bringup_visualization.launch

op3_bringup_visualization.launch

<?xml version="1.0" ?>
<launch>
  <param name="robot_description" command="$(find xacro)/xacro.py '$(find op3_description)/urdf/robotis_op3.urdf.xacro'"/>

  <!-- Send fake joint values and monitoring present joint angle -->
  <node pkg="joint_state_publisher" type="joint_state_publisher" name="joint_state_publisher">
    <param name="use_gui" value="TRUE"/>
    <rosparam param="/source_list">[/robotis/present_joint_states]</rosparam>
  </node>

  <!-- Combine joint values -->
  <node pkg="robot_state_publisher" type="state_publisher" name="robot_state_publisher">
    <remap from="/joint_states" to="/robotis/present_joint_states" />
  </node>

  <!-- Show in Rviz   -->
  <node pkg="rviz" type="rviz" name="rviz" args="-d $(find op3_bringup)/rviz/op3_bringup.rviz"/>
</launch>

Description

This section explains configuration files used in op3_manager(within op3_bringup.launch).

Robot file(.robot)

Information of the robot to operate.
Control frequency, communication interface, baud rate, available devices and their properties are defined.

Reference : Robot Information file(.robot)

Joint Initialize File (.yaml)

Set initialization values for properties of DYNAMIXEL or sensor.

Reference : Joint initialize file(.yaml)

Offset file(.yaml)

If the robot is mechanically distorted due to assembly tolerance and other reasons, adjusting offset can help to correct the error.
Offset file contains offset angles of each joint(radian) to correct distortion and initial posture joint angles for Offset Tuner.

Reference : How to use offset tuner

How to execute Default Demo

Overview

This chapter explains how to play basic demonstrations of OP3. There are three available demos; playing soccer, vision and sequence of various actions.

Reference : op3_demo

Getting started

Download & Build

Reference : Installing ROBOTIS ROS Package

Run

  1. Auto Start
    ROBOTIS-OP3 begins to play demo when startup.

  2. Manual Start
    Connect to ROBOTIS-OP3 and open the terminal window. Acquire the root permission and execute the launch file.
    Enter the following commands in the terminal.
    (password : 111111)
    The demo launch file executes op3_demo and op3_manager.

  $ sudo bash
  [sudo] password for robotis: 111111
  # roslaunch op3_demo demo.launch

Execution result

DYNAMIXEL of ROBOTIS-OP3 will be powered and take the initial posture.

Description

Button Functions

From the left, each button is assigned for Mode, Start, User and Reset.

Soccer Demo

  1. How to play Press the mode button once from demonstration ready mode to switch to autonomous soccer mode, then play soccer demo by pressing the start button.
    (ROBOTIS-OP3 will announce “Autonomous soccer mode” and red LED in the back will be lit.)
    When the demo begins, ROBOTIS-OP3 will announce “Start soccer demonstration” and stand up to search for a ball.
    If desired ball is detected, walk close to the ball and kick it.

  2. Setting Walking Parameters Walking motion imports parameters saved in the op3_walking_module in op3_manager. Default parameters can be configured by using walking tuner in the op3_gui_demo.

    Reference : How to use walking tuner

  3. Return to Demonstration Ready Mode
    Pressing and holding the mode button for 3 seconds will make ROBOTIS-OP3 to take the initial posture and return to Demonstration ready mode.

Vision Demo

  1. How to Play Press the mode button twice from demonstration ready mode to switch to vision processing mode, then play vision demo by pressing the start button. (ROBOTIS-OP3 will announce “Vision processing mode” and green LED in the back will be lit.)
    When the demo begins, ROBOTIS-OP3 will announce “Start vision processing demonstration” and stand up to search for a face.
    If a face is detected, RGB-LED on the chest and back turns into white color and OP3’s head will follow the detected face.

    Reference : Face Tracker - ROS Package

  2. Return to Demonstration Ready Mode
    Pressing and holding the mode button for 3 seconds will make ROBOTIS-OP3 to take the initial posture and return to Demonstration ready mode.

Action Demo

  1. How to Play Press the mode button thrice from demonstration ready mode to switch to interactive motion mode, then play action demo by pressing the start button. (ROBOTIS-OP3 will announce “Interactive motion mode” and blue LED in the back will be lit.)
    When the demo begins, ROBOTIS-OP3 will start playing predefined action sequence along with audio.
    action_script.yaml contains motion and audio bundles.

  2. action_script.yaml file description
    • File path : /op3_demo/script/action_script.yaml

    • Contents

      # combination action page number and mp3 file path
action_and_sound:
  4 : "/home/robotis/catkin_ws/src/ROBOTIS-OP3/ROBOTIS-OP3-Demo/op3_demo/Data/mp3/Thank you.mp3"
  41: "/home/robotis/catkin_ws/src/ROBOTIS-OP3/ROBOTIS-OP3-Demo/op3_demo/Data/mp3/Introduction.mp3"
  24: "/home/robotis/catkin_ws/src/ROBOTIS-OP3/ROBOTIS-OP3-Demo/op3_demo/Data/mp3/Wow.mp3"
  23: "/home/robotis/catkin_ws/src/ROBOTIS-OP3/ROBOTIS-OP3-Demo/op3_demo/Data/mp3/Yes go.mp3"
  15: "/home/robotis/catkin_ws/src/ROBOTIS-OP3/ROBOTIS-OP3-Demo/op3_demo/Data/mp3/Sit down.mp3"
  1: "/home/robotis/catkin_ws/src/ROBOTIS-OP3/ROBOTIS-OP3-Demo/op3_demo/Data/mp3/Stand up.mp3"
  54: "/home/robotis/catkin_ws/src/ROBOTIS-OP3/ROBOTIS-OP3-Demo/op3_demo/Data/mp3/Clap please.mp3"
  27: "/home/robotis/catkin_ws/src/ROBOTIS-OP3/ROBOTIS-OP3-Demo/op3_demo/Data/mp3/Oops.mp3"
  38: "/home/robotis/catkin_ws/src/ROBOTIS-OP3/ROBOTIS-OP3-Demo/op3_demo/Data/mp3/Bye bye.mp3"

# play list
default: [4, 41, 24, 23, 15, 1, 54, 27, 38]
    • action_and_sound : Combined information of page number of action file and mp3 file path to play with
      action number : mp3 file path
    • default : Play list of action and sound in the interactive motion mode
  3. Return to Demonstration Ready Mode
    Pressing and holding the mode button for 3 seconds will make ROBOTIS-OP3 to take the initial posture and return to Demonstration ready mode.

How to execute GUI program

Reference : op3_gui_demo

Run the program

There are three options to run the GUI program.

  1. Connect input devices and display device directly to ROBOTIS-OP3 and run the GUI program on the robot.
  2. Use VNC from a remote PC to obtain control over the OP3 SBC(Intel NUC) and initiate the GUI program remotely.

  3. Run the GUI program on a remote PC in the same ROS network with ROBOTIS-OP3.
    Open the terminal window and enter the following command.
    op3_manager should be running before executing GUI demo program.

     $ roslaunch op3_gui_demo op3_demo.launch

    Reference : How to run op3_manager

How to take the initial pose of ROBOTIS-OP3

Clicking the button surrounded by the red dashed rectangle will let the base_module control each joint of ROBOTIS-OP3 and take the initial posture.

How to set the Module

How to use walking tuner

Overview

This chapter explains how to configure walking parameters and test them with ROBOTIS-OP3.
Basic demo uses saved walking parameters.

Description

Setting Module

Activate walking_module on the lower body part of ROBOTIS-OP3 for walking test.
Confirm that the joints used for walking are set as walking_module, then move to Walking tab.
(When the walking module is activated, ROBOTIS-OP3 will take the initial posture for walking.)

Start / Stop Walking
  1. start button : Initiate walking
  2. stop button : Stop walking. When stopped, walking related parameters will be reset.

Apply Parameters
  1. Refresh button : Acquire all parameter currently applied on walking_module.
  2. Save button : Save all parameter currently applied on walking_module as default parameter and use it for other program such as op3_demo.
  3. Apply button : Apply modified parameters from the GUI to walking_module.

How to play the motions

Overview

This chapter explains how to play predefined actions.
The action_module controls each joint of ROBOTIS-OP3.

Reference : op3_action_module

Description

How to play
  1. Set the module : Press the action_module button.

  2. Select Motion tab of the gui demo program.

  3. Click the action button to play

Creating and editing actions for action_module

Reference : How to create the motions

How to control the head joints

Overview

This chapter explains how to control the head joint of ROBOTIS-OP3.
Operator can get different camera view angle by controlling head joints.

Reference : op3_head_control_module

Head Joint Control

Setting the Module : Click head_control_module button
Select Head Control tab of the gui demo program.

Change the value for the specific joint.
  1. Use the slide bar to control the head joint.
  2. Enter desired values in the text box to control the head joint.
  3. Bring the head joint to center position.

How to control upgraded walking(online walking)

Overview

This page explains how to control upgraded walking(online walking).

Reference 1 : Introduction to Humanoid Robotics

Reference 2 : op3_online_walking_module

Description

How to

Online walking using footstep planner

Reference : Online walking using footstep planner

How to use offset tuner

Overview

deprecated
This chapter has been merged into How to use tuner client

Reference : op3_offset_tuner_server
Reference : op3_offset_tuner_client

How to use tuner client

Overview

this chapter explains how to adjust kinematic offset and position gain of ROBOTIS-OP3. In the past, we were able to adjust the offset by using op3_offset_server and op3_offset_client. Now we can set both offset and gain using new op3_tuning_module and op3_tuner_client. we made an op3_tuning_module and used it with op3_manager, so you do not need to run the server for using just to tune the offset.

Reference : op3_tuning_module
Reference : op3_tuner_client

Run Tuner Program

How to launch programs

Launching op3_manager and op3_tuner_client program separately

Tuner is consisted of op3_manager and client program so that other PC in the same ROS network can tune offsets and gains.

Execute the op3_manager first.
(Other programs such as op3_action_editor and op3_walking_tuner should be terminated to run the op3_manager`).

$ roslaunch op3_manager op3_manager.launch

After starting the op3_manager, execute client GUI program from the identical PC or any PCs in the same ROS network.

$ roslaunch op3_tuner_client op3_tuner_client.launch

Launching op3_manager and op3_tuner_client program at once

Enter the following commands in the terminal window.
(Other programs such as op3_action_editor and op3_walking_tuner should be terminated to run the offset tuner.)

$ roslaunch op3_tuner_client op3_tuner.launch

launch image

Configuration Files

op3_manager configuration files

op3_tuning_module configuration files

op3_tuner_client configuration file

How to use tuner client GUI program

How to tune the offset

  1. go Initial Pose
  2. Select tab of Kinematics Group
  3. Click the Refresh Button for getting current states of joints
  4. tune the offset of joints
  5. Click the Save Offset button for saving to file.

How to tune the gain

  1. go Initial Pose
  2. Select tab of Kinematics Group
  3. Click the Refresh Button for getting current states of joints
  4. change the pose and tune the gain of joints for watching the graph of the joint
    (If you want to tune other joint, delete topics and add topics that you want to tune)
  5. Click the Save Gain button for saving to file.

Reference : Order of the joint name in the topic(/robotis/goal_joint_states)

  0 : haed_pan  
  1 : haed_tilt  
  2 : l_ank_pitch  
  3 : l_ank_roll  
  4 : l_el  
  5 : l_hip_pitch  
  6 : l_hip_roll  
  7 : l_hip_yaw  
  8 : l_knee  
  9 : l_sho_pitch  
  10 : l_sho_roll  
  11 : r_ank_pitch  
  12 : r_ank_roll  
  13 : r_el  
  14 : r_hip_pitch  
  15 : r_hip_roll  
  16 : r_hip_yaw  
  17 : r_knee  
  18 : r_sho_pitch  
  19 : r_sho_roll

If you want to check in your hand, type like the belows

  $ rostopic echo /robotis/goal_joint_states -n 1

How to create the motions

Overview

ROBOTIS-OP3 Action Editor Node.
This chapter explains how to create and edit action file used in the op3_action_module of ROBOTIS-OP3.

Action File

The action file contains ROBOTIS-OP3’s poses and time data. The current position describes positions of DYNAMIXEL which converted from actual DYNAMIXEL resolution to 4,095 resolution. The action file is written as binary file so users can read its contents with op3_action_editor. ROBOTIS currently provides a default action file with source code. It is located in “op3_action_module/data” directory.

The action file contains 256 pages. Each page can store up to 7 stages (or steps) of action data. The default action file does not use all pages and user can add own actions by writing them on the empty page.

Getting started

Download & Build

Reference : Installing ROBOTIS ROS Package

Run

Execute the launch file.
op3_action_editor has a direct control over ROBOTIS-OP3, therefore other control programs such as op3_manager, op3_offset_tuner and op3_walking_tuner should not be running.
Before executing the op3_action_editor launch file, other programs should be terminated.

$ roslaunch op3_action_editor op3_action_editor.launch

UI

It is strongly advised that when user tests user’s own newly-created or edited actions, there should be small incremental changes in position, speed/time, and pause values for the sake of ROBOTIS-OP3’s stability.

The Contents of The Default Action File

The below table shows the contents of the default action file.

page number page title brief description of page number of pages
1 walki_init initial standing pose 1
2 hello greeting 1
3 thank_you Thank you 1
4 yes yes 1
5 no no 1
6 fighting fighting 1
7 clap clap 2
9 S_H_RE ready for shaking hands 1
10 S_H shaking hands 1
11 S_H_END move to initialpose fram ready pose for shaking hands 1
12 scanning looking around 1
13 ceremony ceremony 1

Basic Command of Action Editor

After typing “help”, the commend list will appear as shown below.

Example Action editing with op3_action_editor

  1. Run the op3_action_editor

  2. Find the page where the “walking_init page” is by typing “list”

  3. Exit the list and go to any blank page by typing “page [x]”(for example, page 15).

  4. And copy the page 1 to page [x].

  5. Go to “walking_init” pose by typing “play”

  6. Turn off the torque of ID 2, 4 and 8 by typing “off 2 4 8”

  7. After getting the desired pose turn torque on again by simple typing on. And insert the pose to step 1 by typing “i 1”

  8. Edit “Pause Time”, “Time” of STP1 and “Page Step” as shown below.

  9. Type “play” and check the ROBOTIS-OP3’s action

How to use ball detector

Overview

This chapter explains how to calibrate the ball_detector_node to find a ball. The ball_detector_node detects a ball by the designated color and Hough Circle Transform.

Getting started

Run the program

$ roslaunch ball_detector ball_detector_from_usb_cam.launch

or

$ roslaunch op3_demo demo.launch

How to change the parameters

  1. Dynamic Reconfigure and Image View

    • run the rqt

      $ rqt

    • Open Dynamic Reconfigure
      Select Plugins -> Configuration -> Dynamic Reconfigure

    • Open Image View
      Select Plugins -> Visualization -> Image View

  2. Parameters
    The description for each parameter will pop up when hovering the mouse cursor over each parameter.

    • gaussian_blur_size: Size of Gaussian Blur Kernel (odd value)
    • gaussian_blur_sigma: Std deviation of Gaussian Blur
    • canny_edge_th: Threshold of the edge detector
    • hough_accum_resolution: Resolution of the Hough accumulator, in terms of inverse ratio of image resolution
    • min_circle_dist: Minimum distance between circles
    • hough_accum_th: Accumulator threshold to decide center detection
    • min_radius: Minimum circle radius allowed, pixels. (if unknown, put 0 for a detault.)
    • max_radius: Maximum circle radius allowed, pixels. (if unknown, put 0 for a detault.)
    • filter_h_min: Minimum threshold of H filter
    • filter_h_max: Maximum threshold of H filter
    • filter_s_min: Minimum threshold of S filter
    • filter_s_max: Maximum threshold of S filter
    • filter_v_min: Minimum threshold of V filter
    • filter_v_max: Maximum threshold of V filter
    • use_second_filter: Use second filter
    • filter2_h_min: Minimum threshold of H filter
    • filter2_h_max: Maximum threshold of H filter
    • filter2_s_min: Minimum threshold of S filter
    • filter2_s_max: Maximum threshold of S filter
    • filter2_v_min: Minimum threshold of V filter
    • filter2_v_max: Maximum threshold of V filter
    • ellipse_size: Ellipse size
    • debug_image: Show filtered image to debug
  3. Description

    • How the ball_detector_node works
      ball_detector_node filters the HSV value first, then detect the ball with HoughCircles

    • How to calibrate

      • Set H(hue) value (color value) first with full range of S and V. Then set the range of S(saturation) and V(value) to remove the noise.
        Hue is measured by degrees within the cylindrically represented color system. Therefore, the value 360 can be represented as 0, and the minimum value can have a bigger number than the maximum value. (ex : min - 350 / max - 10 [Red area])

      • If you check the use_second_filter you can get an image which is detected with two HSV variations.

      • If you check the debug_image you can check the HSV filtered, binary image.

      • After you set the HSV range, you could calibrate the threshold value to detect the edge better.

How to control upgraded walking using footstep planner

Overview

This chapter explains upgraded walking and footstep planner.

Reference : op3_how_to_control_upgraded_walking

Getting started

Installation

Run the program

  1. op3_manager

     $ roslaunch op3_manager op3_manager.launch

  2. op3_gui_demo and footstep planner

     $ roslaunch op3_gui_demo op3_demo_walking.launch

  3. rviz for upgraded walking with footstep planner. If user want to launch a rviz in ROBOTIS-OP3, a monitor is connected to ROBOTIS-OP3.

     $ roslaunch op3_description op3_walking.launch

Walking with footstep planner

Preparation : Set the module and move to the tab
  1. Setting the module : Click online_walking_module button

  2. Select Online Walking tab of the gui demo program.

Controlling walking of ROBOTIS-OP3
  1. Go to initial pose : click Go to Initial Pose button
  2. Balance On

  3. Set the walking parameters

  4. Set a interactive marker in rviz 3d screen and Move the marker to the target pose of feet.

  5. plan the path and send a walking message to ROBOTIS-OP3

How to use Web Setting Tool

Overview

This chapter explains how to set the parameters of ROBOTIS-OP3 through a web page.

Reference : ROBOT WEB TOOL
Reference : web_video_server
Reference : rosbridge_server

Getting started

Installation

How to connect ROBOTIS-OP3 WiFi

Connect to ROBOTIS-OP3 WiFi with below information

How to run web setting tool

How to set parameters

  1. Demo : Control default demo of ROBOTIS-OP3.
  2. Soccer : Setting for ball_detector.
  3. Vision : View the status of the detected face.
  4. Action : Testing ROBOTIS-OP3 actions.
  5. Camera : Change the parameters of ROBOTIS-OP3 camera.
Ball Detector parameters

Modified parameter values will be saved automatically.

Reference : detail of parameter

Camera Setting parameters

Modified parameter values will be saved automatically.

Read-Write Tutorial

Overview

This chapter explains to user how to get joint angles of ROBOTIS-OP3 and how to set their values.

Framework Diagram

This is a framework diagram. The framework(op3_manager) works in the following way.

  1. Initialization
  2. Add sensors and motion modules

  3. Start the timer and run threads
    Execute the process function within the thread at a cycle of 8ms.
    The process function performs the following operations according to the mode.

    • DirectControlMode : This mode directly controls the robot using topics received from the user.

      1. BulkRead RX : Received rx packet containing joint information of each DYNAMIXEL
      2. SyncWrite : Transmit joint values to the multiple DYNAMIXEL’s to control
      3. BulkRead TX : Transmit tx packet to get information of dynamixel
      4. Call process() function of each sensor module
      5. Publish a topic that contains present & goal joint states

    • MotionModuleMode : This mode controls the robot using motion module.

      1. BulkRead RX : Received rx packet containing joint information of each DYNAMIXEL
      2. SyncWrite : Transmit goal values(position, velocity, current, position PID gain, velocity PID gain) to multiple DYNAMIXEL’s
      3. BulkRead TX : Transmit tx packet to get information of dynamixel
      4. Call process() function of each sensor module
      5. Call process() function of each motion module
      6. Publish a topic that contains present & goal joint states

Description

How to Get Joint States

How to Set Joint States

op3_manager provides a way to control each joint of the robot with the following two methods.

Reference : SyncWriteItem
Framework provides SyncWriteItem, a way to write to devices aperiodically.
If user send a SyncWriteItem message with the name of /robotis/sync_write_item, Framework try to sync-write to devices with those message.

Read-Write Demo

Download & Build

Reference : Installing ROBOTIS ROS Package

How to Run Demo

Stop the default demo

$ sudo service OP3-demo stop
[sudo] password for robotis: 111111

Run read-write demo

$ roslaunch op3_read_write_demo op3_read_write.launch

op3_read_write.launch

<?xml version="1.0" ?>
<launch>    
  <param name="gazebo"                   value="false"    type="bool"/>
  <param name="gazebo_robot_name"        value="robotis_op3"/>

  <param name="offset_file_path"         value="$(find op3_manager)/config/offset.yaml"/>
  <param name="robot_file_path"          value="$(find op3_manager)/config/OP3.robot"/>
  <param name="init_file_path"           value="$(find op3_manager)/config/dxl_init_OP3.yaml"/>
  <param name="device_name"              value="/dev/ttyUSB0"/>

  <param name="/robotis/direct_control/default_moving_time"     value="0.04"/>
  <param name="/robotis/direct_control/default_moving_angle"    value="90"/>

  <!-- OP3 Manager -->
  <node pkg="op3_manager" type="op3_manager" name="op3_manager" output="screen">
    <param name="angle_unit" value="30" />
  </node>

  <!-- OP3 Localization -->
  <node pkg="op3_localization" type="op3_localization" name="op3_localization" output="screen"/>

  <!-- OP3 Read-Write demo -->
  <node pkg="op3_read_write_demo" type="read_write" name="op3_read_write" output="screen"/>
</launch>

How to Operate

Source Code