Greetings. A few users have gotten tripped up with Stretch guarded contacts so we thought we’d try to provide some practical guidance here.
Simply put: A guarded contact limits the current that the motor in the arm, lift, or wheel can apply. If the limit is exceeded, motion is stopped.
Additional background is available in the tutorial on Contact Models:
The intention of guarded contacts is to prevent the robot from hurting itself, someone, or something in the environment.
A few important practical comments:
- Guarded contacts are enabled by default for the arm and lift only.
- Contacts are specified in units of
effort_pctwhich is a number in the range [-100,100]. A contact value of 100 corresponds to the maximum current the motor can support.
- Internal disturbances may cause an false-positive contact event
This sounds straightforward and it is. However confusion often arises due to false positive contact events due to internal disturbances in the arm and lift.
Get to know the arm and lift backdriving forces
When the robot is powered off, try moving the arm and lift slowly through its range of motion. You’ll notice that the amount of force to backdrive the joint varies over its range. It can also be dependent on the direction of motion.
In this video you can see what backdriving the joints of a healthy Stretch robot looks like when powered off. If the backdriving forces seem noticeably greater than in this video, it is likely that there is a mechanical issue.
These forces that you are experiencing when backdriving are the internal disturbances of the actuator mechanism. The motor must apply current to overcome these disturbances. If this level of current exceeds the guarded contact settings, then the joint will stop its motion prematurely (e.g. a false positive contact event).
What to do about false positive contact events?
If you are experiencing false positive contact events it may be that you just need to increase your contact thresholds a bit. This may be necessary as the internal forces tend to increase over the lifetime of the robot. Or it may be the case because the arm has additional payload on it.
It may also be the case that there is a mechanical issue with the joint (in which case you should contact Hello Robot support for assistance).
How to adjust contact thresholds
If increasing the contact threshold is the correct path, first check the existing settings:
>>$ stretch_params.py | grep arm | grep contact_thresh_default stretch_configuration_params.yaml param.arm.contact_models.effort_pct.contact_thresh_default [-35.00762878888835, 36.37178741925945]
So we see that the arm will stop motion at about +/-35% of its max current. Now we can run the calibration tool:
This cycles the joint through its range of motion four times and plots the effort required in both directions. For example, here is the effort required to extend the arm
The effort is generally below 25%, however the tool has set the new extension contact threshold to about
42%. This value has been calculated such that the arm can safely move without generating a false positive on extension.
The tool can also be run for the lift:
Please don’t hesitate to contact Hello Robot support if you are unsure about adjusting your robot’s contact settings.