README.md

Cyton Gamma 300 (GazeboSim/RealRobot + MoveIt)

1. Description
2. Packages
3. Installation
   1. Installation using docker
   2. Installation on the host
4. Quick start
   1. Quick start using docker
   2. Quick start on the host
5. Tutorial
   1. Tutorial using docker
   2. Tutorial on the host
6. Related Sources
7. Rationale
8. Maintainer

Description

The project includes a collection of ROS packages to simulate and actuate the Cyton Gamma 300 7-DOF robotic arm from Robai (the company Robai is no longer active). The simulation is done in Gazebo and the MoveIt is used as a motion planning framework. The code has been tested with the melodic distribution of ROS (as of May 2023).

Packages

• cyton_gamma_300_controllers: controllers for actuating gazebo model or the real robot using MoveIt;

• cyton_gamma_300_description: xacro description of the URDF robot model;

• cyton_gamma_300_gazebo: gazebo simulation of the robot;

• cyton_gamma_300_moveit: configuration files of the setup assistant to enable MoveIt functionality.

The aforementioned cyton_gamma_300_* packages enable motion planning for the Cyton Gamma 300 arm. These packages are not self-contained and the dependencies should be met to successfully run the software.

Installation

To visualize / simulate / control, one needs to install the dependencies, which the cyton_gamma_300_* packages require. One can either use docker or install the dependencies on the host machine. Docker is a recommended way of launching the code, as it encapsulates the dependencies and allows multiple ROS installations.

Installation using Docker

The repo provides a Dockerfile, from which the docker image with required pre-installed dependencies can be built. Makefile includes the targets to build the docker image and run the docker containers (see tutorial for details). On the host machine, one needs to install a recent version of docker and a docker compose plugin, follow the official installation instructions. As a result, docker and docker compose commands shall be available on your system.

Create the docker image with required dependencies:

make build

alternatively, on a system without make, run:

source .env && docker compose build cyton-gamma

In the remaining document we will refer to launching docker command via the corresponding make targets.

Installation on the host

One needs to install:

• a full version of ROS, otherwise some other packages might be missing (refer here for the full ROS installation instructions).
• MoveIt.
• OpenCV (refer here for the installation instructions).

In addition, the packages below must be found in your ROS workspace (or on your $ROS_PACKAGE_PATH):

• dynamixel_motor -- cyton_gamma_300_controllers depend on the package to actuate the robot motors;

• ros_controllers -- are instantiated in cyton_gamma_300_controllers;

• ros_control -- ros_controllers depend on this package;

• control_toolbox -- ros_controllers depend on this package;

• realtime_tools -- ros_controllers dependency;

• warehouse_ros -- required if one wants to use the warehouse database server while using motion planning (included by default when running moveit setup_assistant)

Fortunately, one can use available ROS tools to install missing dependencies (replace ${WORKSPACE} with a path to your catkin workspace and ${ROSDISTRO} with the name of the ROS distribution):

