Kinematics

Move robot arms by where the end of the arm (the end effector) should go, rather than joint by joint. Each arm is a kinematic chain, named in the project; positions are in millimetres from the arm's base (+X forward), and orientation is roll, pitch and yaw in degrees. ARCx works out the joint angles and moves the servos.

Where to find it: type Kinematics. in a JavaScript script, or open the ARCx API view of the script editor and expand Kinematics

Commands

Command	What it does
Kinematics.exists	Checks whether a kinematic chain with this name is published.
Kinematics.getChains	Lists the names of every kinematic chain (arm, gimbal and so on) published in the project, sorted alphabetically.
Kinematics.getDescription	Gets the description the provider gave a chain.
Kinematics.getJointAngles	Joint angles in degrees, one per joint in chain order
Kinematics.getJointCount	Gets how many joints a chain has.
Kinematics.getLastMessage	The provider's message from the last move this script requested.
Kinematics.getPitch	Reads the tool's current pitch (rotation about the Y axis) in degrees.
Kinematics.getPose	An object with X, Y, Z, Roll, Pitch, Yaw and HasOrientation
Kinematics.getPosition	[x, y, z]
Kinematics.getProvider	Gets the name of the robot skill that owns and moves a chain.
Kinematics.getRoll	Reads the tool's current roll (rotation about the X axis) in degrees.
Kinematics.getX	Reads where the end of the arm is now along X (forward), in millimeters.
Kinematics.getY	Reads where the end of the arm is now along Y (left), in millimeters.
Kinematics.getYaw	Reads the tool's current yaw (rotation about the Z axis) in degrees.
Kinematics.getZ	Reads where the end of the arm is now along Z (up), in millimeters.
Kinematics.isMoving	Checks whether a chain is in the middle of a move.
Kinematics.moveLinear	Moves the end of the arm to a position along a straight line at the chain's configured speed, without waiting for it to arrive.
Kinematics.moveLinearAndWait	Moves the end of the arm to a position along a straight line at the chain's configured speed and waits until it stops moving.
Kinematics.moveRelative	Moves the end of the arm by an offset from where it is now, at the chain's configured speed, without waiting for it to arrive.
Kinematics.moveRelativeAndWait	Moves the end of the arm by an offset from where it is now, at the chain's configured speed, and waits until it stops moving.
Kinematics.moveTo	Moves the end of the arm to a position at the chain's configured speed, without waiting for it to arrive.
Kinematics.moveToAndWait	Moves the end of the arm to a position at the chain's configured speed and waits until it stops moving.
Kinematics.moveToPose	Moves the end of the arm to a position and tool angle at the chain's configured speed, without waiting for it to arrive.
Kinematics.stop	Stops a move in progress on a chain.
Kinematics.stopAll	Stops every move in progress on every kinematic chain.
Kinematics.supportsOrientation	Checks whether a chain can control the tool angle (roll, pitch and yaw) as well as its position.
Kinematics.waitForMoveComplete	Waits until a chain finishes moving, with no time limit.
Kinematics.wasLastMoveReachable	False when the last move this script requested settled short of the target

Details

Kinematics.exists

Checks whether a kinematic chain with this name is published. Use it before moving when the chain may be missing, since moving an unknown chain is an error.

Kinematics.exists(chainName)

Value	Type	What it is
`chainName`	string	The chain name as its provider published it, such as Left Arm.

Gives back: boolean. Whether the chain exists.

Kinematics.getChains

Lists the names of every kinematic chain (arm, gimbal and so on) published in the project, sorted alphabetically.

Kinematics.getChains()

Gives back: string[]. The chain names, or an empty list when there are none.

Kinematics.getDescription

Gets the description the provider gave a chain. Empty when there is no such chain.

Kinematics.getDescription(chainName)

Value	Type	What it is
`chainName`	string	The chain name as its provider published it, such as Left Arm.

Gives back: string. The description, or empty text.

Kinematics.getJointAngles

Joint angles in degrees, one per joint in chain order

Kinematics.getJointAngles(chainName)

