The Robot requires a certain model to calculate motion in 3D space. The following endpoints allow you to access this model to do calculation on your own.

Different concepts are used by these endpoints: joint angles, end effector position and orientation, waypoints and setpoints.

Concepts

Motion Errors

Motion Errors are used to represent errors that happened when calculating Robot's movement.

Code Meaning
success Success
unknown Unknown error
shoulder_singularity Shoulder singularity error
shoulder_singularity_warn Shoulder singularity warning
elbow_singularity Elbow singularity error
elbow__singularity_warn Elbow singularity warning
wrist_singularity Wrist singularity error
wrist_singularity_warn Wrist singularity warning
singularity Other singularity error
ik Inverse Kinematics failure
ik_empty Inverse Kinematics failure (empty poses)
analytical_ik Analytical Inverse Kinematics failure
j0_boundary Joint 1 boundary limit
j1_boundary Joint 2 boundary limit
j2_boundary Joint 3 boundary limit
j3_boundary Joint 4 boundary limit
j4_boundary Joint 5 boundary limit
j5_boundary Joint 6 boundary limit
reach Reach limit
vel_calc Velocity calculation error
vel_calc_empty Velocity calculation error (empty poses)
acc_calc Acceleration calculation error
acc_calc_empty Acceleration calculation error (empty velocities)
linear_calc Linear path calculation error (empty poses)
cubic_calc Cubic path calculation error (incorrect poses)
j0_ang_vel Joint 1 angle velocity limit
j1_ang_vel Joint 2 angle velocity limit
j2_ang_vel Joint 3 angle velocity limit
j3_ang_vel Joint 4 angle velocity limit
j4_ang_vel Joint 5 angle velocity limit
j5_ang_vel Joint 6 angle velocity limit
j0_ang_acc Joint 1 angle acceleration limit
j1_ang_acc Joint 2 angle acceleration limit
j2_ang_acc Joint 3 angle acceleration limit
j3_ang_acc Joint 4 angle acceleration limit
j4_ang_acc Joint 5 angle acceleration limit
j5_ang_acc Joint 6 angle acceleration limit
ee_over_speed End-effector over speed
ee_over_acceleration End-effector over acceleration
ee_over_energy End-effector over energy
j0_over_energy Joint 1 over energy
j1_over_energy Joint 2 over energy
j2_over_energy Joint 3 over energy
j3_over_energy Joint 4 over energy
j4_over_energy Joint 5 over energy
j5_over_energy Joint 6 over energy
plane_collision Plane collision
self_collision Self collision
object_collision Object collision
generation_error Segment generation error
result_generation_error Segment result generation error
time_too_short Requested time is too short and exceeds velocity limits
time_too_short_switched_to_min Requested time is too short and exceeds velocity limits, switched to minimum time.
too_few_waypoints Too few waypoints in the segment
too_many_waypoints Too many waypoints in the segment
could_not_calculate_min_time Could not calculate minimum time

Pose validity

This endpoint allows you to check if a set of joint angles is valid and would not result with the Robot colliding with itself or its workspace.

Request

PUT /api/v1/calc/pose_valid

Payload

{
  "joints": JOINT_ANGLES
}

where JOINT_ANGLES is an array containing the joint angles of the Robot expressed in radians, e.g. [0,0,0,1.7,0.5,-1].

Reply

{
  "pose": {
    "valid": VALID_RESULT,
    "status": VALID_RESULT_STRING
  }
}

or an error.

Where every VALID_RESULT is a boolean representing if the angles were valid or not, and VALID_RESULT_STRING is a human-readable string explaining if the pose is valid.

Forward Kinematics

This endpoint allows you to calculate the end effector position and orientation using the joint angles of the Robot.

Request

PUT /api/v1/calc/forward_kinematics

Payload

{
  "joints": JOINT_ANGLES
}

where JOINT_ANGLES is an array containing the joint angles of the Robot expressed in radians, e.g. [0,0,0,1.7,0.5,-1].

Reply

{
  "fk": {
    "position": {"x": POSITION_X, "y": POSITION_Y, "z": POSITION_Z},
    "orientation": {"w": QUATERNION_W, "x": QUATERNION_X, "y": QUATERNION_Y, "z": QUATERNION_Z},
  }
}

or an error.

Where every *_X, *_Y and *_Z is a float. The position object is a vector in the end effector space (relative to the base of the Robot). Note that the position is a vector expressed in meters. The orientation is a quaternion that represents the end effector orientation from the base.

Inverse Kinematics

This endpoint allows you to calculate the joint angles of the Robot at a given end effector position. For the calculation to be correct, the service also needs the desired end effector orientation (expressed using 3 vectors) and a guess of the resulting joint angles. Note that this operation can fail.

Request

PUT /api/v1/calc/inverse_kinematics

Payload

{
  "guess": JOINT_ANGLES,
  "target_position": EE_POSITION,
  "target_orientation": EE_ORIENTATION,
}

where JOINT_ANGLES is an array containing the joint angles of the Robot expressed in radians, e.g. [0, 0, 0, 1.7, 0.5, -1]; EE_POSITION is an object containing 3 properties: x, y and z, each being a float, thus representing a vector. EE_ORIENTATION is an object that represents the quaternion of the orientation. It contains 4 properties: w, x, y and z, each being a float.

Example replies

  • It works
{
  "nudge": {
    "result": "success",
    "joints": [-2.3, 0, 0, 0.32, 0, 0.78]
  }
}
    • fails*
{
  "ik": {
    "result": MOTION_ERROR
  }
}

or an error.

Where MOTION_ERROR is a motion error code.

Nudge

This endpoint allows you to calculate the joint angles of the Robot after a "nudge" (moving of a given offset in a given direction). This transformation maintains end effector orientation. Note that this operation can fail.

Request

PUT /api/v1/calc/nudge

Payload

{
  "joints": JOINT_ANGLES,
  "direction": NUDGE_DIRECTION,
  "offset": NUDGE_OFFSET
}

where JOINT_ANGLES is an array containing the joint angles of the Robot expressed in radians, e.g. [0, 0, 0, 1.7, 0.5, -1]; NUDGE_DIRECTION is a string which can be either "x", "y" or "z"; NUDGE_OFFSET is a float representing the distance in meters, e.g. 10.5.

Example replies

  • It works
{
  "nudge": {
    "result": "success",
    "joints": [-2.3, 0, 0, 0.32, 0, 0.78]
  }
}
  • It fails
{
  "nudge": {
    "result": MOTION_ERROR
  }
}

or an error.

Where MOTION_ERROR is a motion error code.

Rotate

This endpoint allows you to calculate the joint angles of the Robot after a rotation of the end effector of a given offset in a given direction. This transformation maintains end effector position. Note that this operation can fail.

Request

PUT /api/v1/calc/rotate

Payload

{
  "joints": JOINT_ANGLES,
  "axis": ROTATE_AXIS,
  "offset": ROTATE_OFFSET
}

where JOINT_ANGLES is an array containing the joint angles of the Robot expressed in radians, e.g. [0, 0, 0, 1.7, 0.5, -1]; ROTATE_AXIS is a string which can be either "x", "y" or "z"; ROTATE_OFFSET is a float representing the angle in radians, e.g. 0.5.

Example replies

  • It works
{
  "rotate": {
    "result": "success",
    "joints": [-2.3, 0, 0, 0.32, 0, 0.78]
  }
}
  • It fails
{
  "rotate": {
    "result": MOTION_ERROR
  }
}

or an error.

Where MOTION_ERROR is a motion error code.