PythonOverROS

• Introduction
• Usage
• Performance
• Repositories
  • ROS 1
  • ROS 2

Introduction

The goal of the dVRK Python package is to be able to write a simple application in Python that communicates with the dVRK console using ROS as middleware.

There are two versions of the dVRK Python package, one for ROS 1 and one for ROS 2. If you installed the dVRK software stack using vcs, the correct dVRK Python package will already be in your workspace.

The dVRK Python packages are based on the CRTK Python client libraries: ROS 1, ROS 2. The API follows the CRTK naming convention: https://crtk-robotics.readthedocs.io.

The Python packages main features are:

• Wrappers around the ROS Python libraries (either rospy or rclpy) so the user doesn't have to deal with creating ROS publishers, subscribers...
• Simple classes to interact with the dVRK arms, console, foot pedals... and methods to access most features
• Conversion to convenient data types, PyKDL for cartesian data and numpy for vectors and matrices
• New in 2.2, a ROS version independent API (crtk.ral for ROS Abstraction Layer) so you can use the same script for the dVRK with ROS 1 or ROS 2. This can be useful if you're starting with ROS 1 and plan to move to ROS 2 later or want to share your code with someone using a different version of ROS

Both the ROS 1 and ROS 2 packages contain:

• dvrk Python module: defines the base class dvrk.arm as well as classes for the PSMs, MTMs, ECMs, console, foot pedals... which uses the dVRK ROS topics to communicate with the dvrk_console_json application included in the dvrk_robot ROS package
• scripts: collection of scripts used to calibrate and test the dVRK as well as examples

Usage

You will first need to start the dVRK console application.

For ROS 1:

  rosrun dvrk_robot dvrk_console_json -j your_console_config_file.json

For ROS 2:

  ros2 run dvrk_robot dvrk_console_json -j your_console_config_file.json

Once the console is running, you can check which arms are available by listing the available ROS topics.

For ROS 1:

  rostopic list

For ROS 2:

  ros2 topic list

You should see one namespace per arm, e.g. /PSM1, /MTML and/or /ECM based on your console configuration as well as /console.

Then in Python:

import crtk, dvrk

# create the ROS Abstraction Layer with the name of the node
ral = crtk.ral('dvrk_python_node')

# create a Python proxy for PSM1, name must match ROS namespace
p = dvrk.psm(ral, 'PSM1')

# wait and check until all the topics are connected
# default timeout is 5 seconds
ral.check_connections()

# spin to make sure subscribers callbacks are called
# this is required for ROS 2 and does nothing on ROS 1
# use for portability!
ral.spin()

# now you can home from Python
p.enable()
p.home()

# retrieve current info (numpy.array)
p.measured_jp()
p.measured_jv()
p.measured_jf()

# retrieve PID desired position and effort computed
p.setpoint_jp()
p.setpoint_jf()

# retrieve cartesian current and desired positions
# PyKDL.Frame
p.measured_cp()
p.setpoint_cp()

# move in joint space
# move is absolute (SI units)

# move multiple joints
import numpy
p.move_jp(numpy.array([0.0, 0.0, 0.10, 0.0, 0.0, 0.0]))

# move in cartesian space
import PyKDL
# start position
goal = p.setpoint_cp()
# move 5cm in z direction
goal.p[2] += 0.05
p.move_cp(goal).wait()

import math
# start position
goal = p.setpoint_cp()
# rotate tool tip frame by 25 degrees
goal.M.DoRotX(math.pi * 0.25)
p.move_cp(goal).wait()

To apply wrenches on MTMs, start ipython and type the following commands while holding the MTM (otherwise the arm will start moving and might bang itself against the console and get damaged).

# load and define the MTM
from dvrk import mtm
import crtk

ral = crtk.ral('mtm_node')
m = mtm(ral, 'MTML')
ral.check_connections()
ral.spin()

# When True, force direction is constant.  Otherwise force direction defined in gripper coordinate system
m.set_wrench_body_orientation_absolute(True)

# about 2N force in y direction
m.body.servo_cf(numpy.array([0.0, 0.0, 2.0, 0.0, 0.0, 0.0]))

# lock the MTM wrist orientation
m.lock_orientation_as_is()

# turn gravity compensation on/off
m.set_gravity_compensation(True)

# turn off forces
self.arm.body.servo_cf(numpy.array([0.0, 0.0, 0.0, 0.0, 0.0, 0.0]))

To access arm specific features (e.g. PSM, MTM, ...), you can use the derived classes psm or mtm. For example from dvrk.psm import *.

Performance

For the dVRK, one can use the classes dvrk.arm, dvrk.psm, dvrk.mtm... that use the crtk.utils to provide as many features as possible. This is convenient for general purpose testing, for example in combination with iPython to test snippets of code.

⚠️ BUT, there is a significant performance penalty when using the dvrk.xxx classes since they subscribe to more topics than generally needed. For your application, it is recommended to use your own class and only add the features you need to reduce the number of ROS messages and callbacks. See examples in the directory scripts, e.g. dvrk-bag-replay.py.

Repositories

These are provided for reference as they are automatically cloned when you use the vcs files provided for the dVRK

ROS 1

Directory in workspace	repository
crtk/crtk_msgs	https://github.com/collaborative-robotics/crtk_msgs
crtk/crtk_python_client	https://github.com/collaborative-robotics/crtk_python_client
dvrk/dvrk-ros /dvrk_python	https://github.com/jhu-dvrk/dvrk-ros

ROS 2

Directory in workspace	repository
crtk/crtk_msgs	https://github.com/collaborative-robotics/ros2_crtk_msgs
crtk/crtk_python_client	https://github.com/collaborative-robotics/ros2_crtk_python_client
dvrk/dvrk_python	https://github.com/jhu-dvrk/ros2_dvrk_python