Value	Type	What it is
`chainName`	string	The chain name as its provider published it, such as Left Arm. An unknown name is an error.

Gives back: number[]. The joint angles in degrees, or an empty list when the provider does not report them.

Kinematics.getJointCount

Gets how many joints a chain has. 0 when there is no such chain.

Kinematics.getJointCount(chainName)

Value	Type	What it is
`chainName`	string	The chain name as its provider published it, such as Left Arm.

Gives back: number. The number of joints.

Kinematics.getLastMessage

The provider's message from the last move this script requested. Empty on success, otherwise the reason (for example that the target is out of reach).

Kinematics.getLastMessage()

Gives back: string. The message, or empty text when the last move succeeded.

Kinematics.getPitch

Reads the tool's current pitch (rotation about the Y axis) in degrees. Only meaningful on chains that support orientation.

Kinematics.getPitch(chainName)

Value	Type	What it is
`chainName`	string	The chain name as its provider published it, such as Left Arm. An unknown name is an error.

Gives back: number. The pitch in degrees.

Kinematics.getPose

An object with X, Y, Z, Roll, Pitch, Yaw and HasOrientation

Kinematics.getPose(chainName)

Value	Type	What it is
`chainName`	string	The chain name as its provider published it, such as Left Arm. An unknown name is an error.

Gives back: any. The current pose: X, Y and Z in millimeters, Roll, Pitch and Yaw in degrees.

Kinematics.getPosition

[x, y, z]

Kinematics.getPosition(chainName)

Value	Type	What it is
`chainName`	string	The chain name as its provider published it, such as Left Arm. An unknown name is an error.

Gives back: number[]. The current position of the end of the arm as [x, y, z] in millimeters.

Kinematics.getProvider

Gets the name of the robot skill that owns and moves a chain. Empty when there is no such chain.

Kinematics.getProvider(chainName)

Value	Type	What it is
`chainName`	string	The chain name as its provider published it, such as Left Arm.

Gives back: string. The provider name, or empty text.

Kinematics.getRoll

Reads the tool's current roll (rotation about the X axis) in degrees. Only meaningful on chains that support orientation.

Kinematics.getRoll(chainName)

Value	Type	What it is
`chainName`	string	The chain name as its provider published it, such as Left Arm. An unknown name is an error.

Gives back: number. The roll in degrees.

Kinematics.getX

Reads where the end of the arm is now along X (forward), in millimeters. It asks the provider, so it includes moves made by other robot skills.

Kinematics.getX(chainName)

Value	Type	What it is
`chainName`	string	The chain name as its provider published it, such as Left Arm. An unknown name is an error.

Gives back: number. The X position in millimeters.

Kinematics.getY

Reads where the end of the arm is now along Y (left), in millimeters. It asks the provider, so it includes moves made by other robot skills.

Kinematics.getY(chainName)

Value	Type	What it is
`chainName`	string	The chain name as its provider published it, such as Left Arm. An unknown name is an error.

Gives back: number. The Y position in millimeters.

Kinematics.getYaw

Reads the tool's current yaw (rotation about the Z axis) in degrees. Only meaningful on chains that support orientation.

Kinematics.getYaw(chainName)

Value	Type	What it is
`chainName`	string	The chain name as its provider published it, such as Left Arm. An unknown name is an error.

Gives back: number. The yaw in degrees.

Kinematics.getZ

Reads where the end of the arm is now along Z (up), in millimeters. It asks the provider, so it includes moves made by other robot skills.

Kinematics.getZ(chainName)

Value	Type	What it is
`chainName`	string	The chain name as its provider published it, such as Left Arm. An unknown name is an error.

Gives back: number. The Z position in millimeters.

Kinematics.isMoving

Checks whether a chain is in the middle of a move.

Kinematics.isMoving(chainName)

Value	Type	What it is
`chainName`	string	The chain name as its provider published it, such as Left Arm. An unknown name is an error.

Gives back: boolean. Whether the chain is moving.

Kinematics.moveLinear

