Only released in EOL distros:  

Package Summary

SVH Driver wrapper to enable control of the Schunk five finger hand

Package Summary

SVH Driver wrapper to enable control of the Schunk five finger hand

Package Summary

SVH Driver wrapper to enable control of the Schunk five finger hand

Package Summary

SVH Driver wrapper to enable control of the Schunk five finger hand


This package provides the driver for controlling the Schunk Five Finger Hand with ROS-control for ROS1 and ROS2.


Please see the install instructions in the official Github repository. The driver communicates via a RS485-based protocol, for which the "Brainbox" USB to Serial converters have proven to work well. They are usually distributed together with the hand.



This node is interfacing with the Schunk Five Finger Hand and provides the ability to control the fingers and read out any feedback

Subscribed Topics

connect (std_msgs/Empty)
  • Tries to connect to the hardware when triggered. The hardware will use the serial_device that can be reconfigured via dynamic reconfigure
reset_channel (std_msgs/Int8)
  • Triggers a reset of the given channel (finger). See channel mapping below.
enable_channel (std_msgs/Int8)
  • Enables a given channel (finger). See channel mapping below.
channel_targets (sensor_msgs/JointState)
  • Target position the channels (fingers) shall move to. Note that it has less performance to give targets for individual channels or a subset of the available DoF than providing it for all at once. If 8 channels are given instead of 9 the driver will send 8 packets instead of 1 which might influence serial device performance. Only the names and positions will be evaluated from the JointState message.

Published Topics

channel_feedback (sensor_msgs/JointState)
  • Current position of the channels (fingers).
channel_currents (std_msgs/Float64MultiArray)
  • Current currents of the channels (fingers).
parameter_descriptions (dynamic_reconfigure/ConfigDescription)
  • Names, values and description of the current parameters
parameter_descriptions (dynamic_reconfigure/ConfigDescription)
  • Names, min/max values and description of the parameters in general
parameter_updates (dynamic_reconfigure/Config)
  • Names, values and description of the current parameters


~autostart (bool, default: true)
  • If set to true the controller will immediately try to connect to the hardware and start a reset of all the channels (fingers)
~serial_device (string, default: /dev/ttyUSB0)
  • Device handle to use for the serial communication, e.g /dev/ttyUSB0
~disable_flags (vector of bool, default: 9 x false)
  • Indicates if a channel (finger) should be disabled. If disabled a finger will not be activated by the hardware but behaves as if everything was fine. This can be used in case a finger has a hardware failure.
~reset_timeout (int, default: 5)
  • Time in seconds after which a reset of a channel (finger) is aborted if the reset current threshold can not be reached. If a channel (finger) needs to reach 300mA for detection of a hard stop but is stuck at 200mA the reset is aborted after reset_timeout seconds.
~finger_reset_speed (double, default: 0.2)
  • Dynamic reconfigure value. Speed of fingers during reset, given as percentage of their usual speed.
/robot_description (urdf model, default: URDF at description/urdf/svh-standalone.urdf.xacro)
  • Urdf model of the hand, including the joints and links describing the svh
~logging_config (string, default: /etc/logging.xml)
  • Path to the logging.xml file configuring the internal logging of the svh_driver library. If none is specified but the internal logging is enabled the output will be lost and warnings will be given.
~use_internal_logging (bool, default: false)
  • Actives the log output of the svh driver library. This uses a ROS Independent logging system providing deeper insight into whats happening. By Default the log files are stored in ~/.ros/log but the files can be specified by providing a new logging.xml.
~CHANNEL_NAME/position_controller (vector of floats, default: see yaml files)
  • Parameters used for the hardware position controller. See additional documentation in YAML files and below. If no values are provides the controller will use safe internal defaults.
~CHANNEL_NAME/current_controller (vector of floats, default: see yaml files)
  • Parameters used for the hardware current controller. See additional documentation in YAML files and below. If no values are provides the current will use safe internal defaults.
~CHANNEL_NAME/home_settings (vector of floats, default: see yaml files)
  • Parameters used for the homing of the fingers providing soft stops and reset parameterization. See additional documentation in YAML files and below. If no values are provides the controller will use safe internal defaults.
~VERSIONS_PARAMETER (array, default: Filled with values from the etc/controller_default.yaml file)
  • Array of parameters for all hardware versions and all joints. The values are read from the *.yaml files in the package's etc directory.

