set_collision_detection¶
Runs at once Any mode Takes control
Set how the robot reacts when the arm hits something. The robot estimates the external torque on each joint from the motor currents and its model. While it moves a joint in EXEC, JOG or a real-time stream, it compares that torque with the one the joint had at rest before the move. Above the joint's contact threshold (robot XML <contact_torque_nm>) it shows a live J<n>:CONTACT_WARNING; above its collision threshold (<collision_torque_nm>) it reacts as mode says. A threshold of 0 leaves it unchecked on that joint.
The check runs on a homed arm, while a joint is commanded faster than 0.5 deg/s and for 0.5 s after; an excursion must last 0.012 s (config/system.xml <safety_monitor>: <hold_still_dps>, <collision_settle_s>, <collision_sustain_s>). It never runs in freedrive, homing or the error state. A warning clears once the joint is back under half its contact threshold, or at rest.
A change lasts while the client that made it holds control. When that client releases control, loses it or disconnects, the reaction returns to its start value, and the robot's log says so. "warn" and "stop" are refused when nothing can be checked: the safety monitor is off in config/system.xml, or the robot XML gives no joint a threshold. latest_status() shows the reaction in force in collision_detection ("off" while the safety monitor is off); the robot's log records a switch to a weaker one as a warning.
Syntax¶
Arguments¶
| Name | Type | Default | Description |
|---|---|---|---|
mode |
str |
required | "off": no contact or collision check. "warn": a live J<n>:COLLISION_WARNING, and the robot keeps moving. "stop": the error J<n>:COLLISION: the robot stops and is disabled, holding every joint, until clear_errors() and enable(); a running program is cancelled. Letter case and spaces around the word do not matter. |
Default values¶
From config/system.xml <safety_monitor><collision>, read when the
robot software starts: "warn" as shipped, and when the element is
missing.
Returns¶
Any
Always None: the robot's answer carries no data.
Examples¶
robot.set_collision_detection("off")
robot.move_joints(90, -105, 165, 0, -30, 180)
robot.wait_idle()
robot.set_collision_detection("warn")
Further details¶
Note
A part the gripper holds reads as external torque until it is declared
with set_payload(). A switch takes a new rest torque at once: switch
while the arm stands still.
Further details¶
Warning
With "off" or "warn" the arm keeps pushing after it hits something,
with all the force its drives give. Turn the check down only for a move
that presses on purpose, and back up right after it; the robot turns it
back up itself only when your client leaves control.
Usage restrictions 5 codes
This command runs at once; it is not queued. The robot accepts it in any mode and state, from the client that holds control or when no client does.
It answers with one of these codes when it does not carry the command out:
- [6101] Control held by another client — another client holds control; the message names it
- [6010] Command not allowed now —
"warn"or"stop"while nothing can be checked: the safety monitor is off, or no joint has a threshold in the robot XML - [6003] Invalid arguments —
modeis not"off","warn"or"stop" - [6025] RTI not running or not answering — rTI did not answer within 1 s: it is not running or not responding. The command may still have taken effect
- [6026] Refused by RTI — rTI could not read the reaction. The message says why
In Python, a code above raises CommandRejected; its number is the code. The call raises:
CommandRejected: The robot refused it:modeis not one of the three words, nothing can be checked, or another client holds control. Or RTI refused it or did not answer within 1 s (Errors:).RobotTimeout: The robot did not answer within 5 s.RobotConnectionError: The client is not connected.
If the connection drops while the call waits for the robot's answer, it raises CommandRejected with the code CONNECTION_LOST (DISCONNECTED after disconnect()); while it waits for the robot's status, RobotConnectionError.
Like every immediate command, it also answers BAD_ARGS when a raw client sends a value the robot cannot read at all, and INTERNAL when it fails inside the robot.
Protocol¶
A client that does not use robotclient sends this over the TCP command protocol (port 29000) for the example above: