Practical guide to guarded contacts

[aedsinger]

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:

1. Guarded contacts are enabled by default for the arm and lift only.
2. Contacts are specified in units of effort_pct which is a number in the range [-100,100]. A contact value of 100 corresponds to the maximum current the motor can support.
3. 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:

REx_calibrate_guarded_contact.py --arm

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:

REx_calibrate_guarded_contact.py --lift

Please don’t hesitate to contact Hello Robot support if you are unsure about adjusting your robot’s contact settings.

[flyingMango]

Thanks for this post @aedsinger. I was wondering if there is any way to check (using stretch_body API) whether a guarded contact trigger was raised. Is there any API request that I can use to get this information?

For some context, I am trying to automatically determine whether the robot has accidentally collided into something, and create some sort of recovery behaviour that allows it to update its original task.

[aedsinger]

Great question. In the Stepper class the Status message has two flags. For the arm look at:

robot.arm.motor.status['in_guarded_event'] and robot.arm.motor.status['guarded_event'].

The in_guarded_event is True if the joint has been forced into Safety mode due to a guarded contact event. It can be reset by commanding a new motion to the joint.

The guarded_event field is a counter of how many events have been triggered since power-up. This can be useful for distinguishing if there are repeated guarded events happening.

Finally, you can turn on and off Guarded Mode by either the API or the YAML parameter enable_guarded_mode.