Scripting API

Scripting API

You can control robots from the Python console and from macros. The module App/rbt_api.py is the public API.

from freecad.Robot_tools.App.rbt_api import get_robot, get_robots, RobotBuilder

All values at the API boundary are millimeters and degrees. Placements are App.Placement objects in world coordinates. Errors raise RbtError (RbtInputError, RbtDocError).

Get a robot

Function	Function result
get_robot(hint=None, doc=None)	One RobotApi. Give no hint when the document has one robot. A hint is a Name, a Label, or a Robot object
get_robots(doc=None)	List of RobotApi for all robots in the document

rob = get_robot()        # the only robot in the active document
rob = get_robot("KR16")  # by Label

RobotApi

Read the structure

Member	Value
rob.n_joints	Number of joints
rob.joint_types	Joint types of the kinematic chain
rob.limits	List of (min, max) for each joint
rob.max_speeds	Maximum speed of each joint
rob.dof_mask	Movable joints as a list of booleans
rob.doc, rob.assembly	The document and the wrapped assembly

Move the joints

Member	Function
rob.q	Joint values. Read and write. Degrees for revolute joints, millimeters for sliders
rob.set_q(q, clamp=False, preview=False)	Set all joints. clamp=True keeps the values in the limits
rob.set_joint(i, value)	Set one joint
rob.jog(q)	Preview only. A recompute sets the pose back
rob.check_limits(q=None)	Empty text when the values are in the limits. Else the violation text

rob.q = [0, -30, 45, 0, 60, 0]

Home and zero

Member	Function
rob.home	The saved home pose
rob.go_home()	Move all joints to the home pose
rob.save_home()	Save the current pose as the home pose
rob.save_zero()	Make the current pose the zero pose ("mastering")

Forward and inverse kinematics

Member	Function
rob.tcp	World TCP placement now (flange when no tool)
rob.fk(q=None)	World TCP for joint values q
rob.ik(target, q_seed=None)	Joint values for a target placement. None when there is no solution
rob.move_to(target)	Solve IK and move the joints

tgt = rob.tcp.copy()
tgt.Base.z -= 50
rob.move_to(tgt)

Base, tool, backend

Member	Function
rob.base	The robot's BasePlacement. Write it to move the full robot
rob.tool, rob.tools	The active tool and the list of all tools
rob.add_tool(name, shape_file=None)	Make a new active tool
rob.kinematics_lib	The IK backend name. See Kinematics

Trajectories

Member	Function
rob.trajectories	List of TrajectoryApi for this robot
rob.add_trajectory()	Make a new trajectory

Escape hatches

Member	Function
rob.recompute()	Recompute the assembly and the tool
rob.invalidate_cache()	Discard the cached chain and backend
rob.fpo	The raw FeaturePython object

TrajectoryApi

Member	Function
traj.robot	The parent robot as RobotApi
traj.waypoints	The waypoint list. Read and write
traj.teach(name="", motion=PTP)	Record the current pose as a joint waypoint
traj.add_cartesian(target, name="", motion=PTP)	Add a Cartesian waypoint at a placement
traj.goto(idx)	Move the robot to waypoint idx
traj.plan()	The trajectory plan and the validated waypoints
traj.duration	Duration of the plan in seconds
traj.q_at(t_sec)	Joint values at time t_sec along the plan
traj.sample_path(n_per_seg=20)	World TCP polyline for each segment

Motion types: PTP (point-to-point in joint space) and LIN (linear in Cartesian space).

traj = rob.add_trajectory()
traj.teach("start")
rob.q = [0, -30, 45, 0, 60, 0]
traj.teach("pick")
print(traj.duration)
traj.goto(0)

RobotBuilder

RobotBuilder is the script equivalent of the Define Robot wizard: parts → base → joints → finish.

Member	Function
RobotBuilder(doc=None).new_robot()	Make a new assembly and Robot object
.attach(hint=None)	Bind to an existing robot for edits
.import_parts(path)	Merge a parts .FCStd file. Result: the imported objects
.add_parts(objs) / .add_part(obj)	Insert parts into the assembly, in build order
.add_base(ref, jtype=FIXED)	Ground the base link. ref = (link, "FaceN"). Types: FIXED, REVOLUTE (turntable), PRISMATIC (rail)
.add_joint(jtype, ref1, ref2)	Connect two links. Parent side first
.flip_joint(joint) / .delete_joint(joint) / .remove_link(link)	Corrections
.finish()	Validate and recompute. Result: RobotApi

from freecad.Robot_tools.App.rbt_api import RobotBuilder, FIXED, REVOLUTE

b = RobotBuilder().new_robot()
parts = b.import_parts(r"C:\robots\parts.FCStd")
links = b.add_parts(parts)
b.add_base((links[0], "Face3"), FIXED)
b.add_joint(REVOLUTE, (links[0], "Face7"), (links[1], "Face2"))
rob = b.finish()

Exports

get_robot, get_robots, RobotApi, RobotBuilder, TrajectoryApi, RbtError, RbtInputError, RbtDocError, REVOLUTE, PRISMATIC, FIXED, PTP, LIN, Waypoint, is_robot, is_trajectory.