Skip to content

Tools

Selecting a tool, the generic tool action, and the methods of the bound tool object rbt.tool. Tool actions are queued with the motion; tool.stop() is immediate. Tools and the TCP in the guide.

Registered tools

Key Tool Variants (default first)
NONE Bare flange - no tool attached —
PNEUMATIC Pneumatic gripper assembly (vertical/horizontal mounting) vertical, horizontal
SSG-48 SSG-48 adaptive electric gripper (Spectral micro BLDC) finger, pinch
MSG MSG compliant AI stepper gripper (StepFOC) 100mm, 150mm, 200mm
VACUUM Vacuum gripper (pneumatic valve I/O) —

Selecting and acting

select_tool

rbt.select_tool(tool_name: str, variant_key: str = '') -> int

Set the active end-effector tool on the controller.

rbt.select_tool("PNEUMATIC")
Parameter Meaning
tool_name Name of the tool ('NONE', 'PNEUMATIC', 'SSG-48', 'MSG', 'VACUUM')
variant_key Optional variant within the tool type.

Returns: Command index (>= 0) if queued, 0 on failure.

tool_action

rbt.tool_action(
    tool_key: str,
    action: str,
    params: list | None = None,
    *,
    wait: bool = False,
    timeout: float = 10.0,
) -> int

Send a generic tool action command.

Returns the command index (>= 0) on success, -1 on failure. The action and its parameters are checked before anything is sent: a malformed one raises ValueError. A key naming a tool other than the selected one is refused by the controller.

A tool action is queued work: it runs in queue order with motion, the arm holding still while it does, so a wait on it covers the motion queued ahead of it, and one sent after a blended move ends the blend there. A move before a completed calibrate is refused when its turn comes, failing its own index; a tool action that fails cancels what is queued behind it (MOTN_CANCELLED). A pause holds the tool actions still queued. stop(), estop(), reset_state(), a teleport, or a jog or servo stream taking the arm discards them and halts the one running where the jaws are, keeping the grip.

stop alone acts at once, on the tool fitted now: it halts the action running, failing it as cancelled by a tool stop, keeps what is queued behind it, and holds the next queued tool action until the jaws are still.

Electric grippers take move [position, speed, current] (exactly three fractions in [0, 1]; current spans the tool's current_range), calibrate, stop (halt in place, keep grip) and idle (release, the jaws left where they are); set_position/open/close map onto move. Pneumatic grippers take open, close, and move/set_position [position].

rbt.tool_action("PNEUMATIC", "open")
Parameter Meaning
tool_key Tool registry key (e.g. "PNEUMATIC", "SSG-48", "MSG")
action Action name (e.g. "open", "close", "move", "calibrate")
params Positional parameters (meaning defined by tool config)
wait If True, block until action completes
timeout Maximum time to wait in seconds (only used when wait=True)

Note

The actions of the electric grippers: move with [position, speed, current] as fractions, calibrate, stop, idle (release). Of the pneumatic and vacuum grippers: open, close, and move (or set_position) with [position], below 0.5 opening and from 0.5 closing. The tool methods below call these.

The electric gripper tool (SSG-48, MSG)

tool.set_position (electric)

rbt.tool.set_position(
    position: float,
    *,
    speed: float = 0.5,
    current: float = 0.5,
    **wait_kwargs: Any,
) -> int

Moves the jaws to position, 0 open and 1 closed, at speed (a fraction of the gripper's speed range) and with current as the current limit, the grip force. current is a fraction of the tool's current range: 100 to 1300 mA for the SSG-48, 100 to 2800 mA for the MSG, so current=0.5 is 700 mA or 1450 mA. Queued: it waits for the motion before it, and the motion after it waits for the jaws to arrive, stop on a part or stall. Refused when its turn comes on a gripper that was never calibrated.

tool.open (electric)

rbt.tool.open(*, speed: float = 0.5, current: float = 0.5, **wait_kwargs: Any) -> int

set_position(0.0, ...): the jaws fully open.

tool.close (electric)

rbt.tool.close(*, speed: float = 0.5, current: float = 0.5, **wait_kwargs: Any) -> int

set_position(1.0, ...): the jaws close until they reach the end or stop on a part.

tool.calibrate (electric)

rbt.tool.calibrate(**kwargs: object) -> int

Sends the gripper its calibration: it opens fully and closes fully to find its end stops. Queued. The API counts it done after a fixed 2 s (200 control cycles) and does not read the gripper's calibrated bit; the SSG-48 needs about 3 s and the MSG 5 to 6 s, so queue a delay() after it (Calibrating). There is no clear-error action: a latched gripper error is cleared from the commander or Motor GUI.

tool.release (electric)

rbt.tool.release(**kwargs: object) -> int

Drop the grip, freeing the jaws for manual handling, once the commands queued ahead of it have run. The jaws stay where they are.

tool.stop (electric)

rbt.tool.stop(**kwargs: object) -> int

Halt the jaws where they are, keeping the grip, ahead of anything still queued: the action running fails as cancelled, and the queue behind it is kept. On an uncalibrated gripper, which has no position to hold, this releases instead.

The pneumatic gripper tool (PNEUMATIC, VACUUM)

tool.set_position (pneumatic)

rbt.tool.set_position(position: float, **kwargs: float | int) -> int

Binary position: < 0.5 opens, >= 0.5 closes.

tool.open (pneumatic)

rbt.tool.open(**kwargs: float | int) -> int

Switches output 1 high, queued with the motion; the action lasts the tool's estimated stroke (a single control cycle for the vacuum gripper). Which way the gripper moves depends on the tubing.

tool.close (pneumatic)

rbt.tool.close(**kwargs: float | int) -> int

Switches output 1 low, queued with the motion; otherwise as open().

Every tool object also has status(), returning the ToolStatus of the selected tool: key, state, engaged, part_detected, fault_code, positions, channels and variant_key. For the electric grippers, Tool status says where each field comes from.

Comments

Found a mistake on this page? Edit it on GitHub · Report it · Get help · This page as Markdown · llms.txt · The whole manual as PDF