Additional API information

Channel Mapping

The SVH has 9 degrees of freedom which are addressed as channels. Topics that accept channels will use the following mapping:

Channel Name























Parameter sets

Each finger is controlled by a cascade of position and current controller (see additional Information if you are interested in that) and has a set of homing settings. The individual settings are read via parameter server addressing them via their hardware version and CHANNEL_NAME which is stated in the section channel mapping. For example: The settings of the Ring Finger would be searching for the corresponding hardware version and the entry of RING_FINGER and so forth.

When using the launch file svh_controller.launch all parameters are read from yaml files residing in the folder etc. If you want to give custom parameters just edit the file etc/controller_user.yaml if you are using the source installation. In case of an installation from deb you should first copy the file under etc/controller_user.yaml to a folder with user write acces, make your changes and then use it by adding the argument controller_config:=path_to_your/logging.xml when launching the node.

If you want to go back to the original values (and have edited the file, residing in etc) you can simply delete the file and copy the controller_default.yaml to the name controller_user.yaml and start again. If no controller_user.yaml file is present the values of the default file will be used. If both files are missing or the node use used without the launch file hardcoded default values that are safe will be used.

WARNING: These settings enable control of very low level concepts. Setting wrong values here may lead to permanent damage in the hardware. Especially the maximum allowed currents should not be exceeded. Consult the svh_hardware_information.pdf before you change things.


Start the driver by running

roslaunch schunk_svh_driver svh_ros_control_standalone.launch name_prefix:=left_hand

if you have a left Schunk SVH hand, else omit the name_prefix parameter. The default is name_prefix:=right_hand. This will start initializing the SVH. After calibrating each degree of freedom separately, the SVH is ready to use.

The driver starts with a running joint_trajectory_controller for commanding all joints in a synchronized way. You can send trajectory goals to its action server for controlling groups of joints.

An easy access is provided with rqt's joint trajectory controller plugin. You might need to install that first with e.g.

sudo apt install ros-$ROS_DISTRO-rqt-joint-trajectory-controller

In a sourced terminal, call rqt and navigate to Plugins -> Robot Tools -> Joint trajectory controller. You can then move individual fingers with sliders.

Argument Listing

The following arguments are possible for the main launch file:

name_prefix (default: right_hand)

  • Choose left_hand or right_hand.

autostart (default: True)

  • Immediately connect to the hardware and reset the fingers upon start if set to true

serial_device (default: /dev/ttyUSB0)

  • Set the serial device to use for the connection

maximal_force (default: 0.9)

  • Set the max force / current as a percentage of the maximally possible current

debug (default: False)

  • Run the driver inside gdb in a screen session. You can pick-up the session with screen -r and start debugging.


After an autostart (default setting) of the software the fingers do not begin to move

  • The autostart tries to connect to the hand and run and autostart immediately. Check the output of the driver. After a successful connect it should read:
    <2014-09-30 11:24:20.086> DriverSVH(Info) SVHFingerManager::connect: Successfully established connection to SCHUNK five finger hand.
    <2014-09-30 11:24:20.086> DriverSVH(Info) SVHFingerManager::connect: Send packages = 28, received packages = 28
    If the driver states:
    <2014-09-30 13:23:54.741> DriverSVH(Error) SVHSerialInterface::connect: Could not open serial device: /dev/ttyUSB0
    [ INFO] [1412076234.741596785]: SVH Driver Ready, you will need to connect and reset the fingers before you can use the hand.
    the serial device could not ne opened. Check that you have installed the udev rules and that the device shows up as /dev/ttyUSBx when you connect it

After an autostart of the software it says Send packages = 28, received packages = 20 or something similar

  • In this case the device could be opened but the connection has quality issues and loses packets. You can try to connect again using the connect button of the plugin or the connect topic. The problem most likely stems from a bad connection (to long cables, bad connectors) or in rare cases from to little processing power on the executing hardware (which is not able to keep up with the data rate of the connection)

