free_joint¶

Runs at once IDLE mode Takes control

Free one joint so it can be turned by hand. The joint's drive gets a current limit of 0: the joint makes no torque and turns freely, while its encoder keeps counting, so get_joints() follows the hand. Every other joint keeps its IDLE behaviour: it holds still or, on a homed, enabled arm with gravity compensation on, floats in freedrive. It works enabled or disabled, homed or not. One joint is free at a time: freeing another first holds the one that was free.

The robot holds the joint again by itself on any mode change (homing, a jog, an error, the E-stop), and 2 minutes after the last free_joint() for that joint; calling it again for the same joint starts the 2 minutes again. free_joint(0) holds it now. A joint held again stays where the hand left it. The status field free_joint names the free joint, 0 when none is.

Syntax¶

robot.free_joint(joint)

Arguments¶

Name	Type	Default	Description
`joint`	`int`	required	The joint to free, 1 for J1; 0 holds the free joint again.

Returns¶

Any

None: the robot sends no data back.

Examples¶

robot.free_joint(6)
robot.get_joints()[5]
robot.free_joint(0)

Further details¶

Warning

A freed joint holds nothing. A joint that carries the arm's weight, such as J2 or J3, falls at once unless someone supports the arm.

Usage restrictions 5 codes

This command runs at once; it is not queued. The robot accepts it only when it is in IDLE mode, 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:

[6010] Command not allowed now — the message names the mode or state it needs
[6101] Control held by another client — another client holds control; the message names it
[6003] Invalid arguments — joint is not a whole number from 0 to the number of joints
[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
[4007] Freeing a joint refused — the joint cannot be freed: the robot software started less than 1.2 s ago, or the Hall sensor check or a test move runs. The message says why; the status field stays 0

In Python, a code above raises CommandRejected; its number is the code. The call raises:

CommandRejected: The robot refused it: it is not in IDLE mode, joint is out of range, 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.
ValueError: joint is not a whole number. Nothing is sent.
TypeError: joint is None. Nothing is sent.

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:

{"id": "c1", "cmd": "free_joint", "args": [6]}