Moves the end of the arm to a position along a straight line at the chain's configured speed, without waiting for it to arrive. Chains that cannot do straight-line moves may do a normal move instead.

Kinematics.moveLinear(chainName, x, y, z)
Kinematics.moveLinear(chainName, x, y, z, speed)

Value	Type	What it is
`chainName`	string	The chain name as its provider published it, such as Left Arm. An unknown name is an error.
`x`	number	Target X in millimeters (forward from the chain's base).
`y`	number	Target Y in millimeters (left of the chain's base).
`z`	number	Target Z in millimeters (up from the chain's base).
`speed`	number	Optional. 1 (slowest) to 255 (fastest), or -1 for the chain's configured speed.

Gives back: boolean. Whether the provider accepted the move; when not, the last move's message says why.

Kinematics.moveLinearAndWait

Moves the end of the arm to a position along a straight line at the chain's configured speed and waits until it stops moving. Chains that cannot do straight-line moves may do a normal move instead.

Kinematics.moveLinearAndWait(chainName, x, y, z)
Kinematics.moveLinearAndWait(chainName, x, y, z, speed)
Kinematics.moveLinearAndWait(chainName, x, y, z, speed, timeoutMs)

Value	Type	What it is
`chainName`	string	The chain name as its provider published it, such as Left Arm. An unknown name is an error.
`x`	number	Target X in millimeters (forward from the chain's base).
`y`	number	Target Y in millimeters (left of the chain's base).
`z`	number	Target Z in millimeters (up from the chain's base).
`speed`	number	Optional. 1 (slowest) to 255 (fastest), or -1 for the chain's configured speed.
`timeoutMs`	number	Optional. The longest to wait for the move to finish, in milliseconds. 0 or less waits with no limit.

Gives back: boolean. Whether the move was accepted and finished; when refused, the last move's message says why.

Kinematics.moveRelative

Moves the end of the arm by an offset from where it is now, at the chain's configured speed, without waiting for it to arrive.

Kinematics.moveRelative(chainName, dx, dy, dz)
Kinematics.moveRelative(chainName, dx, dy, dz, speed)

Value	Type	What it is
`chainName`	string	The chain name as its provider published it, such as Left Arm. An unknown name is an error.
`dx`	number	How far to move along X in millimeters (forward is positive).
`dy`	number	How far to move along Y in millimeters (left is positive).
`dz`	number	How far to move along Z in millimeters (up is positive).
`speed`	number	Optional. 1 (slowest) to 255 (fastest), or -1 for the chain's configured speed.

Gives back: boolean. Whether the provider accepted the move; when not, the last move's message says why.

Kinematics.moveRelativeAndWait

Moves the end of the arm by an offset from where it is now, at the chain's configured speed, and waits until it stops moving.

Kinematics.moveRelativeAndWait(chainName, dx, dy, dz)
Kinematics.moveRelativeAndWait(chainName, dx, dy, dz, speed)
Kinematics.moveRelativeAndWait(chainName, dx, dy, dz, speed, timeoutMs)

Value	Type	What it is
`chainName`	string	The chain name as its provider published it, such as Left Arm. An unknown name is an error.
`dx`	number	How far to move along X in millimeters (forward is positive).
`dy`	number	How far to move along Y in millimeters (left is positive).
`dz`	number	How far to move along Z in millimeters (up is positive).
`speed`	number	Optional. 1 (slowest) to 255 (fastest), or -1 for the chain's configured speed.
`timeoutMs`	number	Optional. The longest to wait for the move to finish, in milliseconds. 0 or less waits with no limit.

Gives back: boolean. Whether the move was accepted and finished; when refused, the last move's message says why.

Kinematics.moveTo

Moves the end of the arm to a position at the chain's configured speed, without waiting for it to arrive. Each joint goes straight to its angle, so the path is an arc rather than a line.

Kinematics.moveTo(chainName, x, y, z)
Kinematics.moveTo(chainName, x, y, z, speed)

Value	Type	What it is
`chainName`	string	The chain name as its provider published it, such as Left Arm. An unknown name is an error.
`x`	number	Target X in millimeters (forward from the chain's base).
`y`	number	Target Y in millimeters (left of the chain's base).
`z`	number	Target Z in millimeters (up from the chain's base).
`speed`	number	Optional. 1 (slowest) to 255 (fastest), or -1 for the chain's configured speed.

Gives back: boolean. Whether the provider accepted the move; when not, the last move's message says why.

Kinematics.moveToAndWait

Moves the end of the arm to a position at the chain's configured speed and waits until it stops moving. Each joint goes straight to its angle, so the path is an arc rather than a line.

Kinematics.moveToAndWait(chainName, x, y, z)
Kinematics.moveToAndWait(chainName, x, y, z, speed)
Kinematics.moveToAndWait(chainName, x, y, z, speed, timeoutMs)

Value	Type	What it is
`chainName`	string	The chain name as its provider published it, such as Left Arm. An unknown name is an error.
`x`	number	Target X in millimeters (forward from the chain's base).
`y`	number	Target Y in millimeters (left of the chain's base).
`z`	number	Target Z in millimeters (up from the chain's base).
`speed`	number	Optional. 1 (slowest) to 255 (fastest), or -1 for the chain's configured speed.
`timeoutMs`	number	Optional. The longest to wait for the move to finish, in milliseconds. 0 or less waits with no limit.

Gives back: boolean. Whether the move was accepted and finished; when refused, the last move's message says why.

Kinematics.moveToPose

Moves the end of the arm to a position and tool angle at the chain's configured speed, without waiting for it to arrive. Chains that cannot control orientation use only the position.

Kinematics.moveToPose(chainName, x, y, z, roll, pitch, yaw)
Kinematics.moveToPose(chainName, x, y, z, roll, pitch, yaw, speed)

Value	Type	What it is
`chainName`	string	The chain name as its provider published it, such as Left Arm. An unknown name is an error.
`x`	number	Target X in millimeters (forward from the chain's base).
`y`	number	Target Y in millimeters (left of the chain's base).
`z`	number	Target Z in millimeters (up from the chain's base).
`roll`	number	Target rotation about the X axis, in degrees.
`pitch`	number	Target rotation about the Y axis, in degrees.
`yaw`	number	Target rotation about the Z axis, in degrees.
`speed`	number	Optional. 1 (slowest) to 255 (fastest), or -1 for the chain's configured speed.

Gives back: boolean. Whether the provider accepted the move; when not, the last move's message says why.

Kinematics.stop

Stops a move in progress on a chain. Does nothing on a chain whose provider cannot stop mid-move.

Kinematics.stop(chainName)

Value	Type	What it is
`chainName`	string	The chain name as its provider published it, such as Left Arm. An unknown name is an error.

Kinematics.stopAll

Stops every move in progress on every kinematic chain. A chain that fails to stop does not keep the others from stopping.

Kinematics.stopAll()

Kinematics.supportsOrientation

Checks whether a chain can control the tool angle (roll, pitch and yaw) as well as its position. Most hobby arms with 3 to 5 joints cannot.

Kinematics.supportsOrientation(chainName)

Value	Type	What it is
`chainName`	string	The chain name as its provider published it, such as Left Arm.

Gives back: boolean. Whether orientation is supported; not when there is no such chain.

Kinematics.waitForMoveComplete

Waits until a chain finishes moving, with no time limit. Returns straight away when it is not moving.

Kinematics.waitForMoveComplete(chainName)
Kinematics.waitForMoveComplete(chainName, timeoutMs)

Value	Type	What it is
`chainName`	string	The chain name as its provider published it, such as Left Arm. An unknown name is an error.
`timeoutMs`	number	Optional. The longest to wait in milliseconds. 0 or less waits with no limit.

Gives back: boolean. Whether the chain has stopped moving.

Kinematics.wasLastMoveReachable

False when the last move this script requested settled short of the target

Kinematics.wasLastMoveReachable()

Gives back: boolean. Whether the last move this script requested reached its target; a refused move did not.