take_control¶

Runs at once Any mode Open to every client

Take control of the robot for this client. While a client holds control, the robot refuses every other client the commands that take control, with CONTROL_HELD; the commands open to every client still work for all, stopping included. Usually no call is needed: the first command that takes control claims it when nobody holds it. Call it to reserve the robot before a program starts, or with force=True to take control from another client.

Control is released by release_control(), when the client disconnects, or after 30 s without a command that takes control, with nothing queued and no real-time stream running. When control leaves a client this way or by a takeover, a collision-detection change it made returns to the start value (set_collision_detection()).

With the takeover confirmation on (set_force_confirm()), a forced take from another client waits up to 20 s for someone at the control box: holding button 2 for 1 s allows it, button 1 refuses it.

Syntax¶

robot.take_control(force=False, timeout=None)

Arguments¶

Name	Type	Default	Description
`force`	`bool`	`False`	Take control even when another client holds it.
`timeout`	`float \| None`	`None`	Seconds to wait for the robot's answer. `None` means 30 s with `force=True`, time for the button press, and 5 s otherwise.

Returns¶

dict

{"holder": label}, the client that now holds control: its address as the robot sees it, "ip:port", as control_holder() reports it.

Examples¶

robot.take_control()
robot.release_control()

Usage restrictions 5 codes

This command runs at once; it is not queued. The robot accepts it in any mode and state, from every client.

It answers with one of these codes when it does not carry the command out:

[6003] Invalid arguments — force was not true or false (a raw client's 1 / 0 also count)
[6103] Takeover already waiting — another forced takeover is already waiting at the control box
[6102] Takeover not confirmed — the forced takeover was not confirmed: refused or not answered at the control box within 20 s, button 2 already held when it started, or this client disconnected meanwhile
[6101] Control held by another client — another client holds control, and force is false
[6013] Internal error — the confirmation failed inside the robot

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

CommandRejected: The robot refused it; its error code says why.
RobotTimeout: The robot did not answer within timeout.
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": "take_control", "args": [false]}