Stretch RE1 - Dex Wrist User Guide

In this guide, we will cover the installation, configuration, and use of the Stretch Dex Wrist.

Overview

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.

Functional Specification

Working with the Dex Wrist

Safe Use

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:

Avoiding Collisions

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 stretch_xbox_controller_teleop.py tool.

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 collision_model.py

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

XBox Teleoperation

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.

$ stretch_xbox_controller_teleop.py

The new key mapping is shown below. A printable version is available here.

Stretch Body Interface

The new WristPitch and WristRoll joints are accessed from Stretch Body in the same manner as the WristYaw joint.

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 use 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:

$ stretch_about.py

Refer to this table to determine what changes are required for your robot.

Batch Name	Upgrade Wacc Board	Update Baud Rate
Guthrie	Y	Y
Hank	Y	Y
Irma	Y	Y
Joplin	N	Y
Kendrick or later	N	N

Upgrade Wacc Board

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.

Update Baud Rate

The new wrist requires moving to 115200 Baud communication for all Dynamixel servos from the previous 57600 (depending on your production batch). Use the commands below.

$ 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

Attaching the Dex Wrist

Power down your Stretch before installing the Dex Wrist.

The Dex Wrist mounts to the bottom of the Stretch Wrist Tool Plate. Installation 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.

Mounting Bracket

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 (A) to the bottom of the tool plate using the provided M2x6mm bolts (B).

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.

NOTE: During this step ensure the Dynamixel cable from the wrist yaw exits out the back (towards the shoulder)

Next, raise the wrist module up vertically into the mounting bracket

![]

, then sliding it over horizontally so that the bearing mates onto its post.

![]

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 (C) using the T8 Torx wrench.

Finally, route the Dynamixel cable into the wrist pitch servo (pink) and install the cable clip (D) using the M2.5x8mm bolts and the 2mm hex wrench.

Software Configuration

Robots that did not ship with the Dex Wrist pre-installed will require their software to be updated and configured.

NOTE: Each user account on the robot will need to run the following steps to configure the Dex Wrist.

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

Backup User YAML

$ cd $HELLO_FLEET_PATH/$HELLO_FLEET_ID
$ cp stretch_re1_user_params.yaml stretch_re1_user_params.yaml.bak

Run Installation Script

$ cd ~/repos
$ git clone https://github.com/hello-robot/stretch_install
$ cd ./stretch_install
$ git pull
$ ./stretch_new_dex_wrist_install.sh

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 RE1_gripper_calibrate.py