Stretch RE1: Dex Wrist User Guide
In this guide we will cover the installation, configuration, and use of the Stretch Dex Wrist.
The Stretch Dex Wrist is an optional add-on to the RE1. It adds pitch and roll degrees of freedom to the standard wrist yaw joint. It also includes a slightly modified version of the standard Stretch Compliant Gripper.
NOTE: If your robot did not ship with the Stretch Dex Wrist pre-installed you will want to first proceed to the Appendix: Installation and Configuration at the end of this guide.
Working with the Dex Wrist
The Dex Wrist requires added attention to safety. Its additional dexterity introduces new pinch points around the wrist pitch and roll degrees of freedom.
NOTE: Please review the Robot Safety Guide prior to working with the Dex Wrist.
In addition to these precautions, the Dex Wrist requires attention to pinch points between:
- The wrist pitch and wrist yaw structures during yaw motion
- The gripper and wrist pitch structures during pitch motion
The Dex Wrist includes a pinch point safety marking as a reminder to users:
The added dexterity of the Dex Wrist introduces new opportunities for self-collision between the robot tool and the robot. These include
- Running the tool into the base during lift downward motion
- Running the tool into the ground
- Running the tool into the wrist yaw structure
We recommend becoming familiar with the potential collision points of the Dex Wrist by commanding careful motions through the
With Stretch Body v0.1.0 we introduce a simple collision avoidance controller.
The collision avoidance behavior acts to dynamically set the robot joint limits according to simple models of its kinematic state. The avoidance behavior is defined in
For performance reasons this collision avoidance behavior is coarse and does not prevent all self-collisions and considered 'experimental'. The collision avoidance is off by default for the standard Stretch RE1. For robots with the wrist we turn it on by default. It be turned on or off by modifying the following in your user YAML:
robot: use_collision_manager: 1
The Dex Wrist can be teleoperated using the XBox controller. When the Dex Wrist is installed the
stretch_xbox_controller_teleop.py tool will automatically remap control of the pan-tilt head to control of the pitch-roll wrist.
The new key mapping is shown below. A printable version is available here.
Stretch Body Interface
Control of the Stretch Dex Wrist uses the same interfaces as the rest of the Stretch Body Robot joints. For example:
import stretch_body.robot robot=stretch_body.robot.Robot() robot.startup() #Move arm to safe manipulation location robot.stow() robot.lift.move_to(0.4) robot.push_command() time.sleep(2.0) #Pose the Dex Wrist robot.end_of_arm.move_to('wrist_yaw',0) robot.end_of_arm.move_to('wrist_pitch',0) robot.end_of_arm.move_to('wrist_roll',0) robot.end_of_arm.move_to('stretch_gripper',50) time.sleep(2.0) #Go back to stow and shutdown robot.stow() robot.stop()
You can jog the individual joints of the wrist with the Stretch Body interface using the
stretch_dex_wrist_jog.py tool that installs with the Stretch Tool Share:
>>$ stretch_dex_wrist_jog.py --pitch >>$ stretch_dex_wrist_jog.py --yaw >>$ stretch_dex_wrist_jog.py --roll
For reference, the parameters for the Stretch Dex Wrist (which can be overridden in the user YAML) can be seen in params.py.
Stretch ROS Interface
The Dex Wrist can be controlled via ROS as well, as shown in the keyboard teleoperation code. To test the interface:
>>$ roslaunch stretch_calibration simple_test_head_calibration.launch
You can type 'q' then Ctrl-C to exit when done. The menu interface is:
---------- KEYBOARD TELEOP MENU -----------| | | | i HEAD UP | | j HEAD LEFT l HEAD RIGHT | | , HEAD DOWN | | | | | | 7 BASE ROTATE LEFT 9 BASE ROTATE RIGHT | | home page-up | | | | | | 8 LIFT UP | | up-arrow | | 4 BASE FORWARD 6 BASE BACK | | left-arrow right-arrow | | 2 LIFT DOWN | | down-arrow | | | | | | w ARM OUT | | a WRIST FORWARD d WRIST BACK | | x ARM IN | | | | | | c PITCH FORWARD v PITCH BACK | | o ROLL FORWARD p ROLL BACK | | 5 GRIPPER CLOSE | | 0 GRIPPER OPEN | | | | step size: b BIG, m MEDIUM, s SMALL | | q QUIT | | | |-------------------------------------------|
Appendix: Installation and Configuration
Robots that did not ship with the Dex Wrist installed will require additional hardware and software installation.
Production Batch Variation
Earlier production 'batches' of Stretch will require a hardware upgrade prior to use the Dex Wrist. To check your robot's batch, run:
, and note the listed Batch Name.
|Batch Name||Upgrade Wacc Board||Update Baud Rate|
|Kendrick or later||N||N|
If your robot requires a Wacc Board upgrade please follow the instructions here with the assistance of Hello Robot support. This must be done before attaching the Dex Wrist to our robot.
Attaching the Dex Wrist
The Dex Wrist mounts to the bottom of the Stretch Wrist Tool Plate requires
- 8 M2x6mm Torx FHCS bolts (provided)
- 4 M2.5x4mm Torx FHCS bolts (provided)
- 2 M2.5x8mm SHCS bolts (provided)
- T6 Torx wrench (provided)
- T8 Torx wrench (provided)
- 2mm Hex key (provided)
First, remove the standard Stretch Gripper if it is still attached according to the Hardware User Guide.
Note where the forward direction is on the wrist yaw tool plate. The forward direction is indicated by the additional alignment hole that is just outside the bolt pattern (shown pointing down in the image)
Using the T6 Torx wrench, attach the wrist mount bracket to the bottom of the tool plate using the provided M2x6mm bolts.
NOTE: ensure that the forward direction of the bracket (also indicated by an alignment hole) matches the forward direction of the tool plate.
Now route the Dynamixel cable coming from the Stretch Wrist Yaw through the hollow bore of the wrist yaw joint.
Next, raise the wrist module up vertically into the mounting bracket, then sliding it over horizontally so that the bearing mates onto its post.
NOTE: During this step ensure the Dynamixel cable from the wrist yaw exits out the back (towards the shoulder)
Now rotate the wrist yaw joint so the wrist pitch servo body is accessible. Attach the pitch servo to the mounting bracket using the 4 M2.5x4mm screws at T8 Torx wrench.
Finally, plug route the Dynamixel cable into the wrist pitch servo (pink) and install the cable clip using the M2.5x8mm bolts and the 2mm hex wrench.
Robots that did not ship with the Dex Wrist pre-installed will require their software to be updated and configured.
Upgrade Stretch Body
Ensure the latest version of Stretch Body and Stretch Factory are installed
>>$ pip2 install hello-robot-stretch-body -U --no-cache-dir >>$ pip2 install hello-robot-stretch-body-tools -U --no-cache-dir >>$ pip2 install hello-robot-stretch-factory -U --no-cache-dir >>$ pip2 install hello-robot-stretch-tool-share -U --no-cache-dir
Update Servo Baud Rates
If your robot's batch requires a baud rate update:
>>$ RE1_dynamixel_set_baud.py /dev/hello-dynamixel-head 11 115200 --------------------- Checking servo current baud for 57600 ---- Identified current baud of 57600. Changing baud to 115200 Success at changing baud >>$ RE1_dynamixel_set_baud.py /dev/hello-dynamixel-head 12 115200 --------------------- Checking servo current baud for 57600 ---- Identified current baud of 57600. Changing baud to 115200 Success at changing baud >>$ RE1_dynamixel_set_baud.py /dev/hello-dynamixel-wrist 13 115200 --------------------- Checking servo current baud for 57600 ---- Identified current baud of 57600. Changing baud to 115200 Success at changing baud
Configure User YAML
The Dex Wrist requires a number of updates to the robot user YAML
YAML doesn't allow definition of multiple fields with the same name. Depending on what is already listed in your user YAML you will need to manually merge fields.
Merge the new following additions to you your
factory_params: stretch_re1_factory_params.yaml params: - stretch_tool_share.stretch_dex_wrist.params robot: use_collision_manager: 1 tool: tool_stretch_dex_wrist tool_none: baud: 11520 tool_stretch_gripper: baud: 115200 head: baud: 115200 wrist_yaw: baud: 115200 head_tilt: baud: 115200 head_pan: baud: 115200 stretch_gripper: range_t: - 0 - 6415 zero_t: 4017 baud: 115200 lift: i_feedforward: 0.75 hello-motor-lift: gains: i_safety_feedforward: 0.75
Note: The factory gripper calibration may not provide the full range of motion in some cases. If necessary you can dial in the gripper calibration with the tool
Configure for use in ROS
First pull down the Dex Wrist branch of Stretch ROS, Stretch Tool Share, and copy in the URDF data:
>>$ cd ~/catkin_ws/src/stretch_ros/ >>$ git checkout feature/pluggable_end_effector >>$ git pull >>$ cd ~/repos >>$ git clone https://github.com/hello-robot/stretch_tool_share >>$ cd stretch_tool_share/tool_share/stretch_dex_wrist/stretch_description >>$ cp urdf/stretch_dex_wrist.xacro ~/catkin_ws/src/stretch_ros/stretch_description/urdf >>$ cp meshes/*.STL ~/catkin_ws/src/stretch_ros/stretch_description/meshes
stretch_description.xacro to use the Dex Wrist:
>>$ nano ~/catkin_ws/src/stretch_ros/stretch_description/urdf/stretch_description.xacro
and edit to read,
<?xml version="1.0"?> <robot xmlns:xacro="http://www.ros.org/wiki/xacro" name="stretch_description"> <xacro:include filename="stretch_dex_wrist.xacro" /> <xacro:include filename="stretch_main.xacro" /> <xacro:include filename="stretch_aruco.xacro" /> <xacro:include filename="stretch_d435i.xacro" /> <xacro:include filename="stretch_laser_range_finder.xacro" /> <xacro:include filename="stretch_respeaker.xacro" /> </robot>
Update your URDF and then export the URDF for Stretch Body to use (you may need to Ctrl-C to exit
>>$ rosrun stretch_calibration update_urdf_after_xacro_change.sh >>$ cd ~/catkin_ws/src/stretch_ros/stretch_description/urdf >>$ ./export_urdf.sh