Stretch Body release 0.4. and new contact model units

Hello Stretch users!

TLDR: If you upgrade to Stretch Body v0.4 you will be required to run tool before Stretch Body will operate

We have recently released a new version of Stretch Body. In addition to a number of small bug fixes, this release introduces a new approach to guarded contact values.

When Stretch moves its arm, lift, or base it does so with contact parameters that tell it at what force to stop motion. Typically these parameters are pulled from the robot’s YAML parameter file. In some cases you may have existing code that directly passes in these contact parameters.

Prior to Stretch Body 0.4.0 the units of the contact model were very approximate Newtons (using the *_N suffix). We found that these units were confusing to users.

With Stretch Body 0.4.0 we are moving to more intuitive units of effort_pct. Effort Pct is simply a percentage of the maximum allowable winding current for the motor. Its values are bounded between -100 and 100.

More information on contact parameters is available via this tutorial.

Starting with v0.4.0, Stretch Body will automatically check if you must first migrate your contact parameters and code to the new format. For example:

Please run tool before continuing. 

Fortunately, this migration is straightforward. Simply run:

############## Migrating  stretch-re1-1021 ###############
Checking parameters  at: /home/hello-robot/stretch_user/stretch-re1-1021
Attempting migration of contact data for robot stretch-re1-1021. Proceed? [y/N]: y
Converted [-60.000000, 80.000000] to [-33.542039, 44.722719] for homing_force_N of arm
Converted [-62.621646, 65.061853] to [-35.007629, 36.371787] for contact_thresh_N of arm
Converted [-70.000000, 80.000000] to [-29.166667, 33.333333] for homing_force_N of lift
Converted [-56.140879, 79.694501] to [-23.392033, 33.206042] for contact_thresh_N of lift
Updated stretch_configuration_params.yaml.
Robot stretch-re1-1021 now configured to use effort_pct contact parameters

This tool migrates your existing robot contact parameters to the new units. It also stores a backup of your original data

In some cases you may have existing code that directly sets the contact values. For example:

robot.arm.move_to(x_m=0.2, contact_thresh_pos_N=30.0, contact_thresh_pos_N=-30.0)

Running this code will now exit as it is using the deprecate API variables contact_thresh_pos_N and contact_thresh_neg_N. You will now need to port your code by:

import stretch_body.hello_utils as hu
p=hu.pseudo_N_to_effort_pct('arm', 30.0)
n=hu.pseudo_N_to_effort_pct('arm', -30.0)
robot.arm.move_to(x_m=0.2, contact_thresh_pos=p, contact_thresh_neg=n)

The helper function pseudo_N_to_effort_pct automatically converts the contact settings for you.

As always, feel free to email us at or post here if you have any questions or issues.