During reset of the fingers it states Driving channel 5 to hard stop. Detection thresholds: Current MIN: -500.000000mA MAX: 500.000000mA or similar and nothing is happening

  • During reset the fingers need to reach a certain percentage of the maximum allowed current to detect a hard stop. The amount is configured in the homing settings by the "reset current factor" which you can find in the *.yaml files in the etc folder. If for example the finger is supposed to reach 400mA but is stuck and only manages to get up to 200mA the threshold will not be reached. In such cases the reset timeout should abort the timeout after the amount of seconds specified. However the timeout is only active once there is no measurable difference in current. In case the current changes a little bit but does not reach the threshold it will be in an infinite loop. In this (rare) case stop the driver execution, maybe restart the hardware, and set a lower reset current factor.

During reset the finger stops as soon as it touches any resistance and is initialized in an odd position

  • In this case the value for the reset current factor and/or the overall allowed current for the motor controller is set to low. As state above the hard stop is based on a current threshold. If this threshold is very low even small disturbances can be detected as hard stop. Also if the finger is not strong enough to overcome the disturbances the current will rise up to the maximum allowed current. If it still can not overcome the disturbance most likely a reset is detected. Please make sure that no hardware fault is present in case this happens with high enough currents

The fingers work but they "run away" when they do fast movements or touch something and can not be controlled afterwards

  • This is the case when the current peaks commanded to the current controller are to high. The internal driver units will detect overcurrent/voltage and shut down leaving the finger in an odd state. You can reset the finger manually and resume operation, however this is an indication that your current controller parameters are not right. As a general direction: Choose a low P value and a higher I value as the current controller will try to negate an error in the desired current. In case the error changes suddenly a high P gain leads to a very output for the motor drivers resulting in this case. Setting the controllers right is not easy, if you are uncertain what to set just use the default settings

A finger is broken, can i still use the rest of the finger?

  • YES! You can disable the finger by editing the "etc/svh.yaml" file or by copying it and then providing it via launch argument. Change the "disable_flags" value of the finger you want to disable to true and it will not be used during execution. However all calls to this finger will be answered in the most positive way possible (i.e. it will register as enabled and homed)

The plugin does not show in rqt, or a failure occurs during loading

  • Try resetting the cache of rqt by calling rqt --clear-config and then try again

The hand gets very hot

  • There are many motors and electronic circuits on a very small space. A quite high temperature is nothing to worry about. You should however still be able to touch everything. Otherwise you should check for a hardware fault

RVIZ shows nothing like the screenshot when i load it

  • You need to configure it yourself to show the robot model and maybe the TF tree or use the provided config file at "etc/urdf.rviz"

When i start the node with rosrun the URDF tree of a robot state publisher is not complete

  • We used the mimic tag to model the chained kinematic of the fingers. The mimic tag however is only evaluated by the joint state publisher. In the launch file of the controller you can see how you can use the joint state publisher just for the purpose of providing the values for these mimicked joints

Where is the actual functionality within the ROS package? It hardly seems to do anything

  • The actual driver was developed as a standalone library which is then used by the SVHNode to control the functionality. Take a look at the "driver_svh" folder which is also contained in the src folder.

Getting Help

If the troubleshooting did not answer your questions you can ask the community via ROS Answers or open an issue on the official github repository.

Additional information

Information provided here is meant for developers that want to use the driver in a very specific way or extend it.


The following illustration shows where the individual joints are located within the kinematic model of the hand and how the connected finger segments are scaled in respect to these joints. The mimic joints will always have the joint angle of the joint they mimic times the scaling factor that is stated for each joint

  • svh_joint_names.png

The links in the URDF contain many helper and dummy links that are needed to create the quite complex kinematic chain why the following illustration of the links is only partially accurate. Especially the links names "e" are mostly virtual and really in one place. Also the base link is actually further in the back than drawn in the picture. Due to the limitations of 2D we could not accurately illustrate this:

  • svh_link_names.png

For proper illustration of the robot model simplified collada files where created out of the original CAD data of the SVH. The following picture shows which part corresponds to a file name:

  • svh_dae_filenames.png

Kinematic dependencies and ranges

The following indicates the maximum angles (from wich the scaling for the svh driver was calculated):

  • svh_kinematic_ranges.jpg

The joint names correspond to the ones seen in this kinematic description

  • svh_kinematic_dependencies.jpg svh_overall_measurements.jpg

Additional Documents

Wiki: schunk_svh_driver (last edited 2022-11-28 19:06:00 by stefanscherzinger)