Hello Stretch users!
TLDR: If you upgrade to Stretch Body v0.4 you will be required to run tool RE1_migrate_contacts.py 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:
>>$ stretch_robot_home.py
Please run tool RE1_migrate_contacts.py before continuing.
...
Fortunately, this migration is straightforward. Simply run:
>>$ RE1_migrate_contacts.py
############## 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 support@hello-robot.com or post here if you have any questions or issues.
Best,
Aaron