Introduction
Components
Framework
Physics
Virtual Commissioning
Analysis
Tutorials

Robot Controller

The robot controller component is a scripted component that implements a generic robot controller capable of executing a varient of instructions. The robot controller automatically computes the forward and inverse kinematics and can seamlessly handle closed kinematic structures. Practically every type of industrial robot is supported. The axes that make up the robot are automatically detected. Alternatively, if the robot contains joints for a tool (such as a mechanical gripper), the axes to be solved can be manually specified through the “joints” property.

Properties

The robot controller component properties that are accessible through the inspector.

TCP

The entity that serves as the Tool Center Point (TCP) for the robot. This entity must be a child of the robot. Note that the Robot TCP component can be used to accurately position the TCP by selecting a feature of the graphical mesh. If the entity contains a Robot TCP component then that component will be used to determine the position and orientation of the TCP. Otherwise, the TCP entity’s transform will be used.

Programs

The list of exportable robot programs. A robot controller can have multiple programs. Each program must have a (case insentitive) unique name. If the program is called “Main” then the program will be executed automatically. Programs contain an ordered list of instructions. The following instruction types are available:

  • Empty: An empty (placeholder) instruction that performs no action.
  • Pause: Instructs the controller to pause execution of the program for a set number of seconds.
  • Linear Move: Instructs the controller to perform a linear move (MoveL, LIN) to the specified target entity.
  • Joint Move: Instructs the controller to perform a joint move (MoveJ, PTP) to the specified target entity.
  • Set Speed: Instructs the controller to change zero or more motion parameters.
  • Set TCP: Instructs the controller to change the currently active TCP to the specified entity.
  • Await Signal: Instructs the controller to pause execution until the specified signal reports a particular value.
  • Set Signal: Instructs the controller to set the specified signal to a particular value.
  • Call: Instructs the controller to call the specified program.
  • Conditional Call: Instructs the controller to call the specified program if the specified signal reports a particular value.
  • Call Script: Instructs the controller to call the specified scripted program.

Further details about these instructions are provided below.

Joints

The (optional) list of axes to be controlled by the robot controller. If no joints are specified then the robot controller will automatically detect all joints on any descendant entities. If the robot contains a jointed tool, such as a mechanical gripper, then it will be necessary to provide the list of joints that should be controlled. This ensures that the robot controller will not attempt to control the joints belonging to the tool.

Linear Speed

The maximum/target linear speed for the TCP that the robot controller should try to achieve when performing linear moves.

Linear Acceleration

The linear acceleration/deceleration for the TCP that the robot controller should use when performing linear moves.

Angular Speed

The maximum/target rotational speed for the TCP that the robot controller should try to achieve when performing linear moves.

Angular Acceleration

The rotational acceleration/deceleration for the TCP that the robot controller should use when performing linear moves.

Joint Speed

The multiplier to apply to the target speed of all joint motors when performing joint moves. For example, a multiplier of 2.0 (200%) will allow the motors to move up to twice as fast as the initial target speeds set on the motors.

Joint Acceleration

The multiplier to apply to the acceleration/deceleration of all joint motors when performing joint moves. For example, a multiplier of 0.5 (50%) will cause the motors to accelerate/decelerate half as fast as the initial acceleration/deceleration set on the motors.

Instructions

The robot controller supports a wide range of instructions.

Empty

The empty instruction is used as a placeholder. It performs no action when executed.

Pause

The pause instruction causes the robot controller to pause execution for a fixed number of seconds.

Linear Move

The linear move (MoveL/LIN) instruction commands the robot controller to perform a linear movement towards the specified target entity. The TCP will be moved along a line from its current position to the target position. Note that linear moves may encounter singularities. The speed at which the TCP moves through world space governed by the “Linear Speed” and “Linear Acceleration” properties. The speed at which the TCP rotates is governed by the “Angular Speed” and “Angular Acceleration” properties. The initial target speeds and accelerations set on the motors are ignored.

Joint Moves

The joint move (MoveJ/PTP) instruction commands the robot controller to perform a joint movement to the specified target entity. The path that the TCP will take is somewhat unpredictable (though still deterministic). The inverse kinematics for the robot is solved and then the joints are commanded to move to their solved positions. The speed at which the joints move is determined such that all joints arrive at their target positions at the same time whilst ensuring not to violate any speeds/accelerations set on the motors. However, note that the “Joint Speed” and “Joint Acceleration” multipliers are applied, which can be used to adjust the maximum speeds and accelerations of the motors.

Set Speed

The set speed instruction can be used to modify the motion parameters of the robot controller during the execution of a program. The “Enable” property specifies which motion parameters should be modified. Note that multiple parameters may be modified by a single set speed instruction. This instruction is used to adjust the speed/acceleration of the robot for a particular sequence of moves.

Set TCP

The set tool center point instruction can be used to modify the active tool center point of the robot controller during the execution of a program. This is generally used to switch between multiple end effectors. For example, the instruction could be used to switch between two different suction cups. The TCP entity selected must be a descendant of the entity to which the robot controller is attached.

Await Signal

The await signal instruction is used to pause execution of the program until a specified signal on the robot controller’s IO reports a particular value. For example, this instruction can be used to pause execution until a sensor has been blocked. Note that you must first create a signal/variable on the robot controller’s IO.

Set Signal

The set signal instruction is used to set the value of a signal on the robot controller’s IO. For example, this instruction can be used to toggle the state of suction gripper. Note that you must first create a signal/variable on the robot controller’s IO.

Call

The call instruction is used to instruct the robot controller to execute another program. This is useful for organisational purposes, allowing you to group related instructions into a separate program that can be called from the main program.

Conditional Call

The conditional call instruction is used to instruct the robot controller to execute another program if and only if a specified signal reports a particular value. This is used for branching (if statement) purposes. Note that you must first create a signal/variable on the robot controller’s IO.

Call Script

The call script instruction is used to instruct the robot controller to execute a scripted program. Scripted programs can be used for advanced tasks, such as picking moving parts up off a conveyor. Creating a scripted program involves creating a scripted component that inherits from RobotProgramComponent. An example of a scripted program is provided below:

import { type Entity, RobotProgramComponent, type RobotControllerComponent, Future, Sequence, Frame, Quat, Vec3, Wait, Units, UnitType } from "prototwin";

export class MyScriptedProgram extends RobotProgramComponent {
    @Units(UnitType.Time)
    public pauseDuration: number = 0.25;

    constructor(entity: Entity) {
        super(entity);
    }

    public execute(controller: RobotControllerComponent): Future<void> {
        const sequence = new Sequence();
        sequence.add(() => controller.moveJoint(new Frame(Quat.identity, new Vec3(-0.2, 0, 0.2))));
        sequence.add(() => Wait.seconds(this.pauseDuration));
        sequence.add(() => controller.moveJoint(new Frame(Quat.identity, new Vec3(-0.2, 0, -0.2))));
        sequence.add(() => Wait.seconds(this.pauseDuration));
        sequence.start();
        return sequence.completion();
    }
}

You must first add your scripted component to an entity. The scripted program will then be selectable as the “Script” property of the instruction.