home¶

Runs at once IDLE mode Enabled Takes control

Home the arm: find each joint's reference position. The arm moves each joint to its endstop, in the order of the robot's homing sequence, and sets the joint's reference there; the gripper is calibrated too. Then the robot returns to IDLE mode. It takes about half a minute. A homed arm can be homed again.

A failed homing latches an error (J<n>:HOMING_FAILED or GRIPPER_HOMING_FAILED): the robot is then in the error state, disabled and not homed. An error during homing ends it the same way. Leaving it with enter_idle_mode(), stop() or disable() abandons it, and the arm is then not homed (HOMING_ABORTED in the activity log): home it again.

Syntax¶

robot.home(wait=None)

Arguments¶

Name	Type	Default	Description
`wait`	`bool \| None`	`None`	Wait until homing has ended, up to 3 minutes. `None` follows the client's `sync` setting.

Returns¶

Nothing.

Examples¶

robot.enable(wait=True)
robot.home(wait=True)

Further details¶

Warning

The arm moves by itself to every joint's endstop. Keep the space around it clear.

Usage restrictions 4 codes

This command runs at once; it is not queued. The robot accepts it only when it is in IDLE mode and enabled, 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
[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
[6014] Mode change refused — rTI refused HOMING, for example while an error is latched (clear_errors() first). The message says why

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 or not enabled, or another client holds control. Or RTI refused it or did not answer within 1 s (Errors:).
HomingFailed: With wait, homing failed. It names the robot's error keys.
RobotTimeout: The robot did not answer within 5 s, or, with wait, homing had not ended after 3 minutes.
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:

{"id": "c1", "cmd": "home", "args": []}