rosdep install --from-paths ${WORKSPACE} --ignore-src --rosdistro=${ROSDISTRO}`

Quick start: Plan & Execute

Quick start using docker

1. Launch RViz, MoveIt, and Gazebo simulation:

make gazebo-moveit

2. Lauch RViz, MoveIt for the physical robot:

make robot-moveit

In the section below we describe the steps to launch the MoveIt on the host without docker.

Quick start on host

1. Launch RViz, MoveIt, and Gazebo simulation:

roslaunch cyton_gamma_300_controllers gazebo_moveit.launch

2. Lauch RViz, MoveIt for the physical robot:

roslaunch cyton_gamma_300_controllers robot_moveit.launch

Tutorial

Tutorial using docker

1. Visualize the URDF model in RViz:

make urdf-in-rviz

2. Spawn the URDF model in Gazebo:

make urdf-in-gazebo

The model is subject to gravity forces and falls down from its original position.

3. Try out different types of ros_controllers in Gazebo simulation:

• E.g. JointPositionController from effort_controllers:

make joint-effort-controller

• Or another example of JointPositionController from position_controllers:

make joint-position-controller

• JointTrajectoryController from position_controllers allows to control groups of joints:

make joint-trajectory-controller

4. Specify a target pose in RViz, plan in MoveIt using OMPL and execute a plan in Gazebo:

make gazebo-moveit

5. Run MoveIt on the actual robot:

• Make sure read/write access to /dev/ttyUSB0 (assuming that /dev/ttyUSB0 is your dynamixel bus address). The following make target will start everything needed to plan and execute the plan on the actual robot:

make robot-moveit

• Alternatively, it is possible to launch the same functionality separately (e.g. for debugging purposes):

In a docker container we run a controller_manager.py script from dynamixel package that queries the stepper motors on the bus and initializes them. We logically separate motors 0-6 for the arm (or the manipulator planning group) and the stepper motor 7 for the gripper (the gripper planning group). We start initialization with the manipulator planning group:

make robot-manipulator-manager

In a separate terminal we launch a second docker container which spawns controllers that would activate the manipulator joints (i.e. motors 0-6 on the bus):

make robot-manipulator-controller-spawner 

In a separate terminal, we launch additional docker containers to launch controller_manager.py and controller_spawner for the arm gripper:

make robot-gripper-manager

make robot-gripper-controller-spawner

Finally, in an additional docker container we launch MoveIt:

make robot-moveit-movegroup

6. Run MoveIt setup assistant wizard:

make robot-moveit-setup-assistant

Tutorial on the host

In this tutorial the steps, mentioned for the docker are shown, with the packages and launch files one need to launch to achieve the same outcome as in the tutorial above. Feel free to skip this section completely.

1. Visualize the URDF model in RViz:

roslaunch cyton_gamma_300_description urdf_in_rviz.launch

2. Spawn the URDF model in Gazebo:

roslaunch cyton_gamma_300_gazebo gazebo_world.launch

The model is subject to gravity forces and falls down from its original position.

3. Test different types of ros_controllers in Gazebo simulation:

• E.g. JointPositionController from effort_controllers:

roslaunch cyton_gamma_300_controllers gazebo_effort_controllers.launch

• Or another example of JointPositionController from position_controllers:

roslaunch cyton_gamma_300_controllers gazebo_position_controllers.launch

• JointTrajectoryController from position_controllers allows to control groups of joints:

roslaunch cyton_gamma_300_controllers gazebo_joint_trajectory_controllers.launch

4. Specify a target pose in RViz, plan in MoveIt! using OMPL and execute a plan in Gazebo:

roslaunch cyton_gamma_300_controllers gazebo_moveit.launch

5. Run MoveIt on the actual robot:

• Make sure you are in the dialout group or you have read/write access to /dev/ttyUSB0 (assuming that /dev/ttyUSB0 is your dynamixel bus address). The following launch file will start everything one needs to plan and execute the plan on the actual robot:

roslaunch cyton_gamma_300_controllers robot_moveit.launch

• Alternatively, it is possible to launch the same functionality separately (e.g. for debugging purposes):

First, we need to run a controller_manager.py script from dynamixel package that queries the stepper motors on the bus and initializes them. We logically separate motors 0-6 for the arm (or the manipulator planning group) and the stepper motor 7 for the gripper (the gripper planning group). We start initialization with the manipulator planning group:

roslaunch cyton_gamma_300_controllers robot_manipulator_manager.launch

Second, we need to spawn controllers that would activate the manipulator joints (i.e. motors 0-6 on the bus):

roslaunch cyton_gamma_300_controllers robot_manipulator_controller_spawner.launch

Third, we need to repeat steps one and two for the gripper:

roslaunch cyton_gamma_300_controllers robot_gripper_manager.launch

roslaunch cyton_gamma_300_controllers robot_gripper_controller_spawner.launch

Finally, we bring up MoveIt:

roslaunch cyton_gamma_300_controllers robot_moveit_movegroup.launch

Related Sources

András Fekete pioneered in his blog and repo migrating Cyton Gamma 300 arm to open source software from manufacturer's proprietary one. I must confess that I was not able to run his code due to some errors, still he was a source of inspirations for the follow-up projects. Tyler Slabinski created beautiful meshes of the Cyton Gamma 300 arm and wrote the URDF file that others extensively use. AssistiveRoboticsUNH and Andreas Lydakis provided here and here respectively the repositories for running the actual robot using MoveIt, but did not include Gazebo support for simulations of Cyton Gamma 300.

Rationale

As already quite a lot of related sources exist on the github, the goal is (i) provide a functional step-by-step tutorial, (ii) to document the working setup for the current version of ROS, (iii) package dependencies in docker.

Maintainer

Dr. Konstantin Selyunin, for suggestions / questions / comments contact: selyunin [dot] k [dot] v [at] gmail [dot] com