ProtoTwin API
    Preparing search index...

    Class RobotControllerComponent

    Robot controller.

    Used to easily control any industrial robot, including: gantry/cartesian, SCARA, delta and articulated robots. The inverse kinematics for the robot are solved automatically. The robot can be programmed using simple exportable programs through the inspector, or by using createProgram and adding instructions using RobotProgram.add. Advanced scripted programs can be created using custom components by extending RobotProgramComponent and then calling calling the program using a CallScriptRobotInstruction. The main program (which exists by default and must be called "Main") is executed automatically when the simulation starts. This is the entry point for the robot controller, and can be used to call other programs. The main program is executed cyclically, meaning that once the last instruction in the main program has completed, the robot controller automatically executes the main program again. See RobotControllerIO for exchanging data between the robot controller and other components in the simulation using I/O signals.

    Hierarchy (View Summary)

    Index

    Properties

    entity: Entity

    The entity to which the component is attached.

    Accessors

    • get angularAcceleration(): number

      The angular acceleration of the TCP for linear moves.

      Returns number

    • set angularAcceleration(value: number): void

      Parameters

      • value: number

      Returns void

    • get angularSpeed(): number

      The target angular speed of the TCP for linear moves.

      Returns number

    • set angularSpeed(value: number): void

      Parameters

      • value: number

      Returns void

    • get attached(): boolean

      Whether the component is attached to its entity.

      Returns boolean

    • get controlledJoints(): Joint[]

      The ordered list of joints that are controlled by the robot controller.

      Returns Joint[]

    • get gravityCompensation(): boolean

      Whether to apply gravity compensation to the robot joints.

      Returns boolean

      When enabled, gravity is effectively enabled on any links driven by the robot controller. This can improve stability and reduce constant joint error. However, when enabled, the torque reported by the motors will exclude the torque required to compensate for gravity.

    • set gravityCompensation(value: boolean): void

      Parameters

      • value: boolean

      Returns void

    • get initialized(): boolean

      Whether the component has been initialized.

      Returns boolean

    • get jointAcceleration(): number

      The joint acceleration/deceleration multiple for joint moves.

      Returns number

    • set jointAcceleration(value: number): void

      Parameters

      • value: number

      Returns void

    • get joints(): Handle<Joint>[]

      The (optional) list of joints that should be solved by the robot controller.

      Returns Handle<Joint>[]

      If a list of joints isn't provided then the robot controller will automatically use all joints on any entities that are descendants of the entity to which the robot controller is attached.

    • set joints(value: Handle<Joint>[]): void

      Parameters

      Returns void

    • get jointSpeed(): number

      The target joint speed multiple for joint moves.

      Returns number

      The robot controller can command a maximum joint speed of the motor's target speed scaled by this multiple. For example, a multiple of 2.0 allows the joints to move up to twice as fast as the target speed set on the motors that are bound to the joints. This is used only when performing joint moves.

    • set jointSpeed(value: number): void

      Parameters

      • value: number

      Returns void

    • get kinematic(): boolean

      Whether robot motion is applied directly using forward kinematics.

      Returns boolean

      When enabled, robot links are made kinematic when the controller initializes.

    • set kinematic(value: boolean): void

      Parameters

      • value: boolean

      Returns void

    • get linearAcceleration(): number

      The linear acceleration of the TCP for linear moves.

      Returns number

    • set linearAcceleration(value: number): void

      Parameters

      • value: number

      Returns void

    • get linearSpeed(): number

      The target linear speed of the TCP for linear moves.

      Returns number

    • set linearSpeed(value: number): void

      Parameters

      • value: number

      Returns void

    • get localTCP(): Frame

      The frame of the current TCP in the local-space of the robot.

      Returns Frame

    • get name(): string

      The component name.

      Returns string

    • set name(value: string): void

      Parameters

      • value: string

      Returns void

    • get tcp(): null | Entity

      The current Tool Center Point (TCP) for the robot.

      Returns null | Entity

    • set tcp(value: null | Entity): void

      Parameters

      Returns void

    • get weights(): null | ReadonlyMap<Joint, number>

      The (optional) weights for the joints that are controlled by the robot controller.

      Returns null | ReadonlyMap<Joint, number>

      Weights are used to penalize the motion of certain joints, causing the solver to prefer the motion of other joints. This is particularly useful for robots with redundant degrees of freedom, such as when using workpiece positioners or additional axes. Values are clamped to the range [0, 1]. A weight of 0 means that motion of the joint is not penalized. The weights are effectively normalized by the solver, meaning that the weights [0.5, 0.25] are identical to the weights [1, 0.5]. Setting all the weights to the same value is equivalent to not setting any weights at all. Values provided for joints that are not controlled by the robot controller are ignored.

    • set weights(value: null | ReadonlyMap<Joint, number>): void

      Parameters

      • value: null | ReadonlyMap<Joint, number>

      Returns void

    • get world(): World

      The virtual world to which the owning entity belongs.

      Returns World

    • get worldTCP(): Frame

      The frame of the current TCP in world-space.

      Returns Frame

    Methods

    • Added function called immediately after the component is attached to an entity.

      Returns void

    • Clear any errors, allowing the robot controller to continue execution.

      Returns void

    • Creates a new robot program and assigns it to the robot controller.

      Parameters

      • name: null | string = null

        The (optional) unique name for the robot program.

      Returns null | RobotProgram

      The created program, or null if a program with the specified name already exists.

      If a name is not provided, the program will be assigned a unique name automatically.

    • Finds a robot program with a given name.

      Parameters

      • name: string

        The name of the program.

      Returns null | RobotProgram

      The found robot program.

    • Creates a handle (weak reference) to a trackable object.

      Type Parameters

      Parameters

      • type: TrackableType<T>

        The type of object that is to be referenced.

      • value: null | T = null

        The object that is initially referenced by the handle.

      Returns Handle<T>

      A handle to a trackable object.

      Handles created through this function are automatically cleared when the component is detached/removed.

    • Asynchronous initialization function called immediately before simulating when the model is initialized.

      Returns Promise<void>

    • Calculates the inverse kinematics to find the active joint parameters that achieve the specified target frame.

      Parameters

      • frame: IFrame

        The target frame, in the local-space of the reference frame (or the robot when no reference frame is specified).

      • referenceFrame: null | Entity = null

        The optional entity whose local coordinate system the target frame is relative to.

      Returns number[]

      The active joint parameters that achieve the target.

    • Transforms a frame from the local-space of the robot to world-space.

      Parameters

      • localFrame: IFrame

        The frame in the local-space of the robot.

      Returns Frame

      The frame in world-space.

    • Commands the robot controller to perform a joint move.

      Parameters

      • frame: IFrame

        The target frame, in the local-space of the reference frame or robot when no reference frame is specified.

      • constraints: null | ReadonlyMap<Joint, number> = null

        The optional joint constraints at the target.

      • referenceFrame: null | Entity = null

        The optional entity whose local coordinate system the target frame is relative to.

      Returns Future<void>

      The future, which resolves when the move has completed.

      Specify a reference frame when the target is positioned relative to a moving workpiece.

    • Commands the robot controller to perform a joint move to intercept the specified moving entity.

      Parameters

      • entity: Entity

        The entity to intercept.

      • Optionaloffset: IFrame

        The offset applied to the entity in the local-space of the robot.

      Returns Future<void>

      The future, which resolves when the move has completed.

    • Commands the robot controller to perform a linear move.

      Parameters

      • frame: IFrame

        The target frame, in the local-space of the reference frame (or robot when no reference frame is specified).

      • constraints: null | ReadonlyMap<Joint, number> = null

        The optional joint constraints at the target.

      • referenceFrame: null | Entity = null

        The optional entity whose local coordinate system the target frame is relative to.

      Returns Future<void>

      The future, which resolves when the move has completed.

      Specify a reference frame when the target is positioned relative to a moving workpiece.

    • Commands the robot controller to perform a linear move to intercept the specified moving entity.

      Parameters

      • entity: Entity

        The entity to intercept.

      • Optionaloffset: IFrame

        The offset applied to the entity in the local-space of the robot.

      Returns Future<void>

      The future, which resolves when the move has completed.

    • Commands the robot controller to perform a path move.

      Parameters

      • path: IRobotPath

        The path along which the robot should move.

      • constraints: null | ReadonlyMap<Joint, number> = null

        The optional joint constraints at the end of the path.

      • referenceFrame: null | Entity = null

        The optional entity that the path is attached to.

      Returns Future<void>

      The future, which resolves when the move has completed.

      Specify a reference frame when the path is attached to a workpiece moved by a positioner.

    • Commands the robot controller to perform a servo move.

      Parameters

      • servo: number

        The servo index.

      • position: number

        The target position.

      Returns Future<void>

      The future, which resolves when the move has completed.

    • Commands the robot controller to perform a servos move.

      Parameters

      • positions: number[]

        The target positions.

      Returns Future<void>

      The future, which resolves when the move has completed.

    • Retrieves the current active joint parameters/angles.

      Returns number[]

      The current active joint parameters/angles.

    • Asynchronous post-update function called after physics has been updated.

      Parameters

      • dt: number

        The timestep (seconds).

      Returns Promise<void>

    • Removes a robot program with the specified name.

      Parameters

      • name: string

        The name of the robot program to remove.

      Returns boolean

      True if the robot program was removed, false otherwise.

    • Renames a robot program.

      Parameters

      • oldName: string

        The current name of the robot program to rename.

      • newName: string

        The new name to assign to the robot program.

      Returns boolean

      True if the robot program was renamed, false otherwise.

    • Immediately triggers asynchronous initialization if the component hasn't already been initialized.

      Returns Promise<void>

      This can be used in cases where one component references another in its asynchronous initialize function, but it is required that the referenced component has already been asynchronously initialized.

    • Immediately triggers initialization if the component hasn't already been initialized.

      Returns void

      This can be used in cases where one component references another in its initialize function, but it is required that the referenced component has already been initialized.

    • Subscribes to a subscribable object.

      Subscriptions created through this function are automatically unsubscribed when the component is detached/removed.

      Type Parameters

      • T

      Parameters

      • object: Subscribable<T>

        The subscribable object for which to subscribe.

      • subscriber: Subscriber<T>

        The callback function that is triggered when the object's value is updated.

      Returns void

    • The time it will take to perform a joint move.

      Parameters

      • frame: IFrame

        The target frame, in the local-space of the reference frame or robot when no reference frame is specified.

      • referenceFrame: null | Entity = null

        The optional entity whose local coordinate system the target frame is relative to.

      Returns number

      The time to complete the joint move.

    • The time it will take to perform a linear move.

      Parameters

      • frame: IFrame

        The target frame, in the local-space of the reference frame or robot when no reference frame is specified.

      • referenceFrame: null | Entity = null

        The optional entity whose local coordinate system the target frame is relative to.

      Returns number

      The time to complete the linear move.

    • Unsubscribes from a subscribable object.

      Type Parameters

      • T

      Parameters

      • object: Subscribable<T>

        The object from which to unsubscribe.

      • subscriber: Subscriber<T>

        The callback function for the subscription.

      Returns boolean

      True if the subscription was canceled, false otherwise.

    • Asynchronous update function called every timestep when simulating.

      Parameters

      • dt: number

        The timestep (seconds).

      Returns Promise<void>

    • Transforms a frame from world-space to the local-space of the robot.

      Parameters

      • worldFrame: IFrame

        The frame in world-space.

      Returns Frame

      The frame in the local-space of the robot.