arm_api2

🦾 API for robotic manipulators based on:

• Moveit2
• ROS 2

Docker for building required environment can be found here.

For building ROS 2 packages and moveit, it is neccessary to use colcon.

Tell us anonymously what arms we should support here. 😄

Depends on:

• arm_api2_msgs

Aditional dependencies are (depending on the arm you use):

• kinova
• panda_sim
• ur
• ur_sim

Aim of the repository

With arm_api as precursor, which was intended to provide simple ROS interfacing with robot manipulators with the help of MoveIt! and ROS.

This repository arm_api2 is intended to provide interfacing support for robot manipulators for ROS 2 and MoveIt2!.

Goals

Create API simple to run and maintain that supports working with different robot manipulators out of the box.

Robot manipulators of interest are:

• Franka Emika
• UR
• Kinova
• Kuka

Wanted arm functionalities:

1. go_to_pose
2. grasp
3. release
4. push
5. <something_else?>

ROS 2 robot interface:

Change robot state:

• srv: /arm_api2_msgs/srv/ChangeState.srv
• values JOINT_TRAJ_CTL || CART_TRAJ_CTL || SERVO_CTL

Command robot pose:

• msg: geometry_msgs/msg/PoseStamped.msg

Command cartesian path:

• msg: arm_api2_msgs/msg/CartesianWaypoints.msg

Command gripper closing:

• srv: std_srvs/srv/Trigger.srv

Command gripper opening:

• srv: std_srvs/srv/Trigger.srv

Get current end effector pose:

• msg: geometry_msgs/msg/PoseStamped.msg

Robot states

Currently implemented and available robot states are:

• JOINT_TRAJ_CTL, which is used for joint control
• CART_TRAJ_CTL, which is used for cartesian control
• SERVO_CTL, which is used for the end effector servoing

Change robot state by calling:

ros2 service call /change_state arm_api2_msgs/srv/ChangeState "{state: JOINT_TRAJ_CTL}

How to build package?

Build:

Build in ROS 2 workspace. Build just one package with:

colcon build --packages-select arm_api2

Build with the compile commands (enable autocomplete):

colcon build --symlink-install --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

Building with --symlink-install causes it to fail often because of already built ROS 2 packages, you can run:

colcon build --symlink-install --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDS=ON --continue-on-error

Full verbose build command:

colcon build --symlink-install --packages-select moveit2_tutorials --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DCMAKE_VERBOSE_MAKEFILE=ON

Simplify your life

Aliases

Copy to ~/.bashrc and source it.

alias cbp="colcon build --symlink-install --packages-select" 
alias panda_sim="ros2 launch panda gz.launch.py"
alias kinova_sim="ros2 launch kortex_bringup kortex_sim_control.launch.py dof:=7 use_sim_time:=true launch_rviz:=false" 
alias ur_sim="ros2 launch ur_simulation_gz ur_sim_control.launch.py ur_type:=\"ur10\""

Build arm_api2 package as:

cbp arm_api2

Start franka sim with:

franka_sim

Start kinova sim with:

kinova_sim

Start ur sim with:

ur_sim

Start iface by changing robot_name argument to kinova, ur or franka. Depending which arm you want to use, when running:

ros2 launch arm_api2 moveit2_iface.launch.py robot_name:=<robot_name>

Tmunxinator

Start kinova with:

tmuxinator start kinova_api2

after calling

./copy_tmuxinator_config.sh kinova_api2.yml

located in utils/tmux_configs. Navigate between panes with Ctrl+B+(arrows).

How to use Kinova?

You can run kinova in simulation by executing following commands:

ros2 launch kortex_bringup kortex_sim_control.launch.py dof:=7 use_sim_time:=true launch_rviz:=false

or

kinova_sim

if alias has been added.

After that run move_group node as follows:

ros2 launch kinova_gen3_7dof_robotiq_2f_85_moveit_config sim.launch.py

After that run arm_api2 moveit2_iface node as follows:

ros2 launch arm_api2 moveit2_iface.launch.py robot_name:="kinova"

Kinova

How to setup real kinova here.

How to use UR?

How to use?

You can run UR in simulation by executing following commands:

ros2 launch ur_simulation_gz ur_sim_control.launch.py ur_type:="ur10"

or

ur_sim

if alias has been added.

After that run move_group node as follows:

ros2 launch ur_moveit_config ur_moveit.launch.py ur_type:="ur10" use_sim_time:=true

After that run arm_api2 moveit2_iface node as follows:

ros2 launch arm_api2 moveit2_iface.launch.py robot_name:="ur"

How to setup?

First run:

sudo apt-get install ros-humble-ur

After that, in your ROS 2 workspace clone:

• ur_gz_sim
• ur_ros2_driver
  and build your workspace. Source it, and you're good to go.

Note, those are forks of the official UR repositories on the humble branch, with slight changes to the launch files.

How to use with custom arm?

In order to use this package with custom arm, you need to do following:

1. Create moveit_package for your arm using moveit_setup_assistant. Tutorial on how to use it can be be found here. Output of the moveit_setup_assistant is <custom_arm>_moveit_config package.

2. Create config files:

a) Create <custom_arm>_config.yaml and <custom_arm>_servo_config.yaml in the config folder. b) Modify moveit2_iface.launch.py script by setting correct robot argument to the <custom_arm> value.

3. Setup robot launch file:

In order to be able to use <custom_arm> please make sure that you set following parameters to true when launching moveit_group node (generated by moveit_setup_assistant):

    publish_robot_description_semantic = {"publish_robot_description_semantic": True}
    publish_robot_description = {"publish_robot_description": True}
    publish_robot_description_kinematics = {"publish_robot_description_kinematics": True} 

as shown here.

4. Launch:

a) Launch your robot (see examples on kinova, UR or Franka) - move_group node b) Launch moveit2_iface.launch.py with correct robot param.

Arm interfaces

• franka_ros2
• kinova_ros2
• UR_ros2

Useful learning links

• Declare variables as const
• Complicated variable initialization
• C++ good practices
• MoveIt2! C++ iface
• How to setup VSCode
• First Cpp node for ROS 2
• Composition of ROS nodes
• planning_scene
• custom moveit ns
• publish robot_description
• joint state clock not in sync
• issue for initializing MGI

Status

TODO [High priority]:

• Fix command/reached pose mismatch!
• Add orientation normalization
• Add contributing
• Add gripper abstract class
• Add correct inheritance for the gripper abstract class
• Create universal launch file
• Create standardized joystick class
• Test/Test/Test

TODO [Low priority]:

• Test with real robot manipulator [tested on Kinova, basic functionality tested]
• Add basic documentation
• Add roadmap
• Discuss potential SW patterns that can be used
• Add full cartesian following
• Add roll, pitch, yaw and quaternion conversion
• Decouple moveit2_iface.cpp and utils.cpp (contains all utils scripts)
• Create table of supported robot manipulators

Supported arms table

Arms	CART_TRAJ_CTL	JOINT_TRAJ_CTL	SERVO_CTL	SIM	REAL	EXT_TEST
Franka Emika	+	+	+	+	-	-
Kinova	+	+	+	+	-	-
UR	+	+	+	+	-	-
IIWA	-	-	-	-	-	-

Roadmap

timeline
    4/2024 : Start of the development
    6/2024 : Open-sourced version
    9/2024 : Tested on one manipulator
    10/2024: Integrated with GUI 
    11/2024: Integrated with perception capabilities
    12/2024 : Tested on 5 manipulators
    .../2025 : TBA

Loading

If you want to contribute, please check Status section and check CONTRIBUTE.